@sun-asterisk/sungen 3.2.32 → 3.2.34

package/src/harness/spec-coverage.ts

@@ -9,6 +9,7 @@
  * Generic: no project data.
  */
 import * as fs from 'fs';
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
 
@@ -139,7 +140,11 @@ function directionCovered(block: string, dir: FrDirection, subject: string[]): b
   const pool = lines.length ? lines : [block];
   // Narrow to the lines about the clause's element when the suite names it the same way the spec
   // does; a spec in one language and selector keys in another must not read as "no evidence".
-  const about = subject.length ? pool.filter((l) => subject.some((x) => l.includes(x))) : [];
+  // Word-aware (#779), or the narrowing lets in a line about something else and then trusts it:
+  // `under·score` is not a mention of `Score`, but it selected the only absence assertion in the
+  // block and so proved a MUST NOT clause about the Score. (`keywordHit` keeps substring semantics
+  // for a non-ASCII element name, which is what the cross-language case above depends on.)
+  const about = subject.length ? pool.filter((l) => subject.some((x) => keywordHit(l, x))) : [];
   const scan = about.length ? about : pool;
   return scan.some((l) => NEGATIVE_ASSERTION.test(l) === (dir.polarity === 'negate'));
 }
@@ -269,7 +274,12 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     const cited = featLower.includes(idLower) || cites.has(fr.id.toUpperCase());
     const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
       .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
-    const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));
+    // Word-aware, not substring (#779). `haystack.includes('format')` is satisfied by
+    // in·format·ion and `includes('length')` by wave·length, and two such collisions clear the
+    // `>= 2 words` bar as easily as one — so a MUST clause nobody tested read as covered. The
+    // threshold is a separate judgement (is one word enough evidence?) and is unchanged; see
+    // keyword-match.ts for why the boundary is leading-only.
+    const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => keywordHit(s.haystack, w)).length >= Math.min(2, words.length));
     if (!cited && !kwHit) {
       if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
       continue;
@@ -279,7 +289,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     // Which scenarios speak for this requirement — by its id (tags and comments sit in the block)
     // or by the same keyword rule used above.
     const owning = blocks.filter((b) => b.includes(idLower)
-      || (words.length > 0 && words.filter((w) => b.includes(w)).length >= Math.min(2, words.length)));
+      || (words.length > 0 && words.filter((w) => keywordHit(b, w)).length >= Math.min(2, words.length)));
     // Cited from outside any scenario (a header comment): nothing to judge a direction against, so
     // report nothing rather than invent a gap.
     if (!owning.length) { frCovered += units; continue; }
@@ -299,7 +309,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     // blocks that belong to this constraint: cite its msg code (primary), or mention a
     // DISTINCTIVE constraint word (generic words filtered to avoid matching happy paths).
     const own = blocks.filter((b) =>
-      (row.code && b.includes(row.code.toLowerCase())) || kw.some((w) => b.includes(w)),
+      (row.code && b.includes(row.code.toLowerCase())) || kw.some((w) => keywordHit(b, w)),
     );
     if (!own.length) continue; // constraint has no scenarios at all — FR/viewpoint gate covers that
     const found = [...new Set(own.flatMap((b) => actionTriggersIn(b)))];

package/src/harness/ui-inventory.ts

