@dzhechkov/p-replicator 1.9.0 → 1.10.1

package/tests/unit/check-docs-complete.test.js

@@ -130,6 +130,49 @@ describe('the cheap question is asked before the swarm is spent', () => {
     }
   });
 
+  test('P16 - a markdown task-list checkbox is NOT a placeholder', () => {
+    // MEASURED against a real completed /replicate project: 17 lines like `- [ ] AC покрыты
+    // автотестами` were reported as "possibly unfilled". Worse, that project's own Completion.md
+    // TEACHES the notation — "флажки [ ] при каждом FR-GROWTH-00N" — so this warning fired on the
+    // convention the pipeline itself prescribes. Noise on a legitimate convention trains people to
+    // ignore warnings, which is the failure this checker exists to prevent, one level down.
+    const withBoxes = '# Specification\n\n'
+      + '- [ ] AC покрыты автотестами\n'
+      + '- [x] События пишутся в аналитику\n'
+      + '* [ ] Anti-fraud сценарий задокументирован\n'
+      + '| `invite_shown` | [ ] | Share-CTA показан в момент первого рендера |\n\n' + REAL;
+    const r = check(complete({ 'Specification.md': withBoxes }));
+    assert.equal(r.code, 0, 'checkboxes must not block: ' + r.out);
+    assert.ok(!/Specification\.md: возможно незаполнено/.test(r.out),
+      'and must not even WARN — a warning on the pipeline own convention is noise: ' + r.out);
+  });
+
+  test('P17 - a real bracketed placeholder on a checkbox LINE is still seen', () => {
+    // The narrowing must not become an escape hatch: skipping the whole line would let a genuine
+    // placeholder hide behind a checkbox prefix.
+    const r = check(complete({
+      'Specification.md': '# Spec\n\n- [ ] [описание критерия приёмки]\n\n' + REAL,
+    }));
+    assert.match(r.out, /возможно незаполнено/,
+      'a bracketed placeholder AFTER a checkbox must still be reported: ' + r.out);
+  });
+
+  test('P18 - Final_Summary.md is reported when absent, and does not block', () => {
+    // MEASURED: the pipeline promises it in three places — replicate.md and two sites in
+    // sparc-prd-mini, including a whole SYNTHESIS phase — and a real completed project produced
+    // 8 of 9 promised documents WITHOUT it. One project is not enough evidence to decide whether
+    // the pipeline is broken or the document is optional in practice, and BLOCKING on it would
+    // have refused every project that ran like that one.
+    // The shared fixture DOES write it, so this case removes it deliberately — the state a real
+    // completed project was measured in.
+    const files = complete();
+    delete files['Final_Summary.md'];
+    const r = check(files);
+    assert.equal(r.code, 0, 'its absence must not block: ' + r.out);
+    assert.match(r.out, /Final_Summary\.md: отсутствует, хотя конвейер его обещает/,
+      'but the discrepancy must be NAMED, not silently tolerated: ' + r.out);
+  });
+
   test('P7 - no docs directory exits 2, and an empty one does too', () => {
     const none = check({}, { noDocs: true });
     assert.equal(none.code, 2, 'nothing to check is not "complete": ' + none.out);

package/tests/unit/check-ports.test.js

@@ -176,6 +176,105 @@ describe('the storage-port rule finally has a check that can fail', () => {
       'a non-storage service with no proxy present is not this rule\'s business: ' + r.out);
   });
 
+  test('P13 — every argument shape resolves in one frame', { skip: !DOCKER }, () => {
+    // The defect: `-f` stayed RELATIVE while the same spawnSync call overrode docker's cwd to the
+    // directory that relative path already named, so docker re-applied the directory component.
+    // MEASURED before the fix: `check-ports.cjs projects/01` from the parent reported
+    // "open /tmp/X/projects/01/projects/01/docker-compose.yml".
+    //
+    // PR-019 diagnosed a project-root join. There is no such join in the file — proven in pure shell:
+    // the SAME `-f projects/01/docker-compose.yml` succeeds from /tmp/X and doubles from
+    // /tmp/X/projects/01. The cwd override IS the mechanism.
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-frame-')));
+    try {
+      const proj = path.join(root, 'projects', '01');
+      fs.mkdirSync(proj, { recursive: true });
+      fs.writeFileSync(path.join(proj, 'docker-compose.yml'),
+        'services:\n  db:\n    image: postgres:16\n');
+      // Every shape in ONE run: a matrix asserted from one side only cannot be told from a constant.
+      const shapes = [
+        ['projects/01', root, 'a bare relative directory — the shape that was broken'],
+        ['./projects/01', root, 'the ./-prefixed form, which path.join normalises identically'],
+        ['projects/01/docker-compose.yml', root, 'a relative path to the file itself'],
+        ['.', proj, 'the documented invocation — worked before only because it is idempotent'],
+        [null, proj, 'no argument at all'],
+        ['../01', proj, 'a sibling-relative path'],
+        [proj, root, 'absolute, from an unrelated cwd'],
+        [proj, proj, 'absolute, from inside'],
+      ];
+      for (const [arg, cwd, why] of shapes) {
+        const argv = arg === null ? [CHECK] : [CHECK, arg];
+        const r = spawnSync(process.execPath, argv, { encoding: 'utf8', cwd });
+        assert.equal(r.status, 0,
+          'shape must resolve (' + why + '): arg=' + JSON.stringify(arg) + ' cwd=' + cwd
+          + ' -> exit ' + r.status + ': ' + (r.stdout || '') + (r.stderr || ''));
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P14 — run from a PARENT cwd with a relative argument', { skip: !DOCKER }, () => {
+    // The blind spot that let this ship green. Every other case here builds its fixture with
+    // realpathSync(mkdtempSync(...)) and passes it whole — ALWAYS ABSOLUTE — so all 12 tests passed
+    // against the live defect. A regression test that cannot reproduce the bug it guards is not a
+    // guard. This case is the one that could.
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-parent-')));
+    try {
+      const proj = path.join(root, 'projects', '01');
+      fs.mkdirSync(proj, { recursive: true });
+      fs.writeFileSync(path.join(proj, 'docker-compose.yml'),
+        'services:\n  db:\n    image: postgres:16\n    ports: ["5432:5432"]\n');
+      const r = spawnSync(process.execPath, [CHECK, 'projects/01'], { encoding: 'utf8', cwd: root });
+      // A real violation must be REPORTED, not lost behind a path error.
+      assert.equal(r.status, 1, 'expected the published-storage violation: ' + r.stdout + r.stderr);
+      assert.match(r.stdout, /Правило №0/, r.stdout);
+      assert.ok(!/projects\/01\/projects\/01/.test(r.stdout + r.stderr),
+        'the doubled path must be gone: ' + r.stdout + r.stderr);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P15 — a required variable is reported as itself, not masked', { skip: !DOCKER }, () => {
+    // The defect fired BEFORE docker parsed the file, so a genuine config error came back as
+    // "no such file". Second harm, and the one a user would waste the most time on.
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-mask-')));
+    try {
+      const proj = path.join(root, 'projects', '04');
+      fs.mkdirSync(proj, { recursive: true });
+      fs.writeFileSync(path.join(proj, 'docker-compose.yml'),
+        'services:\n  db:\n    image: postgres:${PGTAG:?PGTAG must be set}\n');
+      const r = spawnSync(process.execPath, [CHECK, 'projects/04'], { encoding: 'utf8', cwd: root });
+      assert.equal(r.status, 2, 'an unreadable config is still exit 2: ' + r.stdout);
+      assert.match(r.stdout, /PGTAG/, 'the REAL cause must reach the user: ' + r.stdout);
+      assert.ok(!/no such file/i.test(r.stdout),
+        'the path error must not stand in for the config error: ' + r.stdout);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P16 — the spawn overrides no cwd, and the hint neither guesses nor refutes itself', () => {
+    // Structural, so the removed line cannot creep back. MEASURED on Compose v5.1.1: project name,
+    // relative build contexts, .env discovery and env_file are ALL derived from the first -f file's
+    // directory — a .env in the process cwd was not even used as a fallback. The override's only
+    // demonstrated effect in this file's history is the defect.
+    const src = fs.readFileSync(CHECK, 'utf-8');
+    const at = src.indexOf('spawnSync(');
+    const spawnCall = src.slice(at, at + 300);
+    assert.ok(!/cwd:/.test(spawnCall),
+      'the cwd override must be GONE, not neutralised — a provably-useless line still encodes the '
+      + 'false premise that regrows the class: ' + spawnCall);
+    // The guessed cause named an UNREACHABLE case: a plain unset ${VAR} makes compose exit 0.
+    //
+    // Asserted on CODE, not on the file: the fix's own comment QUOTES the removed phrase to explain
+    // why it went, and a whole-file `includes` cannot tell a mention from a use. That is the same
+    // trap this repo has hit repeatedly, and it caught this test on its first run.
+    const code = src.split('\n')
+      .filter((l) => !l.trim().startsWith('//') && !l.trim().startsWith('*') && !l.trim().startsWith('/*'))
+      .join('\n');
+    assert.ok(!code.includes('обычно это незаданная переменная'),
+      'the hint must not name a cause that cannot produce this exit');
+    assert.match(code, /повторить ровно то, что делали мы/,
+      'and the cure must be presented as a reproduction of OUR invocation');
+    assert.match(src, /path\.resolve\(process\.cwd\(\)/,
+      'the argument must be absolutised once, at the boundary');
+  });
   test('P9 — a clean compose exits 0', { skip: !DOCKER }, () => {
     const r = check('services:\n  db:\n    image: postgres:16\n'
       + '  web:\n    image: node:22\n    ports: ["3000:3000"]\n');

package/tests/unit/generated-guard-templates.test.js

@@ -0,0 +1,134 @@
+'use strict';
+
+// The toolkit generator writes these guards into EVERY project it bootstraps, out of fenced blocks
+// in a markdown reference. They did not inherit the three-code discipline the package's own
+// checkers have, and the result was measured on 2026-08-27 with the threshold substituted to 2:
+//
+//   four `class …Entity` on FOUR lines            → ❌ VIOLATION, exit 1   correct
+//   the SAME four minified onto ONE line          → ✅ Aggregate size OK, exit 0
+//   the file does not exist                       → ✅ Aggregate size OK, exit 0
+//   the placeholder never substituted             → ✅ Aggregate size OK, exit 0   GREEN FOREVER
+//
+// The last is not in the field report and is the worst: `[ 4 -gt "{{MAX_ENTITIES_FROM_FITNESS}}" ]`
+// is an invalid integer comparison, bash errors, the `if` is false, and the script falls through to
+// success. A generator that ever fails to substitute produces a guard that can never refuse.
+//
+// These tests EXTRACT the blocks and RUN them. The defect passed every reading; only execution
+// against real fixtures proves anything.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const MD = path.join(PKG, 'templates', '.claude', 'skills', 'cc-toolkit-generator-enhanced',
+  'references', 'templates', 'ddd-hooks-commands.md');
+
+/** Every fenced shell block, in order — the same text the generator copies out. */
+function blocks() {
+  const md = fs.readFileSync(MD, 'utf-8');
+  const out = [];
+  const re = /^```(?:bash|sh)\s*\n([\s\S]*?)^```/gm;
+  for (let m = re.exec(md); m !== null; m = re.exec(md)) out.push(m[1]);
+  return out;
+}
+
+const named = (needle) => {
+  const b = blocks().find((x) => x.includes(needle));
+  assert.ok(b, 'no fenced block containing ' + needle + ' — the generator has nothing to write');
+  return b;
+};
+
+/**
+ * Run a block the way the generator would: substitute the placeholders, write it out, execute it.
+ * `substitute: false` leaves the placeholders intact — the un-substituted case.
+ */
+function runBlock(code, args, opts) {
+  const o = opts || {};
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-gen-')));
+  try {
+    let script = code;
+    if (o.substitute !== false) {
+      script = script
+        .replace(/\{\{MAX_ENTITIES_FROM_FITNESS\}\}/g, String(o.maxEntities ?? 2))
+        .replace(/\{\{MAX_METHODS_FROM_FITNESS\}\}/g, String(o.maxMethods ?? 10));
+    }
+    const sh = path.join(dir, 'guard.sh');
+    fs.writeFileSync(sh, script);
+    for (const [name, body] of Object.entries(o.files || {})) {
+      const abs = path.join(dir, name);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, body);
+    }
+    const r = spawnSync('bash', [sh, ...(args || [])], { cwd: dir, encoding: 'utf8' });
+    return { code: r.status, out: (r.stdout || '') + (r.stderr || '') };
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+const FOUR_LINES = 'class AEntity {}\nclass BEntity {}\nclass CEntity {}\nclass DEntity {}\n';
+const FOUR_MINIFIED = 'class AEntity {} class BEntity {} class CEntity {} class DEntity {}\n';
+
+describe('a generated guard inherits the discipline the shipped ones have', () => {
+  test('P1 - four declarations are four, on four lines or on one', () => {
+    // The measured false-green. grep -c counts LINES, so the minified form counted as 1 and the
+    // guard blessed four entities against a limit of two.
+    const g = named('Aggregate size');
+    for (const [label, body] of [['four lines', FOUR_LINES], ['one line', FOUR_MINIFIED]]) {
+      const r = runBlock(g, ['src/a.ts'], { files: { 'src/a.ts': body }, maxEntities: 2 });
+      assert.equal(r.code, 1, 'four entities over a limit of two must be a VIOLATION (' + label + '): ' + r.out);
+      assert.match(r.out, /4/, 'and the count must be reported (' + label + '): ' + r.out);
+    }
+  });
+
+  test('P2 - a missing file is exit 2 and is NAMED', () => {
+    const g = named('Aggregate size');
+    const r = runBlock(g, ['src/nope.ts'], { maxEntities: 2 });
+    assert.equal(r.code, 2, 'could-not-read is not "within limits": ' + r.out);
+    assert.match(r.out, /nope\.ts/, 'the unreadable path must be named: ' + r.out);
+  });
+
+  test('P3 - an unsubstituted placeholder is exit 2', () => {
+    // The mode the field report does not name, and the reason the discipline must hold BEFORE
+    // substitution: requiring the generator to always substitute correctly puts the property back
+    // on the generator's memory, which is layer 4.
+    const g = named('Aggregate size');
+    const r = runBlock(g, ['src/a.ts'], { files: { 'src/a.ts': FOUR_LINES }, substitute: false });
+    assert.equal(r.code, 2,
+      'an unsubstituted threshold made this guard green FOREVER: ' + r.out);
+    assert.match(r.out, /MAX_ENTITIES_FROM_FITNESS/,
+      'and the placeholder must be named so the generator failure is findable: ' + r.out);
+  });
+
+  test('P4 - the guard can still PASS', () => {
+    // A guard that only fails is as useless as one that only passes, and this suite would not tell
+    // them apart without this case.
+    const g = named('Aggregate size');
+    const r = runBlock(g, ['src/a.ts'],
+      { files: { 'src/a.ts': 'class AEntity {}\nclass BEntity {}\n' }, maxEntities: 2 });
+    assert.equal(r.code, 0, 'two entities under a limit of two is within limits: ' + r.out);
+  });
+
+  test('P5 - the advisory sibling stays advisory and says so', () => {
+    // `exit 0 # Warnings only, don't block` is HONEST, and generated projects may rely on it not
+    // blocking. The defect was never the exit code; it was that nothing said so where a user looks.
+    const g = named('DDD pattern');
+    const r = runBlock(g, ['src/a.ts'], { files: { 'src/a.ts': 'class Thing {}\n' } });
+    assert.equal(r.code, 0, 'the advisory reporter must keep exit 0: ' + r.out);
+    assert.match(r.out, /advisory|не блокирует|never blocks/i,
+      'and must say in its OWN OUTPUT that it does not gate: ' + r.out);
+  });
+
+  test('P6 - all three exit codes come from ONE block in one run', () => {
+    // Each case above asserts one direction; a constant-answering script could pass a subset.
+    const g = named('Aggregate size');
+    const seen = [
+      runBlock(g, ['src/a.ts'], { files: { 'src/a.ts': 'class AEntity {}\n' }, maxEntities: 2 }).code,
+      runBlock(g, ['src/a.ts'], { files: { 'src/a.ts': FOUR_MINIFIED }, maxEntities: 2 }).code,
+      runBlock(g, ['src/nope.ts'], { maxEntities: 2 }).code,
+    ];
+    assert.deepEqual(seen, [0, 1, 2], 'expected within/over/could-not-check: ' + JSON.stringify(seen));
+  });
+});

package/tests/unit/guard-forms.test.js

@@ -0,0 +1,302 @@
+'use strict';
+
+// A guard is worth exactly what it can refuse. Four shell forms make a guard structurally unable to
+// refuse anything, and all four are recorded from real defects — three of them REPRODUCED in this
+// package on 2026-08-27.
+//
+// The measured one that matters most does NOT live in a .sh file. It is a fenced bash block inside
+// references/templates/ddd-hooks-commands.md, which the toolkit generator writes into EVERY project
+// it bootstraps. Measured there: four `class …Entity` declarations on four lines are caught, the
+// SAME four minified onto one line report "✅ Aggregate size OK", and a missing file reports OK too.
+// A scan limited to *.sh would have missed it entirely — so this test reads markdown as well.
+//
+// THE TRAP THIS TEST IS WRITTEN AROUND: a comment explaining why `grep -c` is wrong necessarily
+// CONTAINS `grep -c`. So does a documentation table of forbidden forms. A mention is not a use —
+// the class that has bitten three separate times in one day, including inside the fix written for
+// it. Comments are stripped before scanning, and P3 is the guard on that.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const TPL = path.join(PKG, 'templates');
+
+/**
+ * The four forbidden forms.
+ *
+ * Each `re` is applied to COMMENT-STRIPPED shell. `why` is what a reader needs in order to fix it,
+ * not a restatement of the pattern.
+ */
+const FORBIDDEN = [
+  {
+    id: 'grep-c-as-occurrence-count',
+    // Fires only on a NON-TRIVIAL pattern. `grep -c ""` counts every line and IS a line count by
+    // construction; `grep -c "class.*Entity"` treats matching lines as a count of declarations,
+    // which is the measured defect. There is no syntactic difference beyond the pattern itself, and
+    // saying so is more honest than pretending the check is complete: `grep -c "^func"` where one
+    // per line is guaranteed would false-fire, and needs the opt-out marker below.
+    re: /\$\(\s*grep\s+-[a-zA-Z]*c[a-zA-Z]*\s+(?!-)(?!""|''|"\^"|'\^')\S/,
+    why: 'grep -c counts matching LINES, not occurrences. Four declarations minified onto one line '
+      + 'count as 1 — MEASURED in ddd-hooks-commands.md, where that exact form reports "OK" for four '
+      + 'entities when the limit is two. Count with `grep -o … | wc -l` when occurrences are meant.',
+  },
+  {
+    id: 'uppercase-name-class',
+    re: /\[A-Z_\]\+/,
+    why: '[A-Z_]+ silently passes any name containing other characters. This package already learned '
+      + 'it once: 06-package-deliver.md records "was {{[A-Z_]+}}, which silently passed {{feature-id}}".',
+  },
+  {
+    id: 'bare-grep-substitution-without-not-found-branch',
+    // A substitution carrying its own fallback (`|| true`, `|| echo …`) has handled the zero-match
+    // exit, so it must not fire. Without this the pattern refused `$(grep … || true)` — the very
+    // form it exists to recommend, which is how an eager guard becomes a deleted guard.
+    // Two shapes are exempt because grep's exit code cannot reach the variable in either:
+    //   - an explicit fallback: `$(grep … || true)`
+    //   - a PIPELINE: `$(grep … | wc -l)` — the exit status belongs to the LAST stage
+    // The second was found by this guard firing on the fix written for a different finding in the
+    // same session. An eager guard is not a stricter guard; it is a guard people delete.
+    re: /^[^\n#]*=\$\(\s*[a-z]*grep(?:(?!\|)[^)])*\)\s*$/m,
+    why: 'grep exits 1 when it matches nothing, and a bare $( ) swallows that. Under `set -e` the '
+      + 'script dies; without it the variable is empty and the comparison silently succeeds. Give it '
+      + 'an explicit not-found branch, or `|| true` with the empty case handled.',
+  },
+  {
+    id: 'echo-0-appended-to-grep-c',
+    re: /grep\s+-c[^\n]*\|\|\s*echo\s+0/,
+    why: '`grep -c … || echo 0` prints TWO values when there is no match, because grep -c already '
+      + 'prints 0 and then exits 1. The arithmetic that follows fails and the guard falls through to '
+      + 'success — MEASURED as one of the three false-green inputs in ddd-hooks-commands.md.',
+  },
+  {
+    id: 'guard-shaped-script-that-cannot-refuse',
+    // Not a grep form — a WHOLE-SCRIPT shape, so it is applied to scripts only (see scan()).
+    // A script that prints verdicts and whose only `exit 1` is its own usage check cannot refuse
+    // anything it was written to judge. MEASURED 2026-08-27: assess-code.sh returns 0 on code with
+    // TODO/FIXME/BUG/HACK, nested infinite loops, an empty catch and eval; assess-tests.sh returns
+    // 0 on tests that do not pass — while BOTH return 1 for a nonexistent path. "Could not check"
+    // is louder than "found violations", which is the semantics exactly inverted.
+    //
+    // This is the form the four grep patterns could NOT see. My first pass reported these two
+    // scripts for a different reason and the reason was WRONG: their substitutions are pipelines,
+    // where grep's exit code never reaches the variable. A guard that finds the right file for the
+    // wrong reason will exonerate it the moment the wrong reason is fixed.
+    scriptOnly: true,
+    test(code) {
+      if (!/❌|🔴|VIOLATION|FAIL/.test(code)) return false;      // not verdict-shaped
+      const exits = [...code.matchAll(/^\s*exit\s+([0-9]+)/gm)].map((m) => m[1]);
+      if (!exits.includes('1') && !exits.includes('2')) return true;   // cannot refuse at all
+      // The principled condition: EVERY non-zero exit happens before the script starts judging.
+      // Counting them was wrong — assess-tests.sh has TWO, both setup checks, and slipped through a
+      // rule that demanded exactly one. What matters is WHERE the last refusal is: if the script
+      // can no longer say no by the time it begins assessing, it cannot refuse its subject.
+      const positions = [...code.matchAll(/^\s*exit\s+[1-9]/gm)].map((m) => m.index);
+      if (positions.length === 0) return true;
+      const lastRefusal = Math.max(...positions);
+      // A verdict-shaped line FOLLOWED by a non-zero exit is a REFUSAL, not a judgement — that is
+      // the script saying "I cannot check", and it must not count as evidence that the script can
+      // refuse its subject. assess-tests.sh prints "🔴 FAILING: Test directory doesn't exist" two
+      // lines before its `exit 1`; without this the first-verdict position lands on the setup
+      // failure and the whole rule misses.
+      const lines = code.split('\n');
+      let firstVerdict = -1;
+      for (let i = 0; i < lines.length; i++) {
+        if (!/❌|🔴|VIOLATION|FAIL/.test(lines[i])) continue;
+        const followedByRefusal = lines.slice(i, i + 4).some((l) => /^\s*exit\s+[1-9]/.test(l));
+        if (followedByRefusal) continue;
+        firstVerdict = lines.slice(0, i).join('\n').length;
+        break;
+      }
+      return firstVerdict > 0 && lastRefusal < firstVerdict;
+    },
+    why: 'this script prints verdicts but its only non-zero exit is the usage check, so it can never '
+      + 'refuse what it judges. Give it the three-code contract: 0 clean, 1 violations found, 2 the '
+      + 'check did not run.',
+  },
+];
+
+/** Shell with comments removed, so a MENTION of a forbidden form cannot be read as a USE. */
+function stripShellComments(src) {
+  return src.split('\n')
+    .map((l) => (/^\s*#/.test(l) ? '' : l.replace(/(^|\s)#(?!\{).*$/, '$1')))
+    .join('\n');
+}
+
+/** Fenced blocks whose language tag is a shell, from a markdown file. */
+function shellBlocks(md) {
+  const out = [];
+  const re = /^```(bash|sh|shell|zsh)\s*\n([\s\S]*?)^```/gm;
+  for (let m = re.exec(md); m !== null; m = re.exec(md)) out.push(m[2]);
+  return out;
+}
+
+function walk(dir, hit) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, hit);
+    else hit(p);
+  }
+}
+
+/** Every shell this package ships: real .sh files, plus fenced shell inside markdown. */
+function shellSources() {
+  const out = [];
+  walk(TPL, (p) => {
+    if (p.endsWith('.sh')) {
+      out.push({ file: path.relative(PKG, p), code: fs.readFileSync(p, 'utf-8'), kind: 'script' });
+    } else if (p.endsWith('.md')) {
+      const md = fs.readFileSync(p, 'utf-8');
+      shellBlocks(md).forEach((code, i) => {
+        out.push({ file: path.relative(PKG, p) + ` (fenced block #${i + 1})`, code, kind: 'fenced' });
+      });
+    }
+  });
+  return out;
+}
+
+/**
+ * An explicit opt-out, on the line itself: `# guard-forms: ok — <reason>`.
+ *
+ * A guard with no exemption is a guard people delete wholesale the first time it is wrong. The
+ * reason is mandatory so the exemption stays reviewable — an unexplained opt-out is the silence this
+ * whole file exists to remove, one level down.
+ */
+const OPT_OUT = /#\s*guard-forms:\s*ok\s*[—-]\s*\S/;
+
+const scan = (code, kind) => {
+  const kept = code.split('\n').filter((l) => !OPT_OUT.test(l)).join('\n');
+  const stripped = stripShellComments(kept);
+  return FORBIDDEN.filter((f) => {
+    // A whole-script shape cannot be judged from a fenced fragment: a block may legitimately show
+    // one function of a larger script. Applied to real .sh files only.
+    if (f.scriptOnly && kind !== 'script') return false;
+    return f.test ? f.test(stripped) : f.re.test(stripped);
+  });
+};
+
+describe('a guard-shaped script must be able to refuse', () => {
+  test('P1 - each forbidden form is DETECTED in a fixture', () => {
+    // Without this the whole file could be a set of patterns that match nothing, and every scan
+    // below would pass by construction.
+    const fixtures = {
+      'grep-c-as-occurrence-count': 'N=$(grep -c "class.*Entity" "$FILE")\n',
+      'uppercase-name-class': 'grep -oE "\\{\\{[A-Z_]+\\}\\}" "$FILE"\n',
+      'bare-grep-substitution-without-not-found-branch': 'HITS=$(grep -n TODO "$FILE")\n',
+      'echo-0-appended-to-grep-c': 'N=$(grep -c foo "$F" 2>/dev/null || echo 0)\n',
+    };
+    for (const [id, code] of Object.entries(fixtures)) {
+      const hits = scan(code, 'script').map((f) => f.id);
+      assert.ok(hits.includes(id),
+        'the pattern for ' + id + ' matched nothing in its own fixture — it guards nothing: '
+        + JSON.stringify(hits));
+    }
+  });
+
+  test('P2 - legitimate shell is NOT refused', () => {
+    // An eager guard is not a stricter guard: it is a guard people delete.
+    const ok = [
+      ['LINES=$(grep -c "" "$FILE" || true)\n',
+        'grep -c with an EMPTY pattern counts every line — a line count by construction — and the '
+        + '|| true handles the zero-count exit. My first draft of this fixture omitted the || true '
+        + 'and was NOT legitimate: grep -c exits 1 when the count is 0, so the bare substitution '
+        + 'really did swallow it. The test caught my own example.'],
+      ['if grep -q pattern "$FILE"; then echo found; fi\n', 'a quiet membership test'],
+      ['HITS=$(grep -n TODO "$FILE" || true)\nif [ -z "$HITS" ]; then echo none; fi\n',
+        'a substitution WITH an explicit not-found branch'],
+      ['grep -oE "[A-Za-z_][A-Za-z0-9_]*" "$FILE"\n', 'a name class that is not the narrow one'],
+    ];
+    for (const [code, why] of ok) {
+      assert.deepEqual(scan(code, 'script').map((f) => f.id), [],
+        'legitimate shell refused (' + why + '): ' + code);
+    }
+  });
+
+  test('P3 - the same forms inside comments PASS', () => {
+    // A mention is not a use. This class has bitten three separate times in one day, including
+    // inside a fix written for it — a whole-file `includes` could not tell the fix's own explanatory
+    // comment from the thing it removed.
+    const commented = [
+      '# never use $(grep -c ...) as an occurrence count\n echo ok\n',
+      '#  {{[A-Z_]+}} silently passed {{feature-id}} — do not use it\n echo ok\n',
+      'echo ok   # HITS=$(grep -n TODO "$FILE") would swallow the exit code\n',
+      '# grep -c foo "$F" || echo 0 prints TWO values\n echo ok\n',
+    ];
+    for (const code of commented) {
+      assert.deepEqual(scan(code, 'script').map((f) => f.id), [],
+        'a comment EXPLAINING a forbidden form was read as using it: ' + code);
+    }
+  });
+
+  test('P5 - fenced bash inside markdown is scanned', () => {
+    // The measured false-green guard is not a .sh file — it is a fenced block the generator writes
+    // into every project it bootstraps. A scan limited to *.sh misses it entirely.
+    const sources = shellSources();
+    const fenced = sources.filter((s) => s.kind === 'fenced');
+    assert.ok(fenced.length >= 5,
+      'fenced shell blocks must be reachable — found ' + fenced.length);
+    const scripts = sources.filter((s) => s.kind === 'script');
+    assert.ok(scripts.length >= 1, 'and real .sh files too: ' + scripts.length);
+  });
+
+  test('P4 - a non-shell fenced block is NOT scanned as shell', () => {
+    // A ```js block containing `grep -c` in a string is not a shell guard.
+    const md = '```js\nconst cmd = \'grep -c foo bar\';\n```\n';
+    assert.deepEqual(shellBlocks(md), [], 'only shell-tagged fences are shell');
+  });
+
+  test('P6 - the package is scanned, and every finding is NAMED with its file and reason', () => {
+    // The live inventory. Findings are REPORTED rather than asserted away: the known-bad shipped
+    // scripts are filed separately (backlog 5e99d823, 11e62b43) and fixing them inside this change
+    // would mix two changes and hide which one did what. What must not happen is that they persist
+    // INVISIBLY — so this test fails the moment the count changes in either direction.
+    const findings = [];
+    for (const src of shellSources()) {
+      for (const f of scan(src.code, src.kind)) findings.push({ file: src.file, form: f.id, why: f.why });
+    }
+    // MEASURED, not guessed: 5 findings across 3 files. The generator block carries THREE forms at
+    // once — it is the artifact written into every bootstrapped project, and it is why this test
+    // scans markdown.
+    // MEASURED. Dropped from 4 when the generator's aggregate guard was rewritten in the same
+    // session: the two survivors are assess-code.sh and assess-tests.sh, filed as 11e62b43 and
+    // deliberately NOT fixed here. Lower this in the commit that fixes them.
+    const KNOWN = 0;
+    assert.equal(findings.length, KNOWN,
+      'the forbidden-form inventory changed. If you FIXED one, lower KNOWN in the same commit; if a '
+      + 'new one appeared, that is the defect this test exists to catch:\n'
+      + findings.map((f) => '  - ' + f.file + ' :: ' + f.form + '\n      ' + f.why).join('\n'));
+  });
+
+  test('P7 - every entry names its property in words, not in its find string', () => {
+    // MONOREPO-ONLY, and measured rather than assumed: files[] ships `tests/`, not `test/`, so the
+    // mutation registry does NOT reach a tarball — correctly, it is repo machinery and says nothing
+    // about a user's installation. Gated on the same POSITIVE fact the other monorepo-only files
+    // use, so a broken detection takes them all down together.
+    //
+    // Found by running the suite from a freshly packed tarball. My first guess at the cause was
+    // wrong — I assumed the shipped .sh scripts were missing; they ship fine. Measuring beat it.
+    let siblingPresent = false;
+    try {
+      siblingPresent = fs.statSync(path.resolve(PKG, '..', 'harness-core', 'package.json')).isFile();
+    } catch { siblingPresent = false; }
+    if (!siblingPresent) {
+      console.log('# SKIP (monorepo-only): the mutation registry is repo machinery and is not '
+        + 'shipped (files[] carries tests/, not test/). This says nothing about your installation.');
+      return;
+    }
+    // A registry whose entries describe their `find` string stops meaning anything the moment the
+    // code is refactored. The gate's contract makes a non-applying mutation a FAILURE, which keeps
+    // that honest; the WORDS are what let a human re-derive the entry afterwards.
+    const reg = JSON.parse(fs.readFileSync(path.join(PKG, 'test', 'mutation-registry.json'), 'utf-8'));
+    assert.ok(reg.entries.length >= 6, 'one entry is not a registry: ' + reg.entries.length);
+    for (const e of reg.entries) {
+      assert.ok(e.property && e.property.length > 80,
+        e.id + ': the property must be stated in words a human can re-derive from: '
+        + JSON.stringify(e.property));
+      assert.ok(!e.property.includes(e.mutation.find.trim()),
+        e.id + ': the property restates its own find string — it would mean nothing after a refactor');
+      assert.ok(fs.existsSync(path.join(PKG, e.file)), e.id + ': names a file that does not exist');
+    }
+  });
+});