@mstar-harness/dsh 3.10.1 → 3.10.3

package/harness-skills/mstar-roles/references/qa-engineer/acceptance-gate.md

@@ -34,10 +34,7 @@ When **`QA mode: acceptance-only`**:
 
 ### Captured evidence mapping (`sdd evidence`)
 
-Retained `sdd evidence` bundles are consumed read-only: QA integrity-checks and maps the evidence — it never repeats the captured child command (exact command shapes and exit meanings → `mstar-sdd/references/file-handoffs.md` § Verification evidence). Map every AC with all columns:
-
-| AC | run/manual reference | original input identity | integrity | outcome | target applicability and reason | coverage judgment | targeted gap |
-| --- | --- | --- | --- | --- | --- | --- | --- |
+Retained `sdd evidence` bundles are consumed read-only: QA integrity-checks and maps the evidence — it never repeats the captured child command (exact command shapes, exit meanings and the four separate `verify` outputs → `mstar-sdd/references/file-handoffs.md` § Verification evidence). Map every AC with all columns of the report's AC table (**`references/qa-engineer.md`** § QA Report Landing and Template); for a retained bundle each column carries:
 
 - **Run/manual reference**: `{SDD_DIR}/evidence/<run-uuid>/` with the record and raw `stdout.log`/`stderr.log` paths — or the manual report/CI citation with provenance.
 - **Original input identity**: the recorded run's Git HEAD plus declared-input digest from `record.json` — the basis any target comparison reuses.
@@ -56,6 +53,28 @@ Scope authority → `mstar-harness-core` § 定向执行与验证边界. All QA
 - Missing screenshot or other real-environment evidence: record the unverified behavior and a pending independent E2E request for PM. Never launch a browser/device/E2E, change roles, or block/reopen routine iteration QA solely for that separate workflow. Unit acceptance cannot claim real-environment acceptance.
 - User-authorized local full-suite execution belongs to a separate implementer/ops action; QA may consume its result but has no `full` mode. Refer the authorization scope to PM instead of executing it here.
 
+## Budget stop and coverage readback
+
+Ceiling and scope authority → **`mstar-harness-core`** § 定向执行与验证边界; the role wording is in `references/qa-engineer.md` § Budget and Stopping. Honour the Assignment **`Budget`** / **`Return shape`** and never widen the core default. A bound stop keeps the AC outcomes and findings already verified and never invents elapsed time or file counts.
+
+- **Label only a real cut.** Emit `- Truncated coverage: <budget reached; specific ACs/interfaces not covered>` in the report `## Scope` only when a bound actually stopped expansion, naming the required ACs/interfaces left unchecked, and record those ACs as unverified. Omit the line on a complete run — a negation value is still a line, and consumers read the label's presence, not its wording.
+- **Exhaustion is not a channel failure.** A cap stop never rewrites an observed result, never becomes `Unconfirmed`, and never invents new QA vocabulary. A required evidence channel that is unavailable is a verification gap, handled by the existing `Blocked` result.
+- **Coverage readback, per assigned AC.** A checked AC keeps its observed `outcome` and its `run/manual reference`, including a witnessed failure; a required AC left without supported evidence is recorded as unverified and is not a pass.
+
+| Readback | Required coverage | Result |
+| --- | --- | --- |
+| Every assigned AC has supported evidence | covered | ordinary acceptance may proceed |
+| A required AC has no supported evidence (unverified, or its channel unavailable) | uncovered | return the existing **`Blocked`**; name the uncovered ACs and hand PM the targeted remaining scope |
+| An assigned AC failed with witnessed evidence | covered — the finding is retained | report the observed failure with its evidence; coverage ending never turns it into a coverage-only conclusion |
+
+A clean checked subset with `findings: []` is compatible with `unverified` ACs: `findings: []` describes the checked scope only and is never presented as full mandatory acceptance or `Done`.
+
+## Durable acceptance mapping (before Done)
+
+The landed report is the raw record; its landing obligation is defined once in `references/qa-engineer.md` § QA Report Landing and Template and is unchanged when the Assignment names no output path. Before `Done`, the report's compact AC → evidence → result mapping is preserved in the existing durable main-plan **`## QA Gate Summary`** (`mstar-artifacts/references/plan-files-and-reports.md`) — per-AC result, evidence reference, coverage/gap disclosure and the exact report pointer — which QA supplies from its report.
+
+Reuse that existing summary: no second archive, manifest or report format is created. Retain the raw report while the gate is active, so a later permitted bundle cleanup never leaves the only AC mapping in a deleted file.
+
 ## Unchanged hard duties
 
 Before sign-off or Done recommendation:
@@ -69,6 +88,8 @@ Before sign-off or Done recommendation:
 
 Use template in `references/qa-engineer.md`. May skip QC tri only when no implementation/test/config artifacts were committed.
 
+`report-only` is a mode, not the landing condition: the mandatory landing, scope/truncation disclosure and coverage readback above are unchanged, and an advisory report acquires no acceptance authority from its filename.
+
 ## Related
 
 - PM trigger matrix: `references/project-manager/qa-trigger-matrix.md`

package/harness-skills/mstar-roles/references/qa-engineer.md

@@ -27,7 +27,7 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
 
 ## Core QA Gate Duties
 
-Before sign-off: validate phase-gate prerequisites, Assignment metadata alignment, and reproducible evidence for any **new** checks. Mode/mapping rules → **`references/qa-engineer/acceptance-gate.md`**. Retained `sdd evidence` bundles are integrity-checked and mapped read-only (captured-evidence mapping columns → **`references/qa-engineer/acceptance-gate.md`** § Captured evidence mapping); QA never repeats a captured child command, and manual historical evidence is never converted into a v1 runner record.
+Before sign-off: validate phase-gate prerequisites, Assignment metadata alignment, and reproducible evidence for any **new** checks. Mode/mapping rules → **`references/qa-engineer/acceptance-gate.md`**. Retained `sdd evidence` bundles are integrity-checked and mapped read-only (captured-evidence mapping → **`references/qa-engineer/acceptance-gate.md`** § Captured evidence mapping); QA never repeats a captured child command, and manual historical evidence is never converted into a v1 runner record.
 
 ## Branch & Review Context Gate
 
@@ -35,14 +35,36 @@ Before sign-off: validate phase-gate prerequisites, Assignment metadata alignmen
 - Do not validate on a mismatched checkout
 - Same-repo concurrent write scenarios require worktree discipline
 
-## QA Report Template (Report-only)
+## Budget and Stopping (hard)
 
