@nurix/etna 0.18.20 → 0.18.22

package/data/harnesses/code/skills/design/scripts/validate-combinations.mjs

@@ -0,0 +1,314 @@
+// skills/design/scripts/validate-combinations.mjs — schema validator for the combination datasets (data/combinations/): file presence, byte-exact headers, sequential ids, tier/density/surface vocabularies, symbol-glyph ban, palette hex + WCAG contrast floors, chart token discipline, lucide/font registry membership, and manifest row-count parity. Importable (validateCombinations(dir)) and runnable as a CLI.
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = join(SCRIPTS_DIR, "..");
+const DEFAULT_DIR = join(SKILL_ROOT, "data/combinations");
+
+const CSV_FILES = ["typography.csv", "palettes.csv", "styles.csv", "product-router.csv", "charts.csv", "icons.csv", "landing.csv"];
+const REQUIRED_FILES = [...CSV_FILES, "manifest.json", "lucide-names.json", "fonts-known.json", "Readme.md"];
+
+// Byte-exact, order-exact header contract per dataset.
+const HEADERS = {
+    "typography.csv": ["id", "pairing", "tier", "heading_family", "body_family", "mono_family", "contrast", "mood", "best_for", "heading_weights", "body_weights", "google_fonts_css", "notes"],
+    "palettes.csv": ["id", "palette", "tier", "product_affinity", "mood", "background", "foreground", "card", "card-foreground", "popover", "popover-foreground", "muted", "muted-foreground", "border", "input", "ring", "primary", "primary-foreground", "secondary", "secondary-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground", "success", "warning", "chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground", "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring", "notes"],
+    "styles.csv": ["id", "movement", "tier", "era", "keywords", "description", "palette_stance", "type_stance", "shape_stance", "motion_stance", "density_affinity", "best_for", "avoid_for", "token_leanings", "operator_note"],
+    "product-router.csv": ["id", "product_type", "tier", "keywords", "style_priority", "palette_stance", "type_stance", "density_tier", "key_surfaces", "decision_rules", "anti_patterns", "notes"],
+    "charts.csv": ["id", "data_shape", "tier", "keywords", "best_chart", "alternatives", "when", "when_not", "volume_guidance", "series_tokens", "a11y_notes", "fallback", "interaction"],
+    "icons.csv": ["id", "intent", "tier", "keywords", "lucide_name", "import_name", "usage", "notes"],
+    "landing.csv": ["id", "pattern", "tier", "keywords", "section_order", "cta_placement", "color_strategy", "effects", "conversion_notes"],
+};
+
+const VALID_TIERS = new Set(["operator-active", "dormant-marketing"]);
+const VALID_DENSITIES = new Set(["spacious", "standard", "dense"]);
+const VALID_TYPE_CONTRASTS = new Set(["serif+sans", "sans+sans", "sans+serif", "serif+serif", "display+sans", "mono+sans"]);
+const VALID_KEY_SURFACES = new Set(["list-detail", "dashboard", "entity-detail", "create-edit", "log-stream", "command-center"]);
+
+const UPPER_HEX = /^#[0-9A-F]{6}$/;
+const RAW_HEX_ANYWHERE = /#[0-9a-fA-F]{3,8}\b/;
+// Box drawing, geometric shapes, misc symbols, dingbats, misc symbols-and-arrows, VS16, and emoji — covers ✓ ⚡ ◐ ☐ and kin.
+const BANNED_GLYPHS = new RegExp("[\\u2500-\\u25FF\\u2600-\\u27BF\\u2B00-\\u2BFF\\uFE0F]|\\p{Extended_Pictographic}", "u");
+
+// Foreground-on-base pairs that must clear WCAG AA text contrast (>= 4.5:1).
+const AA_TEXT_PAIRS = [
+    ["background", "foreground"], ["card", "card-foreground"], ["popover", "popover-foreground"],
+    ["muted", "muted-foreground"], ["primary", "primary-foreground"], ["secondary", "secondary-foreground"],
+    ["accent", "accent-foreground"], ["destructive", "destructive-foreground"],
+    ["sidebar", "sidebar-foreground"], ["sidebar-primary", "sidebar-primary-foreground"],
+    ["sidebar-accent", "sidebar-accent-foreground"],
+];
+// Status/series colors that must clear >= 3:1 against background.
+const GRAPHIC_VS_BACKGROUND = ["success", "warning", "chart-1", "chart-2", "chart-3", "chart-4", "chart-5"];
+// The 34 color cells: everything between background and sidebar-ring inclusive in the palettes header.
+const PALETTE_COLOR_COLUMNS = HEADERS["palettes.csv"].slice(
+    HEADERS["palettes.csv"].indexOf("background"),
+    HEADERS["palettes.csv"].indexOf("sidebar-ring") + 1
+);
+
+// Read a UTF-8 file, returning null when it does not exist.
+function readSafe(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+// Parse RFC4180-style CSV text into an array of field arrays (quotes + doubled-quote escapes honored).
+function parseCsv(text) {
+    const rows = [];
+    let field = "";
+    let record = [];
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') { field += '"'; i++; }
+                else inQuotes = false;
+            } else field += ch;
+        } else if (ch === '"') inQuotes = true;
+        else if (ch === ",") { record.push(field); field = ""; }
+        else if (ch === "\n") { record.push(field); rows.push(record); record = []; field = ""; }
+        else if (ch === "\r") { /* skip */ }
+        else field += ch;
+    }
+    if (field.length > 0 || record.length > 0) { record.push(field); rows.push(record); }
+    return rows;
+}
+
+// WCAG 2.x relative luminance of an uppercase #RRGGBB hex.
+function relativeLuminance(hex) {
+    const chan = (v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    };
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return 0.2126 * chan(r) + 0.7152 * chan(g) + 0.0722 * chan(b);
+}
+
+// WCAG contrast ratio between two #RRGGBB hex colors.
+function contrastRatio(hexA, hexB) {
+    const la = relativeLuminance(hexA);
+    const lb = relativeLuminance(hexB);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+
+// Load one CSV into { header, rows: [{...byExpectedColumn, _cells, _line}] }, or null (recording an error) when absent.
+function loadCsv(dir, file, errors) {
+    const text = readSafe(join(dir, file));
+    if (text === null) return null;
+    const raw = parseCsv(text).filter((r) => r.length > 1 || (r.length === 1 && r[0].trim() !== ""));
+    if (raw.length === 0) { errors.push(`${file}: file is empty`); return null; }
+    const expected = HEADERS[file];
+    const rows = raw.slice(1).map((cells, i) => {
+        const obj = {};
+        expected.forEach((k, idx) => { obj[k] = cells[idx] !== undefined ? cells[idx] : ""; });
+        obj._cells = cells;
+        obj._line = i + 2; // 1-based, after the header line
+        return obj;
+    });
+    return { header: raw[0], rows };
+}
+
+// Generic invariants shared by every dataset: exact header, column counts, sequential ids, unique names, valid tier, no symbol glyphs.
+function checkGeneric(file, csv, errors) {
+    const expected = HEADERS[file];
+    if (csv.header.length !== expected.length || expected.some((h, i) => csv.header[i] !== h))
+        errors.push(`${file}: header mismatch: expected [${expected.join(",")}] got [${csv.header.join(",")}]`);
+
+    const nameCol = expected[1];
+    const seenNames = new Map();
+    csv.rows.forEach((row, i) => {
+        if (row._cells.length !== expected.length)
+            errors.push(`${file} row ${row._line}: has ${row._cells.length} columns, expected ${expected.length}`);
+
+        if (!/^\d+$/.test(row.id) || parseInt(row.id, 10) !== i + 1)
+            errors.push(`${file} row ${row._line}: id "${row.id}" breaks 1..N sequence (expected ${i + 1})`);
+
+        const name = row[nameCol];
+        if (seenNames.has(name)) errors.push(`${file} row ${row._line}: duplicate ${nameCol} "${name}" (first at row ${seenNames.get(name)})`);
+        else seenNames.set(name, row._line);
+
+        if (!VALID_TIERS.has(row.tier))
+            errors.push(`${file} row ${row._line}: invalid tier "${row.tier}" (want operator-active|dormant-marketing)`);
+
+        for (const cell of row._cells) {
+            const m = BANNED_GLYPHS.exec(cell);
+            if (m) { errors.push(`${file} row ${row._line}: cell contains banned symbol glyph "${m[0]}"`); break; }
+        }
+    });
+}
+
+// palettes.csv: uppercase 6-digit hex in all 34 color cells + WCAG contrast floors.
+function checkPalettes(csv, errors) {
+    for (const row of csv.rows) {
+        const valid = {};
+        for (const col of PALETTE_COLOR_COLUMNS) {
+            const v = row[col];
+            if (!UPPER_HEX.test(v)) errors.push(`palettes.csv row ${row._line} (${row.palette}): ${col} "${v}" is not uppercase #RRGGBB`);
+            else valid[col] = v;
+        }
+        for (const [base, fg] of AA_TEXT_PAIRS) {
+            if (!valid[base] || !valid[fg]) continue;
+            const ratio = contrastRatio(valid[base], valid[fg]);
+            if (ratio < 4.5) errors.push(`palettes.csv row ${row._line} (${row.palette}): ${fg} on ${base} contrast ${ratio.toFixed(2)}:1 < 4.5:1`);
+        }
+        for (const col of GRAPHIC_VS_BACKGROUND) {
+            if (!valid[col] || !valid.background) continue;
+            const ratio = contrastRatio(valid[col], valid.background);
+            if (ratio < 3) errors.push(`palettes.csv row ${row._line} (${row.palette}): ${col} vs background contrast ${ratio.toFixed(2)}:1 < 3:1`);
+        }
+    }
+}
+
+// charts.csv: operator-active only, --chart-N discipline in series_tokens, N in 1..5 everywhere, no raw hex.
+function checkCharts(csv, errors) {
+    for (const row of csv.rows) {
+        if (row.tier !== "operator-active")
+            errors.push(`charts.csv row ${row._line} (${row.data_shape}): tier must be operator-active (got "${row.tier}")`);
+        if (!/--chart-\d/.test(row.series_tokens))
+            errors.push(`charts.csv row ${row._line} (${row.data_shape}): series_tokens mentions no --chart-N token`);
+        if (RAW_HEX_ANYWHERE.test(row.series_tokens))
+            errors.push(`charts.csv row ${row._line} (${row.data_shape}): series_tokens contains raw hex "${RAW_HEX_ANYWHERE.exec(row.series_tokens)[0]}"`);
+        for (const cell of row._cells) {
+            for (const m of cell.matchAll(/--chart-(\d+)/g)) {
+                const n = parseInt(m[1], 10);
+                if (n < 1 || n > 5) errors.push(`charts.csv row ${row._line} (${row.data_shape}): --chart-${m[1]} out of range 1..5`);
+            }
+        }
+    }
+}
+
+// icons.csv rows against the lucide-names.json registry (kebab -> Pascal).
+function checkIcons(csv, dir, errors) {
+    const text = readSafe(join(dir, "lucide-names.json"));
+    if (text === null) return; // presence already reported
+    let reg;
+    try { reg = JSON.parse(text); } catch { errors.push("lucide-names.json does not parse as JSON"); return; }
+    for (const key of ["lucide_react_version", "fetched", "source", "icons"])
+        if (!(key in reg)) errors.push(`lucide-names.json: missing key "${key}"`);
+    if (typeof reg.icons !== "object" || reg.icons === null) { errors.push("lucide-names.json: \"icons\" is not an object"); return; }
+    if (!csv) return;
+    for (const row of csv.rows) {
+        if (!(row.lucide_name in reg.icons))
+            errors.push(`icons.csv row ${row._line} (${row.intent}): lucide_name "${row.lucide_name}" not in lucide-names.json`);
+        else if (row.import_name !== reg.icons[row.lucide_name])
+            errors.push(`icons.csv row ${row._line} (${row.intent}): import_name "${row.import_name}" != registry "${reg.icons[row.lucide_name]}"`);
+    }
+}
+
+// typography.csv rows against the fonts-known.json registry (family -> known weights) + contrast vocabulary.
+function checkTypography(csv, dir, errors) {
+    const text = readSafe(join(dir, "fonts-known.json"));
+    if (text === null) return; // presence already reported
+    let reg;
+    try { reg = JSON.parse(text); } catch { errors.push("fonts-known.json does not parse as JSON"); return; }
+    for (const key of ["fetched", "source", "families"])
+        if (!(key in reg)) errors.push(`fonts-known.json: missing key "${key}"`);
+    if (typeof reg.families !== "object" || reg.families === null) { errors.push("fonts-known.json: \"families\" is not an object"); return; }
+    if (!csv) return;
+    for (const row of csv.rows) {
+        for (const col of ["heading_family", "body_family", "mono_family"])
+            if (!(row[col] in reg.families))
+                errors.push(`typography.csv row ${row._line} (${row.pairing}): ${col} "${row[col]}" not in fonts-known.json`);
+        for (const [weightsCol, familyCol] of [["heading_weights", "heading_family"], ["body_weights", "body_family"]]) {
+            const known = reg.families[row[familyCol]];
+            if (!Array.isArray(known)) continue; // family membership error already reported
+            for (const tok of row[weightsCol].split(";").map((t) => t.trim()).filter((t) => t !== "")) {
+                if (!/^\d+$/.test(tok)) errors.push(`typography.csv row ${row._line} (${row.pairing}): ${weightsCol} entry "${tok}" is not an integer`);
+                else if (!known.includes(parseInt(tok, 10)))
+                    errors.push(`typography.csv row ${row._line} (${row.pairing}): weight ${tok} not a known weight of ${row[familyCol]} (known: ${known.join(",")})`);
+            }
+        }
+        if (!VALID_TYPE_CONTRASTS.has(row.contrast))
+            errors.push(`typography.csv row ${row._line} (${row.pairing}): invalid contrast "${row.contrast}"`);
+    }
+}
+
+// styles.csv / product-router.csv density vocabulary + product-router key_surfaces vocabulary.
+function checkDensityAndSurfaces(file, csv, errors) {
+    const densityCol = file === "styles.csv" ? "density_affinity" : "density_tier";
+    const nameCol = HEADERS[file][1];
+    for (const row of csv.rows) {
+        if (!VALID_DENSITIES.has(row[densityCol]))
+            errors.push(`${file} row ${row._line} (${row[nameCol]}): invalid ${densityCol} "${row[densityCol]}" (want spacious|standard|dense)`);
+        if (file === "product-router.csv" && row.tier === "operator-active") {
+            for (const surface of row.key_surfaces.split(",").map((s) => s.trim()).filter((s) => s !== ""))
+                if (!VALID_KEY_SURFACES.has(surface))
+                    errors.push(`product-router.csv row ${row._line} (${row.product_type}): unknown key_surface "${surface}"`);
+        }
+    }
+}
+
+// landing.csv: dormant-marketing on every row.
+function checkLanding(csv, errors) {
+    for (const row of csv.rows)
+        if (row.tier !== "dormant-marketing")
+            errors.push(`landing.csv row ${row._line} (${row.pattern}): tier must be dormant-marketing (got "${row.tier}")`);
+}
+
+// manifest.json: datasets entry per CSV with the required keys and a rows.total matching the actual row count.
+function checkManifest(dir, csvs, errors) {
+    const text = readSafe(join(dir, "manifest.json"));
+    if (text === null) return; // presence already reported
+    let manifest;
+    try { manifest = JSON.parse(text); } catch { errors.push("manifest.json does not parse as JSON"); return; }
+    if (typeof manifest.datasets !== "object" || manifest.datasets === null) { errors.push("manifest.json: missing \"datasets\" object"); return; }
+    for (const file of CSV_FILES) {
+        const entry = manifest.datasets[file] ?? manifest.datasets[file.replace(/\.csv$/, "")];
+        if (entry === undefined) { errors.push(`manifest.json: datasets has no entry for ${file}`); continue; }
+        for (const key of ["seed", "research", "quality_bar", "rows", "refresh_trigger"])
+            if (!(key in entry)) errors.push(`manifest.json: datasets entry for ${file} missing key "${key}"`);
+        const total = entry.rows && typeof entry.rows === "object" ? entry.rows.total : undefined;
+        if (typeof total !== "number") errors.push(`manifest.json: datasets entry for ${file} has no numeric rows.total`);
+        else if (csvs[file] && total !== csvs[file].rows.length)
+            errors.push(`manifest.json: ${file} rows.total=${total} but the CSV has ${csvs[file].rows.length} data rows`);
+    }
+}
+
+// Validate every combination dataset in `dir`; returns a self-integrity-shaped result.
+export function validateCombinations(dir) {
+    const name = "combination-data validation";
+    if (!existsSync(dir))
+        return { name, pass: false, detail: "combinations dir missing", errors: [`${dir} does not exist`] };
+
+    const errors = [];
+    for (const file of REQUIRED_FILES)
+        if (!existsSync(join(dir, file))) errors.push(`missing ${file}`);
+
+    const csvs = {};
+    for (const file of CSV_FILES) {
+        const csv = loadCsv(dir, file, errors);
+        csvs[file] = csv;
+        if (csv) checkGeneric(file, csv, errors);
+    }
+
+    if (csvs["palettes.csv"]) checkPalettes(csvs["palettes.csv"], errors);
+    if (csvs["charts.csv"]) checkCharts(csvs["charts.csv"], errors);
+    checkIcons(csvs["icons.csv"], dir, errors);
+    checkTypography(csvs["typography.csv"], dir, errors);
+    if (csvs["styles.csv"]) checkDensityAndSurfaces("styles.csv", csvs["styles.csv"], errors);
+    if (csvs["product-router.csv"]) checkDensityAndSurfaces("product-router.csv", csvs["product-router.csv"], errors);
+    if (csvs["landing.csv"]) checkLanding(csvs["landing.csv"], errors);
+    checkManifest(dir, csvs, errors);
+
+    const totalRows = CSV_FILES.reduce((n, f) => n + (csvs[f] ? csvs[f].rows.length : 0), 0);
+    return { name, pass: errors.length === 0, detail: errors.length ? `${errors.length} issue(s)` : `${CSV_FILES.length} datasets, ${totalRows} rows validated`, errors };
+}
+
+// CLI entry: node validate-combinations.mjs [--dir <path>]
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    const args = process.argv.slice(2);
+    let dir = DEFAULT_DIR;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--dir") dir = resolve(args[++i] || "");
+        else if (args[i].startsWith("--dir=")) dir = resolve(args[i].slice("--dir=".length));
+    }
+    const r = validateCombinations(dir);
+    if (r.pass) { console.log(`PASS  ${r.name} — ${r.detail}`); process.exit(0); }
+    console.error(`FAIL  ${r.name} — ${r.detail}`);
+    for (const e of r.errors) console.error(`   - ${e}`);
+    process.exit(1);
+}

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance), or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record or revise an architecture decision (an AD), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance) or a one-shot migration runbook, (11) write a steering doc (system overview, domain model, glossary, non-goals, security overview, testing strategy), (12) catalog the API surface or the environment/config registry, or (13) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "AD", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD", "glossary", "domain model", "runbook", "API reference".
 ---
 
 # Technical Documentation Skill