@@ -0,0 +1,164 @@
+/**
+ * #811 — the design inventory: is every item the DESIGN shows accounted for by the suite?
+ *
+ * Design sources in `requirements/ui/` (images, `figma-meta.md`) and `requirements/spec_figma.md`
+ * were read "for visual context" and never turned into a checkable list, so a column that exists
+ * only on the design — or contradicts the spec — was missed by the author AND the reviewer, and a
+ * deliberate deferral looked exactly like an oversight.
+ *
+ * create-test now writes `requirements/ui-inventory.md`: one `UI-NNN` row per component / column /
+ * button / state / annotation, with its source (`spec+design` | `design-only` | `conflict`). An
+ * item is accounted for by a scenario tag (`@ui:UI-014`) or a reasoned deferral comment
+ * (`# UI-DEFERRED: UI-002..013 — <reason>`) — no other mention counts; ranges and `/`
+ * enumerations read the same way as spec ids (spec-coverage `citedIds`). `spec+design` items are already measured
+ * by spec-coverage, so only `design-only` / `conflict` items are reported uncovered.
+ *
+ * Advisory: findings never move the score or the gate.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { citedIds } from './spec-coverage';
+import { readTextFile } from './read-text';
+
+export type UiItemSource = 'spec+design' | 'design-only' | 'conflict';
+
+export interface UiItem {
+  id: string;
+  item: string;
+  kind: string;
+  source: UiItemSource;
+}
+
+export interface UiInventoryResult {
+  /** Design sources the unit holds: image files, figma-meta.md, spec_figma.md. */
+  designSources: string[];
+  /** `requirements/ui-inventory.md` exists. */
+  hasInventory: boolean;
+  items: UiItem[];
+  /** `images read: a/b` from the inventory header — null when the line is absent. */
+  imagesRead: { read: number; total: number } | null;
+  /** Images on disk, for comparing against `imagesRead.total`. */
+  imagesOnDisk: number;
+  covered: string[];
+  deferred: string[];
+  /** design-only / conflict items neither covered nor deferred. */
+  uncovered: UiItem[];
+}
+
+const IMAGE = /\.(png|jpe?g|webp|gif)$/i;
+
+/** Every design source in a unit's `requirements/` — what makes an inventory necessary. */
+export function designSourcesOf(reqDir: string): string[] {
+  const out: string[] = [];
+  const uiDir = path.join(reqDir, 'ui');
+  try {
+    for (const f of fs.readdirSync(uiDir).sort()) {
+      if (IMAGE.test(f) || f === 'figma-meta.md') out.push(`ui/${f}`);
+    }
+  } catch { /* no ui/ dir */ }
+  if (fs.existsSync(path.join(reqDir, 'spec_figma.md'))) out.push('spec_figma.md');
+  return out;
+}
+
+/**
+ * The Source cell, read leniently ("design only", "Spec + Design", "conflict — …"). Anything else
+ * is NOT assumed to be spec-backed: an unreadable source is reported like a design-only item, so a
+ * typo can never make an item disappear from the check.
+ */
+function sourceOf(cell: string): UiItemSource | null {
+  const c = cell.trim().toLowerCase();
+  if (/^design[\s_-]*only\b/.test(c)) return 'design-only';
+  if (/^conflict\b/.test(c)) return 'conflict';
+  if (/^spec\s*(?:\+|&|and)\s*design\b/.test(c)) return 'spec+design';
+  return null;
+}
+
+/**
+ * Parse the inventory table: any markdown row whose first cell is a `UI-<n>` id. Leading/trailing
+ * pipes are optional (GFM), and the Source cell is FOUND rather than counted — a `|` written inside
+ * the Item cell shifts the columns, and a positional read then misfiled a design-only row.
+ */
+export function parseUiInventory(text: string): { items: UiItem[]; imagesRead: UiInventoryResult['imagesRead'] } {
+  const items: UiItem[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.includes('|')) continue;
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!/^UI-\d+$/i.test(cells[0] ?? '')) continue;
+    // Source = the last cell that reads as one (Seen-in follows it; prose in Item never starts so).
+    let srcIdx = -1;
+    for (let i = cells.length - 1; i >= 2; i--) if (sourceOf(cells[i])) { srcIdx = i; break; }
+    const source: UiItemSource = srcIdx >= 0 ? sourceOf(cells[srcIdx])! : 'design-only';
+    const kindIdx = srcIdx >= 0 ? srcIdx - 1 : Math.min(2, cells.length - 1);
+    items.push({
+      id: cells[0].toUpperCase(),
+      item: cells.slice(1, Math.max(2, kindIdx)).join(' | '),
+      kind: cells[kindIdx] ?? '',
+      source,
+    });
+  }
+  const m = text.match(/images read:\s*(\d+)\s*\/\s*(\d+)/i);
+  return { items, imagesRead: m ? { read: Number(m[1]), total: Number(m[2]) } : null };
+}
+
+/**
+ * Ids cited on a `UI-DEFERRED` comment line — a deliberate, REASONED omission. A line that lists
+ * ids and nothing else is not a decision anyone can review, so it defers nothing.
+ */
+function deferredIds(featureText: string): Set<string> {
+  const lines = featureText.split('\n').filter((l) => {
+    if (!/^\s*#\s*UI-DEFERRED\b/i.test(l)) return false;
+    const reason = l.replace(/^\s*#\s*UI-DEFERRED\b\s*:?/i, '').replace(/\bUI-\d+(?:\s*(?:\.\.|–|—|~|\/)\s*(?:UI-)?\d+)*/gi, '');
+    return /[\p{L}]{3,}/u.test(reason);
+  });
+  return citedIds(lines.join('\n'));
+}
+
+export function uiInventoryCoverage(reqDir: string, featureText: string): UiInventoryResult {
+  const designSources = designSourcesOf(reqDir);
+  const invPath = path.join(reqDir, 'ui-inventory.md');
+  const invText = fs.existsSync(invPath) ? readTextFile(invPath) : null;
+  const { items, imagesRead } = invText ? parseUiInventory(invText) : { items: [], imagesRead: null };
+  // Coverage is the `@ui:` TAG, nothing else: a `UI-001`-shaped string elsewhere (an `@spec:UI-001`
+  // requirement in a project that numbers its FRs that way, prose, an unreasoned deferral line)
+  // must not mark a design item as proven.
+  const cites = citedIds((featureText.match(/@ui:\S+/gi) ?? []).join(' '));
+  const deferSet = deferredIds(featureText);
+  const covered: string[] = [];
+  const deferred: string[] = [];
+  const uncovered: UiItem[] = [];
+  for (const it of items) {
+    if (deferSet.has(it.id)) deferred.push(it.id);
+    else if (cites.has(it.id)) covered.push(it.id);
+    else if (it.source !== 'spec+design') uncovered.push(it);
+  }
+  return {
+    designSources,
+    hasInventory: invText !== null,
+    items,
+    imagesRead,
+    imagesOnDisk: designSources.filter((s) => IMAGE.test(s)).length,
+    covered,
+    deferred,
+    uncovered,
+  };
+}
+
+/** Advisory findings for the audit report. */
+export function uiInventoryFindings(r: UiInventoryResult): string[] {
+  const out: string[] = [];
+  if (r.designSources.length === 0) return out;
+  if (!r.hasInventory) {
+    out.push(`UI-INVENTORY-MISSING: the unit has design sources (${r.designSources.slice(0, 4).join(', ')}${r.designSources.length > 4 ? ', …' : ''}) but no \`requirements/ui-inventory.md\` — nothing shows the design was read item by item, so an item that exists only on the design (or contradicts the spec) is invisible to the gate and to review. Re-run /sungen:create-test so it writes the inventory, or write it by hand: one \`| UI-NNN | item | kind | spec+design / design-only / conflict |\` row per component, column, button, state and annotation.`);
+    return out;
+  }
+  if (r.imagesRead && r.imagesRead.read < Math.max(r.imagesRead.total, r.imagesOnDisk)) {
+    out.push(`UI-INVENTORY-INCOMPLETE: the inventory records "images read: ${r.imagesRead.read}/${r.imagesRead.total}" and the unit holds ${r.imagesOnDisk} image(s) — the unread design is not inventoried. Read the remaining images and add their items.`);
+  } else if (!r.imagesRead && r.imagesOnDisk > 0) {
+    out.push(`UI-INVENTORY-INCOMPLETE: the unit holds ${r.imagesOnDisk} image(s) but the inventory does not record "images read: N/N" — nothing shows every image was opened. Add the line after reading them all.`);
+  }
+  for (const it of r.uncovered.slice(0, 10)) {
+    out.push(`UI-ITEM-UNCOVERED: ${it.id} "${it.item}" (${it.kind}, ${it.source}) has no scenario and no deferral — ${it.source === 'conflict' ? 'the design and spec.md disagree on it; resolve which is right, then cover it' : 'it exists only on the design, outside spec.md'}. Cover it (\`@ui:${it.id}\` on the scenario that proves it), or record the decision: \`# UI-DEFERRED: ${it.id} — <reason>\`.`);
+  }
+  if (r.uncovered.length > 10) out.push(`UI-ITEM-UNCOVERED: … and ${r.uncovered.length - 10} more design-only/conflict item(s).`);
+  return out;
+}

package/src/harness/viewpoint-ledger.ts

@@ -9,8 +9,9 @@
  * gaps that inflate a "looks-covered" score; it does not fail the gate.
  */
 import * as fs from 'fs';
-import { ScenarioInfo } from './parse';
-import { readTextFile } from './read-text';
+import { NON_DECLARATION_SECTION, PRIORITY_WORDS, ScenarioInfo } from './parse';
+import { readViewpointText } from './read-text';
+import { keywordHit } from './keyword-match';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -68,7 +69,10 @@ const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.T
 const PLACEHOLDER_ITEM = /^(none\b|n\/a\b|tbd\b|no known\b|nothing\b|do not invent\b|-+$)/i;
 /** A priority-DECLARATION row: `| VP-LOGIC | High | <reason prose> |`. The category id and its
  *  priority are consumed by the traceability + balance axes; the reason is rationale. */
-const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|normal|low|deferred)\b/i;
+// The word must be the WHOLE second cell: `skip` / `none` / `n/a` also open real claims
+// ("Skip link moves focus to main", "None of the optional fields block submit") — and so did
+// `high`/`low` ("High contrast mode …"), which the old word-boundary match swallowed too.
+const PRIORITY_ROW = new RegExp(`^(?:VP|FL)[A-Z0-9._-]*\\s+—\\s+[*_\`]*(?:${PRIORITY_WORDS})[*_\`.]*(?=\\s+—|\\s*$)`, 'i');
 /**
  * Whole SECTIONS that declare something ABOUT the checklist rather than listing claims to prove.
  *
@@ -81,13 +85,26 @@ const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|nor
  * `Design Decisions` deliberately stays IN: "values are buffered between step 3 and 4, a reload
  * loses them" is a real claim, and it is what the continuity check reads.
  */
-const DECLARATION_SECTION = /^(?:known issues?|open questions?|deferred|out of scope|viewpoint grouping|traceability|metadata|scope|journey phases?|revision history|references?|sources?|changelog)\b/i;
+const DECLARATION_SECTION = NON_DECLARATION_SECTION;   // shared with the overview parser (#833)
+/**
+ * A lead-in that introduces a manual check's PROCEDURE — `How to run VP-SEC-1:`, `Procedures:`,
+ * `Steps to reproduce:`. The list under it is how to EXECUTE a claim already declared above;
+ * counting each step as its own claim made gaps no scenario can close (8 of 13 surplus items on a
+ * field unit, #855).
+ *
+ * Deliberately narrow, because a false match HIDES claims: the lead may name one id and nothing
+ * else (`How to verify the following claims hold:` introduces claims, not steps), and a bare
+ * `Steps:` (a flow lists real step claims under it) and `Tester verifies:` (expected outcomes —
+ * exactly what the ledger counts) never qualify.
+ */
+const PROCEDURE_LEAD = /^(?:how to (?:run|test|reproduce|verify)|(?:manual )?procedures?|manual steps|steps to reproduce)(?:\s+(?:VP|FL)-[\w.-]+)?\s*:$/i;
+const LIST_ITEM = /^(?:[-*+]|\d+[.)])\s+/;
 const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
 
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
 export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
   if (!fs.existsSync(viewpointPath)) return [];
