@nurix/etna 0.20.14 → 0.20.16

package/data/harnesses/delivery/skills/documentation/scripts/source-lint.mjs

@@ -0,0 +1,225 @@
+// skills/documentation/scripts/source-lint.mjs - mechanical checks over source comments (header path, density, tense, shouting)
+// Usage: node source-lint.mjs <file | dir ...> | node source-lint.mjs --changed   (git-changed + untracked source files)
+// Exit 1 when any block-severity finding survives. Escape hatch: a `source-lint-disable: id[, id]` comment,
+// file-wide in the first 20 lines or on the offending line; the reason goes in a second comment beside it.
+//
+// The convention is the harness `CLAUDE.md` § File Structure and is not restated here: a repo-relative path
+// header of two or three present-tense sentences, one third-person sentence above each non-obvious function,
+// rationale in the owning doc. This script checks only what is mechanical; voice and placement stay judgement.
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { execSync, spawnSync } from 'node:child_process';
+import { basename, extname } from 'node:path';
+
+// Comment syntax per extension, and whether a leading `#!` shebang may precede the header.
+const DIALECTS = {
+  '.ts': '//', '.tsx': '//', '.mts': '//', '.cts': '//',
+  '.js': '//', '.jsx': '//', '.mjs': '//', '.cjs': '//',
+  '.rs': '//', '.go': '//', '.java': '//', '.kt': '//', '.swift': '//', '.c': '//', '.h': '//', '.cpp': '//',
+  '.css': '/*', '.scss': '//',
+  '.sql': '--',
+  '.py': '#', '.sh': '#', '.zsh': '#', '.bash': '#', '.rb': '#',
+};
+
+// Generated trees, vendored copies, and formats with no comment syntax are a different genre. `.claude/`
+// is harness-owned in every consumer — its files are overwritten on the next roll, so a finding there
+// names work nobody in that repo can land. The forge lints its own copies at `harness/`, not here.
+const SKIP = /(^|\/)(node_modules|dist|build|target|\.git|\.claude|coverage|__screenshots__|data\/harnesses)\/|\.min\.|\.d\.ts$|(^|\/)(pnpm-lock|package-lock)\./;
+// A generated file says so in its own first lines; the convention exempts it.
+const GENERATED = /@generated|DO NOT EDIT|AUTO-GENERATED|This file was generated/i;
+// Below this a file is too small for a density ratio to mean anything.
+const RATIO_MIN_LINES = 40;
+// A file-level ceiling, not a target. The house style sits near 14%; a file past this is carrying prose.
+// It grades INHERITED density, so it only warns: a file somebody else wrote at 42% is not this session's
+// debt, and a wall that blocks on it stops every commit in the repo until a rewrite pass lands.
+const RATIO_CEILING = 0.35;
+// The ceiling that actually holds the line, because it grades only the lines THIS change adds. The measured
+// regression that prompted the rule ran at 28% on new files while the tree sat at 14% — a file-level 35%
+// ceiling passes that cleanly, so the file-level rule cannot be what stops it. You own what you add.
+const ADDED_RATIO_CEILING = 0.25;
+// Below this an added-line ratio is noise — a two-line fix with one comment is not a prose problem.
+const ADDED_MIN_LINES = 20;
+// The header's own ceiling in wrapped lines, from the measured p99 of the convention's own sweep.
+const HEADER_MAX_LINES = 6;
+// A comment block longer than this is a document living in a source file.
+const BLOCK_MAX_LINES = 12;
+
+const RULES = {
+  'header-missing': { severity: 'block', message: 'no file-path header comment — add one naming this file\'s repo-relative path' },
+  'header-path-stale': { severity: 'block', message: 'the header names another path — a header a move left behind reads as current' },
+  'header-too-long': { severity: 'warn', message: `header past ${HEADER_MAX_LINES} lines — two or three sentences, and the fuller account goes in its doc` },
+  'comment-ratio': { severity: 'warn', message: `comment lines over ${Math.round(RATIO_CEILING * 100)}% of the file — the rationale belongs in the owning doc` },
+  'comment-ratio-added': { severity: 'block', message: `over ${Math.round(ADDED_RATIO_CEILING * 100)}% of the lines this change adds are comments — one sentence per symbol, and the rationale goes in the owning doc` },
+  'comment-block-long': { severity: 'warn', message: `a comment block past ${BLOCK_MAX_LINES} lines — one sentence per symbol; a paragraph is a doc, unless it names a booby trap` },
+  'comment-narration': { severity: 'warn', message: 'history, a ticket or decision-record reference, or a dated note in a comment — the journey belongs in a record' },
+  'comment-shouting': { severity: 'warn', message: 'an ALL-CAPS clause opener — comments are third-person present tense, not emphasis' },
+};
+
+const NARRATION = /\bused to\b|\bno longer\b|\bpreviously\b(?!-)|\bwas (renamed|removed|extracted|folded|migrated|replaced|ported)\b|\bported from\b|\bfor now\b|\bnot yet implemented\b|\b(AD|ADR)-\d+\b|\b20\d{2}-\d{2}-\d{2}\b/i;
+const SHOUTING = /(?:^|[.:;]\s+)([A-Z][A-Z0-9 ,'`\-]{14,})(?=[.,:]|\s+[a-z])/;
+
+// The comment token for a path, or null when the format has none.
+function tokenFor(path) {
+  return DIALECTS[extname(path)] ?? null;
+}
+
+// True when the line is a comment line in this dialect (an open block, a continuation, or a line comment).
+function isCommentLine(line, token) {
+  const t = line.trim();
+  if (t === '') return false;
+  if (token === '//') return t.startsWith('//') || t.startsWith('/*') || t.startsWith('*') || t.startsWith('*/');
+  if (token === '/*') return t.startsWith('/*') || t.startsWith('*') || t.startsWith('*/');
+  if (token === '--') return t.startsWith('--') || t.startsWith('/*') || t.startsWith('*');
+  return t.startsWith(token);
+}
+
+// The leading comment block: its lines, skipping a shebang and any blank lines above it.
+function leadingBlock(lines, token) {
+  let i = 0;
+  if (lines[0]?.startsWith('#!')) i = 1;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  const block = [];
+  while (i < lines.length && isCommentLine(lines[i], token)) {
+    block.push(lines[i]);
+    i++;
+  }
+  return block;
+}
+
+// Rule ids disabled file-wide (first 20 lines) or on one line.
+function disabledIds(text) {
+  const head = text.split('\n').slice(0, 20).join('\n');
+  const ids = new Set();
+  for (const m of head.matchAll(/source-lint-disable:\s*([a-z0-9,\s-]+)/g))
+    for (const id of m[1].split(',')) ids.add(id.trim());
+  return ids;
+}
+
+// The comment ratio of the lines this change ADDS, or null where there is nothing to grade. An untracked
+// file is added whole; a tracked one is graded on its `+` lines against HEAD. Reading the diff rather than
+// the file is what makes the rule fair: inherited prose is somebody else's row, and a session that adds
+// twenty clean lines to a 60%-comment file passes.
+function addedRatio(path, token) {
+  let added;
+  try {
+    const tracked = spawnSync('git', ['ls-files', '--error-unmatch', path], { encoding: 'utf8' }).status === 0;
+    if (!tracked) added = readFileSync(path, 'utf8').split('\n');
+    else {
+      const out = spawnSync('git', ['diff', '-U0', '--no-color', 'HEAD', '--', path], { encoding: 'utf8' });
+      if (out.status !== 0) return null;
+      added = out.stdout.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++')).map((l) => l.slice(1));
+    }
+  } catch {
+    return null;
+  }
+  const nonBlank = added.filter((l) => l.trim() !== '');
+  if (nonBlank.length < ADDED_MIN_LINES) return null;
+  const comments = nonBlank.filter((l) => isCommentLine(l, token)).length;
+  return { ratio: comments / nonBlank.length, comments, lines: nonBlank.length };
+}
+
+function lintFile(path, findings) {
+  if (SKIP.test(path)) return false;
+  const token = tokenFor(path);
+  if (!token) return false;
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return false;
+  }
+  if (GENERATED.test(text.split('\n').slice(0, 5).join('\n'))) return false;
+
+  const lines = text.split('\n');
+  const disabled = disabledIds(text);
+  const add = (id, n, excerpt) => {
+    if (disabled.has(id)) return;
+    const lineDisable = /source-lint-disable:\s*([a-z0-9,\s-]+)/.exec(lines[n - 1] ?? '');
+    if (lineDisable && lineDisable[1].split(',').some((x) => x.trim() === id)) return;
+    findings.push({ path, n, id, ...RULES[id], excerpt });
+  };
+
+  // --- the header ---------------------------------------------------------------------------------
+  const block = leadingBlock(lines, token);
+  if (block.length === 0) add('header-missing', 1);
+  else {
+    const head = block.join('\n');
+    // The FIRST path-shaped token, compared exactly — containment would pass a header reading
+    // `packages/old-name/src/app.ts` for a file at `src/app.ts`, which is the rename this catches.
+    const named = /([\w.@-]+(?:\/[\w.@-]+)*\.[A-Za-z]{1,5})\b/.exec(head);
+    if (!named) add('header-missing', 1);
+    else if (named[1] !== path) {
+      if (basename(named[1]) === basename(path)) add('header-path-stale', 1, named[1]);
+      else add('header-missing', 1, `names ${named[1]}`);
+    }
+    if (block.length > HEADER_MAX_LINES) add('header-too-long', 1, `${block.length} lines`);
+  }
+
+  // --- density, block length, and comment prose --------------------------------------------------
+  let commentLines = 0;
+  let nonBlank = 0;
+  let runStart = 0;
+  let run = 0;
+  lines.forEach((line, i) => {
+    if (line.trim() !== '') nonBlank++;
+    if (isCommentLine(line, token)) {
+      commentLines++;
+      if (run === 0) runStart = i + 1;
+      run++;
+      const body = line.replace(/^\s*(\/\/+|\/\*+|\*+\/?|--+|#+)\s?/, '');
+      if (NARRATION.test(body)) add('comment-narration', i + 1, body.slice(0, 90));
+      const shout = SHOUTING.exec(body);
+      if (shout) add('comment-shouting', i + 1, shout[1].slice(0, 60));
+      return;
+    }
+    if (run > BLOCK_MAX_LINES) add('comment-block-long', runStart, `${run} lines`);
+    run = 0;
+  });
+  if (run > BLOCK_MAX_LINES) add('comment-block-long', runStart, `${run} lines`);
+  if (nonBlank >= RATIO_MIN_LINES) {
+    const ratio = commentLines / nonBlank;
+    if (ratio > RATIO_CEILING) add('comment-ratio', 1, `${Math.round(ratio * 100)}% of ${nonBlank} lines`);
+  }
+  const grown = addedRatio(path, token);
+  if (grown && grown.ratio > ADDED_RATIO_CEILING)
+    add('comment-ratio-added', 1, `${grown.comments} of ${grown.lines} added lines`);
+  return true;
+}
+
+function expandDirs(paths) {
+  const out = [];
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    if (!statSync(p).isDirectory()) {
+      out.push(p);
+      continue;
+    }
+    for (const e of readdirSync(p, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      out.push(...expandDirs([`${p.replace(/\/$/, '')}/${e.name}`]));
+    }
+  }
+  return out;
+}
+
+const args = process.argv.slice(2);
+let files = args.filter((a) => a !== '--changed');
+if (args.includes('--changed')) {
+  const out = execSync('git diff --name-only HEAD; git ls-files --others --exclude-standard', { encoding: 'utf8', shell: '/bin/bash' });
+  files = [...new Set([...files, ...out.split('\n').filter(Boolean)])];
+}
+files = expandDirs(files);
+if (!files.length) {
+  console.error('usage: node source-lint.mjs <file | dir ...> | --changed');
+  process.exit(2);
+}
+
+const findings = [];
+let checked = 0;
+for (const f of files) if (lintFile(f, findings)) checked++;
+
+for (const f of findings.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'block' ? -1 : 1)))
+  console.log(`${f.path}:${f.n} [${f.severity}] ${f.id} — ${f.message}${f.excerpt ? `: "${f.excerpt}"` : ''}`);
+const blocks = findings.filter((f) => f.severity === 'block').length;
+console.log(`\n${findings.length} finding(s), ${blocks} blocking, ${checked} file(s) checked.`);
+process.exit(blocks ? 1 : 0);

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 |