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

package/src/contract/lock-secret-guard.ts

@@ -0,0 +1,95 @@
+/**
+ * Nothing sensitive goes into a lock (DOS-14.4, DOS-14.7, red-team #14). Before a lock is written:
+ *
+ *   1. the existing secret scanner (harness/secret-scan) runs over the EXACT text about to be
+ *      written — vendor token prefixes, secret-named keys with long literals;
+ *   2. semantic detection by field meaning (exporters/sensitive-key's vocabulary — password, token,
+ *      secret, otp, api key… — matched as whole words): a LITERAL typed into such a field.
+ *      `{{var}}`, `<placeholder>` and `${ENV}` are references, not values, and pass.
+ *
+ * A hit refuses the write — nothing is written, neither the lock nor its decision — and names the
+ * place (feature file:line, or lock line) without echoing the value.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { SENSITIVE_NAME } from '../exporters/sensitive-key';
+import { scanTestDataSecrets } from '../harness/secret-scan';
+import type { ContractScenario, ContractStep } from './contract-schema';
+import { LOCK_FILE_NAME } from './contracts-lock-file';
+
+export interface LockSecretHit { where: string; reason: string }
+
+export class LockSecretError extends Error {
+  constructor(public readonly hits: LockSecretHit[]) {
+    super(`Refused: the contract would write ${hits.length} sensitive value(s) into ${LOCK_FILE_NAME}. Nothing was written.\n`
+      + hits.map((h) => `  ${h.where} — ${h.reason}`).join('\n')
+      + '\n  Move each value into the unit\'s test-data (qa/<kind>/<unit>/test-data/*.yaml, or an env overlay for a real'
+      + ' credential), reference it in the step as {{variable}}, then approve again.');
+    this.name = 'LockSecretError';
+  }
+}
+
+const REFERENCE = /^(?:\{\{[^}]*\}\}|<[^>]+>|\$\{[A-Za-z_][A-Za-z0-9_]*\})$/;
+const literals = (joined: string | undefined): string[] =>
+  (joined ?? '').split(' | ').map((v) => v.trim()).filter((v) => v.length > 0 && !REFERENCE.test(v));
+
+/** The exporters' credential vocabulary, matched against WHOLE words (plural allowed), not substrings. */
+const SENSITIVE_WORD = new RegExp(`^(?:${SENSITIVE_NAME.source})s?$`, 'i');
+
+/**
+ * Is a field name a credential? Word by word — `confirmPassword`, `new_password`, `API Key`, `OTP` are;
+ * `Passenger Name`, `Compass`, `Bypass Code`, `Hotpot` are not (they only CONTAIN the letters).
+ * Adjacent words are also tried joined, so `API Key` reads as `apikey`.
+ */
+export function isSensitiveFieldName(name: string | undefined): boolean {
+  if (!name) return false;
+  const words = name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  return words.some((w, i) => SENSITIVE_WORD.test(w) || (i > 0 && SENSITIVE_WORD.test(`${words[i - 1]}${w}`)));
+}
+const sensitive = isSensitiveFieldName;
+
+function stepHit(step: ContractStep): string | null {
+  if (step.kind !== 'action') return null;   // a check's expected text is what the page SHOWS, not a typed credential
+  const names = [step.target?.ref, ...(step.target?.also ?? [])];
+  const field = names.find(sensitive);
+  if (field && literals(step.value).length) return `a literal value typed into the sensitive field [${field}]`;
+  const [header, ...rows] = step.table ?? [];
+  const col = (header ?? []).findIndex(sensitive);
+  if (col >= 0 && rows.some((r) => literals(r[col]).length)) return `a literal value in the sensitive column "${header[col]}"`;
+  return null;
+}
+
+/** Semantic hits over the scenarios about to be locked. */
+export function sensitiveLiteralHits(scenarios: ContractScenario[]): LockSecretHit[] {
+  const hits: LockSecretHit[] = [];
+  for (const sc of scenarios) {
+    sc.steps.forEach((step, i) => {
+      const reason = stepHit(step);
+      if (!reason) return;
+      const line = sc.source.lines[i];
+      hits.push({ where: `${path.basename(sc.source.file)}${line ? `:${line}` : ''} (${sc.id}, step ${i + 1})`, reason });
+    });
+  }
+  return hits;
+}
+
+/** The secret scanner over the lock text exactly as it would be written. */
+export function scannerHits(lockText: string): LockSecretHit[] {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-lock-scan-'));
+  try {
+    fs.mkdirSync(path.join(dir, 'test-data'));
+    fs.writeFileSync(path.join(dir, 'test-data', LOCK_FILE_NAME), lockText);
+    const result = scanTestDataSecrets(dir);
+    if (result.unscanned.length) throw new Error(`the secret scan could not read the lock it was given (${result.unscanned[0].reason})`);
+    return result.hits.map((h) => ({ where: `${LOCK_FILE_NAME}:${h.line}`, reason: h.reason }));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Throws LockSecretError when the lock would carry a sensitive value. */
+export function assertNoLockSecrets(scenarios: ContractScenario[], lockText: string): void {
+  const hits = [...sensitiveLiteralHits(scenarios), ...scannerHits(lockText)];
+  if (hits.length) throw new LockSecretError(hits);
+}

package/src/contract/lock-vs-git-head.ts

@@ -0,0 +1,38 @@
+/**
+ * The working lock against the committed one (DOS-14.4, red-team #3). A lock entry is trusted only
+ * where it equals `git show HEAD:<lock>`: a commit went through review, a local edit did not — an
+ * agent that weakened a test could have edited the lock to match. Every difference is
+ * `contract.lock-uncommitted` (hard), including the cases that make a contract VANISH: an entry
+ * removed, or the whole lock deleted while HEAD still holds it.
+ *
+ * The same rule id carries the other ways a lock entry can fail to be what QA approved:
+ *   tampered    its steps no longer hash to its `hash` (contracts-lock-file.ts)
+ *   unverified  no committed contract-approval decision vouches for it (verify-approval-decisions.ts)
+ */
+import type { ContractLock } from './contract-schema';
+import { HeadSnapshot, headFileText, posixRel } from './contract-git';
+import { sameJson } from './contract-hash';
+import { parseLockText } from './contracts-lock-file';
+
+export interface UncommittedEntry { id: string; change: 'added' | 'changed' | 'removed' | 'tampered' | 'unverified'; detail?: string }
+
+export type HeadComparison = { status: 'no-git' } | { status: 'compared'; uncommitted: UncommittedEntry[] };
+
+export function compareLockWithHead(
+  projectRoot: string, lockFile: string, workingText: string | null, working: ContractLock | null, snap: HeadSnapshot,
+): HeadComparison {
+  if (snap.blobs === null) return { status: 'no-git' };
+  const rel = posixRel(projectRoot, lockFile);
+  const headText = headFileText(snap, rel, workingText);
+  if (headText !== null && headText === workingText) return { status: 'compared', uncommitted: [] };
+  const head = headText === null ? null : parseLockText(headText, `HEAD:${rel}`);
+  const now = working?.scenarios ?? {};
+  const was = head?.scenarios ?? {};
+  const uncommitted: UncommittedEntry[] = [];
+  for (const id of [...new Set([...Object.keys(now), ...Object.keys(was)])].sort((a, b) => a.localeCompare(b, 'en'))) {
+    if (!(id in was)) uncommitted.push({ id, change: 'added' });
+    else if (!(id in now)) uncommitted.push({ id, change: 'removed' });
+    else if (!sameJson(now[id], was[id])) uncommitted.push({ id, change: 'changed' });
+  }
+  return { status: 'compared', uncommitted };
+}

package/src/contract/normalize-contract-step.ts

@@ -0,0 +1,74 @@
+/**
+ * One parsed Gherkin step → one contract step (DOS-14.1). The step was already parsed by the
+ * existing GherkinParser (ParsedStep: parent scope, state clause, data table, nth); this re-reads
+ * its sentence with references and values masked, as the StepMapper's matcher does
+ * (`maskRefsForMatching`) so a NAME can never read as grammar — and keeps what it masked:
+ *
+ *   `User see [Status] text with {{s}} in [Job Row] row with {{t}}`
+ *     → {kind: assert, verb: 'see [] text with {}', target: {ref: 'Status', parent: 'row [Job Row] with {{t}}'},
+ *        matcher: 'equals', expected: '{{s}}'}
+ *
+ * The verb keeps every word and number of the sentence, so two steps with equal contract steps are
+ * the same sentence up to case and spacing: an exact match is never a guess. `{{var}}` stays a
+ * variable (never resolved), a literal loses only its quotes.
+ */
+import type { ParsedStep } from '../generators/gherkin-parser';
+import { extractParentScopeClause } from '../generators/gherkin-parser/parent-scope-clause';
+import type { ContractStep, ContractTarget } from './contract-schema';
+import { assertShapeOf } from './assertion-matcher-vocabulary';
+
+export type StepBucket = 'given' | 'when' | 'then';
+
+/** Quoted literal · `{{var}}` · `<outline placeholder>` · `[Reference]`, left to right. */
+const TOKEN = /"[^"]*"|\{\{[^}]*\}\}|<[^>\s][^>]*>|\[[^\]]*\]/g;
+
+function parentOf(text: string): { parent?: string; body: string } {
+  const { clause } = extractParentScopeClause(text);
+  if (!clause) return { body: text };
+  const tail = clause.valueRef !== undefined ? ` with {{${clause.valueRef}}}` : clause.valueText !== undefined ? ` with "${clause.valueText}"` : '';
+  return { parent: `${clause.type} [${clause.ref.trim()}]${tail}`, body: clause.remainingText };
+}
+
+export function normalizeContractStep(step: ParsedStep, bucket: StepBucket): ContractStep {
+  const { parent, body } = parentOf(step.text);
+  const refs: string[] = [];
+  const values: string[] = [];
+  const masked = body.replace(TOKEN, (tok) => {
+    if (tok.startsWith('[')) { refs.push(tok.slice(1, -1).trim()); return '[]'; }
+    values.push(tok.startsWith('"') ? tok.slice(1, -1) : tok);
+    return '{}';
+  });
+  const verb = masked.replace(/^\s*user\s+/i, '').replace(/\s+/g, ' ').replace(/\s*[.:]\s*$/, '').trim().toLowerCase();
+  const kind = bucket === 'then' ? 'assert' : 'action';
+
+  let target: ContractTarget | undefined;
+  if (refs.length) target = { ref: refs[0], ...(refs.length > 1 ? { also: refs.slice(1) } : {}) };
+  else if (kind === 'assert' && /^expect\b/.test(verb) && values.length) target = { ref: values.shift()! };
+  if (target && parent) target.parent = parent;
+  if (target && step.nth && step.nth > 0) target.nth = step.nth;
+
+  const joined = values.length ? values.join(' | ') : undefined;
+  const table = step.dataTable ? [step.dataTable.headers, ...step.dataTable.rows.map((r) => r.cells)] : undefined;
+  const out: ContractStep = { kind, verb };
+  if (target) out.target = target;
+  if (kind === 'action') {
+    if (joined !== undefined) out.value = joined;
+  } else {
+    const shape = assertShapeOf(verb, step.state);
+    out.matcher = shape.matcher;
+    if (joined !== undefined) out.expected = joined;
+    if (shape.negated) out.negated = true;
+  }
+  if (table) out.table = table;
+  return out;
+}
+
+/** Given/When/Then for every step of one block, And/But inheriting the last primary keyword. */
+export function bucketsOf(steps: ParsedStep[]): StepBucket[] {
+  let last: StepBucket = 'given';
+  return steps.map((s) => {
+    const kw = s.keyword.trim().toLowerCase();
+    if (kw === 'given' || kw === 'when' || kw === 'then') last = kw;
+    return last;
+  });
+}

package/src/contract/normalize-feature-steps.ts

@@ -0,0 +1,93 @@
+/**
+ * A unit's `.feature` files → its contract scenarios (DOS-14.1, 14.2), through the existing
+ * GherkinParser — no second parser.
+ *
+ *   which scenarios  every automated one: not `@manual` (scenario or feature), not `@deferred:flow`,
+ *                    not a `@steps:` block or a `@beforeAll/@afterEach/@afterAll` hook
+ *   steps            Background + the `@extend:` base's Given/When (the compiler's own rule) + its own
+ *   id               the title's leading ID (`VP-LOGIN-001`), as the harness reads it; a title with no
+ *                    ID is locked by its name, so renaming it reads as removing it
+ *   implementation   `@free` → free, `@impl:code` → impl:code, otherwise compiled — scenario or feature tag
+ *   hash             contractHash(implementation, steps); the scenario name is not in it
+ *
+ * A file that does not parse throws: an unreadable contract is never an empty one.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
+import { isIdLike } from '../harness/parse';
+import { featureFilesFor } from '../harness/unit-paths';
+import { contractHash } from './contract-hash';
+import type { ContractScenario, ContractStep, Implementation } from './contract-schema';
+import { bucketsOf, normalizeContractStep } from './normalize-contract-step';
+
+const EXCLUDED = (tags: string[]): boolean => tags.some((t) => /^@manual\b/i.test(t) || /^@deferred:flow$/i.test(t));
+
+function implementationOf(tags: string[]): Implementation {
+  if (tags.some((t) => /^@free$/i.test(t))) return 'free';
+  if (tags.some((t) => /^@impl:code$/i.test(t))) return 'impl:code';
+  return 'compiled';
+}
+
+function idOf(name: string): { id: string; hasId: boolean } {
+  const lead = name.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+  return lead && isIdLike(lead) ? { id: lead.toUpperCase(), hasId: true } : { id: name.replace(/\s+/g, ' ').trim(), hasId: false };
+}
+
+/** Only Given→When of an `@extend` base: its Then (and the And/But after it) stay with the base. */
+const extendPart = (steps: ParsedStep[]): ParsedStep[] => steps.filter((_, i) => bucketsOf(steps)[i] !== 'then');
+
+const normalizeBlock = (steps: ParsedStep[]): ContractStep[] => {
+  const buckets = bucketsOf(steps);
+  return steps.map((s, i) => normalizeContractStep(s, buckets[i]));
+};
+
+/** 1-based line of each step, searched in order from line index `from` — for messages only (0 = not found). */
+function stepLines(lines: string[], from: number, steps: ParsedStep[]): number[] {
+  let at = Math.max(from, 0);
+  return steps.map((s) => {
+    const i = lines.findIndex((l, n) => n >= at && l.trim().endsWith(s.text.trim()));
+    if (i >= 0) at = i + 1;
+    return i + 1;
+  });
+}
+
+const HEADER = /^\s*(?:Scenario|Scenario Outline|Scenario Template|Example):/;
+const OUTLINE = /^\s*Scenario (?:Outline|Template):/;
+const headerLine = (lines: string[], name: string): number => lines.findIndex((l) => HEADER.test(l) && l.includes(name.trim()));
+
+export function scenariosOfFeatureFile(file: string): ContractScenario[] {
+  const feature = new GherkinParser().parseFeatureFile(file);
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const base = new Map<string, ParsedScenario>();
+  for (const sc of feature.scenarios) if (sc.stepsName) base.set(sc.stepsName, sc);
+  const background = feature.background?.steps ?? [];
+  const out: ContractScenario[] = [];
+  for (const sc of feature.scenarios) {
+    const tags = [...(feature.tags ?? []), ...(sc.tags ?? [])];
+    if (sc.stepsName || sc.hookType || EXCLUDED(tags)) continue;
+    const baseScenario = sc.extendsName ? base.get(sc.extendsName) : undefined;
+    const extended = extendPart(baseScenario?.steps ?? []);
+    const steps = [...normalizeBlock(background), ...normalizeBlock(extended), ...normalizeBlock(sc.steps)];
+    const implementation = implementationOf(tags);
+    const { id, hasId } = idOf(sc.name);
+    const header = headerLine(lines, sc.name);
+    const sourceLines = [
+      ...stepLines(lines, 0, background),
+      ...stepLines(lines, baseScenario ? headerLine(lines, baseScenario.name) : 0, extended),
+      ...stepLines(lines, header, sc.steps),
+    ];
+    const outline = header >= 0 && OUTLINE.test(lines[header]);
+    out.push({ id, implementation, steps, hash: contractHash(implementation, steps), source: { file, name: sc.name, hasId, lines: sourceLines, outline } });
+  }
+  return out;
+}
+
+/** Every contract scenario of a unit, in `featureFilesFor` order. Missing feature files contribute nothing. */
+export function loadContractScenarios(unitDir: string, unit: string): ContractScenario[] {
+  return featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f)).flatMap(scenariosOfFeatureFile);
+}
+
+/** Feature files that make up a unit's contract input (for the inputs hash). */
+export const contractFeatureFiles = (unitDir: string, unit: string): string[] =>
+  featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f)).map((f) => path.resolve(f));

