@dzhechkov/p-replicator 1.5.17 → 1.6.0

package/tests/unit/statusline-two-roots.test.js

@@ -0,0 +1,237 @@
+'use strict';
+
+// The status line answered TWO questions with ONE anchor, so it told half the truth from every
+// directory. MEASURED before the fix, with the toolkit at a course root and a 13-feature roadmap one
+// level down in projects/01-app:
+//
+//   from the course root:  "Roadmap — no roadmap yet"   Toolkit Skills 10/10, Hooks 6/6
+//   from projects/01-app:  "Roadmap Done 0/13"          Toolkit Skills 0/10, Hooks 0/6, Settings missing
+//
+// WHERE THE INSTRUMENTS ARE is settled by the hook's own location and is correct from any cwd.
+// WHICH PROJECT'S ROADMAP TO SHOW is a different question, answered by surveying projects/*.
+//
+// The report also proposed walking UPWARD to find the project. Measured: the roadmap lies BELOW, so
+// an upward walk returns the same root and the line does not change — the remedy does not treat its
+// own symptom. Not implemented; the backlog item orders it third.
+//
+// These tests run the REAL hook as a real subprocess and read its REAL rendered output.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG_DIR = path.resolve(__dirname, '..', '..');
+const TPL = path.join(PKG_DIR, 'templates', '.claude');
+const HOOK_SRC = path.join(TPL, 'hooks', 'statusline.cjs');
+
+function writeRoadmap(dotClaudeDir, spec) {
+  const total = spec.total;
+  const done = spec.done || 0;
+  const mvp = spec.mvp || 0;
+  const features = [];
+  for (let i = 0; i < total; i++) {
+    features.push({
+      id: 'f' + i,
+      status: i < done ? 'done' : 'next',
+      // 'priority' is the package's own documented key — commands/next.md:66 — NOT 'tags'. The field
+      // report claimed the reader was wrong here; measuring the schema refuted that, and rewriting
+      // the reader toward 'tags' would break the documented contract. Filed separately: 4ca0970c.
+      // 'low', not 'later': the priority set is CLOSED (mvp|high|medium|low) and this fixture
+      // used a value in no enum — an off-schema roadmap of my own making, which the schema
+      // marker correctly flagged the moment it existed.
+      priority: i < mvp ? 'mvp' : 'low',
+    });
+  }
+  fs.writeFileSync(path.join(dotClaudeDir, 'feature-roadmap.json'),
+    JSON.stringify({ version: '1.0', features }));
+}
+
+/** A course-shaped fixture: the toolkit at the root, sub-projects below. */
+function course(opts) {
+  const o = opts || {};
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-2roots-')));
+  fs.mkdirSync(path.join(root, '.claude', 'hooks'), { recursive: true });
+  fs.copyFileSync(HOOK_SRC, path.join(root, '.claude', 'hooks', 'statusline.cjs'));
+  if (o.toolkit !== false) {
+    for (let i = 1; i <= 10; i++) {
+      fs.mkdirSync(path.join(root, '.claude', 'skills', 's' + i), { recursive: true });
+    }
+    fs.copyFileSync(path.join(TPL, 'settings.json'), path.join(root, '.claude', 'settings.json'));
+  }
+  if (o.rootRoadmap) writeRoadmap(path.join(root, '.claude'), o.rootRoadmap);
+  for (const [name, spec] of Object.entries(o.subs || {})) {
+    const dir = path.join(root, 'projects', name, '.claude');
+    fs.mkdirSync(dir, { recursive: true });
+    if (spec === 'malformed') fs.writeFileSync(path.join(dir, 'feature-roadmap.json'), '{not json');
+    else writeRoadmap(dir, spec);
+  }
+  return root;
+}
+
+const STRIP = new RegExp('\\x1b\\[[0-9;]*m', 'g');
+
+/** Run the hook from `cwd`, with the host naming `projectRoot`. Returns plain text. */
+function render(root, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || root;
+  const env = Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: o.projectRoot || root });
+  try {
+    const out = execFileSync(process.execPath,
+      [path.join(root, '.claude', 'hooks', 'statusline.cjs')],
+      { cwd, env, encoding: 'utf8', stdio: 'pipe' });
+    return { code: 0, text: (out || '').replace(STRIP, '') };
+  } catch (err) {
+    return { code: err.status == null ? 1 : err.status,
+      text: (err.stdout ? err.stdout.toString() : '').replace(STRIP, '') };
+  }
+}
+
+const line = (text, marker) => (text.split('\n').find((l) => l.includes(marker)) || '');
+const cleanup = (d) => fs.rmSync(d, { recursive: true, force: true });
+
+describe('the status line answers two questions with two anchors (PR-011)', () => {
+  test('P1 — from a subdirectory, the toolkit counts are the ROOT\'s, not zeros', () => {
+    const root = course({ subs: { '01-app': { total: 13 } } });
+    try {
+      const r = render(root, { cwd: path.join(root, 'projects', '01-app') });
+      const toolkit = line(r.text, 'Toolkit');
+      assert.match(toolkit, /Skills\s+.?10\/10/,
+        'the toolkit lives at the root and must be counted there from any cwd: ' + toolkit);
+      // Derived, not typed: the expected total is whatever the package registers, so adding a hook
+      // moves this with it instead of turning it red for a correct reason.
+      const expectedHooks = Object.keys(
+        require(path.join(PKG_DIR, 'src', 'utils.js')).COMPONENTS.hooks.items).length;
+      assert.match(toolkit, new RegExp('Hooks\\s+.?1\\/' + expectedHooks),
+        'and the hook count too — the fixture ships exactly one hook: ' + toolkit);
+      // Cross-family QE: `line()` returns '' when the segment is absent, and '' trivially satisfies
+      // doesNotMatch — so dropping the Settings segment entirely would have passed. Presence first.
+      const settings = line(r.text, 'Settings');
+      assert.notEqual(settings, '', 'the Settings segment must be rendered at all');
+      assert.doesNotMatch(settings, /missing/,
+        'settings.json is at the root; reporting it missing from a subdirectory is the old defect');
+    } finally { cleanup(root); }
+  });
+
+  test('P2 — root has no roadmap, a sub-project has 13: the line reports those 13', () => {
+    // The exact measured symptom: "no roadmap yet" while thirteen features sat one level down.
+    const root = course({ subs: { '01-app': { total: 13, done: 4 } } });
+    try {
+      const roadmap = line(render(root).text, 'Roadmap');
+      assert.doesNotMatch(roadmap, /no roadmap yet/,
+        'a roadmap exists one level down; claiming none is the defect: ' + roadmap);
+      assert.match(roadmap, /4\/13/, 'the sub-project figures must appear: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P3 — sub-project figures are LABELLED as theirs, never presented as the root\'s own', () => {
+    // A number that means something other than it appears to is worse than a missing number.
+    const root = course({ subs: { '01-app': { total: 13, done: 4 } } });
+    try {
+      const roadmap = line(render(root).text, 'Roadmap');
+      assert.match(roadmap, /in\s+01-app/,
+        'the line must say WHERE the figures come from: ' + roadmap);
+      assert.doesNotMatch(roadmap, /mvp/,
+        'the root has no roadmap, so it has no mvp counter to report: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P4 — when the root HAS its own roadmap, the primary counters are the root\'s', () => {
+    const root = course({
+      rootRoadmap: { total: 5, done: 2, mvp: 3 },
+      subs: { '01-app': { total: 13, done: 4 } },
+    });
+    try {
+      const roadmap = line(render(root).text, 'Roadmap');
+      assert.match(roadmap, /Done\s+2\/5/,
+        'the root\'s own 2/5 must be the headline, not the sub-project\'s 4/13: ' + roadmap);
+      // 2/3, not 0/3: the fixture's first two features are both done AND mvp. The code was right
+      // and the first version of this expectation was wrong.
+      assert.match(roadmap, /mvp\s+2\/3/, 'and its own mvp counter: ' + roadmap);
+      // Sub-projects are still surfaced — as a separate, labelled segment. Merging them into
+      // "Done x/y" would silently change what that fraction means.
+      assert.match(roadmap, /\+1 sub\s+13/,
+        'sub-projects must appear as their own segment: ' + roadmap);
+      assert.doesNotMatch(roadmap, /Done\s+6\/18/,
+        'totals must NOT be merged into the root\'s counters: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P8 — several sub-projects, arbitrary names: the aggregate and the count are real', () => {
+    // Cross-family QE: every fixture was named '01-app', so the "N projects" branch had never been
+    // rendered and a survey that only recognised that one name would have passed the whole suite.
+    const root = course({ subs: { 'zeta-svc': { total: 4, done: 1 }, 'alpha-web': { total: 6, done: 2 } } });
+    try {
+      const roadmap = line(render(root).text, 'Roadmap');
+      assert.match(roadmap, /in\s+2 projects/,
+        'more than one sub-project must be reported as a count, not as one name: ' + roadmap);
+      assert.match(roadmap, /3\/10/,
+        'and the aggregate must be the real sum of both, 1+2 of 4+6: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P9 — the survey is BOUNDED: it runs on every prompt', () => {
+    // An unbounded scan adds its cost to every keystroke. 40 entries against a limit of 24.
+    const subs = {};
+    for (let i = 0; i < 40; i++) subs['p' + String(i).padStart(2, '0')] = { total: 1 };
+    const root = course({ subs });
+    try {
+      const r = render(root);
+      assert.equal(r.code, 0, 'the status line must never fail the session');
+      const roadmap = line(r.text, 'Roadmap');
+      assert.match(roadmap, /in\s+24 projects/,
+        'the scan must stop at its stated limit rather than walking all 40: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P5 — no roadmap anywhere: the legacy line is untouched', () => {
+    const root = course({});
+    try {
+      assert.match(line(render(root).text, 'Roadmap'),
+        /no roadmap yet \(run \/next or \/replicate\)/,
+        'the empty case must stay byte-identical — this feature adds a survey, it does not '
+        + 'rewrite the line everyone already knows');
+    } finally { cleanup(root); }
+  });
+
+  test('P6 — a file named projects/x and a malformed roadmap are skipped, never thrown on', () => {
+    const root = course({ subs: { '01-app': { total: 3 }, '02-bad': 'malformed' } });
+    try {
+      fs.writeFileSync(path.join(root, 'projects', 'notadir'), 'x');
+      const r = render(root);
+      assert.equal(r.code, 0, 'the status line must never fail the session');
+      const roadmap = line(r.text, 'Roadmap');
+      assert.match(roadmap, /0\/3/,
+        'the good sub-project still counts; the bad ones are skipped: ' + roadmap);
+    } finally { cleanup(root); }
+  });
+
+  test('P7 — the toolkit questions name TOOLKIT_ROOT, not a cwd expression', () => {
+    // Guards the split itself: re-point either reader at a cwd and this goes red. Comments are
+    // stripped first — a mention in prose is not a use in code.
+    // Line-wise, not regex-wise: a /\*...\*/ stripper over this file removed 12 158 of its 18 153
+    // characters and lost every function name, so the assertions below would have been searching an
+    // empty string. Dropping comment LINES is boring, and it is right. A trailing same-line comment
+    // survives, which cannot realistically fake a whole path.join expression.
+    const src = fs.readFileSync(HOOK_SRC, 'utf-8').split('\n')
+      .filter((l) => !/^\s*(\/\/|\/\*|\*)/.test(l)).join('\n');
+    assert.doesNotMatch(src, /process\.cwd\(\)/, 'the anchor must not come from the drifting cwd');
+    const toolkit = src.slice(src.indexOf('function parseToolkit'),
+      src.indexOf('function parseExpectedToolkit'));
+    assert.match(toolkit, /TOOLKIT_ROOT/,
+      'parseToolkit must name the root it means, so re-pointing it is a visible change');
+    const settingsAt = src.indexOf('function parseSettingsStatus');
+    assert.match(src.slice(settingsAt, settingsAt + 400), /TOOLKIT_ROOT/,
+      'and so must parseSettingsStatus');
+    assert.match(src, /function parseSubProjects/,
+      'the survey is what replaces guessing which project is meant');
+    // Cross-family QE: a defined-but-never-called function satisfies the line above. The behavioural
+    // tests are the real proof; this makes the dead-code case red here too.
+    assert.ok(src.split('parseSubProjects').length - 1 >= 2,
+      'parseSubProjects must be CALLED, not merely defined');
+    assert.match(src, /SUB_SCAN_LIMIT/,
+      'the survey must carry its own bound — it renders on every prompt');
+  });
+});

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

@@ -0,0 +1,209 @@
+'use strict';
+
+// scripts/sync-templates.js copies <found root>/.claude/{skills,commands,agents,rules,hooks} over
+// templates/.claude/ — the directory that becomes the npm tarball. It finds its source by walking up
+// to five parents and taking the FIRST one containing .claude/skills, which inside a monorepo is the
+// MONOREPO, whose .claude/skills holds a whole different toolkit.
+//
+// Nothing had fired only because package.json's prepublishOnly points at the publish gate, not here.
+// "Safe because dead" is not a safety property: a dead script can be revived by anyone who does not
+// know what it does — and two places used to invite exactly that, a test helper printing
+// "Run prepublishOnly first: node scripts/sync-templates.js" and an architecture doc calling it the
+// prepublishOnly hook.
+//
+// These tests run the REAL script as a real subprocess against real fixtures and compare the tree
+// before and after, because a script that exits 0 having copied two hundred files and one that exits
+// 0 having copied nothing look identical from the outside.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG_DIR = path.resolve(__dirname, '..', '..');
+const SCRIPT_SRC = path.join(PKG_DIR, 'scripts', 'sync-templates.js');
+const MARKER = '.p-replicator-sync-source';
+const DECLARATION = 'p-replicator-sync-source: v1';
+
+/** A fixture shaped like the real geometry: <root>/.claude/skills, and the package one level down
+ *  with its own templates/.claude tree. `marker` decides whether the root claims to be the source. */
+function fixture(opts) {
+  const o = opts || {};
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-sync-')));
+  if (o.rootHasClaude !== false) {
+    fs.mkdirSync(path.join(root, '.claude', 'skills', 'intruder'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.claude', 'skills', 'intruder', 'SKILL.md'),
+      '# a skill that belongs to the monorepo, not to this package\n');
+  }
+  // A VALID marker is a regular file carrying the declaration. Cross-family QE: the first fixture
+  // wrote an EMPTY file, which institutionalised exactly the weakest form of the authorization.
+  if (o.marker === true) fs.writeFileSync(path.join(root, MARKER), DECLARATION + '\n');
+  if (o.marker === 'empty') fs.writeFileSync(path.join(root, MARKER), '');
+  if (o.marker === 'dir') fs.mkdirSync(path.join(root, MARKER));
+  if (o.marker === 'symlink') {
+    const real = path.join(root, 'elsewhere');
+    fs.writeFileSync(real, DECLARATION + '\n');
+    fs.symlinkSync(real, path.join(root, MARKER));
+  }
+  if (o.marker === 'wrong') fs.writeFileSync(path.join(root, MARKER), 'yes please\n');
+
+  const pkg = path.join(root, 'packages', 'p-replicator');
+  fs.mkdirSync(path.join(pkg, 'scripts'), { recursive: true });
+  fs.copyFileSync(SCRIPT_SRC, path.join(pkg, 'scripts', 'sync-templates.js'));
+  fs.mkdirSync(path.join(pkg, 'templates', '.claude', 'skills', 'shipped'), { recursive: true });
+  fs.writeFileSync(path.join(pkg, 'templates', '.claude', 'skills', 'shipped', 'SKILL.md'),
+    '# the package\'s own shipped skill\n');
+  return { root, pkg };
+}
+
+/** SHA-256 of every file under a directory, keyed by relative path. */
+function treeHash(dir) {
+  const out = {};
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, e.name);
+      const rel = path.join(base, e.name);
+      if (e.isDirectory()) walk(full, rel);
+      else out[rel] = crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex');
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir, '');
+  return out;
+}
+
+function runScript(pkgDir) {
+  try {
+    const stdout = execFileSync(process.execPath, [path.join(pkgDir, 'scripts', 'sync-templates.js')],
+      { cwd: pkgDir, encoding: 'utf8', stdio: 'pipe' });
+    return { code: 0, out: stdout || '' };
+  } catch (err) {
+    return {
+      code: err.status == null ? 1 : err.status,
+      out: (err.stdout ? err.stdout.toString() : '') + (err.stderr ? err.stderr.toString() : ''),
+    };
+  }
+}
+
+const cleanup = (d) => fs.rmSync(d, { recursive: true, force: true });
+const readPkg = (rel) => fs.readFileSync(path.join(PKG_DIR, rel), 'utf-8');
+
+describe('a publish-time copy that was safe only because nobody called it', () => {
+  test('P1 — an unmarked root is REFUSED, and not one byte of templates/ changes', () => {
+    const f = fixture({});
+    try {
+      const templates = path.join(f.pkg, 'templates');
+      const before = treeHash(templates);
+      const r = runScript(f.pkg);
+      const after = treeHash(templates);
+      assert.notEqual(r.code, 0,
+        'a refusal must exit non-zero; exit 0 is how a guard becomes invisible to a caller');
+      assert.deepEqual(after, before,
+        'the refusal path must touch nothing — the check has to precede every write, not follow it');
+      assert.ok(!fs.existsSync(path.join(templates, '.claude', 'skills', 'intruder')),
+        'the monorepo skill must not have arrived in what becomes the tarball');
+    } finally { cleanup(f.root); }
+  });
+
+  test('P2 — the refusal says what it found and why, not just that it stopped', () => {
+    const f = fixture({});
+    try {
+      const out = runScript(f.pkg).out;
+      assert.match(out, /REFUSING to sync/, 'it must say it refused');
+      assert.ok(out.includes(f.root),
+        'and name the root it found, or the reader cannot tell which directory it objected to');
+      assert.match(out, /becomes the npm tarball/,
+        'and say what was at stake, or the refusal reads as a configuration nag');
+      assert.ok(out.includes(DECLARATION),
+        'and say how to opt in — quoting the exact declaration, or someone will delete the check');
+      assert.match(out, /a directory, a symlink, or an empty file is NOT a declaration/,
+        'and say which near-misses do not count, since those are the accidental ones');
+    } finally { cleanup(f.root); }
+  });
+
+  test('P3 — a MARKED root still syncs: the guard must not break the legitimate path', () => {
+    // A guard that also blocks the intended use is a deletion wearing a disguise.
+    const f = fixture({ marker: true });
+    try {
+      const r = runScript(f.pkg);
+      assert.equal(r.code, 0, 'an opted-in root must proceed: ' + r.out);
+      assert.ok(fs.existsSync(path.join(f.pkg, 'templates', '.claude', 'skills', 'intruder', 'SKILL.md')),
+        'and the source files must actually arrive');
+      assert.ok(fs.existsSync(path.join(f.pkg, 'templates', '.claude', 'skills', 'shipped', 'SKILL.md')),
+        'while MERGE mode preserves what the package already shipped');
+    } finally { cleanup(f.root); }
+  });
+
+  test('P8 — a near-miss marker does NOT authorize: empty, directory, symlink, wrong text', () => {
+    // Cross-family QE: any node satisfies existsSync, so an empty file committed by accident, or a
+    // stray directory, would have permanently authorized overwriting the tarball. lstat keeps a
+    // symlink from vouching for a tree this script cannot see, and the declaration is content nobody
+    // types by accident.
+    for (const kind of ['empty', 'dir', 'symlink', 'wrong']) {
+      const f = fixture({ marker: kind });
+      try {
+        const templates = path.join(f.pkg, 'templates');
+        const before = treeHash(templates);
+        const r = runScript(f.pkg);
+        assert.notEqual(r.code, 0, 'a ' + kind + ' marker must not authorize the copy');
+        assert.deepEqual(treeHash(templates), before,
+          'and must touch nothing: ' + kind);
+      } finally { cleanup(f.root); }
+    }
+  });
+
+  test('P9 — the script header does not claim to be the prepublishOnly hook', () => {
+    // The same false claim lived in three places. Fixing the doc and the helper while leaving the
+    // script's own docblock saying it "runs automatically before npm publish" would have left the
+    // lie in the most authoritative one.
+    const src = readPkg(path.join('scripts', 'sync-templates.js'));
+    const header = src.slice(0, src.indexOf('const fs ='));
+    assert.ok(!/prepublishOnly hook/.test(header),
+      'the header must not call it the prepublishOnly hook');
+    assert.ok(!/Run automatically before/.test(header),
+      'nor say it runs automatically — it does not, and that belief is what gets it run');
+    assert.match(header, /OPT-IN, and NOT part of publishing/,
+      'it must say what it actually is, at the top where a reader looks first');
+  });
+
+  test('P4 — no candidate root at all: the pre-existing skip is unchanged', () => {
+    const f = fixture({ rootHasClaude: false });
+    try {
+      const r = runScript(f.pkg);
+      assert.equal(r.code, 0, 'this path was always benign and must stay exit 0: ' + r.out);
+      assert.match(r.out, /Not in repo context — skipping sync/,
+        'and keep its existing message — this feature adds a guard, it does not rewrite the script');
+    } finally { cleanup(f.root); }
+  });
+
+  test('P5 — no helper tells a reader to run it', () => {
+    // The helper printed "Run prepublishOnly first: node scripts/sync-templates.js" when templates/
+    // was missing: a live invitation to the hazardous command, in the one situation where a reader
+    // is already confused.
+    assert.ok(!readPkg(path.join('tests', 'snapshot', 'update-baseline.js')).includes('sync-templates'),
+      'update-baseline.js must not name the script as a recovery step');
+  });
+
+  test('P6 — the architecture doc no longer calls it the prepublishOnly hook', () => {
+    // Being false in THIS direction is the worst one: it makes the script sound sanctioned and
+    // current, which is exactly the belief that gets it run.
+    const doc = readPkg(path.join('README', 'eng', '05_architecture.md'));
+    assert.ok(!/`scripts\/sync-templates\.js` — runs as `prepublishOnly` hook/.test(doc),
+      'the doc must not claim it runs as prepublishOnly — it does not');
+    assert.match(doc, /refuses to run unless the root it finds carries a `\.p-replicator-sync-source` marker/,
+      'and must record what it actually is now');
+  });
+
+  test('P7 — prepublishOnly does not point at it', () => {
+    // The regression guard on the fact that kept it dormant. If someone wires it into publishing,
+    // this goes red — and after this feature the guard would stop it anyway, which is the point:
+    // reviving it is now safe rather than catastrophic.
+    const pkg = JSON.parse(readPkg('package.json'));
+    const hook = (pkg.scripts && pkg.scripts.prepublishOnly) || '';
+    assert.ok(!hook.includes('sync-templates'),
+      'publishing must not run the template overwrite: ' + hook);
+    assert.match(hook, /prepublish-gate\.mjs/, 'publishing runs the gate');
+  });
+});

package/tests/unit/utils.test.js

@@ -341,11 +341,11 @@ describe('COMPONENTS.items SSOT', () => {
     }
   });
 
-  test('item counts: 10 skills, 11 commands, 4 agents, 5 rules, 1 settings', () => {
+  test('item counts: 10 skills, 11 commands, 4 agents, 6 rules, 1 settings', () => {
     assert.equal(Object.keys(utils.COMPONENTS.skills.items).length, 10, 'skills count');
     assert.equal(Object.keys(utils.COMPONENTS.commands.items).length, 11, 'commands count (post v1.4: + 9 generic commands)');
     assert.equal(Object.keys(utils.COMPONENTS.agents.items).length, 4, 'agents count');
-    assert.equal(Object.keys(utils.COMPONENTS.rules.items).length, 5, 'rules count (post v1.4: + 3 generic rules)');
+    assert.equal(Object.keys(utils.COMPONENTS.rules.items).length, 6, 'rules count (post v1.4: + 3 generic rules; + docker-ports)');
     assert.ok(utils.COMPONENTS.settings, 'settings component group added in v1.4');
     assert.equal(Object.keys(utils.COMPONENTS.settings.items).length, 1, 'settings.json count');
   });

package/tests/unit/validation-gate-teeth.test.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// The Phase-2 quality gate existed but could not block on the thing it exists to measure.
+//
+// MEASURED from the weight tables in scoring-system.md: a user story with NO acceptance criteria and
+// NO test links loses exactly Testable (8), Completeness (10) and Traceability (10), keeps every
+// other criterion legitimately full, and totals 72/100 — above the 70 READY line, filed by the
+// interpretation table under "fix minor issues, then proceed". The skill whose stated job is "Block
+// untestable requirements" passed it.
+//
+// The field report named a different pair — Measurable (8) + Traceability (10) = 82. Same arithmetic
+// hole, wrong pair: Measurable scores 0 for ANY requirement without a number, and plenty of correct
+// functional requirements have none, so a floor there converts a false PASS into a false BLOCK. The
+// floor is closed at Testable/Completeness, and P2 below is what keeps it closed.
+//
+// Second half: replicate.md said "Never skip validation" and nothing checked it. Phase 3 now carries
+// a precondition naming the file, both admissible verdicts, and the action on failure.
+//
+// These are PROMPT files a model executes, so the deterministic layer available is their content.
+// Every assertion below is DISCRIMINATING: remove what it names and it goes red.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const T = path.join(__dirname, '..', '..', 'templates', '.claude');
+const read = (rel) => fs.readFileSync(path.join(T, rel), 'utf-8');
+
+const SCORING = 'skills/requirements-validator/references/scoring-system.md';
+const VALIDATOR = 'skills/requirements-validator/SKILL.md';
+const REPLICATE = 'commands/replicate.md';
+
+/** A named section of a markdown file: the heading and everything up to the next same-level one.
+ *  Cross-family QE: an assertion that searches a WHOLE file passes on explanatory prose elsewhere,
+ *  which is exactly the "a mention is not a rule" failure this suite exists to prevent. */
+function section(src, heading, nextHeading) {
+  const start = src.indexOf(heading);
+  const end = src.indexOf(nextHeading, start + 1);
+  assert.ok(start >= 0, 'missing section: ' + heading);
+  assert.ok(end > start, 'missing section terminator: ' + nextHeading);
+  return src.slice(start, end);
+}
+
+/** Phase 3 of replicate.md — placement is the property: a precondition stated in a later phase
+ *  guards nothing, because the toolkit is already generated by then. */
+function phase3(src) {
+  const start = src.indexOf('### Phase 3: TOOLKIT GENERATION');
+  const end = src.indexOf('### Phase 4');
+  assert.ok(start > 0, 'replicate.md must have a Phase 3');
+  assert.ok(end > start, 'replicate.md must have a Phase 4 after it');
+  return src.slice(start, end);
+}
+
+describe('the Phase-2 gate must be able to block (PR-009 + PR-004)', () => {
+  test('P1 — the blocking floor exists and names BOTH vetoing criteria', () => {
+    const src = read(SCORING);
+    assert.match(src, /Blocking floor/, 'the floor must be stated where the arithmetic lives');
+    assert.match(src, /weakest link decides, never the average/,
+      'the family phrase — goap-research-ed25519/SKILL.md already states this rule in these words, '
+      + 'so the two skills read as one doctrine rather than two');
+    assert.match(src, /`Testable`[^\n]*\|[^\n]*no acceptance criteria/,
+      'Testable = 0 must veto: it is the criterion that asks whether AC exist at all');
+    assert.match(src, /`Completeness`[^\n]*\|[^\n]*No AC/,
+      'Completeness = 0 must veto too — the rubric\'s own "No AC" row');
+    assert.match(src, /72\/100/,
+      'the worked case must carry its number, or a later reader cannot check the claim');
+    // Cross-family QE, the load-bearing finding: the SAME agent assigns these scores and is bound by
+    // the floor, so the floor read a number the floor's subject had written. Reporting Testable = 4
+    // ("vague AC") on a story with no AC evades the veto without contradicting the rubric. The floor
+    // must therefore key on the artifact — a non-zero score has to quote the AC it is scoring.
+    assert.match(src, /REQUIRES quoting the acceptance criteria/,
+      'a non-zero Testable/Completeness must be evidenced by the AC text, not asserted');
+    assert.match(src, /No quote ⇒ the score is 0/,
+      'and the consequence of having no quote must be stated, or the requirement is decorative');
+  });
+
+  test('P2 — the floor is CLOSED, and says so with its reason', () => {
+    // Without this, the next editor "strengthens" the gate by adding Measurable, and every
+    // non-numeric functional requirement starts failing. The refusal has to be as visible as the rule.
+    const src = read(SCORING);
+    assert.match(src, /floor is CLOSED/, 'the list must declare itself closed');
+    assert.match(src, /`Measurable`[\s\S]{0,80}deliberately NOT/,
+      'Measurable must be named as excluded — naming it is what makes the exclusion survive an edit');
+    assert.match(src, /false pass into a false block/,
+      'the REASON must be recorded, not just the exclusion');
+  });
+
+  test('P3 — the skill\'s own verdict table carries the floor too', () => {
+    // One document fixed and the other not is worse than neither: a reader who stops at SKILL.md
+    // gets a verdict table that still says 72 is a minor fix.
+    // Scoped to the section that CARRIES the verdict table. Searching the whole file would pass on
+    // any prose that happens to mention the floor — the finding cross-family QE raised here.
+    const block = section(read(VALIDATOR), '## Scoring System', '## Output Format');
+    assert.match(block, /Blocking floor/, 'the floor must sit beside the score table it overrides');
+    assert.match(block, /Testable = 0/, 'and name the first vetoing criterion');
+    assert.match(block, /Completeness = 0/, 'and the second');
+    assert.match(block, /REQUIRES quoting/, 'and carry the evidence rule, not only the veto');
+  });
+
+  test('P4 — Phase 3 states a checkable precondition: file, verdicts, action', () => {
+    const block = phase3(read(REPLICATE));
+    assert.match(block, /docs\/validation-report\.md/,
+      'the precondition must name the FILE — "validated docs" is not checkable');
+    assert.match(block, /must EXIST/, 'existence is the first check');
+    // Cross-family QE: naming the three verdict emoji ANYWHERE in the phase is satisfied by prose.
+    // The property is a single anchored contract — WHICH line carries the verdict, and that a
+    // verdict word found elsewhere does not count.
+    assert.match(block, /\*\*first line\*\* must be `\*\*Verdict:\*\*` followed by 🟢 READY or 🟡 CAVEATS/,
+      'the admissible verdicts must be bound to the ONE authoritative line, not merely mentioned');
+    assert.match(block, /is NOT the verdict/,
+      'a verdict word elsewhere in the report must be explicitly rejected');
+    assert.match(block, /more than one line starting\s+with `\*\*Verdict:\*\*`/,
+      'uniqueness must be required, or two verdicts leave the reader to choose');
+    assert.match(block, /do NOT generate anything/,
+      'a precondition with no stated consequence is advice; the action is the rule');
+    assert.match(block, /return to Phase 2/, 'and where to go instead');
+  });
+
+  test('P5 — the Phase-2 exit table carries the same floor, so both ends agree', () => {
+    const src = read(REPLICATE);
+    const start = src.indexOf('### Phase 2: VALIDATION');
+    const end = src.indexOf('### Phase 3');
+    const block = src.slice(start, end);
+    assert.ok(start > 0 && end > start, 'replicate.md must have a Phase 2 before Phase 3');
+    assert.match(block, /blocking floor/,
+      'the phase that DECIDES the verdict must state the floor, not only the phase that consumes it');
+    assert.match(block, /`Testable = 0`/, 'named in the NEEDS WORK row');
+    assert.match(block, /`Completeness = 0`/, 'both of them');
+  });
+
+  test('P7 — Phase 2 EMITS the anchored verdict line Phase 3 reads', () => {
+    // A reader-side contract with no writer-side obligation is half a contract: Phase 3 would demand
+    // a first-line **Verdict:** that Phase 2 was never told to write, and every run would bounce.
+    const src = read(REPLICATE);
+    const block = src.slice(src.indexOf('### Phase 2: VALIDATION'), src.indexOf('### Phase 3'));
+    assert.match(block, /\*\*first line\*\* must be exactly one of/,
+      'Phase 2 must be told the exact form Phase 3 will read');
+    assert.match(block, /\*\*Verdict:\*\* 🟢 READY/, 'and shown it verbatim');
+    assert.match(block, /no other line in the file may begin with `\*\*Verdict:\*\*`/,
+      'and told to keep it unique, which is what makes Phase 3\'s uniqueness check satisfiable');
+  });
+
+  test('P6 — the precondition is imperative and file-naming, not advisory', () => {
+    const block = phase3(read(REPLICATE));
+    assert.ok(!/make sure|try to|ideally|should probably/i.test(block),
+      'advisory wording would pass a reviewer and instruct nothing');
+    // "Never skip validation" was TRUE, imperative, and unenforceable — it named no file to read.
+    // The NEVER line must now point at the check rather than stand alone.
+    // Cross-family QE was right that the first version accepted a self-attestation: a line reading
+    // "this is CHECKED, not assumed" is a CLAIM about the rule, and a claim is what the old advisory
+    // line already was. What makes the NEVER line non-advisory is that it POINTS at a named,
+    // readable artifact — so that is what this asserts.
+    const src = read(REPLICATE);
+    assert.match(src, /Never skip validation[^\n]*\n?[^\n]*`\*\*Verdict:\*\*` line of `docs\/validation-report\.md`/,
+      'the NEVER line must point at the exact line of the exact file that enforces it');
+  });
+});

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dzhechko
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.