contextdevkit 1.8.0

package/tools/integration-test-tooling.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * ContextDevKit integration test — TOOLING scripts.
+ *
+ * Installs the kit into a throwaway temp project and exercises the tool scripts
+ * (modular CLAUDE.md, git, deep-analysis, security mode, deps-audit, gh-alerts,
+ * fleet, agent-tuning, …). Two focused siblings carry the longer subsystems:
+ * `integration-test-tooling-pipeline.mjs` (DevPipeline, ADR-0016 H1 split)
+ * and `integration-test-tooling-agent-forge.mjs` (forge round-trip + Fase 6
+ * pipeline DSL — split when Fase 6 pushed this file past the RED zone, as the
+ * cohesion note had anticipated). The core hooks/engine are covered by
+ * `integration-test.mjs`. Shared harness: `it-helpers.mjs`.
+ *
+ * Cohesion note (line budget): the remaining ~13 tool checks share ONE
+ * fixture install at L5 and run in dependency order under a single
+ * try/finally — that is the responsibility seam (one install, many tool
+ * scripts). The next natural extraction when budget pressure returns is the
+ * deps-audit + GitHub security batch (the next-longest cohesive subsystem).
+ *
+ * Run:  node tools/integration-test-tooling.mjs   (exit 0 = healthy)
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { KIT, run, readJson, reporter, installFixture } from './it-helpers.mjs';
+
+const rep = reporter();
+const { ok, bad } = rep;
+console.log('\n🌀 ContextDevKit integration test — tooling\n');
+const fx = installFixture(rep);
+const { proj, cfgPath, hook, script } = fx;
+
+try {
+  // Modular CLAUDE.md: two apps lacking CLAUDE.md → scaffold creates both.
+  mkdirSync(join(proj, 'apps', 'api'), { recursive: true });
+  mkdirSync(join(proj, 'apps', 'web'), { recursive: true });
+  writeFileSync(join(proj, 'apps', 'api', 'package.json'), '{"name":"api"}');
+  writeFileSync(join(proj, 'apps', 'web', 'package.json'), '{"name":"web"}');
+  const cmFind = script('claude-md.mjs', 'find', '--json');
+  (() => { try { return JSON.parse(cmFind.stdout).moduleRoots.length === 2; } catch { return false; } })()
+    ? ok('claude-md detects 2 module roots') : bad(`claude-md find failed: ${cmFind.stdout || cmFind.stderr}`);
+  script('claude-md.mjs', 'scaffold');
+  existsSync(join(proj, 'apps', 'api', 'CLAUDE.md')) && existsSync(join(proj, 'apps', 'web', 'CLAUDE.md'))
+    ? ok('claude-md scaffolds scoped CLAUDE.md per module') : bad('module CLAUDE.md not scaffolded');
+
+  // Version control: git.mjs reports a repo with no remote (temp project has none).
+  const gitStatus = script('git.mjs', 'status', '--json');
+  (() => { try { const g = JSON.parse(gitStatus.stdout); return g.isRepo === true && g.remoteUrl === null; } catch { return false; } })()
+    ? ok('git.mjs reports repo + missing remote') : bad(`git.mjs failed: ${gitStatus.stdout || gitStatus.stderr}`);
+
+  // DevPipeline tests live in `integration-test-tooling-pipeline.mjs` (sibling).
+
+  // Deep analysis: aggregates the deterministic scanners into one report.
+  const deep = JSON.parse(script('deep-analysis.mjs', '--json').stdout || '{}');
+  deep.byScan && typeof deep.total === 'number' && Array.isArray(deep.findings)
+    ? ok('deep-analysis aggregates scanners into one report') : bad(`deep-analysis failed: ${JSON.stringify(deep).slice(0, 120)}`);
+
+  // Security mode: SessionStart reminds to /deep-analysis on the cadence (default-on).
+  const secCfg = readJson(cfgPath);
+  secCfg.securityMode = { active: true, everyNSessions: 1 };
+  writeFileSync(cfgPath, JSON.stringify(secCfg, null, 2));
+  writeFileSync(join(proj, 'contextkit', 'memory', 'sessions', '2026-01-01-01-x.md'), '# x');
+  hook('session-start.mjs', { session_id: 'sec' }).includes('Security mode')
+    ? ok('security-mode boot trigger fires on cadence') : bad('security-mode banner missing');
+  secCfg.securityMode.active = false;
+  writeFileSync(cfgPath, JSON.stringify(secCfg, null, 2));
+  !hook('session-start.mjs', { session_id: 'sec' }).includes('Security mode')
+    ? ok('security-mode disabled via config (active:false)') : bad('security-mode fired while disabled');
+
+  // Security: a crafted base-branch arg must reach git LITERALLY (one invalid ref →
+  // non-zero exit), not be split by a shell — proves no shell was involved.
+  const wt = script('worktree-new.mjs', 'feat', 'HEAD; echo INJECTED_PWNED');
+  wt.status !== 0
+    ? ok('worktree-new passes the base-branch arg literally (no shell injection)')
+    : bad('worktree-new shell injection NOT neutralized (a shell split the arg)');
+
+  // tech-debt --ci gate: a clean project has no RED-zone finding → exits 0.
+  const debtCi = script('tech-debt-scan.mjs', '--ci');
+  debtCi.status === 0 && /CI gate/.test(debtCi.stdout || '')
+    ? ok('tech-debt --ci gate passes on a clean project')
+    : bad(`tech-debt --ci gate failed: ${debtCi.stdout || debtCi.stderr}`);
+
+  // Pluggable detectors: a drop-in contextkit/detectors/*.mjs is loaded and its findings appear.
+  mkdirSync(join(proj, 'contextkit', 'detectors'), { recursive: true });
+  writeFileSync(join(proj, 'contextkit', 'detectors', 'custom.mjs'),
+    "export default function detectFooBar(p, c) { return c.includes('FOOBAR') ? [{ kind: 'custom-foobar', severity: 2, path: p, line: 1, message: 'FOOBAR marker' }] : []; }\n");
+  mkdirSync(join(proj, 'src'), { recursive: true });
+  writeFileSync(join(proj, 'src', 'marker.js'), '// FOOBAR\n');
+  JSON.parse(script('tech-debt-scan.mjs', '--json').stdout || '{"findings":[]}').findings.some((f) => f.kind === 'custom-foobar')
+    ? ok('tech-debt-scan loads a drop-in custom detector (contextkit/detectors/)') : bad('custom detector not loaded');
+
+  // Stack presets: install --preset merges stack paths into config (union with defaults).
+  run([join(KIT, 'install.mjs'), '--target', proj, '--update', '--preset', 'go']);
+  (readJson(cfgPath).ledger?.important || []).includes('internal/')
+    ? ok('install --preset merges a stack preset into config') : bad('preset paths not merged into config');
+
+  // Recommended start level (ADR-0009): greenfield auto-picks L3, existing auto-picks L7
+  // (the latter also proves the level cap accepts 7 — a broken cap would downgrade to 2).
+  const gdir = mkdtempSync(join(tmpdir(), 'contextkit-gf-'));
+  const edir = mkdtempSync(join(tmpdir(), 'contextkit-ex-'));
+  try {
+    run([join(KIT, 'install.mjs'), '--target', gdir, '--yes']);
+    readJson(join(gdir, 'contextkit', 'config.json')).level === 3
+      ? ok('install auto-picks L3 for a greenfield project') : bad(`greenfield default not L3: ${readJson(join(gdir, 'contextkit', 'config.json')).level}`);
+    mkdirSync(join(edir, 'src'), { recursive: true });
+    writeFileSync(join(edir, 'src', 'index.js'), 'export const x = 1;\n');
+    run([join(KIT, 'install.mjs'), '--target', edir, '--yes']);
+    readJson(join(edir, 'contextkit', 'config.json')).level === 7
+      ? ok('install auto-picks L7 for an existing project (+ level cap accepts 7)') : bad(`existing default not L7: ${readJson(join(edir, 'contextkit', 'config.json')).level}`);
+  } finally {
+    rmSync(gdir, { recursive: true, force: true });
+    rmSync(edir, { recursive: true, force: true });
+  }
+
+  // Quality CI workflow scaffolded (contract-drift + tech-debt gates).
+  existsSync(join(proj, '.github', 'workflows', 'quality.yml')) ? ok('quality CI workflow installed') : bad('quality.yml not installed');
+
+  // Visual testing harness (#6): the scaffolder writes a Playwright starter; status detects it.
+  script('visual-test.mjs', 'scaffold', '--js');
+  existsSync(join(proj, 'playwright.config.js')) && existsSync(join(proj, 'tests', 'visual', 'home.spec.js'))
+    ? ok('visual-test scaffolds a Playwright starter') : bad('visual-test did not scaffold');
+  (() => { try { return JSON.parse(script('visual-test.mjs', 'status', '--json').stdout).set === true; } catch { return false; } })()
+    ? ok('visual-test status detects the scaffolded harness') : bad('visual-test status missed the harness');
+
+  // Dependency audit: flags no-lockfile + loose version ranges as findings.
+  writeFileSync(join(proj, 'package.json'), JSON.stringify({ name: 'it', dependencies: { leftpad: '*' } }));
+  const deps = JSON.parse(script('deps-audit.mjs', '--json').stdout || '{"findings":[]}').findings || [];
+  deps.some((f) => f.kind === 'no-lockfile') && deps.some((f) => f.kind === 'loose-range')
+    ? ok('deps-audit flags no-lockfile + loose ranges') : bad(`deps-audit findings: ${JSON.stringify(deps)}`);
+
+  // Dependency policy: a denied license is flagged; --sbom writes a CycloneDX SBOM.
+  const depCfg = readJson(cfgPath);
+  depCfg.deps = { requireLockfile: true, licenses: { allow: [], deny: ['GPL-3.0'] } };
+  writeFileSync(cfgPath, JSON.stringify(depCfg, null, 2));
+  writeFileSync(join(proj, 'package.json'), JSON.stringify({ name: 'it', version: '1.0.0', dependencies: { gpllib: '1.0.0' } }));
+  mkdirSync(join(proj, 'node_modules', 'gpllib'), { recursive: true });
+  writeFileSync(join(proj, 'node_modules', 'gpllib', 'package.json'), JSON.stringify({ name: 'gpllib', version: '1.0.0', license: 'GPL-3.0' }));
+  JSON.parse(script('deps-audit.mjs', '--json').stdout || '{"findings":[]}').findings.some((f) => f.kind === 'license-deny')
+    ? ok('deps-audit flags a denied license (deps policy)') : bad('deps-audit did not flag the denied license');
+  script('deps-audit.mjs', '--sbom');
+  (() => { try { const s = readJson(join(proj, 'contextkit', 'memory', 'sbom.json')); return s.bomFormat === 'CycloneDX' && (s.components || []).some((c) => c.name === 'gpllib'); } catch { return false; } })()
+    ? ok('deps-audit --sbom writes a CycloneDX SBOM') : bad('SBOM not written/invalid');
+
+  // GitHub-native security: scaffolding + code-security agent installed; alert sync degrades safely.
+  existsSync(join(proj, '.github', 'dependabot.yml')) && existsSync(join(proj, '.github', 'workflows', 'security.yml'))
+    ? ok('GitHub security scaffolding installed (dependabot.yml + security workflow)') : bad('security scaffolding not installed');
+  existsSync(join(proj, '.claude', 'agents', 'code-security.md')) ? ok('code-security agent installed (L5)') : bad('code-security agent missing');
+  const ghAlerts = script('gh-alerts.mjs', '--json');
+  ghAlerts.status === 0 && (() => { try { return Array.isArray(JSON.parse(ghAlerts.stdout).findings); } catch { return false; } })()
+    ? ok('gh-alerts degrades safely without a GitHub repo (exit 0, empty findings)') : bad(`gh-alerts failed: ${ghAlerts.stdout || ghAlerts.stderr}`);
+
+  // Fleet mode: register this project in a temp registry, aggregate stats across the fleet.
+  const fleetEnv = { ...process.env, CONTEXT_FLEET_FILE: join(proj, '.fleet.json') };
+  const fleet = (...a) => run([join(proj, 'contextkit', 'tools', 'scripts', 'fleet.mjs'), ...a], { cwd: proj, env: fleetEnv });
+  fleet('add', proj);
+  const fleetStats = fleet('stats', '--json');
+  (() => { try { const d = JSON.parse(fleetStats.stdout); return d.totals.repos === 1 && d.repos[0]?.ok === true && typeof d.totals.totalSessions === 'number'; } catch { return false; } })()
+    ? ok('fleet stats aggregates a registered repo (control plane)') : bad(`fleet failed: ${fleetStats.stdout || fleetStats.stderr}`);
+
+  // Agent tuning: signal aggregation lists the installed agent roster (proposes only).
+  const tuning = script('agent-tuning.mjs', '--json');
+  (() => { try { const d = JSON.parse(tuning.stdout); return Array.isArray(d.agents) && d.agents.length >= 1 && typeof d.sessionsAnalyzed === 'number'; } catch { return false; } })()
+    ? ok('agent-tuning aggregates the agent roster + signals') : bad(`agent-tuning failed: ${tuning.stdout || tuning.stderr}`);
+
+  // agent-forge round-trip + Fase 6 pipeline DSL → integration-test-tooling-agent-forge.mjs.
+} catch (err) {
+  bad(`crashed: ${err?.stack || err}`);
+} finally {
+  fx.cleanup();
+}
+
+rep.finish('Integration (tooling)');

