@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/cli/commands/next.ts

@@ -3,12 +3,24 @@
  *
  * The next step is derived from what the project HOLDS, not from which command just ran, so a
  * session cannot lose the thread by finishing somewhere that has no footer of its own (#597).
+ *
+ *   sungen next [unit]                every unit (or one), unit-level steps; test-case work folds
+ *                                     into one line per node ("N test case(s) …")
+ *   sungen next <unit> --case <id>    one test case: its state, and its steps after the blocking
+ *                                     unit steps before them (OES-10.3)
+ *   --json                            the same, machine-readable; steps add nodeId, granularity,
+ *                                     testCase?, gates?; every older field is kept. stdout is the
+ *                                     payload alone (#660, #836)
  */
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as path from 'path';
-import { readUnitState, UnitState } from '../../harness/next-step';
+import { CLI_GIT_TIMEOUT_MS, headSnapshot } from '../../contract/contract-git';
+import { testCaseStatusLabel } from '../../graph/test-case-satisfied';
+import { testCaseStates } from '../../graph/test-case-states';
+import { deriveSteps, NextStep, readUnitState, UnitState } from '../../harness/next-step';
 import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+import { withProjectInvocation } from '../project-sungen-invocation';
 
 /** Every unit the project holds, so `sungen next` with no argument still answers. */
 function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
@@ -24,7 +36,16 @@ function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; d
   return out;
 }
 
-function render(s: UnitState): void {
+/** Steps as text, each `sungen …` command as this project runs it (#939); `--json` keeps them canonical. */
+function renderSteps(steps: NextStep[], cwd: string): void {
+  for (const st of steps) {
+    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
+    console.log(`  ${mark} ${withProjectInvocation(st.command, cwd)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
+    console.log(`     ${st.because}`);
+  }
+}
+
+function render(s: UnitState, cwd: string): void {
   const L = console.log;
   L('');
   L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
@@ -38,12 +59,40 @@ function render(s: UnitState): void {
   ].filter(Boolean);
   L(`  state: ${held.length ? held.join(' · ') : '(nothing yet)'}`);
   if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
+  else if (s.auditNotCounted) L(`  audit: ${s.auditNotCounted.state === 'stale' ? 'stale' : 'not trusted'} — ${s.auditNotCounted.reason}`);
   L('');
-  for (const st of s.steps) {
-    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
-    L(`  ${mark} ${st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
-    L(`     ${st.because}`);
+  renderSteps(s.steps, cwd);
+  L('');
+}
+
+/** `--case <id>`: the case's state and its frontier. Exits 1 when the case cannot be found. */
+function caseView(s: UnitState, cwd: string, unitDir: string, id: string, json: boolean): void {
+  let cases = s.testCases;
+  if (!cases) {
+    try { cases = testCaseStates(cwd, s.unit, { unitDir }); } catch (e) {
+      throw new Error(`the test cases of ${s.unit} could not be read: ${e instanceof Error ? e.message : e}`);
+    }
   }
+  const tc = cases.find((c) => c.id === id);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${id}" in ${s.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ' (it holds no scenario)'}`);
+  }
+  const steps = deriveSteps({ ...s, testCases: cases }, { testCase: id });
+  if (json) { console.log(JSON.stringify({ unit: s.unit, kind: s.kind, testCase: tc, steps }, null, 2)); return; }
+  const L = console.log;
+  L('');
+  L(`━━━ Next steps: ${s.unit} › ${tc.id} (${s.kind}) ━━━`);
+  L('');
+  L(`  test case: ${tc.title}${tc.unstableId ? '   (no VP-id — this id changes when the title does)' : ''}`);
+  L(`  where:     ${tc.file}#L${tc.lines[0]}-L${tc.lines[1]}`);
+  L(`  status:    ${testCaseStatusLabel(tc)} · result ${tc.result}${tc.mocked && tc.result === 'passed' ? ' (mocked)' : ''}${tc.stale ? ` · stale: ${tc.stale}` : ''}${tc.triage ? ` · triage ${tc.triage.class}` : ''}`);
+  if (tc.contract) L(`  contract:  ${tc.contract.class}${tc.contract.uncommitted ? ' · lock entry not committed' : ''}${tc.contract.lowIdentity ? ' · low target identity' : ''}`);
+  if (tc.anchors.length) L(`  anchors:   ${tc.anchors.map((a) => `${a.anchor} (${a.change})`).join(', ')}`);
+  for (const f of tc.findings) L(`  finding:   ${f.code} [${f.confidence.label} ${f.confidence.score}] ${f.citation}`);
+  L('');
+  if (steps.length) renderSteps(steps, cwd);
+  else L(`  ✓ nothing to do for this test case — ${testCaseStatusLabel(tc)}`);
   L('');
 }
 
@@ -51,10 +100,13 @@ export function registerNextCommand(program: Command): void {
   program
     .command('next [unit]')
     .description('What to do next for a unit (or every unit), derived from the project state')
+    .option('--case <id>', 'One test case of the unit (its VP-id): its state and its next steps')
     .option('--json', 'Machine-readable output')
-    .action((unit: string | undefined, o: { json?: boolean }) => {
+    .action((unit: string | undefined, o: { json?: boolean; case?: string }) => {
       try {
         const cwd = process.cwd();
+        if (o.case && !unit) throw new Error('--case needs a unit: sungen next <unit> --case <id>');
+        const gitSnapshot = headSnapshot(cwd, CLI_GIT_TIMEOUT_MS);
         let states: UnitState[];
         if (unit) {
           const resolved = resolveUnit(unit, cwd);
@@ -62,7 +114,9 @@ export function registerNextCommand(program: Command): void {
             console.error(`Error: no unit named "${unit}" under qa/screens, qa/flows or qa/api.`);
             process.exit(1);
           }
-          states = [readUnitState(cwd, resolved.dir, unit, resolved.kind)];
+          const state = readUnitState(cwd, resolved.dir, unit, resolved.kind, { gitSnapshot });
+          if (o.case) { caseView(state, cwd, resolved.dir, o.case, Boolean(o.json)); return; }
+          states = [state];
         } else {
           const units = allUnits(cwd);
           if (units.length === 0) {
@@ -72,14 +126,14 @@ export function registerNextCommand(program: Command): void {
           // A name in two places is ambiguous; report it rather than answering for one of them.
           states = units.map((u) => {
             if (resolveUnitCandidates(u.name, cwd).length > 1) throw new AmbiguousUnitError(u.name, resolveUnitCandidates(u.name, cwd));
-            return readUnitState(cwd, u.dir, u.name, u.kind);
+            return readUnitState(cwd, u.dir, u.name, u.kind, { gitSnapshot });
           });
         }
         if (o.json) {
           console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
           return;
         }
-        for (const s of states) render(s);
+        for (const s of states) render(s, cwd);
       } catch (e) {
         console.error(`Error: ${e instanceof Error ? e.message : e}`);
         process.exit(1);

package/src/cli/commands/triage.ts

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import { resolveUnit } from '../resolve-unit';
+import { triageUnit, writeTriageReport } from '../../harness/triage-unit';
+import type { TriageClass } from '../../harness/triage';
+
+/** Display order: what needs a decision first, green last. */
+const ORDER: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'blocked-capability', 'known-defect', 'flaky'];
+
+/**
+ * `sungen triage` — classify every red or flaky scenario of the latest run (see harness/triage.ts).
+ * Reports, never gates: always exits 0 once the unit is found.
+ */
+export function registerTriageCommand(program: Command): void {
+  program
+    .command('triage')
+    .description('Classify each red or flaky scenario of the latest run: known-defect, blocked, environment, test-defect, product-candidate, unclassified')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api')
+    .option('--json', 'Output the raw JSON report')
+    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const cwd = process.cwd();
+        const unit = resolveUnit(name, cwd);
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = triageUnit(cwd, unit);
+        if (report.resultFiles.length === 0) {
+          if (o.json) console.log(JSON.stringify(report, null, 2));
+          else console.log(`\n  ${name}: no results — run the tests first.\n`);
+          return;
+        }
+        const saved = writeTriageReport(cwd, report);
+        if (o.json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Triage: ${name} ━━━`);
+        if (report.rows.length === 0) L('  ✓ every scenario passed on its first attempt');
+        for (const cls of ORDER) {
+          const rows = report.rows.filter((r) => r.class === cls);
+          if (rows.length === 0) continue;
+          L(`\n  ${cls} (${rows.length})`);
+          for (const r of rows) {
+            L(`    • ${r.scenario}${r.variant ? ` [${r.variant}]` : ''}${r.defectId ? ` → ${r.defectId}` : ''}`);
+            L(`      ${r.ruleId}: ${r.evidence}`);
+          }
+        }
+        L(`\n  Report: ${path.relative(cwd, saved)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -41,7 +41,7 @@ export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
     .description(
-      'Reinstall @sun-asterisk/sungen (stable by default, --beta for prerelease) + refresh AI rules, commands, skills',
+      'Reinstall @sun-asterisk/sungen (stable by default, --beta / --alpha for prerelease) + refresh AI rules, commands, skills',
     )
     .option('--dry-run', 'Show what would be updated without making changes')
     .option(
@@ -56,9 +56,19 @@ export function registerUpdateCommand(program: Command): void {
       'Switch to the BETA channel (installs @beta — prerelease builds for testing)',
       false,
     )
+    // `--beta --alpha` is ambiguous: commander refuses it while parsing — one usage-error line, exit 1,
+    // before the action (and any npm install) runs — rather than settling it by flag order.
+    .addOption(
+      new Option(
+        '--alpha',
+        'Switch to the ALPHA channel (installs @alpha — early builds of the next big update, ahead of beta)',
+      )
+        .default(false)
+        .conflicts('beta'),
+    )
     .option(
       '--tag <dist-tag>',
-      'Install a specific npm dist-tag (e.g. latest, beta, next). Overrides --beta.',
+      'Install a specific npm dist-tag (e.g. latest, beta, alpha, next). Overrides --beta / --alpha.',
     )
     .option(
       '--skip-npm-install',
@@ -70,16 +80,14 @@ export function registerUpdateCommand(program: Command): void {
       'Skip reinstalling the project-local sungen packages (AI assets only — leaves node_modules stale)',
       false,
     )
-    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean; skipProject?: boolean; assistant?: string[]; force?: boolean }) => {
+    .action(async (options: { dryRun?: boolean; beta?: boolean; alpha?: boolean; tag?: string; skipNpmInstall?: boolean; skipProject?: boolean; assistant?: string[]; force?: boolean }) => {
       try {
         const skipNpm =
           Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
         const skipProject =
           Boolean(options.skipProject) || process.env[SKIP_PROJECT_ENV] === '1';
 
-        // Channel resolution via npm dist-tags. Default `latest` = official/stable.
-        // `--beta` → beta channel; running plain `sungen update` later switches back to stable.
-        const channel = options.tag || (options.beta ? 'beta' : 'latest');
+        const channel = resolveUpdateChannel(options);
 
         if (!skipNpm) {
           reinstallSungen(channel);
@@ -106,6 +114,13 @@ export function registerUpdateCommand(program: Command): void {
         // …and move the old `trace: 'on-first-retry'` default, which never records a trace off CI.
         const { installTraceMode } = require('../../orchestrator/trace-mode-install');
         installTraceMode(process.cwd(), options.dryRun ?? false);
+        // Claude Code hooks: re-merged into .claude/settings.json (user hooks kept); sungen entries a
+        // newer version dropped, or qa/sungen.config.yaml turned off, are removed.
+        if (resolveAssistants(options.assistant).includes('claude')) {
+          const { installClaudeHooks, describeHooksInstall } = require('../../orchestrator/claude-hooks-install');
+          const hooks = installClaudeHooks(process.cwd(), { dryRun: options.dryRun ?? false });
+          console.log(`${hooks.settings === 'unreadable' ? '⚠️ ' : '🪝'} ${options.dryRun ? '[dry-run] ' : ''}${describeHooksInstall(hooks)}\n`);
+        }
       } catch (error) {
         console.error('❌ Update failed:', error);
         process.exit(1);
@@ -113,6 +128,18 @@ export function registerUpdateCommand(program: Command): void {
     });
 }
 
+/**
+ * The npm dist-tag `sungen update` installs. `latest` = official/stable (the default, and how a
+ * plain `sungen update` switches back); `--beta` / `--alpha` pick a prerelease channel (each branch
+ * auto-publishes to the dist-tag of its name); `--tag` names any dist-tag and wins over both.
+ * `--beta` with `--alpha` never reaches here — the option definition refuses the pair.
+ */
+export function resolveUpdateChannel(o: { tag?: string; beta?: boolean; alpha?: boolean }): string {
+  if (o.tag) return o.tag;
+  if (o.alpha) return 'alpha';
+  return o.beta ? 'beta' : 'latest';
+}
+
 function reinstallSungen(channel: string): void {
   const spec = `@sun-asterisk/sungen@${channel}`;
   const label = channel === 'latest' ? 'stable (latest)' : `${channel} channel`;
@@ -139,7 +166,7 @@ function printCurrentVersion(channel: string): void {
     spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
   }
   if (channel === 'latest') {
-    console.log('   Channel: stable. To try prereleases:  sungen update --beta');
+    console.log('   Channel: stable. To try prereleases:  sungen update --beta  (or --alpha for the next big update)');
   } else {
     console.log(`   Channel: ${channel} (prerelease). To return to stable:  sungen update`);
   }

package/src/cli/index.ts

@@ -37,16 +37,28 @@ import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
 import { registerContextCommand } from './commands/context';
 import { registerRepairCommand } from './commands/repair';
+import { registerTriageCommand } from './commands/triage';
+import { registerDefectCommand } from './commands/defect';
 import { registerResultsCommand } from './commands/results-merge';
 import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { warnAssetsDrift } from '../orchestrator/assets-drift';
+import { attachCliHandBack } from '../hooks/hand-back-core';
+import { registerHookCommand } from '../hooks/hook-cli-command';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
 
 async function main() {
+  // #597 + P0.1 — the hand-back, once, for EVERY command, and from the moment parsing starts: a
+  // usage error never reaches an action, and `main().catch` exits from outside one. It hangs off
+  // process exit (not postAction) because several commands exit with a MEANINGFUL code that skips
+  // commander's hooks (`depth-lint` → 2). It points at `sungen next` instead of restating a step,
+  // so it cannot drift from the project state. A failure prints it on stderr after the error;
+  // `--json`/`--grep` keep it off stdout (#836); `hook` never prints one, `next` only when it fails (#937). The line and
+  // those rules live in the hook core (src/hooks/hand-back-core.ts) — this file only wires it.
+  const handBack = attachCliHandBack(process.argv, process.cwd());
   const program = new Command();
 
   program
@@ -89,10 +101,16 @@ registerSetupMobileEnvCommand(program);
   registerFlowCheckCommand(program);
   registerContextCommand(program);
   registerRepairCommand(program);
+  registerTriageCommand(program);
+  registerDefectCommand(program);
   registerResultsCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
   registerLoginCommand(program);
+  // Test Contract (DOS-14). Registered inline (typed require, still loaded eagerly like every command)
+  // so the phase that added it touches ONE line of this file — no import-block edit to merge-conflict.
+  (require('./commands/contract') as typeof import('./commands/contract')).registerContractCommand(program);
+  registerHookCommand(program); // hidden: Claude Code hooks, JSON on stdout
 
   // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
   // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
@@ -104,38 +122,14 @@ registerSetupMobileEnvCommand(program);
   // Every command warns once when the project's AI assets came from a different
   // build — `update` is the only thing that refreshes them, and nothing used to
   // say so (stderr, so `--json` output stays parseable).
-  program.hook('preAction', () => { warnAssetsDrift(process.cwd()); });
-
-  // #597 — the hand-back, once, for EVERY command. It used to be hardcoded per command and only
-  // two of twenty-nine printed one, so a run that finished anywhere else finished in silence:
-  // `capability add` ended with a blank line and the session stopped mid-workflow. Adding a
-  // footer to the other twenty-seven would repeat the mistake in bulk.
-  //
-  // It hangs off `process.on('exit')` rather than a postAction hook because several commands
-  // exit with a MEANINGFUL code (`depth-lint` returns 2 when there are deepen candidates) and
-  // `process.exit` skips commander's hooks entirely — a postAction version printed for `audit`
-  // and silently not for `depth-lint`, which is the same class of gap all over again.
-  //
-  // It points at `sungen next` instead of restating a step, so it can never drift from the real
-  // project state. Skipped on a hard error (code 1): there the error message is the actionable
-  // thing, and burying it under a footer helps nobody. `--json` keeps stdout parseable.
-  let handBack: { unit?: string; json: boolean } | null = null;
+  // `hook` speaks only JSON to Claude Code — no drift warning there.
   program.hook('preAction', (_thisCommand, actionCommand) => {
-    if (actionCommand.name() === 'next') return;            // `next` IS the answer
-    const opts = actionCommand.opts() as Record<string, unknown>;
-    const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
-      ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
-    // `--grep` is machine output too: callers capture it with `$(…)`, and a footer on stdout
-    // became part of the regex — the last alternative of `changed --grep` silently matched
-    // nothing, so `--change-only` skipped its last scenario (#836).
-    handBack = { unit: unit as string | undefined, json: opts.json === true || opts.grep === true };
+    if (actionCommand.name() !== 'hook') warnAssetsDrift(process.cwd());
   });
-  process.on('exit', (code) => {
-    if (!handBack || code === 1) return;
-    const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
-    // stderr under --json / --grep so the hand-back never lands in the captured payload.
-    if (handBack.json) process.stderr.write(`${line}\n`);
-    else process.stdout.write(`${line}\n`);
+
+  // The action knows its unit and output mode; the hand-back default above is refined here.
+  program.hook('preAction', (_thisCommand, actionCommand) => {
+    handBack.onAction(actionCommand.name(), actionCommand.opts() as Record<string, unknown>, actionCommand.args);
   });
 
   await program.parseAsync(process.argv);

package/src/cli/project-sungen-invocation.ts

@@ -0,0 +1,39 @@
+/**
+ * How a hint names sungen inside a project (#939, items 1–2).
+ *
+ * A project that installs its own sungen (`npm i -D @sun-asterisk/sungen`) runs it with `npx sungen`;
+ * a bare `sungen` is whatever global install the machine has — in the field test an older 3.2.24-beta
+ * beside the project's 3.3.0-alpha. And `sungen update` without a flag switches to the stable
+ * channel, so on an alpha or beta install the update hint must keep the channel it runs on.
+ *
+ *   sungenInvocation(root)          'npx sungen' when <root>/node_modules/@sun-asterisk/sungen exists, else 'sungen'
+ *   withProjectInvocation(cmd, root) a canonical `sungen …` command as this project runs it
+ *   updateCommand(root, version?)   `<invocation> update` plus `--alpha` / `--beta` (`--tag <id>` for another prerelease)
+ *
+ * Only the project root itself is looked at — where `npm i` puts a QA project's install — so a
+ * monorepo checkout above a fixture does not turn its hints into `npx`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from '../exporters/package-info';
+
+export function sungenInvocation(projectRoot: string): string {
+  return fs.existsSync(path.join(projectRoot, 'node_modules', '@sun-asterisk', 'sungen', 'package.json')) ? 'npx sungen' : 'sungen';
+}
+
+/** `sungen audit --screen x` → `npx sungen audit --screen x` in a project with its own install; anything else unchanged. */
+export function withProjectInvocation(command: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv !== 'sungen' && /^sungen\b/.test(command) ? `${inv}${command.slice('sungen'.length)}` : command;
+}
+
+/** The `sungen update` flag that keeps the channel of `version` (its prerelease id); '' for stable. */
+export function updateChannelFlag(version: string = getPackageVersion()): string {
+  const id = version.match(/^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/)?.[1];
+  if (!id) return '';
+  return id === 'alpha' || id === 'beta' ? ` --${id}` : ` --tag ${id}`;
+}
+
+export function updateCommand(projectRoot: string, version: string = getPackageVersion()): string {
+  return `${sungenInvocation(projectRoot)} update${updateChannelFlag(version)}`;
+}

package/src/contract/approve-contract.ts

@@ -0,0 +1,94 @@
+/**
+ * `sungen contract approve --screen <u> [--scenario <id>]` — the human act that locks a contract
+ * (DOS-14.4, DOS-13.4, takumi T5). In order, so a human never confirms something then rejected:
+ *
+ *   1. resolve the unit, read the current scenarios and the lock (an unreadable lock refuses)
+ *   2. pick what changes: new, changed or tampered scenarios, and — when approving the whole unit —
+ *      the entries of scenarios that left the feature; nothing changed → nothing to approve, no prompt
+ *   3. refuse a duplicated id or a Scenario Outline, and run the secret guard
+ *   4. show each change with its ladder class (a weakening is named before it is confirmed) and
+ *      require the typed phrase on a TTY — without one: refuse and print the exact command
+ *   5. read everything AGAIN: if the feature or the lock moved while the human was reading, what
+ *      they confirmed is not what would be written — refuse (L5)
+ *   6. record the decision and the lock (record-contract-approval.ts)
+ */
+import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import { gitUserName } from '../decisions/decision-source';
+import { classifyScenario } from './classify-contract-change';
+import { canonicalJson } from './contract-hash';
+import { ContractScenario, isHumanApproved } from './contract-schema';
+import { resolveContractUnit } from './contract-units';
+import { lockPathFor, ReadLock, readLockFile } from './contracts-lock-file';
+import { dropProposedTags } from './free-feature-blocks';
+import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
+import { ApprovalWrite, checkApprovalSecrets, recordContractApproval } from './record-contract-approval';
+
+export interface ApproveInput { projectRoot: string; unit: string; scenario?: string; reason?: string; io: ConfirmationIO }
+export interface ApproveResult {
+  status: 'approved' | 'nothing-to-approve';
+  lockPath: string;
+  decisionId?: string;
+  approved: string[];
+  removed: string[];
+}
+
+interface Plan { write: ApprovalWrite; lock: ReadLock | null; fingerprint: string }
+
+function plan(i: ApproveInput): Plan {
+  const unit = resolveContractUnit(i.projectRoot, i.unit);
+  const lock = readLockFile(lockPathFor(unit.dir));
+  const current = loadContractScenarios(unit.dir, unit.name);
+  const ids = new Set(current.map((s) => s.id));
+  if (i.scenario && !ids.has(i.scenario) && !lock?.scenarios[i.scenario]) {
+    throw new Error(`--scenario ${i.scenario} names no scenario of ${i.unit} (current: ${[...ids].join(', ') || 'none'})`);
+  }
+  const chosen = current.filter((s) => !i.scenario || s.id === i.scenario);
+  const dup = [...new Set(chosen.map((s) => s.id))].find((id) => current.filter((s) => s.id === id).length > 1);
+  if (dup) throw new Error(`Refused: scenario id ${dup} is used by ${current.filter((s) => s.id === dup).length} scenarios — a lock entry must name exactly one. Give each its own ID.`);
+  const outlines = chosen.filter((s) => s.source.outline).map((s) => s.id);
+  if (outlines.length) throw new Error(`Refused: ${outlines.join(', ')} ${outlines.length > 1 ? 'are' : 'is a'} Scenario Outline — the compiler does not support it, so it cannot be locked. Rewrite it as @cases data.`);
+  const tampered = new Set(lock?.tampered ?? []);
+  const approve = chosen.filter((s) => { const e = lock?.scenarios[s.id]; return !isHumanApproved(e) || e.hash !== s.hash || tampered.has(s.id); });
+  const removed = Object.keys(lock?.scenarios ?? {}).filter((id) => !ids.has(id) && (!i.scenario || id === i.scenario));
+  const write: ApprovalWrite = { projectRoot: i.projectRoot, unitDir: unit.dir, unit: unit.name, approve, removed, reason: i.reason, lock };
+  return { write, lock, fingerprint: canonicalJson({ lock, approve: approve.map((s) => [s.id, s.hash]), removed }) };
+}
+
+function describe(sc: ContractScenario, lock: ReadLock | null): string {
+  const entry = lock?.scenarios[sc.id];
+  if (!isHumanApproved(entry) || lock?.tampered.includes(sc.id)) return `+ ${sc.id}  new (${sc.steps.length} steps, ${sc.implementation})`;
+  const r = classifyScenario(sc.id, entry, sc);
+  return `~ ${sc.id}  ${r.class}${r.findings.length ? ` — ${r.findings.map((f) => f.detail).join('; ')}` : ''}`;
+}
+
+export async function approveContract(i: ApproveInput): Promise<ApproveResult> {
+  const before = plan(i);
+  const { approve, removed } = before.write;
+  const lockPath = lockPathFor(before.write.unitDir);
+  if (!approve.length && !removed.length) return { status: 'nothing-to-approve', lockPath, approved: [], removed: [] };
+  checkApprovalSecrets(before.write);
+
+  const unnamed = approve.filter((s) => !s.source.hasId).length;
+  await requireTypedConfirmation({
+    what: `approve the Test Contract of ${i.unit} (${approve.length} scenario(s)${removed.length ? `, ${removed.length} removed` : ''})`,
+    phrase: i.unit,
+    command: formatCommand(['sungen', 'contract', 'approve', '--screen', i.unit, ...(i.scenario ? ['--scenario', i.scenario] : []), ...(i.reason ? ['--reason', i.reason] : [])]),
+    summary: [
+      ...approve.map((s) => describe(s, before.lock)),
+      ...removed.map((id) => `- ${id}  removed from the feature — its approved checks leave the contract`),
+      ...(unnamed ? [`note: ${unnamed} scenario(s) have no ID and are locked by name — renaming one will read as removing it`] : []),
+      `recorded by: ${gitUserName(i.projectRoot)}`,
+    ],
+    io: i.io,
+  });
+
+  const after = plan(i);
+  if (after.fingerprint !== before.fingerprint) {
+    throw new Error('Refused: the feature or the lock changed while you were confirming — nothing was written. Run the command again and review the new summary.');
+  }
+  const { decisionId } = recordContractApproval(after.write);
+  // A derived `@free @proposed` scenario stops being a proposal once QA locks it (DOS-14.8).
+  const approvedIds = new Set(approve.map((s) => s.id));
+  for (const f of contractFeatureFiles(after.write.unitDir, after.write.unit)) dropProposedTags(f, approvedIds);
+  return { status: 'approved', lockPath, decisionId, approved: approve.map((s) => s.id), removed };
+}

package/src/contract/assertion-matcher-vocabulary.ts

@@ -0,0 +1,93 @@
+/**
+ * What an assertion checks — the CLOSED vocabulary of the strength ladder (DOS-14.1, DOS-14.4).
+ *
+ * Read off the normalized sentence the QA wrote (the documented `see` / `is on` / `expect` forms of
+ * sungen-gherkin-syntax), not off the compiler's pattern registry: that registry is assembled from
+ * whichever drivers a machine has installed, so a hash built on it would differ between two
+ * checkouts of the same `.feature`, and the hook would judge differently from the CLI. A sentence
+ * outside the vocabulary is `unknown`, and an unknown check that changed is `review`, never `match`.
+ *
+ *   strength 1  visible · exists                                  (something is there)
+ *   strength 2  page · state · contains · matches · range · key-matching · child · url-/title-contains|matches
+ *   strength 3  equals · count · table-data · tab-order · schema · url · title
+ *   `all:` (every item) adds one. A negation (`not see`, `is not <state>`, `is hidden`) is a flag.
+ */
+import type { StateClause } from '../generators/test-generator/patterns/types';
+
+export interface AssertShape { matcher: string; negated: boolean }
+
+const NEGATION = /\b(?:not|no longer|never|cannot|can't|don't|doesn't|isn't|aren't|shouldn't)\b/;
+const NOT_SEE = /^(?:do not|does not|don't|doesn't|should not|shouldn't|cannot|can't|not|never) see\b/;
+const IS_NOT_STATE = /\bis not (sorted ascending|sorted descending|unchecked|checked|hidden|visible|disabled|enabled|focused|empty|loading|selected)$/;
+const RANGE = /\b(?:at least|at most|more than|less than|greater than|fewer than|between)\b/;
+const PAGE_SUBJECT = /^see (?:the )?(?:current |page )?(url|title)\b(.*)$/;
+/** A state and its complement are one check with a negation: hidden = not visible. */
+const STATE_AS: Partial<Record<StateClause, [string, boolean]>> = {
+  visible: ['visible', false], hidden: ['visible', true],
+  enabled: ['enabled', false], disabled: ['enabled', true],
+  checked: ['checked', false], unchecked: ['checked', true],
+};
+
+function comparison(rest: string): string | null {
+  if (/\bcontains?\b/.test(rest)) return '-contains';
+  if (/\bmatches\b/.test(rest)) return '-matches';
+  return /\b(?:is|equals?|with) \{\}|^ ?\{\}$/.test(rest) ? '' : null;
+}
+
+function baseMatcher(verb: string, state?: StateClause): string {
+  if (/^expect\b/.test(verb)) {
+    if (/\bmatches schema\b/.test(verb)) return 'schema';
+    if (RANGE.test(verb)) return 'range';
+    if (/\bcontains?\b/.test(verb)) return 'contains';
+    if (/\bmatches\b/.test(verb)) return 'matches';
+    return /\b(?:is|equals?)\b/.test(verb) ? 'equals' : 'unknown';
+  }
+  if (/\bin (?:local|session) storage\b/.test(verb)) {
+    if (/\bkey matching\b/.test(verb)) return 'key-matching';
+    if (/\bhas length\b/.test(verb)) return 'count';
+    if (/\bis not empty\b/.test(verb)) return 'state:empty';
+    return /\b(?:exists?|exist)\b/.test(verb) ? 'exists' : 'unknown';
+  }
+  if (/^see tab order\b/.test(verb)) return 'tab-order';
+  if (/\bmatch data$/.test(verb)) return 'table-data';
+  if (!/^(?:see|is on)\b/.test(verb)) return 'unknown';
+  const page = verb.match(PAGE_SUBJECT);
+  if (page) { const c = comparison(page[2]); return c === null ? 'unknown' : `${page[1]}${c}`; }
+  if (state) return STATE_AS[state]?.[0] ?? `state:${state}`;
+  if (/^see all \[\] contains? \[\]/.test(verb)) return 'child';
+  if (RANGE.test(verb)) return 'range';
+  if (/\bmatches \{\}/.test(verb)) return 'matches';
+  if (/\b(?:contains?|includes?) \{\}/.test(verb)) return 'contains';
+  if (/\b(?:has|have|with) (?:text|value) \{\}|\bwith \{\}/.test(verb)) return 'equals';
+  if (/\b(?:has|have) (?:\d+|\{\})(?: [\w-]+)?$/.test(verb)) return 'count';
+  if (/^is on \[\] (?:page|screen|dialog)$|^see \[\] page$/.test(verb)) return 'page';
+  if (/^see (?:all )?\[\](?: [\w-]+)?$/.test(verb)) return 'visible';
+  return 'unknown';
+}
+
+/** What an assertion sentence (the normalized `verb`) checks. `state` is the parser's trailing clause. */
+export function assertShapeOf(verb: string, parsedState?: StateClause): AssertShape {
+  const v = verb.replace(NOT_SEE, 'see');
+  const state = parsedState ?? (v.match(IS_NOT_STATE)?.[1] as StateClause | undefined);
+  const base = baseMatcher(v, state);
+  const flips = state ? STATE_AS[state]?.[1] === true : false;
+  const negated = NEGATION.test(verb) !== flips;
+  const all = /^see all\b/.test(v) && base !== 'unknown';
+  return { matcher: all ? `all:${base}` : base, negated };
+}
+
+const STRENGTH: Record<string, number> = {
+  visible: 1, exists: 1,
+  page: 2, enabled: 2, checked: 2, contains: 2, matches: 2, range: 2, 'key-matching': 2, child: 2,
+  'url-contains': 2, 'url-matches': 2, 'title-contains': 2, 'title-matches': 2,
+  equals: 3, count: 3, 'table-data': 3, 'tab-order': 3, schema: 3, url: 3, title: 3,
+};
+
+/** The ordinal strength of a matcher, or null when the ladder cannot judge it. */
+export function matcherStrength(matcher: string | undefined): number | null {
+  if (!matcher || matcher === 'unknown') return null;
+  const all = matcher.startsWith('all:');
+  const base = all ? matcher.slice(4) : matcher;
+  const s = base.startsWith('state:') ? 2 : STRENGTH[base];
+  return s === undefined ? null : s + (all ? 1 : 0);
+}