@@ -9,12 +9,31 @@ description: Template & generator library for technical docs — the skill agent
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
+---
+
+## The Two Natures
+
+Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
+
+| | **Truth document** | **Record** |
+| --- | --- | --- |
+| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
+| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
+| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
+| Read to | Act correctly today | Trace provenance, diagnose, audit |
+| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
+
+The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
+
+- **Truth documents never narrate history.** No migration/fold stories, no dated "shipped/verified on YYYY-MM-DD" markers, no "was X → now Y" journeys, no provenance asides ("ex-`@nurix/X`, folded 2026-06-12"). When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
+- **The one bridge — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog**: the single sanctioned dated-history section inside a truth document, because for a decision the journey (what each revision reversed, and what triggered it) is part of the reasoning. The AD body stays current-truth-only; the tail carries the dates and links to the plans that implemented each revision. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents — never to a plan or changelog entry as the "read first" source.
+
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
-**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans); `docs/memory/` is the agent's dated log and is likewise exempt, and an ADR's **Decision Changelog** section is the one sanctioned dated-history section inside an active doc (the ADR body itself stays current-truth-only). A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
-
 ---
 
 ## Decision Tree
@@ -24,23 +43,39 @@ User request
     │
     ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
     │
-    ├─ "Document feature/module (LLD)" ▶ Module Template
+    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
     │
