# 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, the issue-store lifecycle writes, phase and push gates, and PR-review arithmetic and path contracts — and one row is not a check at all: `mstar audit scaffold` writes a review report, indexed here only so the audit family is not mistaken for a read-only one (see its 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`.

Payload discovery is read-only: mstar-harness schema <type> describes supported runtime inputs such as CaptureInput, OccurrenceInput, IssueTriage, ClosureEvidence, IssueLink and PlanProgress; current command help owns flags and completion payload lookup. Schema output never validates the operator's evidence/authority. Historical `judgment submit` is retired; no command route is registered.

## 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: a missing **required argument** is answered by the usage envelope — `command.invalid-input`, exit `2` — carrying the parser's own message line, for example `error: missing required argument 'kind'` (the probed behavior of the current built CLI); the parser routes its missing-input failures to this same usage envelope. Read the message before classifying an exit.

Diagnostics go to stderr in every case; a check that prints a rollup (the tech-debt rollup) puts it on stdout.

A check that reads the execution authority or the issue store refuses `store.not-initialized` (exit `1`) when the control root has no store. The refusal names the two bootstrap paths: an empty workspace runs `mstar harness scaffold` then `mstar store init`; a workspace holding historical file state runs `mstar store upgrade` to import it. A workspace that needs no execution authority uses conversation tracking (no-plan mode) instead of creating a store.

## Command index

| Command | What it checks | Owning skill (callout home) | Exit codes |
|---|---|---|---|
| `mstar status validate` | the control root's ACTIVE execution authority: the store's route/state plus the root, workflow and plan CAS tokens a caller records as `--expect`. The retired file route is refused by name (`status.file-route-retired`) when a caller passes `--path` | `mstar-artifacts` | `0` ok · `1` refusal (no store, not active, unreadable authority) · `2` usage |
| `mstar status tech-debt` | the issue store's open-issue rollup ({HARNESS_DIR}/store.db): total open, by severity, by project. Informational: the store is the source of truth, so there is no stored-summary drift check. A missing, corrupt or staged store refuses — never an empty rollup | `mstar-project-governance` | `0` rollup (zero when the store has no open issues) · `1` project dir or store not readable / resolution failed |
| `mstar status findings-cleanup` | enforces a plan's cleanup mode over the OPEN issues linked to that plan in the issue store, keyed by plan id; an explicit mode wins, otherwise the permissive default. Plans without linked issues pass trivially. A missing, corrupt or staged store refuses instead of passing as no findings | `mstar-artifacts` | `0` no open-issue violations · `1` one row per violating open issue |
| the `store` group — `migrate` | the staged issue/catalog migration: a read-only preview manifest by default (provenance digests, mappings, unresolved rows, catalog conflicts, retirement sections; writes no DB), or the explicit reviewed `--apply` — one transaction with persistent ID mapping and current semantic/path-set checks, not source-byte drift refusal. An applied store stays **staged**: ordinary mutations are refused until activation | `mstar-project-governance` (capture/source mapping), `mstar-conventions` (store authority) | `0` preview or applied · `1` semantic/state/path refusal · `2` usage |
| the `store` group — `backup` / `activate` / `retire` | the store lifecycle: a quiesced SQLite-consistent `VACUUM INTO` backup verified by reopening it; the activation barrier (final apply receipt + compatible-consumer attestation + backup, one transaction flipping authority and epoch); retirement of the exact reviewed legacy registers and index sections under a resumable ledger. **Not read-only rows**: run them only under the recorded authorization, never from a review seat | `mstar-conventions` (store vs execution JSON); `references/status-and-registers.md` § Store lifecycle | `0` done · `1` refusal (stale receipt, missing attestation, legacy write detected) · `2` usage |
| `mstar status workflow-close` | one finished lifecycle: terminal workflow row plus idempotent 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 twice over. It exits `1` and names the replacement: findings are issues in the store now, closed through the plan-scoped or unscoped issue disposition. The residual register it used to touch is migration history | — (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` | the engine-enforced worktree facts. Workflow entry (`--workflow <id> --entry`): recorded branch anchors complete, main-worktree residency, recorded integration checkout exists on its branch and is clean, integration merge-lease state. L1 (per plan): recorded main residency, integration checkout and source metadata checkout/branch, **plus** the workflow's integration merge-lease fact. L2 (`--l2`): parallel writable tracks. Output is scoped to these engine-enforced facts and never implies the full pre-dispatch checklist | `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) have matching semantic field values across the given seat files, accepting the separate and the combined label forms; not serialized file-byte equality | `mstar-branch-worktree` | `0` ok · `1` mismatch or missing field · `2` no files given |
| `mstar worktree cleanup` | `worktree cleanup --workflow <id> [--harness <path>] [--apply] [--remote] [--worktree <path>] [--all-workflows] [--verbose]`: guarded worktree and branch cleanup, default candidates from the selected workflow's recorded claims (`--all-workflows` full sweep; `--worktree` also narrows branch candidates by exact owner; `--verbose` per-pair ancestry diagnostics); dry-run by default printing one verdict row per candidate; ownership / merge-evidence / refusal / apply-order semantics → `mstar-branch-worktree`「Worktree / branch cleanup」 | `mstar-branch-worktree` (call sites: `mstar-iteration` phase-2 same-round + phase-6 post-merge close) | `0` valid dry run or successful removals · `1` probe or mutation failure · `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 workflow row, 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; `--knowledge-dir` adds the document-scope guard and, for the harness-configured knowledge root exactly, the knowledge catalog completeness query. Any other directory — outside that root or a subdirectory of it — is refused (`compound.catalog.knowledge-dir-mismatch`) rather than answered from the configured root's verdict, because completeness proves only the documents registered relative to the configured root, and the retired README index-row check still refuses with `compound.index.retired` — registration belongs to the store catalog, not README rows | `mstar-compound`, `mstar-compound-refresh` | `0` ok · `1` violations / retired index check / catalog or directory refusal · `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` | **not a check — it writes.** `scaffold` writes the run's review report `README.md` for a codebase audit from a findings file, under `{REVIEW_DIR}/<date>-codebase-<level>-<round>/`; `--reviews-dir` overrides the review root, `--dir` the whole run dir (then `--level` / `--round` / `--reviews-dir` are ignored); run it only under the authorization its owning skill names | `mstar-audit` | `0` wrote · `1` failure · `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 (`report-path` defaults to the resolved `{REVIEW_DIR}`; `--reviews-dir` overrides it), 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 lifecycle close and the migration — and `mstar audit scaffold` writes outside any lock when it creates a review report. The retired register verbs from the issue/catalog cutover are deliberately absent here: they parse, refuse and name their issue replacement, so they are not a transport for anything. 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 audit writer, the store-lifecycle rows or the scoped migration 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` (finding `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 issue store; the store 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.