package/tools/integration-test.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * ContextDevKit integration test — CORE engine (install + the real hooks).
+ *
+ * Installs the kit into a throwaway temp project and drives the runtime hooks
+ * end-to-end (drift block, L5 gate, predictions, concurrency, --update, …). The
+ * tool scripts (pipeline, deps, fleet, agent-tuning, …) are covered by
+ * `integration-test-tooling.mjs`. Shared harness: `it-helpers.mjs`.
+ *
+ * Run:  node tools/integration-test.mjs   (exit 0 = healthy)
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KIT, run, readJson, reporter, installFixture } from './it-helpers.mjs';
+
+const rep = reporter();
+const { ok, bad } = rep;
+console.log('\n🌀 ContextDevKit integration test — core\n');
+const fx = installFixture(rep);
+const { proj, cfgPath, hook, script } = fx;
+
+try {
+  // L3 git hooks installed (pre-push conflict check).
+  existsSync(join(proj, '.git', 'hooks', 'pre-push')) ? ok('pre-push git hook installed') : bad('pre-push hook missing');
+
+  // First-run trigger.
+  hook('session-start.mjs', {}).includes('First run')
+    ? ok('SessionStart fires the first-run trigger')
+    : bad('first-run banner missing');
+
+  // Drift ledger + Stop block.
+  hook('track-edits.mjs', { session_id: 'it', tool_name: 'Write', tool_input: { file_path: 'src/a.js' } });
+  hook('track-edits.mjs', { session_id: 'it', tool_name: 'Write', tool_input: { file_path: 'src/b.js' } });
+  existsSync(join(proj, '.claude', '.sessions', 'it.json')) ? ok('PostToolUse writes the ledger') : bad('ledger not written');
+  hook('check-registration.mjs', { session_id: 'it' }).includes('"decision":"block"')
+    ? ok('Stop blocks on drift')
+    : bad('Stop did not block on drift');
+
+  // L5 gate: block, then allow after a simulation record.
+  const cfg = readJson(cfgPath);
+  cfg.l5.highRiskPaths = ['src/secure/'];
+  writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+  hook('simulate-gate.mjs', { session_id: 'it', tool_name: 'Write', tool_input: { file_path: 'src/secure/x.js' } }).includes('"decision":"block"')
+    ? ok('L5 gate blocks an unsimulated high-risk edit')
+    : bad('L5 gate did not block');
+  script('mark-simulation.mjs', 'cover secure', 'src/secure/');
+  hook('simulate-gate.mjs', { session_id: 'it', tool_name: 'Write', tool_input: { file_path: 'src/secure/x.js' } }).trim() === ''
+    ? ok('L5 gate allows after /simulate-impact')
+    : bad('L5 gate still blocked after simulation');
+  // Ancestor parity: /simulate-impact leaves a prediction trail file.
+  existsSync(join(proj, 'contextkit', 'memory', 'predictions')) && readdirSync(join(proj, 'contextkit', 'memory', 'predictions')).some((f) => f.endsWith('.md'))
+    ? ok('simulate-impact writes a prediction file (predictions/)')
+    : bad('no prediction file written');
+  // Pluggable-detector seed (026): README + inert example install (discoverable, not auto-run).
+  existsSync(join(proj, 'contextkit', 'detectors', 'README.md')) && existsSync(join(proj, 'contextkit', 'detectors', 'example-detector.mjs.example'))
+    ? ok('detectors seed installed (README + .example, discoverable)') : bad('detectors seed not installed');
+  // Ancestor parity: workflow guides (L1–L6) + reusable playbooks are installed.
+  existsSync(join(proj, 'contextkit', 'workflows', 'README.md')) &&
+    ['tech-debt-sweep.md', 'simulate-impact.md', 'distillation-cycle.md', 'security-batch.md']
+      .every((f) => existsSync(join(proj, 'contextkit', 'workflows', 'playbooks', f)))
+    ? ok('workflows + playbooks installed (workflows/playbooks/)')
+    : bad('workflows/playbooks not installed');
+  // Ancestor parity #1 (loop closed): predictions-review fills the Actual section.
+  script('predictions-review.mjs');
+  const predMd = readdirSync(join(proj, 'contextkit', 'memory', 'predictions')).find((f) => f.endsWith('.md'));
+  const predBody = predMd ? readFileSync(join(proj, 'contextkit', 'memory', 'predictions', predMd), 'utf-8') : '';
+  predBody.includes('## Actual (reviewed') && predBody.includes('src/a.js') && !predBody.includes('fill on review')
+    ? ok('predictions-review closes the predicted-vs-actual loop (Actual filled)')
+    : bad('predictions-review did not fill the Actual section');
+
+  // Concurrency guard (L3+): warn before overwriting a file another session edited.
+  hook('track-edits.mjs', { session_id: 'other', tool_name: 'Write', tool_input: { file_path: 'src/shared.js' } });
+  hook('concurrency-guard.mjs', { session_id: 'me', tool_name: 'Write', tool_input: { file_path: 'src/shared.js' } }).includes('Concurrency')
+    ? ok('concurrency-guard warns on cross-session collision')
+    : bad('concurrency-guard did not warn');
+  const l5settings = readJson(join(proj, '.claude', 'settings.json'));
+  (l5settings.hooks?.PreToolUse || []).some((g) => (g.hooks || []).some((h) => h.command.includes('concurrency-guard')))
+    ? ok('L5 wires the concurrency guard (PreToolUse)') : bad('concurrency-guard not wired at L5');
+
+  // 008 — a booting session must NOT delete a concurrent session's fresh/empty ledger.
+  const concLedger = join(proj, '.claude', '.sessions', 'concurrent.json');
+  writeFileSync(concLedger, JSON.stringify({ sessionId: 'concurrent', startedAt: Date.now(), modifications: [], registered: false, stopWarnedAt: null, simulations: [] }));
+  hook('session-start.mjs', { session_id: 'booting-now' });
+  existsSync(concLedger) ? ok('session-start preserves a concurrent session fresh ledger (008)') : bad('session-start deleted a concurrent fresh ledger');
+
+  // Safe --update: preserves CLAUDE.md, config (level + overrides), memory.
+  writeFileSync(join(proj, 'CLAUDE.md'), readFileSync(join(proj, 'CLAUDE.md'), 'utf-8') + '\n## USER MARKER\n');
+  run([join(KIT, 'install.mjs'), '--target', proj, '--update']);
+  const afterCfg = readJson(join(proj, 'contextkit', 'config.json'));
+  readFileSync(join(proj, 'CLAUDE.md'), 'utf-8').includes('USER MARKER') && afterCfg.level === 5 && !existsSync(join(proj, 'CLAUDE.contextdevkit.md'))
+    ? ok('--update preserves CLAUDE.md + level (no data loss)')
+    : bad('--update lost data (CLAUDE.md/level/side-file)');
+
+  // setup-complete silences the trigger.
+  script('setup-complete.mjs');
+  !hook('session-start.mjs', {}).includes('First run')
+    ? ok('first-run trigger silent after setup-complete')
+    : bad('trigger still firing after setup-complete');
+
+  // context-level down to L2 removes PreToolUse wiring.
+  script('context-level.mjs', '2');
+  const settings = readJson(join(proj, '.claude', 'settings.json'));
+  !settings.hooks?.PreToolUse ? ok('context-level 2 removes the L5 PreToolUse hook') : bad('PreToolUse still wired at L2');
+  settings.hooks?.SessionStart && settings.hooks?.Stop ? ok('context-level 2 keeps L1/L2 hooks') : bad('L1/L2 hooks lost');
+  // L7 is a valid capability-tier level (no new hook beyond L5/L6).
+  script('context-level.mjs', '7');
+  readJson(join(proj, 'contextkit', 'config.json')).level === 7 ? ok('context-level 7 sets the L7 capability tier') : bad('context-level 7 not applied');
+
+  // GitHub templates + QA/compliance/design/security agents + two-tier briefings.
+  existsSync(join(proj, '.github', 'PULL_REQUEST_TEMPLATE.md')) ? ok('GitHub PR template installed') : bad('PR template not installed');
+  existsSync(join(proj, '.claude', 'agents', 'qa-orchestrator.md')) ? ok('QA squad agents installed (L5)') : bad('qa-orchestrator agent missing');
+  existsSync(join(proj, 'contextkit', 'squads', 'README.md')) ? ok('squad manifest installed') : bad('squads/README.md missing');
+  existsSync(join(proj, '.claude', 'agents', 'privacy-lgpd.md')) && existsSync(join(proj, '.claude', 'agents', 'ux-designer.md'))
+    ? ok('compliance + design squads installed') : bad('new squad agents missing');
+  existsSync(join(proj, '.claude', 'agents', 'infra-security.md')) ? ok('security-team infra-security agent installed') : bad('infra-security agent missing');
+  script('squad.mjs', 'brief', 'security');
+  existsSync(join(proj, 'contextkit', 'squads', 'security-team', 'security.md'))
+    ? ok('squad brief scaffolds a tier-2 briefing (squads/<team>/)') : bad('squad brief did not scaffold');
+
+  // Status-line widget: wired into settings.json + runs and prints a line.
+  readJson(join(proj, '.claude', 'settings.json')).statusLine?.command?.includes('contextkit/runtime/statusline')
+    ? ok('statusLine widget wired into settings.json') : bad('statusLine not wired into settings.json');
+  (run([join(proj, 'contextkit', 'runtime', 'statusline.mjs')], { cwd: proj }).stdout || '').includes('🌀')
+    ? ok('statusline.mjs prints a status line') : bad('statusline.mjs produced no output');
+
+  // context-config show/set round-trip.
+  script('context-config.mjs', 'set', 'qa.coverageTarget.lines', '90');
+  const showOut = script('context-config.mjs', 'show', 'qa.coverageTarget.lines').stdout || '';
+  showOut.trim() === '90' ? ok('context-config set/show round-trips') : bad(`context-config round-trip failed: ${showOut}`);
+
+  // doctor runs and reports — and accepts the current level (L7 set above) as valid,
+  // not "out of range" (regression guard for the level-range cap).
+  const doc = script('doctor.mjs');
+  /ContextDevKit doctor/i.test(doc.stdout || '') && !/level.*out of range/i.test(doc.stdout || '')
+    ? ok('doctor runs + accepts L7 as a valid level') : bad(`doctor failed/flagged level: ${doc.stdout || doc.stderr}`);
+
+  // L5/L6 scanners run and produce JSON.
+  const debt = script('tech-debt-scan.mjs', '--json');
+  (() => { try { return Array.isArray(JSON.parse(debt.stdout).findings); } catch { return false; } })()
+    ? ok('tech-debt-scan emits JSON findings') : bad(`tech-debt-scan failed: ${debt.stderr}`);
+  const stats = script('stats.mjs', '--json');
+  (() => { try { return typeof JSON.parse(stats.stdout).driftRatePct === 'number'; } catch { return false; } })()
+    ? ok('stats emits JSON metrics') : bad(`stats failed: ${stats.stderr}`);
+
+  // best-practices doc + business-rules scaffold installed.
+  existsSync(join(proj, 'contextkit', 'best-practices.md')) ? ok('best-practices.md installed') : bad('best-practices.md missing');
+  existsSync(join(proj, 'contextkit', 'memory', 'business-rules', '_TEMPLATE.md')) ? ok('business-rules/ scaffolded (ancestor parity)') : bad('business-rules template missing');
+
+  // Contract drift: deepened extractor catches default / export* / abstract / type-only.
+  const ccfg = readJson(cfgPath);
+  ccfg.l5 = ccfg.l5 || {};
+  ccfg.l5.contractGlobs = ['src/contract/'];
+  writeFileSync(cfgPath, JSON.stringify(ccfg, null, 2));
+  mkdirSync(join(proj, 'src', 'contract'), { recursive: true });
+  const apiPath = join(proj, 'src', 'contract', 'api.ts');
+  writeFileSync(apiPath, [
+    'export default function main() {}',
+    'export const alpha = 1;',
+    'export abstract class Beta {}',
+    "export * from './other';",
+    'export type Gamma = { x: number };',
+    "export { delta, epsilon as zeta } from './m';",
+  ].join('\n'));
+  script('contract-scan.mjs', '--save');
+  writeFileSync(apiPath, ['export const alpha = 1;', "export { delta, epsilon as zeta } from './m';"].join('\n'));
+  const drift = script('contract-scan.mjs', '--json');
+  (() => {
+    try {
+      const removed = JSON.parse(drift.stdout).removals.join('\n');
+      return ['default', 'Beta', 'Gamma'].every((n) => removed.includes(n)) && removed.includes('* from ./other');
+    } catch { return false; }
+  })()
+    ? ok('contract-scan detects removed default / export* / abstract / type-only exports')
+    : bad(`contract-scan drift miss: ${drift.stdout || drift.stderr}`);
+  // Optional AST contract drift (#001): with a parser available (fake via CONTEXT_CONTRACT_PARSER),
+  // extraction uses the AST, not regex — the baseline reflects AST-derived names.
+  const astCfg = readJson(cfgPath);
+  astCfg.l5.contractGlobs = ['src/ast/'];
+  writeFileSync(cfgPath, JSON.stringify(astCfg, null, 2));
+  mkdirSync(join(proj, 'src', 'ast'), { recursive: true });
+  writeFileSync(join(proj, 'src', 'ast', 'mod.js'), 'export const regexName = 1;\n');
+  writeFileSync(join(proj, '_fakeparser.mjs'), 'export function parse(){return{body:[{type:"ExportDefaultDeclaration"},{type:"ExportNamedDeclaration",specifiers:[{exported:{name:"astOnly"}}]}]};}\n');
+  run([join(proj, 'contextkit', 'tools', 'scripts', 'contract-scan.mjs'), '--save'], { cwd: proj, env: { ...process.env, CONTEXT_CONTRACT_PARSER: join(proj, '_fakeparser.mjs') } });
+  const astBaseline = readFileSync(join(proj, 'contextkit', 'memory', 'contract-baseline.json'), 'utf-8');
+  astBaseline.includes('astOnly') && !astBaseline.includes('regexName')
+    ? ok('contract-scan uses the optional AST parser when importable') : bad(`AST path not used: ${astBaseline}`);
+
+  // Playbook management (#8): the registry lists installed playbooks; run records a tracked entry.
+  const pbList = script('playbook.mjs', 'list').stdout || '';
+  pbList.includes('tech-debt-sweep') && pbList.includes('security-batch')
+    ? ok('playbook list shows the registry') : bad(`playbook list missing entries: ${pbList}`);
+  script('playbook.mjs', 'run', 'tech-debt-sweep', 'IT run');
+  const pbRuns = existsSync(join(proj, 'contextkit', 'memory', 'playbook-runs.md'))
+    && readFileSync(join(proj, 'contextkit', 'memory', 'playbook-runs.md'), 'utf-8');
+  pbRuns && pbRuns.includes('tech-debt-sweep')
+    ? ok('playbook run records a tracked entry') : bad('playbook run did not track');
+
+  // Token economy (#7): token-report aggregates usage from transcripts (fake --from dir; also
+  // exercises the cwd filter + defensive JSON parsing of a bad line).
+  const ttx = join(proj, '_ttx');
+  mkdirSync(ttx, { recursive: true });
+  const usageLine = (i, o) => JSON.stringify({ type: 'assistant', sessionId: 'sess1', timestamp: '2026-05-24T00:00:00Z', cwd: proj, message: { role: 'assistant', usage: { input_tokens: i, output_tokens: o, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 } } });
+  writeFileSync(join(ttx, 'sess1.jsonl'), [usageLine(100, 200), usageLine(50, 25), '{ bad json'].join('\n'));
+  const tr = script('token-report.mjs', '--from', ttx, '--json');
+  (() => { try { const j = JSON.parse(tr.stdout); return j.sessions === 1 && j.totals.total === 375 && j.totals.input === 150; } catch { return false; } })()
+    ? ok('token-report aggregates token usage from transcripts') : bad(`token-report failed: ${tr.stdout || tr.stderr}`);
+
+  // Predictions-review cadence (#002): cadence on + an unreviewed prediction → SessionStart reminds.
+  const prCfg = readJson(cfgPath);
+  prCfg.predictionsReview = { active: true, everyNSessions: 1 };
+  writeFileSync(cfgPath, JSON.stringify(prCfg, null, 2));
+  writeFileSync(join(proj, 'contextkit', 'memory', 'sessions', '2026-01-01-01-x.md'), '# x\n');
+  writeFileSync(join(proj, 'contextkit', 'memory', 'predictions', 'unrev.md'), '# Prediction\n\n## Actual — fill on review\n');
+  hook('session-start.mjs', {}).includes('/predictions-review')
+    ? ok('predictions-review cadence reminds when a review is due') : bad('no predictions-review cadence reminder');
+
+  // Roadmap seeded (undefined) + find reports it as not-defined.
+  existsSync(join(proj, 'contextkit', 'memory', 'roadmap.md')) ? ok('roadmap.md installed') : bad('roadmap.md missing');
+  const rm = script('roadmap.mjs', 'find', '--json');
+  (() => { try { return JSON.parse(rm.stdout).canonicalDefined === false; } catch { return false; } })()
+    ? ok('roadmap find reports undefined (seed placeholder)') : bad(`roadmap find failed: ${rm.stderr || rm.stdout}`);
+} catch (err) {
+  bad(`crashed: ${err?.stack || err}`);
+} finally {
+  fx.cleanup();
+}
+
+rep.finish('Integration (core)');

