dsh-tower 2.6.0 → 2.7.0

package/scripts/generate-shapes-reference.mjs

@@ -0,0 +1,171 @@
+// Generate the shape reference from the one shape registry (#149).
+//
+// Every fact in docs/reference/shapes.md comes from domain/shapes/index.js and
+// the two shape modules, so documentation cannot drift from the policy the
+// generic layers actually resolve. `--check` is wired into `npm run check`.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { SHAPE_KINDS, shapeFor } from '../domain/shapes/index.js'
+import { RULES } from './shape-audit.mjs'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'shapes.md')
+
+/**
+ * Resolve an audit rule by id. A verdict that names a rule the audit does not
+ * run fails generation, so the reference can never describe an unenforced rule.
+ * @param {string} id
+ */
+function fitness(id) {
+  const rule = RULES.find((entry) => entry.id === id)
+  if (!rule) throw new Error(`unknown shape-audit rule "${id}" named by the shapes reference generator`)
+  return `\`${rule.id}\` — ${rule.rule}`
+}
+
+/** Rule ids as code spans; throws if a verdict names a rule the audit does not run. */
+function rules(...ids) {
+  for (const id of ids) {
+    if (!RULES.some((entry) => entry.id === id)) {
+      throw new Error(`unknown shape-audit rule "${id}" named by the shapes reference generator`)
+    }
+  }
+  return ids.map((id) => `\`${id}\``).join(', ')
+}
+
+const fitnessRules = RULES.map((rule) => `| \`${rule.id}\` | \`${rule.owner}\` | ${rule.rule} |`)
+
+const rows = SHAPE_KINDS.map((kind) => {
+  const shape = shapeFor(kind)
+  const hasTerminal = shape.statuses.some((status) => shape.isTerminal(status))
+  // #148 W2: a shape with a sandbox dimension resolves its placement from
+  // tuning config, so the reference names both placements instead of the static
+  // default only. Both placements render as text: a raw `|` would split the cell.
+  const provisioning = shape.fields.sandbox ? '`shared` / `detached`' : `\`${shape.provisioning}\``
+  return `| \`${kind}\` | \`${shape.statuses.join('`, `')}\` | ${hasTerminal ? 'yes' : 'no'} | ${provisioning} | ${shape.canMerge} | ${shape.canRebase} | ${shape.reach.ownsPaths} / \`${shape.reach.fence}\` | ${shape.requiredComponent ?? '—'} | ${shape.acceptsResult} |`
+})
+
+const transitions = SHAPE_KINDS.map((kind) => {
+  const shape = shapeFor(kind)
+  const body = shape.statuses
+    .map((status) => {
+      const targets = shape.transitions[status] ?? []
+      return `| \`${status}\` | ${shape.isTerminal(status) ? 'terminal' : targets.map((target) => `\`${target}\``).join(', ') || '—'} |`
+    })
+    .join('\n')
+  return `### ${kind}\n\n| From | To |\n|---|---|\n${body}`
+})
+
+const invariants = SHAPE_KINDS.map((kind) => {
+  const { completion } = shapeFor(kind)
+  const flags = Object.entries(completion)
+    .filter(([key]) => key.startsWith('requires'))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(', ')
+  return `| \`${kind}\` | ${flags} | \`${completion.check.name}\` |`
+})
+
+const expected = `# Mission shapes (generated)
+
+> Generated by \`npm run docs:generate:shapes\` from \`domain/shapes/index.js\`. Do not edit by hand.
+
+A mission shape is the single place its kind's contract lives (#148/#149). Generic
+layers resolve \`shapeFor(mission.kind)\` and never branch on a kind literal; the
+shape audit (\`npm run shape:audit\`) refuses kind and role comparisons outside
+\`domain/shapes/\`, the global \`TERMINAL_STATUSES\`/\`TRANSITIONS\` vocabulary,
+one-argument \`isTerminal\`/\`canTransition\` calls, and the dimension regressions
+recorded in the inventory below (review tip, batch status, lease ledger, blocked
+writes, evidence reads, legacy vocabulary, path permission and role/shape
+conflation).
+
+## Kinds
+
+| Kind | Statuses | Has terminal | Provisioning | Can merge | Can rebase | Reach (owns / fence) | Component | Accepts result |
+|---|---|---|---|---|---|---|---|---|
+${rows.join('\n')}
+
+## Transitions
+
+${transitions.join('\n\n')}
+
+## Survey placement (#148 W2)
+
+\`survey.sandbox\` is tuning, not a component: the \`tower-survey\` row stays the
+switch. The shape resolves both the placement and the preset, so generic layers
+never read the raw key or compare a kind.
+
+The decision is made once, at provisioning time. A mission with a recorded
+\`mission.sandbox\` keeps the detached placement and its completion invariants
+even if \`survey.sandbox\` later changes — a config flip can neither skip the
+sandbox HEAD/zero-commit checks nor strand the disposable checkout. A survey
+that never got a sandbox keeps the shared invariants for the same reason.
+
+| \`survey.sandbox\` | Provisioning | Preset | Completion invariants |
+|---|---|---|---|
+| \`none\` (default) | \`shared\`: no checkout, the agent reads the main checkout | \`tower-survey\` (strictly read-only: no write, edit, or shell tool) | HEAD equals \`readCommit\`, tracked-status fingerprint unchanged, zero commits |
+| \`detached\` | \`detached\`: \`git worktree add --detach <worktreeRoot>/<id>-sandbox <readCommit>\` (no branch, no \`baseCommit\`, never merged) | \`tower-survey-sandbox\` (read/write/edit/pwsh plus the mission tools; spawn/merge/rebase/review/diff still absent) | sandbox HEAD equals \`readCommit\`, zero commits; disposable write/shell side effects are ignored; sandbox removed on completion, abandon or teardown with a bounded retry |
+
+## Completion invariants
+
+| Kind | Invariants | Check |
+|---|---|---|
+${invariants.join('\n')}
+
+## Role
+
+| Contract | Owner |
+|---|---|
+| Status, transitions, terminality, merge/rebase, provisioning, reach, plan fields, completion, dependencies, briefing, summary | \`domain/shapes/<kind>.js\` |
+| Kind resolution and the action guard | \`domain/shapes/index.js\` |
+| Role vocabulary and the role contract (preset, model, placement, briefing, prerequisites) | \`domain/roles.js\` |
+| Generated reference and the audit | \`scripts/generate-shapes-reference.mjs\`, \`scripts/shape-audit.mjs\` |
+
+## Dimension inventory (#149)
+
+Every dimension the registry audit covers. A **shape-owned** verdict lives in
+\`domain/shapes/<kind>.js\`; a **correctly generic** verdict has one owner module
+outside the shapes; a **redesigned** verdict replaced an earlier ambiguous
+contract. The fitness rule is the mechanical check the audit (or the generated
+invariant) enforces.
+
+| Dimension | Verdict | Owner module | Fitness rule |
+|---|---|---|---|
+| Mission lifecycle | **Shape-owned.** Statuses, transitions and terminality are per kind. | \`domain/shapes/<kind>.js\` | ${rules('kind-literal', 'global-status-vocabulary', 'shape-entry-point')} |
+| Role vocabulary | **Correctly generic.** Roles are actors, not mission kinds. | \`domain/roles.js\` | ${rules('role-literal')} |
+| Provisioning | **Shape-owned.** A build gets a branch worktree; a survey is shared or a detached sandbox. | \`domain/shapes/<kind>.js\` | Generated invariant: only a build creates a branch/worktree; a recorded \`mission.sandbox\` decides a survey's placement. |
+| Read-only completion | **Shape-owned.** \`resolveCompletion\` derives invariants from the recorded placement. | \`domain/shapes/survey.js\` | Generated invariant: shared survey keeps HEAD and tracked status; detached survey keeps HEAD pinned; both make zero commits. |
+| Dependency | **Shape-owned.** \`dependencySatisfied\` names the terminal statuses that satisfy a dependent. | \`domain/shapes/<kind>.js\` | Generated invariant: a completed survey satisfies a dependent build; a merged build does too. |
+| Archive / reanchor / planning | **Shape-owned.** Terminality is the one archive/reanchor predicate. | \`domain/shapes/<kind>.js\` | Generated invariant: a terminal shape leaves open work and never blocks reanchor. |
+| Completion result | **Shape-owned.** Only a survey may record a completion result. | \`domain/shapes/<kind>.js\` | Generated invariant: \`shape.acceptsResult\`. |
+| Required component | **Shape-owned.** A survey needs the \`tower-survey\` row. | \`domain/shapes/<kind>.js\` | Generated invariant: planning refuses with an actionable code while the required component is off. |
+| Review | **Redesigned.** Commit-stamped evidence: a reviewer reads a disposable checkout at the recorded review commit; only a shape with a branch is reviewable. | \`app/review.js\`, \`app/reviewCheckout.js\`, \`domain/missions/review.js\` | ${fitness('review-tip-read')} |
+| Batch | **Correctly generic second lifecycle.** A batch is finite evidence over missions, not a mission kind; no shape knows about batches. | \`domain/batch.js\`, \`domain/collab/batch.js\`, \`app/batch.js\` | ${fitness('batch-status-literal')} |
+| Leases | **Correctly generic.** One fail-closed admission point; expiry is recovered only by an explicit \`force\` release. | \`adapters/leases.js\`, \`app/spawn-prechecks.js\` | ${fitness('lease-ledger')} |
+| Paused vs blocked | **Redesigned.** \`blocked\` is derived machine state; \`paused\` is a deliberate stop with a cause. | \`domain/missions/lifecycle.js\`, \`domain/state/semantics.js\` | ${fitness('blocked-status-write')} |
+| Test receipts / evidence | **Redesigned — one reader.** Completion checks and discovery receipts are one normalized evidence contract in \`domain/evidence.js\`; the shape declares whether a receipt is tip-bound. \`tower_complete\` no longer copies a synthetic \`tests\` check into the report. | \`domain/evidence.js\`; \`domain/shapes/<kind>.js\` declares \`evidence\` | ${fitness('evidence-single-read')} |
+| Legacy import | **Redesigned — strict adapter.** One payload is one declared format; status remaps, assumed kinds and non-carried fields are reported as \`remapped\`/\`unresolved\`/\`dropped\` instead of approximated. Import stays read-only and never resumes a paused mission. | \`adapters/legacy.js\`; \`domain/batch.js\` reads only the canonical \`pausedMissionIds\` | ${fitness('legacy-vocabulary')} |
+| Scope ownership | **Redesigned — shape.reach.** The shape owns path permission (\`reach.ownsPaths\`, \`reach.fence\`); the gate, planner, lifecycle and auto-deps derive from it through one fence. | \`domain/scope.js\` + \`shape.reach\` in \`domain/shapes/<kind>.js\` | ${fitness('scope-reach')} |
+| Role vs kind | **Redesigned — orthogonal role contract.** Spawn, preset, model, placement, briefing, roster budget and gates resolve the role through \`domain/roles.js\`; the shape only supplies facts. | \`domain/roles.js\`; callers \`tools/spawn.js\`, \`app/spawn-prechecks.js\`, \`app/spawn-support.js\`, \`domain/roster.js\`, \`host/presets.js\` | ${fitness('role-shape-conflation')} |
+
+## Fitness rules
+
+Generated from \`scripts/shape-audit.mjs\` \`RULES\`; the audit is wired into \`npm run check\`.
+
+| Rule | Owner module | Contract |
+|---|---|---|
+${fitnessRules.join('\n')}
+`
+
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('shapes reference is stale; run npm run docs:generate:shapes')
+    process.exit(1)
+  }
+  console.log(`shapes reference: ${SHAPE_KINDS.length} shapes in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${SHAPE_KINDS.length} shapes)`)
+}
+process.exit(0)

