@nurix/etna 0.20.15 → 0.20.16

package/data/harnesses/etna/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/etna/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/etna/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.15",
+  "version": "0.20.16",
   "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
   "type": "module",
   "bin": {
@@ -42,5 +42,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "4dd6abe08c97"
+  "etnaFingerprint": "6b7b8d3d3e8f"
 }