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

package/src/decisions/legacy-waiver-migration.ts

@@ -0,0 +1,135 @@
+/**
+ * Waivers move from `.sungen/journey/<slug>.state.json` into the decision layer (DOS-13.5, red-team
+ * #2) — without laundering an agent-forged waiver into a hash-valid decision (review H1).
+ *
+ * The state file is agent-writable, so a legacy waiver is TRUSTED only when its record equals the
+ * one committed in git HEAD (a commit went through review; a local edit did not). Per obligation,
+ * with L = the legacy waiver and D = the decision in force:
+ *   L same as D                 → nothing to do (same reason against the same evidence)
+ *   L untrusted                 → not imported, not counted; needs-you says UNTRUSTED and how to confirm it
+ *   L trusted, no D             → import L (`where: migrated`, idempotent by content id)
+ *   L trusted, newer than D     → import L superseding D — an `at` in the future never counts as newer
+ *   L trusted, not newer than D → D wins; the dual-write corrects the legacy file
+ * The import runs ONCE per unit: when nothing untrusted remains, a marker is written and from then on
+ * the legacy file is only a dual-write target (so the previous CLI still reads the waivers), never a source.
+ *
+ * plan is read-only, so the board is the same whether or not the writes succeed. commit writes under
+ * the write-ahead sentinel; only an unwritable checkout is tolerated silently — a conflict is raised.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withMigrationSentinel } from '../basis/migration-sentinel';
+import { appendDecision, AppendResult } from './append-decision';
+import { canonicalJson, computeDecisionId } from './decision-identity';
+import { decisionsDirFor, unitDecisionScope } from './decision-file';
+import { DecisionDraft } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { committedJson } from './git-head-trust';
+import { formatCommand } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { asLegacyWaiver, effectiveWaiverEntries, isLegacyWaiver, LegacyWaiver, sameWaiver, waiverDraft } from './waiver-decisions';
+
+export interface UntrustedWaiver { obligation: string; waiver: LegacyWaiver }
+
+export interface WaiverSyncPlan {
+  scope: string | null;
+  /** obligation → waiver in force (legacy shape): what the board counts. */
+  waivers: Record<string, LegacyWaiver>;
+  untrusted: UntrustedWaiver[];
+  /** What the dual-write puts back in the legacy file: legacy key order, unknown records kept verbatim. */
+  stateWaivers: Record<string, unknown>;
+  imports: DecisionDraft[];
+  /** Write the import marker on commit: nothing untrusted is left to decide. */
+  markDone: boolean;
+}
+
+export const importMarkerPath = (projectRoot: string, slug: string): string =>
+  path.join(projectRoot, '.sungen', 'migrations', `${slug}.waivers-imported.json`);
+
+const asRecord = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {});
+const newer = (w: LegacyWaiver, validFrom: string): boolean => {
+  const at = Date.parse(w.at);
+  return at > Date.parse(validFrom) && at <= Date.now();
+};
+
+export function planWaiverSync(projectRoot: string, unit: string, slug: string, statePath: string, legacy: unknown): WaiverSyncPlan {
+  const legacyWaivers = asRecord(legacy);
+  const scope = unitDecisionScope(projectRoot, unit);
+  const inForce = scope ? effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries) : new Map();
+  const stateWaivers: Record<string, unknown> = { ...legacyWaivers };
+  const waivers: Record<string, LegacyWaiver> = {};
+  const untrusted: UntrustedWaiver[] = [];
+  const imports: DecisionDraft[] = [];
+
+  if (scope && fs.existsSync(importMarkerPath(projectRoot, slug))) {
+    for (const [ob, d] of inForce) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+    return { scope, waivers, untrusted, stateWaivers, imports, markDone: false };
+  }
+
+  const head = asRecord(asRecord(committedJson(projectRoot, statePath)).waivers);
+  for (const [ob, w] of Object.entries(legacyWaivers)) {
+    if (!isLegacyWaiver(w)) continue;                                 // unreadable record: kept in the file, never counted
+    const d = inForce.get(ob);
+    if (d && sameWaiver(asLegacyWaiver(d), w)) { waivers[ob] = w; continue; }
+    if (!(ob in head) || canonicalJson(head[ob]) !== canonicalJson(w)) { untrusted.push({ obligation: ob, waiver: w }); continue; }
+    if (d && !newer(w, d.valid_from)) { stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d); continue; }
+    if (scope) imports.push(waiverDraft(ob, w, { by: 'unknown', where: 'migrated' }, d?.id));
+    waivers[ob] = w;
+  }
+  for (const [ob, d] of inForce) if (!(ob in waivers)) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+  return { scope, waivers, untrusted, stateWaivers, imports, markDone: !!scope && untrusted.length === 0 };
+}
+
+/** The needs-you line for a waiver that is not in git HEAD: not counted, and how a human confirms it. */
+export function untrustedWaiverText(unit: string, slug: string, title: string, u: UntrustedWaiver): string {
+  const confirm = formatCommand(['sungen', 'journey', '--screen', unit, '--waive', u.obligation, '--reason', u.waiver.reason]);
+  return `⚠️ Waiver on "${title}" is UNTRUSTED — not counted (decision.in-run: it is in .sungen/journey/${slug}.state.json `
+    + `but not in git HEAD). If it is yours, confirm it on a terminal: ${confirm}`;
+}
+
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+function writeFile(file: string, text: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, 'utf-8');
+}
+
+/**
+ * Persist a plan: imports, the dual-written legacy file, the import marker. Returns false when the
+ * checkout cannot be written (read-only, full disk); any other failure — a decision that does not
+ * verify, a migration in progress or interrupted — is raised, never swallowed.
+ */
+export function commitWaiverSync(projectRoot: string, unit: string, slug: string, plan: WaiverSyncPlan, statePath: string, stateText: string): boolean {
+  const marker = importMarkerPath(projectRoot, slug);
+  const writeMarker = plan.markDone && !fs.existsSync(marker);
+  const markerText = (ids: string[]) => `${JSON.stringify({ schema: 1, unit, importedAt: new Date().toISOString(), imported: ids }, null, 2)}\n`;
+  try {
+    if (!plan.scope || plan.imports.length === 0) {
+      writeFile(statePath, stateText);
+      if (writeMarker) writeFile(marker, markerText([]));
+      return true;
+    }
+    const scope = plan.scope;
+    const dir = decisionsDirFor(projectRoot, scope);
+    const targets = plan.imports.map((d) => path.join(dir, `${computeDecisionId(d, scope)}.yaml`));
+    withMigrationSentinel(projectRoot, unit, slug, `import ${plan.imports.length} legacy waiver(s) into the decision layer`,
+      [statePath, ...(writeMarker ? [marker] : []), ...targets], () => {
+        const ids = plan.imports.map((d) => appendDecision(projectRoot, scope, d).entry.id);
+        writeFile(statePath, stateText);
+        if (writeMarker) writeFile(marker, markerText(ids));
+      });
+    return true;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return false;
+    throw err;
+  }
+}
+
+/** Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any. */
+export function recordWaiver(projectRoot: string, unit: string, obligation: string, w: LegacyWaiver): AppendResult {
+  const scope = unitDecisionScope(projectRoot, unit);
+  if (!scope) throw new Error(`Cannot record a waiver: "${unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api.`);
+  const current = effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries).get(obligation);
+  if (current && sameWaiver(asLegacyWaiver(current), w)) return { status: 'already-recorded', entry: current, path: current.path };
+  return appendDecision(projectRoot, scope, waiverDraft(obligation, w, { by: gitUserName(projectRoot), where: 'cli' }, current?.id));
+}