-    ├─ "Create/update changelog" ──────▶ Changelog Template
+    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
     │
-    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
     │
-    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
     │
     ├─ "Add to protected files" ───────▶ Protected Files Template
     │
-    ├─ "Record architecture decision" ─▶ ADR Template
+    ├─ "Record/revise architecture
+    │    decision" ────────────────────▶ AD Template (one per subject; revisions update it in place)
+    │
+    ├─ "System at a glance" ───────────▶ System Overview Template
+    │
+    ├─ "Domain model / glossary /
+    │    non-goals" ───────────────────▶ Steering Templates
+    │
+    ├─ "Catalog the API surface" ──────▶ API Reference Template
+    │
+    ├─ "Document env vars / config" ───▶ Environment Registry Template
+    │
+    ├─ "Security / threat model" ──────▶ Security Overview Template
+    │
+    ├─ "Testing strategy" ─────────────▶ Testing Strategy Template
+    │
+    ├─ "Recurring procedure/setup" ────▶ Operations Procedure Template
     │
-    ├─ "Document a procedure/setup" ───▶ Operations Procedure Template
+    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
     │
     ├─ "Create/update root README" ────▶ Project Root README Template
     │
-    ├─ "Create/update plan" ───────────▶ Plan Template
+    ├─ "Create/update plan" ───────────▶ Plan Template (record)
     │
     ├─ "Update existing doc" ──────────▶ Preserve existing structure
     │
