@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/harness/viewpoint-mode.ts

@@ -0,0 +1,49 @@
+/**
+ * Which create-test mode a unit's test-viewpoint.md calls for — the table in create-test.md,
+ * computed so the agent reads it from `sungen viewpoint scan` instead of inferring it.
+ *
+ *   mode 2 (AI drafts / re-reviews its draft): file missing · untouched scaffold · first line
+ *          `drafted-by: ai` · VP rows exist but none has a Kỳ vọng
+ *   mode 1 (review only, never edit): anything else — a QA-written file, with or without VP ids
+ *
+ * "Untouched scaffold" is checked on RAW lines against the template the scaffold is written from:
+ * apart from the first `# ` line (the title), every non-blank line must be a template line —
+ * comments included, so a QA note inside `<!-- -->` or under its own `# ` heading makes the file
+ * the QA's (owner decision 2026-10-14: a QA file is never overwritten). Every doubt falls to
+ * mode 1: a scaffold from an older sungen (other template lines) or an unreadable template.
+ */
+import { isAiDraft } from './viewpoint-draft-header';
+import { viewpointScaffold } from '../orchestrator/viewpoint-scaffold';
+
+export type ViewpointMode = 1 | 2;
+
+/** Trimmed non-blank lines without the title (the first `# ` line), BOM and CRLF ignored. */
+function bodyLines(text: string): string[] {
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n').map((l) => l.trim()).filter(Boolean);
+  const title = lines.findIndex((l) => l.startsWith('# '));
+  if (title >= 0) lines.splice(title, 1);
+  return lines;
+}
+
+let templateLines: Set<string> | null = null;
+function isUntouchedScaffold(raw: string): boolean {
+  if (!templateLines) {
+    try {
+      templateLines = new Set([false, true].flatMap((mobile) => bodyLines(viewpointScaffold('', mobile))));
+    } catch {
+      return false;   // no template to compare with → treat the file as the QA's
+    }
+  }
+  const known = templateLines;
+  return bodyLines(raw).every((l) => known.has(l));
+}
+
+/** `raw` is the file as written (null when missing); `rows` are its VP rows from the scan. */
+export function viewpointMode(raw: string | null, rows: { hasExpected: boolean }[]): { mode: ViewpointMode; reason: string } {
+  if (raw === null) return { mode: 2, reason: 'file missing' };
+  if (isAiDraft(raw)) return { mode: 2, reason: 'drafted-by: ai (re-review)' };
+  if (rows.length > 0) {
+    return rows.some((r) => r.hasExpected) ? { mode: 1, reason: 'QA-written' } : { mode: 2, reason: 'VP rows without Kỳ vọng' };
+  }
+  return isUntouchedScaffold(raw) ? { mode: 2, reason: 'untouched scaffold' } : { mode: 1, reason: 'QA-written, no VP ids' };
+}

package/src/harness/viewpoint-priority.ts

