Generate a convergence issue from a repo's audit (audit.py --issue)

[ptr727]

Scripts the convergence-issue content so it's derived from the audit, never composed on the fly — the idempotent-artifact model applied to issues. Filing a hand-written issue is exactly the "content drifts from reality" problem the fidelity model exists to kill.

What

• spec/audit.py --issue <repo> — runs the per-repo audit and emits a ready-to-file issue (title on the first line, then the body) on stdout, so it can be captured and filed. render_issue groups the findings by what the maintainer does with them:
  • Must fix — DEFECT / LETTER (a missing carried file, a broken workflow contract).
  • Converge — DRIFT (re-vendor a verbatim: file or section, honor an interface: contract, or judge a stale/intent copy per AUDIT.md).
  • Could not verify — ERROR.
• The body quotes the audit run stamp and the "regenerate with" command, per AUDIT.md section 8 (which this PR extends to document the generator).
• --selftest covers grouping, the finding count in the title, and the clean case.

Verified live

--issue Financial-Modeling → its four real divergences (the three verbatim AGENTS.md sections + the stale configure.sh), no invented prose.

Next

Use it to file finmod's convergence issue — the first catalog-driven issue.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an --issue output mode to the fleet audit runner so it can deterministically generate a ready-to-file convergence issue (title + body) from the live audit findings, reducing drift between reported findings and tracking issues.

Changes:

• Extend spec/audit.py with --issue <repo> to emit a convergence issue derived from audit_repo() findings.
• Add render_issue() to group findings into “Must fix”, “Converge”, and “Could not verify”, and extend --selftest to cover this rendering.
• Update AUDIT.md to document the new issue generator and reiterate the “point-in-time snapshot” requirement.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
spec/audit.py	Implements issue generation (--issue) and adds selftest coverage for grouping/title/empty-case output.
AUDIT.md	Documents generating convergence issues from audit output to avoid hand-written drift.

Comments suppressed due to low confidence (2)

spec/audit.py:817

• In --issue mode the script claims to emit "title on the first line, then the body", but the current output adds a TITLE: prefix and an extra blank line. That makes the stdout harder to capture and file as-is (and doesn't match the documented contract).

        print(f"TITLE: {title}")
        print()
        print(body, end="")
        return 0

spec/audit.py:740

• The generated issue intro sentence ends with "The full letter and intent verdict is AUDIT.md's.", which reads ungrammatical and is likely to confuse readers of the issue. Rephrase to a clear directive to consult AUDIT.md for the full verdicts.

    w(f"Generated from the hub audit of `{name}` ({types}) at `{stamp}`, hub `{hub_sha}`, {run_utc}. "
      f"Regenerate with `spec/audit.py --issue {name}`. Findings are a point-in-time snapshot - re-run the "
      f"audit before acting (AUDIT.md section 8). This lists what the audit mechanically detects. The full "
      f"letter and intent verdict is AUDIT.md's.")

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

spec/audit.py:816

• --issue mode is documented as emitting a ready-to-file issue with the title on the first line, but the code prefixes the title with TITLE: . That makes the output not directly pasteable/consumable as a GitHub issue title and contradicts the nearby comment/docstrings describing the format.

        title, body = render_issue(entry, findings, entry.get("groundTruthBranch", "main"),
                                   audited_sha, run_utc, hub_sha)
        print(f"TITLE: {title}")
        print()
        print(body, end="")

spec/audit.py:802

• This new --issue header comment is 3 lines and mostly restates what the code does. AGENTS.md asks to keep comments terse (one line by default) and focus on the non-obvious why (AGENTS.md:145-149). Consider condensing this to a single line.

    # --issue <repo>: emit a ready-to-file convergence issue for one repo (title on the first line, then the
    # body) - stdout carries only the issue so it can be captured and filed. The body is generated from the
    # audit, so it never drifts from reality.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

spec/audit.py:816

• --issue mode prints TITLE: ... plus a blank line before the body. The PR description/AUDIT.md describe a ready-to-file issue with the title on the first line, then the body; the TITLE: prefix makes the output not directly copy/pasteable as an issue title.

        print(f"TITLE: {title}")
        print()
        print(body, end="")

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

spec/audit.py:812

• --issue is documented (and commented) as emitting the title on the first line and the body from the second, so consumers can take line 1 as the issue title. Prefixing the first line with TITLE: makes the output not "ready-to-file" and can break simple capture tooling.

        print(f"TITLE: {title}")

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

spec/audit.py:813

• --issue output is documented as "title on the first line, then the body" for clean capture/filing, but it currently prefixes the first line with TITLE: . That makes simple "first line is the issue title" tooling harder and doesn't match the PR description/AUDIT.md wording.

        print(f"TITLE: {title}")
        print(body, end="")  # body begins on the next line - title first line, body from the second

spec/audit.py:730

• When audited_sha is empty (e.g. early gh failure), stamp becomes just the branch name, so the issue intro claims it read @ main instead of quoting the documented @ <branch>@<sha> stamp format. Consider emitting an explicit @ <branch>@unknown so derived artifacts still follow the contract while staying honest about missing data.

    name = entry["name"]
    types = ", ".join(entry.get("types", [])) or "untyped"
    stamp = f"{ground}@{audited_sha[:7]}" if audited_sha else ground
    blocking = [(k, t) for k, t in findings if k in ("DEFECT", "LETTER")]
    drift = [t for k, t in findings if k == "DRIFT"]

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

spec/audit.py:813

• --issue output contract is documented as "title on the first line, then the body" for easy capture/filing, but the code prefixes the first line with TITLE:. That breaks simple consumers that treat line 1 as the issue title verbatim (and it also diverges from the PR description/AUDIT.md text). Print the raw title as line 1 instead.

        title, body = render_issue(entry, findings, entry.get("groundTruthBranch", "main"),
                                   audited_sha, run_utc, hub_sha)
        print(f"TITLE: {title}")
        print(body, end="")  # body begins on the next line - title first line, body from the second