@attalabs/vinaya 0.19.3 → 0.20.1

package/aeg-root/skills/brief-authoring/SKILL.md

@@ -249,7 +249,7 @@ Do not leave documentation as an implication of the tier checklist. **List the e
 - **Never list a new file for a one-off report, audit finding, coverage summary, or working brief.** If the task's deliverable is a finding, an audit result, or a coverage report, its home is the PR body (task-scoped) or an Issue/PR comment (not task-scoped) — never a new file under `aeg-root/` or a product's `aeg-project/`. A committed scratch file has already broken AEG Studio once (a coverage report committed as `aeg-root/tranches/<name>.audit.md` was silently parsed as a broken tranche by the Studio loader) and produced a stale permanent brief once (`aeg-project/briefs/<name>-brief.md`, contradicting this skill's own "pasted, not committed" rule above). See `tranche-model.md` §9 rule 4.
 - **Tier 0** — usually none. State "No doc updates required (Tier 0)."
 - **Tier 1** — name each: which spec(s) reflect the new behavior, which skill(s) if a convention shifted, `docs-index.md` if files were added/removed/renamed.
-- **Tier 3** — all Tier 1 items, plus: which state changes (the per-project pinned state Issue; the tranche file; per-project backlogs). **Never** list `roadmap.md` or `now.md` — both retired (`roadmap.md`; `now.md`). Active-work state is derived from the forge, not written to a file.
+- **Tier 3** — all Tier 1 items, plus: which state changes (the tranche file; per-project backlogs; any non-derivable fact recorded as an ordinary open Issue). **Never** list `roadmap.md`, `now.md`, or a pinned state Issue — all retired. Active-work state is derived from the forge, not written to a file.
 
 A Tier 1+ brief with an empty doc-update list is malformed.
 
@@ -371,7 +371,7 @@ These two qualify a task and ride into the PR body. Both are reference-only —
 ```
 **Project:** [project(s) this task touches — e.g. "web" or "engine, api"]
 ```
-Multi-valued. Resolves against `.vinaya/projects.md`. **Required in a multi-project repo; omitted entirely in a single-project repo** (no registry → one project → no field). Routes the Developer to the right specs and the Archivist to the right per-project state; a value that doesn't resolve to a registry row makes the brief malformed (refuse, don't guess). It must match the Planner's `Project(s)` for the task, including every shared-package consumer in the blast radius — see `roles/planner.md` and the planner-brief contract.
+Multi-valued. Resolves against `.vinaya/projects.md`. **Required in a multi-project repo; omitted entirely in a single-project repo** (no registry → one project → no field). Routes the Developer to the right specs; a value that doesn't resolve to a registry row makes the brief malformed (refuse, don't guess). It must match the Planner's `Project(s)` for the task, including every shared-package consumer in the blast radius — see `roles/planner.md` and the planner-brief contract.
 
 ```
 **Ticket:** [external ticket link(s) — e.g. "SAT-412 — https://…"]

package/aeg-root/state-machine.md

@@ -125,11 +125,10 @@ Rows = artifact types. Columns = roles. "—" means no authority. The Reviewer i
 | **Specs** (`apps/*/specs/*.md`) | Approves PR; ratifies a spec-only change | Coherence review on PR; can open spec-only PRs | Writes in PR per brief scope | Validates cross-references; flags stale specs in drift cron |
 | **Skills** (canonical `aeg-root/skills/*/SKILL.md`) | Approves PR | Coherence review | Writes in PR per brief scope | Flags stale skill references in drift cron |
 | **Agent defs** | Approves PR | Coherence review | Writes in PR per brief scope | Flags stale agent references in drift cron |
-| **`state.md`** | Approves PR | Writes in PR | Flags state changes needed in PR description | Updates per-project state at close-out, for every project the task listed |
 | **Per-project backlogs** (`apps/*/specs/*-backlog.md`) | Approves PR | Writes (held/future items — out of the flow) | — | — |
-| **`coordination.md`**, **`state-machine.md`** | Approves PR; final authority on system-level rule changes | Proposes changes via PR | — | Flags inconsistencies in drift cron |
+| **`state-machine.md`** | Approves PR; final authority on system-level rule changes | Proposes changes via PR | — | Flags inconsistencies in drift cron |
 | **`thinking.md`** | Reads | Writes freely in any Brief Author session (best-effort, optional) | Reads | Flags if untouched >7 days |
-| **Per-project state / lessons log** (pinned Issues) | Approves/rejects/defers items at windows | Appends items; marks resolved after Principal action | Appends via escalation (`severity: product`) | — for the per-task Archivist; the **Tranche Archivist** updates it at Phase 13 close-out (`update-pinned-state-issue`, `roles/tranche-archivist.md`) |
+| **Lessons log** (the standing lessons Issue) | Approves/rejects/defers items at windows | Appends items; marks resolved after Principal action | Appends via escalation (`severity: product`) | The **Tranche Archivist** appends the retrospective at Phase 13 close-out (`roles/tranche-archivist.md`) — one new comment per tranche, never an edit. (The hand-edited per-project state Issue this row once also covered is retired: everything it held is either forge-derived — Milestones + `vinaya/tranche:*` labels — or belongs in an ordinary open Issue closed when resolved.) |
 | **Source code** | Merges PR | — | Writes in PR per brief scope; opens PR | — |
 | **Forge labels** (the Section 14 vocabulary) | Applies `vinaya/override:docs` (Principal-only) | Applies `vinaya/tier:*` (Planner, at cut) + `vinaya/needs:*-input` / `vinaya/blocked` (by hand or via automation) | Applies `vinaya/needs:*-input` / `vinaya/blocked` (by hand or via automation) | Applies `vinaya/needs:brief-correction`; asserts `vinaya/tier:*` label == PR-body `Tier:` (drift cron) |
 | **Task status** | — | — | — | — *(nobody writes it — derived from the forge)* |
@@ -167,7 +166,7 @@ Used when verifying state, resolving contradictions, running verify-docs, post-m
 1. Ratified specs (`Status: ratified`)
 2. Shipped code (main — what actually runs)
 3. Aspirational specs (`Status: target`)
-4. PM docs (tranche files) plus per-project pinned state/lessons Issues — non-derivable operational facts / plan topology (active status derived from forge)
+4. The lessons Issue (append-only retrospectives/calibration) — non-derivable observations; active status always derived from the forge, never from any doc
 5. Skills + `thinking.md`
 6. Briefs / Issues / PR descriptions — intent at time of writing
 7. Conversation logs / tool runtime logs — lowest
@@ -205,6 +204,8 @@ A spec file exists in one of four states:
 
 Most specs are `draft` — no deliberate ratification pass has been done. Future PRs ratify as appropriate.
 
+**Spec naming (locked):** spec filenames are `{product}-spec.md` or `{component}-spec.md` — no `-v0`/`-v1`/`-draft`/date suffixes. Version state lives in the file's `Status:` block above, never the filename. Renaming to add a version suffix requires a lock challenge.
+
 > Note: the Reviewer's spec-conformance check (§3) reads the project spec **as written** — at whatever ratification state it currently holds. A `draft` spec is still the project's stated intent and is checked against; a contradiction with a `ratified` spec is the most serious. The Reviewer never edits the spec; if it's wrong, that's an escalation.
 
 ---
@@ -304,7 +305,7 @@ The lowest-commitment way to run AEG: read-only over a team's existing process.
 - **Typecheck, tests** — standard CI gates; always blocking.
 - **Issue template / no forbidden fields** — a required Issue template + a CI check reject planning metadata (priority/estimates/points) on task Issues, keeping them execution-only.
 - **Brief validation** — the Archivist's `brief-validation` job runs `packages/aeg-core/bin/verify-brief.ts` against the PR body and checks presence of every required brief section (Tier, `For:` model attribution, `Project:` — both read from the PR body's header block, before the first `##` heading, the same region the post-merge Archivist's provenance assembly reads — tagged Test Plan, surface map, doc-update list, worktree Step 0, stop conditions, autonomy clause, `Closes #N`); flags malformed briefs (`vinaya/needs:brief-correction`) and fails CI. **The trigger is the body, not the branch (`fix/brief-gate-nontask`):** the gate runs when the branch is `task/<tranche>/<n>` **or** the body is brief-shaped (`isBriefShaped` — ≥2 of surface map / doc-update list / stop conditions / autonomy clause, matched on `stripCode`'d text so a brief *quoted inside a fence* stays exempt). Bodies that are neither still bypass — that exemption is for an ordinary non-AEG PR (a one-line dependency bump) which carries no brief and must not be forced to grow one. The old branch-only bypass was the wrong proxy for it: a standalone `fix/*` brief **is** a brief, and it skipped every section check — confirmed live on `fix/studio-tranche-href`, which shipped with no §7 documentation-update list because `checkDocUpdateList`, the checker that exists for exactly that, never ran. `Closes #N` remains **task-branch-only** (`BriefSectionsOptions.requireClosesN`): a standalone fix brief has no task Issue to close, and a `plan/*` PR is *forbidden* to carry one by the plan-PR guard below — requiring it there would make the two gates jointly unsatisfiable. The same validator also runs at **authoring time** as the `brief-shape` check — `PR_BODY="$(cat brief.md)" vinaya check brief-shape` (on this repo's toolchain, also `bun packages/aeg-core/bin/verify-brief.ts --body-file <brief.md>`) — before a PR or even a branch exists, so a Brief Author gates a brief before dispatch rather than after the Developer has done the work (`skills/brief-authoring/SKILL.md` protocol step 4); with no `BRANCH`, the branch is read from the brief's own Step 0 `git worktree add … -b` line. **Includes the plan-PR Closes guard**: a `plan/*` branch whose PR body carries `Closes #N` fails CI before the non-task bypass even runs — a plan PR creates Issues, it does not resolve one (`roles/planner.md`); this closed a confirmed pattern of plan PRs prematurely closing task Issues on merge. **Real**, now the `Brief Validation` step (9/9) of the AEG gate suite job in `.github/workflows/forge-lifecycle.yml`. Presence-only — it cannot judge whether a Test Plan item is truly scriptable or whether a declared `unit-tests-only` is justified by the surface map; those remain Reviewer + Verification judgment. Same enforcement substrate as above.
-- **Per-task Archivist close-out** — `.github/workflows/archivist.yml::post-merge` (`packages/aeg-core/bin/archive-task.ts`) runs on every push to `main`, resolves the merge commit's PR via `gh api repos/{owner}/{repo}/commits/{sha}/pulls`, and — for task-branch PRs only — assembles and posts the Archivist provenance block (`roles/archivist.md` item 8) and explicitly closes the task's Issue, confirming the closed state before exiting. Idempotent **per PR**, not per Issue (an Issue can legitimately accrue multiple merged PRs over its life; idempotency never spans PRs): skips silently if the PR already carries a provenance comment. Skips silently on non-task branches (`plan/*`, `fix/*`, …). Fails loud (non-zero exit) on any `gh`/permission error — never a silent no-op. Real, installed with `contents: read`, `issues: write`, `pull-requests: write` permissions. Does not automate the Tranche Archivist or items 2–7 of per-task close-out (docs coherence, per-project state, `docs-index.md`, token ledger) — those remain dispatched-Archivist judgment work.
+- **Per-task Archivist close-out** — `.github/workflows/archivist.yml::post-merge` (`packages/aeg-core/bin/archive-task.ts`) runs on every push to `main`, resolves the merge commit's PR via `gh api repos/{owner}/{repo}/commits/{sha}/pulls`, and — for task-branch PRs only — assembles and posts the Archivist provenance block (`roles/archivist.md` item 8) and explicitly closes the task's Issue, confirming the closed state before exiting. Idempotent **per PR**, not per Issue (an Issue can legitimately accrue multiple merged PRs over its life; idempotency never spans PRs): skips silently if the PR already carries a provenance comment. Skips silently on non-task branches (`plan/*`, `fix/*`, …). Fails loud (non-zero exit) on any `gh`/permission error — never a silent no-op. Real, installed with `contents: read`, `issues: write`, `pull-requests: write` permissions. Does not automate the Tranche Archivist or items 2–7 of per-task close-out (docs coherence, `docs-index.md`, token ledger) — those remain dispatched-Archivist judgment work.
 - **Manifest integrity** — `verify-docs --full` and the coherence oracle validate the doc-owners manifest: pointer existence (M1), glob syntax (M2 advisory), and duplicate globs (M3). There is no decision-number sequencing: the log it validated is gone.
 - **Closes #N gate** — task-branch PRs must declare `Closes #<its-issue>` in the PR body; absence fails CI. Non-task branches bypass this forward direction automatically. Real, installed at `.github/workflows/forge-lifecycle.yml::closes-n-gate`. Same enforcement substrate as above. **Forge-native-tranche fix (`fix/closes-n-forge-native`):** the gate's scoped `loadTrancheFiles(null, onlySlug)` call discovers which tranches exist by listing `aeg-root/tranches/*.md` filenames — a tranche with zero topology file never entered that enumeration, so the forge derivation was never invoked for it despite the tranche already being fully Milestone-capable, and the gate failed every such PR with a misleading "no topology file found." Fixed by falling back to a direct forge derivation (the Milestone-existence check plus the file-and-forge composition, today `indexTrancheMilestonesAsync` + `mergeFileTopology`) when the requested `onlySlug` isn't found via files, gated on an actual open Milestone existing so an unrecognized branch slug still fails honestly — the scoped-path counterpart to `verify-dispatch.ts`'s `otherActiveTrancheSlugs` fix. **Reverse direction (`fix/closes-n-reverse`):** a `Closes #N` that resolves to a real AEG task Issue (title matches the `[<tranche-slug>] <task-id>...` convention and carries a `vinaya/tranche:<slug>` label) now requires the branch to actually be named `task/<tranche-slug>/<task-id>`, regardless of what the branch itself is called — closing the blind spot that let a mis-named branch implement a real task Issue with zero forge-visible status. One batched forge query (`fetchTaskIssueRefs`) resolves each referenced Issue's task identity before `checkClosesN` runs. **Code-span hardening (`fix/closes-gate-hardening`):** both the pre-merge gate (`checkClosesN` in `brief-validation.ts`) and the coherence-side parse (`extractClosesReferences` in `coherence-checks.ts`) now `stripCode` the body before matching the closing keyword, as GitHub's own auto-close parser ignores `Closes #N` inside a code span or fenced block. Inline spans of **any backtick-run length** are covered (`` `x` ``, `` ``x`` ``, …) via CommonMark's `(`+)…\1` matched-run rule — the double-backtick form was a false-green in the first cut (peeled as two empty spans). Fenced blocks are matched by a line scanner that pairs a fence with its own closer by **character and run length**: `~~~` tilde fences, info strings (```` ```js ````), and runs longer than three (```` `````` ````) all strip correctly, and an unclosed fence runs to end of body as GitHub renders it — the earlier `` /```[\s\S]*?```/g `` regex missed all three. The keyword set matches GitHub's own: `close`/`closes`/`closed`, `fix`/`fixes`/`fixed`, `resolve`/`resolves`/`resolved`. Before this, a body whose only `Closes #N` was backticked passed the gate **green** yet merged **without** closing its Issue, then read red on every open PR via A3 `auto-close-misfire`; "verify-docs green" now implies "GitHub will auto-close" for fenced + inline-code forms. 4-space **indented** code blocks are stripped too, conservatively: a ≥4-column-indented run counts as code only when it follows a blank line *and* is not inside a list — since within a list item that indentation is the item's own content indent, which GitHub *does* auto-close (blanking it would be a false-red, the brief's over-strip stop condition). The strip runs on the **whole body, before any region is sliced out of it** — never on a slice. Every rule in it is block-structural (a fence pairs with its own closer; an indented run is code only after a blank line and outside list context), so a fragment strips differently from the same text in place: stripping the sliced `AEG:CLOSES` region blanked an anchor indented inside a list item — list content GitHub *does* auto-close — and the Archivist's `extractIssue` returned no Issue, stranding it on merge exactly as before. Markers are HTML comments and survive the strip, so selecting the region from stripped text loses nothing and subsumes the decoy protection: a decoy anchor inside code never survives to be sliced. The same grammar governs `maskCode`, the index-preserving variant `anchoredRegion` runs to find the `AEG:*` markers themselves — it is **upstream** of every `stripCode` call, so while it stayed on the naive fence/inline regexes a decoy `AEG:CLOSES` anchor inside a tilde fence, a ≥4-backtick fence, a double-backtick span, or an indented block won the region outright and the gate resolved a **wrong** Issue number (worse than the strandings above: the post-merge Archivist's `extractIssue` would explicitly close an unrelated Issue). Both now delegate to one pair of scanners, differing only in what they emit per code line — nothing for `stripCode`, same-length filler for `maskCode` — so a divergence is a compile-level impossibility rather than a convention. This hardens all five anchored fields (`CLOSES`, `PROJECT`, `TIER`, `PREMISE`, `TEST-PLAN`) at once, not just the closing reference. `stripCode` normalises `\r\n`/`\r` to `\n` before any of these scanners run: the fence scanners anchor per line, and JS's `.`/`$` never match `\r`, so a CRLF body opened no fence at all and let a fenced `Closes #N` walk free — the same false-green along a new axis, and it hit exactly the web-UI-authored bodies this CI backstop exists for (HTML normalises textarea newlines to CRLF on submit). The closing-keyword separator is **bounded** (`\s{0,8}:?\s{0,8}`, identical in both parsers): two adjacent unbounded `\s*` groups backtrack quadratically on `closes` + long whitespace + no `#` — ~2.0 s at GitHub's 65,536-char body cap, run twice on the fail path — where the bound is 0.1 ms. **Known residual:** a genuine indented code block *nested inside a list* is therefore left unstripped — the deliberately safe direction of that trade. A `Closes #N` surviving only inside code fails with an actionable message pointing at a bare reference in the `AEG:CLOSES` anchor. `stripCode` is the one shared stripper, exported from `anchored-region.ts` (no duplicated regex).
 - *(The practitioner-facing map of every enforcement mechanism — prevention, detection, audit — lives in `aeg-root/enforcement.md`; this section remains the normative gate registry.)*
@@ -324,7 +325,7 @@ The lowest-commitment way to run AEG: read-only over a team's existing process.
 - **Dispatch gates** (depends-on merged / no conflicting PR open) — read from the forge and complied with; mechanical enforcement arrives when an automation tool runs dispatch (`tranche-model.md` §8).
 - **Label discipline** (Section 14) — `vinaya/tier:*` present on every task Issue and kept in sync with the PR-body `Tier:`; `vinaya/needs:*-input` / `vinaya/blocked` present-when-true *and removed when false*; no `status:*` labels; no `project:*` labels; no label outside the closed set. Trusted discipline; the Archivist drift cron asserts the tier label/field match and flags stale `vinaya/needs:*` labels.
 - **Contract conformance** (a role doc matches its `contracts/*.md` seam) — trusted discipline; the Archivist drift cron flags a role doc that contradicts its contract. The contract is the source of truth; a divergent role doc is the bug. (The Planner→Brief contract's *rationale field-completeness* — every task Issue body carries all eight fields — moved to Enforced via R1 above; only the "role doc text matches contract prose" half remains trusted here.)
-- **Provenance assembly at close-out — items 1/8 moved to Enforced**, see "Per-task Archivist close-out" above; items 2–7 of close-out (docs coherence, per-project state, `docs-index.md`, token ledger) remain trusted, dispatched-Archivist judgment work — it records, it never gates.
+- **Provenance assembly at close-out — items 1/8 moved to Enforced**, see "Per-task Archivist close-out" above; items 2–7 of close-out (docs coherence, `docs-index.md`, token ledger) remain trusted, dispatched-Archivist judgment work — it records, it never gates.
 - **Decision logging during chat** — Brief Author announces and logs during the conversation; CI cannot verify.
 - **No execution metadata in the tranche file; no dynamic conflict scanner** — the two anti-regression rules (`tranche-model.md` §9); trusted discipline, flagged by the Archivist drift cron and the Planner's gates.
 - **`thinking.md` updates; ratification-window attendance; lock acknowledgment (advisory in V0); spec ratification passes** — all trusted.
@@ -400,6 +401,7 @@ No label outside this table may be applied to a task Issue or its PR. (The Archi
 | `vinaya/tier:0` / `vinaya/tier:1` / `vinaya/tier:3` | Issue (+ mirrors the PR-body `Tier:`) | Impact tier — drives required docs (§9) and whether it merges at a ratification window. The forge has no concept of "impact." | **Planner** sets it at Issue cut (plan-time estimate). The **PR-body `Tier:`** is the binding value at merge; the Developer corrects the field if execution reveals a different tier, and re-syncs the label. | **Always-mandatory** — exactly one per task |
 | `vinaya/type:build` / `vinaya/type:chore` / `vinaya/type:docs` / `vinaya/type:feat` / `vinaya/type:fix` / `vinaya/type:perf` / `vinaya/type:refactor` / `vinaya/type:revert` / `vinaya/type:style` / `vinaya/type:test` | Issue | What kind of change the task is — the same ten commit-type names `roles/developer.md`'s commit conventions use, applied to the Issue instead of the commit. The forge has no concept of a task's shape. | **Planner** sets it at Issue cut. | **Always-mandatory, checked at Issue creation only** — `open-issue.ts` requires exactly one on every `create`; it never re-checks the label on a later `edit`, so this is forward-only from this axis's own merge without retroactively refusing an edit to an Issue that predates it (no backfill) |
 | `vinaya/blocked` | Issue | A block that has **no forge fact** behind it ("waiting on an answer" isn't visible from branch/PR state). | Developer/Brief Author when a task is blocked on an escalation; **removed** the moment it unblocks. | Conditional-mandatory |
+| `vinaya/backlog` | Issue | Marks deliberate unplanned-ness — the Issue belongs to no tranche and is excluded from dispatch, a fact no forge field shows. | Planner/Principal when an Issue is consciously left unplanned; **removed** when a Planner promotes it into a tranche. | Conditional-mandatory |
 | `vinaya/incoherent` | Issue | A `COMPLETED` close with **no merged-PR link** — the forge shows "closed" but cannot show *whether the one law was honored* (done iff a merged `Closes #N`). Marks the anomaly for a human to resolve; AEG never auto-reopens. | Detected by `verify-coherence` (A1) / surfaced in Studio; applied when the incoherence is found, **removed** when a human clears it (link the merge, or re-close `NOT_PLANNED`). | Conditional-mandatory |
 | `vinaya/needs:execution-input` | Issue | Routes an open escalation to the **Brief Author** (§7). | Developer at escalation; removed when answered. | Conditional-mandatory |
 | `vinaya/needs:strategy-input` | Issue | Routes to the **Brief Author** — a design-path question, not an execution one. | Developer at escalation; removed when answered. | Conditional-mandatory |

package/aeg-root/task-model.md

@@ -36,7 +36,7 @@ This is the operational sequence — distinct from §2's derived-status vocabula
 3. **Review** — code-reviewer pass (`roles/reviewer.md`) and security pass (`roles/security.md`), each emitting a structured verdict. A REQUEST CHANGES or FAIL loops back to **Code** — bounded by a revision ceiling so the loop always ends, never open-ended.
 4. **Verify** — the tagged Test Plan runs for real: the `[agent]` items the Developer executes against the running app, the `[principal]` items a human confirms. This is the gap between "CI is green" and "the feature actually works" — static review alone cannot exercise an auth-gated, key-dependent, or browser-rendered path.
 5. **Merge** — the PR merges once Review and Verify are both satisfied. This is the boundary, not a stage with its own actor: merging is the mechanical consequence of the two gates above clearing, not a separate decision.
-6. **Archive** — the Archivist closes out: the Issue is explicitly closed (never left to GitHub's advisory auto-close), docs coherence is confirmed, the per-project pinned state Issue is updated for every project the task listed, the provenance block is assembled and posted to the merged PR. This is the task's terminal stage — nothing follows it at this altitude.
+6. **Archive** — the Archivist closes out: the Issue is explicitly closed (never left to GitHub's advisory auto-close), docs coherence is confirmed, the provenance block is assembled and posted to the merged PR. This is the task's terminal stage — nothing follows it at this altitude. (The hand-edited per-project state Issue is retired — non-derivable facts live as ordinary open Issues, closed when resolved; active state is derived from the forge.)
 
 Orphaned task (a branch exists, no PR, gone stale) is the one named exception to this straight line: a close-out/sweep step flags it and a human deletes the branch, returning the task to `todo` — a real, owned recovery path, not a silent drop.
 

package/aeg-root/templates/pr-report-template.md

@@ -46,6 +46,10 @@ Closes #[N]
 
 Run `vinaya pr report --write <this-body-file>` and commit its output — this block is generated, never hand-typed. `check-evidence-fresh` refuses a body whose block doesn't match the head it's attached to.
 
+The block opens with `Head:` and a `Summary:` line — a file and line count derived from the same `--numstat` printed two lines below it, so the body never needs a hand-written "four files changed" sentence that a later commit silently falsifies. Its value is emitted inside backticks, which is what makes it legal under the bare-digit rule below — no exemption, just the same inline code span any other digit needs. Do not type or edit the line: `check-evidence-fresh` byte-compares it, backticks included, against a fresh recompute, and a hand-written count fails there.
+
+**Keep the anchor pair out of the `<details>` block.** `body-bare-digits` blanks every digit inside a collapsed block, so an evidence block hidden in one is exempt from the digit scan and unverifiable — `check-evidence-fresh` refuses rather than passing silently. Both checks resolve this region from one shared, normalised context, so a zero-width character or an HTML entity in a marker no longer makes one of them see a block the other cannot.
+
 <!-- AEG:EVIDENCE:START -->
 [run `vinaya pr report --write` to populate — do not type this block by hand]
 <!-- AEG:EVIDENCE:END -->

package/dist/checks/bin/check-body-bare-digits.js

@@ -5,17 +5,17 @@
 import { execFileSync as execFileSync3 } from "child_process";
 // ../../packages/aeg-core/src/gate-audience.ts
 var GATE_AUDIENCE = {
-  "check-branch-topology": { shippedAs: "branch-topology" },
-  "check-first-push-dispatch": { shippedAs: "first-push-dispatch" },
-  "check-no-disk-state": { shippedAs: "no-disk-state" },
-  "verify-brief": { shippedAs: "brief-shape" },
-  "verify-coherence": { shippedAs: "coherence" },
-  "verify-dispatch": { shippedAs: "dispatch-readiness" },
-  "verify-docs": { shippedAs: ["doc-coverage", "doc-coverage-push"] },
-  "verify-registry": { shippedAs: "registry-gates" },
-  "verify-review-gate": { shippedAs: "review-gate" },
-  "verify-single-plan-pr": { shippedAs: "single-plan-pr" },
-  "verify-test-plan": { shippedAs: "test-plan" },
+  "check-branch-topology": { shippedAs: "branch-topology", ring: 0 },
+  "check-first-push-dispatch": { shippedAs: "first-push-dispatch", ring: 0 },
+  "check-no-disk-state": { shippedAs: "no-disk-state", ring: 0 },
+  "verify-brief": { shippedAs: "brief-shape", ring: 0 },
+  "verify-coherence": { shippedAs: "coherence", ring: 0 },
+  "verify-dispatch": { shippedAs: "dispatch-readiness", ring: 0 },
+  "verify-docs": { shippedAs: ["doc-coverage", "doc-coverage-push"], ring: 0 },
+  "verify-registry": { shippedAs: "registry-gates", ring: 0 },
+  "verify-review-gate": { shippedAs: "review-gate", ring: 1 },
+  "verify-single-plan-pr": { shippedAs: "single-plan-pr", ring: 0 },
+  "verify-test-plan": { shippedAs: "test-plan", ring: 1 },
   "check-direct-main-push": {
     internal: "Reaches adopters through `vinaya audit --only=direct-push`, not the check registry: it is a ring-2 sweep over merge history keyed on `GITHUB_SHA`, run by the generated archivist job on push to the default branch. It has no diff to key on, so there is nothing for `vinaya check` to run it against."
   },
@@ -327,6 +327,13 @@ var LABELS = [
     form: "literal",
     carries: "Execution is halted pending an external unblock; wins over every other derived status."
   },
+  {
+    key: "backlog",
+    id: "vinaya/backlog",
+    category: "state",
+    form: "literal",
+    carries: "The Issue is deliberately unplanned — belongs to no tranche and is excluded from dispatch, until a Planner promotes it."
+  },
   {
     key: "tier-0",
     id: "vinaya/tier:0",
@@ -1985,7 +1992,59 @@ function overrideActive(opts) {
   return false;
 }
 // ../../packages/aeg-core/src/premise-check.ts
+import { createHash } from "node:crypto";
 var ASSERTION_KINDS = new Set(["contains", "absent", "sha256"]);
+function isPremiseHeader(line) {
+  const stripped = line.replace(/[*#]/g, "").trim();
+  return /^premise\s*:?$/i.test(stripped);
+}
+var PREMISE_LINE = /^[-*]\s*(\S+)\s+(contains|absent|sha256)\s*:\s*(.+)$/i;
+function parsePremiseBlock(prBody) {
+  const searchIn = anchoredRegion(prBody, "PREMISE") ?? prBody;
+  const lines = searchIn.split(/\r?\n/);
+  const assertions = [];
+  let inBlock = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!inBlock) {
+      if (isPremiseHeader(line))
+        inBlock = true;
+      continue;
+    }
+    if (line === "")
+      break;
+    const m = line.match(PREMISE_LINE);
+    if (!m)
+      break;
+    const [, path, kindRaw, value] = m;
+    const kind = kindRaw.toLowerCase();
+    if (!ASSERTION_KINDS.has(kind))
+      continue;
+    assertions.push({ kind, path, value: value.trim() });
+  }
+  return assertions;
+}
+function checkPremises(assertions, fileReader) {
+  const failures = [];
+  for (const a of assertions) {
+    const content = fileReader(a.path);
+    if (content === null) {
+      failures.push(`premise-check: ${a.path} does not exist on disk (premise asserted \`${a.kind}: ${a.value}\`) — the surface moved since this brief was authored; re-dig before proceeding.`);
+      continue;
+    }
+    if (a.kind === "contains" && !content.includes(a.value)) {
+      failures.push(`premise-check: ${a.path} no longer contains "${a.value}" — the premise this brief pinned has moved; re-dig before proceeding.`);
+    } else if (a.kind === "absent" && content.includes(a.value)) {
+      failures.push(`premise-check: ${a.path} now contains "${a.value}", but the brief pinned it absent — the premise has moved; re-dig before proceeding.`);
+    } else if (a.kind === "sha256") {
+      const actual = createHash("sha256").update(content).digest("hex");
+      if (actual !== a.value.toLowerCase()) {
+        failures.push(`premise-check: ${a.path} sha256 mismatch (brief pinned ${a.value}, file is now ${actual}) — the file changed since this brief was authored; re-dig before proceeding.`);
+      }
+    }
+  }
+  return { pass: failures.length === 0, failures };
+}
 
 // ../../packages/aeg-core/src/test-plan-section.ts
 var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
@@ -2789,6 +2848,7 @@ function checkG1(rows, existsFn) {
   }
   return { check: "G1", status: findings.length > 0 ? "fail" : "pass", findings };
 }
+var SCAFFOLD_PLACEHOLDER = "[undocumented — fill in why]";
 function checkG2(rows, candidateFiles) {
   const implementations = new Set(rows.map((r) => r.implementation).filter((p) => p !== ""));
   const findings = [];
@@ -2800,6 +2860,16 @@ function checkG2(rows, candidateFiles) {
       });
     }
   }
+  for (const row of rows) {
+    const carriesPlaceholder = [row.summary, row.description, row.spec].some((cell) => cell === SCAFFOLD_PLACEHOLDER);
+    if (carriesPlaceholder) {
+      findings.push({
+        row: row.action,
+        path: row.implementation,
+        reason: `${row.ring} row "${row.action}" still carries the scaffold placeholder marker — the why is owed`
+      });
+    }
+  }
   return { check: "G2", status: findings.length > 0 ? "info" : "pass", findings };
 }
 function checkG3(ring0Rows, crossingFiles) {
@@ -3319,6 +3389,29 @@ function isNewDiskStateFile(path, status) {
     return false;
   return ANY_DEPTH_TRANCHES_MD.test(path) || TOKENS_FILE.test(path);
 }
+// ../../packages/aeg-core/src/main-branch-refusal.ts
+function checkMainBranchRefusal(facts) {
+  const { currentSymbolicBranch, defaultBranch } = facts;
+  if (currentSymbolicBranch === null)
+    return null;
+  if (defaultBranch === null) {
+    return {
+      reason: "default-branch-undetermined",
+      severity: "warning",
+      currentBranch: currentSymbolicBranch,
+      defaultBranch: null
+    };
+  }
+  if (currentSymbolicBranch === defaultBranch) {
+    return {
+      reason: "on-default-branch",
+      severity: "error",
+      currentBranch: currentSymbolicBranch,
+      defaultBranch
+    };
+  }
+  return null;
+}
 // ../../packages/aeg-core/src/branch-topology-gate.ts
 function taskBranchTopologyFields(branch) {
   if (!/^task\/.*\/.*$/.test(branch))
@@ -3665,8 +3758,15 @@ function isSafeRepoRelPath(p) {
 var SafeRepoRelPath = z.string().refine(isSafeRepoRelPath, {
   message: "must be a repo-root-relative path with no `..` segment or absolute root"
 });
+var CANONICAL_HOOK_BLOCK_PREFIXES = [".git/", ".husky/", ".vinaya/hooks/", ".claude/hooks/"];
+function isCanonicalHookBlockPath(p) {
+  return CANONICAL_HOOK_BLOCK_PREFIXES.some((prefix) => p.startsWith(prefix) && p.length > prefix.length);
+}
+var ManagedHookBlockPath = SafeRepoRelPath.refine(isCanonicalHookBlockPath, {
+  message: `must start with one of ${CANONICAL_HOOK_BLOCK_PREFIXES.join(", ")} (byte-exact, case-sensitive)`
+});
 var ManagedBlockRecordSchema = z.object({
-  path: SafeRepoRelPath,
+  path: ManagedHookBlockPath,
   marker: z.string(),
   comment: z.enum(["hash", "html"])
 });
@@ -3847,6 +3947,81 @@ function emitCheckError(error) {
 `);
 }
 
+// src/lib/numstat.ts
+function summariseNumstat(numstat) {
+  const rows = numstat.split(`
+`).filter((l) => l.trim() !== "");
+  let added = 0;
+  let deleted = 0;
+  let binary = 0;
+  for (const row of rows) {
+    const [a, d] = row.split("\t");
+    if (a === "-" || d === "-") {
+      binary++;
+      continue;
+    }
+    added += Number(a) || 0;
+    deleted += Number(d) || 0;
+  }
+  const files = `${rows.length} file${rows.length === 1 ? "" : "s"} changed`;
+  const bin = binary > 0 ? `, ${binary} binary` : "";
+  return `${files}, ${added} insertion${added === 1 ? "" : "s"}(+), ${deleted} deletion${deleted === 1 ? "" : "s"}(-)${bin}`;
+}
+var EVIDENCE_SUMMARY_PREFIX = "Summary: ";
+
+// src/checks/scan-context.ts
+var ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/g;
+var HTML_ENTITIES = {
+  """: '"',
+  "'": "'",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&amp;": "&"
+};
+function decodeNamedEntities(body) {
+  return body.replace(/&(?:quot|apos|lt|gt|amp);/g, (m) => HTML_ENTITIES[m] ?? m);
+}
+function normalizeBody(rawBody) {
+  return decodeNamedEntities(rawBody.replace(ZERO_WIDTH, ""));
+}
+function buildAnchorLookupMask(body) {
+  return maskDetailsBlocks(maskCode(body));
+}
+
+class ScanContext {
+  raw;
+  normalised;
+  masked;
+  constructor(raw, normalised, masked) {
+    this.raw = raw;
+    this.normalised = normalised;
+    this.masked = masked;
+  }
+  static from(rawBody) {
+    const normalised = normalizeBody(rawBody);
+    return new ScanContext(rawBody, normalised, buildAnchorLookupMask(normalised));
+  }
+  rawResolutionAgrees(field) {
+    const rawHasPair = anchoredRegionBounds(this.raw, field) !== null;
+    return rawHasPair === (anchoredRegionBounds(this.masked, field) !== null);
+  }
+}
+function resolveAnchoredRegion(ctx, field) {
+  const bounds = anchoredRegionBounds(ctx.masked, field);
+  if (bounds === null) {
+    return anchoredRegionBounds(ctx.normalised, field) !== null ? "hidden" : null;
+  }
+  return {
+    region: ctx.normalised.slice(bounds.innerStart, bounds.innerEnd),
+    maskedRegion: ctx.masked.slice(bounds.innerStart, bounds.innerEnd)
+  };
+}
+function summaryLineIndex(maskedRegion) {
+  const index = maskedRegion.split(`
+`).findIndex((line) => line.startsWith(EVIDENCE_SUMMARY_PREFIX));
+  return index === -1 ? null : index;
+}
+
 // src/checks/body-bare-digits-logic.ts
 function blankRange(text, start, end) {
   const region = text.slice(start, end);
@@ -4022,8 +4197,8 @@ var BOUNDED_ANCHOR_BLANK = {
   PROJECT: blankProjectField,
   EVIDENCE: blankEvidenceField
 };
-function buildScanMask(body) {
-  let masked = maskDetailsBlocks(maskCode(body));
+function buildScanMask(ctx) {
+  let masked = ctx.masked;
   masked = blankAnchoredRegions(masked);
   masked = blankPremiseValues(masked);
   masked = blankTokenReportSection(masked);
@@ -4032,17 +4207,6 @@ function buildScanMask(body) {
 }
 var TOKEN_WITH_DIGIT = /\S*\p{Nd}\S*/gu;
 var LIST_MARKER_TOKEN = /^\p{Nd}{1,9}[.)]$/u;
-var ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/g;
-var HTML_ENTITIES = {
-  "&quot;": '"',
-  "&apos;": "'",
-  "&lt;": "<",
-  "&gt;": ">",
-  "&amp;": "&"
-};
-function decodeNamedEntities(body) {
-  return body.replace(/&(?:quot|apos|lt|gt|amp);/g, (m) => HTML_ENTITIES[m] ?? m);
-}
 function isLineLeadingListMarker(line, matchStart, rawToken) {
   if (!LIST_MARKER_TOKEN.test(rawToken))
     return false;
@@ -4050,8 +4214,9 @@ function isLineLeadingListMarker(line, matchStart, rawToken) {
   return /^ {0,3}$/.test(before);
 }
 function checkBareDigits(rawBody) {
-  const body = decodeNamedEntities(rawBody.replace(ZERO_WIDTH, ""));
-  const masked = buildScanMask(body);
+  const ctx = ScanContext.from(rawBody);
+  const body = ctx.normalised;
+  const masked = buildScanMask(ctx);
   const maskedLines = masked.split(`
 `);
   const origLines = body.split(`