@@ -51,10 +86,19 @@ User request
 
 ## Naming & Lifecycle
 
-- Features: `kebab-case.md` — living reference, status `Active`
-- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
-- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
-- Memory: `{agent-name}.md` — agent-maintained
+| Document | Nature | Name | Lifecycle |
+| --- | --- | --- | --- |
+| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
+| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
+| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
+| API reference / environment registry | Truth | fixed names | Living |
+| Operations procedure | Truth | `kebab-case.md` | Living |
+| Protected files | Truth | `protected-files.md` | Living |
+| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
+| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
+| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
+| Research | Record | `history/research/{topic}/` | Frozen snapshot |
+| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
 
 ---
 
@@ -65,7 +109,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 ### When to run
 
 - **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the Feature/Module template, project its `owns:` globs
+- **New feature doc** — when creating a doc via the Feature template, project its `owns:` globs
 - **Doc update** — when the documented scope changes, update the doc's `owns:` globs
 
 ### How to derive the frontmatter
@@ -123,6 +167,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, protected files, ADR, project root README templates |
-| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, migration runbook, protected files, AD, steering docs (system overview, domain model, glossary, non-goals, security, testing strategy), API reference, environment registry, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/code/skills/documentation/references/examples.md

@@ -151,6 +151,46 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 
 ---
 
