@sun-asterisk/sungen 3.2.34-beta.1 → 3.3.0-alpha.1

package/src/basis/spec-frontmatter.ts

@@ -0,0 +1,68 @@
+/**
+ * Optional `spec.md` frontmatter (DOS-12.2).
+ *
+ * `source_mode: linked|authored` (default `authored`), `id` and `version` (both in the BM-51
+ * template), and `status`, `superseded_by` when present. `screen_id` is kept as metadata only — it
+ * never enters an anchor. No frontmatter = the old behavior, so this never throws: a malformed
+ * block is reported as a problem and read as absent.
+ */
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { isDocId } from './anchor-grammar';
+
+export type SourceMode = 'linked' | 'authored';
+
+export interface SpecFrontmatter {
+  source_mode: SourceMode;
+  id?: string;
+  version?: string;
+  status?: string;
+  superseded_by?: string;
+  screen_id?: string;
+}
+
+export interface FrontmatterRead {
+  present: boolean;
+  frontmatter: SpecFrontmatter;
+  /** 0-based index of the first line after the closing fence (0 when there is no frontmatter). */
+  bodyStartIndex: number;
+  problems: string[];
+}
+
+const scalar = (v: unknown): string | undefined =>
+  typeof v === 'string' ? v.trim() || undefined : typeof v === 'number' ? String(v) : undefined;
+
+export function readSpecFrontmatter(text: string, source = 'spec.md'): FrontmatterRead {
+  const absent: FrontmatterRead = { present: false, frontmatter: { source_mode: 'authored' }, bodyStartIndex: 0, problems: [] };
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n');
+  if (lines[0]?.trim() !== '---') return absent;
+  const close = lines.findIndex((l, i) => i > 0 && (l.trim() === '---' || l.trim() === '...'));
+  if (close < 0) return { ...absent, problems: [`${source}: frontmatter opened with --- but never closed; read as absent`] };
+
+  const problems: string[] = [];
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(lines.slice(1, close).join('\n'), `${source} frontmatter`);
+  } catch (err) {
+    return { ...absent, bodyStartIndex: close + 1, problems: [err instanceof Error ? err.message : String(err)] };
+  }
+  if (raw === null || raw === undefined) raw = {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...absent, bodyStartIndex: close + 1, problems: [`${source}: frontmatter is not a mapping; read as absent`] };
+  }
+  const fm = raw as Record<string, unknown>;
+  const out: SpecFrontmatter = { source_mode: 'authored' };
+
+  const mode = scalar(fm.source_mode);
+  if (mode === 'linked' || mode === 'authored') out.source_mode = mode;
+  else if (mode !== undefined) problems.push(`${source}: source_mode "${mode}" is not linked|authored; using authored`);
+
+  const id = scalar(fm.id);
+  if (id && isDocId(id)) out.id = id;
+  else if (id) problems.push(`${source}: id "${id}" is not a document id like SPEC-AUTH-001; item anchors are not derived`);
+
+  for (const key of ['version', 'status', 'superseded_by', 'screen_id'] as const) {
+    const v = scalar(fm[key]);
+    if (v) out[key] = v;
+  }
+  return { present: true, frontmatter: out, bodyStartIndex: close + 1, problems };
+}

package/src/basis/spec-sections.ts

