@dzhechkov/p-replicator 1.10.4 → 1.13.1

package/tests/unit/detection-ladder-contract.test.js

@@ -0,0 +1,302 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const Module = require('node:module');
+const os = require('node:os');
+const path = require('node:path');
+const { Worker } = require('node:worker_threads');
+
+const PKG_DIR = path.resolve(__dirname, '..', '..');
+const RULE_DIR = path.join(PKG_DIR, 'templates', '.claude', 'rules');
+const RULE_FILE = 'cost-of-detection-ladder.md';
+const RULE_PATH = path.join(RULE_DIR, RULE_FILE);
+const TEST_PATH = 'tests/unit/detection-ladder-contract.test.js';
+const CLI = path.join(PKG_DIR, 'bin', 'cli.js');
+
+const read = (file) => fs.readFileSync(file, 'utf8');
+
+function npmPackDryRunFiles() {
+  const npmCli = process.env.npm_execpath && fs.existsSync(process.env.npm_execpath)
+    ? process.env.npm_execpath
+    : path.join(
+      path.dirname(require.resolve('npm/package.json', { paths: Module.globalPaths })),
+      'bin',
+      'npm-cli.js');
+  const cache = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-npm-pack-cache-'));
+
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+    const worker = new Worker(`
+      const { workerData } = require('node:worker_threads');
+      process.argv = ['node', 'npm', 'pack', workerData.pkgDir, '--dry-run', '--json'];
+      process.env.npm_config_cache = workerData.cache;
+      require(workerData.npmCli);
+    `, {
+      eval: true,
+      workerData: { npmCli, pkgDir: PKG_DIR, cache },
+      stdout: true,
+      stderr: true,
+    });
+    worker.stdout.setEncoding('utf8');
+    worker.stderr.setEncoding('utf8');
+    worker.stdout.on('data', (chunk) => { stdout += chunk; });
+    worker.stderr.on('data', (chunk) => { stderr += chunk; });
+    worker.once('error', (error) => {
+      fs.rmSync(cache, { recursive: true, force: true });
+      reject(error);
+    });
+    worker.once('exit', (code) => {
+      fs.rmSync(cache, { recursive: true, force: true });
+      if (code !== 0) {
+        reject(new Error(`npm pack --dry-run --json exited ${code}: ${stderr}`));
+        return;
+      }
+      try {
+        const result = JSON.parse(stdout);
+        resolve(result[0].files.map((entry) => entry.path));
+      } catch (error) {
+        reject(new Error(`npm pack --dry-run --json returned invalid JSON: ${error.message}`));
+      }
+    });
+  });
+}
+
+function ladderProblems(text) {
+  const problems = [];
+  const layers = [
+    /### Layer 1 — Deterministic test, CI check, or static guard/i,
+    /### Layer 2 — Always-loaded governance/i,
+    /### Layer 3 — Pipeline gate/i,
+    /### Layer 4 — Skill or reviewer judgment/i,
+    /### Layer 5 — Agent memory or informal recall/i,
+  ];
+  let previous = -1;
+  for (const layer of layers) {
+    const index = text.search(layer);
+    if (index < 0) problems.push(`missing ${layer}`);
+    if (index >= 0 && index <= previous) problems.push(`out of order ${layer}`);
+    previous = Math.max(previous, index);
+  }
+  if (!/strongest layer that can reliably express the property/i.test(text)) {
+    problems.push('missing strongest-capable-layer rule');
+  }
+  if (!/critic\/reviewer will catch it/i.test(text)) {
+    problems.push('missing critic/reviewer anti-pattern');
+  }
+  if (!/deterministic propert(?:y|ies)[\s\S]{0,180}(?:must not|never)[\s\S]{0,120}probabilistic review/i.test(text)) {
+    problems.push('anti-pattern does not protect deterministic properties');
+  }
+  return problems;
+}
+
+function bookReinforcementProblems(text) {
+  const problems = [];
+  const mappings = [
+    /Static structure or format\s*\|\s*Static check or deterministic test/i,
+    /Local behavior\s*\|\s*Unit test/i,
+    /Component interaction\s*\|\s*Integration or contract test/i,
+    /Behavior over time\s*\|\s*Monitor with a defined threshold or invariant/i,
+    /Runtime quantity\s*\|\s*Metric and threshold alert/i,
+    /Discrete transition\s*\|\s*Event or audit check/i,
+    /Failure resilience\s*\|\s*Controlled fault injection/i,
+    /Semantic or adversarial property\s*\|\s*Independent model-backed review gate/i,
+  ];
+  if (!/check kind and enforcement layer are separate axes/i.test(text)) {
+    problems.push('missing two-axis decision');
+  }
+  for (const mapping of mappings) {
+    if (!mapping.test(text)) problems.push(`missing signal mapping ${mapping}`);
+  }
+  if (!/\| Cause \/ property \| Observable signal \| Check kind \| Layer \| Trigger \/ cadence \| Reaction \| Owner \|/i.test(text)) {
+    problems.push('missing closed-loop Reaction column');
+  }
+  if (!/Reaction must name a concrete action/i.test(text)) {
+    problems.push('Reaction is not mandatory and concrete');
+  }
+  if (!/block or return the change|repair the practice|revisit the decision/i.test(text)) {
+    problems.push('missing concrete reaction choices');
+  }
+  return problems;
+}
+
+function privateMarkerHits(text) {
+  const markers = [
+    /dz-harness-hub/i,
+    /\/home\/dz-projects-2026/i,
+    /packages\/@dzhechkov/i,
+    /\.claude\/rules\/feature-adr-conventions\.md/i,
+    /harness-core|harness-cli|health-advisor/i,
+    /\bdz guard\b/i,
+    /\bfeatures\//i,
+    /claim-check|discrimination-check|amendment gate|fa-improvements/i,
+  ];
+  return markers.filter((marker) => marker.test(text)).map(String);
+}
+
+function backlinkProblems(ruleDir) {
+  const allusion = /cost.of.detection|strongest.*layer|layer [1-5]|слой [1-5]|лестниц/i;
+  const linked = /\[[^\]]+\]\((?:\.\/)?cost-of-detection-ladder\.md\)/i;
+  const linkLine = /\[[^\]]+\]\((?:\.\/)?cost-of-detection-ladder\.md\)/i;
+  const problems = [];
+  for (const name of fs.readdirSync(ruleDir).filter((entry) => entry.endsWith('.md'))) {
+    if (name === RULE_FILE) continue;
+    const text = read(path.join(ruleDir, name));
+    const allusionText = text
+      .split(/\r?\n/)
+      .filter((line) => !linkLine.test(line))
+      .join('\n');
+    if (allusion.test(allusionText) && !linked.test(text)) problems.push(name);
+  }
+  return problems;
+}
+
+function registryProblems(ruleDir, registryKeys) {
+  const files = fs.readdirSync(ruleDir)
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => path.basename(entry, '.md'))
+    .sort();
+  const keys = [...registryKeys].sort();
+  return files.length === keys.length && files.every((name, index) => name === keys[index])
+    ? []
+    : [`template rules ${JSON.stringify(files)} != registry ${JSON.stringify(keys)}`];
+}
+
+function runnerProblems(pkg) {
+  return ['test', 'test:unit'].filter((script) => !pkg.scripts?.[script]?.includes(TEST_PATH));
+}
+
+function packagingProblems(pkg) {
+  return pkg.files?.includes('templates/') ? [] : ['package files[] omits templates/'];
+}
+
+function scopeProblems(files) {
+  const packagePrefix = 'packages/@dzhechkov/p-replicator/';
+  const manifest = 'features/ship-detection-ladder/07_code_changes/change_manifest.md';
+  return files.filter((file) => !file.startsWith(packagePrefix) && file !== manifest);
+}
+
+test('P1 — consumer ladder preserves the ordered contract and rejects an unlinked real mention', () => {
+  const canonical = read(RULE_PATH);
+  assert.deepEqual(ladderProblems(canonical), []);
+  assert.deepEqual(backlinkProblems(RULE_DIR), []);
+
+  const withoutLayerThree = canonical.replace(
+    /\n### Layer 3 — Pipeline gate[\s\S]*?(?=\n### Layer 4)/, '');
+  assert.ok(ladderProblems(withoutLayerThree).length > 0,
+    'removing a load-bearing layer must fire the ordered-contract safeguard');
+
+  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-ladder-link-'));
+  try {
+    fs.writeFileSync(path.join(fixture, RULE_FILE), canonical);
+    fs.writeFileSync(path.join(fixture, 'unlinked-rule.md'), 'Put this safeguard on layer 3.\n');
+    assert.deepEqual(backlinkProblems(fixture), ['unlinked-rule.md'],
+      'a real unlinked allusion must fire the backlink safeguard');
+  } finally {
+    fs.rmSync(fixture, { recursive: true, force: true });
+  }
+
+  for (const requiredRule of ['skill-interface-protocol.md', 'feature-lifecycle.md']) {
+    const withoutLink = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-ladder-required-link-'));
+    try {
+      fs.cpSync(RULE_DIR, withoutLink, { recursive: true });
+      const requiredPath = path.join(withoutLink, requiredRule);
+      fs.writeFileSync(requiredPath, read(requiredPath).replace(
+        /\[([^\]]+)\]\((?:\.\/)?cost-of-detection-ladder\.md\)/i,
+        '$1'));
+      assert.deepEqual(backlinkProblems(withoutLink), [requiredRule],
+        `removing the ADR-required link from ${requiredRule} must fire the backlink safeguard`);
+    } finally {
+      fs.rmSync(withoutLink, { recursive: true, force: true });
+    }
+  }
+});
+
+test('P2 — self-containment gate rejects a real internal-path leak fixture', () => {
+  const canonical = read(RULE_PATH);
+  assert.deepEqual(privateMarkerHits(canonical), []);
+  const leaked = canonical + '\nSee .claude/rules/feature-adr-conventions.md for details.\n';
+  assert.ok(privateMarkerHits(leaked).length > 0,
+    'the literal private conventions path must fire the self-containment safeguard');
+});
+
+test('P3 — both book-grounded decisions are recorded and reflected in the template', () => {
+  const canonical = read(RULE_PATH);
+  assert.deepEqual(bookReinforcementProblems(canonical), []);
+
+  const withoutKind = canonical.replace(
+    /\n## Choose the check kind from the signal[\s\S]*?(?=\n## )/, '');
+  assert.ok(bookReinforcementProblems(withoutKind).length > 0,
+    'removing check-kind-by-signal must fire the decision guard');
+
+  const withoutReaction = canonical.replace(
+    /\n## Close the loop with a reaction[\s\S]*?(?=\n## )/, '');
+  assert.ok(bookReinforcementProblems(withoutReaction).length > 0,
+    'removing the mandatory Reaction contract must fire the decision guard');
+});
+
+test('P4 — rule registry rejects a real orphan and fresh init ships the ladder', () => {
+  const { COMPONENTS } = require(path.join(PKG_DIR, 'src', 'utils.js'));
+  const keys = Object.keys(COMPONENTS.rules.items);
+  assert.deepEqual(registryProblems(RULE_DIR, keys), []);
+
+  const orphanDir = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-ladder-orphan-'));
+  try {
+    fs.cpSync(RULE_DIR, orphanDir, { recursive: true });
+    fs.writeFileSync(path.join(orphanDir, 'orphan.md'), '# Orphan\n');
+    assert.ok(registryProblems(orphanDir, keys).length > 0,
+      'a real orphan Markdown rule must fire the registry safeguard');
+  } finally {
+    fs.rmSync(orphanDir, { recursive: true, force: true });
+  }
+
+  assert.ok(registryProblems(RULE_DIR, keys.filter((key) => key !== 'cost-of-detection-ladder')).length > 0,
+    'a cloned registry missing the ladder slug must fire the registry safeguard');
+
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-ladder-consumer-'));
+  try {
+    execFileSync(process.execPath, [CLI, 'init'], { cwd: consumer, stdio: 'pipe' });
+    const installed = read(path.join(consumer, '.claude', 'rules', RULE_FILE));
+    assert.deepEqual(ladderProblems(installed), []);
+  } finally {
+    fs.rmSync(consumer, { recursive: true, force: true });
+  }
+});
+
+test('P5 — package runner and scope guards reject omitted and out-of-scope inputs', () => {
+  const pkg = JSON.parse(read(path.join(PKG_DIR, 'package.json')));
+  assert.deepEqual(runnerProblems(pkg), []);
+
+  for (const script of ['test', 'test:unit']) {
+    const omitted = JSON.parse(JSON.stringify(pkg));
+    omitted.scripts[script] = omitted.scripts[script].replace(TEST_PATH, '');
+    assert.deepEqual(runnerProblems(omitted), [script],
+      `removing the focused file from the ${script} runner must fire the safeguard`);
+  }
+
+  const allowed = [
+    'packages/@dzhechkov/p-replicator/templates/.claude/rules/cost-of-detection-ladder.md',
+    'features/ship-detection-ladder/07_code_changes/change_manifest.md',
+  ];
+  assert.deepEqual(scopeProblems(allowed), []);
+  assert.deepEqual(
+    scopeProblems([...allowed, 'packages/@dzhechkov/harness-cli/src/forbidden.js']),
+    ['packages/@dzhechkov/harness-cli/src/forbidden.js'],
+    'a real out-of-scope package path must fire the scope safeguard');
+});
+
+test('A2 — package files include templates and the actual npm pack listing contains the ladder', async () => {
+  const pkg = JSON.parse(read(path.join(PKG_DIR, 'package.json')));
+  assert.deepEqual(packagingProblems(pkg), []);
+  const omitted = JSON.parse(JSON.stringify(pkg));
+  omitted.files = omitted.files.filter((entry) => entry !== 'templates/');
+  assert.deepEqual(packagingProblems(omitted), ['package files[] omits templates/'],
+    'a cloned files[] without templates/ must fire the distribution safeguard');
+  const packedFiles = await npmPackDryRunFiles();
+  assert.ok(
+    packedFiles.includes(`templates/.claude/rules/${RULE_FILE}`),
+    `actual npm pack listing omits templates/.claude/rules/${RULE_FILE}`);
+});

package/tests/unit/detection-ladder-registry.test.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PKG_DIR = path.resolve(__dirname, '..', '..');
+
+test('the thirteen-rule contract retains the detection ladder', () => {
+  const { COMPONENTS } = require(path.join(PKG_DIR, 'src', 'utils.js'));
+  const rules = Object.keys(COMPONENTS.rules.items);
+  assert.equal(rules.length, 13, 'the pre-shipped contract must require thirteen rules');
+  assert.ok(rules.includes('cost-of-detection-ladder'),
+    'doctor and verify must require cost-of-detection-ladder');
+});
+
+test('P13 - PR-022 writer guards are registered for targeted mutation proof', () => {
+  const registry = JSON.parse(fs.readFileSync(
+    path.join(PKG_DIR, 'test', 'mutation-registry.json'), 'utf8'));
+  const expected = {
+    'harvest-required-writer-receipt': {
+      file: 'templates/.claude/commands/harvest.md', test: 'P1 - quick and full reject',
+    },
+    'harvest-first-write-creates-missing-carrier': {
+      file: 'templates/.claude/hooks/write-insight.cjs', test: 'P2 - writer creates',
+    },
+    'harvest-exact-repeat-is-idempotent': {
+      file: 'templates/.claude/hooks/write-insight.cjs', test: 'P2 - writer creates',
+    },
+    'session-insights-missing-is-visible': {
+      file: 'templates/.claude/hooks/session-insights.cjs', test: 'P8 - missing store triggers',
+    },
+  };
+
+  for (const [id, contract] of Object.entries(expected)) {
+    const entry = registry.entries.find((candidate) => candidate.id === id);
+    assert.ok(entry, `missing targeted mutation id ${id}`);
+    assert.equal(entry.file, contract.file, `${id} mutates the wrong production surface`);
+    assert.ok(entry.property && entry.property.length > 40,
+      `${id} needs a behavioral property, not a cosmetic label`);
+    assert.ok(entry.mutation?.find && entry.mutation?.replace,
+      `${id} needs a real source mutation selected by --only`);
+    assert.ok(Number.isInteger(entry.minFailing) && entry.minFailing >= 1,
+      `${id} must require at least one failing behavioral test`);
+    assert.match(entry.property, new RegExp(contract.test.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
+      `${id} must name the real-input confirmation test that kills it`);
+  }
+
+  assert.equal(registry.entries.filter((entry) => expected[entry.id]).length, 4,
+    'all four and only the planned PR-022 guards must resolve by exact id');
+});

package/tests/unit/doctor-insight-flow.test.js

@@ -0,0 +1,315 @@
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const CLI = path.join(PKG, 'bin', 'cli.js');
+const DOCTOR = path.join(PKG, 'src', 'commands', 'doctor.js');
+const REFERENCE_TIME = new Date(2026, 7, 30, 12, 0, 0);
+const WINDOW_DATES = ['2026-08-28', '2026-08-29', '2026-08-30'];
+
+function tempProject(prefix = 'p-rep-doctor-flow-') {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+  execFileSync(process.execPath, [CLI, 'init'], { cwd: root, stdio: 'ignore' });
+  return root;
+}
+
+function cleanup(root) {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+function git(root, args, options = {}) {
+  const result = spawnSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: options.stdio || 'pipe',
+    env: { ...process.env, ...(options.env || {}) },
+  });
+  assert.equal(result.status, 0,
+    `git ${args.join(' ')} failed: ${result.stderr || result.error || ''}`);
+  return result.stdout || '';
+}
+
+function initGit(root) {
+  git(root, ['init', '-q']);
+  git(root, ['config', 'user.name', 'P-Replicator Test']);
+  git(root, ['config', 'user.email', 'p-replicator@example.invalid']);
+}
+
+let commitSequence = 0;
+function commit(root, subject, date) {
+  commitSequence += 1;
+  fs.writeFileSync(path.join(root, `.doctor-flow-${commitSequence}.txt`), `${subject}\n${date}\n`);
+  git(root, ['add', '-A']);
+  const env = {
+    GIT_AUTHOR_DATE: `${date}T12:00:00`,
+    GIT_COMMITTER_DATE: `${date}T12:00:00`,
+  };
+  git(root, ['commit', '-qm', subject], { env });
+}
+
+function writeInsights(root, records) {
+  const index = path.join(root, '.claude', 'insights', 'index.md');
+  fs.mkdirSync(path.dirname(index), { recursive: true });
+  fs.writeFileSync(index, ['# Project Insights', '', ...records.map(({ date, title }, i) => [
+    `## ${date} — ${title}`,
+    '',
+    '**Problem:**',
+    `Problem ${i + 1}.`,
+    '',
+    '**Solution:**',
+    `Solution ${i + 1}.`,
+    '',
+    '---',
+    '',
+  ].join('\n'))].join('\n'));
+  return index;
+}
+
+function runDoctor(root) {
+  delete require.cache[require.resolve(DOCTOR)];
+  const doctor = require(DOCTOR);
+  const lines = [];
+  const originalLog = console.log;
+  const previousExitCode = process.exitCode;
+  console.log = (...args) => lines.push(args.map(String).join(' '));
+  process.exitCode = undefined;
+  try {
+    doctor({ targetDir: root, now: REFERENCE_TIME });
+    return { code: process.exitCode ?? 0, out: lines.join('\n') + '\n' };
+  } finally {
+    console.log = originalLog;
+    process.exitCode = previousExitCode;
+  }
+}
+
+function flowLines(out) {
+  return out.split('\n').filter((line) => /Insight flow/i.test(line));
+}
+
+function assertWindow(line) {
+  assert.match(line, /2026-08-28/);
+  assert.match(line, /2026-08-30/);
+}
+
+function measuredProject(prefix) {
+  const root = tempProject(prefix);
+  initGit(root);
+  commit(root, 'feat: establish project history', '2026-08-27');
+  return root;
+}
+
+describe('doctor insight-flow observation', () => {
+  test('P1 reports one shared three-day window with structural fix and insight counts', () => {
+    const root = measuredProject();
+    try {
+      commit(root, 'fix: first in-window repair', WINDOW_DATES[0]);
+      commit(root, 'fix(api): second in-window repair', WINDOW_DATES[1]);
+      commit(root, 'fix: third in-window repair', WINDOW_DATES[2]);
+      commit(root, 'feat: fix wording in documentation', WINDOW_DATES[2]);
+      commit(root, 'docs: describe fix commits', WINDOW_DATES[2]);
+      commit(root, 'fix: outside the window', '2026-08-31');
+      writeInsights(root, [
+        { date: '2026-08-27', title: 'Outside before' },
+        { date: WINDOW_DATES[0], title: 'First in window' },
+        { date: WINDOW_DATES[2], title: 'Second in window' },
+        { date: '2026-08-31', title: 'Outside after' },
+      ]);
+
+      const result = runDoctor(root);
+      const lines = flowLines(result.out);
+      assert.equal(lines.length, 1, result.out);
+      assertWindow(lines[0]);
+      assert.match(lines[0], /3 fix commits/);
+      assert.match(lines[0], /2 insight records/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P2 reports A1 no repository as not performed without changing exit code', () => {
+    const root = tempProject();
+    try {
+      const result = runDoctor(root);
+      const lines = flowLines(result.out);
+      assert.equal(lines.length, 1, result.out);
+      assert.match(lines[0], /check NOT performed/);
+      assert.match(lines[0], /not a git repository/);
+      assert.doesNotMatch(lines[0], /0 fix commits/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P3 reports A2 no readable history as not performed without changing exit code', () => {
+    const root = tempProject();
+    try {
+      initGit(root);
+      const result = runDoctor(root);
+      const lines = flowLines(result.out);
+      assert.equal(lines.length, 1, result.out);
+      assert.match(lines[0], /check NOT performed/);
+      assert.match(lines[0], /no readable git history/);
+      assert.doesNotMatch(lines[0], /0 fix commits/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P4 treats A3 missing insights carrier as measured zero', () => {
+    const root = measuredProject();
+    try {
+      commit(root, 'fix: measured without a carrier', WINDOW_DATES[1]);
+      const result = runDoctor(root);
+      const line = flowLines(result.out)[0] || '';
+      assertWindow(line);
+      assert.match(line, /1 fix commit(?:s)?/);
+      assert.match(line, /0 insight records/);
+      assert.doesNotMatch(line, /NOT performed/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P5 treats A4 zero fix commits as measured zero', () => {
+    const root = measuredProject();
+    try {
+      commit(root, 'feat: in-window non-fix work', WINDOW_DATES[1]);
+      writeInsights(root, [{ date: WINDOW_DATES[1], title: 'One measured insight' }]);
+      const result = runDoctor(root);
+      const line = flowLines(result.out)[0] || '';
+      assertWindow(line);
+      assert.match(line, /0 fix commits/);
+      assert.match(line, /1 insight record(?:s)?/);
+      assert.doesNotMatch(line, /NOT performed/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P6 keeps claimant-shaped 19/0 evidence neutral and non-gating', () => {
+    const root = measuredProject();
+    try {
+      for (let i = 1; i <= 19; i += 1) {
+        commit(root, `fix: claimant-shaped repair ${i}`, WINDOW_DATES[(i - 1) % 3]);
+      }
+      const result = runDoctor(root);
+      const lines = flowLines(result.out);
+      assert.equal(lines.length, 1, result.out);
+      assertWindow(lines[0]);
+      assert.match(lines[0], /19 fix commits/);
+      assert.match(lines[0], /0 insight records/);
+      assert.doesNotMatch(lines[0], /healthy|clean|few|warning|problem|broken|unused|capture/i);
+      assert.doesNotMatch(lines[0], /[✓✗⚠!]/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P7 re-reads git and insights on each invocation', () => {
+    const root = measuredProject();
+    try {
+      commit(root, 'fix: first live repair', WINDOW_DATES[0]);
+      const index = writeInsights(root,
+        [{ date: WINDOW_DATES[0], title: 'First live insight' }]);
+      const first = flowLines(runDoctor(root).out)[0] || '';
+      assert.match(first, /1 fix commit(?:s)?/);
+      assert.match(first, /1 insight record(?:s)?/);
+
+      commit(root, 'fix(core): second live repair', WINDOW_DATES[2]);
+      fs.appendFileSync(index, [
+        `## ${WINDOW_DATES[2]} — Second live insight`,
+        '',
+        '**Problem:** Changed after the first doctor run.',
+        '',
+        '**Solution:** Read the carrier again.',
+        '',
+      ].join('\n'));
+      const second = flowLines(runDoctor(root).out)[0] || '';
+      assert.match(second, /2 fix commits/);
+      assert.match(second, /2 insight records/);
+    } finally { cleanup(root); }
+  });
+
+  test('P8 reports an unreadable insight carrier as not performed', () => {
+    const root = measuredProject();
+    try {
+      commit(root, 'fix: carrier failure remains unknown', WINDOW_DATES[1]);
+      const index = path.join(root, '.claude', 'insights', 'index.md');
+      fs.mkdirSync(index, { recursive: true });
+      const result = runDoctor(root);
+      const line = flowLines(result.out)[0] || '';
+      assert.match(line, /check NOT performed/);
+      assert.match(line, /insight carrier.*unreadable/i);
+      assert.doesNotMatch(line, /insight records/);
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+
+  test('P9 preserves existing zero and nonzero doctor exits across flow states', () => {
+    for (const broken of [false, true]) {
+      const root = tempProject();
+      try {
+        if (broken) {
+          fs.rmSync(path.join(root, '.claude', 'rules', 'docker-ports.md'));
+        }
+        const expected = broken ? 1 : 0;
+        const noRepository = runDoctor(root);
+        assert.equal(noRepository.code, expected, noRepository.out);
+        assert.match(flowLines(noRepository.out)[0] || '', /NOT performed/);
+
+        initGit(root);
+        commit(root, 'fix: measured state', WINDOW_DATES[1]);
+        const measured = runDoctor(root);
+        assert.equal(measured.code, expected, measured.out);
+        assert.match(flowLines(measured.out)[0] || '', /1 fix commit(?:s)?/);
+
+        const index = path.join(root, '.claude', 'insights', 'index.md');
+        fs.mkdirSync(index, { recursive: true });
+        const unavailable = runDoctor(root);
+        assert.equal(unavailable.code, expected, unavailable.out);
+        assert.match(flowLines(unavailable.out)[0] || '', /NOT performed/);
+      } finally { cleanup(root); }
+    }
+  });
+
+  test('P10 package scripts include the doctor insight-flow suite', () => {
+    const pkg = require(path.join(PKG, 'package.json'));
+    for (const name of ['test', 'test:unit']) {
+      const occurrences = pkg.scripts[name]
+        .split('doctor-insight-flow.test.js').length - 1;
+      assert.equal(occurrences, 1, `${name} must run the suite exactly once`);
+    }
+  });
+
+  test('P11 README describes the doctor insight-flow observation as informational and non-gating', () => {
+    const readme = fs.readFileSync(path.join(PKG, 'README.md'), 'utf8');
+    const start = readme.indexOf('### Doctor insight-flow observation');
+    const end = readme.indexOf('\n### ', start + 1);
+    assert.ok(start >= 0 && end > start, 'README must contain a bounded doctor insight-flow section');
+    const section = readme.slice(start, end);
+    assert.match(section, /three calendar days/i);
+    assert.match(section, /git history/i);
+    assert.match(section, /\.claude\/insights\/index\.md/);
+    assert.match(section, /fix commits[\s\S]*insight records/i);
+    assert.match(section, /check NOT performed/);
+    assert.match(section, /does not change[^.]*exit status/i);
+    assert.match(section, /does not interpret|no threshold/i);
+    assert.doesNotMatch(section, /19\s+fix|0\s+insight/i,
+      'claimant field figures are not locally reproduced product evidence');
+  });
+
+  test('P12 uses argument-array git execution for metacharacter paths and subjects', () => {
+    const root = measuredProject('p rep ; touch P12_SIDE_EFFECT ; ');
+    try {
+      commit(root, 'fix(shell): $(touch P12_SUBJECT_SIDE_EFFECT)', WINDOW_DATES[1]);
+      const result = runDoctor(root);
+      const line = flowLines(result.out)[0] || '';
+      assert.match(line, /1 fix commit(?:s)?/);
+      assert.equal(fs.existsSync(path.join(root, 'P12_SIDE_EFFECT')), false,
+        'targetDir metacharacters must never reach a shell');
+      assert.equal(fs.existsSync(path.join(root, 'P12_SUBJECT_SIDE_EFFECT')), false,
+        'commit subjects are data, never executable text');
+      assert.equal(result.code, 0, result.out);
+    } finally { cleanup(root); }
+  });
+});