@dzhechkov/p-replicator 1.5.18 → 1.6.0

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.