-When Assignment provides a report path, write report-only output under `{SDD_DIR}/review/` (for example `qa.md`) unless PM explicitly chooses tracked report archive mode.
+Scope and numeric-ceiling authority → **`mstar-harness-core`** § 定向执行与验证边界; this role adds its own stop/return duty, never a second cap. Honour the Assignment **`Budget`** and **`Return shape`**; when `Budget` is omitted the core default applies — it may be tightened, never loosened. Follow past the assigned QA scope only on a must-fix trail.
+
+- **Stop expanding on either bound.** Keep every outcome and finding already earned: a checked AC result (pass or fail) and a witnessed failure stay in the report and the AC map — truncation never rewrites, erases or downgrades an observed result. A clean checked subset may return `findings: []`; that describes the checked scope only, never full mandatory acceptance. Never invent elapsed time or file counts to justify a stop.
+- **Disclose the cut once, in the report `## Scope`.** When a bound actually stopped expansion, emit `- Truncated coverage: <budget reached; specific ACs/interfaces not covered>`, naming the required ACs/interfaces left unchecked, and record those ACs as unverified. On a complete run, omit the line entirely — do not emit it with a negation value either, because consumers read the label's presence, not its wording.
+- **A cap stop is not a failed evidence channel.** Exhaustion is never described as `Unconfirmed` and never invents new QA result vocabulary; a required evidence channel that is unavailable is recorded under verification gaps and returns the existing `Blocked` result. Uncovered required acceptance always returns `Blocked` — never a whole-scope pass, never `Done`; hand PM the targeted remaining scope.
+
+Acceptance readback and the durable mapping → **`references/qa-engineer/acceptance-gate.md`**.
+
+## QA Report Landing and Template
+
+Mandatory QA always writes `${SDD_DIR}/review/qa.md` (or the Assignment's explicit same-directory basename) with its AC → evidence → result mapping; report-only is a mode, not a condition for mandatory report landing.
+
+An Assignment that names no output path is not an exemption — the default above still applies, and mandatory acceptance is never conversation-only. `report-only` is a QA mode, not an authority: an advisory report never confers mandatory acceptance, and no filename confers `Done`. `Review archive mode: tracked reports` changes where the report is retained, not the obligation above.
 
 ```markdown
-# QA Report (Report-only)
+# QA Report
+
+## Scope
+- QA gate / QA mode: {mandatory | report-only} / {acceptance-only | targeted | report-only}
+- Review range / Diff basis: {exact copy from Assignment}
+- Working branch (verified): {name}
+- Review cwd (verified): {path from git rev-parse --show-toplevel}
+- Truncated coverage: {present only when a bound actually stopped expansion — name the required ACs/interfaces left unchecked; omit this line on a complete run. Truncation is not `Unconfirmed`}
+
+## Acceptance Criteria (AC → evidence → result)
+| AC | run/manual reference | original input identity | integrity | outcome | target applicability and reason | coverage judgment | targeted gap |
+| --- | --- | --- | --- | --- | --- | --- | --- |
 
-## Scope tested
 ## Findings
 ## Reproduction steps
 ## Evidence
@@ -50,7 +72,7 @@ When Assignment provides a report path, write report-only output under `{SDD_DIR
 ## Recommended owners
 ```
 
-The acceptance AC mapping uses the evidence columns defined in **`references/qa-engineer/acceptance-gate.md`** § Captured evidence mapping (`AC | run/manual reference | original input identity | integrity | outcome | target applicability and reason | coverage judgment | targeted gap`).
+Every assigned AC gets a row of that table with all eight columns recorded — a column that does not apply is written `n/a` / `not-assessed`, never dropped. What each column must contain for a retained `sdd evidence` bundle is defined in **`references/qa-engineer/acceptance-gate.md`** § Captured evidence mapping.
 
 ## Skill Preset (PM-Activated)
 
@@ -58,7 +80,7 @@ External topic skills below are **presets activated by PM**, not unconditional r
 
 1. `mstar-harness-core` → `mstar-coding-behavior` → `mstar-dispatch-gates` + `mstar-branch-worktree` (anti-recursion; checkout alignment with QC)
 2. Host adapter: `mstar-host` (detect; Read `references/opencode.md`, `cursor.md`, or `codex.md`)
-3. On demand: `mstar-artifacts` (closing R#); `mstar-conventions` (paths); `mstar-design-md` (map supplied UI evidence to DESIGN.md; no environment execution); `mstar-phase-gates` (Assignment references verification phase); review bundle files and QC consolidated inputs named in Assignment
+3. On demand: `mstar-artifacts` (closing R#); `mstar-conventions` (paths); `mstar-design-md` (map supplied UI evidence to DESIGN.md; no environment execution); `mstar-phase-gates` (Assignment references verification phase); `mstar-use-cli` (round runs or interprets CLI commands — closing a register row, reading a gate verdict's exit code); review bundle files and QC consolidated inputs named in Assignment
 
 ## Completion Report
 

package/harness-skills/mstar-roles/references/qc-specialist-shared.md

@@ -102,7 +102,7 @@ Role-owned procedures — **always read with this file, never preset-gated**: `r
 
 1. `mstar-harness-core` → `mstar-dispatch-gates` + `mstar-branch-worktree` → `mstar-artifacts` (review bundle paths and naming)
 2. Host: `mstar-host` → active host reference
-3. On demand: `mstar-conventions` (paths); `mstar-design-md` (UI vs DESIGN.md)
+3. On demand: `mstar-conventions` (paths); `mstar-design-md` (UI vs DESIGN.md); `mstar-use-cli` (seat runs or interprets a CLI check — report validation, checkout alignment, reading a refusal code)
 
 ## Completion Report
 

package/harness-skills/mstar-sdd/SKILL.md

@@ -58,8 +58,8 @@ Dispatch independent ready tasks concurrently after L2 worktree isolation. Keep
     - **`SDD implementer session: fresh`** (default) — new subagent; templates: `references/implementer-prompt.md`
     - **`SDD implementer session: sticky`** — first task: same as fresh + write `{SDD_DIR}/implementer-session.json` with `host_agent_id`; later tasks: host **resume** + `references/implementer-continuation-prompt.md` (see **`references/sticky-implementer-session.md`**)
 5. On `DONE`: `mstar sdd review-package BASE HEAD` → diff file
-6. Dispatch **fresh** task reviewer — role **`code-reviewer`** (L2; **not** `qc-specialist*`; host fallback generic + C5b → `mstar-host` C5) — brief, report, diff, Global Constraints — `references/task-reviewer-prompt.md` — **never** sticky resume for reviewers
-7. Fix loop for Critical/Important; re-review until approved
+6. Dispatch **fresh** task reviewer — role **`code-reviewer`** (L2; **not** `qc-specialist*`; host fallback generic + C5b → `mstar-host` C5) — brief, implementer report, diff, Global Constraints, and the reviewer's own output **`REPORT_FILE`** = `{SDD_DIR}/task-N-review.md` — `references/task-reviewer-prompt.md` — **never** sticky resume for reviewers
+7. Fix loop for Critical/Important; re-review until approved. Then PM reads `{SDD_DIR}/task-N-review.md` — the always-on L2 report, never the implementer's `task-N-report.md` — before appending step 8: the earned `Task quality` and partial findings stand for the reviewed scope, but assigned review scope left uncovered blocks task-complete and dependent release, so PM routes the remaining scope through a fresh/tightened reviewer dispatch; it never overwrites an `Approved` earned for checked scope or invents `Needs fixes` because the budget ended
 8. Append `progress.md`; record ledger progress through the **domain call** (`mstar plan progress --session <session.json> --file <absolute-json-path> --expect <revision>` on the scoped route; direct snapshot edit only on a non-scoped legacy route where the CLI is absent) plus `implementer-session.json` `last_task` if sticky — snapshot/revision semantics → `mstar-artifacts` `references/status-and-residuals.md`; scoped route → `mstar-iteration/references/plan-scoped-pm.md` §4/§7
 9. Release dependent tasks only after reviewed prerequisite commits are present in their assigned base, per Dependent-task readiness above; independent ready tasks need not wait
 
@@ -111,7 +111,7 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
 
 PM at start: `cat {SDD_DIR}/progress.md`. Tasks marked complete are DONE — do not re-dispatch after compaction.
 
-PM appends on clean review: `Task N: complete (<base>..<head>, review clean)`.
+PM appends on clean review: `Task N: complete (<base>..<head>, review clean, review: task-N-review.md)` — the entry names the L2 report path the review closed on.
 
 Minor findings → `## Minor (for plan QC)` section in same file.
 
@@ -125,6 +125,8 @@ Minor findings → `## Minor (for plan QC)` section in same file.
 - `HEAD~1` as review BASE
 - Pre-judge reviewer ("do not flag", "at most Minor")
 - Skip task review or accept missing verdict
+- Accept the L2 verdict from the message alone, or write L2 output to the implementer's `task-N-report.md` (the report is `{SDD_DIR}/task-N-review.md`)
+- Mark a task complete or release dependents while the assigned L2 review scope is uncovered
 - Re-dispatch tasks listed complete in ledger
 - PM thread implements instead of subagent dispatch
 - Sticky **resume** for task reviewers

package/harness-skills/mstar-sdd/references/file-handoffs.md

@@ -33,7 +33,7 @@ PM runs context-dependent `mstar sdd workspace`, `task-brief`, and `review-packa
    - One line scene-setting (where task fits)
    - Absolute brief path: read first — verbatim requirements
    - Interfaces / decisions brief cannot know
-   - Absolute report path: `$SDD_DIR/task-N-report.md`
+   - Absolute report path: `$SDD_DIR/task-N-report.md` — the implementer's own output slot and L2's **input**; the reviewer's separate output is `$SDD_DIR/task-N-review.md`
    - Absolute control root, feature cwd, branch and plan paths, plus task-specific brief/report/diff paths fixed for this dispatch; the context path is PM coordination metadata, not a leaf checkout selector
    - **Inherited plan scope, no credentials**: the handoff restates the inherited plan id + absolute paths and nothing more — a leaf neither selects a plan nor writes the workflow snapshot / root register / leases. Session JSON, `mstar plan --session` write credentials and `--expect <revision>` are PM/coordinator-only and **never** appear in a leaf prompt (`mstar-iteration/references/plan-scoped-pm.md` §8)
    - `Model tier` → host-specific model (required)
@@ -41,7 +41,7 @@ PM runs context-dependent `mstar sdd workspace`, `task-brief`, and `review-packa
 
 ## Implementer report file
 
-Implementer writes full report to `task-N-report.md`. Return to PM only:
+Implementer writes full report to `task-N-report.md` — its own output, and an **input** to L2; the task reviewer never writes this path and never overwrites it. Return to PM only:
 
 - Status: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
 - Commits (SHAs)
@@ -94,10 +94,16 @@ PM sets `FEATURE_CWD` from the completed task's immutable Assignment `Worktree p
 
 1. `HEAD_SHA=$(git -C "$FEATURE_CWD" rev-parse HEAD)`
 2. `mstar sdd review-package "$BASE_SHA" "$HEAD_SHA" --context "$SDD_DIR/context.json"` — context `featureCwd` must equal the same `$FEATURE_CWD` used for `HEAD_SHA`; probes git there, writes the diff into the control sddDir, prints absolute paths.
-3. Dispatch task reviewer with: brief path, report path, diff path, Global Constraints (verbatim from plan).
+3. Dispatch task reviewer with: brief path, implementer report path (`task-N-report.md` — an input it reads), diff path, **`REPORT_FILE` = `$SDD_DIR/task-N-review.md`** (the reviewer's own output — a different file, never the implementer's slot), Global Constraints (verbatim from plan).
 
 **Never use `HEAD~1` as BASE** — multi-commit tasks truncate.
 
+## Task review report file (L2 output)
+
+The fresh task reviewer writes its full report to `task-N-review.md` — always, for every completed task under `Execution mode: sdd`: not optional, never conversation-only, separate from the implementer report it reads. Body sections and `Task quality` verdict → **`task-reviewer-prompt.md`**. This file is the L2 output only — not formal QC (`{SDD_DIR}/review/qcN.md`) and not QA, and no consumer silently searches another basename.
+
+PM reads that named report before marking the task complete, and the ledger entry below records it. Partial findings and the `Task quality` verdict earned for the reviewed scope stay valid; assigned review scope left uncovered does **not**: PM routes the remaining scope through a fresh/tightened reviewer dispatch and does not append task-complete or release dependent work. A coverage gap is never converted into an invented code defect, and an `Approved` earned for checked scope is never overwritten.
+
 ## Bound child launch (CLI-launchable children)
 
 **PM-only serialized launch:** when the implementer is a CLI command rather than a hosted subagent, PM holds the serialized context operation through context validation and child spawn, using the launch Assignment's fixed checkout/branch. Do not rotate context until the launch resolves. Hosted leaves never use this entry for their assigned checks; they run allowed commands directly from their verified assigned feature workdir and branch:
@@ -127,10 +133,10 @@ The per-task fix loop applies the same fix-round mechanics as plan-level QC fix
 On clean task review, PM alone appends to `$SDD_DIR/progress.md`:
 
 ```text
-Task N: complete (<base>..<head>, review clean)
+Task N: complete (<base>..<head>, review clean, review: task-N-review.md)
 ```
 
-Minor findings: append under `## Minor (for plan QC)` in same file.
+The entry names the L2 report path the review closed on. Minor findings: append under `## Minor (for plan QC)` in same file.
 
 ## Plan-level QC package
 

package/harness-skills/mstar-sdd/references/task-reviewer-prompt.md

@@ -20,7 +20,8 @@ Dispatch:
 
     ## Destinations (absolute — read-only review)
 
-    - Control harness root: [CONTROL_ROOT] — implementer report [REPORT_FILE], diff [DIFF_FILE] are control artifacts.
+    - Control harness root: [CONTROL_ROOT] — implementer report [IMPLEMENTER_REPORT] and diff [DIFF_FILE] are control artifacts you read.
+    - **Your output — `REPORT_FILE` = [REPORT_FILE]**, i.e. `${SDD_DIR}/task-N-review.md`: write your full review there, and it is the only file you write. It is a different file from the implementer's report — never write or overwrite [IMPLEMENTER_REPORT].
     - Feature worktree under review: [FEATURE_CWD] on branch [WORKING_BRANCH] — you do not write there or anywhere except [REPORT_FILE].
     - The diff was produced by the bound `mstar sdd review-package --context [CONTEXT_FILE]` (git probed in the feature worktree, artifact written to the control sddDir).
     - First step: confirm the paths above are absolute and present; if a path is missing or relative, report NEEDS_CONTEXT instead of guessing.
@@ -28,9 +29,9 @@ Dispatch:
     Global constraints (verbatim):
     [GLOBAL_CONSTRAINTS]
 
-    ## Implementer report
+    ## Implementer report (input — not your output)
 
-    [REPORT_FILE] — treat claims as unverified until checked against diff.
+    [IMPLEMENTER_REPORT] — treat claims as unverified until checked against diff.
 
     ## Diff
 
@@ -48,11 +49,19 @@ Dispatch:
     assigned acceptance questions are answered.
     The task diff plus directly affected interfaces are this review's budget
     (default bounded-seat cap → `mstar-harness-core` § 定向执行与验证边界);
-    when it is reached, stop there and return the assessment for what was
-    reviewed plus a `Truncated coverage: <what was not covered>` line.
+    when it is reached, stop expanding there and disclose the cut once, in the
+    report `## Scope`, as `- Truncated coverage: <budget reached; specific
+    interfaces/files left unexamined>`; keep the assessment earned for what you
+    did review. On a complete review omit that line entirely — never emit it
+    with a negation value, because consumers read the label's presence.
+    A budget stop is not a failed evidence channel: never describe it as
+    `Unconfirmed`, and never downgrade an earned verdict or invent a finding
+    because coverage ended.
 
     ## Output
 
+    Write all of it to [REPORT_FILE].
+
     ### Spec Compliance
     - ✅ Spec compliant | ❌ Issues found (file:line)
     - ⚠️ Cannot verify from diff: [items for PM to check]
@@ -66,4 +75,8 @@ Dispatch:
     **Task quality:** Approved | Needs fixes
 ```
 
+When budget truncation applies, insert a `## Scope` section before `### Spec Compliance` with one bullet: `- Truncated coverage: <budget reached; specific interfaces/files left unexamined>`. On a complete review omit that section entirely.
+
+The reviewer always writes that full report to `REPORT_FILE` (`${SDD_DIR}/task-N-review.md`) and returns only a compact pointer plus the assessment to PM — a completed task under `Execution mode: sdd` has no conversation-only L2 output, and `REPORT_FILE` here is never the implementer's `task-N-report.md`. The `## Scope` line is the only truncation disclosure; a truncated review keeps the `Task quality` it earned for checked scope, and PM cannot mark the whole task complete while assigned review scope remains uncovered.
+
 Re-review after fixes checks both verdicts only for the raised findings and fix delta; unchanged evidence remains reusable. PM resolves all ⚠️ items before marking task complete.

package/harness-skills/mstar-use-cli/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: mstar-use-cli
+description: Use when a Morning Star agent must choose, run, or interpret `mstar-harness` / `mstar` CLI commands — picking the command family for a task (plan row, lifecycle close, register write, report landing, worktree and lease checks, path resolution), satisfying the preconditions a family needs (harness root, control root, neutral cwd, session envelope, version tokens), reading exit codes 0 / 1 / 2 and stable refusal codes, or running the versioned read-modify-write handshake. Also load it when a topical skill's engine-check callout points at the CLI, or when a command refused and the cause looks like a missing precondition. Flags and option wording are never restated here — the CLI help owns them.
+---
+
+# CLI contract (`mstar-use-cli`)
+
+The CLI is the harness's machine surface: gates, coordination writes and validators sit behind it. This skill is the index that says **which family answers a task, what must be true before running it, in what order a sequence goes, and how to read the answer**.
+
+It is deliberately silent in one direction. Command help is generated from the same source that parses the arguments, so it is the only non-drifting owner of flags, option wording and argument shapes. Help cannot express cross-command choice, preconditions, sequence order or refusal meaning — those are what this skill owns.
+
+## Load Order
+
+1. `mstar-harness-core` — lifecycle, gates, authorization and conflict authority; first read whenever it is loaded.
+2. The **owning topical skill** for the family about to run (named in the task index below) — it holds the semantics, role boundaries and surrounding workflow.
+3. This skill — the CLI transport contract for that family.
+
+Conditional scope: this applies when a CLI binary is on PATH. Where the CLI is absent, the engine-import / prose path declared by each topical skill stays authoritative; do not read the command text here as a load-order dependency, and never use this skill as a substitute for the owning skill's rules.
+
+Add `mstar-host` when the host's tool shapes decide how a command is launched.
+
+## Scope
+
+Load when:
+
+- a CLI command must be run, or output from one must be interpreted;
+- a topical skill's engine-check callout pointed here;
+- an exit 1 / 2 came back and its meaning is unclear, or a command refused for a reason that looks like a missing precondition;
+- a decision is needed between families (read a row, close a lifecycle, register a document, land a report, check a worktree);
+- a coordinated document must be written — versioned replacement, token-aware retry.
+
+Do not load for:
+
+- installation, host bootstrap, per-host config — `INSTALL.md` plus `mstar-host`;
+- flags, option wording, per-command argument shapes — the CLI help owns them;
+- field schemas (`mstar-artifacts`), iteration phase semantics (`mstar-iteration`), checkout rules (`mstar-branch-worktree`), role preset decisions (`mstar-roles`);
+- slash commands (`/codebase-audit`, `/iteration-drive`, …). They ship with the host plugin, not the CLI binary; their owning skills (`mstar-audit`, `mstar-iteration`, …) hold their contracts.
+
+## Workflow
+
+### 1. Task → command family
+
+Find the task, run the family, then read its owning skill for the rules around it.
+
+| Task | Family | Owning skill |
+|---|---|---|
+| Read a plan row: revision, byte versions, scoped paths, operations allowed now | `mstar plan show` | `mstar-iteration` (scoped drive), `mstar-artifacts` (fields) |
+| Claim or resume a scoped session; bootstrap a coordinator session | `mstar plan bind` | `mstar-iteration` |
+| Register a reviewed Assignment and release its dependencies | `mstar plan prepare` | `mstar-iteration` |
+| Update progress; open / close a residual in this plan's bucket | `mstar plan progress`, `mstar plan residual-add`, `mstar plan residual-close` | `mstar-sdd`, `mstar-artifacts` |
+| Finish a plan (handoff; row stays InReview) | `mstar plan handoff` | `mstar-sdd`, `mstar-artifacts` |
+| Transfer execution ownership / return a handoff | `mstar plan accept`, `mstar plan return` | `mstar-iteration` |
+| Run the pinned integration and record Done; recover a crashed attempt | `mstar plan integration-start`, `mstar plan integration-accept`, `mstar plan complete`, `mstar plan reconcile` | `mstar-branch-worktree`, `mstar-iteration` |
+| Amend an approved Prepare scope | `mstar workflow show-prepare`, `mstar workflow amend-prepare` | `mstar-artifacts` |
+| Register a standalone plan workflow; record delivery evidence | `mstar workflow register`, `mstar workflow evidence` | `mstar-artifacts` |
+| Close one finished lifecycle (terminal snapshot + root unregister) | `mstar status workflow-close` | `mstar-iteration` (Phase 6) |
+| Validate a coordination document before trusting or replacing it | `mstar status validate` | `mstar-artifacts` |
+| Read the residual rollup; enforce a plan's findings-cleanup mode; register or close deferred backlog | `mstar status tech-debt`, `mstar status findings-cleanup`, `mstar status backlog-register`, `mstar status backlog-close` | `mstar-project-governance`, `mstar-artifacts` |
+| Read or replace a coordination document | `mstar persist get`, `mstar persist list`, `mstar persist <kind>` | `mstar-artifacts` |
+| Land or check a QC seat report | `mstar qc validate-report` | `mstar-review-qc` |
+| Validate an Assignment before dispatch | `mstar dispatch validate` | `mstar-dispatch-gates` |
+| Map an execution mode to its QC seat count; assert tri identity | `mstar review seats` | `mstar-review-qc` |
+| Verify a plan's execution lease; verify the integration merge lease | `mstar lease verify`, `mstar lease verify-integration` | `mstar-artifacts`, `mstar-branch-worktree` |
+| Check L1 / L2 pre-dispatch worktree topology | `mstar worktree check` | `mstar-branch-worktree`, `mstar-dispatch-gates` |
+| Assert QC / QA checkout alignment across seat files | `mstar worktree qc-alignment` | `mstar-branch-worktree` |
+| Post-merge worktree and branch cleanup (dry-run first) | `mstar worktree cleanup` | `mstar-iteration` |
+| SDD helpers: workspace, brief, branch diff package, bound launch, evidence capture | `mstar sdd workspace`, `mstar sdd task-brief`, `mstar sdd review-package`, `mstar sdd check-context`, `mstar sdd exec`, `mstar sdd evidence` | `mstar-sdd` |
+| Evaluate a phase-transition gate; probe push cadence | `mstar iteration gate`, `mstar iteration push-cadence` | `mstar-iteration`, `mstar-phase-gates` |
+| Resolve the harness / plan / SDD / workflow / project dirs | `mstar path resolve` | `mstar-conventions` |
+| Detect the active host; resolve a loaded skill root | `mstar host detect`, `mstar host skill-root` | `mstar-host` |
+| Lint harness artifacts by content type | `mstar lint` | `mstar-skill-authoring`, `mstar-coding-behavior`, `mstar-strategy` |
+| Lint a skill's frontmatter and five-question body | `mstar skill lint` | `mstar-skill-authoring` |
+| Validate the role mapping and load-order corpus | `mstar roles validate` | `mstar-roles` |
+| Validate a knowledge doc and its index row | `mstar compound validate` | `mstar-compound` |
+| Validate DESIGN.md tokens and parity | `mstar design-md validate` | `mstar-design-md` |
+| Scaffold or promote audit plans; run static security checks | `mstar audit scaffold`, `mstar audit promote`, `mstar audit secret-scan`, `mstar audit supply-chain` | `mstar-audit` |
+| PR-review arithmetic, report path, saved-report validation, worktree setup | `mstar pr-review tally`, `mstar pr-review report-path`, `mstar pr-review validate-report`, `mstar pr-review worktree-setup` | `mstar-audit` (pr variant) |
+| Bootstrap a harness directory | `mstar harness scaffold` | `mstar-conventions` |
+| Migrate a v1 status tree to v2 (one-shot, not a routine step) | `mstar migrate` | `mstar-artifacts` |
+
+Per-family detail — refusal codes, JSON envelopes, sequence walkthroughs — is in the references listed at the end. Validator and lint families are indexed in `references/checks-and-lints.md`.
+
+### 2. Precondition ladder
+
+Take the rungs in order. Each one fails closed: a command that cannot establish a rung refuses instead of silently falling back to a different root or a different identity.
+
+1. **Root.** Every command that touches harness state resolves a harness directory, and two resolutions exist: a *process root* derived from the main worktree (so a command run inside a linked worktree still addresses the control harness) and a *local probe* that walks up from the cwd, bounded by the workspace root. They can disagree from the same cwd, and a linked worktree usually carries no harness root of its own. Read `mstar path resolve` first when unsure, and name the root explicitly (`--harness <absolute-path>`, `MSTAR_HARNESS_DIR`, or the positional control root where the command takes one).
+2. **Residency.** Coordinator verbs belong to the main worktree — or to the recorded integration worktree where a sequence says so. Product edits stay in the feature worktree; process documents stay in the control root.
+3. **cwd neutrality.** Git-derived checks derive the main worktree and branch facts from the process cwd. Run them from a neutral cwd so the derivation matches what the snapshot recorded.
+4. **Identity.** `--session <absolute-json>` names an engine-generated envelope obtained from the bind verb; the engine re-checks it against its document inside the write lock. There is no force, no takeover, no holder or role input, and no lease-release verb. A resume is read-only. Write credentials stay with the coordinator: a session envelope or a revision token never reaches a leaf executor's assignment.
+5. **Tokens.** Three kinds, never interchangeable: a row revision and a register version (both from `mstar plan show --json`), and a document byte version (`mstar persist get --versioned`, `mstar workflow show-prepare`).
+6. **Re-read after a refusal.** Refusals are mutation-free; a stale token is recovered by reading again, never by forcing or retrying blind.
+
+Full treatment of every rung, including the failure each one produces: `references/preconditions.md`.
+
+### 3. Two canonical sequences
+
+Both are protocol shapes, not scripts — supply the placeholders, take the flags from the family's help.
+
+Protected document, versioned read-modify-write:
+
+```sh
+# 1. read the current bytes and their version token
+mstar persist get snapshot --key <workflow-id> --versioned
+
+# 2. modify the payload locally, keeping the document's schema intact
+
+# 3. replace it against exactly that token (nothing is merged)
+mstar persist snapshot --key <workflow-id> --expect-version sha256:<64-hex> --file payload.json --session <coordinator-envelope>
+```
+
+`status` always uses the key `root`; `residuals` takes the project id; replacing a coordinated snapshot also needs the coordinator envelope. For a document that does not exist yet the token is the literal `absent`.
+
+Plan completion, coordinator side, after the plan session handed off. The engine picks one of **two routes** from the workflow's own type and delivery kind — never from anchors that happen to be missing:
+
+```sh
+mstar plan handoff --session <plan-session.json> --file handoff.json --expect <revision>
+mstar plan accept --session <coordinator.json> --plan <plan-id> --handoff <live-handoff-id> --expect <revision>
+
+# iteration route only (type: iteration, or any non-standalone workflow)
+mstar plan integration-start --session <coordinator.json> --plan <plan-id> --handoff <live-handoff-id> --expect <revision>
+git merge --no-ff --no-edit <source-sha>          # operator action, in the recorded integration worktree
+mstar plan integration-accept --session <coordinator.json> --plan <plan-id> --handoff <live-handoff-id> --expect <revision>
+
+# both routes end here; a standalone development plan completes straight from the accepted handoff
+mstar plan complete --session <coordinator.json> --plan <plan-id> --handoff <live-handoff-id> --expect <revision>
+```
+
+`complete` releases only the row's lease on the standalone route and both leases on the iteration route; a standalone workflow stays running until its delivery evidence and the workflow close. `mstar plan return` handles a failed attempt; `mstar plan reconcile` finishes an attempt after a crash without a second merge — on the standalone route it only replays an already-completed row. `repair-delivery-source` exists solely for pre-fix snapshots whose registered source branch wrongly equals the target. Every `--expect` comes from a fresh read, because the previous call consumed the revision. Per-step preconditions and failure behavior: `references/plan-and-workflow.md`.
+
+## Decision Rules
+
+- **Canonical binary is `mstar-harness`.** `mstar` is a short alias that shares its bin namespace with an unrelated third-party npm package of the same name: outside an environment where the harness package is installed, invoking the short alias through a package runner resolves via the registry to that other tool, and co-installing both packages globally silently overwrites the `mstar` shim — last install wins. Prefer the canonical name in scripts, CI and anything a reader might copy out of context.
+- **Exit codes: `0` ok, `1` engine refusal, `2` usage.** `0` includes idempotent no-ops and read-only reads. `1` carries a stable machine code and leaves authoritative bytes unchanged. `2` is a usage error — unknown flag, missing required option, malformed or relative path where an absolute one is required, unreadable payload.
+- **The argument parser can exit 1 for a missing required argument**, which lands inside the refusal range: the message reads `error: missing required argument '<name>'`. Read the message, not only the number, before treating an exit as a gate refusal or as a usage error. Commands that validate their own required arguments print a `usage:` line and exit 2 even for a missing argument, so the two shapes coexist in the same CLI.
+- **Flags come from the CLI help, never from this skill.** Run the group help, or the verb help, before guessing an option; the group help is also the authority for which verbs exist at all.
+- **Refusals are mutation-free, so they are recoverable by reading.** Re-read the document, then retry with fresh tokens. There is no force, no replace and no takeover flag to escalate to.
+- **A submitted handoff pins the bytes of the reports it names.** The digest is taken at submission, so any later edit to a cited report — even appending a section — invalidates it, and completion then refuses with a stale-evidence code naming the mismatching path. Finish every evidence file before handing off; if one genuinely has to change afterwards, `return` the handoff and re-sign it rather than completing against the old pin.
+- **Streams are per command and per mode — observe them, never infer from the family.** A verb's machine surface (the `--json` form, or a verb whose output is a machine object such as `persist get`) writes that object to **stdout**, failure and refusal objects included, so neither the exit code nor the family tells you which stream carried the bytes. On the human surface a success is usually one short line on **stdout** (`<path>: OK`, `host: <id>`), though some verbs leave stdout empty and put the readable summary on **stderr**; usage errors and most refusal diagnostics go to **stderr**, and one command can split inside itself — machine rows on stdout, the human headline on stderr. No split holds for every command and no enumeration is reliable, so never assume a command's failure text is on stderr: where a pipe depends on it, read the actual output or that command's help. The exit code is the verdict; an empty stdout is not by itself a failure signal.
+- **The CLI you run may not be the code you read.** The globally installed binary runs the *published* engine build, and even a workspace entry point resolves the engine's **built output**, which can lag its source until that package is rebuilt — so a fix present in the engine source can be absent from the very command you are testing. Install health, and a healthy setup check, prove neither. When a result contradicts source you just read, rebuild or re-resolve before concluding the source is wrong, and follow the version-alignment path in `mstar-harness-core`. The same caution covers a repository's own generated bundles: a checkout can be mid-flight between source and artifact.
+- **Never write a lifecycle state or a lease by editing a document.** Done and lease release go through the completion verb; the protected coordination documents refuse direct writes by design.
+- **Never hand write credentials to a leaf.** Session envelopes and revision tokens are coordinator/PM material; the scoped-drive rules in `mstar-iteration` own that boundary.
+- **A validator's `OK` is a statement about its own contract only.** Exit 0 means no violations of that check — not that the content is correct, complete or current.
+
+## Evidence
+
+A CLI claim is proven when:
+
+- the command was actually run, or the result is a machine object a command produced this round — not a recollection of documentation;
+- the exit code matches the family contract, and a `1` is reported with its stable code and message;
+- preconditions were explicit: absolute paths, an explicit root wherever discovery is ambiguous, a session envelope obtained from the bind verb, and tokens read from the command that will consume them;
+- no refusal was retried with a stale token — after a refusal the document was re-read;
+- commands quoted in a plan, report or handoff are re-runnable as written, with real absolute paths or visibly-marked placeholders;
+- for a validator, the cited check is the one that covers the claim being made.
+
+## References
+
+| Open | When |
+|---|---|
+| `references/plan-and-workflow.md` | plan / workflow families: verb and role boundaries, refusal codes, JSON envelopes, the completion sequence, the CAS read-modify-write shape |
+| `references/status-and-registers.md` | `status.json` root, workflow snapshot and project register: write surfaces, protection levels, versioned replacement, close order, residual lifecycle |
+| `references/checks-and-lints.md` | maintainer validators and lints that skill callouts cite: what each checks, its owning skill, its exit codes |
+| `references/preconditions.md` | harness-root resolution, control root vs feature worktree, neutral cwd, session identity, tokens, and how each missing precondition presents itself |
+
+Command help is the flag reference. Installation and host setup live in `INSTALL.md` and `mstar-host`.

package/harness-skills/mstar-use-cli/references/checks-and-lints.md

@@ -0,0 +1,70 @@
+# Maintainer validators and lints
+
+This file indexes the check commands — the ones skill engine-check callouts cite and the ones a gate or a review runs before trusting an artifact. The validator and lint rows are a thin transport over an engine validator: each reads a document, applies that validator's contract, and reports violations. The table is not all validators, though — it also carries an informational rollup, register and lifecycle writes, phase and push gates, and PR-review arithmetic and path contracts — and two rows are not checks at all: `mstar audit scaffold` and `mstar audit promote` write files and register a workflow, indexed here only so the audit family is not mistaken for a read-only one (see their row). Use it to answer three questions: which command checks this artifact, which skill owns the rules behind it, and what its exit code means.
+
+Behavior that the check's own contract does not cover is owned elsewhere: field schemas by `mstar-artifacts`, phase semantics by `mstar-iteration`, checkout rules by `mstar-branch-worktree`, dispatch fields by `mstar-dispatch-gates`.
+
+## Reading a result
+
+| Code | Meaning |
+|---|---|
+| `0` | no violations of this check's contract (an empty directory walk prints a "no lintable files" note and still exits 0) |
+| `1` | violations or data errors — one row per violation on stderr, each with a stable code; also used for a missing document, an unreadable input, or a resolution failure |
+| `2` | usage: missing target, unknown option value, or a path the command cannot classify |
+
+The description-driven commands follow the same convention, with one parser caveat: a missing **required argument** may be reported by the argument parser with exit `1` and a `error: missing required argument '<name>'` line instead of the contract's `2`. Commands that validate their own required arguments print a `usage:` line and exit `2`. Read the message before classifying an exit.
+
+Diagnostics go to stderr in every case; a check that prints a rollup (the tech-debt and lease checks) puts it on stdout.
+
+## Command index
+
+| Command | What it checks | Owning skill (callout home) | Exit codes |
+|---|---|---|---|
+| `mstar status validate` | a v2 status root (version + timestamp + registered workflows with per-entry invariants) or one workflow snapshot (schema version, plan rows, lease shapes). v1 input fails closed and points at the migration verb | `mstar-artifacts` | `0` ok · `1` violations / missing or unreadable file |
+| `mstar status tech-debt` | residual tech-debt rollup aggregated over every project register (total open, by severity, by target, by plan). Informational: the register is the source of truth, so there is no stored-summary drift check | `mstar-project-governance` | `0` rollup (zero when registers are empty) · `1` project dir not found or resolution failed |
+| `mstar status findings-cleanup` | enforces a plan's cleanup mode over its project-register entries, keyed by plan id; an explicit mode wins, otherwise the permissive default. Plans without register entries pass trivially | `mstar-artifacts` | `0` no open-residual violations · `1` one row per violating open residual |
+| `mstar status backlog-register` | registers deferred-PR backlog entries in a project register under the status write lock: same-day key bump and entry-id uniqueness inside the lock, with provenance fields filled by the command | `mstar-project-governance` | `0` registered · `1` gate or IO refusal · `2` usage |
+| `mstar status backlog-close` | closes one backlog entry in place under the same lock (resolved lifecycle, closure timestamp, closure note); an absent id or key fails loud rather than silently no-op | `mstar-project-governance` | `1` absent entry · `0` closed |
+| `mstar status workflow-close` | one finished lifecycle: terminal snapshot plus root unregister. Consults delivery evidence before writing; dangling leases, unfinished rows and incomplete evidence refuse before any write. Order, authorization and partial-close recovery → `references/status-and-registers.md` | `mstar-iteration` (Phase 6 post-merge close) | `0` closed or idempotent re-run · `1` gate or IO refusal · `2` usage |
+| `mstar status archive-residuals` | nothing — removed in v3. It exits `1` and names the replacement: close the entry in its project register instead | — (points at `mstar-project-governance`) | `1` always |
+| `mstar dispatch validate` | an Assignment document: required header fields, exactly one branch form, then the protected-default-branch gate | `mstar-dispatch-gates`, `mstar-review-qc` | `0` ok · `1` violations · `2` usage |
+| `mstar review seats` | maps an execution mode to its QC seat count; with the reviewer list, asserts tri identity | `mstar-review-qc` | `0` ok · `1` violations · `2` usage |
+| `mstar worktree check` | pre-dispatch topology at L1: main-worktree residency, the dedicated integration checkout, and the plan's execution-lease feature worktree (existence, branch alignment); the L2 form checks parallel writable tracks | `mstar-branch-worktree`, `mstar-dispatch-gates` | `0` ok · `1` violations · `2` usage |
+| `mstar worktree qc-alignment` | that the QC/QA alignment fields (plan id, review range, diff basis) are byte-identical across the given seat files, accepting the separate and the combined label forms | `mstar-branch-worktree` | `0` ok · `1` mismatch or missing field · `2` no files given |
+| `mstar worktree cleanup` | guarded worktree and branch cleanup for a workflow: merged-evidence-only branch deletion with active-lease, checked-out, foreign, dirty and non-terminal refusals; a dry run by default that prints one verdict row per candidate | `mstar-iteration` (post-merge close) | `0` valid dry run or successful removals · `1` probe or mutation failure · `2` usage |
+| `mstar lease verify` | a plan's execution lease on its snapshot row | `mstar-artifacts` | `0` valid (prints the holder) · `1` missing or invalid |
+| `mstar lease verify-integration` | the workflow's integration merge lease when present; an absent lease is a valid unclaimed state | `mstar-artifacts`, `mstar-iteration` | `0` unclaimed or valid · `1` invalid lease · `2` usage |
+| `mstar qc validate-report` | a saved QC seat report against its machine-readable contract: frontmatter fields, verdict vocabulary, body/verdict agreement, summary-to-findings count parity, truncation and verdict coherence | `mstar-review-qc` | `0` ok · `1` violations |
+| `mstar iteration gate` | the phase-transition gate for a workflow, printing the transition plus its entry and exit checklists; the post-merge form checks local close state (terminal snapshot, no dangling lease, root entry unregistered) and needs no compass | `mstar-iteration`, `mstar-phase-gates` | `0` pass · `1` gate fail or error · `2` usage |
+| `mstar iteration push-cadence` | the push gate: never push while CI or a review wave is running | `mstar-iteration` | `0` clear · `1` blocked |
+| `mstar lint` | harness artifacts by content type, inferred from the target's name and location: plan files against the quality bar, skills against the frontmatter contract, `STRATEGY.md` against its required sections, task reports against the report triple, code files for markers. Two content types are explicit-only: finding documents and the content-agnostic provenance scan, which reports dated local-instance citations that tracked text must not carry | `mstar-skill-authoring`, `mstar-strategy`, `mstar-sdd`, `mstar-coding-behavior`, `mstar-audit` | `0` ok · `1` violations or file errors · `2` missing target, unknown type, unclassifiable file without a forced type |
+| `mstar skill lint` | one skill directory: frontmatter contract (name, trigger-contract description), the five-question body, and the ephemeral-citation scan | `mstar-skill-authoring` | `0` ok · `1` violations · `2` usage |
+| `mstar roles validate` | the role mapping and parameter tables against the on-disk references layout, plus the load-order declarations across sibling skills | `mstar-roles` | `0` ok · `1` violations |
+| `mstar compound validate` | a knowledge document's frontmatter against its schema; with the knowledge dir, also the README index rows and the document's scope | `mstar-compound`, `mstar-compound-refresh` | `0` ok · `1` violations · `2` usage |
+| `mstar design-md validate` | DESIGN.md in a directory: token frontmatter, light/dark parity when the dark file exists, and the completeness level | `mstar-design-md` | `0` ok · `1` violations · `2` usage |
+| `mstar path resolve` | the resolved harness, plan, SDD, workflow and project dirs from a start dir; the machine form adds the start dir and a resolution flag | `mstar-conventions` | `0` resolved · `1` no harness dir from that start dir |
+| `mstar host detect` | the active host id from a comma-separated list of session tool-shape tokens; prints an ambiguous verdict rather than guessing | `mstar-host` | `0` host id · `2` usage |
+| `mstar host skill-root` | the canonical loaded-skill root for one host and skill, optionally with a relative asset path appended | `mstar-host` | `0` prints the root · `1` missing required option · `2` unknown host or empty skill |
+| `mstar audit secret-scan` / `mstar audit supply-chain` | the two read-only static scans: credential patterns over tracked files, and supply-chain shape (lockfile, unpinned action refs, PR-head checkout) | `mstar-audit` | `0` clean · `1` findings · `2` usage |
+| `mstar audit scaffold` / `mstar audit promote` | **not a check — both write.** `scaffold` creates an `audit-<date>/` plan directory (numbered plan files + README index) from a findings file, at `--dir` or `./audit-<date>` from cwd; `promote` writes a workflow snapshot and then **registers the workflow in `{HARNESS_DIR}/status.json`** — a guarded registration entry point, not a review-seat check (payload fields → `mstar-artifacts`). `promote` refuses without `--delivery-kind`; run either only under the authorization its owning skill names | `mstar-audit` | `0` wrote / registered · `1` failure (for `promote`, also an unresolvable harness dir) · `2` usage |
+| `mstar pr-review tally` / `mstar pr-review report-path` / `mstar pr-review validate-report` | the PR-review arithmetic and naming contracts: tally computation from findings, local report path resolution, and saved-report validation | `mstar-audit` (pr variant) | `0` ok · `1` violations · `2` usage |
+| `mstar plugin validate` | a plugin package against the portable plugin format: root manifest schema, server descriptor when present, and skill discovery (child directory with a matching skill file) | repository maintenance, not a skill callout | `0` conformant · `1` findings |
+
+Two rows write state under a lock — the backlog pair and the lifecycle close — and the audit pair writes outside any lock: `mstar audit scaffold` creates a plan directory and `mstar audit promote` registers a workflow. Read-only rows are what make this table usable from a review seat, so before running a row from one, read the row itself: never invoke the two audit writers from a read-only seat.
+
+## `/codebase-audit` category tokens
+
+The audit command's category token set, used when a run is narrowed to one category (recon first, then that category only):
+
+| Token | Meaning | Default |
+|---|---|---|
+| `<category>` | Category focus — recon, then that category only: `bug`, `security`, `perf`, `tests`, `tech-debt`, `migration`, `dx`, `docs`, `direction` (plan `Category` field values) | all nine |
+
+## What a green run proves
+
+Each command mirrors one validator, so exit `0` is a statement about that validator's contract and nothing more:
+
+- a structural pass does not prove a command ran, a diff applied, or an artifact is content-correct — those need the evidence the owning skill names;
+- a check that skips unreadable inputs passes on what it could read, so pair it with the artifact-level claim the owning skill requires;
+- an informational command (the tech-debt rollup) reports a projection of the register; the register stays the source of truth;
+- when a check and a gate disagree, the gate's owning skill decides, and the disagreement is a finding to report rather than a check to rerun.