package/src/contract/oracle-strength.ts

@@ -0,0 +1,80 @@
+/**
+ * How a changed assertion compares to the approved one on the same target (DOS-14.4).
+ *
+ * Every rule is written for POSITIVE checks, from the approved check A to the new check B:
+ *   weakened      expected value dropped · a data-table row removed or a cell changed · a shorter
+ *                 literal under `contains` · a lower rung on the ladder (conservative)
+ *   strengthened  B implies A, with the same expected value, on the same element (IMPLICATION, never
+ *                 rung): equals ⇒ contains · all:X ⇒ X · url ⇒ url-contains · title ⇒ title-contains
+ *   review        anything else — it blocks delivery until QA re-approves it
+ * Nothing implies `visible`: a text or count check passes on a hidden element, and a state (enabled,
+ * checked, empty, focused, selected, loading, sorted…) says nothing about visibility either.
+ *
+ * Under a NEGATION the direction reverses — `not P` proves `not Q` exactly when Q ⇒ P — so the same
+ * rules run with A and B swapped: `does not see [Toast]` → `does not see [Toast] with text {{x}}` is
+ * a weakening (a visible toast with other text now passes). A negation added or removed is a flip.
+ */
+import { sameJson } from './contract-hash';
+import type { ContractStep } from './contract-schema';
+import { matcherStrength } from './assertion-matcher-vocabulary';
+
+export { assertShapeOf, matcherStrength } from './assertion-matcher-vocabulary';
+export type { AssertShape } from './assertion-matcher-vocabulary';
+
+const IMPLIES: Record<string, readonly string[]> = { equals: ['contains'], url: ['url-contains'], title: ['title-contains'] };
+
+/** Does a passing `now` check prove the `was` check (both positive)? */
+export function impliesMatcher(now: string | undefined, was: string | undefined): boolean {
+  if (!now || !was || now === was) return false;
+  if (was.startsWith('all:') && !now.startsWith('all:')) return false;
+  const n = now.replace(/^all:/, '');
+  const w = was.replace(/^all:/, '');
+  return n === w || (IMPLIES[n] ?? []).includes(w);
+}
+
+const CONNECTORS = new Set(['with', 'has', 'have', 'contains', 'contain', 'includes', 'include', 'is', 'matches', 'in', 'to', 'and']);
+const elementType = (verb: string): string => {
+  const m = verb.match(/\[\] ([\w-]+)/);
+  return m && !CONNECTORS.has(m[1]) ? m[1] : '';
+};
+const isLiteral = (v: string | undefined): v is string => v !== undefined && !/\{\{|<[^>]+>/.test(v);
+const baseOf = (m: string | undefined): string => (m ?? '').replace(/^all:/, '');
+const rowsOf = (t: string[][] | undefined): string[] => (t ?? []).map((r) => JSON.stringify(r));
+const TEXT = new Set(['equals', 'contains']);
+
+/** x ⇒ y for two positive LITERAL text checks (equals / contains); null when they are not both that. */
+function literalImplies(x: ContractStep, y: ContractStep): boolean | null {
+  const bx = baseOf(x.matcher);
+  const by = baseOf(y.matcher);
+  if (!isLiteral(x.expected) || !isLiteral(y.expected) || !TEXT.has(bx) || !TEXT.has(by)) return null;
+  return by === 'equals' ? bx === 'equals' && x.expected === y.expected : x.expected.includes(y.expected);
+}
+
+export type AssertComparison = { class: 'strengthened' | 'review' | 'oracle-weakened'; detail: string };
+
+const show = (s: ContractStep): string => `${s.negated ? 'not ' : ''}${s.matcher ?? '?'}${s.expected !== undefined ? ` "${s.expected}"` : ''}`;
+
+/** Two assertions on the same target that are NOT identical. */
+export function compareAsserts(locked: ContractStep, current: ContractStep): AssertComparison {
+  const change = `${show(locked)} → ${show(current)}`;
+  const weak = (why: string): AssertComparison => ({ class: 'oracle-weakened', detail: `${why}: ${change}` });
+  const review = (why: string): AssertComparison => ({ class: 'review', detail: `${why}: ${change}` });
+  if (!!locked.negated !== !!current.negated) return weak('negation flipped');
+  const neg = locked.negated === true;
+  const [a, b] = neg ? [current, locked] : [locked, current];
+  const sa = matcherStrength(a.matcher);
+  const sb = matcherStrength(b.matcher);
+  if (sa === null || sb === null) return review(`the ladder cannot judge "${locked.verb}" → "${current.verb}"`);
+  if (a.expected !== undefined && b.expected === undefined) return weak(neg ? 'a value was added to a negated check' : 'expected value dropped');
+  if (a.table) {
+    const kept = new Set(rowsOf(b.table));
+    const lost = rowsOf(a.table).filter((r) => !kept.has(r)).length;
+    if (lost) return weak(`${lost} data-table row(s) ${neg ? 'added to a negated check' : 'removed or changed'}`);
+  }
+  if (literalImplies(a, b) === true && literalImplies(b, a) === false) return weak(neg ? 'a longer literal under a negated check' : 'a shorter literal under contains');
+  if (sb < sa) return weak('weaker check');
+  if (a.expected !== undefined && b.expected !== a.expected) return review('expected value changed');
+  const sameElement = sameJson(a.target, b.target) && elementType(a.verb) === elementType(b.verb) && rowsOf(a.table).length === rowsOf(b.table).length;
+  if (sameElement && impliesMatcher(b.matcher, a.matcher)) return { class: 'strengthened', detail: `stronger check: ${change}` };
+  return review('changed, and the new check does not prove the approved one');
+}

package/src/contract/project-contract-blockers.ts

@@ -0,0 +1,36 @@
+/**
+ * Which units' contracts hold a delivery back — for the Claude Code guard (OES-12.3, DOS-14.4).
+ *
+ * HEAD is read once (one `git ls-tree`, bounded by the caller's timeout). A unit with no lock in the
+ * working tree AND none in HEAD has no contract to break and is skipped without parsing anything.
+ * Every other unit gets its verdict rebuilt by buildContractVerdict — the same function `contract
+ * check` runs — and anything but `pass` blocks. A lock deleted from the working tree still counts
+ * while HEAD holds it. If git FAILS in a checkout that has .git while a delivered unit has a lock,
+ * this throws (GitUnavailableError): the guard asks rather than calling an unverifiable lock clean.
+ */
+import * as fs from 'fs';
+import { buildContractVerdict, ContractUnit, VerdictValue } from './build-contract-verdict';
+import { CLI_GIT_TIMEOUT_MS, GitUnavailableError, headSnapshot, posixRel } from './contract-git';
+import { HARD_CLASSES } from './contract-schema';
+import { lockPathFor } from './contracts-lock-file';
+
+export interface ContractBlocker { unit: string; verdict: Exclude<VerdictValue, 'pass'>; headline: string }
+
+export function contractBlockers(projectRoot: string, units: ContractUnit[], opts: { gitTimeoutMs?: number } = {}): ContractBlocker[] {
+  const unique = [...new Map(units.map((u) => [u.dir, u])).values()];
+  const snap = headSnapshot(projectRoot, opts.gitTimeoutMs ?? CLI_GIT_TIMEOUT_MS);
+  const hasWorkingLock = (u: ContractUnit): boolean => fs.existsSync(lockPathFor(u.dir));
+  if (snap.error && unique.some(hasWorkingLock)) throw new GitUnavailableError(snap.error);
+  const out: ContractBlocker[] = [];
+  for (const unit of unique) {
+    if (!hasWorkingLock(unit) && !snap.blobs?.has(posixRel(projectRoot, lockPathFor(unit.dir)))) continue;
+    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap });
+    if (v.verdict === 'pass') continue;
+    const worst = v.scenarios.find((s) => HARD_CLASSES.has(s.class)) ?? v.scenarios.find((s) => s.class === 'hash-changed');
+    const headline = worst
+      ? `${worst.id} ${worst.class}${worst.findings[0] ? ` (${worst.findings[0].detail})` : ''}`
+      : `${v.uncommitted.length} lock entr${v.uncommitted.length === 1 ? 'y is' : 'ies are'} not what QA approved and committed (${v.uncommitted[0]?.id} ${v.uncommitted[0]?.change})`;
+    out.push({ unit: unit.name, verdict: v.verdict, headline });
+  }
+  return out;
+}

