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

package/src/contract/contract-schema.ts

@@ -0,0 +1,137 @@
+/**
+ * The Test Contract's data model (DOS-14.1 – 14.4) and the strict check of a stored lock entry.
+ *
+ *   step   {kind: action|assert, verb, target?:{ref, also?, parent?, nth?}, value?, matcher?, expected?, negated?, table?}
+ *   lock   qa/<kind>/<unit>/contracts.lock.yaml → {schema: 1, scenarios: {<scenario id>: LockEntry}}
+ *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?}
+ *
+ * A stored entry is checked the way the decision layer checks its records: a wrong type or an
+ * UNKNOWN key is an error, because a field outside the hash could carry meaning the hash does not
+ * vouch for. `humanApproved` counts only when it is literally `true` (takumi T5).
+ */
+import { DECISION_ID_RE } from '../decisions/decision-schema';
+
+export const IMPLEMENTATIONS = ['compiled', 'impl:code', 'free'] as const;
+export type Implementation = typeof IMPLEMENTATIONS[number];
+
+export interface ContractTarget {
+  /** The first `[Reference]` of the step, or the data path of an `expect {{x}} …` step. */
+  ref: string;
+  /** Further `[References]` in the order written (`drag [A] to [B]`, `all [Card] contain [Child]`). */
+  also?: string[];
+  /** The `in [Parent] <container>` scope, as `<container> [<Parent>]` plus its `with` tail. */
+  parent?: string;
+  nth?: number;
+}
+
+export interface ContractStep {
+  kind: 'action' | 'assert';
+  /** The sentence with the actor dropped, refs as `[]`, values as `{}`, lowercased — the step's exact form. */
+  verb: string;
+  target?: ContractTarget;
+  /** An action's input: `{{var}}` kept as written, a literal without its quotes; several joined by ` | `. */
+  value?: string;
+  /** An assertion's check, from the closed vocabulary in oracle-strength.ts (`unknown` when it has none). */
+  matcher?: string;
+  /** An assertion's expected value(s), same form as `value`. */
+  expected?: string;
+  negated?: true;
+  /** The step's data table, header row first. */
+  table?: string[][];
+}
+
+export interface ContractScenario {
+  id: string;
+  implementation: Implementation;
+  steps: ContractStep[];
+  hash: string;
+  /** Where it was read — never hashed. `outline`: a Scenario Outline, which the compiler does not support. */
+  source: { file: string; name: string; hasId: boolean; lines: number[]; outline: boolean };
+}
+
+export interface LockEntry {
+  hash: string;
+  steps: ContractStep[];
+  implementation: Implementation;
+  approvedAt: string;
+  decisionId: string;
+  humanApproved?: true;
+}
+
+export const LOCK_SCHEMA = 1;
+export interface ContractLock { schema: typeof LOCK_SCHEMA; scenarios: Record<string, LockEntry> }
+
+export type LadderClass = 'match' | 'strengthened' | 'hash-changed' | 'oracle-weakened' | 'target-changed' | 'assertion-lost';
+/** Classes only a trace can produce (DOS-14.6) — free / impl:code scenarios. */
+export type TraceClass = 'opaque' | 'nondeterministic' | 'inconclusive' | 'unproven';
+export type ScenarioClass = LadderClass | 'proposed' | TraceClass;
+export type FindingClass = Exclude<LadderClass, 'match'> | 'lock-uncommitted' | TraceClass;
+
+/** Exit ≠ 0 (DOS-14.4, DOS-14.6). `unproven` applies to free / impl:code only. */
+export const HARD_CLASSES: ReadonlySet<string> = new Set(['oracle-weakened', 'target-changed', 'assertion-lost', 'lock-uncommitted', 'unproven']);
+/** Exit 0, but delivery waits for QA (DOS-14.4): changed-not-weaker, checks no code can compare, and an
+ *  approved free scenario whose final attempt did not pass (inconclusive — review decision M6). */
+export const REVIEW_CLASSES: ReadonlySet<string> = new Set(['hash-changed', 'opaque', 'inconclusive']);
+
+/** The catalog rule each class is reported under (gate-rules.yaml); `strengthened` has none. */
+export const RULE_OF: Readonly<Partial<Record<FindingClass, string>>> = {
+  'hash-changed': 'contract.hash-changed',
+  'oracle-weakened': 'contract.oracle-weakened',
+  'target-changed': 'contract.target-changed',
+  'assertion-lost': 'contract.assertion-lost',
+  'lock-uncommitted': 'contract.lock-uncommitted',
+  opaque: 'contract.opaque-step',
+  nondeterministic: 'contract.nondeterministic',
+  inconclusive: 'contract.inconclusive',
+  unproven: 'contract.unproven',
+};
+
+const STEP_KEYS = new Set(['kind', 'verb', 'target', 'value', 'matcher', 'expected', 'negated', 'table']);
+const TARGET_KEYS = new Set(['ref', 'also', 'parent', 'nth']);
+const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved']);
+const HASH_RE = /^[0-9a-f]{12}$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringList = (v: unknown): v is string[] => Array.isArray(v) && v.every((x) => typeof x === 'string');
+const unknownKeys = (o: Record<string, unknown>, allowed: Set<string>, at: string): string[] =>
+  Object.keys(o).filter((k) => !allowed.has(k)).map((k) => `${at}: unknown key "${k}"`);
+
+function targetErrors(t: unknown, at: string): string[] {
+  if (!isObject(t)) return [`${at}: target must be a mapping`];
+  const e = unknownKeys(t, TARGET_KEYS, at);
+  if (typeof t.ref !== 'string') e.push(`${at}: target.ref must be a string`);
+  if (t.also !== undefined && !isStringList(t.also)) e.push(`${at}: target.also must be a list of strings`);
+  if (t.parent !== undefined && typeof t.parent !== 'string') e.push(`${at}: target.parent must be a string`);
+  if (t.nth !== undefined && !(Number.isInteger(t.nth) && (t.nth as number) > 0)) e.push(`${at}: target.nth must be a positive integer`);
+  return e;
+}
+
+export function stepErrors(s: unknown, at: string): string[] {
+  if (!isObject(s)) return [`${at}: not a mapping`];
+  const e = unknownKeys(s, STEP_KEYS, at);
+  if (s.kind !== 'action' && s.kind !== 'assert') e.push(`${at}: kind must be action|assert`);
+  if (typeof s.verb !== 'string' || !s.verb) e.push(`${at}: verb is required`);
+  if (s.target !== undefined) e.push(...targetErrors(s.target, at));
+  for (const k of ['value', 'matcher', 'expected'] as const) if (s[k] !== undefined && typeof s[k] !== 'string') e.push(`${at}: ${k} must be a string`);
+  if (s.negated !== undefined && s.negated !== true) e.push(`${at}: negated is either true or absent`);
+  if (s.table !== undefined && !(Array.isArray(s.table) && s.table.every(isStringList))) e.push(`${at}: table must be rows of strings`);
+  return e;
+}
+
+/** Errors in one stored lock entry (empty = well-formed). The hash itself is checked by the reader. */
+export function lockEntryErrors(raw: unknown, id: string): string[] {
+  const at = `scenario ${id}`;
+  if (!isObject(raw)) return [`${at}: not a mapping`];
+  const e = unknownKeys(raw, ENTRY_KEYS, at);
+  if (typeof raw.hash !== 'string' || !HASH_RE.test(raw.hash)) e.push(`${at}: hash must be 12 hex characters`);
+  if (!IMPLEMENTATIONS.includes(raw.implementation as Implementation)) e.push(`${at}: implementation must be ${IMPLEMENTATIONS.join('|')}`);
+  if (typeof raw.approvedAt !== 'string' || Number.isNaN(Date.parse(raw.approvedAt))) e.push(`${at}: approvedAt must be an ISO-8601 timestamp`);
+  if (typeof raw.decisionId !== 'string' || !DECISION_ID_RE.test(raw.decisionId)) e.push(`${at}: decisionId must be D-<16 hex>`);
+  if (raw.humanApproved !== undefined && raw.humanApproved !== true) e.push(`${at}: humanApproved is either true or absent`);
+  if (!Array.isArray(raw.steps)) e.push(`${at}: steps must be a list`);
+  else raw.steps.forEach((s, i) => e.push(...stepErrors(s, `${at} step ${i + 1}`)));
+  return e;
+}
+
+/** Approved by a human on a TTY — and nothing else counts (an absent field is `proposed`, T5). */
+export const isHumanApproved = (entry: LockEntry | undefined): entry is LockEntry => entry?.humanApproved === true;

