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

package/dist/orchestrator/templates/claude-hooks/sungen-hook.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * sungen — Claude Code hook launcher. Written by `sungen init` / `sungen update`; edits are
+ * overwritten. `.claude/settings.json` runs it in exec form (no shell):
+ *   { "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/sungen-hook.cjs", "<hook>"] }
+ *
+ * Finds the installed sungen and runs one hook IN-PROCESS (node on dist — no npx — so a hook costs
+ * one Node start). Lookup: $SUNGEN_HOOK_ENTRY when set (exactly that file), else the project's own
+ * dependency, else the global npm prefix.
+ *
+ * FAILS OPEN: kill-switch set, sungen not found, or any error → prints `{}` and exits 0. A hook can
+ * never block or derail a session.
+ *
+ * Off switches: SUNGEN_HOOKS=off (all) · SUNGEN_HOOK_<NAME>=off (one) · qa/sungen.config.yaml `hooks:`.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ENTRY = ['@sun-asterisk', 'sungen', 'dist', 'hooks', 'claude-hook-entry.js'];
+
+function noop() {
+  process.stdout.write('{}\n', () => process.exit(0));
+}
+
+function npmrcPrefix() {
+  try {
+    const m = fs.readFileSync(path.join(os.homedir(), '.npmrc'), 'utf8').match(/^\s*prefix\s*=\s*(.+?)\s*$/m);
+    return m ? m[1].replace(/^~(?=$|[\\/])/, os.homedir()) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function findEntry() {
+  const override = process.env.SUNGEN_HOOK_ENTRY;
+  if (override) return fs.existsSync(override) ? override : null;
+  const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    return require.resolve(ENTRY.join('/'), { paths: [project] });
+  } catch (_) { /* not a project dependency — try the global install */ }
+  const bin = path.dirname(process.execPath);
+  const prefixes = [process.env.npm_config_prefix, npmrcPrefix(), path.join(bin, '..'), bin].filter(Boolean);
+  for (const prefix of prefixes) {
+    for (const lib of [path.join(prefix, 'lib', 'node_modules'), path.join(prefix, 'node_modules')]) {
+      const candidate = path.join(lib, ...ENTRY);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+try {
+  if (/^(?:off|0|false|no|disabled?)$/i.test(String(process.env.SUNGEN_HOOKS || '').trim())) {
+    noop();
+  } else {
+    const entry = findEntry();
+    if (!entry) noop();
+    else Promise.resolve(require(entry).main(process.argv[2] || '')).then(() => process.exit(0), noop);
+  }
+} catch (_) {
+  noop();
+}

package/dist/orchestrator/viewpoint-pattern-catalog.d.ts

@@ -15,9 +15,6 @@ export interface ViewpointPattern {
     mobile?: boolean;
 }
 export declare const VIEWPOINT_PATTERNS: readonly ViewpointPattern[];
-/**
- * The scaffold's pattern-table rows: 1–17 for every screen, plus Group F on a mobile project.
- * `Áp dụng?` is left empty for the QA to mark ✅ / ❌, as the QA template does.
- */
+/** The scaffold's pattern-table rows: 1–17 for every screen, plus Group F on a mobile project. */
 export declare function uiPatternRows(isMobile: boolean): string[];
 //# sourceMappingURL=viewpoint-pattern-catalog.d.ts.map

package/dist/orchestrator/viewpoint-pattern-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewpoint-pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/orchestrator/viewpoint-pattern-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAiCzD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAIzD"}
+{"version":3,"file":"viewpoint-pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/orchestrator/viewpoint-pattern-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAiCzD,CAAC;AAEF,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAIzD"}

package/dist/orchestrator/viewpoint-pattern-catalog.js

@@ -36,13 +36,10 @@ exports.VIEWPOINT_PATTERNS = [
     { n: 31, name: 'Settings Toggle List', mobile: true },
     { n: 32, name: 'App Lifecycle & Orientation', mobile: true },
 ];
-/**
- * The scaffold's pattern-table rows: 1–17 for every screen, plus Group F on a mobile project.
- * `Áp dụng?` is left empty for the QA to mark ✅ / ❌, as the QA template does.
- */
+/** The scaffold's pattern-table rows: 1–17 for every screen, plus Group F on a mobile project. */
 function uiPatternRows(isMobile) {
     return exports.VIEWPOINT_PATTERNS
         .filter((p) => isMobile || !p.mobile)
-        .map((p) => `| ${p.n} | ${p.name} | | |`);
+        .map((p) => `| ${p.n} | ${p.name} | ☐ | |`);
 }
 //# sourceMappingURL=viewpoint-pattern-catalog.js.map

package/dist/orchestrator/viewpoint-pattern-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"viewpoint-pattern-catalog.js","sourceRoot":"","sources":["../../src/orchestrator/viewpoint-pattern-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"viewpoint-pattern-catalog.js","sourceRoot":"","sources":["../../src/orchestrator/viewpoint-pattern-catalog.ts"],"names":[],"mappings":"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"}

package/dist/utils/safe-yaml-parse.d.ts

@@ -0,0 +1,8 @@
+export declare const SAFE_YAML_MAX_ALIAS_COUNT = 10;
+export declare const SAFE_YAML_MAX_BYTES: number;
+export declare class UnsafeYamlError extends Error {
+    readonly source: string;
+    constructor(source: string, detail: string);
+}
+export declare function safeYamlParse(text: string, source?: string): unknown;
+//# sourceMappingURL=safe-yaml-parse.d.ts.map

package/dist/utils/safe-yaml-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-yaml-parse.d.ts","sourceRoot":"","sources":["../../src/utils/safe-yaml-parse.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,qBAAa,eAAgB,SAAQ,KAAK;aACZ,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI3D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAW,GAAG,OAAO,CAiBtE"}

package/dist/utils/safe-yaml-parse.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsafeYamlError = exports.SAFE_YAML_MAX_BYTES = exports.SAFE_YAML_MAX_ALIAS_COUNT = void 0;
+exports.safeYamlParse = safeYamlParse;
+/**
+ * Parse YAML that a person or an agent wrote into `qa/` — decisions, test-basis, locks — without
+ * letting the file attack the reader (red-team #14, DOS-13.8).
+ *
+ * - `maxAliasCount` small: a "billion laughs" document that multiplies one anchor through nested
+ *   aliases is refused instead of expanding to gigabytes. None of these files has a reason to
+ *   alias at all; a handful is allowed so a hand-written file with one shared block still reads.
+ * - YAML **core** schema and nothing else: `!!binary`, `!!timestamp`, `!!js/…` or any custom tag is
+ *   an error (the library would otherwise resolve "known" extra tags even under core), and yaml-1.1
+ *   merge keys (`<<`) are not merged. `2026-10-21` stays the string it was written as, so a hash
+ *   over the parsed value equals a hash over the text's intent.
+ * - duplicate keys are an error: two `reason:` lines must not let the second silently win.
+ * - a byte cap: these files are a few hundred bytes; a 100 MB one is an attack or an accident.
+ */
+const yaml_1 = require("yaml");
+exports.SAFE_YAML_MAX_ALIAS_COUNT = 10;
+exports.SAFE_YAML_MAX_BYTES = 1024 * 1024;
+class UnsafeYamlError extends Error {
+    constructor(source, detail) {
+        super(`${source}: ${detail}`);
+        this.source = source;
+        this.name = 'UnsafeYamlError';
+    }
+}
+exports.UnsafeYamlError = UnsafeYamlError;
+function safeYamlParse(text, source = '<yaml>') {
+    if (Buffer.byteLength(text, 'utf8') > exports.SAFE_YAML_MAX_BYTES) {
+        throw new UnsafeYamlError(source, `larger than ${exports.SAFE_YAML_MAX_BYTES} bytes`);
+    }
+    let doc;
+    try {
+        doc = (0, yaml_1.parseDocument)(text, { schema: 'core', resolveKnownTags: false, merge: false, uniqueKeys: true, strict: true, prettyErrors: false });
+    }
+    catch (err) {
+        throw new UnsafeYamlError(source, err instanceof Error ? err.message : String(err));
+    }
+    const problem = doc.errors[0] ?? doc.warnings[0]; // an unresolved tag is only a warning to the library
+    if (problem)
+        throw new UnsafeYamlError(source, problem.message);
+    try {
+        return doc.toJS({ maxAliasCount: exports.SAFE_YAML_MAX_ALIAS_COUNT });
+    }
+    catch (err) {
+        throw new UnsafeYamlError(source, err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=safe-yaml-parse.js.map

package/dist/utils/safe-yaml-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-yaml-parse.js","sourceRoot":"","sources":["../../src/utils/safe-yaml-parse.ts"],"names":[],"mappings":";;;AA0BA,sCAiBC;AA3CD;;;;;;;;;;;;;GAaG;AACH,+BAAqC;AAExB,QAAA,yBAAyB,GAAG,EAAE,CAAC;AAC/B,QAAA,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAA4B,MAAc,EAAE,MAAc;QACxD,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QADJ,WAAM,GAAN,MAAM,CAAQ;QAExC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,SAAgB,aAAa,CAAC,IAAY,EAAE,MAAM,GAAG,QAAQ;IAC3D,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,2BAAmB,EAAE,CAAC;QAC1D,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,eAAe,2BAAmB,QAAQ,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,GAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,GAAG,GAAG,IAAA,oBAAa,EAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5I,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAG,qDAAqD;IACzG,IAAI,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,iCAAyB,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.34-beta.1",
+  "version": "3.3.0-alpha.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.34-beta.1",
-    "@sungen/driver-ui": "3.2.34-beta.1",
+    "@sungen/driver-data-factory": "3.3.0-alpha.1",
+    "@sungen/driver-ui": "3.3.0-alpha.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/basis/anchor-grammar.ts

@@ -0,0 +1,83 @@
+/**
+ * Anchor grammar and the shared trace vocabulary (DOS-12.1, DOS-12.2; takumi T7).
+ *
+ * | anchor                     | example                  | label       |
+ * |----------------------------|--------------------------|-------------|
+ * | `<docId>#<itemId>`         | `SPEC-AUTH-001#A-2`      | `EXTRACTED` |
+ * | `<docId>#<itemId>/val`     | `SPEC-AUTH-001#A-2/val`  | `EXTRACTED` |
+ * | `sec-<slug>`               | `sec-login-form`         | `INFERRED`  |
+ * | duplicate id / fuzzy match | —                        | `AMBIGUOUS` |
+ *
+ * docId is the spec frontmatter `id`; itemId is COMPOSED from BM-51 §4.1 (`2.0` under section row
+ * `A` → `A-2`). BM-51 has no `VAL-xx` codes: a Validation row is keyed by its item. `screen_id` is
+ * metadata and never part of an anchor. Every anchor is cited as `repo@SHA:path#Lx-Ly`.
+ */
+import { createHash } from 'crypto';
+
+export type AnchorKind = 'item' | 'validation' | 'section';
+export type AnchorConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** Score band per label (takumi confidence taxonomy): inclusive lower, inclusive upper. */
+export const CONFIDENCE_BANDS: Record<AnchorConfidence, readonly [number, number]> = {
+  EXTRACTED: [0.9, 1],
+  INFERRED: [0.5, 0.89],
+  AMBIGUOUS: [0, 0.49],
+};
+
+const DOC_ID = '[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+';
+const ITEM_ID = '[A-Z]+-\\d+(?:\\.\\d+)?';
+const ITEM_ANCHOR_RE = new RegExp(`^(${DOC_ID})#(${ITEM_ID})(/val)?$`);
+const SECTION_ANCHOR_RE = /^sec-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CITATION_RE = /^([^@\s]+)@([^:\s]+):([^#\s]+)#L(\d+)-L(\d+)$/;
+
+export interface ParsedAnchorId { kind: AnchorKind; docId?: string; itemId?: string; slug?: string }
+
+export function parseAnchorId(id: string): ParsedAnchorId | null {
+  const item = ITEM_ANCHOR_RE.exec(id);
+  if (item) return { kind: item[3] ? 'validation' : 'item', docId: item[1], itemId: item[2] };
+  if (SECTION_ANCHOR_RE.test(id)) return { kind: 'section', slug: id.slice(4) };
+  return null;
+}
+
+export function isItemAnchorId(id: string): boolean {
+  return ITEM_ANCHOR_RE.test(id);
+}
+
+export function isDocId(id: string): boolean {
+  return new RegExp(`^${DOC_ID}$`).test(id);
+}
+
+export function itemAnchorId(docId: string, itemId: string, validation = false): string {
+  return `${docId}#${itemId}${validation ? '/val' : ''}`;
+}
+
+/**
+ * BM-51 §4.1 numbers items `1.0, 2.0 …` under a bold section row; the composed id drops the `.0`
+ * (`2.0` under `A` → `A-2`) and keeps a real sub-number (`2.1` → `A-2.1`). No section → null.
+ */
+export function composeItemId(section: string | null, itemNumber: string): string | null {
+  if (!section || !/^[A-Z]+$/.test(section)) return null;
+  const n = itemNumber.trim().replace(/\.0+$/, '');
+  return /^\d+(?:\.\d+)?$/.test(n) ? `${section}-${n}` : null;
+}
+
+/** `sec-<slug>` from a heading: accents folded, ASCII kebab-case; a script with no ASCII gets a hash. */
+export function sectionAnchorId(heading: string): string {
+  const slug = heading.normalize('NFKD').replace(/\p{M}/gu, '').replace(/[đĐ]/g, 'd').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return `sec-${slug || createHash('sha1').update(heading).digest('hex').slice(0, 8)}`;
+}
+
+export interface CitationBase { repo: string; sha: string; path: string }
+
+export function formatCitation(base: CitationBase, startLine: number, endLine: number): string {
+  return `${base.repo}@${base.sha}:${base.path.replace(/\\/g, '/')}#L${startLine}-L${endLine}`;
+}
+
+export function parseCitation(s: string): (CitationBase & { start: number; end: number }) | null {
+  const m = CITATION_RE.exec(s);
+  if (!m) return null;
+  const start = Number(m[4]);
+  const end = Number(m[5]);
+  return start >= 1 && end >= start ? { repo: m[1], sha: m[2], path: m[3], start, end } : null;
+}

package/src/basis/anchor-hash.ts

@@ -0,0 +1,27 @@
+/**
+ * Hash by anchor kind (DOS-12.3, red-team #1).
+ *
+ * | anchor kind                  | hash        | why                                                      |
+ * |------------------------------|-------------|----------------------------------------------------------|
+ * | section `sec-<slug>` (legacy) | `sha1-12`   | every manifest already on disk holds these; a new algorithm would read "changed" everywhere |
+ * | item `<docId>#<itemId>`       | `sha256-12` | new in schema 2, so nothing old depends on it            |
+ *
+ * `sectionHash` is the exact computation the manifest has always used: sha1 over the section
+ * body joined with LF and trimmed, first 12 hex. Do not "improve" it.
+ */
+import { createHash } from 'crypto';
+
+export type HashAlgo = 'sha1-12' | 'sha256-12';
+
+export function sectionHash(bodyLines: string[]): string {
+  return createHash('sha1').update(bodyLines.join('\n').trim()).digest('hex').slice(0, 12);
+}
+
+/** One table row as compared: cells trimmed, inner whitespace collapsed, joined by `|`. */
+export function normalizeRow(cells: string[]): string {
+  return cells.map((c) => c.normalize('NFC').replace(/\s+/g, ' ').trim()).join('|');
+}
+
+export function itemRowHash(cells: string[]): string {
+  return createHash('sha256').update(normalizeRow(cells)).digest('hex').slice(0, 12);
+}

package/src/basis/bm51-tables.ts

@@ -0,0 +1,65 @@
+/**
+ * Read the BM-51 screen-spec tables that carry item ids (company standard, DOS-12.0).
+ *
+ * `reports/mng/specs/_templates/BM-2-901-51-screen-specification-template.md`:
+ *   §4.1 Item          `| ID | Item Name | Item Type | Required | Note |`  — bold section row `A`, then `1.0`, `2.0` …
+ *   §4.2 Validation    `| ID | Type | Min | Max | Default | … |`          — rows keyed by the composed id `A-2`
+ *   §4.3 Data Mapping  `| ID | Data Source | API ID | … |`                — same key
+ *   §5   Event         `| ID | Given (Pre-condition) | … |`               — same key, or `-`
+ *
+ * Tables are recognised by their header (first column `ID` plus the second column's name), not by
+ * heading numbers, so a translated heading still reads. Rows keep their 1-based source line.
+ */
+import { composeItemId } from './anchor-grammar';
+
+export type Bm51TableKind = 'item' | 'validation' | 'mapping' | 'event';
+
+export interface Bm51Row { table: Bm51TableKind; cells: string[]; id: string; line: number }
+export interface Bm51ItemRow extends Bm51Row { section: string | null; itemId: string | null }
+export interface Bm51Tables { items: Bm51ItemRow[]; validations: Bm51Row[]; mappings: Bm51Row[]; events: Bm51Row[] }
+
+const SEPARATOR = /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+const COMPOSED_ID = /^[A-Z]+-\d+(?:\.\d+)?$/;
+
+function splitRow(line: string): string[] {
+  const body = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return body.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}
+const bare = (cell: string): string => cell.replace(/\*\*|__|`/g, '').trim();
+
+function kindOf(header: string[]): Bm51TableKind | null {
+  if (bare(header[0] ?? '').toUpperCase() !== 'ID') return null;
+  const second = bare(header[1] ?? '').toLowerCase();
+  if (second === 'item name') return 'item';
+  if (second === 'type') return 'validation';
+  if (second === 'data source') return 'mapping';
+  if (second.startsWith('given')) return 'event';
+  return null;
+}
+
+/** `lines` are the spec's lines; `firstLine` is the 1-based number of `lines[0]`. */
+export function readBm51Tables(lines: string[], firstLine = 1): Bm51Tables {
+  const out: Bm51Tables = { items: [], validations: [], mappings: [], events: [] };
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (!lines[i].trim().startsWith('|') || !SEPARATOR.test(lines[i + 1].trim())) continue;
+    const kind = kindOf(splitRow(lines[i]));
+    let j = i + 2;
+    let section: string | null = null;
+    for (; j < lines.length && lines[j].trim().startsWith('|'); j++) {
+      if (!kind) continue;
+      const cells = splitRow(lines[j]);
+      const id = bare(cells[0] ?? '');
+      const line = firstLine + j;
+      if (kind === 'item') {
+        if (/^[A-Z]+$/.test(id)) { section = id; continue; }
+        if (!/^\d+(?:\.\d+)?$/.test(id)) continue;
+        out.items.push({ table: kind, cells, id, line, section, itemId: composeItemId(section, id) });
+      } else if (COMPOSED_ID.test(id)) {
+        const row: Bm51Row = { table: kind, cells, id, line };
+        (kind === 'validation' ? out.validations : kind === 'mapping' ? out.mappings : out.events).push(row);
+      }
+    }
+    i = j - 1;
+  }
+  return out;
+}

package/src/basis/extract-spec-anchors.ts

@@ -0,0 +1,95 @@
+/**
+ * Every anchor a `spec.md` offers, with its hash, confidence label and citation (DOS-12.1 – 12.3).
+ *
+ *   section  `sec-<slug>`             sha1-12 of the section body (the manifest's hash)   INFERRED
+ *   item     `<docId>#<itemId>`       sha256-12 of the normalized §4.1 row                EXTRACTED
+ *   val      `<docId>#<itemId>/val`   sha256-12 of the normalized §4.2 row                EXTRACTED
+ *   a duplicate id, or a §4.2 row naming no §4.1 item                                    AMBIGUOUS
+ *
+ * A §4.3 / §5 row naming no §4.1 item is reported in `orphans` (AMBIGUOUS, not an error). Item
+ * anchors need a docId (frontmatter `id`); without one only section anchors exist. Pointers and
+ * hashes only — no spec text leaves this function (red-team #14).
+ */
+import { AnchorConfidence, AnchorKind, CitationBase, formatCitation, itemAnchorId, sectionAnchorId } from './anchor-grammar';
+import { HashAlgo, itemRowHash, sectionHash } from './anchor-hash';
+import { readBm51Tables } from './bm51-tables';
+import { normalizeSectionName, readSpecSectionBlocks } from './spec-sections';
+import { readSpecFrontmatter, SpecFrontmatter } from './spec-frontmatter';
+
+export interface SourceAnchor {
+  id: string;
+  kind: AnchorKind;
+  confidence: AnchorConfidence;
+  hash: string;
+  hashAlgo: HashAlgo;
+  location: string;
+  /** Why the label is AMBIGUOUS. */
+  note?: string;
+}
+
+export interface OrphanReference { table: 'mapping' | 'event'; itemId: string; location: string; confidence: 'AMBIGUOUS' }
+
+export interface SpecAnchors {
+  frontmatter: SpecFrontmatter;
+  anchors: SourceAnchor[];
+  orphans: OrphanReference[];
+  problems: string[];
+}
+
+/** Mark every anchor whose id occurs more than once as AMBIGUOUS — a human must pick. */
+function flagDuplicates(anchors: SourceAnchor[]): void {
+  const count = new Map<string, number>();
+  for (const a of anchors) count.set(a.id, (count.get(a.id) ?? 0) + 1);
+  for (const a of anchors) {
+    if ((count.get(a.id) ?? 0) > 1) { a.confidence = 'AMBIGUOUS'; a.note = 'duplicate id'; }
+  }
+}
+
+export function extractSpecAnchors(text: string, citation: CitationBase): SpecAnchors {
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n');
+  const fm = readSpecFrontmatter(text, citation.path);
+  const problems = [...fm.problems];
+  const cite = (start: number, end: number): string => formatCitation(citation, start, end);
+
+  const sections: SourceAnchor[] = readSpecSectionBlocks(lines).map((s) => ({
+    id: sectionAnchorId(normalizeSectionName(s.name)),
+    kind: 'section',
+    confidence: 'INFERRED',
+    hash: sectionHash(s.body),
+    hashAlgo: 'sha1-12',
+    location: cite(s.headingIndex + 1, s.headingIndex + 1 + s.body.length),
+  }));
+  flagDuplicates(sections);
+
+  const docId = fm.frontmatter.id;
+  const tables = readBm51Tables(lines);
+  const items: SourceAnchor[] = [];
+  const orphans: OrphanReference[] = [];
+  if (!docId) {
+    if (tables.items.length) problems.push(`${citation.path}: a BM-51 item table is present but the frontmatter has no id; no item anchors`);
+    return { frontmatter: fm.frontmatter, anchors: sections, orphans, problems };
+  }
+
+  for (const row of tables.items) {
+    if (!row.itemId) { problems.push(`${citation.path}:${row.line}: item ${row.id} has no section row above it; skipped`); continue; }
+    items.push({ id: itemAnchorId(docId, row.itemId), kind: 'item', confidence: 'EXTRACTED', hash: itemRowHash(row.cells), hashAlgo: 'sha256-12', location: cite(row.line, row.line) });
+  }
+  flagDuplicates(items);
+  const known = new Set(tables.items.map((r) => r.itemId).filter(Boolean));
+
+  const vals: SourceAnchor[] = tables.validations.map((row) => ({
+    id: itemAnchorId(docId, row.id, true),
+    kind: 'validation',
+    confidence: known.has(row.id) ? 'EXTRACTED' : 'AMBIGUOUS',
+    hash: itemRowHash(row.cells),
+    hashAlgo: 'sha256-12',
+    location: cite(row.line, row.line),
+    ...(known.has(row.id) ? {} : { note: 'no §4.1 item with this id' }),
+  }));
+  flagDuplicates(vals);
+
+  for (const row of [...tables.mappings, ...tables.events]) {
+    if (!known.has(row.id)) orphans.push({ table: row.table as 'mapping' | 'event', itemId: row.id, location: cite(row.line, row.line), confidence: 'AMBIGUOUS' });
+  }
+  return { frontmatter: fm.frontmatter, anchors: [...items, ...vals, ...sections], orphans, problems };
+}

package/src/basis/migration-sentinel.ts

@@ -0,0 +1,175 @@
+/**
+ * Write-ahead sentinel for migrations and re-baselines (takumi T6, DOS-13.6).
+ *
+ * Before a migration writes anything it records `.sungen/migrations/<slug>.pending.json`: every
+ * file it will touch plus a copy of each one's current bytes (or "did not exist"). The sentinel is
+ * deleted when the migration completes. An error inside the migration rolls the copies back at
+ * once; only a process that DIES mid-migration leaves the sentinel behind — and then the next run
+ * stops and asks a human for REVERT (restore every copy byte for byte) or KEEP (keep the new
+ * files). It never continues silently. (Reference: reports/takumi/docs/system-architecture.md:656-677.)
+ *
+ * A sentinel carries pid, host and startedAt. While its writer is alive on this host and it is under a
+ * minute old, another run is simply migrating: the answer is "retry", not a REVERT/KEEP prompt. Only a
+ * dead writer or an old sentinel is an interrupted migration. One slug per unit covers both writers:
+ * the waiver import (DOS-13.5) and the manifest upgrade to schema 2 on save (DOS-12.3).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createFileExclusive } from '../decisions/exclusive-file-create';
+
+export interface SentinelFile { path: string; existed: boolean; contentBase64?: string }
+export interface PendingMigration {
+  schema: 1; unit: string; slug: string; reason: string; startedAt: string; pid?: number; host?: string; files: SentinelFile[];
+}
+export type MigrationChoice = 'REVERT' | 'KEEP';
+export const IN_PROGRESS_WINDOW_MS = 60_000;
+
+export function sentinelPath(projectRoot: string, slug: string): string {
+  return path.join(projectRoot, '.sungen', 'migrations', `${slug}.pending.json`);
+}
+
+export class PendingMigrationError extends Error {
+  constructor(public readonly unit: string, public readonly slug: string, public readonly file: string, detail: string) {
+    super(
+      `An interrupted migration left ${file} (${detail}).\n`
+      + '  Nothing continues until a human chooses: REVERT restores every file it lists byte for byte;\n'
+      + `  KEEP keeps the new files. Run in a terminal and answer the prompt:  sungen journey --screen ${unit}`,
+    );
+    this.name = 'PendingMigrationError';
+  }
+}
+
+/** The sentinel, or null when there is none. An unreadable sentinel still exists: `files` is then empty. */
+export function readPendingMigration(projectRoot: string, slug: string): (PendingMigration & { readable: boolean }) | null {
+  const p = sentinelPath(projectRoot, slug);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as PendingMigration;
+    if (raw && raw.schema === 1 && Array.isArray(raw.files)) return { ...raw, readable: true };
+  } catch { /* fall through: a sentinel that cannot be read is still a stop sign */ }
+  return { schema: 1, unit: slug, slug, reason: 'unreadable sentinel', startedAt: '?', files: [], readable: false };
+}
+
+export class MigrationInProgressError extends Error {
+  constructor(public readonly unit: string, detail: string) {
+    super(`Another sungen run is migrating ${unit} right now (${detail}). Retry in a moment — nothing was changed.`);
+    this.name = 'MigrationInProgressError';
+  }
+}
+
+function pidAlive(pid: unknown): boolean {
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+/** in-progress: under a minute old and written by a process alive on this host (another host cannot be checked). */
+export function pendingMigrationState(p: PendingMigration & { readable: boolean }): 'in-progress' | 'interrupted' {
+  if (!p.readable) return 'interrupted';
+  const age = Date.now() - Date.parse(p.startedAt);
+  if (!(age >= 0 && age < IN_PROGRESS_WINDOW_MS)) return 'interrupted';
+  if (p.host !== os.hostname()) return 'in-progress';
+  return pidAlive(p.pid) ? 'in-progress' : 'interrupted';
+}
+
+function pendingError(projectRoot: string, slug: string, pending: PendingMigration & { readable: boolean }): Error {
+  if (pendingMigrationState(pending) === 'in-progress') {
+    const age = Math.round((Date.now() - Date.parse(pending.startedAt)) / 1000);
+    return new MigrationInProgressError(pending.unit, `pid ${pending.pid} on ${pending.host}, started ${age}s ago: ${pending.reason}`);
+  }
+  const rel = path.relative(projectRoot, sentinelPath(projectRoot, slug));
+  return new PendingMigrationError(pending.unit, slug, rel, `started ${pending.startedAt}: ${pending.reason}`);
+}
+
+/** Throws MigrationInProgressError (retry) or PendingMigrationError (REVERT/KEEP) when a sentinel exists. */
+export function assertNoPendingMigration(projectRoot: string, slug: string): void {
+  const pending = readPendingMigration(projectRoot, slug);
+  if (pending) throw pendingError(projectRoot, slug, pending);
+}
+
+/** A sentinel path must stay inside the project — it is data read back from disk. */
+function inside(projectRoot: string, rel: string): string {
+  const abs = path.resolve(projectRoot, rel);
+  const back = path.relative(path.resolve(projectRoot), abs);
+  if (path.isAbsolute(rel) || back === '' || back.startsWith('..') || path.isAbsolute(back)) {
+    throw new Error(`refusing to restore "${rel}": outside the project`);
+  }
+  return abs;
+}
+
+/** Bytes, not text: REVERT must restore a file exactly, whatever its encoding. Tmp + rename = atomic. */
+function writeBytesAtomic(abs: string, bytes: Buffer): void {
+  const tmp = `${abs}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, bytes);
+    fs.renameSync(tmp, abs);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+function restore(projectRoot: string, files: SentinelFile[]): string[] {
+  const done: string[] = [];
+  for (const f of files) {
+    const abs = inside(projectRoot, f.path);
+    if (f.existed) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      writeBytesAtomic(abs, Buffer.from(f.contentBase64 ?? '', 'base64'));
+    } else {
+      fs.rmSync(abs, { force: true });
+    }
+    done.push(f.path);
+  }
+  return done;
+}
+
+/**
+ * Run `write` under a sentinel covering `files` (absolute paths). The sentinel is written atomically
+ * before `write` starts and removed after it returns. If `write` throws, the copies are restored and
+ * the sentinel removed before the error is rethrown; a failed rollback leaves the sentinel in place.
+ */
+export function withMigrationSentinel<T>(
+  projectRoot: string, unit: string, slug: string, reason: string, files: string[], write: () => T,
+): T {
+  assertNoPendingMigration(projectRoot, slug);
+  const snapshot: SentinelFile[] = files.map((abs) => {
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    inside(projectRoot, rel);
+    return fs.existsSync(abs)
+      ? { path: rel, existed: true, contentBase64: fs.readFileSync(abs).toString('base64') }
+      : { path: rel, existed: false };
+  });
+  const p = sentinelPath(projectRoot, slug);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const pending: PendingMigration = {
+    schema: 1, unit, slug, reason, startedAt: new Date().toISOString(), pid: process.pid, host: os.hostname(), files: snapshot,
+  };
+  // Exclusive: a second migration of the same unit racing this one cannot also believe it holds it.
+  if (!createFileExclusive(p, `${JSON.stringify(pending, null, 2)}\n`)) {
+    const holder = readPendingMigration(projectRoot, slug);
+    throw holder ? pendingError(projectRoot, slug, holder) : new MigrationInProgressError(unit, 'it just finished');
+  }
+  let result: T;
+  try {
+    result = write();
+  } catch (err) {
+    restore(projectRoot, snapshot);   // throws → the sentinel stays: the next run asks REVERT/KEEP
+    fs.rmSync(p, { force: true });
+    throw err;
+  }
+  fs.rmSync(p, { force: true });
+  return result;
+}
+
+/** Answer a leftover sentinel. REVERT restores every listed file exactly; KEEP only removes the sentinel. */
+export function resolvePendingMigration(projectRoot: string, slug: string, choice: MigrationChoice): string[] {
+  const pending = readPendingMigration(projectRoot, slug);
+  if (!pending) return [];
+  if (choice === 'REVERT' && !pending.readable) {
+    throw new Error(`${sentinelPath(projectRoot, slug)} cannot be read, so there is nothing to restore from — choose KEEP.`);
+  }
+  const restored = choice === 'REVERT' ? restore(projectRoot, pending.files) : [];
+  fs.rmSync(sentinelPath(projectRoot, slug), { force: true });
+  return restored;
+}