+## Example 5: Architecture Decision revision
+
+### ❌ Bad: Supersession chain
+
+```
+docs/architecture/decisions/
+├── AD-002-auth-keycloak.md        (status: Superseded)
+├── AD-006-auth-better-auth.md     (status: Superseded, "supersedes AD-002")
+└── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
+```
+
+**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
+
+### ✅ Good: One subject, updated in place
+
+```
+docs/architecture/decisions/
+└── AD-002-auth.md                 (status: Accepted, last-updated bumped)
+```
+
+```markdown
+## Decision
+
+We use Better Auth with one-shot credential issuance…   ← current truth, no journey
+
+…
+
+## Decision Changelog
+
+- 2026-05-02 — Moved issuance to one-shot tokens because refresh-token theft
+  surfaced in review. Implemented by [plan](…). (Previously: long-lived refresh tokens.)
+- 2026-03-18 — Replaced Keycloak with Better Auth because self-hosting cost
+  outweighed SSO needs. Implemented by [plan](…). (Previously: Keycloak.)
+- 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
+```
+
+**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
+
+---
+
 ## Quick Comparison
 
 | Aspect     | Bad                  | Good                        |
@@ -159,4 +199,5 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 | State      | Every occurrence     | Persistence points only     |
 | Flows      | Prose paragraphs     | ASCII diagrams              |
 | Changelogs | "Updated X"          | Function names + migrations |