package/src/contract/contract-units.ts

@@ -0,0 +1,52 @@
+/**
+ * Which units a contract command or a `sungen delivery` call touches — the same units `delivery`
+ * enumerates (cli/commands/delivery.ts `listAllTargets` / `resolveTargetsFromArg`), restated here
+ * so the guard does not load the whole delivery command; a test pins the two enumerations together.
+ *
+ *   every unit       qa/screens/*, qa/flows/*, qa/api/* (not `flows`), and qa/api/flows/* as `flows/<name>`
+ *   a name           EVERY directory it can mean (a screen and a flow of one name are both checked);
+ *                    for delivery only, a name that is no unit falls back to the units hosting a
+ *                    feature file of that basename
+ *
+ * Names come from untrusted input (a Bash command): they are only compared with enumerated directory
+ * names, never joined into a path.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { featureFilesFor } from '../harness/unit-paths';
+
+export interface ContractUnitRef { name: string; dir: string }
+
+function subdirs(dir: string): string[] {
+  try { return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort(); } catch { return []; }
+}
+
+export function allContractUnits(root: string): ContractUnitRef[] {
+  const qa = path.join(root, 'qa');
+  const out: ContractUnitRef[] = [];
+  for (const kind of ['screens', 'flows', 'api']) {
+    for (const name of subdirs(path.join(qa, kind))) if (!(kind === 'api' && name === 'flows')) out.push({ name, dir: path.join(qa, kind, name) });
+  }
+  for (const name of subdirs(path.join(qa, 'api', 'flows'))) out.push({ name: `flows/${name}`, dir: path.join(qa, 'api', 'flows', name) });
+  return out;
+}
+
+/** Every unit directory `name` can mean (`pay` matches a flow `pay` and an api flow `flows/pay`). */
+export function contractUnitDirsNamed(root: string, name: string): ContractUnitRef[] {
+  return allContractUnits(root).filter((u) => u.name === name || u.name === `flows/${name}`);
+}
+
+/** The units `sungen delivery <name>` delivers. */
+export function deliveryUnitsNamed(root: string, name: string): ContractUnitRef[] {
+  const direct = contractUnitDirsNamed(root, name);
+  if (direct.length) return direct;
+  return allContractUnits(root).filter((u) => featureFilesFor(u.dir, u.name).some((f) => path.basename(f, '.feature') === name && fs.existsSync(f)));
+}
+
+/** The one unit a contract command names; an unknown or ambiguous name is an error, never a guess. */
+export function resolveContractUnit(root: string, name: string): ContractUnitRef {
+  const found = contractUnitDirsNamed(root, name);
+  if (found.length === 1) return found[0];
+  if (!found.length) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, qa/api/${name} or qa/api/flows/${name}`);
+  throw new Error(`"${name}" names ${found.length} units (${found.map((u) => path.relative(root, u.dir)).join(', ')}) — rename one so the contract knows which`);
+}

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

@@ -0,0 +1,97 @@
+/**
+ * `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 } : {}),
+      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,120 @@
+/**
+ * `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
+ *   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 { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
+import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
+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[];
+  note?: 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 }); }
+}
+
+/**
+ * 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.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())), 0);
+  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 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;
+}