PLAN: audit — from /audit:issues to the bulk-audit family

[mmcky]

Development plan for the audit plugin: maintainer-facing, read-only, portfolio-wide audits that produce an evidence-cited report. Landed in #11, which ships the first skill so the shared method is proven against a real procedure before more are written on top of it.

Where we are

In place	Pending
/audit:issues — whole-tracker review, status verified against the code rather than the thread	The other three skills below
references/doctrine.md — trust rules, evidence classes, the read-only boundary, checkpointing, the coverage self-audit	Second execution against a different repo type, to test what actually generalises
references/quantecon-context.md — repo types, label ownership, the cross-repo graph, notes-system discovery	—
references/deliverables.md — what an audit owes its reader, plus the /audit:issues bundle as a worked example	—
scripts/fetch_tracker.py — deterministic snapshot with a coverage reconciliation	Unit tests for reconcile and require_thread_objects

Candidate skills

None of these is committed; each needs the same evidence a skill in this repo normally carries before it is written.

Skill	Audits	Notes
/audit:prs	Every open PR: does it solve a real issue, is it mergeable, what should the review say	Closest sibling to /audit:issues; would reuse the snapshot directly
/audit:tech-debt	A codebase's accumulated debt, with a filing-ready catalog	Run once by hand against quantecon-py
/audit:translations	Parity between a source series and its translation	Run by hand for the lecture-python.myst ↔ zh-cn work

Work items

• Add unit tests for fetch_tracker.py's reconcile and require_thread_objects, using the fixtures convention established in Land the lecture evaluation system (benchmark plugin 0.3.0: rubric v2, skill wired) #5 rather than inventing a second one
• Convert the marketplace entry to the co-located ./audit form once Land the lecture evaluation system (benchmark plugin 0.3.0: rubric v2, skill wired) #5 lands — its validator rejects a remote source pointing back at this repo (done during the Land the lecture evaluation system (benchmark plugin 0.3.0: rubric v2, skill wired) #5 rebase)
• Run /audit:issues against a second repo of a different type, and record which parts of the doctrine actually transferred
• Only then decide whether the shared method deserves more structure, or less

Open questions

The plugin deliberately under-specifies its own scaffolding right now — the report shape, the phase division, and the skill-naming form are all documented as what the first skill happened to do, not as contracts. That is a decision to revisit once a second audit exists to generalise from, not an omission.

[mmcky]

Two of the work items here now have a home. A full read of the plugin (2026-07-27) found that the problem is not over-complication but abstraction ahead of evidence — executed once by hand as a runbook, never as a skill — so the validation program is now specified in #16, with a claims-under-test table, a four-repo run matrix, and exit criteria.

Three defects were real enough to fix without a run and have landed as audit 0.1.1: named phase checkpoints with per-item appends (resumability was promised in three files but phases 2 and 3 named no artifact), a bundle that scales to the tracker, and meta.fetched_by replacing an authenticated flag that could only ever be true.

The two items that move to #16: the second-repo run (now four runs, sequenced, with the action-translation hand-run as the regression anchor) and the more-structure-or-less decision, which #16 defers to after the QuantEcon/meta run — the case furthest from the original execution, and so the sharpest test of what actually generalises. The reconcile / require_thread_objects unit tests are carried into #16's exit criteria too, since coverage.json is load-bearing evidence.