@dzhechkov/p-replicator 1.10.4 → 1.12.0

package/tests/unit/insights-docs-tell-the-truth.test.js

@@ -1,26 +1,19 @@
 'use strict';
 
-// Two shipped documents promised something the hook does not do — and, as written, CANNOT do.
-//
-// `myinsights.md` said insights are injected "when their tags match the current task". The hook
-// runs on SessionStart, BEFORE the user has said anything, so there is no current task to match
-// tags against. MEASURED: `session-insights.cjs:33` is `sections.slice(-3)` — the last three by
-// file order, and no tag matching exists anywhere in the package.
-//
-// The hook's own printed heading, "Recent project insights", was already honest. Only the documents
-// around it were not.
-//
-// This test exists because a promise removed from prose comes back. It pins the CODE and the DOC to
-// each other: if selection ever becomes relevance-based, this test is where the doc must change too.
-
 const { test, describe } = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
 const TPL = path.join(__dirname, '..', '..', 'templates', '.claude');
+const PKG = path.join(__dirname, '..', '..');
 const CMD = path.join(TPL, 'commands', 'myinsights.md');
 const HOOK = path.join(TPL, 'hooks', 'session-insights.cjs');
+const RULE = path.join(TPL, 'rules', 'insights-capture.md');
+const HARVEST = path.join(TPL, 'commands', 'harvest.md');
+const README = path.join(PKG, 'README.md');
+const API_EN = path.join(PKG, 'README', 'eng', '04_api_reference.md');
+const API_RU = path.join(PKG, 'README', 'ru', '04_api_reference.md');
 
 const read = (f) => fs.readFileSync(f, 'utf-8');
 /** Prose with code fences and comments removed — a MENTION of a claim is not the claim. */
