@dzhechkov/p-replicator 1.5.18 → 1.6.0

package/tests/unit/spec-pseudocode-traceability.test.js

@@ -0,0 +1,146 @@
+'use strict';
+
+// A scenario could promise a check that no algorithm performs, and nothing in the pipeline could
+// notice. MEASURED: Specification.md's user-story template produced Gherkin acceptance criteria with
+// no identifier of any kind, Pseudocode.md's algorithm template was "### Algorithm: [Name]" with no
+// back-reference, and a sweep of the skill for traceab|SC-\d|scenario id returned nothing. The two
+// documents are written one phase apart and were never compared again.
+//
+// WHAT THIS FEATURE CLAIMS, exactly. It establishes that a CLAIM exists and that its two ends name
+// each other. It does not establish that the algorithm performs the check — no comparison of names
+// can. The nearest precedent says the same of itself: the K2 gate's own source records that its C1
+// check is a grep and that PROSE satisfies it. So this catches "nobody wrote anything about this
+// scenario"; it does not catch "someone wrote a line that mentions it", and closing a gap with
+// paperwork is precisely the failure the field report is about. P6 asserts the limit is written into
+// the template, so the next reader sees the same caveat the author did.
+
+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');
+const read = () => fs.readFileSync(SKILL, 'utf-8');
+
+function phase(src, heading, nextHeading) {
+  const start = src.indexOf(heading);
+  const end = src.indexOf(nextHeading, start + 1);
+  assert.ok(start > 0, 'missing section: ' + heading);
+  assert.ok(end > start, 'missing terminator: ' + nextHeading);
+  return src.slice(start, end);
+}
+
+const phase3 = (src) => phase(src, '### Phase 3: SPECIFICATION', '### Phase 4: PSEUDOCODE');
+const phase4 = (src) => phase(src, '### Phase 4: PSEUDOCODE', '### Phase 5: ARCHITECTURE');
+
+describe('a scenario and the algorithm that claims it can be traced to each other (PR-003)', () => {
+  test('P1 — Phase 3 gives every acceptance scenario an ID of a stated form', () => {
+    const block = phase3(read());
+    assert.match(block, /\[SC-<story-id>-1\]/,
+      'the ID must appear IN the template, so its form is unambiguous rather than described');
+    assert.match(block, /`SC-<US-id>-<n>`/, 'and the form must be stated');
+    // Cross-family QE: <story-id> had no definition and no uniqueness rule, so two scenarios could
+    // end up with the same name and a trace would point at either.
+    assert.match(block, /`US-<nnn>` — three digits, assigned in order, never reused/,
+      'the story id must be DEFINED, with a uniqueness rule, or the scenario id is not well-formed');
+    assert.match(block, /the scenarios of `US-007` are `SC-US-007-1`/,
+      'and shown worked once, so the composition is unambiguous');
+    assert.match(block, /nothing to trace to if a scenario has no\s+name/,
+      'and WHY, or a later editor drops the ID as noise');
+  });
+
+  test('P2 — Phase 4 algorithms declare what they realise, where they are written', () => {
+    const block = phase4(read());
+    // Structural, not textual: between the algorithm heading and its INPUT line. Cross-family QE
+    // noted the first version only proved the string occurs somewhere in the phase.
+    const at = block.indexOf('### Algorithm: [Name]');
+    assert.ok(at > 0, 'the algorithm template must exist');
+    const algo = block.slice(at, block.indexOf('COMPLEXITY', at));
+    assert.match(algo, /REALISES: \[SC-… ids this algorithm implements/,
+      'the declaration must sit in the algorithm block itself, not in a table someone must remember');
+    assert.ok(algo.indexOf('REALISES') < algo.indexOf('INPUT:'),
+      'and beside INPUT/OUTPUT where the algorithm is written, not appended after it');
+  });
+
+  test('P3 — the reconciliation is INSIDE Phase 4 and OUTSIDE the [MANUAL] CP4 block', () => {
+    // Placement is the property, twice over. A step after Phase 4 reconciles nothing in time; a step
+    // inside the fenced [MANUAL] block is skipped by an AUTO run, so a "mandatory" step would run in
+    // half of runs. The sibling Phase-5 feature shipped that exact defect and had it caught in
+    // review — "precedes the checkpoint text" and "outside the MANUAL-only block" are two different
+    // facts, and only the second one is the property.
+    const src = read();
+    const block = phase4(src);
+    const step = block.indexOf('**Шаг 4.9 — ПОКРЫТИЕ СЦЕНАРИЕВ');
+    const manual = block.indexOf('**[MANUAL] CP4:**');
+    assert.ok(step > 0, 'the coverage step must live inside Phase 4');
+    assert.ok(manual > step,
+      'and BEFORE the manual checkpoint block, not after it: ' + step + ' vs ' + manual);
+    // NOTE: an earlier version added a "not inside the fenced block" assertion here. It was VACUOUS
+    // — the fence is located FROM `manual`, so after `manual > step` the step cannot be inside it.
+    // Cross-family QE caught it. The assertion above is the real guard, and the mutation that moves
+    // the step into the fenced block turns it red, which is the evidence that matters.
+  });
+
+  test('P4 — a Scenario Coverage block is required in EVERY case, including all-covered', () => {
+    const block = phase4(read());
+    assert.match(block, /## Scenario Coverage/,
+      'the required output block must be named, or "reconcile" is advice');
+    assert.match(block, /in every\s+case, including the one where everything is covered/,
+      'an absent block and a block saying "all covered" are indistinguishable to the next reader');
+    assert.match(block, /Not claimed by any algorithm:/,
+      'and the uncovered scenarios must be listed, not summarised as a count');
+    // Cross-family QE: the check ran ONE WAY. An algorithm could declare REALISES for a scenario
+    // nobody ever wrote, and the dangling reference reads exactly like coverage.
+    assert.match(block, /Claimed by an algorithm but absent from Specification\.md:/,
+      'traceability must run both ways, or a dangling REALISES passes as coverage');
+    assert.match(block, /Both tables are required, and both may be the single word `none`/,
+      'and the empty case must be written out — an empty table and a forgotten one look identical');
+  });
+
+  test('P5 — the reason vocabulary is CLOSED, and the two escape hatches are rejected by name', () => {
+    const block = phase4(read());
+    const expected = ['ui-only', 'external-service', 'out-of-mvp-scope', 'data-only', 'config-only'];
+    for (const reason of expected) {
+      assert.ok(block.includes('`' + reason + '`'),
+        'the closed list must carry the reason: ' + reason);
+    }
+    assert.match(block, /CLOSED list of five/, 'and declare itself closed, with its size');
+    // CLOSED means closed: the first version asserted the values exist and let a sixth in silently.
+    // The count is the property, and it must agree with the stated size.
+    const at = block.indexOf('CLOSED list of five');
+    const table = block.slice(at, block.indexOf('Free text is NOT a reason', at));
+    const rows = table.split('\n').filter((l) => /^\| `[a-z-]+` \|/.test(l));
+    assert.equal(rows.length, expected.length,
+      'the reason table must have exactly the stated number of rows: ' + JSON.stringify(rows));
+    // Without these two named, "free text" creeps back as the default and the list means nothing.
+    assert.match(block, /Free text is NOT a reason, and `N\/A` is NOT a reason/,
+      'the two ways this field gets emptied must be rejected by name');
+    assert.match(block, /A field that accepts anything records nothing/,
+      'with the reason, so the rejection survives an editor who finds it unfriendly');
+  });
+
+  test('P6 — the template states its own limit', () => {
+    // The load-bearing honesty. A traceability block LOOKS like proof of implementation, and the
+    // field report's actual complaint is gaps closed with paperwork — which this cannot detect.
+    const block = phase4(read());
+    assert.match(block, /It does NOT establish that the algorithm's steps actually perform the check/,
+      'the limit must be written into the artifact, not only into the feature\'s own report');
+    assert.match(block, /nobody wrote anything about this\s+scenario/,
+      'and the class it DOES catch must be named, so the claim is bounded on both sides');
+  });
+
+  test('P7 — the phase order is still S→P→A→R→C', () => {
+    // Regression guard on the file this edits: the skill is named sparc-prd-mini and its phases are
+    // the acronym. A reorder would leave it claiming a methodology it no longer follows.
+    const src = read();
+    const order = ['### Phase 3: SPECIFICATION', '### Phase 4: PSEUDOCODE',
+      '### Phase 5: ARCHITECTURE', '### Phase 6: REFINEMENT', '### Phase 7: COMPLETION'];
+    let prev = -1;
+    for (const h of order) {
+      const at = src.indexOf(h);
+      assert.ok(at > prev, 'phases must appear in SPARC order; out of place: ' + h);
+      prev = at;
+    }
+  });
+});

package/tests/unit/statusline-honest-labels.test.js

@@ -0,0 +1,178 @@
+'use strict';
+
+// Two ways the status line said something untrue, both reproduced before the fix.
+//
+// 1. The progress bar was built from done/total and captioned `mvp`, with `Done x/y` rendered
+//    separately beside it — one glyph, two different quantities, read as one statement.
+//
+// 2. The domain regexes had no word boundaries, so ordinary sentences picked a domain:
+//      "Run healthchecks before deploy"  → healthcare   (`health` inside `healthchecks`)
+//      "We translate the UI"             → enterprise   (`sla` inside `tranSLAte`)
+//      "A slack bot for standups"        → enterprise   (`sla` inside `SLAck`)
+//      "Embankment mapping service"      → banking      (`bank` inside `emBANKment`)
+//    All four expressions were affected.
+//
+// THE TRAP, and it is why P3/P4 exist: `\b` is not the fix. It is defined over \w = [A-Za-z0-9_], so
+// there is no word boundary between a space and a Cyrillic letter — MEASURED, /\bбанк/.test('банк
+// России') is FALSE. A reflex `\b` fix would have silently deleted every Russian term while looking
+// correct in review. The boundaries are Unicode lookarounds with the `u` flag.
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = 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 HOOK = path.join(TPL, 'hooks', 'statusline.cjs');
+const STRIP = new RegExp('\\x1b\\[[0-9;]*m', 'g');
+
+/** Run the REAL hook over a project whose CLAUDE.md says `text`, return its plain output. */
+function render(opts) {
+  const o = opts || {};
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-labels-')));
+  try {
+    fs.mkdirSync(path.join(root, '.claude', 'hooks'), { recursive: true });
+    fs.copyFileSync(HOOK, path.join(root, '.claude', 'hooks', 'statusline.cjs'));
+    if (o.claudeMd !== undefined) fs.writeFileSync(path.join(root, 'CLAUDE.md'), o.claudeMd);
+    // The Domain segment lives INSIDE the Roadmap line, so a domain fixture needs a roadmap too —
+    // without one the hook takes its "no roadmap yet" branch and never renders a domain at all.
+    if (o.features === undefined && o.claudeMd !== undefined) {
+      o.features = [{ id: 'a', status: 'next', priority: 'mvp' }];
+    }
+    if (o.features) {
+      fs.writeFileSync(path.join(root, '.claude', 'feature-roadmap.json'),
+        JSON.stringify({ version: '1.0', features: o.features }));
+    }
+    const r = spawnSync(process.execPath, [path.join(root, '.claude', 'hooks', 'statusline.cjs')],
+      { cwd: root, env: Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: root }),
+        encoding: 'utf8' });
+    return { code: r.status, text: (r.stdout || '').replace(STRIP, '') };
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+}
+
+const domainOf = (text) => {
+  const m = text.match(/Domain:\s*(\S+)/);
+  return m ? m[1] : null;
+};
+
+/** The source of parseDomain, for the assertions that must look at the expressions themselves. */
+function parseDomainSource() {
+  const src = fs.readFileSync(HOOK, 'utf-8');
+  const start = src.indexOf('function parseDomain');
+  const end = src.indexOf('\nfunction ', start + 1);
+  assert.ok(start > 0 && end > start, 'parseDomain must exist');
+  return src.slice(start, end);
+}
+
+describe('the status line says what it means (PR-011, two small fixes)', () => {
+  test('P1 — ordinary sentences no longer pick a domain', () => {
+    // Each case is the EXACT sentence that produced the false positive, so a future edit that
+    // half-fixes one term is visible rather than averaged away.
+    const cases = [
+      ['Run healthchecks before deploy', 'health inside healthchecks'],
+      ['We translate the UI into three languages', 'sla inside translate'],
+      ['A slack bot for standups', 'sla inside slack'],
+      ['Embankment mapping service', 'bank inside embankment'],
+      ['Translation memory service', 'sla again'],
+      // Cross-family QE counter-examples: a left-only boundary was not enough for the Russian stems.
+      ['Сервис организации банкетов под ключ', 'банк inside банкетов'],
+      ['Финты в футболе: разбор техники', 'финт inside финты'],
+      ['ЦБС городской библиотеки', 'цб inside ЦБС — a two-letter acronym cannot be made safe'],
+      ['Video conversion service', 'bare conversion is not commerce'],
+    ];
+    for (const [text, why] of cases) {
+      const r = render({ claudeMd: '# Project\n\n' + text + '\n' });
+      assert.equal(r.code, 0, 'the status line must never fail the session');
+      assert.equal(domainOf(r.text), null,
+        'still matched (' + why + '): ' + JSON.stringify(text) + ' → ' + domainOf(r.text));
+    }
+  });
+
+  test('P2 — real domains are still detected, Cyrillic stems included', () => {
+    // The half a reflex `\b` fix would have deleted. Every Cyrillic entry here is a STEM meant to
+    // match its inflections, so it must keep matching them.
+    const cases = [
+      ['Мобильный банк для МСБ', 'banking'],
+      ['Финтех-стартап', 'banking'],
+      ['A healthcare records system', 'healthcare'],
+      ['Клиника на 40 врачей', 'healthcare'],
+      ['Retail analytics platform', 'retail'],
+      ['Рекомендательная система товаров', 'retail'],
+      ['Enterprise SLA dashboard', 'enterprise'],
+      // Cross-family QE: these were MISSED by the first version — a fix that loses true positives
+      // trades one wrong answer for another.
+      ['Retailer inventory analytics', 'retail'],
+      ['Health tech startup', 'healthcare'],
+      ['Platform for enterprises', 'enterprise'],
+      ['Улучшаем конверсию воронки', 'retail'],
+      ['Банковское приложение', 'banking'],
+    ];
+    for (const [text, expected] of cases) {
+      const r = render({ claudeMd: '# Project\n\n' + text + '\n' });
+      assert.equal(domainOf(r.text), expected,
+        JSON.stringify(text) + ' should be ' + expected + ', got ' + domainOf(r.text));
+    }
+  });
+
+  test('P3 — no domain expression uses \\b', () => {
+    // Asserted on the source because `\b` fails SILENTLY around Cyrillic: it does not error, it just
+    // stops matching, and every Russian term would vanish while the code looked right.
+    // Comments stripped first: the comment above these expressions EXPLAINS why \b is wrong and
+    // therefore contains it. A mention is not a use — the same trap this suite has hit before.
+    const code = parseDomainSource().split('\n').filter((l) => !/^\s*\/\//.test(l)).join('\n');
+    assert.ok(!/\\b/.test(code),
+      '\\b is not a word boundary around Cyrillic in JavaScript — /\\bбанк/.test("банк России") is '
+      + 'false. Use a Unicode lookaround.');
+  });
+
+  test('P4 — the boundaries are Unicode lookarounds with the u flag', () => {
+    const src = parseDomainSource();
+    assert.match(src, /\(\?<!\[\\\\p\{L\}\\\\p\{N\}\]\)/,
+      'a left boundary over Unicode letters is required');
+    assert.match(src, /\(\?!\[\\\\p\{L\}\\\\p\{N\}\]\)/,
+      'and a right boundary for whole words');
+    assert.match(src, /'iu'/, "and the `u` flag, or \\p{L} is not a property escape at all");
+    // The stem/word distinction is the reason the Cyrillic half survives; losing it would take the
+    // inflections with it.
+    assert.match(src, /const stem = /, 'stems take a left boundary only');
+    assert.match(src, /const word = /, 'whole words take both');
+    // Cross-family QE: the helpers being DECLARED proves nothing — dead declarations plus one 'iu'
+    // token satisfied the assertions above while an unbounded /conversion/i survived beside them.
+    // Every domain expression must be BUILT by one of the two helpers.
+    const built = [...src.matchAll(/const (\w+) = (stem|word)\(/g)].map((m) => m[1]);
+    assert.ok(built.length >= 6,
+      'each domain must be built by stem() or word(): found ' + JSON.stringify(built));
+    const raw = [...src.matchAll(/const (\w+(?:Stem|Word)) = \//g)].map((m) => m[1]);
+    assert.deepEqual(raw, [],
+      'these are raw regex literals, bypassing the boundary helpers: ' + JSON.stringify(raw));
+  });
+
+  test('P5 — the bar is captioned with what it draws', () => {
+    const r = render({ features: [
+      { id: 'a', status: 'done', priority: 'mvp' },
+      { id: 'b', status: 'next', priority: 'mvp' },
+      { id: 'c', status: 'next', priority: 'low' },
+    ] });
+    const line = r.text.split('\n').find((l) => l.includes('Roadmap')) || '';
+    assert.match(line, /\[[●○]+\]\s+Done\s+1\/3/,
+      'the bar is built from done/total, so Done is its caption: ' + line);
+    assert.match(line, /mvp\s+1\/2/, 'and mvp keeps its own segment: ' + line);
+    assert.ok(!/\[[●○]+\]\s+mvp/.test(line),
+      'the bar must not be captioned with a quantity it does not draw: ' + line);
+  });
+
+  test('P6 — with no MVP features the bar is still rendered', () => {
+    // The field report proposed hiding the bar when mvpTotal === 0. The bar is CORRECT; hiding a
+    // working indicator to mask a wrong caption fixes the wrong half.
+    const r = render({ features: [
+      { id: 'a', status: 'done', priority: 'low' },
+      { id: 'b', status: 'next', priority: 'low' },
+    ] });
+    const line = r.text.split('\n').find((l) => l.includes('Roadmap')) || '';
+    assert.match(line, /\[[●○]+\]/, 'the bar must survive an mvp count of zero: ' + line);
+    assert.match(line, /Done\s+1\/2/, 'and still report the real progress: ' + line);
+    assert.match(line, /mvp\s+0\/0/, 'while the mvp segment says plainly that there are none');
+  });
+});

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

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