-  const lines = readTextFile(viewpointPath).split('\n');
+  const lines = readViewpointText(viewpointPath).split('\n');
   const items: { id?: string; text: string }[] = [];
   let inFence = false;
   let inDeclarationSection = false;
@@ -95,10 +112,36 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
   // nested under `## 8. Traceability Index` used to re-open the section and hand its rows
   // back as claims, because exclusion was recomputed from scratch at every heading.
   let excludedAt: number | null = null;
-  for (const raw of lines) {
-    const line = raw.trim();
+  // Inside the list a PROCEDURE_LEAD introduced: the indent of the lead (-1 for a paragraph lead),
+  // whose list items — and their wrapped continuation lines — are steps. A heading, a table, a
+  // new lead, or (after a paragraph lead) a blank line once a step was read ends it: when in
+  // doubt a step stays a claim, because a swallowed claim is a gap nobody ever sees — so a LOOSE
+  // procedure (steps separated by blank lines) leaks its later steps as claims, by design.
+  // Only an INDENTED line continues a step (Markdown's continuation); unindented prose ends it.
+  let procIndent: number | null = null;
+  let procSteps = 0;
+  let prevBlank = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
     if (line.startsWith('```')) { inFence = !inFence; continue; }
-    if (inFence || !line) continue;
+    if (inFence) continue;
+    if (!line) { prevBlank = true; continue; }
+    const wasBlank = prevBlank;
+    prevBlank = false;
+    const isItem = LIST_ITEM.test(line);
+    const indent = lines[i].length - lines[i].trimStart().length;
+    if (PROCEDURE_LEAD.test(line.replace(LIST_ITEM, '').replace(/[*_`]/g, '').trim())) {
+      procIndent = isItem ? indent : -1;
+      procSteps = 0;
+      continue;
+    }
+    if (procIndent !== null) {
+      const listEnded = wasBlank && procIndent < 0 && procSteps > 0;
+      if (!listEnded && isItem && indent > procIndent) { procSteps++; continue; }          // a step
+      if (!listEnded && !isItem && !wasBlank && procSteps > 0 && indent > Math.max(procIndent, 0)
+        && !/^[#|]/.test(line) && !line.endsWith(':')) continue;                          // a step that wraps
+      procIndent = null;
+    }
     const heading = line.match(/^(#{1,6})\s+(.*)$/);
     if (heading) {
       const level = heading[1].length;
@@ -120,6 +163,11 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
     if (bullet) { text = bullet[1]; lead = bullet[1]; }
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
+      // The row right above a `|---|` separator IS the header, whatever its words (`Skill #`,
+      // `Case #`) — structure, not a guessed word list, so a data row such as `C#` or `Issue #`
+      // is never mistaken for one (#832). The word list below still covers a separator-less table.
+      const next = (lines[i + 1] ?? '').trim();
+      if (/^\|[\s|:-]+\|?$/.test(next) && next.includes('-')) continue; // header
       const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
       if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status|step|flow|ref|level|question|screen|actor|branches from|own steps|component|thành phần|trường|bước)$/i.test(cells[0] || '')) continue; // header
       text = cells.join(' — ');
@@ -198,7 +246,7 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
     } else {
       const words = [...new Set((item.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w)))];
       const need = Math.min(2, words.length);
-      isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= need);
+      isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => keywordHit(s.haystack, w)).length >= need);
     }
     if (isCovered) covered++;
     else missing.push({ id: item.id, text: item.text });