+| Decisions  | New doc per revision | One AD per subject, updated in place |
 | Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -220,26 +220,31 @@ Use for structured info:
 
 ---
 
-## Tense & History
+## The Two Natures — Tense & History
 
-**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans). Two sanctioned exceptions: `docs/memory/` is the agent's own dated log, and an ADR's **Decision Changelog** section carries that decision's dated revision history (the rest of the ADR body stays current-truth-only).
+Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
 
-Strip this language from active docs:
+**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Two sanctioned exceptions: `docs/memory/` is the agent's own dated ledger, and an AD's **Decision Changelog** tail carries that decision's dated revision history (the AD body stays current-truth-only — head is truth, tail is provenance).
 
-| ❌ Historical narration (belongs in `docs/history/`) | ✅ Present-tense fact (belongs in the active doc) |
+**Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
+
+Strip this language from truth documents:
+
+| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
 | --- | --- |
 | "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
 | "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
 | "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
 | "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
-| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-SOT>.md`" |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
 
 Rules:
 
-- **No dates in active docs** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
-- **Cite the ADR for the _why_, never the _when_.** `Provenance: ADR-002` is good (it points to the decision rationale). "Decided in ADR-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to current authority docs.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current SOT doc, or drop the row.
-- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the active doc simply becomes correct in present tense.** Never leave the diff narrated in place.
+- **No dates in truth documents** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
+- **Routing/index docs point only to truth documents.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row.
+- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
+- **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
 
 ---