@@ -0,0 +1,38 @@
+/**
+ * One reading of a priority — a viewpoint row's cell or a scenario's tag.
+ *
+ * The overview parser, the ledger's uniform-priority check and PRIORITY-CONTRADICTED each read a
+ * priority their own way (`/high/i` substrings, raw words, a one-off medium→normal), so the same
+ * row could be `Medium` to one and `Unknown` to another — `Med`, which QA writes, was `Unknown`.
+ * The vocabulary is `high | normal | low`; `critical`, `medium` and `med` are read as aliases.
+ */
+export type PriorityLevel = 'high' | 'normal' | 'low' | 'deferred' | 'skip' | 'unknown';
+
+const WORD: Record<string, PriorityLevel> = {
+  critical: 'high', high: 'high',
+  medium: 'normal', med: 'normal', normal: 'normal',
+  low: 'low', deferred: 'deferred',
+};
+/** "Declared not applicable" — one level, so every consumer checks one word. */
+const NOT_APPLICABLE = /^(?:skip(?:ped)?|n\/a|none|not applicable)$/;
+
+/**
+ * A priority cell or tag → its level. The whole cell being a word is the clean case; otherwise the
+ * overview has always read prose by SUBSTRING in precedence order (`High — complex form`,
+ * `Medium-High`), and keeps doing so. The substring words stay unbounded for `high|medium|low`
+ * (existing behaviour); the newer `critical|normal|med` need word boundaries (`Medical` is not `Med`).
+ */
+export function parsePriority(cell: string): PriorityLevel {
+  const w = cell.replace(/[*_`]/g, '').replace(/\.+$/, '').trim().toLowerCase();
+  if (WORD[w]) return WORD[w];
+  if (NOT_APPLICABLE.test(w)) return 'skip';
+  if (/high|\bcritical\b/.test(w)) return 'high';
+  if (/medium|\bnormal\b|\bmed\b/.test(w)) return 'normal';
+  if (/low/.test(w)) return 'low';
+  return 'unknown';
+}
+
+/** The public `ViewpointEntry.priority` spelling of a level — the exported type is unchanged. */
+export function toEntryPriority(level: PriorityLevel): 'High' | 'Medium' | 'Low' | 'Unknown' {
+  return level === 'high' ? 'High' : level === 'normal' ? 'Medium' : level === 'low' ? 'Low' : 'Unknown';
+}

package/src/harness/viewpoint-review-open.ts

@@ -0,0 +1,51 @@
+/**
+ * VIEWPOINT-REVIEW-OPEN (info) — the audit's one line about `requirements/viewpoint-review.md`.
+ *
+ * create-test reviews test-viewpoint.md with the sungen-viewpoint checklist and writes each point a
+ * QA should look at as a table row whose last cell is `[ ]`; the QA ticks it `[x]` or deletes the
+ * row. While rows stay unticked the audit says how many, once. Advisory only: no score, no gate, no
+ * baseline effect. A missing or unreadable file says nothing — the review is optional input.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripHtmlComments } from './read-text';
+
+export const VIEWPOINT_REVIEW_FILE = 'viewpoint-review.md';
+
+const SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+/** A table separator, not a `---` rule under a row. */
+const isSeparator = (line: string): boolean => SEPARATOR.test(line) && line.includes('|');
+const UNTICKED = /^\[\s?\]$/;
+
+/** The last cell of a markdown table row, or null for a line that is not one. */
+function lastCell(line: string): string | null {
+  const t = line.trim();
+  if (!t.startsWith('|') || !t.endsWith('|') || t.length < 2) return null;
+  const cells = t.slice(1, -1).split(/(?<!\\)\|/);
+  return cells[cells.length - 1].trim();
+}
+
+/** Body rows whose last cell is `[ ]`. The header row (`… | [ ] |` above `|---|`) is not a point. */
+export function openReviewPoints(text: string): number {
+  const lines = stripHtmlComments(text.replace(/\r\n?/g, '\n')).split('\n');
+  let open = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (isSeparator(lines[i]) || isSeparator(lines[i + 1] ?? '')) continue;
+    const last = lastCell(lines[i]);
+    if (last !== null && UNTICKED.test(last)) open++;
+  }
+  return open;
+}
+
+/** The info finding for one unit's `requirements/` directory; empty when nothing is open. */
+export function viewpointReviewOpenFindings(requirementsDir: string): string[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(requirementsDir, VIEWPOINT_REVIEW_FILE), 'utf-8');
+  } catch {
+    return [];
+  }
+  const open = openReviewPoints(text);
+  if (open === 0) return [];
+  return [`VIEWPOINT-REVIEW-OPEN (info): ${open} open point(s) in requirements/${VIEWPOINT_REVIEW_FILE} — the checklist review of test-viewpoint.md is waiting for QA. QA: fix the viewpoint where you agree, then tick the row \`[x]\` or delete it. Not scored; an agent does not tick rows for the QA.`];
+}

package/src/harness/viewpoint-scan-refs.ts

@@ -0,0 +1,154 @@
+/**
+ * Building blocks of `sungen viewpoint scan` (viewpoint-scan.ts): the markdown table walker, the
+ * item-reference reader and the item universe. Pure, read-only, format-tolerant by design — a
+ * QA-written file is never judged here, only its ids and item numbers are read.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readTextFile, stripHtmlComments } from './read-text';
+import { parseUiInventory } from './ui-inventory';
+import { parseSpecClauses } from './spec-coverage';
+
+export interface TableRow {
+  /** 1-based line in the (comment-stripped, newline-preserving) text. */
+  line: number;
+  raw: string;
+  /** Cells with `**`, backticks and edge spaces removed. */
+  cells: string[];
+  /** The table's header cells; null for a table with no separator line. */
+  header: string[] | null;
+  /** Text of every heading enclosing the row (outermost first) — where a `# MANUAL/ENV` mark may sit. */
+  section: string;
+}
+
+const SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+const splitCells = (line: string): string[] => line.trim().replace(/^\|/, '').replace(/\|$/, '')
+  .split(/(?<!\\)\|/).map((c) => c.replace(/\*\*|`/g, '').trim());
+
+/** Every body row of every markdown table, with its header and enclosing headings. */
+export function tableRows(text: string): TableRow[] {
+  const lines = text.split('\n');
+  const out: TableRow[] = [];
+  const headings: string[] = [];   // index = level − 1
+  let header: string[] | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const h = raw.match(/^(#{1,6})\s+(.*)$/);
+    if (h) { headings.length = h[1].length - 1; headings[h[1].length - 1] = h[2]; header = null; continue; }
+    if (!raw.includes('|')) { header = null; continue; }
+    if (SEPARATOR.test(raw)) continue;
+    if (i + 1 < lines.length && SEPARATOR.test(lines[i + 1])) { header = splitCells(raw); continue; }
+    out.push({ line: i + 1, raw, cells: splitCells(raw), header, section: headings.join(' ') });
+  }
+  return out;
+}
+
+const NUM = String.raw`(?<!\d)\d{1,3}(?:\.\d{1,3})*(?![\d])`;
+const LIST = new RegExp(`(?:\\bitems?|項目|(?<![\\w-])UI[\\s-]*#?|#)\\s*(${NUM}(?:\\s*(?:[-–—~〜～,;&/]|(?<![\\p{L}\\p{N}])(?:và|and)(?![\\p{L}\\p{N}]))\\s*${NUM})*)`, 'giu');
+
+/** `009` → `9`, `4.03` → `4.3`; null when the text is not a plain (dotted) number. */
+export function normRef(s: string): string | null {
+  const t = s.replace(/[[\]§#]/g, '').trim();
+  return /^\d+(\.\d+)*$/.test(t) ? t.split('.').map((p) => String(Number(p))).join('.') : null;
+}
+
+/**
+ * The refs strictly between `a` and `b` (normalised): `4`–`6` → `5`, `5.4`–`5.8` → `5.5 … 5.7`.
+ * Only the last level steps, so both ends need the same prefix; `5.4–6.2` or `3–5.2` cannot be
+ * enumerated without the item list and give nothing.
+ */
+function between(a: string, b: string): string[] {
+  const pa = a.split('.');
+  const pb = b.split('.');
+  if (pa.length !== pb.length || pa.slice(0, -1).join('.') !== pb.slice(0, -1).join('.')) return [];
+  const lo = Number(pa[pa.length - 1]);
+  const hi = Number(pb[pb.length - 1]);
+  if (!(hi > lo && hi - lo < 200)) return [];
+  const prefix = pa.slice(0, -1).map((p) => `${p}.`).join('');
+  return Array.from({ length: hi - lo - 1 }, (_, k) => `${prefix}${lo + 1 + k}`);
+}
+
+/**
+ * Item numbers a cell cites: `item 9`, `item 2, 3, 7`, `item 4–6`, `item 5.4–5.8`, `項目 4.3〜4.6`, `UI #9`,
+ * `UI-009`, `[9]`, `§4.3.2`. Prose (`Auth guard`), message codes (`M02`) and question ids
+ * (`Q-01`) are not refs.
+ */
+export function extractRefs(text: string): string[] {
+  const refs = new Set<string>();
+  const add = (s: string): void => { const r = normRef(s); if (r) refs.add(r); };
+  for (const m of text.matchAll(LIST)) {
+    let prev: string | null = null;
+    let range = false;
+    for (const tok of m[1].matchAll(new RegExp(`(${NUM})|([-–—~〜～])`, 'g'))) {
+      if (tok[2]) { range = prev !== null; continue; }
+      const n = normRef(tok[1]);
+      if (!n) continue;
+      if (range && prev) for (const r of between(prev, n)) refs.add(r);
+      refs.add(n); prev = n; range = false;
+    }
+  }
+  for (const m of text.matchAll(/\[(\d{1,3})\]/g)) add(m[1]);
+  for (const m of text.matchAll(/§\s*(\d{1,3}(?:\.\d{1,3})*)/g)) add(m[1]);
+  return [...refs];
+}
+
+export type ItemSource = 'spec-ids' | 'spec-table' | 'spec-ids+spec-table' | 'ui-inventory' | 'none';
+export interface UniverseItem { ref: string; name: string }
+/** Every list a citation could point at, each in its own notation. */
+export interface ItemUniverses { specIds: UniverseItem[]; specTable: UniverseItem[]; inventory: UniverseItem[] }
+
+const NO_COL = /^(no\.?|#|stt|№|番号)$/i;
+const TYPE_COL = /種別|\b(type|kind)\b|loại/i;
+const NAME_COL = /item|name|tên|項目|名|field|label|trường|thành phần|component/i;
+
+/**
+ * The unit's lists, by where each id is DECLARED: requirement ids spec.md declares (`**FR-BC-03**:`),
+ * the spec's item table (`No` + name + type columns), and ui-inventory ids (`UI-NNN`). An id's shape
+ * says nothing about which list it belongs to — `item 9` on a mockup and `UI-009` in the inventory
+ * number different things.
+ */
+export function itemUniverses(reqDir: string): ItemUniverses {
+  const read = (f: string): string | null => {
+    const p = path.join(reqDir, f);
+    return fs.existsSync(p) ? stripHtmlComments(readTextFile(p)) : null;
+  };
+  const out: ItemUniverses = { specIds: [], specTable: [], inventory: [] };
+  const spec = read('spec.md');
+  if (spec) {
+    out.specIds = parseSpecClauses(path.join(reqDir, 'spec.md')).frs.map((f) => ({ ref: f.id, name: f.text.slice(0, 80) }));
+    for (const row of tableRows(spec)) {
+      const h = row.header;
+      const no = h?.findIndex((c) => NO_COL.test(c)) ?? -1;
+      const type = h?.findIndex((c) => TYPE_COL.test(c)) ?? -1;
+      const name = h?.findIndex((c, i) => i !== no && i !== type && NAME_COL.test(c)) ?? -1;
+      if (no < 0 || type < 0 || name < 0) continue;
+      const ref = normRef(row.cells[no] ?? '');
+      if (ref) out.specTable.push({ ref, name: row.cells[name] ?? '' });
+    }
+  }
+  const inv = read('ui-inventory.md');
+  if (inv) {
+    out.inventory = parseUiInventory(inv).items.flatMap((i) => {
+      const ref = normRef(i.id.replace(/^UI-/i, ''));
+      return ref ? [{ ref, name: i.item }] : [];
+    });
+  }
+  return out;
+}
+
+/**
+ * The list(s) the viewpoint actually cites — a list nobody cites says nothing about gaps. The spec's
+ * ids and its item table, each when cited (both when both are: the notations cannot collide, and
+ * dropping one would under-report); the table also when nothing is cited at all (then every item is
+ * uncited, which is true); the inventory only when the viewpoint writes `UI-NNN`; else none.
+ */
+export function citedUniverse(u: ItemUniverses, cited: ReadonlySet<string>, writesInventoryIds: boolean): { source: ItemSource; items: UniverseItem[] } {
+  const hits = (items: UniverseItem[]): boolean => items.some((i) => cited.has(i.ref));
+  const ids = hits(u.specIds);
+  const table = u.specTable.length > 0 && (cited.size === 0 || hits(u.specTable));
+  if (ids && table) return { source: 'spec-ids+spec-table', items: [...u.specIds, ...u.specTable] };
+  if (ids) return { source: 'spec-ids', items: u.specIds };
+  if (table) return { source: 'spec-table', items: u.specTable };
+  if (writesInventoryIds && hits(u.inventory)) return { source: 'ui-inventory', items: u.inventory };
+  return { source: 'none', items: [] };
+}

package/src/harness/viewpoint-scan.ts

@@ -0,0 +1,111 @@
+/**
+ * `sungen viewpoint scan` — the code half of reviewing a QA-written test-viewpoint.md.
+ *
+ * It does set arithmetic on ids and nothing else: which VP rows exist, what each cites, which spec
+ * items nobody cites, which ids no scenario carries. It never judges meaning, never edits the file,
+ * and feeds no audit finding, score or baseline.
+ *
+ * A VP row is a markdown table row whose FIRST cell is a full id (`VP-UI-001`, `FL-LOGIN-3`).
+ * Priority-table rows (`VP-LOGIN (Auth)`), bullets and appendix text are not rows. This is
+ * deliberately NOT `parseViewpointItems` (viewpoint-ledger.ts), which also reads id-less rows.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readViewpointText, readTextFile } from './read-text';
+import { featureFilesFor } from './unit-paths';
+import { tableRows, extractRefs, itemUniverses, citedUniverse, ItemSource } from './viewpoint-scan-refs';
+import { viewpointMode, ViewpointMode } from './viewpoint-mode';
+
+export interface VpRow {
+  id: string;
+  line: number;
+  /** Item numbers the row cites (normalised: `009` → `9`), and spec-declared ids it cites (`FR-BC-03`). */
+  refs: string[];
+  /** `# MANUAL/ENV` or `@manual` on the row or an enclosing heading. */
+  manual: boolean;
+  /** The Kỳ vọng / Expected cell has text (best effort when the table has no such header). */
+  hasExpected: boolean;
+}
+
+export interface ViewpointScan {
+  /** The create-test mode this file calls for (viewpoint-mode.ts): 2 = AI drafts, 1 = review only. */
+  mode: ViewpointMode;
+  modeReason: string;
+  vpRows: VpRow[];
+  /** Distinct VP ids among `vpRows` — a reused id is several rows but one id. */
+  distinctIds: number;
+  rowsWithoutExpected: string[];
+  manualRows: string[];
+  itemSource: ItemSource;
+  /** Spec/inventory items no VP row cites — a hint for the review, not a verdict. */
+  uncitedItems: { ref: string; name: string }[];
+  /** VP ids no feature file mentions; null when the unit has no feature file yet. */
+  withoutScenario: string[] | null;
+  /** Why `vpRows` is empty, else null. */
+  note: string | null;
+}
+
+const VP_ID = /^(VP|FL)-[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+$/;
+const MANUAL = /\bMANUAL\/ENV\b|@manual\b/i;
+const EXPECTED_COL = /kỳ vọng|kết quả mong đợi|expected|期待/i;
+/** Whole-word match (Unicode-aware: `\b` fails on `ồ`) so `Resource` / `Datasource` are not a source column. */
+const SOURCE_COL = /(?<![\p{L}\p{N}])(?:nguồn|source|tham chiếu|ref|出典|根拠)(?![\p{L}\p{N}])/iu;
+const PRIORITY = /^(critical|high|med(?:ium)?|low|cao|trung bình|thấp)$/i;
+const BLANK = /^[\s\-–—…]*$/;
+const SPEC_ID = /(?<![\w-])[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[A-Z]?(?![\w-])/gi;
+export const NO_VP_IDS_NOTE = 'file has no VP ids; review falls back to AI-only';
+
+/**
+ * VP rows of one viewpoint text (already comment-stripped, as `readViewpointText` returns it).
+ * `specIds`: the requirement ids spec.md declares — only those count as spec citations.
+ */
+export function scanViewpointText(text: string, specIds: ReadonlySet<string> = new Set()): VpRow[] {
+  const rows: VpRow[] = [];
+  for (const r of tableRows(text)) {
+    const id = r.cells[0];
+    if (!VP_ID.test(id)) continue;
+    const exp = r.header?.findIndex((c) => EXPECTED_COL.test(c)) ?? -1;
+    const src = r.header?.findIndex((c) => SOURCE_COL.test(c)) ?? -1;
+    const cites = src > 0 ? r.cells[src] ?? '' : r.cells.slice(1).join(' | ');
+    rows.push({
+      id,
+      line: r.line,
+      refs: [...extractRefs(cites), ...[...cites.matchAll(SPEC_ID)].map((m) => m[0].toUpperCase()).filter((id) => specIds.has(id))],
+      manual: MANUAL.test(r.raw) || MANUAL.test(r.section),
+      // Without a Kỳ vọng header: any later cell with text that is neither a priority word nor a ref.
+      hasExpected: exp > 0
+        ? !BLANK.test(r.cells[exp] ?? '')
+        : r.cells.slice(2).some((c) => !BLANK.test(c) && !PRIORITY.test(c) && extractRefs(c).length === 0),
+    });
+  }
+  return rows;
+}
+
+/** Scan one unit directory (`qa/screens/<n>`, `qa/flows/<n>`, …); `unit` names its feature files. */
+export function scanViewpointUnit(unitDir: string, unit: string): ViewpointScan {
+  const reqDir = path.join(unitDir, 'requirements');
+  const vpPath = path.join(reqDir, 'test-viewpoint.md');
+  const vpText = readViewpointText(vpPath);
+  const universes = itemUniverses(reqDir);
+  const vpRows = scanViewpointText(vpText, new Set(universes.specIds.map((i) => i.ref)));
+  const { mode, reason } = viewpointMode(fs.existsSync(vpPath) ? readTextFile(vpPath) : null, vpRows);
+  const cited = new Set(vpRows.flatMap((r) => r.refs));
+  const { source, items } = citedUniverse(universes, cited, /(?<![\w-])UI-\d{1,3}\b/i.test(vpText));
+  const features = featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f));
+  // Same rule as the ledger (viewpoint-ledger.ts): an id is carried when the feature text contains it.
+  const featureText = features.map((f) => readTextFile(f).toLowerCase()).join('\n');
+
+  return {
+    mode,
+    modeReason: reason,
+    vpRows,
+    distinctIds: new Set(vpRows.map((r) => r.id)).size,
+    rowsWithoutExpected: vpRows.filter((r) => !r.hasExpected).map((r) => r.id),
+    manualRows: vpRows.filter((r) => r.manual).map((r) => r.id),
+    itemSource: source,
+    uncitedItems: items.filter((i) => !cited.has(i.ref)),
+    withoutScenario: features.length === 0 ? null : vpRows.filter((r) => !featureText.includes(r.id.toLowerCase())).map((r) => r.id),
+    note: vpRows.length > 0 ? null
+      : fs.existsSync(vpPath) ? NO_VP_IDS_NOTE : 'requirements/test-viewpoint.md is missing',
+  };
+}

package/src/harness/write-atomic.ts

@@ -0,0 +1,22 @@
+/**
+ * Write a file so that a crash mid-write can never leave a truncated one behind: write a sibling
+ * tmp, then rename. Same directory = same device, so the rename is atomic; a concurrent writer is
+ * last-rename-wins. On failure the tmp is removed and the error rethrown — the caller still learns.
+ *
+ * `results merge` and `results sanitize` each grew this block inline, for the same reason and with
+ * the same comment. The third caller (`ai-skills/writer.ts`) did not, and its truncated manifest is
+ * precisely the corrupt input that #782's readers then absorbed in silence — so the two halves of
+ * that defect are one file apart.
+ */
+import * as fs from 'fs';
+
+export function writeFileAtomic(file: string, data: string): void {
+  const tmp = `${file}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup — the real error is below */ }
+    throw err;
+  }
+}

package/src/orchestrator/ai-skills/writer.ts

@@ -16,6 +16,8 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { BuiltFile } from './build';
 import { AdapterKey } from './adapters';
+import { readJsonConfig, warnUnreadableConfig } from '../../harness/config-file';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 export interface ApplyOptions { force?: boolean; dryRun?: boolean; version: string }
 export interface ApplyReport {
@@ -42,10 +44,21 @@ function adapterOf(relPath: string): AdapterKey | null {
   return null;
 }
 
+/**
+ * The manifest is what makes orphan cleanup possible: it is the only record of which files a
+ * PREVIOUS version managed. An unreadable one used to read as an empty one — so cleanup found
+ * nothing to remove, and the stale files it failed to remove are absent from the NEW manifest too.
+ * No later run can ever find them again. Say it, then carry on with what can still be done.
+ */
 function readManifest(cwd: string): Manifest {
   const p = path.join(cwd, MANIFEST_REL);
-  if (!fs.existsSync(p)) return { version: '', managed: {} };
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return { version: '', managed: {} }; }
+  const read = readJsonConfig<Manifest>(p);
+  if (read.state === 'unreadable') {
+    warnUnreadableConfig(p, read.error,
+      'orphan cleanup is skipped this run, so files managed by an older version stay in place');
+    return { version: '', managed: {} };
+  }
+  return read.state === 'ok' ? read.value : { version: '', managed: {} };
 }
 
 export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptions): ApplyReport {
@@ -121,7 +134,9 @@ export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptio
     Object.assign(mergedManaged, newManaged);
     const mPath = path.join(cwd, MANIFEST_REL);
     fs.mkdirSync(path.dirname(mPath), { recursive: true });
-    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: mergedManaged }, null, 2));
+    // Atomic: an interrupted `sungen init`/`update` must not leave a half-written manifest, because
+    // the reader above can only report that damage — it cannot undo it.
+    writeFileAtomic(mPath, JSON.stringify({ version: opts.version, managed: mergedManaged }, null, 2));
   }
   return r;
 }

package/src/orchestrator/assets-drift.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getPackageVersion } from '../exporters/package-info';
+import { readJsonConfig, warnUnreadableConfig } from '../harness/config-file';
 
 /**
  * Are this project's AI assets (commands + skills under `.claude/` etc.) the ones
@@ -27,12 +28,16 @@ export function checkAssetsDrift(cwd: string): AssetsDrift | null {
   const manifestPath = path.join(cwd, '.sungen', 'manifest.json');
   if (!fs.existsSync(manifestPath)) return null;   // not a sungen project (yet)
 
-  let manifest: { version?: string; managed?: Record<string, string> };
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return null;                                    // unreadable → say nothing
+  const read = readJsonConfig<{ version?: string; managed?: Record<string, string> }>(manifestPath);
+  if (read.state === 'unreadable') {
+    // This function IS the drift alarm. Staying silent on a broken manifest disables the only
+    // warning that a project's .claude/ assets have gone stale — and a truncated manifest is the
+    // likeliest way to get one (it is written non-atomically by `ai-skills/writer.ts`).
+    warnUnreadableConfig(manifestPath, read.error, 'stale-assets drift cannot be checked — re-run `sungen init` to rewrite it');
+    return null;
   }
+  if (read.state === 'absent') return null;
+  const manifest = read.value;
   const recordedVersion = manifest.version ?? '';
   const runningVersion = getPackageVersion();
   const managed = manifest.managed ?? {};

package/src/orchestrator/flow-manager.ts

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
+import { viewpointScaffold } from './viewpoint-scaffold';
 
 export interface FlowOptions {
   name: string;
@@ -143,7 +144,7 @@ export class FlowManager {
     fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');
 
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
-    fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
+    fs.writeFileSync(viewpointPath, viewpointScaffold(`${options.name} Flow`, isMobile), 'utf-8');
 
     console.log(`Created files:`);
     console.log(`  ${path.relative(this.cwd, featurePath)}`);
@@ -217,7 +218,7 @@ export class FlowManager {
       restored.push(file);
     };
     ensure(path.join(paths.requirementsDir, 'spec.md'), () => this.generateSpecTemplate(options, flowName, isMobile));
-    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => this.generateViewpointTemplate(options));
+    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => viewpointScaffold(`${options.name} Flow`, isMobile));
     ensure(paths.featurePath, () => this.generateFeatureTemplate(options, flowName, isMobile));
     return restored;
   }
@@ -287,57 +288,6 @@ export class FlowManager {
 `;
   }
 
-  private generateViewpointTemplate(options: FlowOptions): string {
-    return [
-      `# ${options.name} Flow — Test Viewpoints`,
-      '',
-      '## Edge Cases',
-      '',
-      '<!-- Sample — replace with actual edge cases for this flow:',
-      '- Network drops between screen transitions — should resume or show error?',
-      '- Session expires mid-flow — should redirect to login and preserve progress?',
-      '- Browser back button at step 3 — should return to step 2 with data intact?',
-      '- Complete flow twice rapidly — should prevent duplicate submissions',
-      '-->',
-      '',
-      '## Known Issues',
-      '',
-      '<!-- Sample — replace with actual known issues:',
-      '- [BUG-001] Form data lost if user navigates away and returns',
-      '- [BUG-002] Confirmation page shows stale data on slow connections',
-      '-->',
-      '',
-      '## Design Decisions',
-      '',
-      '<!-- Sample — replace with actual design decisions:',
-      '- Flow requires completing all steps in order (no skip)',
-      '- Draft is auto-saved at each step transition',
-      '- Cancel at any step discards the entire flow',
-      '-->',
-      '',
-      '## Cross-Screen Concerns',
-      '',
-      '<!-- Sample — replace with actual cross-screen concerns:',
-      '- Auth role must remain consistent across all screens',
-      '- Data entered in step 1 must be visible in confirmation (step 3)',
-      '- Error in step 2 should allow returning to step 1 without re-entering data',
-      '-->',
-      '',
-      '## Priority Viewpoints',
-      '',
-      '<!-- Rate importance for this flow (High / Medium / Low / Skip):',
-      '',
-      '| VP | Priority | Reason |',
-      '|---|----------|--------|',
-      '| VP-UI | Medium | Standard forms across screens |',
-      '| VP-VAL | High | Cross-screen validation rules |',
-      '| VP-LOGIC | High | Multi-step business logic, state transitions |',
-      '| VP-SEC | Medium | Auth must persist, role-based access at each screen |',
-      '-->',
-      '',
-    ].join('\n');
-  }
-
   private generateFeatureTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     const description = options.description || `complete the ${options.name} flow`;
 

package/src/orchestrator/project-deps-sync.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveDriverVersion } from './lockstep-version';
+import { ensureSecurityOverrides, reportSecurityOverrides } from './security-overrides';
 
 /**
  * Project-local sync of the sungen package family after a global `sungen update`.
@@ -143,8 +144,29 @@ export function syncProjectSungenDeps(cwd: string, core: string, dryRun: boolean
   }
   for (const s of plan.skipped) console.log(`   – skipped  ${s.pkg} — ${s.why}`);
 
+  // A project scaffolded before #764 carries no security overrides, and npm will never pick them up
+  // from sungen's own manifest — `sungen update` is the one pass that can put them there. Write them
+  // before any install below, since npm reads `overrides` when it resolves.
+  const overridePlan = ensureSecurityOverrides(path.join(cwd, 'package.json'), dryRun);
+  reportSecurityOverrides(overridePlan, dryRun);
+
   if (!plan.specs.length) {
-    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}\n`);
+    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}`);
+    // Family already in lockstep, so nothing would re-resolve — but freshly written overrides only
+    // reach the tree through a resolution pass. Run one.
+    if (overridePlan?.add.length) {
+      if (dryRun) {
+        console.log('   [dry-run] would run: npm install  (re-resolve under the new security overrides)\n');
+        return true;
+      }
+      console.log('   📦 npm install  (re-resolving under the new security overrides)');
+      const r = spawnSync('npm', ['install'], { cwd, stdio: 'inherit', shell: true });
+      if (r.status !== 0) {
+        console.warn('⚠️  Overrides were written to package.json but `npm install` failed — run it by hand.\n');
+        return false;
+      }
+    }
+    console.log('');
     return true;
   }