package/src/contract/record-contract-approval.ts

@@ -0,0 +1,70 @@
+/**
+ * What an approval writes, once a human has confirmed it (DOS-14.3, DOS-14.4, takumi T5):
+ *
+ *   1. the secret guard over the exact lock text — a hit writes nothing at all
+ *   2. a `contract-approval` decision listing every approved scenario id + hash (and the removals)
+ *   3. the lock: each approved entry `humanApproved: true`, `decisionId` = that decision, and
+ *      `approvedAt` = its `valid_from` — the pair `contract check` cross-checks (M1)
+ *
+ * The decision goes first: a crash between the two leaves a record without a lock entry, never an
+ * entry pointing at nothing. Only `sungen contract approve` calls this after its TTY confirmation;
+ * the confirmation itself lives there (approve-contract.ts).
+ */
+import * as path from 'path';
+import { appendDecision } from '../decisions/append-decision';
+import { isValidScope } from '../decisions/decision-file';
+import type { JsonValue } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
+import { lockEntryFor, lockPathFor, serializeLock, writeLockFile } from './contracts-lock-file';
+import { assertNoLockSecrets } from './lock-secret-guard';
+
+export interface ApprovalWrite {
+  projectRoot: string;
+  unitDir: string;
+  unit: string;
+  approve: ContractScenario[];
+  removed: string[];
+  reason?: string;
+  lock: ContractLock | null;
+}
+
+export const DEFAULT_APPROVAL_REASON = 'QA reviewed the normalized Gherkin contract';
+
+/** The decision scope of a unit directory (`screens/login`, `api/flows/pay`…). */
+export function scopeOfUnitDir(projectRoot: string, unitDir: string): string {
+  const scope = path.relative(path.join(projectRoot, 'qa'), unitDir).split(path.sep).join('/');
+  if (!isValidScope(scope)) throw new Error(`${unitDir} is not a unit directory under qa/ (screens|flows|api/<unit>, api/flows/<flow>)`);
+  return scope;
+}
+
+export function nextLock(w: ApprovalWrite, decisionId: string, approvedAt: string): ContractLock {
+  const scenarios = { ...(w.lock?.scenarios ?? {}) };
+  for (const id of w.removed) delete scenarios[id];
+  for (const sc of w.approve) scenarios[sc.id] = lockEntryFor(sc, decisionId, approvedAt);
+  return { schema: LOCK_SCHEMA, scenarios };
+}
+
+/** Throws LockSecretError when the lock this approval would write carries a sensitive value. */
+export function checkApprovalSecrets(w: ApprovalWrite): void {
+  assertNoLockSecrets(w.approve, serializeLock(nextLock(w, 'D-0000000000000000', new Date().toISOString())));
+}
+
+export function recordContractApproval(w: ApprovalWrite): { decisionId: string; lock: ContractLock } {
+  const scope = scopeOfUnitDir(w.projectRoot, w.unitDir);
+  checkApprovalSecrets(w);
+  const payload: Record<string, JsonValue> = {
+    unit: w.unit,
+    scenarios: w.approve.map((s) => ({ id: s.id, hash: s.hash, implementation: s.implementation })),
+    removed: w.removed,
+  };
+  const decision = appendDecision(w.projectRoot, scope, {
+    kind: 'contract-approval', anchors: [], visibility: 'internal', valid_from: new Date().toISOString(), payload,
+    text: `Approved the Test Contract of ${w.unit}: ${[...w.approve.map((s) => s.id), ...w.removed.map((id) => `-${id}`)].join(', ')}`,
+    reason: w.reason?.trim() || DEFAULT_APPROVAL_REASON,
+    source: { by: gitUserName(w.projectRoot), where: 'cli' },
+  });
+  const lock = nextLock(w, decision.entry.id, decision.entry.valid_from);
+  writeLockFile(lockPathFor(w.unitDir), lock);
+  return { decisionId: decision.entry.id, lock };
+}

