parcel-audit

Parcel Audit

The canonical post-build review of a single parcel. Produces a verdict, a findings table with file:line evidence, and a versioned audit file. Does not merge. Does not edit parcel source. Writes exactly one file: the audit.

Bundled with rookery. Pairs with rookery status, rookery land history, and rookery worktree list for fleet-level visibility around the audit.

When to use

A parcel has written its PARCEL_DONE.md and needs independent review before merge
A prior audit exists (v1, v2, …) and the parcel has added commits since — produce a new version
You need authoritative evidence for a gate decision in wave-triage

When NOT to use

The parcel has no PARCEL_DONE.md yet — run parcel-roster to confirm, then ask the parcel session to complete
You only need a presence snapshot — use parcel-roster
You want a multi-parcel merge-order decision — use wave-triage

Path resolution (read this once per session)

This skill operates on parcel worktrees that live under a configurable root. Resolve <worktrees_root> once, in this order:

rookery.yaml in CWD: read the worktrees_root key (top-level). Use this if present and non-empty.
ROOKERY_WORKTREES env var: fall back to this if step 1 yielded nothing.
Default: ./worktrees (relative to CWD).

Resolve the project repo root with git rev-parse --show-toplevel (run from CWD) — this is the path used by uv -C <repo> and for reading the spec.

Audits live at <worktrees_root>/audits/ (a sibling directory under the worktrees root, not inside any worktree).

Workflow

Step 1 — Locate the spec and the worktree

Resolve <worktrees_root> and <repo> per the path-resolution block above.

Given a parcel id, Glob from <repo> for the spec in both known locations:

parcels/<id>.md
parcels/waves/*/<id>.md
parcels/waves/*/<id>-*.md

If more than one matches, prefer the most recently modified (parcel prompts sometimes get revised mid-wave). If none match, record SPEC: absent in the audit and continue — some parcels are ad-hoc and have no spec file.

Locate the worktree at <worktrees_root>/<id>/ or <worktrees_root>/<id>-*/ via Glob. If the worktree is missing, stop and emit STATUS: worktree absent.

Step 2 — Read the PARCEL_DONE (via parcel-reader)

Invoke the parcel-reader skill on the worktree's PARCEL_DONE.md. Use its structured output as the parcel's own claim. Do not re-parse.

If parcel-reader returns STATUS: absent, stop and emit STATUS: PARCEL_DONE absent in the audit. Audit cannot proceed without a completion claim.

Step 3 — Git triad

From the worktree:

git -C <wt> log --oneline main..HEAD
git -C <wt> diff --stat main
git -C <wt> status --short
git -C <wt> merge-base main HEAD

Record: commit count ahead of main, files touched, line deltas, dirty files, merge-base hash. A dirty worktree is a warning (not a fail) — the parcel may have legitimately uncommitted drafts.

Step 4 — Scope check

Cross-reference the git diff --stat main output against the parcel's declared owned directories (from the spec's ownership table, or from the PARCEL_DONE's "affected-trees" section). Any file outside the owned dirs is a scope violation — record each with file:line evidence from the diff.

Step 5 — Read changed source

For each file in git diff --stat main, Read the file in full from the worktree. Note:

Public API shape (exported functions, classes, CLI commands)
Contracts with other parcels (imports across module boundaries)
Stubs or TODO(P<N>) markers that signal deferred work
Tests: presence, coverage shape, any @pytest.mark.skip with a reason

Do not read files outside the diff — they are not the parcel's output.

Step 6 — Dev loop