@@ -348,10 +396,9 @@ export function viewpointIntegrity(
   }
 
   // The Priority-Viewpoints table: `| <id> | <priority> | <reason> |`.
-  // `readTextFile` throws on a missing file, and a unit may legitimately have no viewpoint yet.
-  const vpText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
+  const vpText = readViewpointText(viewpointPath);
   const rows = [...vpText
-    .matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)]
+    .matchAll(new RegExp(`^\\|\\s*((?:VP|FL)[A-Z0-9._-]*)\\s*\\|\\s*(${PRIORITY_WORDS})\\s*\\|`, 'gim'))]
     .map((m) => m[2].toLowerCase());
   const levels = [...new Set(rows)];
   const uniformPriority = rows.length >= 3 && levels.length === 1 ? { levels, rows: rows.length } : null;

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

package/src/orchestrator/project-initializer.ts

@@ -17,6 +17,8 @@ import {
   installMobileDriver,
 } from './mobile-runtime-scaffolder';
 import { emitAppiumEnvironment, runAppiumEnvironmentSetup, appiumEnvironmentRerunCommand } from './appium-environment-setup';
+import { ensureSecurityOverrides, reportSecurityOverrides } from './security-overrides';
+import { readTextFile } from '../harness/read-text';
 
 export { MobileInitOptions };
 
