@sun-asterisk/sungen 3.2.31 → 3.2.33

package/src/harness/spec-branches.ts

@@ -16,6 +16,7 @@
  * explicit — a named heading, a table that declares conditions and outcomes, or an if/else
  * cascade — because a false "you missed a branch" costs more trust than it buys coverage.
  */
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo } from './parse';
 
 export interface SpecBranch {
@@ -172,7 +173,9 @@ export function unenumeratedBranches(branches: SpecBranch[], featureText: string
     const words = [...new Set((b.label.toLowerCase().match(/[a-z][a-z-]{3,}/g) ?? []))]
       .filter((w) => !GENERIC_WORD.has(w));
     if (words.length === 0) return !hay.includes(b.label.toLowerCase());
-    const hits = words.filter((w) => hay.includes(w)).length;
+    // Word-aware (#779): `in·active` and `check·list` are not mentions of `active` and `list`,
+    // and two of them credited a branch no scenario cites.
+    const hits = words.filter((w) => keywordHit(hay, w)).length;
     return hits < Math.min(2, words.length);
   });
 }
@@ -204,38 +207,93 @@ export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: s
 }
 
 /**
- * A "denied → hidden" scenario with no "allowed → shown" counterpart (#630).
+ * A "hidden" scenario with no "shown" counterpart (#630, widened in #679).
  *
  * Two security cases proved that chat content is hidden when `MESSAGE_READ` is denied. If the code
  * hid it unconditionally — ignoring the permission entirely — both still pass. The deny side alone
  * cannot distinguish "the guard works" from "the feature is broken for everyone", so the pair is
  * the test, exactly as `min-1 / min / max / max+1` is the test for a boundary.
  *
- * The mirror of the negative-claim rule the skill already has, on the other side.
+ * The first version gated on PERMISSION vocabulary, and "show A or B, never both" is far broader
+ * than permission: a conditional button, an empty-vs-populated state, an active tab. A field report
+ * lost exactly that case — "the score button is hidden once a score exists" was written, "it is
+ * shown while no score is set" was not, and nothing asked for it. So the trigger is now the
+ * ELEMENT the assertion names: an element this suite proves ABSENT and never proves PRESENT is
+ * unpaired, whatever the condition is called. That also catches the vacuous form — a selector that
+ * matches nothing passes `is hidden` forever.
+ *
+ * Permission stays its own `kind`, because the repair advice differs and its wording is what the
+ * skill teaches.
  */
 const DENY_SHAPE = /\b(?:denied|deny|denies|forbidden|not authoriz\w*|unauthoriz\w*|no permission|without (?:the )?(?:permission|right|access|flag)|permission (?:is )?off|flag (?:is )?off|revoked|restricted)\b/i;
 const HIDDEN_SHAPE = /\b(?:is hidden|are hidden|not (?:visible|shown|displayed)|blocked|masked|redacted|does not (?:show|render|appear))\b/i;
 const ALLOW_SHAPE = /\b(?:granted|allowed|permitted|authoriz\w*|has (?:the )?(?:permission|right|access)|permission (?:is )?on|flag (?:is )?on|with (?:the )?(?:permission|right|access))\b/i;
 