@@ -40,12 +33,13 @@ describe('the insights documents describe the hook that exists', () => {
 
   test('P2 - the document states what the hook actually selects', () => {
     const doc = read(CMD);
-    assert.match(doc, /three most recent/i, 'the real selection must be named');
-    assert.match(doc, /by their\s*\n?order in the file/i, 'and how it is ordered');
-    assert.match(doc, /There is no tag matching, and it is not an omission/,
-      'and WHY there is none, or a future reader files it as a bug');
-    assert.match(doc, /BEFORE you have said anything/,
-      'the reason must be the timing, which is the load-bearing fact');
+    assert.match(doc, /UserPromptSubmit/, 'selection must occur after the real prompt exists');
+    assert.match(doc, /successful,? non-empty.*dz recall/is,
+      'the value-armed recall condition must be named');
+    assert.match(doc, /falls back.*three most recent/is,
+      'the local last-three fallback must remain visible');
+    assert.match(doc, /only.*suppresses.*local/is,
+      'binary presence alone must not read as readiness');
   });
 
   test('P3 - the code and the doc agree, asserted against the CODE', () => {
@@ -60,25 +54,52 @@ describe('the insights documents describe the hook that exists', () => {
   });
 
   test('P4 - the consequence of last-three is stated, not left to be discovered', () => {
-    // The file is append-only and the hook takes the last three, so a long-lived project stops
-    // seeing its earlier entries. insights-capture.md plans for 50+.
     const doc = read(CMD);
     assert.match(doc, /append-only/, 'the growth behaviour must be named');
-    assert.match(doc, /earlier ones stop being injected/,
+    assert.match(doc, /fallback.*earlier ones stop being injected/is,
       'and its consequence, in plain words');
-    const rule = read(path.join(TPL, 'rules', 'insights-capture.md'));
+    const rule = read(RULE);
     assert.match(rule, /50 entries|> 50/,
       'the rule really does plan for a size the hook cannot show — that is the point');
   });
 
-  test('P5 - the /harvest link is described as an intention, not a wired path', () => {
-    // MEASURED: `grep -ci insight` over harvest.md returns 0. The command promised harvest
-    // "extracts reusable patterns from insights", which nothing does.
+  test('P5 - /harvest and /myinsights name their executable shared-carrier contract', () => {
     const doc = read(CMD);
-    assert.match(doc, /does\s*\n?\s*NOT read `\.claude\/insights\/index\.md` today/,
-      'the unwired link must be admitted where it is claimed');
-    const harvest = read(path.join(TPL, 'commands', 'harvest.md'));
-    assert.equal((harvest.match(/insight/gi) || []).length, 0,
-      'if harvest ever DOES read insights, this admission must be removed — that is the trigger');
+    const harvest = read(HARVEST);
+    assert.doesNotMatch(doc, /does\s*\n?\s*NOT read `\.claude\/insights\/index\.md` today/,
+      'the old unwired admission became false once harvest acquired a writer');
+    assert.match(doc, /share the same Markdown carrier/i,
+      'manual and harvest capture must be described as one carrier, not two stores');
+    assert.match(harvest, /REQUIRED INSIGHT PERSISTENCE GATE/,
+      'the relationship must be executable wiring, not a prose aspiration');
+    assert.match(harvest, /\.claude\/hooks\/write-insight\.cjs/,
+      'the shipped writer boundary must be named exactly');
+    assert.match(harvest, /\.claude\/insights\/index\.md/,
+      'the command and /myinsights must converge on the same Markdown source of truth');
+    assert.match(harvest, /Only `created`, `appended`, or `duplicate`/,
+      'normal completion must be bound to the three canonical writer receipts');
+    assert.match(harvest, /writer exits non-zero.*MUST NOT\s+report.*completed/is,
+      'an unestablished write must remain a blocking harvest outcome');
+  });
+
+  test('P6 - docs describe prompt-time armed recall and Markdown authority', () => {
+    const hook = read(HOOK);
+    assert.match(hook, /recall\.kind === 'ok'/,
+      'the docs cannot claim armed recall without the production predicate');
+    assert.doesNotMatch(hook, /command\s+-v\s+dz/,
+      'binary discovery must not become the suppression condition');
+
+    const docs = [read(CMD), read(RULE), read(HARVEST), read(README), read(API_EN), read(API_RU)];
+    for (const [index, doc] of docs.entries()) {
+      assert.match(doc, /Markdown/i, `behavior document ${index + 1} omits Markdown authority`);
+      assert.match(doc, /best-effort/i, `behavior document ${index + 1} omits optional teach`);
+    }
+    for (const doc of [docs[0], docs[1], docs[3], docs[4], docs[5]]) {
+      assert.match(doc, /UserPromptSubmit/, 'prompt-time delivery must be named');
+      assert.match(doc, /(?:non-empty|непуст(?:ой|ого)).*(?:recall|вывод)/is,
+        'successful non-empty output must be the documented arming condition');
+      assert.match(doc, /(?:local|локальн).*(?:fallback|фолб[эе]к)/is,
+        'absent/failing/empty recall must retain local delivery');
+    }
   });
 });

package/tests/unit/insights-dz-delegation.test.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..', '..');
+const HOOK = path.join(PKG, 'templates', '.claude', 'hooks', 'session-insights.cjs');
+const LOCAL = 'LOCAL_ONLY';
+const DZ = 'DZ_ONLY';
+
+function loadHook() {
+  delete require.cache[require.resolve(HOOK)];
+  return require(HOOK);
+}
+
+function project(prefix = 'p-rep-dz-contract-') {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+  const index = path.join(root, '.claude', 'insights', 'index.md');
+  fs.mkdirSync(path.dirname(index), { recursive: true });
+  fs.writeFileSync(index, `## 2026-08-30 — ${LOCAL}\n\nlocal body\n`);
+  return root;
+}
+
+function userPrompt(prompt = 'choose an optional dependency fallback') {
+  return JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt });
+}
+
+function runHook(root, result, rawEvent = userPrompt()) {
+  const chunks = [];
+  const runner = (_file, _args, _options) => result;
+  loadHook().emitInsights(root, { write: (chunk) => chunks.push(chunk) }, { rawEvent, runner });
+  return chunks.join('');
+}
+
+function envelope(stdout) {
+  const lines = stdout.trimEnd().split('\n');
+  assert.equal(lines.length, 1, `expected one hook envelope, got ${lines.length}: ${stdout}`);
+  const parsed = JSON.parse(lines[0]);
+  assert.equal(parsed.hookSpecificOutput.hookEventName, 'UserPromptSubmit');
+  return parsed.hookSpecificOutput.additionalContext;
+}
+
+function recalled(pattern = DZ) {
+  return {
+    status: 0,
+    stdout: JSON.stringify([{ pattern, domain: 'p-replicator-insights' }]),
+    stderr: '',
+  };
+}
+
+function absent() {
+  return { status: null, stdout: '', stderr: '', error: { code: 'ENOENT' } };
+}
+
+describe('PR-022 optional dz delivery contract', () => {
+  test('P10 - absent dz emits local only without dz error text', () => {
+    const root = project();
+    try {
+      const context = envelope(runHook(root, absent()));
+      assert.match(context, new RegExp(LOCAL));
+      assert.doesNotMatch(context, new RegExp(DZ));
+      assert.doesNotMatch(context, /dz recall (unavailable|failed)/i);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P11 - armed non-empty recall emits dz only', () => {
+    const root = project();
+    try {
+      const context = envelope(runHook(root, recalled()));
+      assert.match(context, new RegExp(DZ));
+      assert.doesNotMatch(context, new RegExp(LOCAL));
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P12 - failing or timed-out recall names degradation and emits local only', () => {
+    const root = project();
+    const failures = [
+      { status: 23, stdout: '', stderr: 'SECRET child stderr' },
+      { status: null, stdout: '', stderr: '', error: { code: 'ETIMEDOUT' }, signal: 'SIGTERM' },
+    ];
+    try {
+      for (const result of failures) {
+        const context = envelope(runHook(root, result));
+        assert.match(context, /dz recall unavailable: (exit 23|timeout); using local recent insights/i);
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+        assert.doesNotMatch(context, /SECRET child stderr/);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P13 - empty successful recall emits local only', () => {
+    const root = project();
+    const emptyResults = [
+      { status: 0, stdout: '[]', stderr: '' },
+      { status: 0, stdout: JSON.stringify([
+        { pattern: DZ, domain: 'another-domain' },
+        { pattern: '   ', domain: 'p-replicator-insights' },
+      ]), stderr: '' },
+    ];
+    try {
+      for (const result of emptyResults) {
+        const context = envelope(runHook(root, result));
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+        assert.doesNotMatch(context, /dz recall unavailable/i);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P14 - local suppression requires armed recall and never double-injects across absent/ok/failing/empty', () => {
+    const root = project();
+    const states = {
+      absent: absent(),
+      ok: recalled(),
+      failing: { status: 2, stdout: '', stderr: '' },
+      empty: { status: 0, stdout: '[]', stderr: '' },
+    };
+    try {
+      for (const [state, result] of Object.entries(states)) {
+        const context = envelope(runHook(root, result));
+        const hasLocal = context.includes(LOCAL);
+        const hasDz = context.includes(DZ);
+        assert.notEqual(hasLocal, hasDz, `${state} must select exactly one insight source`);
+        assert.equal(hasDz, state === 'ok', `${state} armedness selected the wrong source`);
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P15 - malformed successful stdout cannot arm recall', () => {
+    const root = project();
+    try {
+      for (const stdout of ['not-json', '{}']) {
+        const context = envelope(runHook(root, { status: 0, stdout, stderr: '' }));
+        assert.match(context, /dz recall unavailable: invalid (JSON|result)/i);
+        assert.match(context, new RegExp(LOCAL));
+        assert.doesNotMatch(context, new RegExp(DZ));
+      }
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P15a - prompt parsing root pin argv and output bounds survive hostile input', () => {
+    const api = loadHook();
+    for (const key of ['prompt', 'user_prompt', 'userPrompt']) {
+      assert.deepEqual(
+        api.parseHookEvent(JSON.stringify({ hook_event_name: 'UserPromptSubmit', [key]: ' task ' })),
+        { kind: 'user-prompt', prompt: 'task' },
+      );
+    }
+
+    const root = project('p rep dz contract ');
+    const calls = [];
+    try {
+      const result = api.recallFromDz('literal $(touch never) `echo never`', root, {
+        runner(file, args, options) {
+          calls.push({ file, args, options });
+          return recalled('X'.repeat(20 * 1024));
+        },
+      });
+      assert.equal(result.kind, 'ok');
+      assert.ok(Buffer.byteLength(result.context, 'utf8') <= 16 * 1024,
+        `rendered context exceeded 16 KiB: ${Buffer.byteLength(result.context, 'utf8')}`);
+      assert.equal(calls.length, 1);
+      assert.equal(calls[0].file, 'dz');
+      // The ADR's Decision pins this argv exactly, --domain included: it is a rank BOOST, and
+      // without it a shared multi-domain store buries insight records below the top-12 cut, so
+      // the armed state never fires. This assertion previously omitted the flag and therefore
+      // cemented the very gap cross-family QE found.
+      assert.deepEqual(calls[0].args, [
+        'recall', 'literal $(touch never) `echo never`', '--limit', '12',
+        '--domain', 'p-replicator-insights',
+        '--project', root, '--json',
+      ]);
+      assert.equal(calls[0].options.cwd, root);
+      assert.equal(calls[0].options.shell, false);
+      assert.equal(calls[0].options.timeout, 1500);
+      assert.equal(calls[0].options.maxBuffer, 1024 * 1024);
+
+      const oversized = api.recallFromDz('task', root, {
+        runner: () => ({ status: null, stdout: '', stderr: '', error: { code: 'ENOBUFS' } }),
+      });
+      assert.deepEqual(oversized, { kind: 'failing', reason: 'spawn ENOBUFS' });
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test('P19 - production comments contain no decision-history narration', () => {
+    for (const file of ['session-insights.cjs', 'write-insight.cjs']) {
+      const source = fs.readFileSync(path.join(PKG, 'templates', '.claude', 'hooks', file), 'utf8');
+      const comments = source.split('\n').filter((line) => /^\s*(\/\/|\/\*|\*)/.test(line)).join('\n');
+      assert.doesNotMatch(comments, /supersed|a0ea8b|cross-model|FIX-\d|AM-\d|third answer/i,
+        `${file} contains decision history that belongs in the ADR`);
+    }
+  });
+});

package/tests/unit/insights-writer.test.js

@@ -0,0 +1,285 @@
+'use strict';
+
+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 PKG = path.resolve(__dirname, '..', '..');
+const TPL = path.join(PKG, 'templates', '.claude');
+const WRITER = path.join(TPL, 'hooks', 'write-insight.cjs');
+const HARVEST = path.join(TPL, 'commands', 'harvest.md');
+const CLI = path.join(PKG, 'bin', 'cli.js');
+
+function tempProject(prefix = 'p-rep-insight-') {
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+}
+
+function cleanup(root) {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+function payload(overrides = {}) {
+  return {
+    date: '2026-08-30',
+    title: 'Anchor writes at the project root',
+    tags: ['hooks', 'project-root'],
+    problem: 'A changed working directory hid the project carrier.',
+    solution: 'Resolve the carrier from the explicit project root.',
+    references: ['templates/.claude/hooks/session-insights.cjs:19'],
+    ...overrides,
+  };
+}
+
+function runWriter(root, input, options = {}) {
+  const env = { ...process.env, PATH: options.path === undefined ? '' : options.path };
+  if (options.withEnv === false) delete env.CLAUDE_PROJECT_DIR;
+  else env.CLAUDE_PROJECT_DIR = root;
+  const writer = options.writer || WRITER;
+  return spawnSync(process.execPath, [writer], {
+    cwd: options.cwd || root,
+    env,
+    input: typeof input === 'string' ? input : JSON.stringify(input),
+    encoding: 'utf8',
+  });
+}
+
+function absentDz() {
+  return { status: null, error: { code: 'ENOENT' }, stdout: '', stderr: '' };
+}
+
+function receipt(result) {
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  return JSON.parse(result.stdout);
+}
+
+function requireWriter() {
+  assert.ok(fs.existsSync(WRITER),
+    'the packaged write-insight.cjs boundary does not exist yet');
+  delete require.cache[require.resolve(WRITER)];
+  return require(WRITER);
+}
+
+describe('PR-022 harvest insight persistence', () => {
+  test('P1 - quick and full reject a real writer failure while marker stays non-writing', () => {
+    const command = fs.readFileSync(HARVEST, 'utf8');
+    assert.match(command, /REQUIRED INSIGHT PERSISTENCE GATE/,
+      'quick/full need one named mandatory gate before their completion report');
+    assert.match(command, /write-insight\.cjs/,
+      'the command must invoke the executable persistence boundary');
+    assert.match(command, /created.*appended.*duplicate/s,
+      'only the three canonical receipts may authorize completion');
+    assert.match(command, /writer exits non-zero.*MUST NOT\s+report.*completed/is,
+      'a real persistence failure must stop the ordinary completion report');
+    assert.match(command, /marker.*does not invoke.*write-insight/is,
+      'marker requests future work and must remain non-writing');
+    assert.match(command, /no candidate.*write nothing.*capture remains\s+incomplete/is,
+      'a findings-free run must stay non-writing and may not fabricate completion');
+
+    const root = tempProject();
+    try {
+      const failed = runWriter(root, '{not-json');
+      assert.notEqual(failed.status, 0, 'malformed JSON must exercise a real writer failure');
+      assert.equal(fs.existsSync(path.join(root, '.claude', 'insights')), false,
+        'a failed candidate must not manufacture the missing carrier');
+    } finally { cleanup(root); }
+  });
+
+  test('P2 - writer creates appends preserves legacy bytes and deduplicates exact payloads', () => {
+    const { writeInsight } = requireWriter();
+    const root = tempProject();
+    try {
+      const index = path.join(root, '.claude', 'insights', 'index.md');
+      const first = writeInsight(root, payload(), { runner: absentDz });
+      assert.equal(first.status, 'created');
+      assert.equal(first.entryCount, 1);
+      const created = fs.readFileSync(index, 'utf8');
+      assert.match(created, /^## 2026-08-30 — Anchor writes at the project root/m);
+      assert.match(created, /<!-- insight-id: sha256:[a-f0-9]{64} -->/);
+
+      const distinct = payload({ title: 'Unicode path stays intact', tags: ['utf-8'],
+        problem: 'Путь с пробелами ломал запись.', solution: 'Передавать JSON через stdin.',
+        references: [] });
+      const appended = writeInsight(root, distinct, { runner: absentDz });
+      assert.equal(appended.status, 'appended');
+      assert.ok(fs.readFileSync(index, 'utf8').startsWith(created),
+        'append must preserve every already-committed byte as a prefix');
+
+      const beforeReplay = fs.readFileSync(index);
+      const duplicate = writeInsight(root, { ...distinct, date: '2026-08-31' }, { runner: absentDz });
+      assert.equal(duplicate.status, 'duplicate', 'date is not part of semantic identity');
+      assert.deepEqual(fs.readFileSync(index), beforeReplay,
+        'an exact normalized replay must perform no carrier write');
+
+      const legacyEntry = [
+        '## 2026-08-29 — Manually captured legacy record',
+        '',
+        '**Tags:** manual',
+        '',
+        '**Problem:**',
+        'This entry predates writer identity markers.',
+        '',
+        '**Solution:**',
+        'Keep every legacy byte intact.',
+        '',
+        '---',
+        '',
+      ].join('\n');
+      fs.appendFileSync(index, legacyEntry);
+      const legacyPrefix = fs.readFileSync(index);
+
+      const sameDateDistinct = writeInsight(root,
+        { ...distinct, solution: 'Use structured stdin.' }, { runner: absentDz });
+      assert.equal(sameDateDistinct.status, 'appended',
+        'same-date payloads remain distinct when a semantic field changes');
+      assert.ok(fs.readFileSync(index).subarray(0, legacyPrefix.length).equals(legacyPrefix),
+        'writer append must preserve a marker-free /myinsights legacy record byte-for-byte');
+      assert.equal(sameDateDistinct.entryCount, 4);
+    } finally { cleanup(root); }
+  });
+
+  test('P3 - CLI validates before mutation and stays project-root anchored', () => {
+    requireWriter();
+    const spaced = tempProject('p rep insight utf8 ');
+    try {
+      const nested = path.join(spaced, 'nested', 'work');
+      fs.mkdirSync(nested, { recursive: true });
+      const ok = runWriter(spaced, payload({ title: 'Путь с пробелами',
+        problem: 'Текущий каталог изменился.', solution: 'Якорь остаётся у корня.' }), { cwd: nested });
+      assert.equal(receipt(ok).status, 'created');
+      assert.ok(fs.readFileSync(path.join(spaced, '.claude', 'insights', 'index.md'), 'utf8')
+        .includes('Путь с пробелами'));
+      assert.equal(fs.existsSync(path.join(nested, '.claude')), false,
+        'cwd drift must not create a second project tree');
+    } finally { cleanup(spaced); }
+
+    const invalidCases = [
+      ['invalid JSON', '{'],
+      ['invalid calendar date', payload({ date: '2026-02-30' })],
+      ['blank required field', payload({ problem: '  ' })],
+      ['non-string array member', payload({ tags: ['ok', 3] })],
+      ['missing field', (() => { const p = payload(); delete p.references; return p; })()],
+    ];
+    for (const [name, input] of invalidCases) {
+      const root = tempProject();
+      try {
+        const result = runWriter(root, input);
+        assert.notEqual(result.status, 0, name + ' must be rejected');
+        assert.equal(fs.existsSync(path.join(root, '.claude', 'insights')), false,
+          name + ' mutated the carrier before validation completed');
+      } finally { cleanup(root); }
+    }
+
+    const broken = tempProject();
+    try {
+      fs.writeFileSync(path.join(broken, '.claude'), 'not a directory\n');
+      const result = runWriter(broken, payload());
+      assert.notEqual(result.status, 0, 'an unavailable carrier must fail loudly');
+      assert.equal(fs.readFileSync(path.join(broken, '.claude'), 'utf8'), 'not a directory\n');
+    } finally { cleanup(broken); }
+  });
+
+  test('P4 - installed writer output remains readable by the hook and doctor', () => {
+    requireWriter();
+    const root = tempProject();
+    try {
+      const init = spawnSync(process.execPath, [CLI, 'init'], { cwd: root, encoding: 'utf8' });
+      assert.equal(init.status, 0, init.stderr || init.stdout);
+      assert.equal(fs.existsSync(path.join(root, '.claude', 'insights')), false,
+        'init must preserve the legitimate pre-first-write missing state');
+
+      const installedWriter = path.join(root, '.claude', 'hooks', 'write-insight.cjs');
+      const written = runWriter(root, payload(), { writer: installedWriter });
+      assert.equal(receipt(written).status, 'created');
+
+      const hook = spawnSync(process.execPath,
+        [path.join(root, '.claude', 'hooks', 'session-insights.cjs')], {
+          cwd: path.join(root, '.claude'),
+          env: { ...process.env, PATH: '', CLAUDE_PROJECT_DIR: root },
+          input: JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt: 'anchor writes' }),
+          encoding: 'utf8',
+        });
+      assert.equal(hook.status, 0, hook.stderr);
+      assert.match(hook.stdout, /Anchor writes at the project root/);
+
+      const doctor = spawnSync(process.execPath, [CLI, 'doctor'], { cwd: root, encoding: 'utf8' });
+      assert.equal(doctor.status, 0, doctor.stderr || doctor.stdout);
+      assert.match(doctor.stdout, /insights carrier.*1 entr/i);
+    } finally { cleanup(root); }
+  });
+
+  test('P16 - Markdown success dominates absent failed and timed-out teach', () => {
+    const { writeInsight } = requireWriter();
+    const cases = [
+      ['absent', { status: null, error: { code: 'ENOENT' }, stdout: '', stderr: '' }, 'absent'],
+      ['failed', { status: 9, stdout: '', stderr: 'private stderr' }, 'failed'],
+      ['timeout', { status: null, error: { code: 'ETIMEDOUT' }, stdout: '', stderr: '' }, 'failed'],
+    ];
+    for (const [name, processResult, expectedState] of cases) {
+      const root = tempProject(`p-rep-teach-${name}-`);
+      let importPath;
+      try {
+        const result = writeInsight(root, payload({ title: `Markdown survives ${name} teach` }), {
+          runner(file, args, options) {
+            assert.equal(file, 'dz');
+            assert.deepEqual(args.slice(0, 2), ['teach', '--from-json']);
+            assert.equal(args[args.length - 2], '--project');
+            assert.equal(args[args.length - 1], root);
+            assert.equal(options.cwd, root);
+            assert.equal(options.timeout, 1500);
+            assert.equal(options.maxBuffer, 1024 * 1024);
+            assert.equal(options.shell, false);
+            importPath = args[2];
+            assert.equal(fs.statSync(importPath).mode & 0o777, 0o600);
+            const imported = JSON.parse(fs.readFileSync(importPath, 'utf8'));
+            assert.equal(imported.length, 1);
+            assert.equal(imported[0].domain, 'p-replicator-insights');
+            return processResult;
+          },
+        });
+        assert.equal(result.status, 'created');
+        assert.equal(result.teach.state, expectedState);
+        assert.match(fs.readFileSync(path.join(root, '.claude', 'insights', 'index.md'), 'utf8'),
+          new RegExp(`Markdown survives ${name} teach`));
+        assert.equal(fs.existsSync(importPath), false, 'private teach import must be removed');
+      } finally { cleanup(root); }
+    }
+
+    const broken = tempProject('p-rep-teach-no-write-');
+    let calls = 0;
+    try {
+      fs.writeFileSync(path.join(broken, '.claude'), 'not a directory\n');
+      assert.throws(() => writeInsight(broken, payload(), {
+        runner() { calls += 1; return { status: 0, stdout: '', stderr: '' }; },
+      }));
+      assert.equal(calls, 0, 'a failed Markdown write must make zero dz calls');
+    } finally { cleanup(broken); }
+  });
+
+  test('P16b - duplicate replay imports one learned row', () => {
+    const { writeInsight, stableTeachText, normalizePayload } = requireWriter();
+    const root = tempProject('p-rep-real-dz-teach-');
+    try {
+      const record = payload({ title: 'Replay-safe learned projection' });
+      const first = writeInsight(root, record);
+      const replay = writeInsight(root, { ...record, date: '2026-08-31' });
+      assert.equal(first.status, 'created');
+      assert.equal(first.teach.state, 'ok');
+      assert.equal(replay.status, 'duplicate');
+      assert.equal(replay.teach.state, 'ok');
+
+      const queried = spawnSync('dz', [
+        'recall', '--all', '--json', '--project', root,
+      ], { cwd: root, encoding: 'utf8', timeout: 5000, maxBuffer: 1024 * 1024 });
+      assert.equal(queried.status, 0, queried.stderr || queried.stdout);
+      const rows = JSON.parse(queried.stdout);
+      const expected = stableTeachText(normalizePayload(record));
+      const matches = rows.filter((row) =>
+        row.domain === 'p-replicator-insights' && row.pattern === expected);
+      assert.equal(matches.length, 1,
+        `two exact replays must leave one learned row, got ${matches.length}`);
+    } finally { cleanup(root); }
+  });
+});

package/tests/unit/shipped-suite-context.test.js

@@ -115,12 +115,14 @@ const count = (out, key) => {
     }
   });
 
-  test('P4 - files[] does not ship scripts/', () => {
+  test('P4 - files[] ships only the deliberate checker, not the scripts directory', () => {
     // The rejected alternative. Adding scripts/ fixes ONE of the two files and hands users build
     // machinery for no reason; module-copy-identity needs sibling PACKAGES, which no tarball has.
     const pkg = JSON.parse(fs.readFileSync(path.join(PKG, 'package.json'), 'utf-8'));
     assert.ok(!(pkg.files || []).includes('scripts/'),
       'shipping scripts/ was rejected: it fixes one file of two and ships build machinery');
+    assert.ok((pkg.files || []).includes('scripts/check-pipeline-gaps.sh'),
+      'the consumer-facing checker must be named explicitly in files[]');
     assert.ok((pkg.files || []).includes('tests/'),
       'this whole file only matters because tests/ ships — if that changes, revisit');
   });