@dzhechkov/p-replicator 1.5.18 → 1.6.0

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

package/tests/unit/roadmap-one-schema.test.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// One file, two canonical schemas. MEASURED: commands/next.md:84-96 documents feature-roadmap.json
+// with a `priority` field over the closed set mvp|high|medium|low, while
+// skills/cc-toolkit-generator-enhanced/references/templates/feature-suggestions.md names the SAME
+// path ("Generate as .claude/feature-roadmap.json") and documents a shape with NO priority at all —
+// and calls itself the single source of truth while being one of two. A generator following the
+// second produces a roadmap the package's own status line cannot read.
+//
+// The consumer was silent about it: statusline.cjs filters `f.priority === 'mvp'`, which is correct
+// against the schema, so a roadmap using `critical` — a value in NO documented enum — or carrying MVP
+// in `tags` rendered "mvp 0/0" and said nothing. The number was right and the reader learned nothing,
+// which is how a divergence becomes permanent.
+//
+// NOT DONE, deliberately: `tags.includes('mvp')` as a "fix". It would bless a document that also used
+// a value in no enum, and teach readers to accept whatever a generator emits. The counter matches the
+// specification; the documents diverged.
+//
+// Also REFUTED while measuring: the report's second defect, a supposed contradiction about who
+// creates the file. feature.md:44 sits under "### What does NOT happen in Mode 2" — it is scoped to
+// the mode where /replicate never runs. Both statements are true in their own mode; what was missing
+// is one place saying both, which P3 now requires.
+
+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 read = (rel) => fs.readFileSync(path.join(TPL, rel), 'utf-8');
+
+const NEXT = 'commands/next.md';
+const SUGGESTIONS = 'skills/cc-toolkit-generator-enhanced/references/templates/feature-suggestions.md';
+
+const STRIP = new RegExp('\\x1b\\[[0-9;]*m', 'g');
+
+/** Run the real status line over a real roadmap and return its plain-text Roadmap line. */
+function roadmapLine(features) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-schema-')));
+  try {
+    fs.mkdirSync(path.join(root, '.claude', 'hooks'), { recursive: true });
+    fs.copyFileSync(path.join(TPL, 'hooks', 'statusline.cjs'),
+      path.join(root, '.claude', 'hooks', 'statusline.cjs'));
+    fs.writeFileSync(path.join(root, '.claude', 'feature-roadmap.json'),
+      JSON.stringify({ version: '1.0', features }));
+    let code = 0;
+    let out = '';
+    try {
+      out = execFileSync(process.execPath, [path.join(root, '.claude', 'hooks', 'statusline.cjs')],
+        { cwd: root, env: Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: root }),
+          encoding: 'utf8', stdio: 'pipe' }) || '';
+    } catch (err) {
+      code = err.status == null ? 1 : err.status;
+      out = err.stdout ? err.stdout.toString() : '';
+    }
+    const text = out.replace(STRIP, '');
+    return { code, line: text.split('\n').find((l) => l.includes('Roadmap')) || '' };
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+}
+
+describe('feature-roadmap.json has ONE schema, and the reader says when a file misses it', () => {
+  test('P1 — next.md declares itself canonical and closes the priority set', () => {
+    const src = read(NEXT);
+    assert.match(src, /\*\*This table is THE schema for `\.claude\/feature-roadmap\.json`\.\*\*/,
+      'the schema must claim the role explicitly, or a second document can claim it too');
+    assert.match(src, /any other\s+document that shows the file's fields must point here/,
+      'and say what other documents must do instead of restating it');
+    assert.match(src, /`priority` is a CLOSED set — `mvp`, `high`, `medium`, `low`/,
+      'the enum must be stated as closed, in the canonical place');
+  });
+
+  test('P2 — feature-suggestions.md points at the schema instead of restating one', () => {
+    const src = read(SUGGESTIONS);
+    assert.match(src, /follow `\.claude\/commands\/next\.md`, which holds the single schema/,
+      'the second document must defer, not describe');
+    // Cross-family QE: the first version was `!A || B`, which the new "single data file" phrase
+    // makes true whether or not the stale claim survives. The claim's ABSENCE is the property —
+    // but SCOPED: a later CLAUDE.md snippet in this same file calls the roadmap the source of truth
+    // for feature STATUS, which is both true and unrelated. Asserting over the whole file would have
+    // forbidden a correct sentence. The claim that mattered was the architecture line at the top.
+    const header = src.slice(0, src.indexOf('## 2.'));
+    assert.ok(!/single source of truth/.test(header),
+      'the schema-level claim must be gone from the architecture line, not merely accompanied');
+    assert.match(header, /single data file/, 'replaced by what it actually is');
+    // Its own JSON sketch must not teach the incompatible shape either: an example is what a
+    // generator copies, and an example without `priority` is a second schema in disguise.
+    const sketch = src.slice(src.indexOf('"features": ['), src.indexOf('```', src.indexOf('"features": [')));
+    assert.match(sketch, /"priority": "mvp\|high\|medium\|low"/,
+      'the example must carry the canonical priority field: ' + sketch.slice(0, 200));
+  });
+
+  test('P3 — one place answers who creates the file, for BOTH modes', () => {
+    // The report called this a contradiction. It is not: feature.md's claim is scoped to Mode 2.
+    // What was missing is a single answer, so a reader landing on one half does not conclude the
+    // other is wrong.
+    const src = read(NEXT);
+    assert.match(src, /Who creates the file/, 'the question must be answered where the schema lives');
+    assert.match(src, /Phase 3 generates it from the PRD MVP scope/, 'the /replicate half');
+    assert.match(src, /the user\s+writes it by hand/, 'and the Mode 2 half');
+  });
+
+  test('P4 — a priority outside the enum is MARKED, not silently zero', () => {
+    const r = roadmapLine([
+      { id: 'a', status: 'next', priority: 'critical' },
+      { id: 'b', status: 'done', priority: 'critical' },
+    ]);
+    assert.equal(r.code, 0, 'the status line must never fail the session');
+    assert.match(r.line, /⚠2 schema/,
+      'an unreadable roadmap must say so, and say HOW MUCH: ' + r.line);
+    // Cross-family QE: the first version replaced the count with '?', discarding what WAS
+    // established. The known count is still knowledge; show both.
+    assert.match(r.line, /mvp 0\/0 ⚠2/,
+      'the known count must survive beside the warning: ' + r.line);
+  });
+
+  test('P5 — MVP moved into tags, no priority at all: also MARKED', () => {
+    // The exact shape the field report was collected on.
+    const r = roadmapLine([
+      { id: 'a', status: 'next', tags: ['mvp'] },
+      { id: 'b', status: 'next', tags: ['mvp'] },
+    ]);
+    assert.equal(r.code, 0, 'the status line must never fail the session');
+    assert.match(r.line, /mvp 0\/0 ⚠2 schema/,
+      'a roadmap with no priority field at all must be marked, with its count: ' + r.line);
+  });
+
+  test('P8 — PARTIAL population is caught: one valid priority beside a broken sibling', () => {
+    // Cross-family QE named this false negative exactly: the first detector only inspected features
+    // that already HAD a string priority, so a valid entry standing next to a missing or non-string
+    // one passed silently — and a half-migrated roadmap is the most likely real one.
+    const r = roadmapLine([
+      { id: 'a', status: 'done', priority: 'mvp' },
+      { id: 'b', status: 'next' },                     // missing entirely
+      { id: 'c', status: 'next', priority: 3 },        // present, not a string
+    ]);
+    assert.equal(r.code, 0);
+    assert.match(r.line, /⚠2 schema/,
+      'both broken siblings must be counted, not hidden by the valid one: ' + r.line);
+    assert.match(r.line, /mvp 1\/1/,
+      'and what IS known must still be reported: ' + r.line);
+  });
+
+  test('P6 — a valid roadmap renders exactly as before, with no marker', () => {
+    // The guard on over-marking: a rule that fires on good input is worse than no rule.
+    const r = roadmapLine([
+      { id: 'a', status: 'done', priority: 'mvp' },
+      { id: 'b', status: 'next', priority: 'mvp' },
+      { id: 'c', status: 'next', priority: 'low' },
+    ]);
+    assert.equal(r.code, 0);
+    assert.match(r.line, /mvp 1\/2/, 'the real counts must still render: ' + r.line);
+    assert.doesNotMatch(r.line, /schema/, 'and no marker on a conforming file: ' + r.line);
+
+    // An EMPTY roadmap has nothing to be off-schema about; marking it would be a false alarm in the
+    // most common state of a fresh project.
+    const empty = roadmapLine([]);
+    assert.equal(empty.code, 0);
+    assert.doesNotMatch(empty.line, /schema/, 'an empty roadmap must not be marked: ' + empty.line);
+  });
+
+  test('P7 — every case exits 0: the marker informs, it never blocks', () => {
+    for (const features of [
+      [{ id: 'a', status: 'next', priority: 'critical' }],
+      [{ id: 'a', status: 'next', tags: ['mvp'] }],
+      [{ id: 'a', status: 'next', priority: 'mvp' }],
+      [],
+    ]) {
+      const r = roadmapLine(features);
+      assert.equal(r.code, 0,
+        'the status line is advisory and must stay non-blocking: ' + JSON.stringify(features));
+      // Cross-family QE: exit 0 alone is satisfied by a program that prints nothing at all. The
+      // line must actually be rendered in every case.
+      assert.notEqual(r.line, '',
+        'and must still RENDER a roadmap line: ' + JSON.stringify(features));
+    }
+  });
+});

package/tests/unit/sparc-reconciliation.test.js

@@ -0,0 +1,117 @@
+'use strict';
+
+// sparc-prd-mini — Phase 5 must reconcile with Phase 4's data model before its checkpoint.
+//
+// The skill runs strictly linearly: Phase 4 PSEUDOCODE authors `## Data Structures` — entity types
+// with concrete field types — and only then does Phase 5 ARCHITECTURE choose the storage and
+// technology those structures have to live in. A sweep from Phase 5 to end-of-file found ZERO
+// re-reads of Pseudocode.md, so nothing ever noticed the two documents disagreeing. One ordering
+// fact explained three separately-reported field symptoms: a boolean where the schema took an enum,
+// an algorithm using a column the schema lacks, and a status with three values on one side and five
+// on the other.
+//
+// The fix is a RECONCILIATION step, deliberately NOT a reorder: SPARC is an acronym — Specification,
+// Pseudocode, Architecture, Refinement, Completion — and the skill is named `sparc-prd-mini`.
+// Swapping P and A would leave the file claiming a methodology it no longer follows. P5 below guards
+// that refused decision, so a later edit cannot quietly take it.
+//
+// These are PROMPT modules executed by a model, so the strongest deterministic layer available is
+// the file's own content. Each assertion is DISCRIMINATING: removing what it names turns it red.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SKILL = path.join(
+  __dirname, '..', '..', 'templates', '.claude', 'skills', 'sparc-prd-mini', 'SKILL.md',
+);
+
+function read() {
+  return fs.readFileSync(SKILL, 'utf-8');
+}
+
+/** The text between the Phase 5 heading and the Phase 6 heading — placement is the property. */
+function phase5(src) {
+  const start = src.indexOf('### Phase 5: ARCHITECTURE');
+  const end = src.indexOf('### Phase 6: REFINEMENT');
+  assert.ok(start > 0, 'Phase 5 heading must exist');
+  assert.ok(end > start, 'Phase 6 heading must follow Phase 5');
+  return src.slice(start, end);
+}
+
+describe('sparc-prd-mini — Phase 5 reconciles with Pseudocode (PR-005/PR-010)', () => {
+  test('P1 — the reconciliation step lives INSIDE Phase 5, before its checkpoint', () => {
+    const block = phase5(read());
+    assert.match(block, /СВЕРКА С ПСЕВДОКОДОМ/,
+      'the step must be inside Phase 5 — somewhere in the file is not the same property');
+    const step = block.indexOf('СВЕРКА С ПСЕВДОКОДОМ');
+    const checkpoint = block.indexOf('CHECKPOINT 5');
+    assert.ok(checkpoint > 0, 'Phase 5 must still carry its checkpoint');
+    assert.ok(step < checkpoint,
+      'reconciling AFTER the user has already approved the phase reconciles nothing');
+  });
+
+  test('P1b — the step is OUTSIDE the [MANUAL] CP5 block, so AUTO mode cannot skip it', () => {
+    // Cross-family QE (Codex gpt-5.6-sol) caught this: the first placement landed the step INSIDE
+    // the fenced `**[MANUAL] CP5:**` block, which AUTO mode is entitled to skip — a mandatory
+    // reconciliation that only happens in one of two run modes is not mandatory. P1's before/after
+    // ordering was true and still missed it, because "before the checkpoint text" and "outside the
+    // MANUAL-only block" are two different facts.
+    const block = phase5(read());
+    const step = block.indexOf('СВЕРКА С ПСЕВДОКОДОМ');
+    const manual = block.indexOf('**[MANUAL] CP5:**');
+    assert.ok(manual > 0, 'the MANUAL checkpoint marker must still exist');
+    assert.ok(step < manual,
+      'the step must precede the [MANUAL] marker — inside it, an AUTO run reconciles nothing');
+  });
+
+  test('P2 — it names BOTH artifacts to re-read, not "check for consistency"', () => {
+    const block = phase5(read());
+    assert.match(block, /Pseudocode\.md/, 'the step must name the file it re-reads');
+    assert.match(block, /## Data Structures/, 'and the data-model section within it');
+    // Codex: "an algorithm uses a missing column" cannot be detected from the type list alone.
+    assert.match(block, /## Core Algorithms/,
+      'the missing-column kind is undetectable without the algorithms — naming only the data '
+      + 'structures would promise a check the step cannot perform');
+  });
+
+  test('P3 — all three measured discrepancy kinds are named verbatim', () => {
+    const block = phase5(read());
+    // Each of these is a real symptom that reached code before this step existed. A generic
+    // "look for inconsistencies" would satisfy a reviewer and catch none of them.
+    // Checked in BOLD form, i.e. where the kinds are DEFINED. A first draft matched the bare
+    // phrase and did not discriminate: the same words also appear inside the example table row, so
+    // deleting a kind from the definition list left the assertion green. A phrase appearing in an
+    // example is not the same fact as a phrase defining a kind — the fifth instance of that trap
+    // in one day, so it is closed by construction here.
+    for (const kind of ['смена типа', 'отсутствующая колонка', 'несовпадение набора значений']) {
+      assert.ok(block.includes(`**${kind}**`),
+        `discrepancy kind must be DEFINED (bold) in the step, not merely mentioned: ${kind}`);
+    }
+  });
+
+  test('P4 — a written outcome is required in EVERY case, including no-change', () => {
+    const block = phase5(read());
+    assert.match(block, /## Reconciliation with Pseudocode/,
+      'the step must name the block it writes into Architecture.md');
+    assert.match(block, /Расхождений с/,
+      'the no-change case needs its own stated sentence — silence cannot distinguish '
+      + '"reconciled and clean" from "never reconciled"');
+  });
+
+  test('P5 — SPARC order is unchanged: the refused decision stays refused', () => {
+    const src = read();
+    const order = ['### Phase 3: SPECIFICATION', '### Phase 4: PSEUDOCODE',
+      '### Phase 5: ARCHITECTURE', '### Phase 6: REFINEMENT', '### Phase 7: COMPLETION'];
+    const at = order.map((h) => {
+      const i = src.indexOf(h);
+      assert.ok(i > 0, `heading must exist: ${h}`);
+      return i;
+    });
+    for (let i = 1; i < at.length; i += 1) {
+      assert.ok(at[i] > at[i - 1],
+        `phases must stay in S-P-A-R-C order — the acronym IS the method's name; ${order[i]} moved`);
+    }
+  });
+});