Run in the worktree (use the worktree's own module layout to scope):

uv -C <wt> sync --extra dev
uv -C <wt> run --extra dev python -m pytest tests/unit/<module> -v
uv -C <wt> run --extra dev python -m mypy src/<package>/<module> --strict
uv -C <wt> run --extra dev python -m ruff check src/<package>/<module>

Capture exit codes and the last ~30 lines of each. A test suite that errors at collection time is a FAIL. Warnings from ruff or mypy without errors are PASS_WITH_WARNINGS. All-green is PASS (modulo earlier steps).

Step 7 — Verdict + findings table

Combine the signals:

Signal	PASS	PASS_WITH_WARNINGS	FAIL
Scope violations	0	0	≥1
Dirty worktree	0	≤5	>5 or uncommitted tests
Tests (pytest)	green	warnings only	any failure or collection error
Types (mypy --strict)	clean	warnings only	any error
Lint (ruff)	clean	warnings only	any error
PARCEL_DONE claims match reality	yes	minor drift	material false claims

Overall verdict is the worst signal. Build a findings table with one row per issue, citing file:line where applicable.

Step 8 — Write the audit

Determine the version: Glob <worktrees_root>/audits/<id>.v*.md, pick max + 1 (or v1 if none).

Write to <worktrees_root>/audits/<id>.v<N>.md using the canonical Phase A–E layout. The <id>.v<N>.md versioning convention is a public contract — keep it. Reviewers cross-read across the fleet and a divergent shape costs them.

# Audit: <id> (iter <N>)

**Verdict:** <PASS | PASS_WITH_WARNINGS | FAIL>

**Summary:** <2–4 sentence prose summary — what changed since any prior audit, current gate status, verdict rationale>

## Phase A — Scope

- Files changed: **N** (`+L / -L`)
- Out-of-scope writes: **none** (or: list each with evidence)
- Deviations from declared owned dirs (per the spec's ownership table or AGENTS.md): <list with file:line>

## Phase B — Contracts

<interfaces / schemas / public API / imports honoured vs drifted; cite commit hashes or file:line>

## Phase C — Tests / Types / Lint

- `pytest tests/unit/<module>` — <summary + count>
- `pytest tests/integration/<module>` — <summary + count>
- `mypy src/<package>/<module> --strict` — <summary>
- `ruff check src/<package>/<module>` — <summary>

## Phase D — Quality

<non-gate observations: documentation coverage, error messages, logging, test isolation, stub markers, technical debt the parcel chose to ship>

## Phase E — Integration Risks (for the next integrator)

<flag anything that will bite at merge: shared files with other parcels, implicit deps on unfinished work, migrations that conflict>

## Recommendations

<ranked list of concrete follow-ups: merge / merge-with-followup / block-on-fix / reject, plus specific patch-sized fixes>

## Raw artefacts

<tool output excerpts: last 20-30 lines of pytest / mypy / ruff, verbatim>

Commit the audit (on main, via the project repo) with a message like audit(parcel/<id>): v<N> <verdict>. The audit lives at <worktrees_root>/audits/<id>.v<N>.md — the parcel's own branch does not track audits.

Hard rules

Rule	Why
Never edit parcel source	Audit is read-only on the subject; one write allowed — the audit file
Never merge, cherry-pick, or push	Merge is a separate (git-ops) concern; audit precedes it
Audit file goes to `<worktrees_root>/audits/`, NOT inside the worktree	Project convention; keeps worktree diffs clean
Use `git -C <wt>` and `uv -C <wt>`, never `cd`	Maintains permission grants; project bash convention
Cite evidence with `file:line`	Reviewers must be able to verify findings
Never fabricate test numbers	If pytest fails at collection, say so; do not invent pass-counts

Anti-patterns

Anti-pattern	Why it hurts
Using `ls` / `find` / `cat` via Bash for file ops	Grep/Glob/Read are the dedicated tools
Paraphrasing PARCEL_DONE instead of quoting verbatim	Reviewer needs the author's exact words to catch drift
Marking PASS when `mypy --strict` has errors but pytest is green	Strict mypy is a mandatory gate; warnings-only is the generous read
Running the dev loop without `--extra dev`	Dev deps are scoped to the extra; bare `uv sync` is a false-negative setup
Writing to the worktree's PARCEL_DONE.md	The parcel session owns that file; audits go to the audits dir
Reading files outside the diff "for context"	Expands scope, inflates audit, misses the point
Hardcoding a worktrees path	Always resolve via `rookery.yaml` → `ROOKERY_WORKTREES` → `./worktrees`

About this skill