package/tools/it-helpers.mjs

@@ -0,0 +1,60 @@
+/**
+ * Shared harness for the integration tests.
+ *
+ * The end-to-end suite is split by responsibility to stay within the line budget:
+ *   - `integration-test.mjs`                  — core engine: install + the real hooks.
+ *   - `integration-test-tooling.mjs`          — the tool scripts (deps, fleet, agent-forge, …).
+ *   - `integration-test-tooling-pipeline.mjs` — the DevPipeline chain (ADR-0016 H1 split).
+ *   - `integration-test-guards.mjs`           — guards that REJECT bad input (commit-msg, pre-push, loader).
+ * Each installs a throwaway temp project via `installFixture` and drives it through
+ * `child_process` with a real stdin pipe — exactly how Claude Code invokes hooks.
+ * Cross-platform (avoids PowerShell's broken string-to-stdin piping), self-cleaning.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const KIT = dirname(dirname(fileURLToPath(import.meta.url)));
+export const node = process.execPath;
+export const run = (args, opts = {}) => spawnSync(node, args, { encoding: 'utf-8', ...opts });
+export const git = (args, cwd) => spawnSync('git', args, { cwd, encoding: 'utf-8' });
+export const readJson = (p) => JSON.parse(readFileSync(p, 'utf-8').replace(/^/, ''));
+
+/** A pass/fail reporter with its own failure counter. `finish` sets the exit code. */
+export function reporter() {
+  let failures = 0;
+  return {
+    ok: (m) => console.log(`  ✓ ${m}`),
+    bad: (m) => {
+      console.error(`  ✗ ${m}`);
+      failures += 1;
+    },
+    finish: (label) => {
+      console.log(failures === 0 ? `\n✅ ${label} passed.\n` : `\n❌ ${failures} check(s) failed.\n`);
+      process.exit(failures === 0 ? 0 : 1);
+    },
+  };
+}
+
+/**
+ * Fresh temp git repo with the kit installed at Level 5. Returns helpers bound to
+ * it: `hook(name, payload)` pipes JSON to a runtime hook; `script(rel, ...args)`
+ * runs a tool script; `cleanup()` removes the temp project.
+ */
+export function installFixture(rep) {
+  const proj = mkdtempSync(join(tmpdir(), 'contextkit-it-'));
+  git(['init', '-b', 'main'], proj);
+  git(['config', 'user.email', 'it@example.com'], proj);
+  git(['config', 'user.name', 'IT'], proj);
+  const inst = run([join(KIT, 'install.mjs'), '--target', proj, '--level', '5', '--name', 'IT App', '--yes']);
+  inst.status === 0 ? rep.ok('install at Level 5') : rep.bad(`install failed (status ${inst.status}): ${inst.stderr}`);
+  return {
+    proj,
+    cfgPath: join(proj, 'contextkit', 'config.json'),
+    hook: (name, payload) => run([join(proj, 'contextkit', 'runtime', 'hooks', name)], { cwd: proj, input: JSON.stringify(payload) }).stdout || '',
+    script: (rel, ...a) => run([join(proj, 'contextkit', 'tools', 'scripts', rel), ...a], { cwd: proj }),
+    cleanup: () => rmSync(proj, { recursive: true, force: true }),
+  };
+}

package/tools/selfcheck-agent-forge-ops.mjs

@@ -0,0 +1,107 @@
+/**
+ * Self-check assertions for the agent-forge **operations** surface — Fase 4 + 5:
+ * package discovery / diagnosis, the rag-designer extension, and the L5 high-risk
+ * paths default that gates `agent-packages/**` edits.
+ *
+ * Split out of `selfcheck-agent-forge.mjs` once the core file (foundational +
+ * build-pipeline checks) reached the 308 hard block — a real responsibility seam
+ * (build engine vs. running fleet), not a premature split.
+ *
+ * Entry point: `runAgentForgeOpsChecks(rep, KIT)`.
+ */
+import { resolve } from 'node:path';
+
+/** package-ops discovers `<name>@<semver>/` dirs without needing yaml; diagnose
+ *  flags missing files + unresolved `{{TOKEN}}` placeholders in governance YAMLs. */
+async function checkPackageOps(rep, KIT) {
+  const { ok, bad } = rep;
+  console.log('Checking agent-forge package-ops (Fase 4)...');
+  const opsUrl = 'file://' + resolve(KIT, 'templates/contextkit/squads/agent-forge/lib/package-ops.mjs').replaceAll('\\', '/');
+  let discoverPackages;
+  let diagnosePackage;
+  try {
+    ({ discoverPackages, diagnosePackage } = await import(opsUrl));
+  } catch (err) {
+    bad(`package-ops import failed: ${err.message}`);
+    return;
+  }
+  const { mkdtempSync, writeFileSync, mkdirSync, rmSync } = await import('node:fs');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const root = mkdtempSync(join(tmpdir(), 'forge-ops-'));
+  try {
+    mkdirSync(join(root, 'demo@0.1.0/governance'), { recursive: true });
+    mkdirSync(join(root, 'demo@0.1.0/prompts'));
+    mkdirSync(join(root, 'demo@0.1.0/tools'));
+    mkdirSync(join(root, 'demo@0.1.0/evals'));
+    mkdirSync(join(root, 'not-a-package'));
+    writeFileSync(join(root, 'demo@0.1.0/manifest.yaml'), 'apiVersion: x\n');
+    const pkgs = await discoverPackages(root);
+    pkgs.length === 1 && pkgs[0].name === 'demo' && pkgs[0].version === '0.1.0'
+      ? ok('package-ops.discoverPackages finds <name>@<semver> dirs and skips others (Fase 4)')
+      : bad(`discoverPackages wrong: ${JSON.stringify(pkgs)}`);
+    const diag = await diagnosePackage(join(root, 'demo@0.1.0'));
+    diag.ok === false && diag.problems.some((problem) => problem.includes('missing'))
+      ? ok('package-ops.diagnosePackage reports missing required files (Fase 4)')
+      : bad(`diagnose wrong: ${JSON.stringify(diag)}`);
+    writeFileSync(join(root, 'demo@0.1.0/governance/cost.policy.yaml'), 'budgets:\n  per_call: {{0.015}}\n');
+    const diag2 = await diagnosePackage(join(root, 'demo@0.1.0'));
+    diag2.problems.some((problem) => problem.includes('placeholders'))
+      ? ok('package-ops.diagnosePackage refuses governance YAML with {{TOKEN}} placeholders (Fase 4)')
+      : bad(`diagnose missed placeholders: ${JSON.stringify(diag2)}`);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** rag-designer shapes the bundle from blueprint (residency drives backend,
+ *  domain drives embedding language, category drives chunk size, complexity drives top_k). */
+async function checkRagDesigner(rep, KIT) {
+  const { ok, bad } = rep;
+  console.log('Checking agent-forge rag-designer (Fase 5)...');
+  const ragUrl = 'file://' + resolve(KIT, 'templates/contextkit/squads/agent-forge/lib/rag-designer.mjs').replaceAll('\\', '/');
+  let designRagConfig;
+  try {
+    ({ designRagConfig } = await import(ragUrl));
+  } catch (err) {
+    bad(`rag-designer import failed: ${err.message}`);
+    return;
+  }
+  const onPrem = designRagConfig({ intent: { category: 'rag-answer', complexity: 'high', domain: 'legal-pt-br' }, privacy: { allow_cloud_providers: false, data_residency: 'on-prem' } });
+  onPrem.config.index.backend === 'pgvector'
+    ? ok('rag-designer routes to pgvector under no-cloud / on-prem (Fase 5)')
+    : bad(`rag-designer leaked to cloud backend: ${onPrem.config.index.backend}`);
+  onPrem.config.embedding.model === 'multilingual-e5'
+    ? ok('rag-designer picks multilingual embedding for non `-en` domain (Fase 5)')
+    : bad(`embedding wrong for multilingual domain: ${onPrem.config.embedding.model}`);
+  onPrem.config.retrieval.top_k === 12
+    ? ok('rag-designer raises top_k for high-complexity intents (Fase 5)')
+    : bad(`top_k wrong for complexity=high: ${onPrem.config.retrieval.top_k}`);
+  const englishExtraction = designRagConfig({ intent: { category: 'extraction', complexity: 'low', domain: 'finance-en' }, privacy: { allow_cloud_providers: true } });
+  englishExtraction.config.embedding.model === 'text-embedding-3-large' && englishExtraction.chunker.chunk_size_tokens === 256
+    ? ok('rag-designer picks english embedding + tight chunks for extraction-en (Fase 5)')
+    : bad(`english-en + extraction wrong: ${JSON.stringify({ embed: englishExtraction.config.embedding.model, chunk: englishExtraction.chunker.chunk_size_tokens })}`);
+}
+
+/** defaults.mjs ships `agent-packages/**` in L5 highRiskPaths so the simulate-impact
+ *  gate triggers on forged-agent edits (ADR-0012). */
+async function checkL5ForgePath(rep, KIT) {
+  const { ok, bad } = rep;
+  console.log('Checking L5 high-risk paths default (Fase 5)...');
+  const defaultsUrl = 'file://' + resolve(KIT, 'templates/contextkit/runtime/config/defaults.mjs').replaceAll('\\', '/');
+  try {
+    const { DEFAULT_CONFIG } = await import(defaultsUrl);
+    DEFAULT_CONFIG?.l5?.highRiskPaths?.includes('agent-packages/**')
+      ? ok('defaults.l5.highRiskPaths includes agent-packages/** by default (Fase 5)')
+      : bad(`agent-packages/** missing from l5.highRiskPaths: ${JSON.stringify(DEFAULT_CONFIG?.l5?.highRiskPaths)}`);
+  } catch (err) {
+    bad(`defaults.mjs import failed: ${err.message}`);
+  }
+}
+
+/** Runs every agent-forge operations check in order. */
+export async function runAgentForgeOpsChecks(rep, KIT) {
+  await checkPackageOps(rep, KIT);
+  await checkRagDesigner(rep, KIT);
+  await checkL5ForgePath(rep, KIT);
+}