package/src/decisions/read-decisions.ts

@@ -0,0 +1,61 @@
+/**
+ * Read the decisions of one scope (DOS-13.1 – 13.3). Best-effort by contract: a missing directory
+ * reads as empty, a bad file becomes a `problem` — a read-only or half-broken checkout never throws.
+ *
+ * Only entries that verify against themselves take effect; an entry whose content no longer matches
+ * its id, or whose entry_hash no longer matches the entry, is reported and ignored (trust nothing
+ * written). Computed on read, never stored:
+ *   - `superseded_by` — the latest visible entry that names this one in `supersedes`
+ *   - `stale`         — with `auditHash` given: `evidence_hash ≠ auditHash` (the waiver rule, DOS-13.5)
+ * `asOf` hides entries whose `valid_from` is later, so a later superseder does not supersede yet.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DecisionEntry, DecisionKind } from './decision-schema';
+import { DecisionProblem, decisionsDirFor, verifyDecisionFile } from './decision-file';
+
+export interface ReadDecision extends DecisionEntry {
+  scope: string;
+  path: string;
+  superseded_by?: string;
+  stale?: boolean;
+}
+
+export interface ReadDecisionsOptions { asOf?: string; auditHash?: string; kind?: DecisionKind }
+export interface ReadDecisionsResult { entries: ReadDecision[]; problems: DecisionProblem[] }
+
+const byTime = (a: DecisionEntry, b: DecisionEntry): number =>
+  Date.parse(a.valid_from) - Date.parse(b.valid_from) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function readDecisions(projectRoot: string, scope: string, opts: ReadDecisionsOptions = {}): ReadDecisionsResult {
+  const problems: DecisionProblem[] = [];
+  let dir: string;
+  let names: string[];
+  try {
+    dir = decisionsDirFor(projectRoot, scope);
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+  } catch {
+    return { entries: [], problems };
+  }
+
+  const cutoff = opts.asOf ? Date.parse(opts.asOf) : Infinity;
+  const entries: ReadDecision[] = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    const v = verifyDecisionFile(file, scope);
+    if (v.problem) { problems.push(v.problem); continue; }
+    if (Date.parse(v.entry.valid_from) > cutoff) continue;
+    entries.push({ ...v.entry, scope, path: file });
+  }
+  entries.sort(byTime);
+
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  for (const e of entries) {
+    const target = e.supersedes ? byId.get(e.supersedes) : undefined;
+    if (target) target.superseded_by = e.id;   // ascending time: the latest superseder wins
+  }
+  if (opts.auditHash !== undefined) {
+    for (const e of entries) if (e.evidence_hash !== undefined) e.stale = e.evidence_hash !== opts.auditHash;
+  }
+  return { entries: opts.kind ? entries.filter((e) => e.kind === opts.kind) : entries, problems };
+}

package/src/decisions/viewpoint-baseline-adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * The accepted viewpoint baseline, seen as decisions — read-only (DOS-11.4; storage moves in P1).
+ *
+ * `sungen audit --accept-viewpoint` records `.sungen/viewpoint-baseline.json` (harness/viewpoint-
+ * baseline.ts). Each unit in it is projected as one `viewpoint-acceptance` decision, without moving or
+ * rewriting anything: no file is written here, ever.
+ *
+ * The file is agent-writable, so a unit is projected only while its record equals the one committed
+ * in git HEAD (review H1) — otherwise it would turn a local edit into a hash-valid decision. Anything
+ * not projected is reported: an `untrusted` unit, an `invalid` unit record, an `unreadable` file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson, sealDecision } from './decision-identity';
+import { DecisionProblem, PROJECT_SCOPE } from './decision-file';
+import { committedJson } from './git-head-trust';
+import { ReadDecision } from './read-decisions';
+
+/** Same location harness/viewpoint-baseline.ts writes. */
+const baselineFile = (projectRoot: string): string => path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+interface UnitRecord { hash: string; ids: string[]; recordedAt?: string; fileHash?: string }
+
+function isUnitRecord(v: unknown): v is UnitRecord {
+  const r = v as UnitRecord;
+  return !!r && typeof r === 'object' && typeof r.hash === 'string' && Array.isArray(r.ids) && r.ids.every((i) => typeof i === 'string');
+}
+const unitsOf = (raw: unknown): Record<string, unknown> | null => {
+  const u = (raw as { units?: unknown } | null)?.units;
+  return u && typeof u === 'object' && !Array.isArray(u) ? u as Record<string, unknown> : null;
+};
+
+function project(unit: string, r: UnitRecord, file: string): ReadDecision {
+  const at = typeof r.recordedAt === 'string' && !Number.isNaN(Date.parse(r.recordedAt)) ? new Date(r.recordedAt).toISOString() : EPOCH;
+  const entry = sealDecision({
+    kind: 'viewpoint-acceptance',
+    anchors: [],
+    text: `Accept the test-viewpoint declaration of ${unit} as the baseline`,
+    reason: 'Accepted with sungen audit --accept-viewpoint (legacy .sungen/viewpoint-baseline.json)',
+    payload: { unit, hash: r.hash, ids: r.ids, ...(typeof r.fileHash === 'string' ? { fileHash: r.fileHash } : {}) },
+    source: { by: 'unknown', where: 'legacy:viewpoint-baseline' },
+    valid_from: at,
+    visibility: 'internal',
+  }, PROJECT_SCOPE);
+  return { ...entry, scope: PROJECT_SCOPE, path: file };
+}
+
+export function viewpointAcceptanceDecisions(projectRoot: string): { entries: ReadDecision[]; problems: DecisionProblem[] } {
+  const file = baselineFile(projectRoot);
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  if (!fs.existsSync(file)) return { entries, problems };
+  let units: Record<string, unknown> | null;
+  try {
+    units = unitsOf(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (err) {
+    problems.push({ path: file, code: 'unreadable', message: `viewpoint baseline cannot be read: ${err instanceof Error ? err.message : String(err)}` });
+    return { entries, problems };
+  }
+  if (!units) return { entries, problems: [{ path: file, code: 'unreadable', message: 'viewpoint baseline has no `units` mapping' }] };
+
+  const committed = unitsOf(committedJson(projectRoot, file)) ?? {};
+  for (const unit of Object.keys(units).sort()) {
+    const r = units[unit];
+    if (!isUnitRecord(r)) { problems.push({ path: file, code: 'invalid', message: `viewpoint baseline record for ${unit} is malformed; not projected` }); continue; }
+    if (!(unit in committed) || canonicalJson(committed[unit]) !== canonicalJson(r)) {
+      problems.push({ path: file, code: 'untrusted', message: `viewpoint baseline for ${unit} is not the one in git HEAD — not taken as a decision (decision.in-run); commit it through review` });
+      continue;
+    }
+    entries.push(project(unit, r, file));
+  }
+  return { entries, problems };
+}

package/src/decisions/waiver-decisions.ts

@@ -0,0 +1,56 @@
+/**
+ * Journey waivers as decisions (DOS-13.5).
+ *
+ * A waiver entry is `kind: waiver`, `payload.obligation`, `evidence_hash` = the audit hash the waiver
+ * was given against (legacy `auditHashAtWaive`). Per obligation the waiver in force is the latest
+ * (by `valid_from`) entry that nothing supersedes. Whether it COUNTS is the old rule, unchanged: only
+ * while `evidence_hash` equals the current audit hash; otherwise it is STALE and goes back to a human.
+ */
+import { DecisionDraft, DecisionEntry, DecisionSource } from './decision-schema';
+import { ReadDecision } from './read-decisions';
+
+/** The legacy shape in `.sungen/journey/<slug>.state.json` — still dual-written for one release. */
+export interface LegacyWaiver { reason: string; at: string; auditHashAtWaive: string }
+
+const norm = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function isLegacyWaiver(w: unknown): w is LegacyWaiver {
+  const x = w as LegacyWaiver;
+  return !!x && typeof x === 'object' && typeof x.reason === 'string' && norm(x.reason).length > 0
+    && typeof x.at === 'string' && !Number.isNaN(Date.parse(x.at)) && typeof x.auditHashAtWaive === 'string';
+}
+
+/** Same decision: same reason against the same evidence (the time it was recorded does not matter). */
+export function sameWaiver(a: LegacyWaiver, b: LegacyWaiver): boolean {
+  return norm(a.reason) === norm(b.reason) && a.auditHashAtWaive === b.auditHashAtWaive;
+}
+
+export function waiverDraft(obligation: string, w: LegacyWaiver, source: DecisionSource, supersedes?: string): DecisionDraft {
+  return {
+    kind: 'waiver',
+    anchors: [],
+    text: `Waive ${obligation}`,
+    reason: w.reason,
+    payload: { obligation },
+    source,
+    valid_from: w.at,
+    ...(supersedes ? { supersedes } : {}),
+    visibility: 'internal',
+    evidence_hash: w.auditHashAtWaive,
+  };
+}
+
+export function asLegacyWaiver(e: DecisionEntry): LegacyWaiver {
+  return { reason: e.reason, at: e.valid_from, auditHashAtWaive: e.evidence_hash ?? '' };
+}
+
+/** obligation → the waiver entry in force. `entries` come from readDecisions (sorted by time). */
+export function effectiveWaiverEntries(entries: ReadDecision[]): Map<string, ReadDecision> {
+  const out = new Map<string, ReadDecision>();
+  for (const e of entries) {
+    const ob = e.payload?.obligation;
+    if (e.kind !== 'waiver' || e.superseded_by || typeof ob !== 'string') continue;
+    out.set(ob, e);   // ascending time: the latest wins
+  }
+  return out;
+}

package/src/exporters/matrix/build.ts

@@ -34,6 +34,7 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { CATALOG_GATE_RULES, GateRules } from '../../harness/gates/resolve-rule';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
@@ -128,6 +129,8 @@ export interface BuildInputs {
   specText?: string;
   /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
   apiCatalog?: Record<string, ApiCatalogEntry>;
+  /** The unit's gate rules (catalog + gate-overrides, OES-11.2); the catalog alone when absent. */
+  gateRules?: GateRules;
 }
 
 /**
@@ -594,7 +597,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     variantsByVp.set(v.vpId, list);
   }
 
-  const findings = runGates({ inputs, variants, variantsByVp });
+  const findings = runGates({ inputs, variants, variantsByVp, rules: inputs.gateRules });
   const stale = new Set(findings.filter((f) => f.gate === 'E' && f.ref).map((f) => f.ref as string));
 
   const items: DeliveryItem[] = map.groups.map((g) => {
@@ -660,22 +663,21 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
   // requirements/spec.md; @spec: traces mark `covered`; the map's `requirements:`
   // section carries the reviewed overrides (partially_covered / not_applicable / …).
   const requirements = computeRequirements(inputs.specText ?? '', map, items);
+  // Gate R levels come from the catalog like every other matrix gate (OES-11.2); `off` drops the finding.
+  const gateR = (rule: string, message: string): void => {
+    const { severity } = (inputs.gateRules ?? CATALOG_GATE_RULES).resolve(rule);
+    if (severity !== 'off') findings.push({ gate: 'R', severity, message });
+  };
   const gaps = requirements.filter((r) => r.status === 'gap');
   if (gaps.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`,
-    });
+    gateR('matrix.gate-r.requirement-gap', `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`);
   }
   // A `covered` claim with no traced variant is prose, not traceability: nothing
   // detects it when the proving scenario is later changed or deleted. Either tag
   // the scenario that proves it (`@spec:<id>`) or say where it IS covered.
   const unbacked = requirements.filter((r) => r.status === 'covered' && r.items.length === 0);
   if (unbacked.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`,
-    });
+    gateR('matrix.gate-r.covered-unbacked', `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`);
   }
 
   const variantCount = items.reduce((a, i) => a + i.variants.length, 0);

package/src/exporters/matrix/export.ts

@@ -28,6 +28,7 @@ import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
 import { RunEnvironment } from '../run-environment';
+import { GateRules } from '../../harness/gates/resolve-rule';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -50,6 +51,8 @@ export interface MatrixTargetPaths {
   mapFile: string;
   /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
   runEnv?: RunEnvironment;
+  /** The unit's gate rules (catalog + gate-overrides) — absent means the catalog alone. */
+  gateRules?: GateRules;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -94,6 +97,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
+    gateRules: paths.gateRules,
   });
   model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
@@ -132,6 +136,7 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog,
+    gateRules: paths.gateRules,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };