@dzhechkov/p-replicator 1.5.18 → 1.6.0

package/tests/unit/detect-parse-anchor.test.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// The project-type scanner probed seven paths from one parameter, and the paths disagreed about what
+// that parameter was. MEASURED before the fix:
+//
+//   {docs_path}/docs/ddd/ · /.ai-context/ · /docs/tests/*.feature · /docs/adr/*.md · /docs/ADR.md
+//        → all five imply docs_path is the PROJECT ROOT
+//   {docs_path}/Architecture.md · {docs_path}/Solution_Strategy.md
+//        → these two imply docs_path is `docs/`
+//
+// And the pipeline writes those two files to docs/ (commands/replicate.md:234,237). So the SPARC
+// probes looked exactly where the pipeline does not write: the scanner could not recognise its own
+// output as SPARC-shaped.
+//
+// The parameter description was the root of it — one sentence naming two directories: "In Claude
+// Code / replicate context this is `docs/` (project root)." A reader implementing a probe picked
+// whichever half they read last. Nobody passes the parameter explicitly (a sweep of SKILL.md and
+// commands/replicate.md for `docs_path` returns nothing), so that sentence IS the specification.
+//
+// Both the field report and the reviewing swarm got this wrong in opposite directions: the report
+// said all six probes were wrong, the swarm said the table was wrong and the probes right. Five
+// probes are right, two are wrong, and the table contradicts itself.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MODULE = path.join(__dirname, '..', '..', 'templates', '.claude', 'skills',
+  'cc-toolkit-generator-enhanced', 'modules', '01-detect-parse.md');
+const read = () => fs.readFileSync(MODULE, 'utf-8');
+
+/** Every path this module probes, as written. */
+function probes() {
+  const src = read();
+  return [...src.matchAll(/\{docs_path\}\/([^"')\s]+)/g)].map((m) => m[1]);
+}
+
+describe('every probe resolves from ONE anchor, and the anchor is named once', () => {
+  test('P1 — no probe implies an anchor other than the project root', () => {
+    // The property is AGREEMENT across all of them, not the correctness of any single path. A
+    // top-level SPARC artifact would mean docs_path is `docs/` for that probe and the root for the
+    // others — which is the state this feature removes.
+    // DERIVED, not typed. Cross-family QE: the first version hard-coded seven basenames, so a probe
+    // for Research_Findings.md — a real pipeline document I had not listed — would have escaped it.
+    // The authoritative list is the pipeline's own: replicate.md writes every SPARC document to docs/.
+    const replicate = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', '.claude',
+      'commands', 'replicate.md'), 'utf-8');
+    const written = new Set([...replicate.matchAll(/^- `docs\/([A-Z][A-Za-z_]*\.md)`/gm)].map((m) => m[1]));
+    assert.ok(written.size >= 9,
+      'the pipeline document list must be readable from replicate.md: ' + [...written]);
+
+    const disagreeing = probes().filter((p) => written.has(p));
+    assert.deepEqual(disagreeing, [],
+      'these probe a document the pipeline writes to docs/, as if it were at the project root — '
+      + 'which only makes sense if docs_path is `docs/`, while every other probe treats it as the '
+      + 'root: ' + JSON.stringify(disagreeing));
+
+    // And the prose must not re-introduce the ambiguity the probes just lost. Five sites carried it.
+    const src = read();
+    assert.ok(!/top-level or docs\//.test(src),
+      'the scan catalog still preserves the "top-level or docs/" reading this feature removes');
+    for (const doc of ['Architecture.md', 'Solution_Strategy.md', 'PRD.md', 'Specification.md']) {
+      const bare = new RegExp('(?<![/\\w])`' + doc.replace('.', '\\.') + '`');
+      assert.ok(!bare.test(src),
+        'a pipeline document is named without its docs/ prefix, which reads as project-root: ' + doc);
+    }
+  });
+
+  test('P2 — the two SPARC probes look under docs/, where the pipeline writes', () => {
+    const src = read();
+    assert.match(src, /has_sparc_arch = exists\(f"\{docs_path\}\/docs\/Architecture\.md"\)/,
+      'commands/replicate.md:237 writes docs/Architecture.md');
+    assert.match(src, /has_sparc_sol\s+= exists\(f"\{docs_path\}\/docs\/Solution_Strategy\.md"\)/,
+      'commands/replicate.md:234 writes docs/Solution_Strategy.md');
+  });
+
+  test('P3 — the root-level probe stays at the root', () => {
+    // .ai-context/ sits beside .claude/, not under docs/. Moving it "for consistency" would break a
+    // probe that was correct all along — the failure mode the field report actually proposed.
+    assert.ok(probes().includes('.ai-context/'),
+      'the .ai-context probe must remain anchored at the project root: ' + JSON.stringify(probes()));
+    assert.ok(!probes().includes('docs/.ai-context/'),
+      '.ai-context/ is a root-level directory; probing it under docs/ finds nothing');
+  });
+
+  test('P4 — the parameter names ONE directory', () => {
+    const src = read();
+    const row = src.split('\n').find((l) => l.startsWith('| `docs_path` |'));
+    assert.ok(row, 'the parameter table row must exist');
+    assert.ok(!/this is `docs\/` \(project root\)/.test(row),
+      'the row still names two different directories in one breath — that sentence is what split '
+      + 'the probes in the first place: ' + row);
+    assert.match(row, /the PROJECT ROOT/,
+      'it must name the anchor unambiguously');
+    assert.match(row, /not `docs\/`/,
+      'and rule out the other reading explicitly, since that reading is what produced the split');
+  });
+
+  test('P5 — both ADR shapes are still collected', () => {
+    // This logic shipped in an earlier feature (one decision per file, and /replicate's single
+    // docs/ADR.md). Re-anchoring must not disturb it.
+    const src = read();
+    assert.match(src, /glob\(f"\{docs_path\}\/docs\/adr\/\*\.md"\)/, 'shape A: a directory of files');
+    assert.match(src, /f"\{docs_path\}\/docs\/ADR\.md"/, 'shape B: /replicate\'s single file');
+    assert.match(src, /has_adr = len\(collect_adrs\(docs_path\)\) > 0/,
+      'and the one definition that unifies them');
+  });
+});

package/tests/unit/external-dependency-check.test.js

@@ -0,0 +1,209 @@
+'use strict';
+
+// Every validation lens compared documents to documents. MEASURED — replicate.md's Phase-2 table
+// listed five: stories→PRD, AC→stories, Architecture.md, Pseudocode.md, cross-document coherence.
+// Nothing anywhere asked whether the outside world agrees, so a requirement could rest on a
+// capability the provider does not have and reach code generation unchallenged. It is the only
+// contact-with-reality defect in this pipeline; everything else it checks, it can check by reading
+// its own output.
+//
+// TWO honesty constraints bind this suite, both from the field report:
+//   1. check-pipeline-gaps.sh, which the report cites, DOES NOT EXIST. P7 keeps it uncited.
+//   2. No external fact may be baked in. What an API can do DRIFTS: a fixture asserting one would
+//      fail when the world changes and pass when our own rule breaks. P6 asserts the ABSENCE of
+//      vendor names, and no assertion here mentions a capability of any real service.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TPL = path.join(__dirname, '..', '..', 'templates', '.claude');
+const read = (rel) => fs.readFileSync(path.join(TPL, rel), 'utf-8');
+
+const SPARC = 'skills/sparc-prd-mini/SKILL.md';
+const REPLICATE = 'commands/replicate.md';
+
+/** The External Dependencies section of the Phase-5 Architecture.md template. Scoped, because an
+ *  assertion over a whole file passes on any prose that happens to mention the words. */
+function inventory() {
+  const src = read(SPARC);
+  const start = src.indexOf('## External Dependencies\n');
+  assert.ok(start > 0, 'the Phase-5 template must carry an External Dependencies section');
+  const end = src.indexOf('## Data Architecture', start);
+  assert.ok(end > start, 'and it must sit before Data Architecture, where the stack is still in view');
+  return src.slice(start, end);
+}
+
+/** Phase 2 of replicate.md — a lens declared in a later phase validates nothing. */
+function phase2() {
+  const src = read(REPLICATE);
+  const start = src.indexOf('### Phase 2: VALIDATION');
+  const end = src.indexOf('### Phase 3', start);
+  assert.ok(start > 0 && end > start, 'replicate.md must have a Phase 2 before Phase 3');
+  return src.slice(start, end);
+}
+
+describe('the pipeline asks whether the outside world can do what a requirement needs (PR-010)', () => {
+  test('P1 — the inventory exists and carries all five columns', () => {
+    const block = inventory();
+    // The HEADER ROW, not five words scattered through prose. Cross-family QE: a paragraph
+    // containing all five labels would have replaced the table without failing.
+    const header = block.split('\n').find((l) => l.startsWith('| Capability needed |')) || '';
+    assert.notEqual(header, '', 'the inventory must have a table header row starting with the '
+      + 'capability column');
+    for (const col of ['Capability needed', 'Provider / API', 'Evidence', 'Verdict',
+      'Requirements relying on it']) {
+      assert.ok(header.includes(col), 'the header row must carry the column: ' + col);
+    }
+    // One row per CAPABILITY, not per vendor: a provider can do one of two things you need.
+    assert.match(block, /One row per capability, not one row\s+per vendor/,
+      'the granularity must be stated, or one row hides two questions');
+  });
+
+  test('P2 — the evidence rule is CLOSED on both sides', () => {
+    // Saying what evidence IS leaves every reader to decide what it is not. The three ways this
+    // check gets faked are named, so a row using one of them is visibly not evidence.
+    const block = inventory();
+    assert.match(block, /link to the PROVIDER'S OWN documentation/,
+      'what counts must be stated precisely — not "a source"');
+    assert.match(block, /plus the date it was checked/,
+      'a citation without a date cannot be re-checked later');
+    // Cross-family QE, the load-bearing finding: CONFIRMED was self-attested, and a plausible URL is
+    // the cheapest forgery there is. A verbatim quote is what a link alone cannot fake.
+    assert.match(block, /verbatim QUOTE from\s+that page stating the capability/,
+      'a non-fabricable artifact must be required, not just a link');
+    assert.match(block, /a URL nobody opened/,
+      'and the link-alone forgery must be named as not-evidence');
+    assert.match(block, /do NOT count/, 'and the rule must be closed on the other side too');
+    for (const fake of ['landing page', 'pricing page', 'recollection']) {
+      assert.ok(block.includes(fake), 'the not-evidence list must name: ' + fake);
+    }
+  });
+
+  test('P3 — exactly three verdicts, and the empty case is explicit', () => {
+    const block = inventory();
+    // Each verdict must be a ROW of the verdict table, not a word somewhere in the prose. Found by
+    // mutation: renaming the UNCONFIRMED row to UNKNOWN left the vocabulary broken and the first
+    // version of this assertion green, because the word still appeared in the paragraph below it.
+    for (const v of ['CONFIRMED', 'UNCONFIRMED', 'CONTRADICTED']) {
+      assert.match(block, new RegExp('^\\| ' + v + ' \\|', 'm'),
+        'the verdict must be a row of the verdict table, not merely mentioned: ' + v);
+    }
+    // Two values would collapse "we checked and it cannot" into "nobody checked", which overstates
+    // one and hides the other. The reason has to be written down or the third value looks redundant.
+    assert.match(block, /exactly three, because two would hide a difference that\s+matters/,
+      'the reason for three values must be recorded, or a later edit will merge two of them');
+    // EXACTLY three: the first version asserted the three exist and let a fourth in silently.
+    const verdictRows = block.split('\n')
+      .filter((l) => /^\| [A-Z_]+ \|/.test(l) && !l.startsWith('| Verdict |'));
+    assert.equal(verdictRows.length, 3,
+      'the verdict table must have exactly three rows, not merely contain the three: '
+      + JSON.stringify(verdictRows));
+    assert.match(block, /No external dependencies —\s+this product calls no third-party service/,
+      'a project with none must say so: an empty section and an absent one look identical');
+  });
+
+  test('P4 — Phase 2 declares the sixth lens, inside Phase 2', () => {
+    const block = phase2();
+    const lensRow = block.split('\n').find((l) => l.startsWith('| `validator-dependencies` |')) || '';
+    assert.notEqual(lensRow, '',
+      'the lens must be a ROW of the validator table, not a mention in prose');
+    assert.match(lensRow, /External Dependencies/,
+      'and its scope column must name the section it reads: ' + lensRow);
+    assert.match(lensRow, /evidence that names that capability/,
+      'and its criteria column must say what it checks for: ' + lensRow);
+    assert.match(block, /the only one that looks OUTSIDE the\s+documents/,
+      'and say what makes it different from the other five, or it reads as a sixth of the same kind');
+  });
+
+  test('P5 — the exit criteria carry BOTH consequences, and UNCONFIRMED does not pass silently', () => {
+    // Anchored to the exit-criteria ROW each term belongs to. Cross-family QE: three independent
+    // phrase matches anywhere in Phase 2 would pass on explanatory prose that changed no verdict.
+    const rows = {};
+    for (const l of phase2().split('\n')) {
+      const m = l.match(/^\| (🟢 READY|🟡 CAVEATS|🔴 NEEDS WORK) \|/);
+      if (m) rows[m[1]] = l;
+    }
+    assert.ok(rows['🟢 READY'] && rows['🟡 CAVEATS'] && rows['🔴 NEEDS WORK'],
+      'the exit-criteria table must carry all three verdict rows');
+    assert.match(rows['🔴 NEEDS WORK'], /any external dependency is `CONTRADICTED`/,
+      'a contradicted dependency must send the run back, in the row that sends it back');
+    assert.match(rows['🟡 CAVEATS'], /every `UNCONFIRMED` dependency NAMED row by row/,
+      'an unconfirmed dependency must be NAMED in the CAVEATS row — an unnamed caveat is one '
+      + 'nobody acts on');
+    assert.match(rows['🟢 READY'], /no external dependency `UNCONFIRMED` or `CONTRADICTED`/,
+      'and READY must exclude both, or the strongest verdict is the one that checks least');
+    // And the consequence must be scoped to the REQUIREMENT: without that, an inventory of nothing
+    // but UNCONFIRMED rows reaches Phase 3 with a caveat and feasibility is never established.
+    assert.match(inventory(), /cannot enter Phase 3 — defer, remove or replace them/,
+      'UNCONFIRMED must stop the requirements that rest on it, or the check is optional in practice');
+  });
+
+  test('P6 — NO vendor fact is baked in: external facts drift', () => {
+    // A fixture asserting what some API can do would fail when the world changes and pass when our
+    // own rule breaks. The template must teach the SHAPE and name nobody.
+    const block = inventory();
+    const vendors = ['Anthropic', 'OpenAI', 'Stripe', 'Twilio', 'SendGrid', 'AWS', 'Google Cloud',
+      'Azure', 'Firebase', 'Supabase'];
+    for (const v of vendors) {
+      assert.ok(!block.includes(v),
+        'the template must name no real provider — capabilities drift and a stale fact recorded as '
+        + 'evidence is worse than none. Found: ' + v);
+    }
+    // A denylist can only ever catch the names on it. The positive assertion is what actually holds:
+    // the example row's own cells must be bracketed placeholders, so there is no cell for a real
+    // vendor to sit in. The list above stays as a cheap second net.
+    const exampleRow = block.split('\n')
+      .find((l) => l.startsWith('| [') && l.includes('CONFIRMED')) || '';
+    assert.notEqual(exampleRow, '', 'the template must show one example row');
+    const cells = exampleRow.split('|').map((c) => c.trim()).filter(Boolean);
+    for (const cell of cells) {
+      assert.ok(/^\[|^CONFIRMED$/.test(cell) || cell.startsWith('['),
+        'every example cell must be a bracketed placeholder or the verdict itself, so no real '
+        + 'provider can sit in the row: ' + cell);
+    }
+    assert.match(block, /are PLACEHOLDERS/, 'and it must say the example names are placeholders');
+    assert.match(block, /a stale fact recorded as evidence is worse than\s+none/,
+      'with the reason, so a later editor does not helpfully fill in a real one');
+  });
+
+  test('P8 — the agent that DISPATCHES the swarm lists the same lenses as the command', () => {
+    // Found by an independent reviewer after the fact: commands/replicate.md gained the sixth lens
+    // and templates/.claude/agents/doc-validator.md did not. Two files describing one swarm, one of
+    // them a lens short — and the sha256 snapshot test cannot see it, because both files hash fine.
+    const cmd = read(REPLICATE);
+    const agent = fs.readFileSync(path.join(TPL, 'agents', 'doc-validator.md'), 'utf-8');
+    const names = (src) => new Set([...src.matchAll(/\| `(validator-[a-z-]+)`/g)].map((m) => m[1]));
+    const inCmd = names(cmd);
+    const inAgent = names(agent);
+    assert.ok(inCmd.size >= 6, 'the command must dispatch at least six lenses: ' + [...inCmd]);
+    assert.deepEqual([...inAgent].sort(), [...inCmd].sort(),
+      'the dispatching agent and the command disagree about the swarm: '
+      + JSON.stringify({ agent: [...inAgent], command: [...inCmd] }));
+    // And the count in the agent's own prose must match the table it introduces.
+    const stated = agent.match(/Launch (\d+) parallel validation agents/);
+    assert.ok(stated, 'doc-validator.md must state how many it launches');
+    assert.equal(Number(stated[1]), inAgent.size,
+      'doc-validator.md says ' + stated[1] + ' but tables ' + inAgent.size);
+  });
+
+  test('P7 — nothing cites check-pipeline-gaps.sh, which does not exist', () => {
+    // The report cites it. MEASURED — a repo-wide find returns nothing. Pointing a reader at a
+    // script that is not there is a worse failure than the gap it was cited to close.
+    for (const f of [SPARC, REPLICATE]) {
+      assert.ok(!read(f).includes('check-pipeline-gaps'),
+        f + ' references a script that does not exist in this repository');
+    }
+    // The premise, asserted rather than assumed: if someone ever ADDS the script, this goes red and
+    // whoever added it has to revisit the rule instead of leaving a stale prohibition behind.
+    const pkgRoot = path.join(__dirname, '..', '..');
+    const candidates = ['check-pipeline-gaps.sh', path.join('scripts', 'check-pipeline-gaps.sh'),
+      path.join('bin', 'check-pipeline-gaps.sh')];
+    for (const c of candidates) {
+      assert.ok(!fs.existsSync(path.join(pkgRoot, c)),
+        'the script now exists at ' + c + ' — this rule was written on the premise that it does '
+        + 'not, so revisit it rather than deleting this assertion');
+    }
+  });
+});

package/tests/unit/growth-module-b2b-gate.test.js

@@ -0,0 +1,104 @@
+'use strict';
+
+// Two callers disabled the exact branch the module they call declares. MEASURED:
+//
+//   commands/replicate.md:169        | M5: Growth Engine | If B2C/PLG | …
+//   agents/product-discoverer.md:22  | M5: Growth Engine | If B2C/PLG | …
+//   modules/05-growth-engine.md:62   - Если B2B → sales-led growth, не product-led; переключи framework
+//   reverse-engineering-unicorn/SKILL.md:94   MODULE 5: GROWTH ENGINE → …      (no condition)
+//
+// Three files disagreed about whether M5 runs, and the two that said "only for B2C" were the ones
+// that decided. For every B2B project the one output slot — product-discoverer.md "### Growth
+// Channels [From growth engine analysis — if applicable]" — arrived empty, not because there was
+// nothing to say but because the gate stopped the module that would have said it.
+//
+// NOT done, deliberately: editing the growth module. It exists in four byte-identical copies across
+// three published packages, kept in step by a --check gate that exits 1 on drift. A two-line fix in
+// two callers touches ONE package; touching the module is a three-package release. P5 pins that.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TPL = path.join(__dirname, '..', '..', 'templates', '.claude');
+const read = (rel) => fs.readFileSync(path.join(TPL, rel), 'utf-8');
+
+const CALLERS = [
+  { file: 'commands/replicate.md', produces: 'Channels, integrations' },
+  { file: 'agents/product-discoverer.md', produces: 'Channels, integrations, viral loops' },
+];
+const MODULE = 'skills/reverse-engineering-unicorn/modules/05-growth-engine.md';
+
+/** EVERY table row that decides whether M5 runs. Cross-family QE: taking the FIRST match let a gate
+ *  come back in a duplicate row further down, invisible to both helpers. */
+function m5Rows(file) {
+  const rows = read(file).split('\n').filter((l) => l.startsWith('| M5: Growth Engine |'));
+  assert.equal(rows.length, 1,
+    file + ' must have exactly one M5 row; found ' + rows.length + ': ' + JSON.stringify(rows));
+  return rows;
+}
+const cells = (row) => row.split('|').map((c) => c.trim());
+
+describe('the growth module is not gated off for the type it handles itself', () => {
+  test('P1 — neither caller conditions M5 on a product type', () => {
+    // Asserted on the ROW, not the file: the phrase "B2C" appears legitimately elsewhere (the
+    // sentence explaining WHY the gate went), and a whole-file check would forbid the explanation.
+    // The property is not "no condition" — cross-family QE was right that `Always` over-promises,
+    // because M5's outputs are CAC, channels and loops and an internal tool with no acquisition
+    // objective has nothing to put in them. The property is that the condition does not EXCLUDE a
+    // product type the module handles: if it names types at all, B2B must be among them.
+    for (const { file } of CALLERS) {
+      for (const row of m5Rows(file)) {
+        const condition = cells(row)[2];
+        assert.notEqual(condition, '', file + ': the M5 condition cell is empty');
+        const namesTypes = /B2C|B2B|PLG|product-led|sales-led/i.test(condition);
+        if (namesTypes) {
+          assert.match(condition, /B2B/i,
+            file + ' gates M5 on product type and leaves B2B out — the module handles B2B at '
+            + 'modules/05-growth-engine.md:62: ' + JSON.stringify(condition));
+        }
+        assert.ok(!/^If B2C/i.test(condition),
+          file + ' restored the original product-type gate: ' + JSON.stringify(condition));
+      }
+    }
+  });
+
+  test('P2 — the row keeps saying what M5 produces', () => {
+    // A removal that took the row with it would satisfy P1 and lose the module from the table.
+    // The OUTPUT COLUMN, not a substring of the row: cross-family QE noted a substring check passes
+    // if the text drifts into the condition cell.
+    for (const { file, produces } of CALLERS) {
+      for (const row of m5Rows(file)) {
+        assert.equal(cells(row)[3], produces,
+          file + ' lost or moved M5\'s output column: ' + row);
+      }
+    }
+  });
+
+  test('P3 — the orchestrator still runs M5 unconditionally: it is the fixed point', () => {
+    const skill = read('skills/reverse-engineering-unicorn/SKILL.md');
+    const line = skill.split('\n').find((l) => l.includes('MODULE 5: GROWTH ENGINE'));
+    assert.ok(line, 'SKILL.md must still list MODULE 5');
+    assert.ok(!/if |если |B2C|B2B|PLG/i.test(line),
+      'the orchestrator must stay unconditional — all three files agree with IT: ' + line);
+  });
+
+  test('P4 — the module\'s own B2B branch survives the removal that it justifies', () => {
+    // This is the load-bearing one. Removing the gate is safe BECAUSE the module decides per type.
+    // Without this assertion someone could delete the justification and keep the removal, and the
+    // module would then run for B2B with no B2B behaviour.
+    assert.match(read(MODULE), /Если B2B → sales-led growth, не product-led/,
+      'the branch that makes the ungated call correct must still be there');
+  });
+
+  test('P5 — the growth module is byte-identical: this feature touches two callers only', () => {
+    // Four byte-identical copies across three published packages hang off this file. Pinning its
+    // hash is what keeps a two-line fix from becoming a three-package release by accident.
+    const sha = crypto.createHash('sha256')
+      .update(fs.readFileSync(path.join(TPL, MODULE))).digest('hex');
+    assert.equal(sha, '98e8577aa5a5472574ac9bac590b76a4a3d16f99bc67ebec2b09b604c7c1faab',
+      'the growth module changed; that is a three-package release, not this feature');
+  });
+});

package/tests/unit/hooks-project-anchored.test.js

@@ -0,0 +1,223 @@
+'use strict';
+
+// The six shipped hooks resolved BOTH their own file and their own data against a directory that
+// drifts. One `cd` inside a Bash tool call broke all six for the rest of the session, silently,
+// because hooks are non-blocking.
+//
+// Two independent resolutions, failing differently:
+//   - the HOST resolves the command string  -> wrong: MODULE_NOT_FOUND, loud;
+//   - the SCRIPT resolves its own data      -> wrong: exit 0 having done nothing, silent.
+//
+// This suite is deliberately BEHAVIOURAL where it can be. The field report's own verification
+// looped the hooks from a subdirectory and checked the exit code: all four returned 0 while
+// committing nothing and injecting nothing. An exit code proves the module LOADED. P4/P5/P6 assert
+// an EFFECT, and P5 is the one that fails if either half of the fix is missing.
+
+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 HOOKS = ['autocommit-roadmap', 'autocommit-insights', 'autocommit-plans',
+  'session-insights', 'statusline', 'state-update'];
+
+const readTpl = (rel) => fs.readFileSync(path.join(TPL, rel), 'utf-8');
+
+/** Source with comments removed. Cross-family QE: the first version of P3 was satisfied by the
+ *  explanatory comment that NAMES both CLAUDE_PROJECT_DIR and __dirname, while the executable code
+ *  could still anchor anywhere. A mention is not a use. */
+function code(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+const settings = () => JSON.parse(readTpl('settings.json'));
+
+/** Every command string the host will spawn: the four hooks plus the status line. */
+function allCommands() {
+  const s = settings();
+  const out = [];
+  if (s.statusLine && s.statusLine.command) out.push(s.statusLine.command);
+  for (const entries of Object.values(s.hooks || {})) {
+    for (const entry of entries) for (const h of entry.hooks || []) out.push(h.command);
+  }
+  assert.ok(out.length >= 5, 'expected at least the 4 hooks + statusLine, got ' + out.length);
+  return out;
+}
+
+/** A throwaway git project with the shipped hooks installed and a subdirectory to run them from. */
+function project() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-anchor-'));
+  const real = fs.realpathSync(dir);            // macOS /var -> /private/var, else git paths differ
+  fs.mkdirSync(path.join(real, '.claude', 'hooks'), { recursive: true });
+  for (const h of HOOKS) {
+    fs.copyFileSync(path.join(TPL, 'hooks', h + '.cjs'),
+      path.join(real, '.claude', 'hooks', h + '.cjs'));
+  }
+  fs.mkdirSync(path.join(real, 'projects', '01-sub'), { recursive: true });
+  const git = (args) => execFileSync('git', args, { cwd: real, stdio: 'ignore' });
+  git(['init', '-q']);
+  git(['config', 'user.email', 'test@example.invalid']);
+  git(['config', 'user.name', 'test']);
+  return { root: real, sub: path.join(real, 'projects', '01-sub'), git };
+}
+
+/** Run one hook FROM THE SUBDIRECTORY — the only place this defect is visible. */
+function runFromSub(p, hook, { withEnv = true, args = [] } = {}) {
+  const env = { ...process.env };
+  if (withEnv) env.CLAUDE_PROJECT_DIR = p.root;
+  else delete env.CLAUDE_PROJECT_DIR;
+  try {
+    const stdout = execFileSync(process.execPath,
+      [path.join(p.root, '.claude', 'hooks', hook + '.cjs'), ...args],
+      { cwd: p.sub, env, encoding: 'utf8', stdio: 'pipe' });
+    return { code: 0, stdout: stdout || '' };
+  } catch (err) {
+    return { code: err.status ?? 1, stdout: err.stdout?.toString() ?? '' };
+  }
+}
+
+describe('hooks resolve against the project, not the drifting cwd (PR-013)', () => {
+  test('P1 — no command the host spawns resolves relatively', () => {
+    for (const cmd of allCommands()) {
+      assert.doesNotMatch(cmd, /node\s+["']?\.claude[/\\]/,
+        'a relative script path resolves against the drifting cwd, not settings.json: ' + cmd);
+      assert.match(cmd, /CLAUDE_PROJECT_DIR/,
+        'every command must be anchored at the project root: ' + cmd);
+      // A correctly-spelled anchor in front of a script that does not exist is still a dead hook.
+      const named = cmd.match(/hooks\/([A-Za-z0-9._-]+\.cjs)/);
+      assert.ok(named, 'the command must name a .cjs script: ' + cmd);
+      assert.ok(fs.existsSync(path.join(TPL, 'hooks', named[1])),
+        'settings.json points at a script this package does not ship: ' + named[1]);
+    }
+  });
+
+  test('P2 — the anchor is the PowerShell-safe braced form, and the rejected spellings stay rejected', () => {
+    for (const cmd of allCommands()) {
+      // MEASURED from the Claude Code binary: it rewrites the exact token ${CLAUDE_PROJECT_DIR}
+      // to ${env:CLAUDE_PROJECT_DIR} for PowerShell, and warns that the UNBRACED $CLAUDE_PROJECT_DIR
+      // "PowerShell reads as an undefined variable ($null)".
+      assert.match(cmd, /\$\{CLAUDE_PROJECT_DIR\}/,
+        'must use the braced form the host rewrites for PowerShell: ' + cmd);
+      // ${CLAUDE_PROJECT_DIR:-.} is what this repo's own config uses and is REJECTED here: the
+      // rewrite is a literal replaceAll of "${CLAUDE_PROJECT_DIR}", so the :- form never matches
+      // and stays a POSIX-only construct — against the template's own cross-platform promise.
+      assert.doesNotMatch(cmd, /\$\{CLAUDE_PROJECT_DIR:-/,
+        'the POSIX default-expansion form is not cross-platform: ' + cmd);
+      assert.doesNotMatch(cmd, /\$CLAUDE_PROJECT_DIR[^{]/,
+        'the unbraced form is null on PowerShell: ' + cmd);
+      assert.match(cmd, /"\$\{CLAUDE_PROJECT_DIR\}[^"]*"/,
+        'the path must be double-quoted — a project path may contain spaces: ' + cmd);
+    }
+  });
+
+  test('P3 — no hook reads process.cwd(); all six are anchored', () => {
+    for (const h of HOOKS) {
+      const src = code(readTpl(path.join('hooks', h + '.cjs')));
+      assert.doesNotMatch(src, /process\.cwd\(\)/,
+        h + '.cjs still anchors on the drifting cwd — settings.json alone only makes it RUN');
+      assert.match(src, /process\.env\.CLAUDE_PROJECT_DIR/,
+        h + '.cjs must consult the host first — it is authoritative about the project');
+      assert.match(src, /__dirname/,
+        h + '.cjs must fall back to its own location, so it works with the variable absent');
+      // A truthy but RELATIVE host value would still resolve against the drifting cwd — the very
+      // bug this anchor removes. Truthiness is not enough; absoluteness is the property.
+      assert.match(src, /path\.isAbsolute\(/,
+        h + '.cjs must require the host value to be ABSOLUTE, not merely non-empty');
+    }
+  });
+
+  test('P4 — with CLAUDE_PROJECT_DIR UNSET, a hook still finds the project', () => {
+    // This is what makes the settings fix non-load-bearing for correctness: an older host, a
+    // hand-run, a CI shell. It also pins the || ordering: remove the __dirname fallback and this
+    // is the assertion that goes red.
+    const p = project();
+    try {
+      fs.mkdirSync(path.join(p.root, '.claude', 'insights'), { recursive: true });
+      fs.writeFileSync(path.join(p.root, '.claude', 'insights', 'index.md'),
+        '## Insight one\n\nbody one\n');
+      const r = runFromSub(p, 'session-insights', { withEnv: false });
+      assert.equal(r.code, 0, 'the hook must stay non-blocking');
+      assert.match(r.stdout, /Insight one/,
+        'with no env var and cwd in a subdirectory, the hook must still read the ROOT index');
+    } finally { fs.rmSync(p.root, { recursive: true, force: true }); }
+  });
+
+  test('P5 — EFFECT from a subdirectory: the roadmap is actually committed', () => {
+    // The property the whole feature exists for. An exit-code check passes on the broken hook;
+    // this does not. Fails if EITHER half of the fix is missing.
+    const p = project();
+    try {
+      fs.writeFileSync(path.join(p.root, '.claude', 'feature-roadmap.json'), '{"v":1}\n');
+      p.git(['add', '-A']);
+      p.git(['commit', '-q', '-m', 'base']);
+      fs.writeFileSync(path.join(p.root, '.claude', 'feature-roadmap.json'), '{"v":2}\n');
+
+      const before = execFileSync('git', ['rev-list', '--count', 'HEAD'],
+        { cwd: p.root, encoding: 'utf8' }).trim();
+      const r = runFromSub(p, 'autocommit-roadmap');
+      assert.equal(r.code, 0, 'the hook must stay non-blocking');
+      const after = execFileSync('git', ['rev-list', '--count', 'HEAD'],
+        { cwd: p.root, encoding: 'utf8' }).trim();
+
+      assert.equal(Number(after), Number(before) + 1,
+        'a changed roadmap must be COMMITTED when the hook runs from a subdirectory — '
+        + 'this is the assertion the report\'s exit-code check could not make');
+      const clean = execFileSync('git', ['status', '--porcelain', '--', '.claude/feature-roadmap.json'],
+        { cwd: p.root, encoding: 'utf8' });
+      assert.equal(clean.trim(), '', 'and the file must be left clean, not merely staged');
+    } finally { fs.rmSync(p.root, { recursive: true, force: true }); }
+  });
+
+  test('P7 — every autocommit hook puts -m BEFORE the `--`, or it commits nothing', () => {
+    // Found BY P5, not by review: everything after `--` is a pathspec, so
+    // ['commit','--only','--',RELATIVE,'-m',MSG] made git look for files literally named '-m' and
+    // 'docs(roadmap): auto-update'. It failed from EVERY directory, and the hook exits 0 on failure,
+    // so three autocommit hooks had never committed anything and nothing said so. P5 proves the
+    // behaviour for one of the three; this pins the shape for all three, since the other two have
+    // no git fixture of their own.
+    for (const h of ['autocommit-roadmap', 'autocommit-insights', 'autocommit-plans']) {
+      const src = readTpl(path.join('hooks', h + '.cjs'));
+      const m = src.match(/git\(\[('commit'[^\]]*)\]\)/);
+      assert.ok(m, h + '.cjs must invoke git commit');
+      const args = m[1];
+      // Cross-family QE: comparing indexOf directly made a MISSING -m pass, since -1 is less than
+      // any real index. Presence first, then order.
+      const mi = args.indexOf("'-m'");
+      const dd = args.indexOf("'--'");
+      assert.ok(mi >= 0, h + ".cjs: git commit must carry -m at all: " + args);
+      assert.ok(dd >= 0, h + ".cjs: git commit must carry the `--` pathspec separator: " + args);
+      assert.ok(mi < dd,
+        h + ".cjs: -m must precede `--`, else the message is parsed as a pathspec: " + args);
+    }
+  });
+
+  test('P6 — writer and reader agree on ONE path, from any cwd', () => {
+    // state-update.cjs writes the state, statusline.cjs reads it. Two drifting anchors can
+    // disagree, and a status line reading a file nobody wrote is worse than none.
+    const p = project();
+    try {
+      // A DISTINCTIVE value: cross-family QE noted that matching /replicate|VALIDATE/ would pass on
+      // any static status output that happens to contain those words, without reading the file at
+      // all. A token that appears nowhere else can only have come through the state file.
+      const TOKEN = 'ZQPHASE7X';
+      const w = runFromSub(p, 'state-update',
+        { args: ['--command', '/replicate', '--phase', TOKEN, '--index', '2', '--total', '4'] });
+      assert.equal(w.code, 0, 'the writer must stay non-blocking');
+      const stateFile = path.join(p.root, '.claude', '.p-replicator-state.json');
+      assert.ok(fs.existsSync(stateFile),
+        'the writer must publish state at the PROJECT root, not under the subdirectory it ran from');
+      assert.doesNotMatch(
+        fs.existsSync(path.join(p.sub, '.claude')) ? 'stray' : 'clean', /stray/,
+        'and must not have created a second .claude tree under the subdirectory');
+
+      const r = runFromSub(p, 'statusline');
+      assert.equal(r.code, 0, 'the reader must stay non-blocking');
+      assert.match(r.stdout, new RegExp(TOKEN),
+        'the reader must echo the DISTINCTIVE token the writer just published — a token that '
+        + 'appears nowhere else can only have arrived through the state file');
+    } finally { fs.rmSync(p.root, { recursive: true, force: true }); }
+  });
+});