@nurix/etna 0.20.15 → 0.20.16

package/data/harnesses/delivery/skills/documentation/templates/behavioral-checklist.md

@@ -35,7 +35,7 @@ Required: **Conventions**, at least one numbered behavior section, **Failure Rep
 - **State each section's trace.** `Pinned:` names the suite test that now guards it, or says `driven only` **with the reason** — an unmarked section is indistinguishable from an unexamined one.
 - **State each section's `AC:` keys.** Where the repo carries a keyed acceptance-criteria source, each section names the keys it proves, so the chain from criterion to checklist to suite test survives the last hop; the gate reports coverage and backlogs uncovered keys. `none — not AC-mapped` is the honest line where no keyed source exists.
 - **A known-failing assertion stays written as the contract.** A checklist states what the feature promises; the *run* records the failure and the backlog carries the defect. Never soften an assertion to make a run go green.
-- **Each driven section carries a dated `Driven` line** — `Driven {YYYY-MM-DD} · PASS|FAIL ({environment}).` plus the evidence the assertion turned on. It is the only thing separating a promise someone verified from a promise someone typed, and its date is what makes staleness visible: a section still carrying last quarter's date next to a surface rewritten since is the file telling you it was not re-driven. `FAIL` is stamped and kept, with the backlog item it raised; a section blocked rather than driven says `NOT DRIVEN — {what blocked it}`.
+- **No section carries a date.** This file is a truth document: it states what must be true and what guards it, and the *event* of driving — the date, the environment, the evidence the assertion turned on, a `FAIL` and the backlog item it raised — is recorded in the changelog entry of the unit that drove it, where a dated line belongs. What separates a promise somebody verified from a promise somebody typed is the `Pinned:` trace, and it is stronger than a stamp because it re-checks itself on every suite run. A section a drive could not reach says `not reachable — {what blocks it}` on its trace line, in the present tense, and keeps saying it until the blocker is gone.
 - **The file is maintained by whoever drives it.** Nothing else watches it — a checklist owns no code, so no ownership glob implicates it and no hook fires when the surface underneath it changes. Retiring dead sections and repairing traces is part of running the gate, not a separate cleanup someone schedules.
 
 ```
@@ -63,7 +63,6 @@ Each step is an action; each **Assert** is the observable it must produce.
 - [ ] **Assert**: {the observable, with exact literals}
 - [ ] **Assert**: {the persistence claim, where the behavior writes something}
 
-> Driven {YYYY-MM-DD} · PASS ({environment}). {the evidence — the literal observed, the row that moved}
 > Pinned: `{tests/path/to/file.test.ts}` — or `driven only — {why no durable test is bought}` — or `none yet — {the test this section owes}`
 > AC: {the acceptance-criteria keys this section proves} — or `none — not AC-mapped`
 

package/data/harnesses/delivery/skills/documentation/templates/bookkeeping.md

@@ -21,4 +21,4 @@ The shared work queue keeping documentation and code in sync — a queue, never
 
 **A waiver covers a finding only when it names the finding's kind and its subject in backticks** — the matcher (`waiverCovers`) tests the backticked subject exactly, so a waiver written without them silences nothing and the wall stands. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `dead-glob` waivers double as the dead-glob allowlist; `ownership-overlap` waivers cover the CI ownership check the same way.
 
-Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `package-rejected` · `frozen-record-edited`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.
+Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.

package/data/harnesses/etna/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.20",
+  "version": "1.5.21",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "4c5fe7575b80"
+  "digest": "a3f92ccefc2e"
 }

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

@@ -11,6 +11,26 @@ Document contracts and architecture, not implementation details. Show function s
 
 ---
 
+## Where a file's documentation lives
+
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+
+**Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
+
+| The claim is | What it earns |
+| --- | --- |
+| Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
+| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
+| History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
+
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+
+**The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
+
+**Never convert a booby trap into a one-liner.** A comment whose subject is a danger on an edge that looks safe — a pinned dependency's limitation, a measurement that justifies a narrow allowlist, a two-clock interaction — is load-bearing where it sits, because the reader who needs it is mid-edit and will not go looking. Compress it if it rambles; do not relocate it. The tell is that the comment names a version, a measurement, or a condition under which it expires.
+
+---
+
 ## Present tense, always
 
 **A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
@@ -24,6 +44,12 @@ Document contracts and architecture, not implementation details. Show function s
 
 The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
 
+**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The four exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, `docs/structure.md`'s **Health Log** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present.
+
+**Cite a record by what it is, never by when it was.** `the dev reset runbook` links to the file; "the 2026-09-13 reset" states a date the reader must now keep in their head and that goes stale as soon as a second reset happens. The link carries the date in its path, where it belongs, and the prose stays true forever.
+
+**A verification stamp is a record, not a status line.** "Driven 2026-09-13 · PASS" in a behavioural checklist is the clearest instance of this defect: it reads as documentation and is actually a dated event. The section states what must be true and which suite test guards it; *that* somebody drove it on a Tuesday belongs to the changelog entry of the unit that drove it, and staleness is then visible from something that re-checks itself — a pin that runs in CI — rather than from a date nobody re-stamped. A section with no automated guard says so in its trace, which is a stronger signal than an old date, because it cannot silently become wrong.
+
 The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch. Two invocation traps: the disable comment takes **bare rule ids only** — prose inside the comment silently breaks the parse, so put the reason in a second comment beside it — and the script grades truth-vs-record scope by matching `docs/(history|research|memory)/` against **the path string it is given**, so always hand it a repo-root-relative path; linting a record from inside its own folder grades it as a truth document.
 
 ---
@@ -155,3 +181,5 @@ update, and the `maintenance` agent's baseline pass, route there.
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |
 | `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |
+| `scripts/source-lint.mjs` | Mechanical checks over source **comments** (header path identity, the added-line comment ratio, narration, shouting) — run `--changed` before finishing any change that writes source |
+| `scripts/comment-strip.mjs` | The proof a comment sweep changed no executable code: strips comments from two revisions and diffs what is left. Exit 0 is the claim; exit 1 names the file and the first diverging line |

package/data/harnesses/etna/skills/documentation/scripts/comment-strip.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// skills/documentation/scripts/comment-strip.mjs - Proves a comment sweep changed no executable code.
+// Strips comments from a git revision of each file and from the working copy, then compares the two
+// stripped forms; a difference is a code change hiding inside a comments-only pass. String and
+// template literals, character literals, regex literals, and raw strings are honoured, so a `//`
+// inside a string is code and stays.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { readdirSync } from "node:fs";
+import { join, extname } from "node:path";
+
+// Comment syntax per extension. `block` is null where the language has none.
+const DIALECTS = {
+    ".ts": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".tsx": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".mts": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".js": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".jsx": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".mjs": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".cjs": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".css": { line: null, block: ["/*", "*/"], strings: `'"`, regex: false , sameLineQuotes: true },
+    ".rs": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false, rustRaw: true , sameLineQuotes: true },
+    ".go": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: false , sameLineQuotes: true },
+    ".java": { line: "//", block: ["/*", "*/"], strings: `'"`, regex: false , sameLineQuotes: true },
+    ".swift": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false , sameLineQuotes: true },
+    ".kt": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false , sameLineQuotes: true },
+    ".sql": { line: "--", block: ["/*", "*/"], strings: `'"`, regex: false },
+    ".py": { line: "#", block: null, strings: `'"`, regex: false },
+    ".sh": { line: "#", block: null, strings: `'"`, regex: false },
+    ".zsh": { line: "#", block: null, strings: `'"`, regex: false },
+    ".yml": { line: "#", block: null, strings: `'"`, regex: false },
+    ".yaml": { line: "#", block: null, strings: `'"`, regex: false },
+    ".toml": { line: "#", block: null, strings: `'"`, regex: false },
+};
+
+// Whether a `/` at this position opens a regex literal rather than dividing — decided by the last
+// significant character, the same way a JavaScript tokenizer decides it.
+function regexCanStart(prev) {
+    if (prev === "") return true;
+    return !/[\w$)\]]/.test(prev);
+}
+
+// The index just past a template literal starting at `i`, following `${…}` interpolations and the
+// templates and quotes nested inside them. A scan that stops at the first backtick it meets closes the
+// OUTER template on an INNER one — `${x ? `<b>${y}</b>` : ""}` — and every quote and comment downstream
+// is then read in the wrong context, which reports a whole file as changed code.
+function templateEnd(source, i) {
+    const n = source.length;
+    let j = i + 1;
+    while (j < n) {
+        const c = source[j];
+        if (c === "\\") {
+            j += 2;
+            continue;
+        }
+        if (c === "`") return j + 1;
+        if (c === "$" && source[j + 1] === "{") {
+            let depth = 1;
+            j += 2;
+            while (j < n && depth > 0) {
+                const d = source[j];
+                if (d === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (d === "`") {
+                    j = templateEnd(source, j);
+                    continue;
+                }
+                if (d === "'" || d === '"') {
+                    const quote = d;
+                    j++;
+                    while (j < n && source[j] !== quote && source[j] !== "\n") {
+                        if (source[j] === "\\") j++;
+                        j++;
+                    }
+                    j++;
+                    continue;
+                }
+                if (d === "{") depth++;
+                else if (d === "}") depth--;
+                j++;
+            }
+            continue;
+        }
+        j++;
+    }
+    return n;
+}
+
+// Remove every comment from `source`, preserving all other bytes including newlines.
+export function stripComments(source, dialect) {
+    const { line, block, strings, regex, rustRaw } = dialect;
+    const out = [];
+    let i = 0;
+    let lastSignificant = "";
+    const n = source.length;
+    while (i < n) {
+        const ch = source[i];
+        const two = source.slice(i, i + 2);
+
+        if (rustRaw && ch === "r" && (source[i + 1] === "#" || source[i + 1] === '"')) {
+            let j = i + 1;
+            let hashes = 0;
+            while (source[j] === "#") {
+                hashes++;
+                j++;
+            }
+            if (source[j] === '"') {
+                const close = '"' + "#".repeat(hashes);
+                const end = source.indexOf(close, j + 1);
+                const stop = end === -1 ? n : end + close.length;
+                out.push(source.slice(i, stop));
+                lastSignificant = '"';
+                i = stop;
+                continue;
+            }
+        }
+
+        if (line && two.slice(0, line.length) === line) {
+            const nl = source.indexOf("\n", i);
+            i = nl === -1 ? n : nl;
+            continue;
+        }
+
+        if (block && two === block[0]) {
+            const end = source.indexOf(block[1], i + 2);
+            const stop = end === -1 ? n : end + block[1].length;
+            // A JSX expression container holding only a comment — `{/* … */}` — is comment syntax
+            // whole: the braces exist to carry it, so they leave with it. Left behind, a multi-line
+            // container collapses to `{}` and reads as a code change.
+            let after = stop;
+            while (after < n && /\s/.test(source[after])) after++;
+            let brace = out.length - 1;
+            while (brace >= 0 && out[brace].trim() === "") brace--;
+            if (regex && source[after] === "}" && brace >= 0 && out[brace] === "{") {
+                out.splice(brace, 1);
+                for (const c of source.slice(i, after + 1)) if (c === "\n") out.push("\n");
+                i = after + 1;
+                continue;
+            }
+            for (const c of source.slice(i, stop)) if (c === "\n") out.push("\n");
+            i = stop;
+            continue;
+        }
+
+        if (ch === "`" && regex) {
+            const stop = templateEnd(source, i);
+            out.push(source.slice(i, stop));
+            lastSignificant = "`";
+            i = stop;
+            continue;
+        }
+
+        if (strings.includes(ch)) {
+            // A quote opens a literal only where one can actually close. In the C family and in Rust a
+            // `'` or `"` literal may not contain a raw newline, so requiring the partner on the same
+            // line is not a heuristic — it is the grammar, and it is what keeps an apostrophe in JSX
+            // text (`Couldn't load`) and a Rust char literal holding a quote (`trim_matches('"')`) from
+            // opening a string that swallows the rest of the file. Backticks span lines by design.
+            if (ch !== "`" && dialect.sameLineQuotes) {
+                let j = i + 1;
+                let closed = false;
+                while (j < n && source[j] !== "\n") {
+                    if (source[j] === "\\") {
+                        j += 2;
+                        continue;
+                    }
+                    if (source[j] === ch) {
+                        closed = true;
+                        break;
+                    }
+                    j++;
+                }
+                if (!closed) {
+                    out.push(ch);
+                    lastSignificant = ch;
+                    i++;
+                    continue;
+                }
+                out.push(source.slice(i, j + 1));
+                lastSignificant = ch;
+                i = j + 1;
+                continue;
+            }
+            out.push(ch);
+            i++;
+            while (i < n) {
+                if (source[i] === "\\") {
+                    out.push(source.slice(i, i + 2));
+                    i += 2;
+                    continue;
+                }
+                out.push(source[i]);
+                if (source[i] === ch) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            lastSignificant = ch;
+            continue;
+        }
+
+        if (regex && ch === "/" && regexCanStart(lastSignificant)) {
+            let j = i + 1;
+            let inClass = false;
+            let closed = false;
+            while (j < n) {
+                const c = source[j];
+                if (c === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (c === "\n") break;
+                if (c === "[") inClass = true;
+                else if (c === "]") inClass = false;
+                else if (c === "/" && !inClass) {
+                    closed = true;
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            if (closed) {
+                out.push(source.slice(i, j));
+                lastSignificant = "/";
+                i = j;
+                continue;
+            }
+        }
+
+        out.push(ch);
+        if (!/\s/.test(ch)) lastSignificant = ch;
+        i++;
+    }
+    // Collapse whitespace so a re-indent left behind by a removed block comment is not a finding.
+    return out
+        .join("")
+        .split("\n")
+        .map((l) => l.replace(/\s+/g, " ").trim())
+        .filter((l) => l !== "")
+        .join("\n");
+}
+
+// Comment-only lines in a source: the non-blank lines it has, less the lines that survive stripping.
+// Both sides exclude blanks, so the difference is comments alone; a trailing comment on a code line is
+// correctly not counted, because the line itself survives.
+function countCommentLines(source, dialect) {
+    const nonBlank = source.split("\n").filter((l) => l.trim() !== "").length;
+    const stripped = stripComments(source, dialect);
+    return nonBlank - (stripped === "" ? 0 : stripped.split("\n").length);
+}
+
+function gitShow(rev, path) {
+    try {
+        return execFileSync("git", ["show", `${rev}:${path}`], { encoding: "utf8", maxBuffer: 1 << 28 });
+    } catch {
+        return null;
+    }
+}
+
+function walk(dir, acc = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) walk(full, acc);
+        else if (DIALECTS[extname(entry.name)]) acc.push(full);
+    }
+    return acc;
+}
+
+function main(argv) {
+    let rev = "HEAD";
+    // With `--to`, both sides come from git and the working tree is not read — the mode that
+    // audits a sweep somebody already committed.
+    let to = null;
+    const paths = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--rev") rev = argv[++i];
+        else if (argv[i] === "--to") to = argv[++i];
+        else if (argv[i] === "--changed") {
+            const out = execFileSync("git", ["diff", "--name-only", rev], { encoding: "utf8" });
+            paths.push(...out.split("\n").filter(Boolean));
+        } else paths.push(argv[i]);
+    }
+    if (paths.length === 0) {
+        const out = execFileSync("git", ["diff", "--name-only", rev], { encoding: "utf8" });
+        paths.push(...out.split("\n").filter(Boolean));
+    }
+
+    const files = [];
+    for (const p of paths) {
+        // A revision-to-revision run names paths that need not exist in the checkout.
+        if (to !== null) {
+            if (DIALECTS[extname(p)]) files.push(p);
+            continue;
+        }
+        if (!existsSync(p)) continue;
+        if (statSync(p).isDirectory()) files.push(...walk(p));
+        else if (DIALECTS[extname(p)]) files.push(p);
+    }
+
+    let changed = 0;
+    let checked = 0;
+    let commentDelta = 0;
+    for (const file of [...new Set(files)]) {
+        const dialect = DIALECTS[extname(file)];
+        const before = gitShow(rev, file);
+        if (before === null) continue;
+        const after = to === null ? readFileSync(file, "utf8") : gitShow(to, file);
+        if (after === null) continue;
+        const a = stripComments(before, dialect);
+        const b = stripComments(after, dialect);
+        checked++;
+        // Count comment lines directly. Differencing raw length against stripped length would fold in the
+        // blank lines the strip also drops, and report a comment+blank delta under a comment label.
+        const cb = countCommentLines(before, dialect);
+        const ca = countCommentLines(after, dialect);
+        commentDelta += ca - cb;
+        if (a !== b) {
+            changed++;
+            const al = a.split("\n");
+            const bl = b.split("\n");
+            let k = 0;
+            while (k < al.length && k < bl.length && al[k] === bl[k]) k++;
+            console.log(`CODE CHANGED  ${file}`);
+            console.log(`  ${rev}: ${al[k] === undefined ? "(end of file)" : al[k].slice(0, 120)}`);
+            console.log(`  now:  ${bl[k] === undefined ? "(end of file)" : bl[k].slice(0, 120)}`);
+        }
+    }
+
+    const verdict = changed === 0 ? "no executable code changed" : `${changed} file(s) changed code`;
+    console.log(`\n${checked} file(s) compared against ${rev} — ${verdict}; comment lines ${commentDelta >= 0 ? "+" : ""}${commentDelta}.`);
+    process.exit(changed === 0 ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -17,19 +17,35 @@ const RULES = [
   { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
   // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`/g, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
+  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and structure.md\'s Health Log tail' },
 ];
 
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
-// Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
-const RECORD = /(^|\/)docs\/(history|research|memory)\//;
+// Instruction files and generated trees are out of scope; the authoring roots are anchored to the repo root.
+const SKIP = /^(\.claude|skills|rules|agents|harness)\/|(^|\/)(node_modules|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
+// `operations/issues/YYYY-MM-DD-{slug}.md` is a sanctioned record genre (`type: issue`, the
+// `issue-bridge` skill's local pack) living outside the record folders, so it is named here too —
+// graded as a truth document it fails the date rule for carrying the date its filename already does.
+const RECORD = /(^|\/)docs\/(history|research|memory)\/|(^|\/)docs\/operations\/issues\//;
 
-// Classify a path: skipped genre, record, or truth.
-function scopeOf(path) {
+const RECORD_TYPES = /^(changelog-entry|plan|migration|migration-runbook|research|brainstorm|journal|record|ledger|issue|triage|project-memory|agent-memory)$/;
+const TRUTH_LOCATIONS = /(^|\/)docs\/(features|architecture|tests|acceptance)\//;
+
+// The genre a document declares for itself, from its own frontmatter `type:` key, or null.
+function declaredType(text) {
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  const m = /^type:\s*(\S+)\s*$/m.exec(end === -1 ? text : text.slice(0, end));
+  return m ? m[1] : null;
+}
+
+// Classify a document: record or truth, the declared genre outranking the path.
+function scopeOf(path, text) {
   if (SKIP.test(path)) return 'skip';
-  return RECORD.test(path) ? 'record' : 'truth';
+  if (RECORD.test(path)) return 'record';
+  const declared = text === undefined ? null : declaredType(text);
+  return declared && RECORD_TYPES.test(declared) ? 'record' : 'truth';
 }
 
 // Yield prose lines only: frontmatter, fenced code blocks, and bridge sections drop out.
@@ -37,13 +53,21 @@ function proseLines(text) {
   const lines = text.split('\n');
   const out = [];
   let inFence = false;
+  let fenceMarker = '';
   let inFrontmatter = lines[0] === '---';
   let inBridge = false;
   let bridgeLevel = 0;
   for (let i = inFrontmatter ? 1 : 0; i < lines.length; i++) {
     const line = lines[i];
     if (inFrontmatter) { if (line === '---') inFrontmatter = false; continue; }
-    if (/^\s*(```|~~~|````)/.test(line)) { inFence = !inFence; continue; }
+    // A fence closes only on a marker at least as long as the one that opened it, so a nested ```yaml
+    // inside a ```markdown block does not invert the state and expose the outer block as prose.
+    const fence = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      if (!inFence) { inFence = true; fenceMarker = fence[1]; }
+      else if (fence[1][0] === fenceMarker[0] && fence[1].length >= fenceMarker.length) inFence = false;
+      continue;
+    }
     if (inFence) continue;
     const heading = line.match(/^(#{1,4})\s/);
     if (heading) {
@@ -64,9 +88,9 @@ function fileDisables(text) {
 }
 
 function lintFile(path, findings) {
-  const scope = scopeOf(path);
-  if (scope === 'skip' || !existsSync(path)) return;
+  if (SKIP.test(path) || !existsSync(path)) return;
   const text = readFileSync(path, 'utf8');
+  const scope = scopeOf(path, text);
   const disabled = fileDisables(text);
   const lines = proseLines(text);
 
@@ -85,6 +109,13 @@ function lintFile(path, findings) {
     }
   }
 
+  // A record genre declared in a settled truth location is a contradiction, not a classification.
+  if (TRUTH_LOCATIONS.test(path)) {
+    const declared = declaredType(text);
+    if (declared && RECORD_TYPES.test(declared) && !disabled.has('record-type-in-truth-location'))
+      findings.push({ path, n: 1, severity: 'block', id: 'record-type-in-truth-location', message: `\`type: ${declared}\` is a record genre declared in a truth location — move the file to \`docs/history/\` if it is a record, or give it its location's genre` });
+  }
+
   // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {