@nurix/etna 0.20.15 → 0.20.16

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "4dd6abe08c97",
+    "fingerprint": "6b7b8d3d3e8f",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -172,8 +172,14 @@ Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise;
 
 ## File Structure
 
-- Add a file-path header comment at the top of each source file, in the file's native comment syntax — `// src/modules/example.js - Module for handling user authentication`. Place it below any shebang line; skip formats with no comment syntax (JSON, lockfiles) and generated files.
-- Add a 1-line description above each function whose purpose isn't fully evident from its name and signature: `// Extract JWT token from request based on endpoint type`. No commented-out code — refactor for clarity instead.
+A file's documentation lives in `docs/`. Its comments carry only what a reader needs with the code in front of them, and the budget is deliberately small — a comment is the one artifact nothing audits, so it is where stale claims accumulate.
+
+- Add a file-path header comment at the top of each source file, in the file's native comment syntax — `// src/modules/example.js - Module for handling user authentication`. Place it below any shebang line; skip formats with no comment syntax (JSON, lockfiles) and generated files. **The path is repo-relative and names the file's own path**: a header a move left behind is worse than no header, because it reads as current.
+- **Two or three present-tense sentences, six lines at the ceiling** — what the file is, the invariant a reader must not break, and where the fuller account lives, as a `docs/…` path.
+- Add a 1-line description above each function whose purpose isn't fully evident from its name and signature: `// Extract JWT token from request based on endpoint type`. **One sentence, third-person indicative** — `Installs the package`, never `Install the package` — and a second sentence only to carry a named invariant. A field, type member, or constant earns a sentence only where its name and type do not already say it; a member of an enum or a constant map earns none. No commented-out code — refactor for clarity instead.
+- **Design rationale, alternatives weighed, history, ticket and decision-record references, and dated notes are not comments.** They belong to the owning feature doc, and moving the claim there is part of the same change — cutting one out of a comment without landing it is a deletion, not a cleanup (the `documentation` skill § Where a file's documentation lives).
+- **The ceiling is on what a change adds, not on what it inherits: under a quarter of the lines a change adds are comments.** The measured regression that set this number ran at 28% on new files while the tree it joined sat at 14%, so a whole-file average is the wrong instrument — it grades the density somebody else wrote and passes the prose being added right now. `.claude/skills/documentation/scripts/source-lint.mjs --changed` reports it and the detector raises one row per offending file; a comments-only sweep proves itself with `comment-strip.mjs`, which strips both revisions and diffs what is left, so a code change hiding inside a cleanup cannot pass as one.
+- **The one comment that earns a paragraph is a booby trap** — an edit that looks obviously safe and is not. It names the version or the measurement that makes it true and the condition under which it stops being true, so the next reader can retire it instead of trusting it. Everything else that wants a paragraph wants a doc.
 
 ---
 

package/data/harnesses/code/agents/bookkeeper.md

@@ -19,6 +19,7 @@ Ground every edit in this ladder, in order. Never invent content; a fact you can
     | --- | --- |
     | `dead-glob` | read the owning doc, find where the files went (`git log --follow`, glob search), update its `owns:` frontmatter |
     | `header-missing` | add the file-path header comment in the file's native comment syntax |
+    | `source-lint` | run `.claude/skills/documentation/scripts/source-lint.mjs <file>` and clear its BLOCK findings: a stale or absent header path is rewritten to the file's own repo-relative path, and `comment-ratio-added` — over a quarter of the lines the change added are comments — is cleared by moving the rationale into the owning doc and leaving one sentence per symbol. Never clear either with a `source-lint-disable`: the one comment that earns its length is a booby trap, and that one takes the disable with its reason beside it. The file-level `comment-ratio` warning is **not** yours — it grades density somebody else wrote, and rewriting an inherited file is a unit of work with an owner, not a queue drain |
     | `doc-lint` | fix the finding, or add `<!-- doc-lint-disable: id -->` with a reason beside it when the flagged text is deliberate |
     | `index-row-missing` | add the doc's row to `docs/README.md` |
     | `doc-implicated` | read the diff of the named source file (`git diff` / `git log -p`), and update the owning doc **only where the diff contradicts documented behavior**; if nothing documented changed, the row's resolution is deleting it |

package/data/harnesses/code/agents/polygraph-finder.md

@@ -17,6 +17,10 @@ Docs state the target design; code is presumed correct unless a standing decisio
 2. Read the document once, whole — it is the one file you always read in full. Then check each claim it makes against the code: grep for the mechanism, open the passage with a line range, cite `file:line`.
 3. Write one row per claim to the partial file, **no header**, exactly ten pipe-separated fields: `id|subject|claim|evidence|counter_evidence|verdict|confidence|depends_on|status|resolution`. A literal `|` becomes `¦`, a newline `; `. Verdicts: `COHERENT` (emit at the unit you audited, so coverage is countable) · `MISDESCRIBED` · `UNDOCUMENTED` · `UNBUILT` · `RESIDUE` · `CONTESTED` · `QUESTION`. `id` is `{doc-stem}-NNN`; `status` is `open`; `resolution` is empty; `confidence` is an honest 0–1.
 4. Sweep the other direction once: code inside the `owns:` globs that no claim in the document covers is an `UNDOCUMENTED` row — after the precedent test.
+5. Sweep the comments inside the `owns:` globs once, against the shape in the repo's `CLAUDE.md` § File Structure — the authority, never restated by you. A comment is not a claim about the code, it is a claim *in* the code, and it is the one artifact nothing else audits. Two things come out of this sweep, and a claim worth keeping produces **both**:
+   - **The claim, as an `UNDOCUMENTED` row against the document** — design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking edit is wrong. The applier folds it into the doc, which is what makes cutting the comment safe later. Cite the comment's `file:line` as evidence and state the claim in the document's voice, not the comment's.
+   - **The comment itself, as a code-side row** naming the file and the lines — `MISDESCRIBED` where it states something the code does not do, `RESIDUE` where it is history, a ticket or decision-record reference, a dated note, a divider, a per-field block, or a restatement of what the doc now carries. Code-side rows leave as register rows; **you never edit a comment**, whatever the row says.
+   Shape breaches are one `RESIDUE` row per file, counted rather than enumerated: no path header, a header naming a path other than its own, a header past three sentences, a function comment past two. **The exception you must not report is the booby trap** — a comment whose subject is a danger on an edit that looks safe, naming the version, measurement, or condition that makes it true. It earns its length where it sits.
 
 Rules that bind every row:
 

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.16.3",
+  "version": "3.16.4",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -25,5 +25,5 @@
     }
   ],
   "docsRoot": "docs",
