@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/contract/contracts-lock-file.ts

@@ -0,0 +1,98 @@
+/**
+ * `qa/<kind>/<unit>/contracts.lock.yaml` — read, check, write (DOS-14.3, DOS-13.8).
+ *
+ *   read   safe YAML (core schema, few aliases, no duplicate keys, byte cap); every entry checked
+ *          strictly. A structural problem throws ContractLockError — a lock that cannot be read is
+ *          not "nothing locked" (CLI exit 1, guard `ask`). An entry whose steps no longer hash to its
+ *          `hash` was edited by hand: it is returned in `tampered` and judged as a hard finding.
+ *   write  scenario ids sorted, one block per scenario, written atomically.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stringify } from 'yaml';
+import { writeFileAtomic } from '../harness/write-atomic';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { contractHash } from './contract-hash';
+import { ContractLock, ContractScenario, ContractStep, LOCK_SCHEMA, LockEntry, lockEntryErrors } from './contract-schema';
+
+export const LOCK_FILE_NAME = 'contracts.lock.yaml';
+export const lockPathFor = (unitDir: string): string => path.join(unitDir, LOCK_FILE_NAME);
+
+const HEADER = '# Sungen Test Contract lock (DOS-14.3) — written only by `sungen contract approve` on a terminal.\n'
+  + '# One block per scenario id. Commit it through review: `sungen contract check` compares it with git HEAD.\n';
+
+export class ContractLockError extends Error {
+  constructor(public readonly source: string, public readonly problems: string[]) {
+    super(`${source} cannot be trusted: ${problems.slice(0, 5).join('; ')}${problems.length > 5 ? ` (+${problems.length - 5} more)` : ''}. Restore it from git, or delete it and approve again on a terminal.`);
+    this.name = 'ContractLockError';
+  }
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * A lock as read. `tampered`: well-formed entries whose steps no longer hash to their `hash` — edited
+ * by hand. They are not a read error: they are a hard finding (`contract.lock-uncommitted`), so the
+ * delivery guard denies instead of asking.
+ */
+export interface ReadLock extends ContractLock { tampered: string[] }
+
+export function parseLockText(text: string, source: string): ReadLock {
+  let raw: unknown;
+  try { raw = safeYamlParse(text, source); } catch (e) { throw new ContractLockError(source, [e instanceof Error ? e.message : String(e)]); }
+  if (!isObject(raw)) throw new ContractLockError(source, ['not a mapping']);
+  const problems = Object.keys(raw).filter((k) => k !== 'schema' && k !== 'scenarios').map((k) => `unknown key "${k}"`);
+  if (raw.schema !== LOCK_SCHEMA) problems.push(`schema must be ${LOCK_SCHEMA}`);
+  if (!isObject(raw.scenarios)) problems.push('scenarios must be a mapping');
+  const scenarios = isObject(raw.scenarios) ? raw.scenarios : {};
+  const tampered: string[] = [];
+  for (const [id, entry] of Object.entries(scenarios)) {
+    const errors = lockEntryErrors(entry, id);
+    problems.push(...errors);
+    const e = entry as unknown as LockEntry;
+    if (!errors.length && contractHash(e.implementation, e.steps) !== e.hash) tampered.push(id);
+  }
+  if (problems.length) throw new ContractLockError(source, problems);
+  return { schema: LOCK_SCHEMA, scenarios: scenarios as Record<string, LockEntry>, tampered };
+}
+
+/** The lock at `file`, or null when there is none. Throws ContractLockError when it cannot be read as a lock. */
+export function readLockFile(file: string): ReadLock | null {
+  let text: string;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new ContractLockError(file, [e instanceof Error ? e.message : String(e)]);
+  }
+  return parseLockText(text, file);
+}
+
+/** The steps in their written key order, so the YAML reads the way DOS-14.1 lists the fields. */
+function orderedStep(s: ContractStep): ContractStep {
+  const t = s.target && { ref: s.target.ref, also: s.target.also, parent: s.target.parent, nth: s.target.nth };
+  const o = { kind: s.kind, verb: s.verb, target: t, value: s.value, matcher: s.matcher, expected: s.expected, negated: s.negated, table: s.table };
+  return JSON.parse(JSON.stringify(o)) as ContractStep;   // drops the undefined fields
+}
+
+export function serializeLock(lock: ContractLock): string {
+  const scenarios: Record<string, LockEntry> = {};
+  for (const id of Object.keys(lock.scenarios).sort((a, b) => a.localeCompare(b, 'en'))) {
+    const e = lock.scenarios[id];
+    scenarios[id] = {
+      hash: e.hash, implementation: e.implementation, approvedAt: e.approvedAt, decisionId: e.decisionId,
+      ...(e.humanApproved === true ? { humanApproved: true as const } : {}),
+      ...(e.acceptedOpaque?.length ? { acceptedOpaque: e.acceptedOpaque.map((a) => ({ step: a.step, sha: a.sha })) } : {}),
+      steps: e.steps.map(orderedStep),
+    };
+  }
+  return HEADER + stringify({ schema: LOCK_SCHEMA, scenarios }, { schema: 'core', lineWidth: 0 });
+}
+
+export function writeLockFile(file: string, lock: ContractLock): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  writeFileAtomic(file, serializeLock(lock));
+}
+
+/** The entry a TTY approval writes for one scenario. Only the approve path sets `humanApproved`. */
+export function lockEntryFor(sc: ContractScenario, decisionId: string, approvedAt: string): LockEntry {
+  return { hash: sc.hash, steps: sc.steps, implementation: sc.implementation, approvedAt, decisionId, humanApproved: true };
+}