package/scripts/mount-smoke/surface.mjs

@@ -36,6 +36,7 @@ export const OPTIONAL_ROW_IDS = [
   'tower-import',
   'tower-leases',
   'tower-skills',
+  'tower-survey',
   'tower-tests',
 ]
 
@@ -67,6 +68,8 @@ export function defaultOffToolIds() {
 export const PRESET_ROWS = Object.freeze([
   Object.freeze({ id: 'tower-worker', specifier: 'preset-worker', name: 'Tower Worker', order: 60 }),
   Object.freeze({ id: 'tower-reviewer', specifier: 'preset-reviewer', name: 'Tower Reviewer', order: 61 }),
+  Object.freeze({ id: 'tower-survey', specifier: 'preset-survey', name: 'Tower Survey', order: 62 }),
+  Object.freeze({ id: 'tower-survey-sandbox', specifier: 'preset-survey-sandbox', name: 'Tower Survey Sandbox', order: 63 }),
 ])
 
 /** Presets the bundle declares for its worker and reviewer roles. */

package/scripts/pack-manifest.txt

@@ -28,6 +28,7 @@ app/briefing.js
 app/checkCompletion.js
 app/enrichedMissions.js
 app/findings.js
+app/freshness.js
 app/gate.js
 app/init.js
 app/merge.js
@@ -40,7 +41,10 @@ app/read.js
 app/rebase.js
 app/recording.js
 app/review.js
+app/reviewCheckout.js
 app/roster.js
+app/sandbox.js
+app/sharedCheckout.js
 app/spawn-prechecks.js
 app/spawn-support.js
 app/spawn.js
@@ -54,6 +58,7 @@ docs/adr/0002-single-state-json.md
 docs/adr/0003-allow-agent-control-default-true.md
 docs/adr/0004-surface-budget.md
 docs/adr/0005-component-surface.md
+docs/adr/0006-mission-shapes.md
 docs/adr/README.md
 docs/agents/domain.md
 docs/agents/issue-tracker.md
@@ -80,6 +85,7 @@ docs/reference/errors.generated.md
 docs/reference/errors.md
 docs/reference/events.md
 docs/reference/operations.md
+docs/reference/shapes.md
 docs/reference/surface-budget.md
 docs/reference/testing.md
 docs/reference/tools.generated.md
@@ -116,6 +122,7 @@ domain/contracts/tool-inputs/missions.js
 domain/contracts/tool-inputs/ops.js
 domain/contracts/tool-inputs/shared.js
 domain/errors.js
+domain/evidence.js
 domain/events.js
 domain/gate.js
 domain/integration/gate.js
@@ -138,8 +145,12 @@ domain/read/enrichedMissions.js
 domain/read/missionContext.js
 domain/read/views.js
 domain/report.js
+domain/roles.js
 domain/roster.js
 domain/scope.js
+domain/shapes/build.js
+domain/shapes/index.js
+domain/shapes/survey.js
 domain/state.js
 domain/state/archive.js
 domain/state/migrations.js
@@ -163,6 +174,8 @@ host/hmr.js
 host/modeState.js
 host/modeStore.js
 host/preset-reviewer.js
+host/preset-survey-sandbox.js
+host/preset-survey.js
 host/preset-worker.js
 host/presets.js
 host/tool-registry.js
@@ -184,6 +197,10 @@ locale/leases/en.json
 locale/leases/zh.json
 locale/preset-reviewer/en.json
 locale/preset-reviewer/zh.json
+locale/preset-survey-sandbox/en.json
+locale/preset-survey-sandbox/zh.json
+locale/preset-survey/en.json
+locale/preset-survey/zh.json
 locale/preset-worker/en.json
 locale/preset-worker/zh.json
 locale/skills/en.json
@@ -219,6 +236,7 @@ scripts/generate-component-surface.mjs
 scripts/generate-config-reference.mjs
 scripts/generate-error-reference.mjs
 scripts/generate-events-reference.mjs
+scripts/generate-shapes-reference.mjs
 scripts/generate-tools-reference.mjs
 scripts/generate-types.mjs
 scripts/issue-audit.mjs
@@ -235,6 +253,7 @@ scripts/pack-manifest.txt
 scripts/regression-audit.mjs
 scripts/release-check.mjs
 scripts/release-notes.mjs
+scripts/shape-audit.mjs
 scripts/surface-baseline.json
 scripts/surface-baseline.mjs
 scripts/types-coverage.mjs
@@ -244,6 +263,8 @@ skills.js
 skills/tower-recovery.md
 skills/tower-review.md
 skills/tower-worker-protocol.md
+survey-sandbox.js
+survey.js
 tools/adopt.js
 tools/batch.js
 tools/complete.js

package/scripts/shape-audit.mjs

@@ -0,0 +1,361 @@
+// Shape audit (#149): one shape registry means generic layers must not branch on
+// a kind or a role, and the old global status vocabulary must not come back.
+//
+// The audit is the ongoing mechanism, not a one-off cleanup: it fails on
+//   - a comparison against a kind literal ('build' | 'survey'),
+//   - a comparison against a role literal ('worker' | 'reviewer' | 'tower'),
+//   - the global TERMINAL_STATUSES / TRANSITIONS identifiers,
+//   - a one-argument isTerminal(...) or one-argument canTransition(...) call,
+//   - reading a review tip from a live worktree HEAD (review evidence is a commit),
+//   - comparing a batch status against a literal outside the batch owner module,
+//   - naming the lease ledger outside the lease adapter,
+//   - reading completion checks / test receipts outside domain/evidence.js,
+//   - the legacy format/status vocabulary outside adapters/legacy.js,
+//   - owning or re-implementing path permission instead of shape.reach + domain/scope.js,
+//   - combining a role decision with a shape decision outside domain/roles.js.
+//
+// Exemptions live in scripts/architecture-waivers.json under `shapeWaivers` and
+// require a reason plus an owner or a ref, exactly like the architecture gate.
+// A waiver with no reason is a contract failure, and a waiver for a path that no
+// longer violates anything is reported as stale.
+//
+// Usage: node scripts/shape-audit.mjs [--root <path>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const WAIVER_FILE = 'scripts/architecture-waivers.json'
+export const WAIVER_KEY = 'shapeWaivers'
+export const SCAN_DIRS = ['domain', 'app', 'tools', 'host', 'adapters', 'ports']
+export const SHAPE_DIR = 'domain/shapes'
+/**
+ * The fitness rules this audit enforces. `docs/reference/shapes.md` is generated
+ * from this list, so a verdict cannot name a rule the audit does not run.
+ */
+export const RULES = [
+  {
+    id: 'kind-literal',
+    rule: 'Generic layers never compare mission.kind with a literal.',
+    owner: 'domain/shapes/<kind>.js',
+  },
+  {
+    id: 'role-literal',
+    rule: 'Generic layers use the vocabulary role predicates, never a role literal.',
+    owner: 'domain/roles.js',
+  },
+  {
+    id: 'global-status-vocabulary',
+    rule: 'No module reaches for the global TERMINAL_STATUSES/TRANSITIONS tables.',
+    owner: 'domain/shapes/<kind>.js',
+  },
+  {
+    id: 'shape-entry-point',
+    rule: 'isTerminal(kind, status) and canTransition(kind, from, to) are the only entry points.',
+    owner: 'domain/shapes/index.js',
+  },
+  {
+    id: 'review-tip-read',
+    rule: 'A review never reads a live worktree HEAD; verdicts are stamped with a recorded commit.',
+    owner: 'app/reviewCheckout.js',
+  },
+  {
+    id: 'batch-status-literal',
+    rule: 'Batch status literals live in domain/batch.js; every other layer uses its constants.',
+    owner: 'domain/batch.js',
+  },
+  {
+    id: 'lease-ledger',
+    rule: 'Only adapters/leases.js reads or writes the lease ledger.',
+    owner: 'adapters/leases.js',
+  },
+  {
+    id: 'blocked-status-write',
+    rule: 'blocked is derived from open blockers; only domain/missions/lifecycle.js writes it.',
+    owner: 'domain/missions/lifecycle.js',
+  },
+  {
+    id: 'evidence-single-read',
+    rule: 'Completion checks and test receipts have one reader: domain/evidence.js.',
+    owner: 'domain/evidence.js',
+  },
+  {
+    id: 'legacy-vocabulary',
+    rule: 'One live vocabulary: legacy formats/statuses are read only by adapters/legacy.js.',
+    owner: 'adapters/legacy.js',
+  },
+  {
+    id: 'scope-reach',
+    rule: 'Path permission derives from shape.reach through domain/scope.js; no module owns or re-implements it.',
+    owner: 'domain/scope.js',
+  },
+  {
+    id: 'role-shape-conflation',
+    rule: 'A role decision never combines with a shape decision; role facts live in domain/roles.js.',
+    owner: 'domain/roles.js',
+  },
+]
+/** Rules whose implementation module necessarily names the vocabulary it owns. */
+export const RULE_EXEMPT_PATHS = {
+  'batch-status-literal': ['domain/batch.js'],
+  'lease-ledger': ['adapters/leases.js'],
+  'blocked-status-write': ['domain/missions/lifecycle.js'],
+  'evidence-single-read': ['domain/evidence.js', 'app/recording.js', 'domain/summary.js', 'domain/state/schema.js'],
+  'legacy-vocabulary': ['adapters/legacy.js'],
+  'scope-reach': ['domain/scope.js'],
+  'role-shape-conflation': ['domain/roles.js'],
+}
+
+const KIND_PATTERN = /(?:\bkind\b\s*[!=]==?\s*['"](?:build|survey)['"])|(?:['"](?:build|survey)['"]\s*[!=]==?\s*\bkind\b)/
+const ROLE_PATTERN = /(?:\brole\b\s*[!=]==?\s*['"](?:worker|reviewer|tower)['"])|(?:['"](?:worker|reviewer|tower)['"]\s*[!=]==?\s*\brole\b)/
+const GLOBAL_VOCAB_PATTERN = /\b(?:TERMINAL_STATUSES|TRANSITIONS)\b/
+const CALL_PATTERN = /(?<!\.)\b(isTerminal|canTransition)\s*\(([^()]*)\)/g
+const REVIEW_TIP_PATTERN = /\brevParse\s*\(\s*[^)]*worktree\.path\s*,\s*['"]HEAD['"]\s*\)/
+const BATCH_STATUS_PATTERN =
+  /(?:\bbatch\.status\s*[!=]==?\s*['"](?:open|closed|abandoned|created|active|pending)['"])|(?:['"](?:open|closed|abandoned|created|active|pending)['"]\s*[!=]==?\s*\bbatch\.status\b)/
+const LEASE_LEDGER_PATTERN = /['"](?:leases\.json|leases\.json\.lock|leases\.lock)['"]/
+const BLOCKED_WRITE_PATTERN = /(?:\bstatus\s*=\s*['"]blocked['"])|(?:['"]status['"]\s*:\s*['"]blocked['"])/
+const EVIDENCE_READ_PATTERN = /\bmission\.testRuns\b|\btestRuns\s*[.[]|completionReport\?\.checks|completionReport\.checks/
+const LEGACY_VOCABULARY_PATTERN = /\btower-codex\b|\bpausedIds\b|\bCODEX_(?:STATUSES|ID_RE)\b/
+const SCOPE_FENCE_PATTERN = /\bownsScope\b|\bfileInScope\s*\(/
+const ROLE_SHAPE_PATTERN = /\b(?:isWorkerRole|isReviewerRole|isTowerRole)\s*\(|\bROLE\.(?:worker|reviewer|tower)\b/
+const SHAPE_DECISION_PATTERN = /\bshapeFor\s*\(|\bshape\s*[.[]/
+
+/**
+ * Count top-level arguments in a call's argument text.
+ * @param {string} args
+ * @returns {number}
+ */
+function argumentCount(args) {
+  const trimmed = args.trim()
+  if (trimmed.length === 0) return 0
+  let depth = 0
+  let count = 1
+  for (const char of trimmed) {
+    if (char === '(' || char === '[' || char === '{') depth += 1
+    else if (char === ')' || char === ']' || char === '}') depth -= 1
+    else if (char === ',' && depth === 0) count += 1
+  }
+  return count
+}
+
+/**
+ * @param {string} source
+ * @returns {Array<{ rule: string, detail: string }>}
+ */
+export function inspectSource(source) {
+  const violations = []
+  const lines = source.split('\n')
+  lines.forEach((line, index) => {
+    const at = `line ${index + 1}`
+    const trimmed = line.trim()
+    // Documentation may quote the vocabulary it forbids; only code counts.
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) return
+    if (KIND_PATTERN.test(line)) {
+      violations.push({ rule: 'kind-literal', detail: `${at}: ${line.trim()} — resolve shapeFor(mission.kind) instead` })
+    }
+    if (ROLE_PATTERN.test(line)) {
+      violations.push({ rule: 'role-literal', detail: `${at}: ${line.trim()} — use the vocabulary role predicates instead` })
+    }
+    if (GLOBAL_VOCAB_PATTERN.test(line)) {
+      violations.push({ rule: 'global-status-vocabulary', detail: `${at}: ${line.trim()} — use shape.isTerminal(status) / shape.transitions` })
+    }
+    if (REVIEW_TIP_PATTERN.test(line)) {
+      violations.push({
+        rule: 'review-tip-read',
+        detail: `${at}: ${line.trim()} — stamp reviews with a recorded commit (tower.branchTip(mission)) instead of a live worktree HEAD`,
+      })
+    }
+    if (BATCH_STATUS_PATTERN.test(line)) {
+      violations.push({
+        rule: 'batch-status-literal',
+        detail: `${at}: ${line.trim()} — use BATCH_STATUS / canTransitionBatch from domain/batch.js`,
+      })
+    }
+    if (LEASE_LEDGER_PATTERN.test(line)) {
+      violations.push({
+        rule: 'lease-ledger',
+        detail: `${at}: ${line.trim()} — the lease ledger is owned by adapters/leases.js`,
+      })
+    }
+    if (BLOCKED_WRITE_PATTERN.test(line)) {
+      violations.push({
+        rule: 'blocked-status-write',
+        detail: `${at}: ${line.trim()} — blocked is derived from open blockers: use markBlocked(mission, text)`,
+      })
+    }
+    if (EVIDENCE_READ_PATTERN.test(line)) {
+      violations.push({
+        rule: 'evidence-single-read',
+        detail: `${at}: ${line.trim()} — read evidence through domain/evidence.js (findEvidence/passingDiscovery/hasCheckEvidence)`,
+      })
+    }
+    if (LEGACY_VOCABULARY_PATTERN.test(line)) {
+      violations.push({
+        rule: 'legacy-vocabulary',
+        detail: `${at}: ${line.trim()} — legacy formats/statuses are normalised by adapters/legacy.js; do not introduce a second vocabulary`,
+      })
+    }
+    if (SCOPE_FENCE_PATTERN.test(line)) {
+      violations.push({
+        rule: 'scope-reach',
+        detail: `${at}: ${line.trim()} — path permission is shape.reach through scopeFenceBlocker(); no ownsScope flag or direct matcher`,
+      })
+    }
+    if (ROLE_SHAPE_PATTERN.test(line) && SHAPE_DECISION_PATTERN.test(line)) {
+      violations.push({
+        rule: 'role-shape-conflation',
+        detail: `${at}: ${line.trim()} — resolve the role through domain/roles.js; the shape supplies facts, not role branches`,
+      })
+    }
+    for (const match of line.matchAll(CALL_PATTERN)) {
+      const expected = match[1] === 'isTerminal' ? 2 : 3
+      if (argumentCount(match[2]) < expected) {
+        violations.push({
+          rule: 'shape-entry-point',
+          detail: `${at}: ${match[0]} — the only entry points are isTerminal(kind, status) and canTransition(kind, from, to)`,
+        })
+      }
+    }
+  })
+  return violations
+}
+
+/**
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walk(start) {
+  const files = []
+  if (!fs.existsSync(start)) return files
+  for (const entry of fs.readdirSync(start, { withFileTypes: true })) {
+    const full = path.join(start, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      files.push(...walk(full))
+    } else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) {
+      files.push(full)
+    }
+  }
+  return files
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ path: string, rule: string, detail: string }[]}
+ */
+export function scan(repoRoot) {
+  const results = []
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(repoRoot, dir))) {
+      const relative = path.relative(repoRoot, file).split(path.sep).join('/')
+      if (relative.startsWith(`${SHAPE_DIR}/`)) continue
+      const source = fs.readFileSync(file, 'utf8')
+      for (const violation of inspectSource(source)) {
+        const exempt = RULE_EXEMPT_PATHS[violation.rule] ?? []
+        if (exempt.includes(relative)) continue
+        results.push({ path: relative, ...violation })
+      }
+    }
+  }
+  return results
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ waivers: Array<{ rule?: string, path?: string, reason?: string, owner?: string, ref?: string, match?: string }>, errors: string[] }}
+ */
+export function loadShapeWaivers(repoRoot) {
+  const file = path.join(repoRoot, WAIVER_FILE)
+  if (!fs.existsSync(file)) return { waivers: [], errors: [`${WAIVER_FILE}: missing`] }
+  let document
+  try {
+    document = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    return { waivers: [], errors: [`${WAIVER_FILE}: not valid JSON (${String(error?.message ?? error)})`] }
+  }
+  const entries = document?.[WAIVER_KEY] ?? []
+  if (!Array.isArray(entries)) return { waivers: [], errors: [`${WAIVER_FILE}: ${WAIVER_KEY} must be an array`] }
+  const errors = []
+  for (const [index, entry] of entries.entries()) {
+    const where = `${WAIVER_FILE} ${WAIVER_KEY}[${index}]`
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${where}: must be an object`)
+      continue
+    }
+    if (typeof entry.rule !== 'string' || entry.rule.length === 0) errors.push(`${where}: rule is required`)
+    if (typeof entry.path !== 'string' || entry.path.length === 0) errors.push(`${where}: path is required`)
+    if (typeof entry.reason !== 'string' || entry.reason.length === 0) errors.push(`${where}: reason is required`)
+    if (!entry.owner && !entry.ref) errors.push(`${where}: owner or ref is required`)
+  }
+  return { waivers: errors.length === 0 ? entries : [], errors }
+}
+
+/**
+ * @param {{ path: string, rule: string, detail: string }[]} violations
+ * @param {Array<{ rule?: string, path?: string, match?: string }>} waivers
+ * @returns {{ violations: typeof violations, waived: typeof violations, unused: Array<{ rule?: string, path?: string }> }}
+ */
+export function applyWaivers(violations, waivers) {
+  const waived = []
+  const used = new Set()
+  const remaining = []
+  for (const violation of violations) {
+    const index = waivers.findIndex((waiver) => {
+      if (waiver.path !== violation.path) return false
+      if (waiver.rule !== violation.rule) return false
+      if (waiver.match && !violation.detail.includes(waiver.match)) return false
+      return true
+    })
+    if (index >= 0) {
+      used.add(index)
+      waived.push(violation)
+    } else {
+      remaining.push(violation)
+    }
+  }
+  const unused = waivers.filter((_, index) => !used.has(index))
+  return { violations: remaining, waived, unused }
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {{ ok: boolean, violations: any[], waived: any[], errors: string[], unused: any[] }}
+ */
+export function evaluator(repoRoot = root) {
+  const reported = []
+  const waivers = loadShapeWaivers(repoRoot)
+  if (waivers.errors.length > 0) return { ok: false, violations: [], waived: [], errors: waivers.errors, unused: [] }
+  const applied = applyWaivers(scan(repoRoot), waivers.waivers)
+  for (const violation of applied.violations) {
+    reported.push(`shape-audit error: [${violation.rule}] ${violation.path} ${violation.detail}`)
+  }
+  if (applied.unused.length > 0) {
+    for (const waiver of applied.unused) {
+      reported.push(`shape-audit error: [stale-waiver] ${waiver.path} ${waiver.rule} no longer matches a violation; remove it`)
+    }
+  }
+  return {
+    ok: reported.length === 0,
+    violations: applied.violations,
+    waived: applied.waived,
+    errors: reported,
+    unused: applied.unused,
+  }
+}
+
+function main(argv) {
+  const rootIndex = argv.indexOf('--root')
+  const repoRoot = rootIndex >= 0 ? path.resolve(argv[rootIndex + 1]) : root
+  const result = evaluator(repoRoot)
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  } else if (result.ok) {
+    process.stdout.write(`shape-audit: ok (waived: ${result.waived.length})\n`)
+  } else {
+    for (const line of result.errors) process.stderr.write(`${line}\n`)
+  }
+  process.exitCode = result.ok ? 0 : 1
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2))