-  "digest": "7a8f67e4b74f"
+  "digest": "5e98d9973eb1"
 }

package/data/harnesses/code/hooks/awareness.mjs

@@ -35,7 +35,7 @@ import {
   readDecision,
 } from "./lib/state.mjs";
 import { readSafe, relIfInside, today, SOURCE_EXT, commandRoot, docsRoot } from "./lib/repo.mjs";
-import { sweepResolvedRows, docLint, hasHeaderComment } from "./lib/sweep.mjs";
+import { sweepResolvedRows, docLint, sourceLint, hasHeaderComment } from "./lib/sweep.mjs";
 import { listPlans, polygraphVerdict } from "./lib/plans.mjs";
 import { frozenStatusAtHead } from "./lib/frozen.mjs";
 import { undischargedDocRows } from "./lib/ledger.mjs";
@@ -369,7 +369,20 @@ function detectorForFile(projectDir, rel, meta, rows) {
           ...meta,
           kind: "header-missing",
           description: `${rel} lacks its file-path header comment`,
-          action: "add the header comment",
+          action: "add the header comment naming this file's own repo-relative path",
+        })
+      );
+    }
+    // The blocking rest of the source-comment convention as one row per file — in practice the added-line
+    // comment ratio, since every other non-header rule only warns. Header findings are excluded because
+    // `header-missing` above already carries them, and two rows for one defect are drained twice.
+    if (sourceLint(projectDir, rel).some((line) => !/header-missing|header-path-stale/.test(line))) {
+      rows.push(
+        formatAutoRow({
+          ...meta,
+          kind: "source-lint",
+          description: `${rel} violates the source-comment convention`,
+          action: "run .claude/skills/documentation/scripts/source-lint.mjs on it and clear the blocking findings, or source-lint-disable an id with its reason",
         })
       );
     }

package/data/harnesses/code/hooks/lib/state.mjs

@@ -180,6 +180,7 @@ const ROW_PATH_RULES = [
   /·\s*doc-implicated\s*·\s*(\S+)\s+changed;\s+owning doc\s+(\S+?)\s+may need/,
   /·\s*doc-lint\s*·\s*(\S+)\s+has\s/,
   /·\s*header-missing\s*·\s*(\S+)\s+lacks\s/,
+  /·\s*source-lint\s*·\s*(\S+)\s+violates\s/,
   /·\s*index-row-missing\s*·\s*(\S+)\s+is not linked from\s+(\S+)/,
   /·\s*package-rejected\s*·\s*(\S+)\s+declares\s/,
   /·\s*frozen-record-edited\s*·\s*(\S+)\s+is a frozen record/,

package/data/harnesses/code/hooks/lib/sweep.mjs

@@ -33,10 +33,19 @@ export function docLint(projectDir, rel) {
   return out.split("\n").filter((line) => /:\d+ \[(block|warn)\]/.test(line));
 }
 
-// True when a source file's first lines carry its repo-relative path (the header-comment rule).
+// True when the first path-shaped token in a source file's opening lines IS its repo-relative path.
 export function hasHeaderComment(projectDir, rel) {
   const head = readSafe(path.join(projectDir, rel)).split("\n").slice(0, 5).join("\n");
-  return head.includes(rel) || head.includes(path.basename(rel));
+  const m = /([\w.@-]+(?:\/[\w.@-]+)*\.[A-Za-z]{1,5})\b/.exec(head);
+  return m ? m[1] === rel : false;
+}
+
+// The installed source-lint's block-severity lines for one file, so warnings advise and blocking rules wall.
+export function sourceLint(projectDir, rel) {
+  const script = path.join(projectDir, ".claude", "skills", "documentation", "scripts", "source-lint.mjs");
+  if (!fs.existsSync(script)) return [];
+  const res = spawnSync("node", [script, rel], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  return `${res.stdout || ""}`.split("\n").filter((line) => /:\d+ \[block\]/.test(line));
 }
 
 // Verifier keys the detector no longer emits — swept when machine-raised, never taught to authors.
@@ -52,6 +61,15 @@ export const ROW_VERIFIERS = {
     return hasHeaderComment(projectDir, rel);
   },
 
+  // "<rel> violates the source-comment convention" — dead once source-lint reports no blocking finding.
+  "source-lint": (projectDir, body) => {
+    const m = /·\s+source-lint\s+·\s+(\S+)\s+violates/.exec(body);
+    if (!m) return false;
+    const rel = m[1];
+    if (!fs.existsSync(path.join(projectDir, rel))) return true;
+    return sourceLint(projectDir, rel).length === 0;
+  },
+
   // "owns: glob `<glob>` in <doc> matches no files" — dead once the glob matches something again.
   "dead-glob": (projectDir, body, ctx) => {
     const m = /`([^`]+)`/.exec(body);

package/data/harnesses/code/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/code/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/code/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)) {