package/src/contract/data-normalize.ts

@@ -0,0 +1,66 @@
+/**
+ * Dynamic data in a trace → stable contract values (DOS-14.6), so two runs of the same test give
+ * the same fingerprint:
+ *
+ *   a value equal to a test-data value      → `{{key}}`   (the unit's `test-data/<unit>.yaml`, flattened)
+ *   uuid                                    → `{{$dynamic:uuid}}`
+ *   ISO date / date-time                    → `{{$dynamic:iso-date}}`
+ *   epoch ms (13 digits) / s (10 digits)    → `{{$dynamic:timestamp}}`
+ *   any other run of 6+ digits              → `{{$dynamic:number}}`
+ *
+ * Dynamic parts are replaced INSIDE a value (`qa+1792638683664@x.dev` → `qa+{{$dynamic:timestamp}}@x.dev`).
+ * Test-data matches only on the WHOLE value, and only for values of 3+ characters — `1` or `ok` in
+ * test-data must not swallow every `1` a page shows. Several keys with one value → the first by name.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+
+export interface TestDataIndex { byValue: Map<string, string> }
+
+const DYNAMIC: Array<[RegExp, string]> = [
+  [/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, 'uuid'],
+  [/\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?/g, 'iso-date'],
+  [/(?<!\d)(?:1\d{12}|1\d{9})(?!\d)/g, 'timestamp'],
+  [/(?<!\d)\d{6,}(?!\d)/g, 'number'],
+];
+
+function flatten(v: unknown, prefix: string, out: Map<string, string>): void {
+  if (v === null || v === undefined) return;
+  if (typeof v === 'string' || typeof v === 'number') {
+    const s = String(v);
+    if (prefix && s.length >= 3 && !out.has(s)) out.set(s, prefix);
+    return;
+  }
+  if (Array.isArray(v)) { v.forEach((x, i) => flatten(x, `${prefix}.${i}`, out)); return; }
+  if (typeof v === 'object') {
+    for (const k of Object.keys(v as Record<string, unknown>).sort()) flatten((v as Record<string, unknown>)[k], prefix ? `${prefix}.${k}` : k, out);
+  }
+}
+
+/** The unit's base test-data file (environment overlays are not the contract's business). */
+export function loadTestDataIndex(unitDir: string, unit: string): TestDataIndex {
+  const file = path.join(unitDir, 'test-data', `${path.basename(unit)}.yaml`);
+  const byValue = new Map<string, string>();
+  if (!fs.existsSync(file)) return { byValue };
+  let doc: unknown;
+  try { doc = safeYamlParse(fs.readFileSync(file, 'utf8')); } catch (e) {
+    throw new Error(`cannot read ${path.basename(file)} to normalize trace values: ${(e as Error).message.split('\n')[0]}`);
+  }
+  flatten(doc, '', byValue);
+  return { byValue };
+}
+
+/** Replace the dynamic parts of a value; whole-value test-data matches win. */
+export function normalizeValue(value: string, index: TestDataIndex): string {
+  const key = index.byValue.get(value);
+  if (key) return `{{${key}}}`;
+  let out = value;
+  for (const [re, kind] of DYNAMIC) out = out.replace(re, `\u0000${kind}\u0001`);
+  return out.replace(/\u0000([a-z-]+)\u0001/g, '{{$dynamic:$1}}');
+}
+
+/** Names and texts the page shows: only the dynamic parts move (a name is never a test-data key). */
+export function normalizeShownText(text: string): string {
+  return normalizeValue(text, { byValue: new Map() });
+}