package/src/contract/render-free-gherkin.ts

@@ -0,0 +1,113 @@
+/**
+ * A trace's intent steps → Gherkin steps, deterministically (DOS-14.8): the same trace and the same
+ * identities give the same text, byte for byte. No LLM is involved — naming a scenario or suggesting
+ * a VP-id is left to the user (or an agent) and never touches the steps or the hash.
+ *
+ *   keywords   first step `Given`; the next action `When`, later actions `And`; a check after an
+ *              action `Then`, after a check `And`; an action after a check `When`
+ *   drops      a click on an element immediately followed by a fill of the SAME element (a focus click)
+ *   opaque     `User see opaque check "<source line>"` / `User do opaque step "<GET /api/x>"`, with a
+ *              `# opaque at <file>:<line>` comment — kept verbatim, always reviewed by a human
+ *   low        `# identity low: <why>` above any step whose target is not proven
+ *   safety     secrets typed into credential fields are redacted everywhere; machine paths scrubbed
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { displayPath, scrubKnownSecrets, scrubMachinePaths } from './field-semantic-redaction';
+import { normalizeShownText, TestDataIndex } from './data-normalize';
+import { renderTarget, sameTarget } from './render-trace-target';
+import { actionSentence, assertSentence, sensitiveStep } from './render-trace-sentence';
+import type { TargetFacts, TargetIdentity } from './trace/target-identity';
+import { isPageLevel } from './trace/trace-identity-resolution';
+import type { IntentStep } from './trace/trace-steps';
+
+export const CONTROL_CHARS = /[\u0000-\u001f\u007f\u2028\u2029]/g;
+
+export interface ResolvedTarget { identity: TargetIdentity; facts?: TargetFacts }
+export interface RenderedStep {
+  keyword: 'Given' | 'When' | 'Then' | 'And';
+  sentence: string;
+  kind: 'action' | 'assert';
+  /** The outermost `test.step` title (impl:code compares group by group). */
+  group?: string;
+  low?: string;
+  opaque?: { verbatim: string; where?: string };
+}
+export interface RenderContext { index: TestDataIndex; projectRoot: string; specFile?: string; secrets: Set<string> }
+
+function whereOf(step: IntentStep, ctx: RenderContext): { where?: string; line?: string } {
+  const loc = step.location;
+  if (!loc?.file) return {};
+  const own = ctx.specFile && (loc.file === ctx.specFile || loc.file.endsWith(`/${ctx.specFile}`) || path.basename(loc.file) === path.basename(ctx.specFile));
+  const file = own ? ctx.specFile! : displayPath(loc.file, ctx.projectRoot);
+  let line: string | undefined;
+  if (own) {
+    try { line = fs.readFileSync(path.join(ctx.projectRoot, ctx.specFile!), 'utf8').split(/\r?\n/)[loc.line - 1]?.trim(); } catch { line = undefined; }
+  }
+  return { where: `${file}:${loc.line}`, line };
+}
+
+const quoteVerbatim = (s: string): string => `"${normalizeShownText(s).replace(/"/g, "'").replace(/\s+/g, ' ').trim()}"`;
+
+function keywordFor(kind: 'action' | 'assert', prev: RenderedStep[]): RenderedStep['keyword'] {
+  const last = prev[prev.length - 1];
+  if (!last) return 'Given';
+  if (kind === 'assert') return last.kind === 'assert' ? 'And' : 'Then';
+  if (last.kind === 'assert') return 'When';
+  return prev.length === 1 && last.keyword === 'Given' ? 'When' : 'And';
+}
+
+export function renderTraceSteps(steps: IntentStep[], targets: Map<string, ResolvedTarget>, ctx: RenderContext): RenderedStep[] {
+  const out: RenderedStep[] = [];
+  steps.forEach((step, i) => {
+    const t = step.callId ? targets.get(step.callId) : undefined;
+    const next = steps[i + 1];
+    if (step.method === 'click' && next && (next.method === 'fill' || next.method === 'type') && sameTarget(t?.identity, next.callId ? targets.get(next.callId)?.identity : undefined)) return;
+    const group = step.group[0];
+    if (step.kind === 'opaque-assert' || step.kind === 'opaque-action') {
+      const { where, line } = whereOf(step, ctx);
+      const verbatim = step.kind === 'opaque-action' && /^[A-Z]+ /.test(step.verbatim ?? '') ? step.verbatim! : line || step.verbatim || step.method;
+      const kind = step.kind === 'opaque-assert' ? 'assert' : 'action';
+      const sentence = kind === 'assert' ? `User see opaque check ${quoteVerbatim(verbatim)}` : `User do opaque step ${quoteVerbatim(verbatim)}`;
+      out.push({ keyword: keywordFor(kind, out), sentence, kind, ...(group ? { group } : {}), opaque: { verbatim, ...(where ? { where } : {}) } });
+      return;
+    }
+    const target = isPageLevel(step) ? { text: '' } : renderTarget(t?.identity, t?.facts, typeof step.params.selector === 'string' ? step.params.selector : undefined);
+    const kind = step.kind === 'assert' ? 'assert' : 'action';
+    const sentence = kind === 'assert' ? assertSentence(step, target.text) : actionSentence(step, target.text, ctx, sensitiveStep(step, t?.facts, t?.identity.name));
+    out.push({ keyword: keywordFor(kind, out), sentence, kind, ...(group ? { group } : {}), ...(target.low ? { low: target.low } : {}) });
+  });
+  // Control characters (terminal escapes, BEL, line separators) would corrupt or spoof a Gherkin line.
+  const clean = (s: string): string => scrubMachinePaths(scrubKnownSecrets(s, ctx.secrets), ctx.projectRoot).replace(CONTROL_CHARS, '');
+  return out.map((s) => ({
+    ...s, sentence: clean(s.sentence), ...(s.low ? { low: clean(s.low) } : {}),
+    ...(s.opaque ? { opaque: { verbatim: clean(s.opaque.verbatim), ...(s.opaque.where ? { where: clean(s.opaque.where) } : {}) } } : {}),
+  }));
+}
+
+/** The Gherkin lines of one scenario's steps, with their comments. */
+export function stepLines(steps: RenderedStep[]): string[] {
+  const lines: string[] = [];
+  for (const s of steps) {
+    if (s.opaque) lines.push(`    # opaque${s.opaque.where ? ` at ${s.opaque.where}` : ''} — compared by a human, never automatically`);
+    if (s.low) lines.push(`    # identity low: ${s.low}`);
+    lines.push(`    ${s.keyword} ${s.sentence}`);
+  }
+  return lines;
+}
+
+export interface FreeScenarioBlock { id: string; title: string; tags: string[]; comments: string[]; steps: RenderedStep[] }
+
+export function scenarioBlockText(b: FreeScenarioBlock): string {
+  return [`  ${b.tags.join(' ')}`, `  Scenario: ${b.title}`, ...b.comments.map((c) => `    # ${c}`), ...stepLines(b.steps)].join('\n');
+}
+
+export const FREE_FEATURE_HEADER = [
+  '# Derived by `sungen contract derive` from Playwright traces — deterministic, no LLM.',
+  '# These steps are the contract; the Playwright test is the implementation. Each scenario stays a',
+  '# proposal (not counted by the audit) until QA approves it: sungen contract approve --screen <unit>',
+];
+
+export function freeFeatureText(unit: string, blocks: string[]): string {
+  return [...FREE_FEATURE_HEADER.map((l) => l.replace('<unit>', unit)), `Feature: ${unit} (free tests)`, '', ...blocks.flatMap((b) => [b, ''])].join('\n');
+}