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

package/src/decisions/confirmed-decision-commands.ts

@@ -0,0 +1,149 @@
+/**
+ * The journey CLI's human-gated actions (DOS-13.4), with the terminal passed in so the exact code the
+ * CLI runs on process.stdin/stderr is the code a test drives with a simulated TTY.
+ *
+ *   waive      `sungen journey --screen <u> --waive <OB> --reason …`                         phrase: the obligation id
+ *   signoff    `sungen journey --screen <u> --signoff [--by <name>]`                          phrase: SIGN-OFF (review W3)
+ *   decide     `sungen journey [--screen <u>] --decide <kind> --text … --reason … [--anchor …]` phrase: the kind
+ *   migration  a leftover write-ahead sentinel → REVERT or KEEP                                 (takumi T6)
+ *
+ * Everything that can be validated is validated BEFORE the prompt, so a human never confirms
+ * something that is then rejected — for a gate-override that includes the override rules (OES-11.3:
+ * soft rule, warning|info|off, `off` only where allowed, one unit or a glob in one kind, reason ≥ 15).
+ * `humanAccepted: true` is added to a gate-override's payload only AFTER the typed confirmation
+ * (takumi T5: present means effective) and can never be supplied through --payload.
+ * Without a TTY each refuses and prints the exact command.
+ */
+import * as path from 'path';
+import { assertNoPendingMigration, pendingMigrationState, PendingMigration, readPendingMigration, resolvePendingMigration, sentinelPath } from '../basis/migration-sentinel';
+import { parseAnchorId } from '../basis/anchor-grammar';
+import { assertCanSignOff, assertWaivable, JourneyReport, runJourney, signoff, signoffSigner, waive } from '../harness/journey';
+import { reportSlug } from '../harness/unit-paths';
+import { appendDecision, AppendResult } from './append-decision';
+import { PROJECT_SCOPE, unitDecisionScope } from './decision-file';
+import { DecisionDraft, DecisionKind, draftErrors, JsonValue } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { askMigrationChoice, ConfirmationIO, formatCommand, requireInteractive, requireTypedConfirmation } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { overridePayloadErrors } from '../harness/gates/gate-override-validation';
+
+export interface WaiveInput { projectRoot: string; unit: string; obligation: string; reason: string; io: ConfirmationIO }
+
+export async function waiveWithConfirmation(i: WaiveInput): Promise<JourneyReport> {
+  if (!i.reason || !i.reason.trim()) throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
+  assertWaivable(runJourney(i.projectRoot, i.unit), i.unit, i.obligation);
+  await requireTypedConfirmation({
+    what: `waive ${i.obligation} for ${i.unit}`,
+    phrase: i.obligation,
+    command: formatCommand(['sungen', 'journey', '--screen', i.unit, '--waive', i.obligation, '--reason', i.reason]),
+    summary: [`reason: ${i.reason.trim()}`, `recorded by: ${gitUserName(i.projectRoot)}`, 'it stops counting as soon as the audit changes (re-decide then)'],
+    io: i.io,
+  });
+  return waive(i.projectRoot, i.unit, i.obligation, i.reason);
+}
+
+export interface SignoffInput { projectRoot: string; unit: string; by?: string; io: ConfirmationIO }
+
+/**
+ * The single human gate (DOS §3.4, S5), typed by a person on a terminal: the gate suggests it, so an
+ * agent must not be able to give it. Refused before the prompt when the board cannot be signed off.
+ */
+export async function signoffWithConfirmation(i: SignoffInput): Promise<JourneyReport> {
+  const what = `sign off ${i.unit} (the single human gate before delivery)`;
+  const command = formatCommand(['sungen', 'journey', '--screen', i.unit, '--signoff', ...(i.by ? ['--by', i.by] : [])]);
+  requireInteractive(i.io, what, command);   // before the board is read: a refused sign-off writes nothing
+  const { signer, gitUser } = signoffSigner(i.projectRoot, i.unit, i.by);   // nobody to name → refused, no prompt
+  const before = runJourney(i.projectRoot, i.unit);
+  assertCanSignOff(before);
+  await requireTypedConfirmation({
+    what, phrase: 'SIGN-OFF', command,
+    summary: [`by: ${signer}${signer !== gitUser ? ` (recorded by git user ${gitUser})` : ''}`, `${before.needsYou.length} item(s) in the review queue — you have reviewed them`, 'it goes stale as soon as the audit changes (sign off again then)'],
+    io: i.io,
+  });
+  return signoff(i.projectRoot, i.unit, i.by);
+}
+
+/** Kinds `--decide` records. The others have a command of their own that computes their payload. */
+export const DECIDE_KINDS: readonly DecisionKind[] = ['gate-override', 'clarification'];
+const OWN_COMMAND: Partial<Record<DecisionKind, string>> = {
+  waiver: 'use `sungen journey --screen <unit> --waive <OB-id> --reason "..."`',
+  'contract-approval': 'it is recorded by `sungen contract approve`',
+  'viewpoint-acceptance': 'it is recorded by `sungen audit --accept-viewpoint`',
+};
+
+export interface DecideInput {
+  projectRoot: string; unit?: string; kind: string; text?: string; reason?: string; anchors?: string[];
+  payload?: string; visibility?: string; supersedes?: string; io: ConfirmationIO;
+}
+
+function decideDraft(i: DecideInput): { scope: string; draft: DecisionDraft } {
+  const kind = i.kind as DecisionKind;
+  if (!DECIDE_KINDS.includes(kind)) {
+    throw new Error(`--decide ${i.kind}: ${OWN_COMMAND[kind] ?? `kind must be one of ${DECIDE_KINDS.join(', ')}`}.`);
+  }
+  const errors: string[] = [];
+  const anchors = i.anchors ?? [];
+  for (const a of anchors) if (!parseAnchorId(a)) errors.push(`--anchor "${a}" is not a spec anchor (SPEC-ID#A-2, SPEC-ID#A-2/val or sec-<slug>)`);
+  let payload: Record<string, JsonValue> | undefined;
+  if (i.payload !== undefined) {
+    try {
+      const p = JSON.parse(i.payload);
+      if (p && typeof p === 'object' && !Array.isArray(p)) payload = p; else errors.push('--payload must be a JSON object');
+    } catch { errors.push('--payload is not valid JSON'); }
+  }
+  const scope = i.unit ? unitDecisionScope(i.projectRoot, i.unit) : PROJECT_SCOPE;
+  if (!scope) errors.push(`--screen ${i.unit} does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  if (kind === 'gate-override') {
+    if (payload && 'humanAccepted' in payload) errors.push('--payload must not carry humanAccepted — the terminal confirmation sets it');
+    else if (!payload) errors.push('--payload is required for a gate-override: {"rule","severity","scope"}');
+    else if (scope) errors.push(...overridePayloadErrors(payload, i.reason ?? '', scope).map((e) => `gate-override: ${e}`));
+  }
+  if (scope && i.supersedes && !readDecisions(i.projectRoot, scope).entries.some((e) => e.id === i.supersedes)) {
+    errors.push(`--supersedes ${i.supersedes} names no decision in ${scope === PROJECT_SCOPE ? 'qa/decisions' : `qa/${scope}/decisions`}`);
+  }
+  const draft = {
+    kind, anchors, text: i.text ?? '', reason: i.reason ?? '', ...(payload ? { payload } : {}),
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(),
+    ...(i.supersedes ? { supersedes: i.supersedes } : {}), visibility: (i.visibility ?? 'internal') as DecisionDraft['visibility'],
+  };
+  errors.push(...draftErrors(draft as unknown as Record<string, unknown>).map((e) => e.replace(/^text /, '--text ').replace(/^reason /, '--reason ')));
+  if (errors.length) throw new Error(`Cannot record the decision:\n  - ${errors.join('\n  - ')}`);
+  return { scope, draft };
+}
+
+export async function decideWithConfirmation(i: DecideInput): Promise<AppendResult> {
+  const { scope, draft } = decideDraft(i);
+  const argv = ['sungen', 'journey', ...(i.unit ? ['--screen', i.unit] : []), '--decide', draft.kind, '--text', draft.text, '--reason', draft.reason,
+    ...draft.anchors.flatMap((a) => ['--anchor', a]), ...(i.payload !== undefined ? ['--payload', i.payload] : []),
+    ...(draft.visibility !== 'internal' ? ['--visibility', draft.visibility] : []), ...(draft.supersedes ? ['--supersedes', draft.supersedes] : [])];
+  await requireTypedConfirmation({
+    what: `record a ${draft.kind} decision in ${scope === PROJECT_SCOPE ? 'qa/decisions' : `qa/${scope}/decisions`}`,
+    phrase: draft.kind,
+    command: formatCommand(argv),
+    summary: [`text: ${draft.text}`, `reason: ${draft.reason}`, ...(draft.anchors.length ? [`anchors: ${draft.anchors.join(', ')}`] : []),
+      ...(draft.payload ? [`payload: ${JSON.stringify(draft.payload)}`] : []), `visibility: ${draft.visibility}`, `recorded by: ${draft.source.by}`],
+    io: i.io,
+  });
+  // Present means effective (T5): only now, after a human typed the phrase, is the override accepted.
+  const confirmed = draft.kind === 'gate-override' ? { ...draft, payload: { ...draft.payload, humanAccepted: true } } : draft;
+  return appendDecision(i.projectRoot, scope, confirmed);
+}
+
+function assertNotInProgress(projectRoot: string, slug: string, pending: PendingMigration & { readable: boolean }): void {
+  if (pendingMigrationState(pending) === 'in-progress') assertNoPendingMigration(projectRoot, slug);   // throws MigrationInProgressError
+}
+
+/** A sentinel left by a killed migration: ask REVERT/KEEP on a TTY, refuse without one. null = none pending. */
+export async function answerPendingMigration(projectRoot: string, unit: string, io: ConfirmationIO): Promise<string[] | null> {
+  const slug = reportSlug(unit);
+  const pending = readPendingMigration(projectRoot, slug);
+  if (!pending) return null;
+  assertNotInProgress(projectRoot, slug, pending);   // another run migrating now: "retry", never a prompt
+  const files = pending.files.map((f) => `    ${f.existed ? 'restore' : 'remove '} ${f.path}`).join('\n');
+  const choice = await askMigrationChoice({
+    detail: `An interrupted migration left ${path.relative(projectRoot, sentinelPath(projectRoot, slug))} (started ${pending.startedAt}: ${pending.reason}).\n${files}`,
+    command: formatCommand(['sungen', 'journey', '--screen', unit]),
+    io,
+  });
+  return resolvePendingMigration(projectRoot, slug, choice);
+}

package/src/decisions/decision-file.ts

@@ -0,0 +1,93 @@
+/**
+ * Where decisions live and how one file reads and writes (DOS-13.1, DOS-3.9).
+ *
+ *   project scope   qa/decisions/<id>.yaml
+ *   unit scope      qa/<kind>/<unit>/decisions/<id>.yaml     scope = `<kind>/<unit>` (e.g. `screens/login`)
+ *
+ * The scope is not stored in the entry: it is where the file lives, and it is part of the id, so a
+ * file moved to another unit no longer matches its own id.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stringify } from 'yaml';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { DecisionEntry, storedEntryErrors } from './decision-schema';
+import { computeDecisionId, computeEntryHash } from './decision-identity';
+
+export const PROJECT_SCOPE = 'project';
+/** A decision file's path (`/`-separated, relative to the project): `…/decisions/<name>.yaml`. One test for every reader. */
+export const DECISION_FILE_PATH = /(^|\/)decisions\/[^/]+\.yaml$/;
+const UNIT_SCOPE_RE = /^(?:(?:screens|flows|api)\/(?!\.\.?$)[^/\\]+|api\/flows\/(?!\.\.?$)[^/\\]+)$/;
+
+export function isValidScope(scope: string): boolean {
+  return scope === PROJECT_SCOPE || UNIT_SCOPE_RE.test(scope);
+}
+
+export function decisionsDirFor(projectRoot: string, scope: string): string {
+  if (!isValidScope(scope)) throw new Error(`invalid decision scope "${scope}" (project, or <screens|flows|api>/<unit>)`);
+  return scope === PROJECT_SCOPE
+    ? path.join(projectRoot, 'qa', 'decisions')
+    : path.join(projectRoot, 'qa', ...scope.split('/'), 'decisions');
+}
+
+/** The unit scope for a unit name, or null when the name matches no unit or more than one. */
+export function unitDecisionScope(projectRoot: string, unit: string): string | null {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  if (found.length !== 1) return null;
+  const scope = path.relative(path.join(projectRoot, 'qa'), found[0].dir).split(path.sep).join('/');
+  return isValidScope(scope) ? scope : null;
+}
+
+/** Every decisions directory that exists, with its scope. */
+export function listDecisionDirs(projectRoot: string): { scope: string; dir: string }[] {
+  const qa = path.join(projectRoot, 'qa');
+  const out: { scope: string; dir: string }[] = [];
+  const add = (scope: string): void => {
+    const dir = decisionsDirFor(projectRoot, scope);
+    if (fs.existsSync(dir)) out.push({ scope, dir });
+  };
+  add(PROJECT_SCOPE);
+  const units = (rel: string): string[] => {
+    try {
+      return fs.readdirSync(path.join(qa, rel), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch { return []; }
+  };
+  for (const kind of ['screens', 'flows', 'api']) {
+    for (const u of units(kind)) if (!(kind === 'api' && u === 'flows')) add(`${kind}/${u}`);
+  }
+  for (const u of units('api/flows')) add(`api/flows/${u}`);
+  return out;
+}
+
+export function serializeDecision(entry: DecisionEntry): string {
+  const head = '# Sungen decision — append-only. To change it, record a new entry with `supersedes`.\n';
+  return head + stringify(entry, { schema: 'core', lineWidth: 0 });
+}
+
+/** `untrusted`: legacy approval state that differs from git HEAD (viewpoint-baseline adapter). */
+export type DecisionProblemCode = 'unreadable' | 'invalid' | 'id-mismatch' | 'hash-mismatch' | 'untrusted';
+export interface DecisionProblem { path: string; code: DecisionProblemCode; message: string }
+
+/**
+ * Read one decision file and verify it against itself: schema, file name = id, id = content
+ * (else `id-mismatch` → decision.id-reuse), entry_hash = entry (else `hash-mismatch` → decision.mutated).
+ * Never throws — a bad file is a problem, and the caller decides what that means.
+ */
+export function verifyDecisionFile(file: string, scope: string): { entry?: DecisionEntry; problem?: DecisionProblem } {
+  const fail = (code: DecisionProblemCode, message: string) => ({ problem: { path: file, code, message } });
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(fs.readFileSync(file, 'utf8'), file);
+  } catch (err) {
+    return fail('unreadable', err instanceof Error ? err.message : String(err));
+  }
+  const errors = storedEntryErrors(raw);
+  if (errors.length) return fail('invalid', errors.join('; '));
+  const entry = raw as DecisionEntry;
+  if (path.basename(file) !== `${entry.id}.yaml`) return fail('id-mismatch', `file name does not match its id ${entry.id}`);
+  const id = computeDecisionId(entry, scope);
+  if (id !== entry.id) return fail('id-mismatch', `stored id ${entry.id} but the content (in scope ${scope}) hashes to ${id}`);
+  if (computeEntryHash(entry) !== entry.entry_hash) return fail('hash-mismatch', 'entry_hash no longer matches the entry');
+  return { entry };
+}

package/src/decisions/decision-identity.ts

@@ -0,0 +1,73 @@
+/**
+ * Decision identity (DOS-13.2). Two hashes answer two different questions:
+ *
+ *   id         = `D-` + first 16 hex of sha256(normalized content)
+ *                content = {kind, scope, anchors (sorted), text, reason, payload, supersedes, visibility,
+ *                evidence_hash}; excludes valid_from, source, id, entry_hash
+ *                → "what was decided, where": re-recording it later, by anyone, yields the same id
+ *   entry_hash = full sha256 of the whole stored entry in canonical form (id, valid_from, source included)
+ *                → "was this file altered": changing any field, even the date, breaks it
+ *
+ * Canonical form: keys sorted, strings NFC with LF line ends and trimmed, absent fields omitted
+ * (`null` in the id content so its key set is fixed). The stored entry IS the normalized form, so a
+ * hash over the parsed file equals a hash over what was sealed.
+ */
+import { createHash } from 'crypto';
+import { DecisionDraft, DecisionEntry, JsonValue } from './decision-schema';
+
+const normText = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function canonicalize(v: unknown): unknown {
+  if (typeof v === 'string') return normText(v);
+  if (Array.isArray(v)) return v.map(canonicalize);
+  if (v && typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = (v as Record<string, unknown>)[k];
+      if (x !== undefined) out[k] = canonicalize(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+export const canonicalJson = (v: unknown): string => JSON.stringify(canonicalize(v));
+const sha256 = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+/** The draft as it is stored: normalized strings, sorted anchors, absent optionals dropped. */
+export function normalizeDraft(d: DecisionDraft): DecisionDraft {
+  const out: DecisionDraft = {
+    kind: d.kind,
+    anchors: d.anchors.map(normText).sort(),
+    text: normText(d.text),
+    reason: normText(d.reason),
+    ...(d.payload !== undefined ? { payload: canonicalize(d.payload) as Record<string, JsonValue> } : {}),
+    source: { by: normText(d.source.by), where: normText(d.source.where) },
+    valid_from: normText(d.valid_from),
+    ...(d.supersedes !== undefined ? { supersedes: normText(d.supersedes) } : {}),
+    visibility: d.visibility,
+    ...(d.evidence_hash !== undefined ? { evidence_hash: normText(d.evidence_hash) } : {}),
+  };
+  return out;
+}
+
+export function computeDecisionId(d: DecisionDraft, scope: string): string {
+  const n = normalizeDraft(d);
+  const content = {
+    kind: n.kind, scope, anchors: n.anchors, text: n.text, reason: n.reason, payload: n.payload ?? null,
+    supersedes: n.supersedes ?? null, visibility: n.visibility, evidence_hash: n.evidence_hash ?? null,
+  };
+  return `D-${sha256(canonicalJson(content)).slice(0, 16)}`;
+}
+
+export function computeEntryHash(entry: Omit<DecisionEntry, 'entry_hash'> & { entry_hash?: string }): string {
+  const { entry_hash: _ignored, ...rest } = entry;
+  return sha256(canonicalJson(rest));
+}
+
+/** Normalize a draft and give it its id and entry_hash, fields in storage order. */
+export function sealDecision(d: DecisionDraft, scope: string): DecisionEntry {
+  const n = normalizeDraft(d);
+  const withId = { id: computeDecisionId(n, scope), ...n };
+  return { ...withId, entry_hash: computeEntryHash(withId) };
+}

package/src/decisions/decision-integrity-check.ts

@@ -0,0 +1,61 @@
+/**
+ * Append-only integrity of the decision layer (DOS-13.3). Emits the catalog's hard rules — it does
+ * not define severity; phase 04's resolver decides what a finding blocks.
+ *
+ *   decision.id-reuse   stored id ≠ id of the content (edited text, renamed file, moved to another scope)
+ *   decision.mutated    entry_hash ≠ entry, an unreadable entry, or an entry in `git show HEAD:` that
+ *                       was edited or deleted in the working tree — the only check a careful forger
+ *                       who recomputes both hashes cannot pass
+ *
+ * Outside git (or with no commit yet) the HEAD comparison is skipped; it never throws.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { canonicalJson } from './decision-identity';
+import { DECISION_FILE_PATH, listDecisionDirs, verifyDecisionFile } from './decision-file';
+import { gitOutput as git } from './git-head-trust';
+
+export const DECISION_INTEGRITY_RULES = { idReuse: 'decision.id-reuse', mutated: 'decision.mutated' } as const;
+export type DecisionIntegrityRule = typeof DECISION_INTEGRITY_RULES[keyof typeof DECISION_INTEGRITY_RULES];
+export interface DecisionFinding { rule: DecisionIntegrityRule; path: string; message: string }
+
+
+/** Same meaning, whatever the line endings or YAML layout: compare the parsed entries canonically. */
+function sameEntry(a: string, b: string): boolean {
+  try {
+    return canonicalJson(safeYamlParse(a)) === canonicalJson(safeYamlParse(b));
+  } catch {
+    return a.replace(/\r\n?/g, '\n') === b.replace(/\r\n?/g, '\n');
+  }
+}
+
+export function checkDecisionIntegrity(projectRoot: string): DecisionFinding[] {
+  const out = new Map<string, DecisionFinding>();
+  const add = (rule: DecisionIntegrityRule, abs: string, message: string): void => {
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    if (!out.has(`${rule} ${rel}`)) out.set(`${rule} ${rel}`, { rule, path: rel, message });
+  };
+
+  for (const { scope, dir } of listDecisionDirs(projectRoot)) {
+    let names: string[] = [];
+    try { names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')); } catch { continue; }
+    for (const name of names) {
+      const file = path.join(dir, name);
+      const v = verifyDecisionFile(file, scope);
+      if (!v.problem) continue;
+      add(v.problem.code === 'id-mismatch' ? DECISION_INTEGRITY_RULES.idReuse : DECISION_INTEGRITY_RULES.mutated, file, v.problem.message);
+    }
+  }
+
+  const listed = git(projectRoot, ['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', 'qa']);
+  for (const rel of (listed ?? '').split('\0').filter((p) => DECISION_FILE_PATH.test(p))) {
+    const abs = path.join(projectRoot, ...rel.split('/'));
+    if (!fs.existsSync(abs)) { add(DECISION_INTEGRITY_RULES.mutated, abs, 'committed entry was deleted (append-only: supersede it instead)'); continue; }
+    const head = git(projectRoot, ['show', `HEAD:./${rel}`]);
+    if (head !== null && !sameEntry(head, fs.readFileSync(abs, 'utf8'))) {
+      add(DECISION_INTEGRITY_RULES.mutated, abs, 'committed entry was edited (append-only: record a superseding entry instead)');
+    }
+  }
+  return [...out.values()];
+}

package/src/decisions/decision-schema.ts

@@ -0,0 +1,76 @@
+/**
+ * Decision entry schema (DOS-13.2).
+ *
+ * `{id, kind, anchors[], text, reason, payload?, source:{by, where}, valid_from, supersedes?,
+ *   visibility: internal|client, evidence_hash?, entry_hash}`
+ *
+ * Validation is strict both ways: a draft is checked before it is written, and a stored entry is
+ * checked when read — an unknown key (a stored `superseded_by`, say) makes the entry invalid, because
+ * a field outside the id's content could carry meaning the id does not vouch for.
+ */
+export const DECISION_KINDS = ['waiver', 'gate-override', 'contract-approval', 'viewpoint-acceptance', 'clarification'] as const;
+export type DecisionKind = typeof DECISION_KINDS[number];
+export type DecisionVisibility = 'internal' | 'client';
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+export interface DecisionSource { by: string; where: string }
+
+export interface DecisionDraft {
+  kind: DecisionKind;
+  anchors: string[];
+  text: string;
+  reason: string;
+  payload?: Record<string, JsonValue>;
+  source: DecisionSource;
+  valid_from: string;
+  supersedes?: string;
+  visibility: DecisionVisibility;
+  evidence_hash?: string;
+}
+
+export interface DecisionEntry extends DecisionDraft { id: string; entry_hash: string }
+
+export const DECISION_ID_RE = /^D-[0-9a-f]{16}$/;
+const ENTRY_HASH_RE = /^[0-9a-f]{64}$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const STORED_KEYS = new Set(['id', 'kind', 'anchors', 'text', 'reason', 'payload', 'source', 'valid_from', 'supersedes', 'visibility', 'evidence_hash', 'entry_hash']);
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const nonEmpty = (v: unknown): boolean => typeof v === 'string' && v.trim().length > 0;
+
+function isJson(v: unknown, depth = 0): boolean {
+  if (depth > 20) return false;
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return true;
+  if (typeof v === 'number') return Number.isFinite(v);
+  if (Array.isArray(v)) return v.every((x) => isJson(x, depth + 1));
+  return isObject(v) && Object.values(v).every((x) => isJson(x, depth + 1));
+}
+
+/** Errors in a draft (empty = valid). Shared by the write boundary and the stored-entry check. */
+export function draftErrors(d: Record<string, unknown>): string[] {
+  const e: string[] = [];
+  if (!DECISION_KINDS.includes(d.kind as DecisionKind)) e.push(`kind must be one of ${DECISION_KINDS.join('|')}`);
+  if (!Array.isArray(d.anchors) || !d.anchors.every(nonEmpty)) e.push('anchors must be a list of non-empty strings');
+  if (!nonEmpty(d.text)) e.push('text is required');
+  if (!nonEmpty(d.reason)) e.push('reason is required');
+  if (d.payload !== undefined && !(isObject(d.payload) && isJson(d.payload))) e.push('payload must be a JSON object');
+  const src = d.source;
+  if (!isObject(src) || typeof src.by !== 'string' || !nonEmpty(src.where) || Object.keys(src).some((k) => k !== 'by' && k !== 'where')) {
+    e.push('source must be {by, where}');
+  }
+  if (typeof d.valid_from !== 'string' || !ISO_RE.test(d.valid_from) || Number.isNaN(Date.parse(d.valid_from))) e.push('valid_from must be an ISO-8601 timestamp');
+  if (d.supersedes !== undefined && (typeof d.supersedes !== 'string' || !DECISION_ID_RE.test(d.supersedes))) e.push('supersedes must be a decision id D-<16 hex>');
+  if (d.visibility !== 'internal' && d.visibility !== 'client') e.push('visibility must be internal|client');
+  if (d.evidence_hash !== undefined && typeof d.evidence_hash !== 'string') e.push('evidence_hash must be a string');
+  return e;
+}
+
+/** A stored entry: the draft rules plus id, entry_hash and no unknown keys. */
+export function storedEntryErrors(raw: unknown): string[] {
+  if (!isObject(raw)) return ['not a mapping'];
+  const e = draftErrors(raw);
+  for (const k of Object.keys(raw)) if (!STORED_KEYS.has(k)) e.push(`unknown key "${k}"`);
+  if (typeof raw.id !== 'string' || !DECISION_ID_RE.test(raw.id)) e.push('id must be D-<16 hex>');
+  if (typeof raw.entry_hash !== 'string' || !ENTRY_HASH_RE.test(raw.entry_hash)) e.push('entry_hash must be 64 hex');
+  return e;
+}

package/src/decisions/decision-source.ts

@@ -0,0 +1,14 @@
+/**
+ * Who recorded a decision: `git config user.name` — a name, never the email (DOS-13.2, security
+ * considerations). Best-effort: no git, no name → 'unknown'.
+ */
+import { execFileSync } from 'child_process';
+
+export function gitUserName(cwd: string): string {
+  try {
+    const name = execFileSync('git', ['config', 'user.name'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString('utf8').trim();
+    return name || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}

package/src/decisions/exclusive-file-create.ts

@@ -0,0 +1,42 @@
+/**
+ * Create a file only if its name is free, and never leave it half-written (red-team #13).
+ *
+ * The bytes go to a private tmp file opened with O_EXCL, are fsynced, then hard-linked to the final
+ * name. `link` fails with EEXIST when the name is taken, so the final file appears complete or not at
+ * all. On a filesystem without hard links an O_EXCL create of the final name keeps the exclusivity.
+ * Used for decision entries (same content → same name → "already recorded") and for the migration
+ * sentinel (two migrations of one unit cannot both believe they hold it).
+ */
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+
+const NO_HARD_LINKS = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV']);
+
+/** true = created, false = the name was already taken. Any other failure throws. */
+export function createFileExclusive(file: string, text: string): boolean {
+  const tmp = `${file}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+  const fd = fs.openSync(tmp, 'wx');
+  try {
+    fs.writeFileSync(fd, text);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.linkSync(tmp, file);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? '';
+    if (code === 'EEXIST') return false;
+    if (!NO_HARD_LINKS.has(code)) throw err;
+    try {
+      fs.writeFileSync(file, text, { flag: 'wx' });
+      return true;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === 'EEXIST') return false;
+      throw e;
+    }
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}

package/src/decisions/git-head-trust.ts

@@ -0,0 +1,32 @@
+/**
+ * What git HEAD says — the trust anchor for agent-writable state (red-team #3, review H1).
+ *
+ * `.sungen/` files are written by the CLI and, without the guard, by any agent. A record in them is
+ * trusted only where it equals its committed version: a commit went through review, a local edit
+ * did not. Outside git, or for a file git does not track, nothing is trusted. Never throws.
+ */
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+
+/** stdout of a git command run in `cwd`, or null when git fails (no repo, no HEAD, untracked path…). */
+export function gitOutput(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024, timeout: 30000 }).toString('utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** The committed text of `abs` (a file inside `projectRoot`), or null when git HEAD has no such file. */
+export function committedText(projectRoot: string, abs: string): string | null {
+  const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return gitOutput(projectRoot, ['show', `HEAD:./${rel}`]);
+}
+
+/** The committed JSON of `abs`, or null (absent from HEAD, or not JSON). */
+export function committedJson(projectRoot: string, abs: string): unknown {
+  const text = committedText(projectRoot, abs);
+  if (text === null) return null;
+  try { return JSON.parse(text.replace(/^/, '')); } catch { return null; }
+}