@@ -94,6 +96,14 @@ export class ProjectInitializer {
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  /**
+   * Actions the user asked for that could NOT be performed. Kept apart from `skippedItems`:
+   * that list renders under "Already exists", which is a statement of fact about the project —
+   * printing "package.json scripts (invalid JSON)" under it tells the user the opposite of what
+   * happened. An action that was not done needs its own heading, or the init summary reads as a
+   * clean success while `npm test` is missing.
+   */
+  private notDoneItems: string[] = [];
   /** set by createCodexMCPConfig when the project isn't Codex-trusted (config would never load) */
   private codexTrustWarning = false;
   private agents: AdapterKey[];
@@ -135,6 +145,7 @@ export class ProjectInitializer {
       : this.baseCwd;
     this.createdItems = [];
     this.skippedItems = [];
+    this.notDoneItems = [];
 
     console.log(`🚀 Initializing Sungen ${this.mobileOnly ? 'mobile-only ' : ''}project...\n`);
 
@@ -439,9 +450,17 @@ export class ProjectInitializer {
 
     if (existed) {
       try {
-        config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-      } catch {
-        this.skippedItems.push(`${displayName} (invalid JSON, skipped)`);
+        // via readTextFile: a UTF-8 BOM is the one thing `JSON.parse` rejects that every other tool
+        // reading this file ignores, and it is invisible in an editor. A config the rest of the
+        // toolchain loads fine must not cost the user their MCP servers here.
+        config = JSON.parse(readTextFile(filePath));
+      } catch (e) {
+        // Anything still unparseable is genuinely broken. Say WHERE — "is not valid JSON" alone
+        // leaves the user to find a missing comma in a file they did not know was the problem.
+        this.notDoneItems.push(
+          `${displayName} (${(e as Error).message.split('\n')[0]}) — MCP servers not registered; `
+          + `fix the JSON and re-run \`sungen init\``,
+        );
         return;
       }
     }
@@ -487,6 +506,13 @@ export class ProjectInitializer {
       });
     }
 
+    if (this.notDoneItems.length > 0) {
+      console.log('\n⚠ Not done — needs your attention:');
+      this.notDoneItems.forEach(item => {
+        console.log(`  ✗ ${item}`);
+      });
+    }
+
     if (this.codexTrustWarning) {
       console.log('\n⚠ Codex: this project is not trusted yet, so .codex/config.toml (the MCP browser');
       console.log('  config for run-test) will be SILENTLY IGNORED by Codex. To fix, either:');
@@ -685,6 +711,13 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
+    // Pin the transitive packages that would otherwise make `npm audit` red here. This MUST happen
+    // before the install below: npm reads `overrides` at resolution time, so a lockfile written
+    // first would already hold the vulnerable versions. See security-overrides.ts for why the pins
+    // cannot simply live in sungen's own manifest.
+    const overridePlan = ensureSecurityOverrides(packageJsonPath);
+    reportSecurityOverrides(overridePlan);
+
     // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
     // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
     // fast-xml-parser: the API driver's XML request/response support lazy-requires it
@@ -696,7 +729,7 @@ export class ProjectInitializer {
 
     let missingDeps: string[] = requiredDeps;
     try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      const packageJson = JSON.parse(readTextFile(packageJsonPath));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
       missingDeps = requiredDeps.filter(d => !deps[d]);
     } catch {
@@ -705,6 +738,12 @@ export class ProjectInitializer {
 
     if (missingDeps.length === 0) {
       console.log('✓ All dependencies already installed\n');
+      // Nothing to install means nothing re-resolves, so overrides just written would sit in
+      // package.json while the lockfile keeps the vulnerable tree. Re-resolve once so they land.
+      if (overridePlan?.add.length) {
+        console.log('📦 Re-resolving the tree so the new security overrides take effect...\n');
+        execSync('npm install', execOpts);
+      }
     } else {
       console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
       execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
@@ -725,8 +764,17 @@ export class ProjectInitializer {
   private ensurePackageScripts(packageJsonPath: string): void {
     let packageJson: Record<string, any>;
     try {
-      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-    } catch {
+      // via readTextFile: a package.json carrying a UTF-8 BOM is one npm reads without complaint,
+      // so it must not be treated as unparseable here. That was the trigger that actually reached
+      // this catch — genuinely broken JSON aborts `npm install` a few lines below instead.
+      packageJson = JSON.parse(readTextFile(packageJsonPath));
+    } catch (e) {
+      // Returning here used to add nothing and say nothing, so init reported success and the user
+      // met `npm error Missing script: "test"` later with nothing pointing back to this run.
+      this.notDoneItems.push(
+        `package.json scripts (${(e as Error).message.split('\n')[0]}) — `
+        + `fix the JSON and re-run \`sungen init\`, or add the scripts by hand`,
+      );
       return;
     }
 

package/src/orchestrator/screen-manager.ts

@@ -9,6 +9,7 @@ import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 import { resolveWebBaseUrl } from '../exporters/env-qa';
+import { uiPatternRows } from './viewpoint-pattern-catalog';
 
 export interface ScreenOptions {
   name: string;
@@ -191,20 +192,11 @@ export class ScreenManager {
         '',
         '## UI Patterns Identified',
         '',
-        '<!-- Check applicable patterns for this screen (from sungen-viewpoint skill):',
+        '<!-- Check applicable patterns for this screen (numbered as in the sungen-viewpoint skill):',
         '',
         '| # | Pattern | Applicable? | Notes |',
         '|---|---------|-------------|-------|',
-        '| 1 | Form & Inputs | ☐ | |',
-        '| 2 | Data Table | ☐ | |',
-        '| 3 | Create / Add | ☐ | |',
-        '| 4 | Update / Edit | ☐ | |',
-        '| 5 | Delete | ☐ | |',
-        '| 6 | Search | ☐ | |',
-        '| 7 | Filter | ☐ | |',
-        '| 8 | Pagination | ☐ | |',
-        '| 9 | Modal / Dialog | ☐ | |',
-        '| 10 | List / Card | ☐ | |',
+        ...uiPatternRows(isMobile),
         '-->',
         '',
         '## Priority Viewpoints',