@@ -0,0 +1,35 @@
+/**
+ * The `##` / `###` section split of `spec.md`, shared by the manifest and the anchor reader so a
+ * `sec-<slug>` anchor and a manifest section can never disagree about where a section starts or
+ * what it hashes. The rules are the manifest's original ones, moved here unchanged (red-team #1):
+ * every line is scanned, a `Section:` prefix is stripped, the body is everything up to the next
+ * `##`/`###` heading.
+ */
+export interface SpecSectionBlock {
+  /** Heading text with any `Section:` prefix stripped (not yet normalized). */
+  name: string;
+  /** 0-based index of the heading line. */
+  headingIndex: number;
+  body: string[];
+}
+
+export function readSpecSectionBlocks(lines: string[]): SpecSectionBlock[] {
+  const out: SpecSectionBlock[] = [];
+  let cur: SpecSectionBlock | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(/^#{2,3}\s+(.*)$/);
+    if (h) {
+      if (cur) out.push(cur);
+      cur = { name: h[1].replace(/^Section:\s*/i, '').trim(), headingIndex: i, body: [] };
+    } else if (cur) {
+      cur.body.push(lines[i]);
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/** The manifest's section-name key: tier suffix and markdown marks dropped, lower-case, spaces collapsed. */
+export function normalizeSectionName(s: string): string {
+  return s.replace(/\(Tier[^)]*\)/i, '').replace(/[#*-]/g, '').trim().toLowerCase().replace(/\s+/g, ' ');
+}

package/src/basis/test-basis-schema.ts

@@ -0,0 +1,81 @@
+/**
+ * Test-basis schema, validator and reader (DOS-12.4). P0 ships only these; the generator and a
+ * `BasisProvider` are P1, and there is no `basis.hand-edited` rule.
+ *
+ *   { schema, source_mode, sources:[{docId, uri, version, hash}], anchors:[{id, kind, hash, location}] }
+ *
+ * It stores pointers and hashes, NEVER spec text (red-team #14). The validator enforces that
+ * structurally rather than by promise: unknown keys, multi-line values and long strings are refused,
+ * and every id, hash and citation must parse.
+ */
+import * as fs from 'fs';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { AnchorKind, isDocId, parseAnchorId, parseCitation } from './anchor-grammar';
+import { SourceMode } from './spec-frontmatter';
+
+export const TEST_BASIS_SCHEMA = 1;
+
+export interface TestBasisSource { docId: string; uri: string; version: string; hash: string }
+export interface TestBasisAnchor { id: string; kind: AnchorKind; hash: string; location: string }
+export interface TestBasis { schema: 1; source_mode: SourceMode; sources: TestBasisSource[]; anchors: TestBasisAnchor[] }
+
+const MAX_LEN: Record<string, number> = { docId: 64, uri: 2048, version: 64, hash: 64, id: 256, kind: 16, location: 2048 };
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** A pointer field: a short single-line string. Anything longer or multi-line is text, not a pointer. */
+function pointerErrors(where: string, obj: Record<string, unknown>, keys: string[]): string[] {
+  const e: string[] = [];
+  for (const k of Object.keys(obj)) if (!keys.includes(k)) e.push(`${where}: unknown key "${k}" (a test-basis holds pointers and hashes, never spec text)`);
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v !== 'string' || !v.trim()) e.push(`${where}.${k} must be a non-empty string`);
+    else if (/[\r\n]/.test(v) || v.length > MAX_LEN[k]) e.push(`${where}.${k} must be a single line of at most ${MAX_LEN[k]} characters`);
+  }
+  return e;
+}
+
+export function validateTestBasis(raw: unknown): string[] {
+  if (!isObject(raw)) return ['test-basis must be a mapping'];
+  const e: string[] = [];
+  for (const k of Object.keys(raw)) if (!['schema', 'source_mode', 'sources', 'anchors'].includes(k)) e.push(`unknown top-level key "${k}"`);
+  if (raw.schema !== TEST_BASIS_SCHEMA) e.push(`schema must be ${TEST_BASIS_SCHEMA}`);
+  if (raw.source_mode !== 'linked' && raw.source_mode !== 'authored') e.push('source_mode must be linked|authored');
+
+  const docIds = new Set<string>();
+  if (!Array.isArray(raw.sources)) e.push('sources must be a list');
+  else raw.sources.forEach((s, i) => {
+    if (!isObject(s)) { e.push(`sources[${i}] must be a mapping`); return; }
+    e.push(...pointerErrors(`sources[${i}]`, s, ['docId', 'uri', 'version', 'hash']));
+    if (typeof s.docId === 'string' && !isDocId(s.docId)) e.push(`sources[${i}].docId "${s.docId}" is not a document id like SPEC-AUTH-001`);
+    if (typeof s.hash === 'string' && !/^[0-9a-f]{12,64}$/.test(s.hash)) e.push(`sources[${i}].hash must be 12-64 lowercase hex`);
+    if (typeof s.docId === 'string') docIds.add(s.docId);
+  });
+
+  const seen = new Set<string>();
+  if (!Array.isArray(raw.anchors)) e.push('anchors must be a list');
+  else raw.anchors.forEach((a, i) => {
+    if (!isObject(a)) { e.push(`anchors[${i}] must be a mapping`); return; }
+    e.push(...pointerErrors(`anchors[${i}]`, a, ['id', 'kind', 'hash', 'location']));
+    const parsed = typeof a.id === 'string' ? parseAnchorId(a.id) : null;
+    if (!parsed) e.push(`anchors[${i}].id "${a.id}" is not an anchor (SPEC-ID#A-2, SPEC-ID#A-2/val, sec-<slug>)`);
+    else if (parsed.kind !== a.kind) e.push(`anchors[${i}].kind "${a.kind}" disagrees with its id (${parsed.kind})`);
+    if (parsed?.docId && !docIds.has(parsed.docId)) e.push(`anchors[${i}] points into ${parsed.docId}, which is not a listed source`);
+    if (typeof a.hash === 'string' && !/^[0-9a-f]{12}$/.test(a.hash)) e.push(`anchors[${i}].hash must be 12 lowercase hex (sha1-12 or sha256-12)`);
+    if (typeof a.location === 'string' && !parseCitation(a.location)) e.push(`anchors[${i}].location must be repo@SHA:path#Lx-Ly`);
+    if (typeof a.id === 'string') { if (seen.has(a.id)) e.push(`anchors[${i}].id "${a.id}" is listed twice`); seen.add(a.id); }
+  });
+  return e;
+}
+
+/** Best-effort reader: no file → no basis (an authored spec); a bad file → problems, never a throw. */
+export function readTestBasis(file: string): { basis?: TestBasis; problems: string[] } {
+  if (!fs.existsSync(file)) return { problems: [] };
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(fs.readFileSync(file, 'utf8'), file);
+  } catch (err) {
+    return { problems: [err instanceof Error ? err.message : String(err)] };
+  }
+  const problems = validateTestBasis(raw);
+  return problems.length ? { problems } : { basis: raw as TestBasis, problems };
+}

package/src/capabilities/registry.ts

@@ -14,6 +14,7 @@
 import type { StepPattern } from '../generators/test-generator/patterns/types';
 import type { Sensor } from './sensor';
 import type { DiscoveryProvider, ContextMapper, RepairProvider } from './context';
+import type { TraceIdentityResolver } from '../contract/trace/target-identity';
 
 export interface CapabilityDescriptor {
   /** Stable id: 'ui' | 'db' | 'api' | 'core' | … */
@@ -70,6 +71,21 @@ export interface CapabilityDescriptor {
    */
   appProfilePresets?: Record<string, unknown>;
 
+  /**
+   * Target-identity resolver for trace-derived contracts: maps a replayed page snapshot + a
+   * recorded action to `{role, name, identityConfidence}` using the runtime's own accessibility
+   * engine (UI → Playwright `getByRole` / `ariaSnapshot`). Spec: `sungen_capability_spi_spec.md`
+   * §4.5, `sungen_durable_orchestration_spec.md` DOS-14.5.
+   *
+   * Pinned in phase 08 (the phase 07 spike gate passed): core renders each snapshot as inert HTML
+   * and asks the resolver for role + name + optional scope per target; a result that is not
+   * well-formed is rejected, and anything core already knows forces `low` (missing CSS…). Called
+   * only by `sungen contract check --trace` / `contract derive`; the verdict reads the cached
+   * answers. There is deliberately no `nodes?` slot: the graph node API is internal to core in P0
+   * (OES-10).
+   */
+  traceIdentity?: TraceIdentityResolver;
+
   // --- Declared for later R-steps; not consumed yet (kept here so the SPI shape is visible). ---
   // adapter?: string;                  // codegen adapter id (existing adapterRegistry)
 }

package/src/cli/commands/audit.ts

@@ -4,7 +4,6 @@ import * as fs from 'fs';
 import { runAudit, AuditReport, catalogIdFromScreenDir } from '../../harness/audit';
 import { reportSlug } from '../../harness/unit-paths';
 import { acceptViewpointBaseline } from '../../harness/viewpoint-baseline';
-import { removeDraftLineFromFile, viewpointFileIsAiDraft } from '../../harness/viewpoint-draft-header';
 import { findUnitDir } from '../resolve-unit';
 
 
@@ -144,7 +143,7 @@ function render(r: AuditReport): void {
       const held = new Set(r.score.axes.filter((x) => x.withheld).map((x) => x.key));
       const absent = na.filter((k) => !held.has(k));
       if (absent.length) L(`      not scored (no evidence in this unit): ${absent.join(', ')}`);
-      if (held.size) L(`      measured but held (viewpoint not accepted yet — changed, adopted after the suite, or an AI draft; review, then --accept-viewpoint): ${[...held].join(', ')}`);
+      if (held.size) L(`      measured but held (viewpoint baseline changed — review, then --accept-viewpoint): ${[...held].join(', ')}`);
     }
     L(`      weakest: ${r.calibration.weakest.axis} ${(r.calibration.weakest.value * 100).toFixed(0)}%${r.calibration.inflated ? '  ⚠ SCORE-INFLATED-BY-BREADTH' : ''}`);
     if (r.calibration.cappedAt !== undefined) {
@@ -174,14 +173,10 @@ export function registerAuditCommand(program: Command): void {
     .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output the raw JSON report')
     .option('--accept-viewpoint', 'Accept the current test-viewpoint.md as the baseline the suite is measured against')
-    .option('--no-baseline', 'Measure without writing .sungen/viewpoint-baseline.json (audit a drafted viewpoint before generating)')
     .action((options) => {
       try {
         const name = options.screen || options.api || options.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
-        // Commander's `--no-*`: `baseline` is true unless the flag is passed.
-        const recordBaseline = options.baseline !== false;
-        if (!recordBaseline && options.acceptViewpoint) throw new Error('--no-baseline and --accept-viewpoint cannot be combined');
         const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
@@ -200,35 +195,18 @@ export function registerAuditCommand(program: Command): void {
         const unitId = catalogIdFromScreenDir(dir);
         const vb = report.viewpointBaseline;
         const postHoc = vb.status === 'new' && report.scenarioCount > 0;
-        // `drafted-by: ai` — a viewpoint the AI wrote is never accepted by the audit that measures it,
-        // with scenarios or without: only `--accept-viewpoint` does, and that removes the line.
-        const vpPath = path.join(dir, 'requirements', 'test-viewpoint.md');
-        const hasDraftMarker = viewpointFileIsAiDraft(vpPath);
-        // A draft with no VP id has nothing to accept — only VIEWPOINT-MISSING speaks for it. Fail
-        // here, before any write, so the file stays as it is and the QA is told why.
-        if (options.acceptViewpoint && vb.status === 'absent' && hasDraftMarker) {
-          throw new Error('the draft declares no VP ids — nothing to accept. Add the viewpoint ids (VP-… in the Priority Viewpoints table or checks), then run --accept-viewpoint again.');
-        }
-        const aiDraft = vb.status !== 'absent' && hasDraftMarker;
         // A re-parsed baseline is a CACHE migration, not an acceptance: the comparison already
         // resolved to `unchanged`, and rewriting the record only lets the NEXT real edit be
         // detected. Left unwritten it would re-migrate — and re-announce — on every run.
-        //
-        // `--no-baseline` skips every write here, the migration included: a draft audited before its
-        // scenarios exist is `new` and not post-hoc, and a plain audit would record it as the yardstick.
-        if (recordBaseline && !aiDraft && vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
-        if (recordBaseline && ((vb.status === 'new' && !postHoc && !aiDraft) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc || aiDraft)))) {
+        if (vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
+        if ((vb.status === 'new' && !postHoc) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc))) {
           acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
           if (options.acceptViewpoint) {
-            // The baseline is recorded first: if the line cannot be removed the draft stays flagged
-            // (held, finding, decide step) and the accept can simply be run again.
-            const lineRemoved = aiDraft && removeDraftLineFromFile(vpPath);
             // Measure again against what was just accepted: the report printed and saved below (the
             // one `sungen next` reads) must not be the pre-accept one, still holding the axes (#867).
             report = runAudit(dir, name);
             if (!options.json) {
               console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
-              if (lineRemoved) console.log('    Removed the `drafted-by: ai` line from test-viewpoint.md — it is QA-reviewed from here on.');
               console.log('    The report below is measured against it.\n');
             }
           }
@@ -250,7 +228,6 @@ export function registerAuditCommand(program: Command): void {
         } else {
           render(report);
           console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
-          if (!recordBaseline) console.log('  ○ baseline not recorded (--no-baseline)');
           console.log('');
         }
         // Non-zero exit when the gate fails — usable in CI / repair loop. Set exitCode (not

package/src/cli/commands/capability.ts

@@ -209,7 +209,7 @@ export function registerCapabilityCommand(program: Command): void {
           // beta channel can lag (e.g. a prerelease first-published-as-latest), pulling a driver
           // whose core dep resolves to the wrong @sun-asterisk/sungen and fails to load.
           const core = coreVersion();
-          const target = resolveDriverVersion(meta.package, core); // exact core, else same-line beta, else 'beta' tag
+          const target = resolveDriverVersion(meta.package, core); // exact core, else same-line build of core's channel, else that channel's tag
           const spec = `${meta.package}@${target}`;
           if (target !== core) {
             console.log(`ℹ ${meta.package}@${core} is not published yet — installing ${spec} (closest on the ${core} line).`);

package/src/cli/commands/contract-derive-command.ts

@@ -0,0 +1,60 @@
+/**
+ * `sungen contract derive --screen <u> [--grep <re>] [--json]` (DOS-14.8, phase 08): free tests'
+ * traces → `features/<u>.free.feature`, every scenario `@free @proposed`, deterministic, no LLM.
+ *
+ *   exit 0  written, unchanged, nothing to derive, or a mobile project (not supported yet)
+ *   exit 1  refused (a secret or a machine path would have been written — nothing was), or an error
+ */
+import type { Command } from 'commander';
+import * as path from 'path';
+import { deriveFreeFeature, DeriveResult } from '../../contract/derive-free-feature';
+import { registeredTraceResolver } from '../../contract/resolve-unit-trace-identities';
+import { resolveContractUnit } from '../../contract/contract-units';
+
+function print(r: DeriveResult, unit: string): void {
+  const L = console.log;
+  const rel = path.relative(process.cwd(), r.file);
+  L('');
+  L(`━━━ Contract derive: ${unit} — free tests' traces → ${rel} ━━━`);
+  L('');
+  if (r.note) L(`  ⚠ ${r.note}`);
+  for (const s of r.scenarios) L(`  + ${s.title}  (${s.steps} steps${s.low ? `, ${s.low} low identity` : ''}${s.opaque ? `, ${s.opaque} opaque` : ''})`);
+  for (const s of r.skipped) L(`  - ${s.id}  skipped: ${s.reason}`);
+  if (r.refused?.length) {
+    L(`  ✗ Refused — nothing was written. ${r.refused.length} likely secret(s) / machine path(s):`);
+    for (const h of r.refused) L(`      ${h.where} — ${h.reason}`);
+    L('    Move the value into test-data (or an env overlay) and use it from there, then derive again.');
+  } else if (r.written) {
+    L(`  ✓ Wrote ${rel}. Review the steps (they ARE the contract), then QA approves on a terminal:`);
+    L(`    sungen contract approve --screen ${unit}`);
+    L('  After approval, re-run the free tests (trace: "on") — a trace older than the contract proves nothing.');
+  } else if (r.scenarios.length) {
+    L(`  = ${rel} is already up to date.`);
+  } else if (!r.note) {
+    L(`  = Nothing to derive: no admissible trace of a test for ${unit} (try --grep).`);
+  }
+  L('');
+}
+
+export function registerDeriveCommand(contract: Command): void {
+  contract
+    .command('derive')
+    .description("Write features/<unit>.free.feature (@free @proposed) from the free tests' traces — deterministic, no LLM")
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--grep <regex>', 'Which tests, matched against "<id> <title> <file>" (default: tests whose file is named after the unit)')
+    .option('--json', 'Output the result as JSON')
+    .action(async (options) => {
+      try {
+        if (!options.screen) throw new Error('Provide --screen <name>');
+        const unit = resolveContractUnit(process.cwd(), String(options.screen));
+        const r = await deriveFreeFeature({
+          projectRoot: process.cwd(), unit, grep: options.grep ? String(options.grep) : undefined, resolver: registeredTraceResolver() ?? null,
+        });
+        if (options.json) console.log(JSON.stringify(r, null, 2)); else print(r, unit.name);
+        process.exit(r.refused?.length ? 1 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/contract.ts

@@ -0,0 +1,130 @@
+/**
+ * `sungen contract approve | check` — the Test Contract (DOS-14, phase 06a).
+ *
+ *   approve --screen <u> [--scenario <id>] [--reason <text>]
+ *       a human types a confirmation on a TTY; writes contracts.lock.yaml + a contract-approval
+ *       decision. No TTY → refused with the exact command (exit 1).
+ *   check --screen <u> [--trace] [--json]
+ *       rebuilds the verdict from .feature + lock + git HEAD + recorded traces (never from a report),
+ *       writes .sungen/reports/<slug>-contract.json as output (secret-scanned first). Exit 2 on a hard
+ *       finding, 0 on pass or review, 1 on an error (unknown unit, untrusted lock, unparseable feature).
+ *       `--trace` first asks driver-ui (a real browser) for the target identities of free / impl:code
+ *       traces; without it the cached answers are used (DOS-14.5, 14.6).
+ *   derive --screen <u> [--grep <re>]   → contract-derive-command.ts (DOS-14.8)
+ */
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { approveContract } from '../../contract/approve-contract';
+import { buildContractVerdict, ContractVerdict } from '../../contract/build-contract-verdict';
+import { contractReportPath, writeContractReport } from '../../contract/contract-report-file';
+import { HARD_CLASSES, REVIEW_CLASSES } from '../../contract/contract-schema';
+import { processIO } from '../../decisions/human-confirmation';
+import { resolveContractUnit } from '../../contract/contract-units';
+import { secretScanHits } from '../../contract/field-semantic-redaction';
+import { resolveUnitTraceIdentities } from '../../contract/resolve-unit-trace-identities';
+import { registerDeriveCommand } from './contract-derive-command';
+
+const MARK: Record<string, string> = {
+  match: '✓', strengthened: '↑', proposed: '+', 'hash-changed': '⚖', 'oracle-weakened': '✗', 'target-changed': '✗', 'assertion-lost': '✗',
+  opaque: '◐', nondeterministic: '≈', inconclusive: '?', unproven: '✗',
+};
+/** `contract check` judges traces with a generous deadline (the guard path keeps ~3 s). */
+const CHECK_TRACE_BUDGET_MS = 120_000;
+const UNPROVEN_HINT = "    → free / impl:code tests need trace: 'on' and the sungen run-record reporter, then a fresh run (see `sungen contract derive`).";
+
+function printVerdict(v: ContractVerdict, reportFile: string): void {
+  const L = console.log;
+  const head = v.verdict === 'pass' ? '✓ PASS' : v.verdict === 'review'
+    ? '⚖ REVIEW — changed, not weaker. Exit 0 here, but review blocks `sungen delivery` until QA re-approves' : '✗ FAIL';
+  L('');
+  L(`━━━ Contract check: ${v.unit} — Gherkin vs the approved lock ━━━`);
+  L('');
+  L(`  verdict: ${head}`);
+  const matched = v.scenarios.filter((s) => s.class === 'match').length;
+  for (const s of v.scenarios.filter((x) => x.class !== 'match')) {
+    L(`  ${MARK[s.class] ?? '?'} ${s.id}  ${s.class}${s.class === 'proposed' ? ' (no approved entry — does not block)' : ''}`);
+    for (const f of s.findings) L(`      ${f.rule ? `[${f.rule}] ` : ''}${f.step ? `step ${f.step}: ` : ''}${f.detail}`);
+    if (s.trace?.hashes.length) L(`      trace: ${[...new Set(s.trace.hashes)].join(', ')} (${s.trace.runs.length} run(s))`);
+    if (s.class === 'unproven') L(UNPROVEN_HINT);
+  }
+  if (matched) L(`  ✓ ${matched} scenario(s) match the approved contract`);
+  const issue = (u: ContractVerdict['uncommitted'][number]): string =>
+    u.change === 'tampered' || u.change === 'unverified' ? `lock entry ${u.change}: ${u.detail}` : `lock entry ${u.change} and not committed`;
+  for (const u of v.uncommitted.slice(0, 10)) L(`  ✗ ${u.id}  ${issue(u)}  [contract.lock-uncommitted]`);
+  if (v.uncommitted.length > 10) L(`  ✗ … and ${v.uncommitted.length - 10} more lock entries that are not what QA approved and committed`);
+  for (const w of v.warnings) L(`  ⚠ ${w}`);
+  L('');
+  // Only missing / refused traces: re-approving cannot help, a fresh traced run can.
+  const blocking = v.scenarios.filter((s) => HARD_CLASSES.has(s.class) || REVIEW_CLASSES.has(s.class));
+  const onlyUnproven = blocking.length > 0 && blocking.every((s) => s.class === 'unproven');
+  if (v.verdict === 'fail') {
+    L(v.uncommitted.length
+      ? '  → Commit the approval (lock + decision) through review, or restore the lock from git (`git checkout -- <lock>`).'
+      : onlyUnproven ? "  → Re-run the free / impl:code tests with trace: 'on', then check again."
+        : '  → Restore the approved checks in the .feature — or, if the change is intended, QA approves it on a terminal:');
+  }
+  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven) L(`    sungen contract approve --screen ${v.unit}`);
+  L(`  Report: ${path.relative(process.cwd(), reportFile)}`);
+  L('');
+}
+
+function unitOrThrow(name: string | undefined): { name: string; dir: string } {
+  if (!name) throw new Error('Provide --screen <name>');
+  return resolveContractUnit(process.cwd(), name);
+}
+
+export function registerContractCommand(program: Command): void {
+  const contract = program
+    .command('contract')
+    .description('Test Contract (DOS-14): the Gherkin QA approved is the contract — lock it (TTY) and check the .feature was not weakened');
+
+  contract
+    .command('approve')
+    .description('Lock the current Gherkin as the approved contract — a human types a confirmation on a TTY')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--scenario <id>', 'Approve one scenario only (its ID, e.g. VP-LOGIN-001)')
+    .option('--reason <text>', 'Why (recorded in the contract-approval decision)')
+    .action(async (options) => {
+      try {
+        const unit = unitOrThrow(options.screen);
+        const r = await approveContract({ projectRoot: process.cwd(), unit: unit.name, scenario: options.scenario, reason: options.reason, io: processIO() });
+        if (r.status === 'nothing-to-approve') { console.log(`\n= Nothing to approve: every chosen scenario of ${unit.name} already matches its approved lock entry.\n`); return; }
+        console.log(`\n✓ Approved ${r.approved.length} scenario(s)${r.removed.length ? `, removed ${r.removed.length}` : ''} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
+        console.log('  Commit the lock and the decision through review: until they are in git HEAD, `sungen contract check` reports contract.lock-uncommitted.\n');
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  contract
+    .command('check')
+    .description('Compare the .feature with the approved lock on the strength ladder, and the lock with git HEAD')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--trace', 'Resolve free / impl:code trace target identities with @sungen/driver-ui (a real browser) first')
+    .option('--json', 'Output the verdict as JSON')
+    .action(async (options) => {
+      let unit: { name: string; dir: string } | undefined;
+      try {
+        unit = unitOrThrow(options.screen);
+        const notes = options.trace ? await resolveUnitTraceIdentities(process.cwd(), unit) : [];
+        // The CLI may take its time; the guard (contractBlockers) keeps the ~3 s default.
+        const verdict = buildContractVerdict(process.cwd(), unit, { traceBudgetMs: CHECK_TRACE_BUDGET_MS });
+        verdict.warnings.push(...notes);
+        const hits = secretScanHits(JSON.stringify(verdict, null, 2), `${unit.name}-contract.json`);
+        if (hits.length) throw new Error(`Refused to write the contract report — likely secret(s): ${hits.map((h) => `${h.where} ${h.reason}`).join('; ')}`);
+        const file = writeContractReport(process.cwd(), verdict);
+        if (options.json) console.log(JSON.stringify(verdict, null, 2));
+        else printVerdict(verdict, file);
+        process.exit(verdict.exitCode);
+      } catch (error) {
+        // Unreadable = not run (DOS-14.0): an earlier report must not outlive the inputs it judged.
+        if (unit) fs.rmSync(contractReportPath(process.cwd(), unit.name), { force: true });
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  registerDeriveCommand(contract);
+}

package/src/cli/commands/delivery.ts

@@ -41,6 +41,11 @@ import { MatrixFinding } from '../../exporters/matrix/types';
 import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
+import { processIO } from '../../decisions/human-confirmation';
+import { DeliveryDecisionGate } from '../../harness/gates/delivery-decision-gate';
+import { runDeliveryDecisionStep } from '../../harness/gates/delivery-decision-step';
+import { deliverableGateOverrides, InRunAcceptance } from '../../harness/gates/gate-override-report';
+import { ChecklistUnit, renderChecklist, unitChecklist } from '../../harness/gates/delivery-checklist';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -660,7 +665,7 @@ export function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTarge
 }
 
 function printFindings(findings: MatrixFinding[]): void {
-  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·` } as const;
+  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·`, info: `${COLOR.gray}i` } as const;
   for (const f of findings) {
     log(`  ${icon[f.severity]} [Gate ${f.gate}]${COLOR.reset} ${f.ref ? `${f.ref}: ` : ''}${f.message}`);
   }
@@ -685,9 +690,11 @@ async function exportMatrixTarget(
   target: DeliveryTarget,
   opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
   env: EnvironmentInfo,
+  decisions?: DeliveryDecisionGate,
 ): Promise<MatrixRunSummary | 'skipped' | null> {
   const paths = matrixPathsFor(cwd, target);
   paths.runEnv = matrixRunEnv(cwd, target, env, paths);
+  paths.gateRules = decisions?.rulesFor(qaDir(cwd, target));   // the unit's gate-overrides apply to its matrix gates
 
   // A feature whose scenarios are ALL @exploration probes has nothing to deliver —
   // skip it quietly (no map required) instead of demanding a reviewed grouping for
@@ -728,6 +735,7 @@ async function exportMatrixTarget(
   // A CSV-only export overwrites no workbook, so an unreadable one only means "nothing to carry".
   catch (e) { if (format !== 'csv') priorError = e as Error; }
   applyManualCarry(model, prior);
+  model.gateOverrides = deliverableGateOverrides(decisions?.overridesFor(qaDir(cwd, target)) ?? [], hasReview(model.findings), decisions?.acceptedInRun);
 
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), review: ${model.manifest.approvalState} (design), test outcome: ${formatTestOutcome(resultTotals(model.items))}`);
   {
@@ -892,6 +900,19 @@ function printSummaryTable(summaries: ScreenSummary[]): void {
   }
 }
 
+/** T6: one checklist block per delivered unit, each box from what its command says now (delivery-checklist.ts). */
+async function printDeliveryChecklist(cwd: string, targets: DeliveryTarget[], accepted?: InRunAcceptance): Promise<void> {
+  const units = new Map<string, ChecklistUnit>();
+  for (const t of targets) {
+    const dir = qaDir(cwd, t);
+    if (!units.has(dir)) units.set(dir, { label: t.isFlow ? `flow/${t.screen}` : t.screen, unitName: t.screen, unitDir: dir, kind: t.kind, resultsPath: resolveResultsPath(cwd, t) });
+  }
+  const rows: Array<{ label: string; boxes: Awaited<ReturnType<typeof unitChecklist>> }> = [];
+  for (const u of units.values()) rows.push({ label: u.label, boxes: await unitChecklist(cwd, u, accepted) });
+  log('');
+  for (const line of renderChecklist(rows)) log(line);
+}
+
 // ----------------------------------------------------------------------------
 // Command registration
 // ----------------------------------------------------------------------------
@@ -910,10 +931,11 @@ export function registerDeliveryCommand(program: Command): void {
     .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
     .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
     .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
+    .option('--accept-in-run', 'Deliver despite gate-overrides/waivers/approvals recorded during the run (decision.in-run) — a human confirms on a terminal')
     .action(async (names: string[], options: {
       skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
       legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
-      format?: string;
+      format?: string; acceptInRun?: boolean;
     }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
@@ -990,6 +1012,30 @@ export function registerDeliveryCommand(program: Command): void {
           .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
         for (const line of formatSecretScan(secretScan)) log(line);
 
+        // OES-11.3–11.5: decisions that do not verify, rejected overrides, a stale audit and in-run
+        // decisions stop the delivery before anything is written (approval only stamps the map).
+        let decisions: DeliveryDecisionGate | undefined;
+        // --approve only stamps a matrix map. With --legacy / --full it would skip this gate and
+        // fall through to the export, so the combination is refused before anything is written.
+        if (options.approve !== undefined && (options.legacy || options.full)) {
+          console.error(`${COLOR.red}--approve applies to the matrix deliverable only${COLOR.reset} — it cannot be combined with --legacy / --full`);
+          process.exit(1);
+        }
+        if (options.approve === undefined) {
+          const gate = await runDeliveryDecisionStep({
+            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log,
+            // --preview / --check soften only the matrix export; --legacy has no draft mode, so it always needs one.
+            requireTrustedAudit: !!(options.legacy || options.full) || (!options.preview && !options.check),
+            refs: toExport.map((t) => ({ label: t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName, unitName: t.screen, unitDir: qaDir(cwd, t), resultsPath: resolveResultsPath(cwd, t) })),
+            argv: ['sungen', 'delivery', ...(names ?? []), ...(options.env ? ['--env', options.env] : []), ...(options.legacy || options.full ? ['--legacy'] : [])],
+          });
+          if (!gate) {
+            await printDeliveryChecklist(cwd, toExport);
+            process.exit(1);
+          }
+          decisions = gate;
+        }
+
         // 3. Export
         const legacy = options.legacy || options.full;
         if (!legacy) {
@@ -1035,13 +1081,15 @@ export function registerDeliveryCommand(program: Command): void {
           for (const target of toExport) {
             const s = await exportMatrixTarget(cwd, target, {
               check: options.check, preview: options.preview, format: format as MatrixFormat,
-            }, env);
+            }, env, decisions);
             if (s === 'skipped') continue; // all-@exploration feature — neither exported nor a failure
             if (s) matrixSummaries.push(s);
             else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);
           }
           if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
+          for (const line of decisions?.summaryLines() ?? []) log(line);
           printSkipSummary(skipped, notExported);
+          await printDeliveryChecklist(cwd, toExport, decisions?.acceptedInRun);
           // A named target that produced nothing is a failure. A sweep is a failure
           // only when it produced nothing at all — units still waiting for a map or
           // an approval are the normal state of a live project. Preflight skips are
@@ -1064,6 +1112,7 @@ export function registerDeliveryCommand(program: Command): void {
         // 4. Summary
         printSummaryTable(summaries);
         printSkipSummary(skipped, []);
+        await printDeliveryChecklist(cwd, toExport, decisions?.acceptedInRun);
         // Same rule as the matrix path: every attempted target in an explicit scope
         // must have produced a file; a sweep only fails when nothing was written.
         if (explicitScope ? summaries.length < toExport.length : summaries.length === 0) process.exit(1);

package/src/cli/commands/generate.ts

@@ -7,6 +7,7 @@ import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '..
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
+import { isHandWritten } from '../../harness/parse';
 
 /**
  * Find .feature files recursively in a directory
@@ -20,7 +21,8 @@ function findFeatureFiles(dir: string): string[] {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...findFeatureFiles(fullPath));
-    } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+    } else if (entry.isFile() && entry.name.endsWith('.feature') && !isHandWritten([], fullPath)) {
+      // A derived `*.free.feature` is a contract for hand-written tests — never compiled (DOS-14.8).
       files.push(fullPath);
     }
   }