package/src/contract/derive-free-feature.ts

@@ -0,0 +1,153 @@
+/**
+ * `sungen contract derive --screen <u>` (DOS-14.8): free tests' traces → `features/<u>.free.feature`,
+ * every scenario tagged `@free @proposed`, built DETERMINISTICALLY from the trace — no LLM.
+ *
+ *   which tests   `--grep <re>` over "<id> <title> <file>", else those whose test file is named
+ *                 after the unit (a path segment `<u>`, or a file `<u>.*` / `<u>-*`)
+ *   which trace   the final attempt, passed, bound to its run (a failed one is skipped, never derived)
+ *   identities    asked of the registered `traceIdentity` resolver (driver-ui) when one is given,
+ *                 otherwise the cache, otherwise core's heuristic — `# identity low` marks those steps
+ *   approved      a scenario QA already approved (no `@proposed`) is never rewritten
+ *   one id, one   two recorded tests claiming one id (#962) refuse the derive — both named with
+ *   test          file:line, NOTHING written for the unit: keeping one would drop the other's contract
+ *   safety        redaction by field meaning, machine paths scrubbed, then the secret scanner and the
+ *                 semantic credential check over the exact text: any hit → NOTHING is written
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { readCapabilities } from '../harness/capability';
+import { isIdLike } from '../harness/parse';
+import { MOBILE_NOT_SUPPORTED } from './build-trace-conformance';
+import { loadTestDataIndex } from './data-normalize';
+import { scrubKnownSecrets, scrubMachinePaths, secretScanHits, SecretHit } from './field-semantic-redaction';
+import { idOfTitle, splitFeatureBlocks } from './free-feature-blocks';
+import { sensitiveLiteralHits } from './lock-secret-guard';
+import { scenariosOfFeatureFile } from './normalize-feature-steps';
+import { featureFilesFor } from '../harness/unit-paths';
+import { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
+import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
+import { idsClaimedByTwoTests } from './trace/scenario-id-claims';
+import { readIdentityCache } from './trace/identity-cache';
+import type { TraceIdentityResolver } from './trace/target-identity';
+import { identitiesFor, resolveWithDriver } from './trace/trace-identity-resolution';
+import { fingerprintOf } from './trace/trace-fingerprint';
+import { traceIntentSteps } from './trace/trace-steps';
+
+export interface DeriveInput { projectRoot: string; unit: { name: string; dir: string }; grep?: string; resolver?: TraceIdentityResolver | null }
+export interface DeriveResult {
+  file: string;
+  written: boolean;
+  scenarios: Array<{ id: string; title: string; steps: number; low: number; opaque: number }>;
+  /** `approved: true` — skipped because QA already approved it (derive never rewrites one), not for want of a trace. */
+  skipped: Array<{ id: string; reason: string; approved?: true }>;
+  refused?: SecretHit[];
+  /**
+   * Ids two or more recorded tests claim (#962), each test as `file:line "title" (run record <path>)` —
+   * nothing was written. `staleRecords`: older test-results/ records that are a claim's only source.
+   */
+  duplicateIds?: Array<{ id: string; tests: string[]; staleRecords?: string[] }>;
+  note?: string;
+  /** A derived id another `.feature` of the unit already uses (#939) — `contract check` and approve would trip on it later. */
+  warnings?: string[];
+}
+
+const MACHINE_PATH = /(?:\/Users|\/home)\/[^/\s"'`]+\/|[A-Za-z]:\\Users\\/;
+
+function belongsToUnit(testFile: string, unit: string): boolean {
+  const segs = testFile.toLowerCase().split(/[\\/]/);
+  const base = segs[segs.length - 1] ?? '';
+  return segs.slice(0, -1).includes(unit) || base.startsWith(`${unit}.`) || base.startsWith(`${unit}-`);
+}
+
+/** The semantic credential check over the text as it would be written. */
+function semanticHits(text: string, label: string): SecretHit[] {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-derive-'));
+  try {
+    const file = path.join(dir, label);
+    fs.writeFileSync(file, text);
+    return sensitiveLiteralHits(scenariosOfFeatureFile(file));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+/**
+ * The derived ids another `.feature` of the unit already carries (#939): `contract check` reports an id
+ * used twice and approve refuses it, so say it now — when it is still one rename away — not at check.
+ */
+function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string, ids: string[]): string[] {
+  const owners = new Map<string, string>();
+  for (const f of featureFilesFor(unit.dir, unit.name)) {
+    if (path.resolve(f) === path.resolve(freeFile) || !fs.existsSync(f)) continue;
+    try {
+      for (const sc of scenariosOfFeatureFile(f)) if (!owners.has(sc.id)) owners.set(sc.id, path.basename(f));
+    } catch { /* an unparseable sibling is `contract check`'s to report */ }
+  }
+  return ids.filter((id) => owners.has(id)).map((id) =>
+    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID, or its @tag) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
+}
+
+/**
+ * Nothing was derived and nothing explains it away: no test of the unit left an admissible trace
+ * (#932). Not when the scenarios are approved (derive leaves those alone by design), up to date,
+ * refused, or the project is mobile (`note`).
+ */
+export function nothingDerived(r: DeriveResult): boolean {
+  return !r.note && !r.refused?.length && !r.duplicateIds?.length && r.scenarios.length === 0 && !r.skipped.some((s) => s.approved);
+}
+
+export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
+  const unitBase = path.basename(i.unit.name);
+  const file = path.join(i.unit.dir, 'features', `${unitBase}.free.feature`);
+  const result: DeriveResult = { file, written: false, scenarios: [], skipped: [] };
+  if ((readCapabilities(i.projectRoot).platform ?? '').toLowerCase() === 'mobile') return { ...result, note: MOBILE_NOT_SUPPORTED };
+  const grep = i.grep ? new RegExp(i.grep, 'i') : null;
+  const found = collectRuns(i.projectRoot, (id, t) => (grep ? grep.test(`${id} ${t.title} ${t.file}`) : belongsToUnit(t.file, unitBase.toLowerCase())), null);
+  const claimed = idsClaimedByTwoTests(i.projectRoot, found.runs);
+  if (claimed.size) {
+    return { ...result, duplicateIds: [...claimed].sort(([a], [b]) => a.localeCompare(b, 'en')).map(([id, c]) => ({ id, tests: c.tests, ...(c.staleRecords.length ? { staleRecords: c.staleRecords } : {}) })) };
+  }
+  const byId = new Map<string, TraceRun[]>();
+  for (const r of found.runs) byId.set(r.scenarioId, [...(byId.get(r.scenarioId) ?? []), r]);
+  const admissible = (runs: TraceRun[]): TraceRun[] => runs.filter((r) => r.status === 'admissible' && r.trace)
+    .sort((a, b) => `${a.record?.file}|${a.test?.testId}`.localeCompare(`${b.record?.file}|${b.test?.testId}`));
+  if (i.resolver) await resolveWithDriver(i.projectRoot, [...byId.values()].flatMap(admissible).map((r) => r.trace!), i.resolver);
+
+  const { cache } = readIdentityCache(i.projectRoot);
+  const index = loadTestDataIndex(i.unit.dir, i.unit.name);
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const kept = splitFeatureBlocks(before);
+  const blocks = new Map(kept.map((b) => [b.id, b.text]));
+  for (const id of [...byId.keys()].sort((a, b) => a.localeCompare(b, 'en'))) {
+    const runs = admissible(byId.get(id)!);
+    if (!runs.length) { result.skipped.push({ id, reason: byId.get(id)![0].reason ?? 'no admissible trace' }); continue; }
+    if (kept.some((b) => b.id === id && !b.proposed)) { result.skipped.push({ id, reason: 'approved — derive never rewrites an approved scenario; use `sungen contract check --trace`', approved: true }); continue; }
+    const secrets = new Set<string>();
+    const rendered = runs.map((r) => {
+      const steps = traceIntentSteps(r.trace!);
+      return renderTraceSteps(steps, identitiesFor(r.trace!, steps, cache), { index, projectRoot: i.projectRoot, specFile: r.specFile, secrets });
+    });
+    const run = runs[0];
+    const rawTitle = run.test!.title;
+    const title = scrubMachinePaths(scrubKnownSecrets(idOfTitle(rawTitle) === id ? rawTitle : `${id} ${rawTitle}`, secrets), i.projectRoot).replace(CONTROL_CHARS, '');
+    const variants = new Set(rendered.map((r) => fingerprintOf(r, 'free').hash)).size;
+    const comments = [
+      `source: ${run.specFile}:${run.test!.line} · run ${run.record!.runId}${run.result!.retry ? ` (retry ${run.result!.retry})` : ''}`,
+      ...(variants > 1 ? [`nondeterministic: ${variants} runs fingerprint differently — derived from the first`] : []),
+      ...(isIdLike(id) ? [] : ['test outside the spec: no VP-id (spec missing, or the test is surplus)']),
+    ];
+    blocks.set(id, scenarioBlockText({ id, title, tags: ['@free', '@proposed'], comments, steps: rendered[0] }));
+    result.scenarios.push({ id, title, steps: rendered[0].length, low: rendered[0].filter((s) => s.low).length, opaque: rendered[0].filter((s) => s.opaque).length });
+  }
+  if (!result.scenarios.length) return result;
+  const reused = reusedIdWarnings(i.unit, file, result.scenarios.map((x) => x.id));
+  if (reused.length) result.warnings = reused;
+
+  const text = freeFeatureText(unitBase, [...blocks.values()]);
+  const label = path.basename(file);
+  const hits = [...(MACHINE_PATH.test(text) ? [{ where: label, reason: 'a machine path survived scrubbing' }] : []), ...secretScanHits(text, label), ...semanticHits(text, label)];
+  if (hits.length) return { ...result, refused: hits };
+  if (text === before) return result;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return { ...result, written: true };
+}

package/src/contract/field-semantic-redaction.ts

@@ -0,0 +1,80 @@
+/**
+ * Nothing secret, nothing machine-specific leaves a trace into a file sungen writes (DOS-14.7, G4).
+ * A login trace holds the password 13–14 times (step title, call params, snapshot value, request
+ * body) and up to 19 `/Users/…` paths (phase 07, R7).
+ *
+ *   by field meaning   a value typed into a field that IS a credential — `type=password`, or a name /
+ *                      id / autocomplete / label / accessible name that reads as one (password, token,
+ *                      secret, otp, api key…, whole words) — becomes `{{$redacted}}` (a test-data key
+ *                      wins when the value is in test-data: `{{login.password}}` is a reference)
+ *   everywhere else    every value redacted that way is also scrubbed from ALL other text written
+ *                      (expected texts, opaque verbatims, titles)
+ *   machine paths      the project root becomes relative; any other home directory becomes `~`
+ *   last line          the existing secret scanner runs over the exact text about to be written; a
+ *                      hit refuses the write — nothing is written, the place is named
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { scanTestDataSecrets } from '../harness/secret-scan';
+import { isSensitiveFieldName } from './lock-secret-guard';
+import type { TargetFacts } from './trace/target-identity';
+
+export const REDACTED = '{{$redacted}}';
+
+const CREDENTIAL_AUTOCOMPLETE = /(?:^|\s)(?:current-password|new-password|one-time-code|cc-number|cc-csc)(?:\s|$)/i;
+
+/** Is the element a value was typed into a credential field? */
+export function isSensitiveTarget(facts: TargetFacts | null | undefined, accessibleName?: string): boolean {
+  const a = facts?.attrs ?? {};
+  if ((a.type ?? '').toLowerCase() === 'password') return true;
+  if (CREDENTIAL_AUTOCOMPLETE.test(a.autocomplete ?? '')) return true;
+  return [a.name, a.id, a.autocomplete, a['aria-label'], a.placeholder, facts?.labelText, accessibleName].some((n) => isSensitiveFieldName(n));
+}
+
+/** Replace every occurrence of a known secret value in `text`. Values shorter than 4 chars are left (noise). */
+export function scrubKnownSecrets(text: string, secrets: Iterable<string>): string {
+  let out = text;
+  for (const s of [...new Set(secrets)].filter((x) => x.length >= 4).sort((a, b) => b.length - a.length)) out = out.split(s).join(REDACTED);
+  return out;
+}
+
+/** Project-relative paths; other home directories → `~` (`/Users/<name>`, `/home/<name>`, `C:\Users\<name>`). */
+export function scrubMachinePaths(text: string, projectRoot: string): string {
+  const root = path.resolve(projectRoot);
+  return text
+    .split(root + path.sep).join('')
+    .split(root).join('.')
+    .replace(/(?:\/Users|\/home)\/[^/\s"'`]+/g, '~')
+    .replace(/[A-Za-z]:\\Users\\[^\\\s"'`]+/g, '~');
+}
+
+/** A path for display: project-relative when inside the project, the basename otherwise. */
+export function displayPath(file: string, projectRoot: string): string {
+  const rel = path.relative(path.resolve(projectRoot), path.resolve(projectRoot, file));
+  return rel.startsWith('..') || path.isAbsolute(rel) ? path.basename(file) : rel.split(path.sep).join('/');
+}
+
+export interface SecretHit { where: string; reason: string }
+
+/** The secret scanner over the exact text about to be written to `label`. */
+export function secretScanHits(text: string, label: string): SecretHit[] {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-trace-scan-'));
+  try {
+    fs.mkdirSync(path.join(dir, 'test-data'));
+    fs.writeFileSync(path.join(dir, 'test-data', 'scan.yaml'), text);
+    const result = scanTestDataSecrets(dir);
+    if (result.unscanned.length) throw new Error(`the secret scan could not read the text it was given (${result.unscanned[0].reason})`);
+    return result.hits.map((h) => ({ where: `${label}:${h.line}`, reason: h.reason }));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export class TraceSecretError extends Error {
+  constructor(public readonly hits: SecretHit[]) {
+    super(`Refused: ${hits.length} likely secret(s) would be written. Nothing was written.\n${hits.map((h) => `  ${h.where} — ${h.reason}`).join('\n')}`
+      + '\n  Move the value into test-data (or an env overlay) and use it from there, then derive again.');
+    this.name = 'TraceSecretError';
+  }
+}

package/src/contract/free-feature-blocks.ts

@@ -0,0 +1,56 @@
+/**
+ * Scenario blocks of a derived `features/<unit>.free.feature` (DOS-14.8) — so `contract derive`
+ * can replace what is still `@proposed` while leaving every APPROVED scenario exactly as QA approved
+ * it, and `contract approve` can drop the `@proposed` tag of what it just locked.
+ *
+ * A block is a scenario's tag/comment lines directly above its `Scenario:` line, through the line
+ * before the next block. Its id is the title's leading id (`VP-LOGIN-001`), else the title — the
+ * same rule the contract uses.
+ */
+import * as fs from 'fs';
+import { isIdLike } from '../harness/parse';
+
+export interface FeatureBlock { id: string; proposed: boolean; text: string }
+
+const SCENARIO = /^\s*Scenario(?: Outline| Template)?:\s*(.*)$/;
+const TAG_OR_COMMENT = /^\s*(?:@|#)/;
+
+export function idOfTitle(title: string): string {
+  const lead = title.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+  return lead && isIdLike(lead) ? lead.toUpperCase() : title.replace(/\s+/g, ' ').trim();
+}
+
+export function splitFeatureBlocks(text: string): FeatureBlock[] {
+  const lines = text.split(/\r?\n/);
+  const featureAt = lines.findIndex((l) => /^\s*Feature:/.test(l));
+  const heads = lines.map((l, i) => (SCENARIO.test(l) && i > featureAt ? i : -1)).filter((i) => i >= 0);
+  const starts = heads.map((h, k) => {
+    let s = h;
+    const floor = k > 0 ? heads[k - 1] + 1 : featureAt + 1;
+    while (s - 1 >= floor && TAG_OR_COMMENT.test(lines[s - 1])) s--;
+    return s;
+  });
+  return heads.map((h, k) => {
+    const end = k + 1 < starts.length ? starts[k + 1] : lines.length;
+    const body = lines.slice(starts[k], end);
+    while (body.length && !body[body.length - 1].trim()) body.pop();
+    const tags = lines.slice(starts[k], h).filter((l) => /^\s*@/.test(l)).join(' ');
+    return { id: idOfTitle(SCENARIO.exec(lines[h])![1]), proposed: /(^|\s)@proposed(\s|$)/.test(tags), text: body.join('\n') };
+  });
+}
+
+/** Approve dropped the tag: remove `@proposed` from the given scenarios. Returns true when the file changed. */
+export function dropProposedTags(file: string, ids: ReadonlySet<string>): boolean {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  let changed = false;
+  let out = text;
+  for (const b of splitFeatureBlocks(text)) {
+    if (!b.proposed || !ids.has(b.id)) continue;
+    const next = b.text.split('\n').map((l) => (/^\s*@/.test(l) ? l.replace(/\s*@proposed(?=\s|$)/g, '') : l)).filter((l) => l.trim() !== '').join('\n');
+    out = out.replace(b.text, () => next);
+    changed = true;
+  }
+  if (changed) fs.writeFileSync(file, out);
+  return changed;
+}

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 };
+}