@dzhechkov/p-replicator 1.5.17 → 1.6.0

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 }); }
+  });
+});

package/tests/unit/hooks-report-failures.test.js

@@ -0,0 +1,207 @@
+'use strict';
+
+// Each autocommit hook ended in a bare swallow — `catch (_err) { process.exit(0); }` — and the
+// comment beside it said "never break Claude session on commit failures". The goal was right and the
+// method was wrong: NOT BREAKING THE SESSION and SAYING NOTHING are different things, and only the
+// first one is the contract, because the contract is about the exit code.
+//
+// This is not a hypothetical class. It is the class that hid a permanent defect: git commit put -m
+// AFTER the `--`, so git read the message as a pathspec and every commit failed, from every
+// directory, forever. Three hooks had never committed anything and nothing said so. It surfaced on
+// 2026-08-26 only because a test asserted an EFFECT rather than an exit code.
+//
+// NOT changed here, and left to the owner: whether a DELETED target should be committed. That is a
+// product question — is removing your roadmap something you want auto-committed? — and it is filed.
+
+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 TPL = path.join(__dirname, '..', '..', 'templates', '.claude');
+
+const HOOKS = [
+  { name: 'autocommit-roadmap', artifact: '.claude/feature-roadmap.json',
+    write: (root) => {
+      fs.mkdirSync(path.join(root, '.claude'), { recursive: true });
+      return { file: path.join(root, '.claude', 'feature-roadmap.json'), body: '{"v":1}\n' };
+    } },
+  { name: 'autocommit-insights', artifact: '.claude/insights/',
+    write: (root) => {
+      fs.mkdirSync(path.join(root, '.claude', 'insights'), { recursive: true });
+      return { file: path.join(root, '.claude', 'insights', 'index.md'), body: '## one\n' };
+    } },
+  { name: 'autocommit-plans', artifact: 'docs/plans/',
+    write: (root) => {
+      fs.mkdirSync(path.join(root, 'docs', 'plans'), { recursive: true });
+      return { file: path.join(root, 'docs', 'plans', 'a.md'), body: '# plan\n' };
+    } },
+];
+
+/** A project with the hooks installed. `identity` decides whether git can commit at all. */
+function project(opts) {
+  const o = opts || {};
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-report-')));
+  fs.mkdirSync(path.join(root, '.claude', 'hooks'), { recursive: true });
+  for (const h of HOOKS) {
+    fs.copyFileSync(path.join(TPL, 'hooks', h.name + '.cjs'),
+      path.join(root, '.claude', 'hooks', h.name + '.cjs'));
+  }
+  if (o.git !== false) {
+    const git = (args) => execFileSync('git', args, { cwd: root, stdio: 'ignore' });
+    git(['init', '-q']);
+    // An EMPTY identity is a real, common failure: git refuses to commit and says why. It is the
+    // cheapest way to drive the failure path without breaking the fixture in an artificial way.
+    git(['config', 'user.email', o.identity === false ? '' : 'test@example.invalid']);
+    git(['config', 'user.name', o.identity === false ? '' : 'test']);
+  }
+  return root;
+}
+
+/** Run a hook and capture BOTH streams. The stream matters: MEASURED in the Claude Code binary,
+ *  a hook exiting 0 has its stderr discarded ("Exit code 0 - stdout/stderr not shown") while stdout
+ *  can be surfaced ("Exit code 0 - stdout shown in transcript mode (ctrl+o)"). The first version of
+ *  this feature wrote its notice to stderr — the one stream guaranteed to be invisible. */
+function runHook(root, hookName) {
+  const script = path.join(root, '.claude', 'hooks', hookName + '.cjs');
+  const env = Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: root });
+  const out = require('node:child_process').spawnSync(process.execPath, [script],
+    { cwd: root, env, encoding: 'utf8' });
+  return { code: out.status, stdout: out.stdout || '', stderr: out.stderr || '' };
+}
+
+const cleanup = (d) => fs.rmSync(d, { recursive: true, force: true });
+
+describe('an autocommit hook that cannot commit says so, once, without blocking', () => {
+  test('P1 — a real git failure is REPORTED, and the exit code is still 0', () => {
+    const root = project({ identity: false });
+    try {
+      const h = HOOKS[0];
+      const t = h.write(root);
+      fs.writeFileSync(t.file, t.body);
+      const r = runHook(root, h.name);
+      assert.equal(r.code, 0,
+        'the non-blocking contract is about the EXIT CODE and must be untouched');
+      assert.ok(r.stdout.includes('[' + h.name + ']'),
+        'the line must name the hook, or the reader cannot tell which artifact is uncommitted: '
+        + r.stdout);
+      assert.ok(r.stdout.includes(h.artifact),
+        'and name the artifact: ' + r.stdout);
+      // WHY, not just what. git's own words are the only thing that says why, and they are only
+      // available because stderr is piped rather than ignored.
+      assert.match(r.stdout, /identity/i,
+        "git's own reason must survive into the message: " + r.stdout);
+      assert.equal(r.stdout.trim().split('\n').length, 1,
+        'exactly one line — a hook that floods output is a hook people silence: ' + r.stdout);
+      assert.equal(r.stderr.trim(), '',
+        'the notice must NOT go to stderr: a hook exiting 0 has its stderr discarded, so writing '
+        + 'there is writing nowhere');
+      // The stage must be accurate. The outer catch also sees staging failures and a missing git
+      // binary, and calling either of those "could not commit" sends the reader to the wrong place.
+      assert.match(r.stdout, /could not commit/,
+        'this fixture fails AT the commit, so that is what the line must say: ' + r.stdout);
+    } finally { cleanup(root); }
+  });
+
+  test('P2 — nothing to commit is SILENT: a notice that cries wolf gets ignored', () => {
+    // The ordinary case, on most sessions, for all three hooks. If it printed, the next REAL failure
+    // would scroll past with the noise.
+    const root = project({});
+    try {
+      const h = HOOKS[0];
+      const t = h.write(root);
+      fs.writeFileSync(t.file, t.body);
+      execFileSync('git', ['add', '-A'], { cwd: root, stdio: 'ignore' });
+      execFileSync('git', ['commit', '-qm', 'base'], { cwd: root, stdio: 'ignore' });
+      const r = runHook(root, h.name);
+      assert.equal(r.code, 0);
+      assert.equal(r.stdout.trim(), '',
+        'the ordinary no-op path must stay silent: ' + r.stdout);
+    } finally { cleanup(root); }
+  });
+
+  test('P3 — not a git repository at all: silent, exit 0', () => {
+    const root = project({ git: false });
+    try {
+      const h = HOOKS[0];
+      const t = h.write(root);
+      fs.writeFileSync(t.file, t.body);
+      const r = runHook(root, h.name);
+      assert.equal(r.code, 0);
+      assert.equal(r.stdout.trim(), '', 'not-a-repo is not a failure to report: ' + r.stdout);
+    } finally { cleanup(root); }
+  });
+
+  test('P4 — the target is absent: silent, exit 0', () => {
+    const root = project({});
+    try {
+      const r = runHook(root, HOOKS[0].name);
+      assert.equal(r.code, 0);
+      assert.equal(r.stdout.trim(), '',
+        'an absent artifact is nothing to commit, not a failure: ' + r.stdout);
+    } finally { cleanup(root); }
+  });
+
+  test('P7 — a repository probe failure other than a plain non-repo is reported', () => {
+    // Every rev-parse failure used to be read as "not a git repository", so a machine with no git on
+    // PATH, a dubious-ownership refusal, or a permission error looked exactly like an ordinary
+    // non-repo directory. Two very different facts, one silence.
+    const root = project({ git: false });
+    try {
+      const h = HOOKS[0];
+      const t = h.write(root);
+      fs.writeFileSync(t.file, t.body);
+      // A directory owned by nobody this process can vouch for is hard to fake portably; the
+      // distinction itself is asserted on the source, and the ordinary case is proven live by P3.
+      const src = fs.readFileSync(path.join(TPL, 'hooks', h.name + '.cjs'), 'utf-8');
+      assert.match(src, /not a git repository/i,
+        'the ordinary case must be recognised by NAME, not by "any failure here is ordinary"');
+      assert.match(src, /throw probeErr/,
+        'and everything else must be re-thrown into the reporting path');
+      assert.equal(runHook(root, h.name).code, 0, 'and the ordinary case still exits 0');
+    } finally { cleanup(root); }
+  });
+
+  test('P5 — all three hooks behave identically', () => {
+    // They are the same shape; a difference between them would be a second thing to remember.
+    for (const h of HOOKS) {
+      const root = project({ identity: false });
+      try {
+        const t = h.write(root);
+        fs.writeFileSync(t.file, t.body);
+        const r = runHook(root, h.name);
+        assert.equal(r.code, 0, h.name + ' must exit 0');
+        assert.ok(r.stdout.includes('[' + h.name + ']'),
+          h.name + ' must report the failure too: ' + r.stdout);
+      } finally { cleanup(root); }
+    }
+  });
+
+  test('P6 — no hook still carries the bare swallow', () => {
+    for (const h of HOOKS) {
+      const src = fs.readFileSync(path.join(TPL, 'hooks', h.name + '.cjs'), 'utf-8');
+      assert.ok(!/catch \(_err\) \{\s*(\/\/[^\n]*\n\s*)*process\.exit\(0\);\s*\}/.test(src),
+        h.name + ' still swallows every failure without a word');
+      assert.match(src, /process\.stdout\.write/,
+        h.name + ' must report on stdout — stderr on exit 0 is discarded, so it is not a channel');
+      assert.ok(!/process\.stderr\.write/.test(src),
+        h.name + ' must not write its notice to the stream nobody reads');
+      assert.match(src, /let stage = 'start'/,
+        h.name + ' must track WHICH operation failed, or "could not commit" is claimed for a '
+        + 'staging failure and a missing git binary too');
+      // The reason is only available because git's stderr is piped. Ignoring it leaves a message
+      // that names what failed and not why, which is half a report.
+      // The PROPERTY is that git's stderr is captured, not the exact array. The first version pinned
+      // ['ignore','ignore','pipe'] literally and went red when stdout was later piped too — for a
+      // different feature that needed to READ a git answer. Pinning a shape instead of a property
+      // makes a compatible change look like a regression.
+      const stdio = src.match(/const SILENT = \{ stdio: (\[[^\]]*\])/);
+      assert.ok(stdio, h.name + ' must configure git stdio explicitly');
+      const streams = JSON.parse(stdio[1].replace(/'/g, '"'));
+      assert.equal(streams[2], 'pipe',
+        h.name + " must capture git's own words on stderr rather than discard them: " + stdio[1]);
+    }
+  });
+});

package/tests/unit/pipeline-file-ownership.test.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// /replicate and /start both write docker-compose.yml and .gitignore — on the RECOMMENDED path.
+//
+// `replicate.md` Phase 4 FINALIZE generates docker-compose.yml (from Architecture.md services),
+// Dockerfile and .gitignore; `start.md` Phase 1 generated package.json, docker-compose.yml,
+// .env.example, .gitignore and tsconfig.base.json with no existence guard at all. And
+// `replicate.md` itself says "Run /start to bootstrap the project" — so the collision was the normal
+// sequence, not an edge case.
+//
+// The field report proposed splitting ownership "by origin": architecture-derived to /replicate,
+// build-derived to /start. That cannot work here, because BOTH derive compose from the SAME source —
+// replicate.md from "Architecture.md services", start.md from "docs/Architecture.md → monorepo
+// structure, Docker Compose, tech stack". One artifact, derived twice; an origin split has nothing
+// to split on. So the guard is existence-plus-stated-change, which closes the silent loss without
+// deciding who owns the file — that ownership question is deliberately left to the owner.
+//
+// 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 CMDS = path.join(__dirname, '..', '..', 'templates', '.claude', 'commands');
+const read = (f) => fs.readFileSync(path.join(CMDS, f), 'utf-8');
+
+/** Phase 1 of start.md — placement matters: a guard in a later phase guards nothing. */
+function startPhase1(src) {
+  const start = src.indexOf('### Phase 1: Foundation');
+  const end = src.indexOf('### Phase 2');
+  assert.ok(start > 0, 'start.md must have a Phase 1');
+  assert.ok(end > start, 'start.md must have a Phase 2 after it');
+  return src.slice(start, end);
+}
+
+describe('/start must not silently discard what /replicate wrote (PR-008)', () => {
+  test('P1 — Phase 1 names BOTH overlapping files under the guard', () => {
+    const block = startPhase1(read('start.md'));
+    assert.match(block, /docker-compose\.yml/, 'the compose file must be named');
+    assert.match(block, /\.gitignore/, 'the gitignore must be named');
+    // Codex found a THIRD overlap I had missed: /replicate Phase 3 enhances README.md and /start
+    // Phase 4 generates-or-updates it, with no preservation rule on either side.
+    assert.match(block, /README\.md/, 'README.md overlaps too and must be under the same rule');
+    assert.match(block, /if not exists/,
+      'the guard phrase must be present — and it is /replicate\'s own phrase, so the two commands '
+      + 'read as one rule rather than two dialects');
+  });
+
+  test('P2 — the PRESENT case has its own stated action, not just an existence check', () => {
+    // Checking existence and then overwriting anyway would satisfy a weaker assertion. The property
+    // is what happens when the file IS there.
+    const block = startPhase1(read('start.md'));
+    assert.match(block, /файла НЕТ/, 'the absent case must be stated (a fresh tree still works)');
+    assert.match(block, /файл ЕСТЬ/, 'the present case must be stated');
+    assert.match(block, /не перегенерировать/,
+      'the present case must forbid regeneration outright — "take it into account" permits it');
+    // Cross-family QE (Codex gpt-5.6-sol): "keep it, change only for a documented reason" still let
+    // a run rewrite the whole file while calling it "added the missing port". The rule now demands a
+    // MINIMAL targeted edit, preservation of everything unrelated, and a look at the diff — the diff
+    // is what distinguishes the two, and a promise is not.
+    assert.match(block, /МИНИМАЛЬНУЮ/, 'the permitted edit must be bounded, not merely justified');
+    assert.match(block, /ПОСМОТРЕТЬ ДИФ/,
+      'inspecting the diff is what turns "I only added a port" from a claim into a check');
+  });
+
+  test('P3 — a permitted change must be NAMED, because an unannounced diff is the same loss', () => {
+    const block = startPhase1(read('start.md'));
+    assert.match(block, /НАЗВАТЬ каждый изменённый фрагмент/,
+      'a legitimate edit is allowed, but every changed hunk has to be visible to the reader');
+  });
+
+  test('P4 — replicate.md still guards .gitignore with the same phrase, and points at /start', () => {
+    const src = read('replicate.md');
+    assert.match(src, /`\.gitignore` — if not exists/,
+      'the pre-existing guard must survive — this feature adds one, it does not trade one for another');
+    // Codex: the collision is SYMMETRIC. /replicate re-run over a tree that already has a compose
+    // would discard it just as /start did; guarding one side only fixes half the defect.
+    assert.match(src, /`docker-compose\.yml` — from Architecture\.md services, \*\*if not exists\*\*/,
+      'replicate must guard its own compose too — the guard is symmetric or it is partial');
+    assert.match(src, /Phase 1/,
+      'replicate.md must point at the phase that reads these files, so the agreement is written down');
+  });
+
+  test('P5 — the guard is imperative and file-naming, not advisory', () => {
+    const block = startPhase1(read('start.md'));
+    // "be careful not to overwrite" would pass a reviewer and instruct nothing. The rule must name
+    // its files and its actions.
+    assert.ok(!/будьте осторожн|постарайтесь не|по возможности/i.test(block),
+      'advisory wording is not a rule');
+    assert.match(block, /Правило|правило/,
+      'the block must present itself as a rule');
+  });
+});