audit: resolve the read-only/working-directory contradiction, and a tutorial for running one

[mmcky]

Everything needed to run the first real validation of /audit:issues (#16), plus the doctrine decision that preparing it forced. audit 0.1.2.

Finding 0 — the read-only boundary and the working directory disagreed

Three statements, each defensible alone, that together instructed the audit to write into the repo it promised not to touch:

• doctrine §3 — "no branch or file changes in the audited repo".
• deliverables.md — the bundle's first-choice destination is "the audited repo's own notes system — .dev/audits/<date>-<subject>/".
• SKILL.md 0.1.1 — --out defaults to .audit/<repo>-<date>/, and the natural working directory is a checkout of the audited repo, since phase 2 verifies against its default branch.

This predates #17; deliverables.md and doctrine §3 have disagreed since #11. The 0.1.1 default only made it concrete.

Resolved as narrowing §3 to content and history — no commits, no pushes, no branches, no edits to tracked files, no tracker mutation — with an explicit statement that a run may write its own working directory. An audit that produces a report necessarily produces files; the property worth protecting is that the report still describes the repo it was run against, and that is about mutation rather than about writing. deliverables.md gains the matching half: writing the bundle is the audit's job, committing or publishing it is not.

Where the working directory goes, decided from a real repo

QuantEcon/action-translation already gitignores .dev/scratch/* (committed via .gitkeep, contents ignored). An audit run there leaves git status completely clean — and needs no .gitignore edit, which would itself be a change to a tracked file. That is better than the flat .audit/ default 0.1.1 shipped, and it is only visible from contact with an actual repo. The rule is now discovery-ordered: an already-ignored scratch location, else an untracked .audit/ at the root, else outside the checkout entirely, with the choice named in the report's method section.

The tutorial

docs/tutorial-run-an-audit.md walks the procedure end to end against action-translation — 228 items, the repo the runbook was first executed against by hand — with the phase 1 output measured 2026-07-27 (116 issues, 112 PRs, 1..228 fully accounted, 11.3 s).

Two things make it different from tutorial-run-an-evaluation.md, and both are deliberate:

There is no reference to reproduce. The evaluation tutorial checks every number against a committed run. /audit:issues has never been executed as a skill, only by hand as a runbook, so there is nothing to check against — the run is the experiment, and the reader's judgement is the result rather than a formality.

Step 4 asks the reader to break it on purpose. Once 20–30 findings exist, interrupt the session and restart. Resumability is asserted in three separate files and has never been tested; before #17 phases 2 and 3 named no artifacts at all, so a resumed session could only work by inventing the same filename twice. This is the check.

Step 6 is a ten-point review checklist — method completeness, evidence tags, [verified] actually meaning verified, code beating the thread, the closed side read, coverage honesty, sibling checks, the closing-keyword hazard in drafted comments — ending with the two only a maintainer can answer: is the tiering right, and would you act on this. Step 7 is the run-document skeleton, following the ge_arrow validation-run convention.

Also

docs/using-skills.md has had no audit row since the plugin shipped in #11, and its install block listed only qe and benchmark. Both fixed. Doc map and site TOC updated.

Merge note

Independent of #18 (a one-line CATALOG change); no overlapping files.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the audit plugin’s doctrine and documentation to resolve the “read-only boundary vs. working-directory output” contradiction, and adds an end-to-end tutorial for running /audit:issues. It also updates the docs site TOC and bumps the audit plugin version to 0.1.2.

Changes:

• Clarifies the read-only boundary to prohibit repo/tracker mutation while explicitly allowing writing to an untracked working directory (preferably already ignored by the audited repo).
• Adds a new tutorial (docs/tutorial-run-an-audit.md) and wires it into the MyST site and repo doc map.
• Updates install/docs references for the audit plugin and bumps the plugin/marketplace version to 0.1.2.

Reviewed changes

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

Show a summary per file

File	Description
NEXT-SESSION.md	Adds a “working notes” scratch document (conflicts with repo guidance that it must not be committed).
myst.yml	Adds the new audit tutorial to the MyST docs navigation.
docs/using-skills.md	Adds audit to install instructions and the plugin summary table.
docs/tutorial-run-an-audit.md	New end-to-end runbook for executing and reviewing /audit:issues.
audit/skills/issues/SKILL.md	Updates working-directory guidance with discovery-ordered output location rules.
audit/references/doctrine.md	Revises §3 to define read-only as “no mutation of tracked content/history or tracker,” while allowing untracked working directory writes.
audit/references/deliverables.md	Clarifies that the audit writes the bundle, but committing/publishing it is a post-run human step.
audit/.claude-plugin/plugin.json	Bumps audit plugin version to 0.1.2.
AGENTS.md	Adds the new audit tutorial to the repository doc map.
.claude-plugin/marketplace.json	Bumps marketplace audit version to 0.1.2.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.