-export function permissionPairGaps(
-  scenarios: ScenarioInfo[],
-): Array<{ scenario: string; subject: string[] }> {
-  const denies = scenarios.filter((s) => DENY_SHAPE.test(s.haystack) && HIDDEN_SHAPE.test(s.haystack));
-  if (denies.length === 0) return [];
-  const allows = scenarios.filter((s) => ALLOW_SHAPE.test(s.haystack) && !HIDDEN_SHAPE.test(s.stepsText));
+/** Absence in sungen's own assertion grammar — `is hidden`, `does not exist`, `not exists`. */
+const ABSENT_ASSERTION = /\bis hidden\b|\bare hidden\b|\bnot (?:visible|shown|displayed)\b|\bdoes not (?:exist|show|appear|render)\b|\bnot exists?\b/i;
+
+export interface VisibilityPairGap {
+  scenario: string;
+  subject: string[];
+  /** The element reference the pair is about, when the assertion names one. */
+  element?: string;
+  /** `permission` keeps the deny/allow repair advice; `condition` is any other state. */
+  kind: 'permission' | 'condition';
+}
+
+/** What a scenario ASSERTS — the Then side. Hand-built fixtures carry no buckets; use their steps. */
+function thenLines(s: ScenarioInfo): string[] {
+  const thens = (s.steps ?? []).filter((st) => st.bucket === 'then').map((st) => st.text.toLowerCase());
+  if (thens.length) return thens;
+  return s.stepsText ? [s.stepsText] : [];
+}
+/** Every `[ref]` of a line. */
+function refsIn(line: string): string[] {
+  return [...line.matchAll(/\[([^\]]{1,60})\]/g)].map((m) => m[1].trim().toLowerCase());
+}
+
+export function visibilityPairGaps(scenarios: ScenarioInfo[]): VisibilityPairGap[] {
+  // Every element the suite proves PRESENT, anywhere. A positive assertion names its element and
+  // any element it is scoped INSIDE (`[Row] row in [Table] table`) — both are demonstrably there.
+  const shown = new Set<string>();
+  for (const s of scenarios) {
+    for (const l of thenLines(s)) {
+      if (ABSENT_ASSERTION.test(l)) continue;
+      for (const ref of refsIn(l)) shown.add(ref);
+    }
+  }
   // Words only — the scenario ID is stripped first, because `[a-z][a-z-]{4,}` happily matches
   // `fl-er-` and an id fragment can never appear in the counterpart's title, so demanding it made
   // the pair impossible to find.
   const distinctive = (s: ScenarioInfo): string[] =>
     [...new Set((s.name.replace(/^\S+\s*/, '').toLowerCase().match(/[a-z]{5,}/g) ?? []))]
       .filter((w) => !GENERIC_WORD.has(w) && !/denied|denies|hidden|permission|scenario/.test(w));
-  const out: Array<{ scenario: string; subject: string[] }> = [];
-  for (const d of denies) {
-    const subject = distinctive(d);
+  const allows = scenarios.filter((s) => ALLOW_SHAPE.test(s.haystack) && !HIDDEN_SHAPE.test(s.stepsText));
+  const out: VisibilityPairGap[] = [];
+  const reported = new Set<string>();
+  for (const s of scenarios) {
+    const absent = thenLines(s).filter((l) => ABSENT_ASSERTION.test(l));
+    if (!absent.length && !(DENY_SHAPE.test(s.haystack) && HIDDEN_SHAPE.test(s.haystack))) continue;
+    const kind = DENY_SHAPE.test(s.haystack) ? 'permission' : 'condition';
+    // Only the FIRST ref of an absence line is its subject: in `see [Row] row in [Table] table … is
+    // hidden` the table is the scope, the row is what went away.
+    const subjects = [...new Set(absent.map((l) => refsIn(l)[0]).filter((r): r is string => !!r))];
+    if (subjects.length) {
+      for (const el of subjects) {
+        if (shown.has(el) || reported.has(el)) continue;
+        reported.add(el);
+        out.push({ scenario: s.name, subject: distinctive(s).slice(0, 4), element: el, kind });
+      }
+      continue;
+    }
+    // The assertion names no element — the permission vocabulary is then the only safe trigger,
+    // paired on the scenario's distinctive title words as before.
+    if (kind !== 'permission' || !HIDDEN_SHAPE.test(s.haystack)) continue;
+    const subject = distinctive(s);
     // The counterpart has to be about the SAME thing — two shared distinctive words, the same
     // bar the ledger's prose matching uses.
-    const paired = allows.some((a) => subject.filter((w) => a.haystack.includes(w)).length >= Math.min(2, subject.length));
-    if (!paired) out.push({ scenario: d.name, subject: subject.slice(0, 4) });
+    const paired = allows.some((a) => subject.filter((w) => keywordHit(a.haystack, w)).length >= Math.min(2, subject.length));
+    if (!paired) out.push({ scenario: s.name, subject: subject.slice(0, 4), kind: 'permission' });
   }
   return out;
 }

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';
 
@@ -16,6 +17,12 @@ export type Modality = 'MUST' | 'SHOULD' | 'MAY';
 
 export interface TriggerGap { constraint: string; code: string; required: string[]; found: string[]; missing: string[] }
 
+/**
+ * One DIRECTION of a requirement that states both — `MUST be shown … MUST NOT be shown …` (#679).
+ * The id is cited, so the requirement looks covered; this names the half nothing asserts.
+ */
+export interface ClauseGap { id: string; polarity: 'affirm' | 'negate'; text: string }
+
 export interface SpecCoverageResult {
   hasSpec: boolean;
   frTotal: number;
@@ -27,10 +34,13 @@ export interface SpecCoverageResult {
    *  requirement table and any later refactor cannot follow it. */
   inferredOnly: string[];
   triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
+  /** Requirements whose two opposing clauses are not BOTH proved (#679). */
+  clauseGaps: ClauseGap[];
   verdict: 'pass' | 'warn' | 'fail';
 }
 
-interface FrClause { id: string; text: string; modality: Modality }
+export interface FrDirection { polarity: 'affirm' | 'negate'; text: string }
+interface FrClause { id: string; text: string; modality: Modality; directions?: FrDirection[] }
 interface ValRow { constraint: string; code: string; triggers: string[] }
 
 // Parsing the spec's Trigger CELL: loose word match ("blur, submit").
@@ -55,6 +65,90 @@ function modalityOf(text: string): Modality {
   return 'MAY';
 }
 
+/**
+ * A requirement that states BOTH directions in one sentence — "`X` MUST be shown when no score is
+ * set; MUST NOT be shown once a score exists" (#679).
+ *
+ * One `FrClause` per LINE carried one modality for the whole sentence, and coverage was a binary
+ * check per id: ONE scenario tagged `@spec:FR-013` closed both halves. The half that went missing
+ * in the field was the MUST NOT one — the classic "both buttons rendered at once" defect, reported
+ * as covered 100% on the first generation.
+ *
+ * Deliberately narrow, three ways at once, because the finding is GATE-BLOCKING:
+ *   - only a HARD prohibition paired with a hard obligation ("MUST be shown and enabled" is one
+ *     direction and stays one unit);
+ *   - only a requirement that NAMES its element, backticked or bracketed — the direction evidence
+ *     is an assertion ABOUT something, and without a subject there is nothing to look for;
+ *   - only a VISIBILITY/enabledness requirement, because that is the vocabulary the evidence test
+ *     reads. "MUST validate the email format on submit. MUST NOT allow submission when it is
+ *     invalid." is an opposing pair in prose and NOT one here: nothing in a correct suite for it
+ *     asserts absence, so judging it would fail a suite with no gap in it.
+ */
+const VISIBILITY_CLAUSE = /\b(?:shown|shows?|displayed|displays?|visible|hidden|hides?|rendered|renders?|appears?|enabled|disabled)\b|表示|hiển thị/i;
+const PROHIBITION = /\b(?:must not|must never|shall not|shall never)\b|KHÔNG ĐƯỢC|してはならない/i;
+const OBLIGATION = /\b(?:must|shall)\b|\bPHẢI\b/i;
+
+function splitDirections(text: string): FrDirection[] | undefined {
+  if (!VISIBILITY_CLAUSE.test(text) || elementRefs(text).length === 0) return undefined;
+  const parts = text.split(/\s*(?:;|；|。|\.\s+|,?\s+but\s+)\s*/i).map((p) => p.trim()).filter(Boolean);
+  if (parts.length < 2) return undefined;
+  const affirm: string[] = [];
+  const negate: string[] = [];
+  for (const part of parts) {
+    if (PROHIBITION.test(part)) negate.push(part);
+    else if (OBLIGATION.test(part)) affirm.push(part);
+  }
+  if (!affirm.length || !negate.length) return undefined;
+  return [
+    { polarity: 'affirm', text: affirm.join('; ') },
+    { polarity: 'negate', text: negate.join('; ') },
+  ];
+}
+
+/** What the clause is ABOUT: a backticked or bracketed element name is the one distinctive token. */
+function elementRefs(text: string): string[] {
+  return [...new Set(
+    [...text.matchAll(/`([^`]+)`|\[([^\]]+)\]/g)]
+      .map((m) => (m[1] ?? m[2]).trim().toLowerCase())
+      .filter((x) => x.length >= 2 && x.length <= 60),
+  )];
+}
+
+/**
+ * Absence, in sungen's own assertion grammar (`is hidden`, `does not exist`) plus the prose a spec
+ * restatement uses. Positive visibility has no marker — `User see [T]` never says "is visible" —
+ * so the affirm side is "an assertion that is not a denial", which is what the suite actually writes.
+ */
+const NEGATIVE_ASSERTION = /\bis hidden\b|\bare hidden\b|\bnot (?:visible|shown|displayed|present)\b|\bdoes not (?:exist|show|appear|render)\b|\bnot exists?\b|\bno longer\b|表示されない|không hiển thị/i;
+
+/** Assertion lines of a scenario block — Then plus the And/But that inherit its bucket. */
+function assertionLines(block: string): string[] {
+  const out: string[] = [];
+  let bucket = '';
+  for (const raw of block.split('\n')) {
+    const kw = raw.trim().match(/^(given|when|then|and|but)\s+/);
+    if (!kw) continue;
+    if (kw[1] !== 'and' && kw[1] !== 'but') bucket = kw[1];
+    if (bucket === 'then') out.push(raw.trim());
+  }
+  return out;
+}
+
+/** Does this scenario block assert THIS direction of the requirement? */
+function directionCovered(block: string, dir: FrDirection, subject: string[]): boolean {
+  const lines = assertionLines(block);
+  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".
+  // 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'));
+}
+
 function specTriggersIn(text: string): string[] {
   return SPEC_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
 }
@@ -86,7 +180,10 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
     const id = m[1].toUpperCase();
     if (seen.has(id)) continue;          // first declaration wins
     seen.add(id);
-    frs.push({ id, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+    const text = m[2].replace(/\*\*/g, '').trim();
+    const modality = modalityOf(text);
+    // A MUST/MUST NOT pair is TWO requirements wearing one id (#679) — carry both directions.
+    frs.push({ id, text, modality, directions: modality === 'MUST' ? splitDirections(text) : undefined });
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
@@ -156,40 +253,63 @@ export function citedIds(featureText: string): Set<string> {
 export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
   const { frs, valRows } = parseSpecClauses(specPath);
   if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
-    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], verdict: 'pass' };
+    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], clauseGaps: [], verdict: 'pass' };
   }
   const featLower = featureText.toLowerCase();
   const cites = citedIds(featureText);
+  const blocks = scenarioBlocks(featureText);
 
   // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
   const uncoveredMust: { id: string; text: string }[] = [];
+  const clauseGaps: ClauseGap[] = [];
   const inferredOnly: string[] = [];
+  let frTotal = 0;
   let frCovered = 0;
   for (const fr of frs) {
+    // A requirement stating both directions is TWO units — counting it as one is what let a suite
+    // holding only the MUST half read 100% covered (#679).
+    const units = fr.directions ? fr.directions.length : 1;
+    frTotal += units;
     const idLower = fr.id.toLowerCase();
     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));
-    if (cited || kwHit) {
-      frCovered++;
-      if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
-    } else if (fr.modality === 'MUST') {
-      uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    // 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;
+    }
+    if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
+    if (!fr.directions) { frCovered++; continue; }
+    // 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) => 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; }
+    const subject = elementRefs(fr.text);
+    for (const dir of fr.directions) {
+      if (owning.some((b) => directionCovered(b, dir, subject))) frCovered++;
+      else if (fr.modality === 'MUST') clauseGaps.push({ id: fr.id, polarity: dir.polarity, text: dir.text.slice(0, 90) });
     }
   }
 
   // Per-constraint trigger coverage — the matrix-collapse catch.
   // generic words that don't identify a constraint (would over-match happy-path scenarios)
   const GENERIC = new Set(['valid', 'local', 'part', 'domain', 'email', 'address', 'must', 'exist', 'store', 'field', 'input', 'value', 'formed', 'well', 'character', 'characters']);
-  const blocks = scenarioBlocks(featureText);
   const triggerGaps: TriggerGap[] = [];
   for (const row of valRows) {
     const kw = (row.constraint.toLowerCase().match(/[a-z]{4,}/g) || []).filter((w) => !GENERIC.has(w));
     // 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)))];
@@ -198,9 +318,9 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
   }
 
   const verdict: SpecCoverageResult['verdict'] =
-    uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
+    uncoveredMust.length > 0 || triggerGaps.length > 0 || clauseGaps.length > 0 ? 'fail' : 'pass';
 
-  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
+  return { hasSpec: true, frTotal, frCovered, uncoveredMust, inferredOnly, triggerGaps, clauseGaps, verdict };
 }
 
 /**

package/src/harness/viewpoint-ledger.ts

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
+import { keywordHit } from './keyword-match';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -198,7 +199,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 });

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/appium-environment-setup.ts

@@ -0,0 +1,127 @@
+/**
+ * Appium environment bundle — emit `appium-environment/` into a mobile project and run its entry point.
+ *
+ * The bundle (bash for macOS, PowerShell for Windows) provisions the OS layer BELOW Appium: JDK, Android
+ * SDK + env vars, Xcode CLT, applesimutils, then the project-local Appium platform drivers, and ends with
+ * `appium driver doctor`. Emitted by `sungen init --mobile` / `sungen capability add mobile` and run once
+ * right after the driver install (spec: docs/spec/sungen_mobile_environment_setup_spec.md, issue #718).
+ *
+ * Core ships the scripts as templates only — no runtime is embedded, nothing is installed globally.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+export const APPIUM_ENV_DIR = 'appium-environment';
+
+export interface EmitResult {
+  created: string[];
+  skipped: string[];
+}
+
+export type EnvSetupOutcome = 'ran' | 'failed' | 'skipped' | 'unsupported';
+
+/** Bundled template root — resolves from src/orchestrator (tsx) and dist/orchestrator (copy-templates). */
+const TEMPLATE_ROOT = path.join(__dirname, 'templates', APPIUM_ENV_DIR);
+
+/** Files under `dir`, relative and posix-separated, sorted for a deterministic emit order. */
+function listTemplateFiles(dir: string, prefix = ''): string[] {
+  const out: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listTemplateFiles(path.join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Copy the bundle into `<cwd>/appium-environment/`, skipping every file that already exists (a QA may
+ * have edited the pinned cmdline-tools build or a hint — same idempotency as the other emitted files).
+ * `*.sh` get the executable bit explicitly: npm and git do not reliably preserve it.
+ */
+export function emitAppiumEnvironment(cwd: string): EmitResult {
+  const created: string[] = [];
+  const skipped: string[] = [];
+  // Non-fatal like the other provisioning steps: a broken install (templates missing) must not abort
+  // `init` / `capability add` — the harness scaffold is still valid without the bundle.
+  try {
+    for (const rel of listTemplateFiles(TEMPLATE_ROOT)) {
+      const dest = path.join(cwd, APPIUM_ENV_DIR, rel);
+      const label = `${APPIUM_ENV_DIR}/${rel}`;
+      if (fs.existsSync(dest)) { skipped.push(label); continue; }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(path.join(TEMPLATE_ROOT, rel), dest);
+      if (rel.endsWith('.sh')) fs.chmodSync(dest, 0o755);
+      created.push(label);
+    }
+  } catch (e) {
+    console.warn(`⚠️  Could not emit ${APPIUM_ENV_DIR}/ (${e instanceof Error ? e.message : e}) — reinstall @sun-asterisk/sungen and re-run: sungen capability add mobile`);
+  }
+  return { created, skipped };
+}
+
+/** The command a QA re-runs by hand, for hints and the init summary. */
+export function appiumEnvironmentRerunCommand(): string {
+  return process.platform === 'win32'
+    ? `powershell -NoProfile -ExecutionPolicy Bypass -File .\\${APPIUM_ENV_DIR}\\setup.ps1`
+    : `./${APPIUM_ENV_DIR}/setup.sh`;
+}
+
+/**
+ * Translate the bundle's POSIX flags to their PowerShell switches. `sungen setup-mobile-env` speaks
+ * one flag vocabulary on both OSes, so the user does not have to know which script is underneath.
+ */
+const PS_SWITCH: Record<string, string> = {
+  '--check': '-Check',
+  '--skip-android': '-SkipAndroid',
+  '--no-profile': '-NoProfile',
+  // `--skip-ios` has no Windows counterpart: setup.ps1 has no iOS steps to skip.
+};
+
+function entryCommand(cwd: string, flags: string[] = []): { file: string; args: string[] } | null {
+  const bundle = path.join(cwd, APPIUM_ENV_DIR);
+  if (process.platform === 'win32') {
+    const switches = flags.map(f => PS_SWITCH[f]).filter((s): s is string => !!s);
+    return {
+      file: 'powershell',
+      // -NoProfile here is powershell.exe's own "skip the user profile" flag, unrelated to the
+      // bundle's -NoProfile switch; the latter arrives through `switches` after -File.
+      args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', path.join(bundle, 'setup.ps1'), ...switches],
+    };
+  }
+  // setup.sh handles Darwin; on Linux it prints the manual-path notice and exits 0.
+  if (process.platform === 'darwin' || process.platform === 'linux') {
+    return { file: 'bash', args: [path.join(bundle, 'setup.sh'), ...flags] };
+  }
+  return null;
+}
+
+/**
+ * Run the emitted entry point for this OS with inherited stdio — its per-step output IS the UX, and any
+ * Homebrew / sudo prompt must reach the user. Non-fatal by contract: problems are reported with the re-run
+ * command and init continues, because the scaffold itself is already complete.
+ */
+export function runAppiumEnvironmentSetup(
+  cwd: string,
+  opts: { skip?: boolean; flags?: string[] } = {},
+): EnvSetupOutcome {
+  if (opts.skip) {
+    console.log(`– skipped  environment setup (--skip-env-setup) — run it later: sungen setup-mobile-env`);
+    return 'skipped';
+  }
+  const cmd = entryCommand(cwd, opts.flags);
+  if (!cmd) {
+    console.log(`ℹ️  environment setup ships for macOS (setup.sh) and Windows (setup.ps1) — on ${process.platform} follow ${APPIUM_ENV_DIR}/README.md → Manual fallback`);
+    return 'unsupported';
+  }
+  console.log(`\n🔧 Provisioning the Appium environment (${APPIUM_ENV_DIR}/) — idempotent, re-run any time...`);
+  const result = spawnSync(cmd.file, cmd.args, { cwd, stdio: 'inherit' });
+  if (result.status === 0) return 'ran';
+  // status null = the shell itself could not start (ENOENT) or was killed — name the real cause.
+  const exit = result.error ? `could not start ${cmd.file}: ${result.error.message}`
+    : result.status === null ? `signal ${result.signal ?? '?'}` : `exit ${result.status}`;
+  console.warn(`⚠️  environment setup reported problems (${exit}) — fix the ✗ items above, then re-run: sungen setup-mobile-env (or ${appiumEnvironmentRerunCommand()} directly)`);
+  return 'failed';
+}

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/mobile-runtime-scaffolder.ts

@@ -22,6 +22,8 @@ export interface MobileInitOptions {
   iosBundleId?: string;
   iosDevice?: string;
   iosVersion?: string;
+  /** Emit `appium-environment/` but do not run it now (`--skip-env-setup`); QA re-runs it by hand. */
+  skipEnvSetup?: boolean;
 }
 
 export interface ScaffoldResult {

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