msd-core/tests/intel.test.cjs

/**
 * Tests for msd-core/bin/lib/intel.cjs
 *
 * Covers: query, status, diff, validate, snapshot, patch-meta,
 * extract-exports, enabled/disabled gating, and CLI routing via msd-tools.
 */
// allow-test-rule: source-text-is-the-product
// readFileSync assertions target API-SURFACE.md, which is the generated product of intelApiSurface; asserting on its text content is the only way to verify correct generation.

'use strict';

const { describe, test, beforeEach, afterEach } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('fs');
const path = require('path');
const { createTempProject, createTempDir, cleanup, runMsdTools } = require('./helpers.cjs');

const {
  intelQuery,
  intelStatus,
  intelDiff,
  intelValidate,
  intelSnapshot,
  intelPatchMeta,
  intelExtractExports,
  intelApiSurface,
  ensureIntelDir,
  isIntelCapabilityActive,
  INTEL_FILES,
} = require('../msd-core/bin/lib/intel.cjs');

const { isCapabilityActive } = require('../msd-core/bin/lib/capability-state.cjs');

// ─── Helpers ────────────────────────────────────────────────────────────────

function enableIntel(planningDir) {
  const configPath = path.join(planningDir, 'config.json');
  const config = fs.existsSync(configPath)
    ? JSON.parse(fs.readFileSync(configPath, 'utf8'))
    : {};
  config.intel = { enabled: true };
  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
}

function writeIntelJson(planningDir, filename, data) {
  const intelPath = path.join(planningDir, 'intel');
  fs.mkdirSync(intelPath, { recursive: true });
  fs.writeFileSync(
    path.join(intelPath, filename),
    JSON.stringify(data, null, 2),
    'utf8'
  );
}

function _writeIntelMd(planningDir, filename, content) {
  const intelPath = path.join(planningDir, 'intel');
  fs.mkdirSync(intelPath, { recursive: true });
  fs.writeFileSync(path.join(intelPath, filename), content, 'utf8');
}

// ─── Surfaced-config-dir fixture ──────────────────────────────────────────────
//
// Positive-path tests (intelQuery, intelStatus, etc.) call isCapabilityActive
// via the tri-state gate — they need the capability to be surfaced.
// Without this fixture those tests are ambient-dependent (pass only on machines
// where intel is surfaced in the real ~/.claude).
//
// Fix: point CLAUDE_CONFIG_DIR at a tmp dir containing a full-profile
// .msd-surface.json (no disabled clusters) so intel is surfaced deterministically.
// An EMPTY tmp config dir also works (defaults to 'full' profile → all surfaced)
// but we write the file explicitly for visible intent.

/** Create a tmp config dir with intel (and all caps) surfaced — full profile. */
function makeSurfacedConfigDir() {
  const dir = createTempDir('msd-intel-surface-cfg-');
  fs.writeFileSync(
    path.join(dir, '.msd-surface.json'),
    JSON.stringify({ baseProfile: 'full', disabledClusters: [], explicitAdds: [], explicitRemoves: [] }, null, 2) + '\n',
    'utf8',
  );
  return dir;
}

/** Save env vars touched by the surfaced-config fixture; returns .restore(). */
function saveSurfacedEnv() {
  const saved = {
    MSD_RUNTIME: process.env.MSD_RUNTIME,
    CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
    MSD_WORKSTREAM: process.env.MSD_WORKSTREAM,
    MSD_PROJECT: process.env.MSD_PROJECT,
  };
  return {
    restore() {
      if (saved.MSD_RUNTIME === undefined) delete process.env.MSD_RUNTIME;
      else process.env.MSD_RUNTIME = saved.MSD_RUNTIME;
      if (saved.CLAUDE_CONFIG_DIR === undefined) delete process.env.CLAUDE_CONFIG_DIR;
      else process.env.CLAUDE_CONFIG_DIR = saved.CLAUDE_CONFIG_DIR;
      if (saved.MSD_WORKSTREAM === undefined) delete process.env.MSD_WORKSTREAM;
      else process.env.MSD_WORKSTREAM = saved.MSD_WORKSTREAM;
      if (saved.MSD_PROJECT === undefined) delete process.env.MSD_PROJECT;
      else process.env.MSD_PROJECT = saved.MSD_PROJECT;
    },
  };
}

// ─── Disabled gating ────────────────────────────────────────────────────────

describe('intel disabled gating', () => {
  let tmpDir;
  let planningDir;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
  });

  afterEach(() => {
    cleanup(tmpDir);
  });

  // isIntelEnabled was removed in Phase 4 (tri-state cutover). These tests now
  // verify the gating via the public command API (intelQuery) and the exported
  // isIntelCapabilityActive helper which delegates to isCapabilityActive.
  test('isIntelCapabilityActive returns false when no config.json exists', () => {
    // No CLAUDE_CONFIG_DIR → defaults to real ~/.claude; no intel.enabled in config.
    // In a hermetic test environment (empty tmpDir), the capability is not surfaced
    // via the real config dir — but isCapabilityActive returns false by construction
    // when the activationKey (intel.enabled) is absent/false regardless of surface,
    // because: active = enabled && configActivation; configActivation=false when key absent.
    // This test is surface-agnostic for the "no config" branch.
    assert.strictEqual(isIntelCapabilityActive(planningDir), false);
  });

  test('isIntelCapabilityActive returns false when intel.enabled is not set', () => {
    fs.writeFileSync(
      path.join(planningDir, 'config.json'),
      JSON.stringify({ model_profile: 'balanced' }),
      'utf8'
    );
    assert.strictEqual(isIntelCapabilityActive(planningDir), false);
  });

  // NOTE: intel has `skills: []` (empty), so installed and surfaced are vacuously true.
  // For intel, active = configActivation (the intel.enabled config key).
  // This test verifies that isIntelCapabilityActive delegates to isCapabilityActive('intel', cwd)
  // and that the function returns a boolean without throwing, regardless of the ambient
  // CLAUDE_CONFIG_DIR. The config dimension is probed hermetically in the section below.
  test('isIntelCapabilityActive delegates to isCapabilityActive and returns a boolean (config=true, ambient surface)', () => {
    // Write config.intel.enabled=true (config dimension ON). Since intel has no skills,
    // surface is vacuously true — so this call returns true when the config is written
    // and the capability system resolves correctly.
    enableIntel(planningDir);
    // We cannot assert the exact value without full hermetic control of all three
    // tri-state dimensions (see hermetic section below for that), but we assert that:
    //   1. isIntelCapabilityActive delegates correctly (does not throw)
    //   2. it returns a boolean (not undefined/null/object)
    const result = isIntelCapabilityActive(planningDir);
    assert.strictEqual(typeof result, 'boolean', 'isIntelCapabilityActive must return a boolean');
  });

  test('intelQuery returns disabled response when intel is off', () => {
    const result = intelQuery('test', planningDir);
    assert.strictEqual(result.disabled, true);
    assert.ok(result.message.includes('disabled'));
  });

  test('intelStatus returns disabled response when intel is off', () => {
    const result = intelStatus(planningDir);
    assert.strictEqual(result.disabled, true);
  });

  test('intelDiff returns disabled response when intel is off', () => {
    const result = intelDiff(planningDir);
    assert.strictEqual(result.disabled, true);
  });

  test('intelValidate returns disabled response when intel is off', () => {
    const result = intelValidate(planningDir);
    assert.strictEqual(result.disabled, true);
  });
});

// ─── Tri-state gate hermetic regression tests ────────────────────────────────
//
// Intel capability has `skills: []` (empty) — so `installed` and `surfaced` are
// VACUOUSLY TRUE. For intel, `active = configActivation` where configActivation
// resolves the `activationKey` ("intel.enabled") via the config. This is a meaningful
// tri-state improvement because the old `isIntelEnabled` read config.json directly
// (synchronous file read, not wired through `loadConfig`), while the new gate goes
// through the full `resolveCapabilityRuntimeState` path.
//
// FAIL-FIRST PROOF (what would fail against the OLD isIntelEnabled code):
//   Scenario: intel installed (skills=[]) + config has intel.enabled=true, BUT the
//   surface has intel NOT surfaced via disabledClusters.
//
//   However: intel has skills:[], so disabledClusters:['intel'] has no effect
//   (no skills to remove from the surfaced set). Intel is always vacuously surfaced.
//
//   The CORRECT regression for intel's tri-state cutover is:
//     intel.enabled=true in config → isCapabilityActive=true → command NOT disabled
//     intel.enabled=false (or absent) → isCapabilityActive=false → command disabled
//   AND that the gate now goes through the shared resolver (not a direct config read).
//
//   FAIL-FIRST SCENARIO: OLD isIntelEnabled read config.json at the planningDir path
//   via platformReadSync. NEW isCapabilityActive uses resolveCapabilityRuntimeState
//   which goes through loadConfig (multi-layer resolution). A test that sets
//   intel.enabled=true in config then calls intelStatus would:
//     OLD: isIntelEnabled → reads .planning/config.json → true → NOT disabled.
//     NEW: isCapabilityActive → resolveCapabilityRuntimeState → configActivation=true → active=true → NOT disabled.
//   Both return the same, so the regression test focuses on the config-absent/false case
//   where the gate correctly returns disabled (proving the delegation path works).

describe('intel tri-state gate hermetic regression (isCapabilityActive cutover)', () => {
  let tmpConfigDir;
  let tmpProjectDir;
  let prevClaudeConfigDir;
  let prevMsdWorkstream;
  let prevMsdProject;

  beforeEach(() => {
    tmpConfigDir = createTempDir('msd-intel-tristate-cfg-');
    tmpProjectDir = createTempProject('msd-intel-tristate-proj-');

    prevClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
    prevMsdWorkstream = process.env.MSD_WORKSTREAM;
    prevMsdProject = process.env.MSD_PROJECT;
    // Empty CLAUDE_CONFIG_DIR (no .msd-surface.json) → defaults to 'full' profile.
    // Intel has skills:[] so it is vacuously installed+surfaced+enabled.
    // Active = configActivation = intel.enabled in config.
    process.env.CLAUDE_CONFIG_DIR = tmpConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    if (prevClaudeConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
    else process.env.CLAUDE_CONFIG_DIR = prevClaudeConfigDir;
    if (prevMsdWorkstream === undefined) delete process.env.MSD_WORKSTREAM;
    else process.env.MSD_WORKSTREAM = prevMsdWorkstream;
    if (prevMsdProject === undefined) delete process.env.MSD_PROJECT;
    else process.env.MSD_PROJECT = prevMsdProject;

    cleanup(tmpConfigDir);
    cleanup(tmpProjectDir);
  });

  // NEGATIVE CASE: config has NO intel.enabled (absent → defaults to false via activationKey).
  // OLD gate: isIntelEnabled reads config.json → no intel key → returns false → disabled.
  // NEW gate: isCapabilityActive → configActivation=false (intel.enabled default=false) → active=false → disabled.
  // Both return disabled. The test PROVES the gate is wired through isCapabilityActive and
  // the command intelStatus returns disabled — regression guard against losing the delegation.
  test('intelStatus returns disabled when intel.enabled is absent in config (hermetic tristate negative)', () => {
    // No config.json in planningDir — intel.enabled defaults to false.
    // OLD isIntelEnabled: reads .planning/config.json → not found → false → disabled.
    // NEW isCapabilityActive: intel.enabled default=false → configActivation=false → active=false → disabled.
    const planningDir = path.join(tmpProjectDir, '.planning');
    const result = intelStatus(planningDir);
    assert.strictEqual(
      result.disabled,
      true,
      'intelStatus must return disabled when intel.enabled is not set — ' +
      'both old and new gate must return disabled here; this is the regression guard for the delegation path',
    );
    assert.ok(
      typeof result.message === 'string' && result.message.length > 0,
      'disabled response must include a non-empty message',
    );
  });

  // POSITIVE CONTROL: intel.enabled=true in config → isCapabilityActive=true → NOT disabled.
  // This is the primary pass case that proves the NEW gate honours config-enabled.
  // OLD gate (isIntelEnabled) returns true. NEW gate (isCapabilityActive) also returns true.
  // The test confirms the behaviour is preserved after cutover.
  test('intelStatus NOT disabled when intel.enabled=true in config (hermetic tristate positive control)', () => {
    const planningDir = path.join(tmpProjectDir, '.planning');
    fs.mkdirSync(planningDir, { recursive: true });
    fs.writeFileSync(
      path.join(planningDir, 'config.json'),
      JSON.stringify({ intel: { enabled: true } }),
      'utf8',
    );

    const active = isCapabilityActive('intel', tmpProjectDir);
    assert.strictEqual(
      active,
      true,
      'isCapabilityActive must return true when intel.enabled=true and intel is vacuously installed+surfaced',
    );

    const result = intelStatus(planningDir);
    assert.ok(
      !result.disabled,
      'intelStatus must NOT return disabled when intel.enabled=true (positive control)',
    );
  });
});

// ─── ensureIntelDir ─────────────────────────────────────────────────────────

describe('ensureIntelDir', () => {
  let tmpDir;
  let planningDir;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
  });

  afterEach(() => {
    cleanup(tmpDir);
  });

  test('creates intel directory if it does not exist', () => {
    const intelPath = ensureIntelDir(planningDir);
    assert.ok(fs.existsSync(intelPath));
    assert.ok(intelPath.endsWith('intel'));
  });

  test('returns existing intel directory without error', () => {
    fs.mkdirSync(path.join(planningDir, 'intel'), { recursive: true });
    const intelPath = ensureIntelDir(planningDir);
    assert.ok(fs.existsSync(intelPath));
  });
});

// ─── intelQuery ─────────────────────────────────────────────────────────────

describe('intelQuery', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    // Harden: ensure intel is surfaced (tri-state gate requires install+surface+config).
    // Empty CLAUDE_CONFIG_DIR defaults to 'full' profile → all caps surfaced.
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('returns empty matches when no intel files exist', () => {
    const result = intelQuery('anything', planningDir);
    assert.strictEqual(result.total, 0);
    assert.deepStrictEqual(result.matches, []);
    assert.strictEqual(result.term, 'anything');
  });

  test('finds matches in JSON file keys', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {
        'src/auth/controller.ts': { size: 1024, type: 'typescript' },
        'src/utils/logger.ts': { size: 512, type: 'typescript' },
      },
    });

    const result = intelQuery('auth', planningDir);
    assert.strictEqual(result.total, 1);
    assert.strictEqual(result.matches[0].source, 'file-roles.json');
    assert.strictEqual(result.matches[0].entries[0].key, 'src/auth/controller.ts');
  });

  test('finds matches in JSON file values', () => {
    writeIntelJson(planningDir, 'dependency-graph.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {
        express: { version: '4.18.0', type: 'runtime', used_by: ['src/server.ts'] },
      },
    });

    const result = intelQuery('express', planningDir);
    assert.strictEqual(result.total, 1);
    assert.strictEqual(result.matches[0].entries[0].key, 'express');
  });

  test('search is case-insensitive', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      entries: {
        'src/AuthController.ts': { type: 'typescript' },
      },
    });

    const result = intelQuery('authcontroller', planningDir);
    assert.strictEqual(result.total, 1);
  });

  test('finds matches in arch-decisions.json entries', () => {
    writeIntelJson(planningDir, 'arch-decisions.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {
        'jwt-auth': { decision: 'Use JWT tokens for stateless authentication', status: 'accepted' },
        'rest-api': { decision: 'REST API endpoints for all services', status: 'accepted' },
      },
    });

    const result = intelQuery('JWT', planningDir);
    assert.strictEqual(result.total, 1);
    assert.strictEqual(result.matches[0].source, 'arch-decisions.json');
  });

  test('searches across multiple intel files', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      entries: { 'src/auth.ts': { exports: ['authenticate'] } },
    });
    writeIntelJson(planningDir, 'api-map.json', {
      entries: { '/api/auth': { method: 'POST', handler: 'authenticate' } },
    });

    const result = intelQuery('auth', planningDir);
    assert.strictEqual(result.total, 2);
    assert.strictEqual(result.matches.length, 2);
  });
});

// ─── #3885 (ADR-3473 §8.5): recursion bound + truncation signal ─────────────
//
// searchJsonEntries/matchesInValue lost the MAX_JSON_SEARCH_DEPTH=48 bound in
// the ADR-0174 SDK retirement. A deeply nested .planning/intel/*.json document
// overflows the call stack (uncaught RangeError, exit 1) instead of failing
// gracefully. Restoring the bound verbatim would trade the crash for a SILENT
// "no match" at depth 49+ — exactly the defect class this epic exists to close
// one layer down (ADR-3473 Decision 4: a routine that discards an input says
// so, naming the input). The required fix therefore pairs the bound with a
// truncation signal.
//
// DESIGN DECISION (chosen by this test file — not yet implemented): a
// top-level `truncated: boolean` field on the IntelQueryResult returned by
// intelQuery. `truncated` is true iff ANY searched intel file's walk hit the
// depth ceiling; false/absent otherwise. Chosen because it is the shape a
// JSON consumer (or the CLI's raw stdout) can read directly without parsing
// per-entry structure.
describe('#3885 (ADR-3473 §8.5): intel query recursion bound + truncation signal', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  // Build an object nested `n` levels deep: {a: {a: {a: ... {leaf: 'needle-here'}}}}.
  function nest(n) {
    let o = { leaf: 'needle-here' };
    for (let i = 0; i < n; i++) o = { a: o };
    return o;
  }

  function writeNestedFixture(depth) {
    writeIntelJson(planningDir, 'file-roles.json', { entries: { top: nest(depth) } });
  }

  // Build the SAME shape as nest(depth) — {a:{a:{a:...{leaf:'needle-here'}}}}
  // wrapped in {entries:{top:...}} — but as JSON TEXT via string .repeat(),
  // with zero recursion in the test process. Required for pathological depths
  // (thousands+): nest() + JSON.stringify() both recurse per level, so at
  // depth 12000 THE TEST'S OWN FIXTURE BUILDER overflows the test process's
  // stack before the CLI is ever spawned (V8's JSON.stringify recurses; its
  // JSON.parse does not). Do not "simplify" this back to
  // JSON.stringify(nest(n)) for large depths — that reintroduces a
  // macOS-green / Linux-red test, since Linux's default container stack is
  // smaller than macOS's.
  function writeNestedFixtureText(depth) {
    const intelPath = path.join(planningDir, 'intel');
    fs.mkdirSync(intelPath, { recursive: true });
    const json =
      '{"entries":{"top":' + '{"a":'.repeat(depth) + '{"leaf":"needle-here"}' + '}'.repeat(depth) + '}}';
    fs.writeFileSync(path.join(intelPath, 'file-roles.json'), json, 'utf8');
  }

  // T2 — MUST STAY GREEN before and after the fix: the ceiling is inclusive.
  test('T2: matchAtDepth48IsFoundUntruncated', () => {
    writeNestedFixture(48);
    const result = intelQuery('needle-here', planningDir);
    assert.strictEqual(result.total, 1, 'depth-48 match must still be found');
    assert.notStrictEqual(result.truncated, true, 'depth-48 (at the ceiling) must not report truncation');
  });

  // T3 — RED today: measured on this tree (e20744eac), depth 49 currently
  // returns total=1 (found), exit 0, with no `truncated` field at all.
  // Required: NOT returned as a match, AND the result reports truncation —
  // never a bare "no match".
  test('T3: matchAtDepth49IsNotSilentlyAbsent', () => {
    writeNestedFixture(49);
    const result = intelQuery('needle-here', planningDir);
    assert.strictEqual(result.total, 0, 'a match past the depth ceiling must not be reported as found');
    assert.deepStrictEqual(result.matches, [], 'no per-file match entries past the ceiling');
    assert.strictEqual(result.truncated, true, 'the result must say the search was truncated — never a bare "no match"');
  });

  // T4 — RED today: measured via the real CLI on this tree — depth 12000
  // exits 1 with stderr "Error: Maximum call stack size exceeded". Required:
  // exit 0, bounded result, truncated:true, and the RangeError text must
  // never appear.
  test('T4: deeplyNestedIntelDoesNotOverflowTheStack', () => {
    writeNestedFixtureText(12000);
    const result = runMsdTools(['intel', 'query', 'needle-here'], tmpDir);
    assert.strictEqual(result.success, true, `must exit 0 (no stack overflow), got: ${result.error}`);
    assert.ok(
      !/Maximum call stack size exceeded/.test(result.error || ''),
      `stderr must never contain the raw RangeError text, got: ${result.error}`,
    );
    const output = JSON.parse(result.output);
    assert.strictEqual(output.truncated, true, 'a 12000-deep document must report truncation');
  });

  // T5 — MUST STAY GREEN (N1): a shallow miss is not truncated. Stops the
  // flag becoming noise on every ordinary "not found" result.
  test('T5: shallowMissReportsNoTruncation', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      entries: { 'src/foo.ts': { type: 'typescript' } },
    });
    const result = intelQuery('needle-here', planningDir);
    assert.strictEqual(result.total, 0);
    assert.notStrictEqual(result.truncated, true, 'a shallow miss must not report truncation');
  });

  // T6 — MUST STAY GREEN (N2): the bound is on DEPTH, not breadth. 10,000
  // shallow siblings must not be mistaken for hitting the depth ceiling.
  test('T6: wideShallowDocumentIsUnaffectedByTheDepthBound', () => {
    const entries = {};
    for (let i = 0; i < 10000; i++) {
      entries[`sibling-${i}`] = { note: `filler ${i}` };
    }
    entries.target = { nested: { leaf: 'needle-here' } };
    writeIntelJson(planningDir, 'file-roles.json', { entries });

    const result = intelQuery('needle-here', planningDir);
    assert.strictEqual(result.total, 1, '10,000-sibling breadth must not suppress a shallow match');
    assert.notStrictEqual(result.truncated, true, 'breadth alone must never trigger the depth-truncation flag');
  });
});

// ─── #3885 (ADR-3473 §8.5): safeReadJson no-silent-swallow ──────────────────
//
// `safeReadJson` folded THREE distinct on-disk states into one bare `null`:
// absent (ENOENT), unreadable (EACCES/EIO/...), and malformed (JSON.parse
// throws). An unreadable or malformed intel file read as "no matches" —
// byte-indistinguishable from a project that simply lacks that intel file.
// This closes the gap: absent stays silent (the common, expected case —
// intelQuery already loops over every INTEL_FILES entry expecting misses),
// while unreadable/malformed are surfaced via the always-present
// `read_errors: string[]` field on IntelQueryResult, naming the file.
describe('#3885 (ADR-3473 §8.5): safeReadJson distinguishes absent from unreadable/malformed', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  // T7 — RED before the fix: an EACCES on a present intel file was swallowed
  // by safeReadJson's bare `catch { return null; }`, so intelQuery reported
  // total:0 with no way to distinguish "no matches" from "could not read
  // the file at all". Monkeypatch fs.readFileSync rather than chmod 0o000 —
  // root bypasses mode bits, so a chmod-based test would pass with zero
  // coverage under root Docker/CI.
  test('T7: unreadableIntelFileIsSurfacedNamingTheFile', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      entries: { 'src/foo.ts': { note: 'needle-here' } },
    });
    const targetPath = path.join(planningDir, 'intel', 'file-roles.json');
    const originalReadFileSync = fs.readFileSync;
    fs.readFileSync = function injectedEaccesFailure(p, ...args) {
      if (p === targetPath) {
        const err = new Error(`EACCES: permission denied, open '${targetPath}'`);
        err.code = 'EACCES';
        throw err;
      }
      return originalReadFileSync.call(fs, p, ...args);
    };
    try {
      const result = intelQuery('needle-here', planningDir);
      assert.strictEqual(result.total, 0, 'an unreadable file cannot contribute a match');
      assert.deepStrictEqual(result.matches, []);
      assert.ok(Array.isArray(result.read_errors), 'read_errors must always be present as an array');
      assert.strictEqual(result.read_errors.length, 1, 'exactly one file failed to read');
      assert.ok(
        result.read_errors[0].includes('file-roles.json'),
        `read_errors must name the unreadable file, got: ${result.read_errors[0]}`,
      );
    } finally {
      fs.readFileSync = originalReadFileSync;
    }
  });

  // T8 — RED before the fix: malformed JSON threw inside safeReadJson's
  // try block and was swallowed by the same bare catch, reading identically
  // to "no matches" — the same defect class as T7, one branch over.
  test('T8: malformedIntelFileIsSurfacedNamingTheFile', () => {
    const intelPath = path.join(planningDir, 'intel');
    fs.mkdirSync(intelPath, { recursive: true });
    fs.writeFileSync(path.join(intelPath, 'file-roles.json'), '{ this is not valid json', 'utf8');

    const result = intelQuery('anything', planningDir);
    assert.strictEqual(result.total, 0);
    assert.deepStrictEqual(result.matches, []);
    assert.strictEqual(result.read_errors.length, 1, 'exactly one file failed to parse');
    assert.ok(
      result.read_errors[0].includes('file-roles.json'),
      `read_errors must name the malformed file, got: ${result.read_errors[0]}`,
    );
  });

  // T9 — MUST STAY GREEN: an absent intel file is normal, not an error. Not
  // every project has every intel file, and intelQuery loops over the full
  // INTEL_FILES set expecting misses. This is the row that keeps the new
  // flag honest — without it, the fix would over-fire on every project that
  // simply lacks an intel file.
  test('T9: absentIntelFileStaysSilentlyAbsent', () => {
    const result = intelQuery('anything', planningDir);
    assert.strictEqual(result.total, 0);
    assert.deepStrictEqual(result.matches, []);
    assert.deepStrictEqual(result.read_errors, [], 'a merely-absent intel file must never be reported as a read error');
  });

  // T10 — MUST STAY GREEN: a readable file with genuinely no matches reports
  // no error at all. Stops the new flag from becoming noise on the
  // overwhelmingly common "not found" case.
  test('T10: readableFileWithGenuinelyNoMatchesReportsNoReadError', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      entries: { 'src/foo.ts': { type: 'typescript' } },
    });
    const result = intelQuery('zzz-nonexistent-term', planningDir);
    assert.strictEqual(result.total, 0);
    assert.strictEqual(result.truncated, false);
    assert.deepStrictEqual(result.read_errors, []);
  });
});

// ─── intelStatus ────────────────────────────────────────────────────────────

describe('intelStatus', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('reports missing files as stale', () => {
    const result = intelStatus(planningDir);
    assert.strictEqual(result.overall_stale, true);
    assert.strictEqual(result.files['file-roles.json'].exists, false);
    assert.strictEqual(result.files['file-roles.json'].stale, true);
  });

  test('reports fresh files as not stale', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {},
    });

    const result = intelStatus(planningDir);
    assert.strictEqual(result.files['file-roles.json'].exists, true);
    assert.strictEqual(result.files['file-roles.json'].stale, false);
  });

  test('reports old files as stale', () => {
    const oldDate = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString();
    writeIntelJson(planningDir, 'file-roles.json', {
      _meta: { updated_at: oldDate },
      entries: {},
    });

    const result = intelStatus(planningDir);
    assert.strictEqual(result.files['file-roles.json'].stale, true);
    assert.strictEqual(result.overall_stale, true);
  });
});

// ─── #3885 (ADR-3473 §8.5): intelStatus read_error field ────────────────────
//
// intelStatus threads safeReadJson's per-file outcome into `read_error` on
// the per-file IntelStatusFileEntry. Before this change, safeReadJson's bare
// catch made an unreadable or malformed file indistinguishable from a file
// that was simply never populated — both showed no way to tell staleness-
// by-neglect apart from staleness-by-read-failure. The fix adds the field to
// every entry: present as a string naming the file when the read/parse
// failed, null for the genuinely-quiet cases (absent, or readable-but-no-
// error).
describe('#3885 (ADR-3473 §8.5): intelStatus read_error field', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  // Monkeypatch fs.readFileSync rather than chmod 0o000 — root bypasses mode
  // bits, so a chmod-based test would pass with zero coverage under root
  // Docker/CI.
  test('unreadableFileReportsReadErrorNamingTheFile', () => {
    writeIntelJson(planningDir, 'file-roles.json', { entries: {} });
    const targetPath = path.join(planningDir, 'intel', 'file-roles.json');
    const originalReadFileSync = fs.readFileSync;
    fs.readFileSync = function injectedEaccesFailure(p, ...args) {
      if (p === targetPath) {
        const err = new Error(`EACCES: permission denied, open '${targetPath}'`);
        err.code = 'EACCES';
        throw err;
      }
      return originalReadFileSync.call(fs, p, ...args);
    };
    try {
      const result = intelStatus(planningDir);
      assert.strictEqual(typeof result.files['file-roles.json'].read_error, 'string');
      assert.ok(
        result.files['file-roles.json'].read_error.includes('file-roles.json'),
        `read_error must name the unreadable file, got: ${result.files['file-roles.json'].read_error}`,
      );
    } finally {
      fs.readFileSync = originalReadFileSync;
    }
  });

  test('malformedJsonReportsReadErrorNamingTheFile', () => {
    const intelPath = path.join(planningDir, 'intel');
    fs.mkdirSync(intelPath, { recursive: true });
    fs.writeFileSync(path.join(intelPath, 'file-roles.json'), '{ this is not valid json', 'utf8');

    const result = intelStatus(planningDir);
    assert.strictEqual(typeof result.files['file-roles.json'].read_error, 'string');
    assert.ok(
      result.files['file-roles.json'].read_error.includes('file-roles.json'),
      `read_error must name the malformed file, got: ${result.files['file-roles.json'].read_error}`,
    );
  });

  // MUST STAY GREEN: a merely-absent file is normal, not an error.
  test('absentFileReportsReadErrorNullNoError', () => {
    const result = intelStatus(planningDir);
    assert.strictEqual(result.files['file-roles.json'].exists, false);
    assert.strictEqual(
      result.files['file-roles.json'].read_error,
      null,
      'a merely-absent file must never be reported as a read error',
    );
  });
});

// ─── intelDiff ──────────────────────────────────────────────────────────────

describe('intelDiff', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('returns no_baseline when no snapshot exists', () => {
    const result = intelDiff(planningDir);
    assert.strictEqual(result.no_baseline, true);
  });

  test('detects added files since snapshot', () => {
    // Save an empty snapshot
    const intelPath = ensureIntelDir(planningDir);
    fs.writeFileSync(
      path.join(intelPath, '.last-refresh.json'),
      JSON.stringify({ hashes: {}, timestamp: new Date().toISOString(), version: 1 }),
      'utf8'
    );

    // Add a file after snapshot
    writeIntelJson(planningDir, 'file-roles.json', { entries: {} });

    const result = intelDiff(planningDir);
    assert.ok(result.added.includes('file-roles.json'));
  });

  test('detects changed files since snapshot', () => {
    // Write initial file
    writeIntelJson(planningDir, 'file-roles.json', { entries: { a: 1 } });

    // Take snapshot
    intelSnapshot(planningDir);

    // Modify file
    writeIntelJson(planningDir, 'file-roles.json', { entries: { a: 1, b: 2 } });

    const result = intelDiff(planningDir);
    assert.ok(result.changed.includes('file-roles.json'));
  });
});

// ─── #3885 (ADR-3473 §8.5): intelDiff read_error / no_baseline false-verdict ─
//
// Before this change intelDiff reported `no_baseline: true` for BOTH a
// genuinely-never-snapshotted project (ENOENT) AND a present-but-unreadable
// or malformed snapshot (EACCES/EIO/corrupt JSON) — folding an ACTIVELY
// FALSE verdict ("you never took a snapshot") over a read failure. This is
// ADR-3473 §8.5's headline case: silently swallowing the read error doesn't
// just hide information here, it manufactures a wrong answer. The fix adds
// `read_error: string | null` beside `no_baseline: true` so a caller can
// tell "no snapshot was ever taken" (read_error: null) from "a snapshot
// exists and I could not read it" (read_error: <string naming the file>).
describe('#3885 (ADR-3473 §8.5): intelDiff read_error / no_baseline false-verdict', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  // Monkeypatch fs.readFileSync rather than chmod 0o000 — root bypasses mode
  // bits, so a chmod-based test would pass with zero coverage under root
  // Docker/CI.
  test('unreadableSnapshotReportsReadErrorNamingTheFile', () => {
    const intelPath = ensureIntelDir(planningDir);
    const snapshotPath = path.join(intelPath, '.last-refresh.json');
    fs.writeFileSync(
      snapshotPath,
      JSON.stringify({ hashes: {}, timestamp: new Date().toISOString(), version: 1 }),
      'utf8',
    );
    const originalReadFileSync = fs.readFileSync;
    fs.readFileSync = function injectedEaccesFailure(p, ...args) {
      if (p === snapshotPath) {
        const err = new Error(`EACCES: permission denied, open '${snapshotPath}'`);
        err.code = 'EACCES';
        throw err;
      }
      return originalReadFileSync.call(fs, p, ...args);
    };
    try {
      const result = intelDiff(planningDir);
      assert.strictEqual(result.no_baseline, true);
      assert.strictEqual(typeof result.read_error, 'string');
      assert.ok(
        result.read_error.includes('.last-refresh.json'),
        `read_error must name the unreadable snapshot file, got: ${result.read_error}`,
      );
    } finally {
      fs.readFileSync = originalReadFileSync;
    }
  });

  test('malformedSnapshotReportsReadErrorNamingTheFile', () => {
    const intelPath = ensureIntelDir(planningDir);
    fs.writeFileSync(path.join(intelPath, '.last-refresh.json'), '{ this is not valid json', 'utf8');

    const result = intelDiff(planningDir);
    assert.strictEqual(result.no_baseline, true);
    assert.strictEqual(typeof result.read_error, 'string');
    assert.ok(
      result.read_error.includes('.last-refresh.json'),
      `read_error must name the malformed snapshot file, got: ${result.read_error}`,
    );
  });

  // MUST STAY GREEN: a project that never took a snapshot is normal, not an
  // error.
  test('absentSnapshotReportsReadErrorNullNoError', () => {
    const result = intelDiff(planningDir);
    assert.strictEqual(result.no_baseline, true);
    assert.strictEqual(
      result.read_error,
      null,
      'a project that never took a snapshot must never be reported as a read error',
    );
  });

  // THE FALSE-VERDICT TEST: `no_baseline: true` ALONE is the defect this
  // fix exists to close — it reads identically whether a snapshot was never
  // taken or a snapshot exists but could not be read/parsed. A caller must
  // be able to tell "no snapshot was ever taken" apart from "a snapshot
  // exists and I could not read it" directly from the return value.
  test('unreadableOrCorruptSnapshotIsDistinguishableFromNeverTookASnapshot_theFalseVerdictCase', () => {
    const neverSnapshotted = intelDiff(planningDir);
    assert.strictEqual(neverSnapshotted.no_baseline, true);
    assert.strictEqual(neverSnapshotted.read_error, null);

    const intelPath = ensureIntelDir(planningDir);
    fs.writeFileSync(path.join(intelPath, '.last-refresh.json'), '{ not json at all', 'utf8');
    const corruptSnapshot = intelDiff(planningDir);
    assert.strictEqual(
      corruptSnapshot.no_baseline,
      true,
      'a corrupt snapshot cannot be diffed against, so no_baseline correctly stays true',
    );
    assert.strictEqual(
      typeof corruptSnapshot.read_error,
      'string',
      'a corrupt snapshot MUST set read_error — otherwise it is byte-indistinguishable from ' +
      'never having snapshotted at all, which is the false verdict this fix exists to close',
    );
    assert.notStrictEqual(
      corruptSnapshot.read_error,
      neverSnapshotted.read_error,
      'the never-snapshotted and corrupt-snapshot cases must differ in the return value',
    );
  });
});

// ─── intelSnapshot ──────────────────────────────────────────────────────────

describe('intelSnapshot', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('saves snapshot with file hashes', () => {
    writeIntelJson(planningDir, 'file-roles.json', { entries: {} });

    const result = intelSnapshot(planningDir);
    assert.strictEqual(result.saved, true);
    assert.strictEqual(result.files, 1);
    assert.ok(result.timestamp);

    const snapshot = JSON.parse(
      fs.readFileSync(path.join(planningDir, 'intel', '.last-refresh.json'), 'utf8')
    );
    assert.ok(snapshot.hashes['file-roles.json']);
  });
});

// ─── intelValidate ──────────────────────────────────────────────────────────

describe('intelValidate', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('reports errors for missing files', () => {
    const result = intelValidate(planningDir);
    assert.strictEqual(result.valid, false);
    assert.ok(result.errors.length > 0);
    assert.ok(result.errors.some(e => e.includes('does not exist')));
  });

  test('reports warnings for missing _meta.updated_at', () => {
    writeIntelJson(planningDir, 'file-roles.json', { entries: {} });
    writeIntelJson(planningDir, 'api-map.json', { entries: {} });
    writeIntelJson(planningDir, 'dependency-graph.json', { entries: {} });
    writeIntelJson(planningDir, 'stack.json', { entries: {} });
    writeIntelJson(planningDir, 'arch-decisions.json', { entries: {} });

    const result = intelValidate(planningDir);
    assert.strictEqual(result.valid, true);
    assert.ok(result.warnings.some(w => w.includes('missing _meta.updated_at')));
  });

  test('reports invalid JSON as error', () => {
    const intelPath = path.join(planningDir, 'intel');
    fs.mkdirSync(intelPath, { recursive: true });
    fs.writeFileSync(path.join(intelPath, 'file-roles.json'), 'not valid json', 'utf8');
    writeIntelJson(planningDir, 'api-map.json', { entries: {} });
    writeIntelJson(planningDir, 'dependency-graph.json', { entries: {} });
    writeIntelJson(planningDir, 'stack.json', { entries: {} });
    writeIntelJson(planningDir, 'arch-decisions.json', { entries: {} });

    const result = intelValidate(planningDir);
    assert.strictEqual(result.valid, false);
    assert.ok(result.errors.some(e => e.includes('invalid JSON')));
  });

  test('passes validation with complete fresh intel', () => {
    const now = new Date().toISOString();
    writeIntelJson(planningDir, 'file-roles.json', {
      _meta: { updated_at: now },
      entries: {},
    });
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: now },
      entries: {},
    });
    writeIntelJson(planningDir, 'dependency-graph.json', {
      _meta: { updated_at: now },
      entries: {},
    });
    writeIntelJson(planningDir, 'stack.json', {
      _meta: { updated_at: now },
      entries: {},
    });
    writeIntelJson(planningDir, 'arch-decisions.json', {
      _meta: { updated_at: now },
      entries: {},
    });

    const result = intelValidate(planningDir);
    assert.strictEqual(result.valid, true);
    assert.strictEqual(result.errors.length, 0);
  });
});

// ─── intelPatchMeta ─────────────────────────────────────────────────────────

describe('intelPatchMeta', () => {
  let tmpDir;
  let planningDir;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
  });

  afterEach(() => {
    cleanup(tmpDir);
  });

  test('patches _meta.updated_at and increments version', () => {
    writeIntelJson(planningDir, 'file-roles.json', {
      _meta: { updated_at: '2025-01-01T00:00:00Z', version: 1 },
      entries: {},
    });

    const filePath = path.join(planningDir, 'intel', 'file-roles.json');
    const result = intelPatchMeta(filePath);

    assert.strictEqual(result.patched, true);

    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
    assert.strictEqual(data._meta.version, 2);
    assert.notStrictEqual(data._meta.updated_at, '2025-01-01T00:00:00Z');
  });

  test('creates _meta if missing', () => {
    writeIntelJson(planningDir, 'file-roles.json', { entries: {} });

    const filePath = path.join(planningDir, 'intel', 'file-roles.json');
    const result = intelPatchMeta(filePath);

    assert.strictEqual(result.patched, true);

    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
    assert.ok(data._meta.updated_at);
    assert.strictEqual(data._meta.version, 1);
  });

  test('returns error for missing file', () => {
    const result = intelPatchMeta('/nonexistent/file.json');
    assert.strictEqual(result.patched, false);
    assert.ok(result.error.includes('not found'));
  });

  test('returns error for invalid JSON', () => {
    const filePath = path.join(tmpDir, 'bad.json');
    fs.writeFileSync(filePath, 'not json', 'utf8');

    const result = intelPatchMeta(filePath);
    assert.strictEqual(result.patched, false);
    assert.ok(result.error.includes('Invalid JSON'));
  });
});

// ─── intelExtractExports ────────────────────────────────────────────────────

describe('intelExtractExports', () => {
  let tmpDir;

  beforeEach(() => {
    tmpDir = createTempProject();
  });

  afterEach(() => {
    cleanup(tmpDir);
  });

  test('extracts CJS module.exports object keys', () => {
    const filePath = path.join(tmpDir, 'example.cjs');
    fs.writeFileSync(filePath, [
      "'use strict';",
      'function doStuff() {}',
      'function helper() {}',
      'module.exports = {',
      '  doStuff,',
      '  helper,',
      '};',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'module.exports');
    assert.ok(result.exports.includes('doStuff'));
    assert.ok(result.exports.includes('helper'));
  });

  test('extracts ESM named exports', () => {
    const filePath = path.join(tmpDir, 'example.mjs');
    fs.writeFileSync(filePath, [
      'export function greet() {}',
      'export const VERSION = "1.0";',
      'export class Widget {}',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'esm');
    assert.ok(result.exports.includes('greet'));
    assert.ok(result.exports.includes('VERSION'));
    assert.ok(result.exports.includes('Widget'));
  });

  test('extracts ESM export block', () => {
    const filePath = path.join(tmpDir, 'example.js');
    fs.writeFileSync(filePath, [
      'function foo() {}',
      'function bar() {}',
      'export { foo, bar };',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.ok(result.exports.includes('foo'));
    assert.ok(result.exports.includes('bar'));
  });

  test('returns empty exports for nonexistent file', () => {
    const result = intelExtractExports('/nonexistent/file.js');
    assert.deepStrictEqual(result.exports, []);
    assert.strictEqual(result.method, 'none');
  });

  // ── Behavior-lock: dedup + order (green before AND after Set conversion) ──

  test('dedup: duplicate exports.X assignments yield each name exactly once', () => {
    // exports.foo appears twice — result must contain 'foo' exactly once
    const filePath = path.join(tmpDir, 'dedup-exports-x.cjs');
    fs.writeFileSync(filePath, [
      "'use strict';",
      'exports.foo = 1;',
      'exports.bar = 2;',
      'exports.foo = 3;',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'exports.X');
    assert.deepStrictEqual(result.exports, ['foo', 'bar']);
  });

  test('order: CJS exports.X preserves first-seen insertion order', () => {
    // Names appear in source order: charlie, alpha, bravo
    const filePath = path.join(tmpDir, 'order-cjs.cjs');
    fs.writeFileSync(filePath, [
      "'use strict';",
      'exports.charlie = 1;',
      'exports.alpha = 2;',
      'exports.bravo = 3;',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'exports.X');
    assert.deepStrictEqual(result.exports, ['charlie', 'alpha', 'bravo']);
  });

  test('dedup: ESM export block with repeated name yields name exactly once', () => {
    // export { foo, foo } — foo must appear once
    const filePath = path.join(tmpDir, 'dedup-esm-block.mjs');
    fs.writeFileSync(filePath, [
      'function foo() {}',
      'export { foo, foo };',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'esm');
    assert.deepStrictEqual(result.exports, ['foo']);
  });

  test('merge order: CJS exports appear before ESM exports, each name once', () => {
    // exports.X = CJS side; export function / export const = ESM side
    // Expected order: CJS-first then ESM additions
    const filePath = path.join(tmpDir, 'merge-order.mjs');
    fs.writeFileSync(filePath, [
      "exports.cjsFirst = 1;",
      "export function esmSecond() {}",
      "export const esmThird = 3;",
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'mixed');
    assert.deepStrictEqual(result.exports, ['cjsFirst', 'esmSecond', 'esmThird']);
  });

  test('export default collapse: only export default (anon) yields ["default"]', () => {
    // A file with only `export default <value>` — no named exports, no default fn/class
    // The collapse guard (esmExports.length === 0 at time of check) produces ["default"]
    const filePath = path.join(tmpDir, 'default-only.mjs');
    fs.writeFileSync(filePath, 'export default 42;', 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'esm');
    assert.deepStrictEqual(result.exports, ['default']);
  });

  test('export default collapse: export default fn + named exports — no "default" collapse', () => {
    // export default function myFunc() {} → myFunc is extracted (named default fn)
    // export const named → also extracted
    // "default" literal does NOT appear because esmExports is not empty when anon-default check runs
    const filePath = path.join(tmpDir, 'default-fn-plus-named.mjs');
    fs.writeFileSync(filePath, [
      'export default function myFunc() {}',
      'export const named = 1;',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.strictEqual(result.method, 'esm');
    assert.deepStrictEqual(result.exports, ['myFunc', 'named']);
  });

  test('return shape: exports is a plain Array (callers use .includes/.length)', () => {
    const filePath = path.join(tmpDir, 'shape-check.cjs');
    fs.writeFileSync(filePath, [
      "'use strict';",
      'exports.foo = 1;',
    ].join('\n'), 'utf8');

    const result = intelExtractExports(filePath);
    assert.ok(Array.isArray(result.exports), 'exports must be a plain Array');
    assert.ok('file' in result, 'result must have file field');
    assert.ok('method' in result, 'result must have method field');
  });
});

// ─── CLI routing via msd-tools ──────────────────────────────────────────────

describe('msd-tools intel subcommands', () => {
  let tmpDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    // Set up surfaced config dir for positive-path CLI tests (subprocess inherits env).
    // Negative-path tests (disabled) still work because intel.enabled is not set by default.
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('intel status returns disabled message when not enabled', () => {
    const result = runMsdTools(['intel', 'status'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.strictEqual(output.disabled, true);
  });

  test('intel query returns disabled message when not enabled', () => {
    const result = runMsdTools(['intel', 'query', 'test'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.strictEqual(output.disabled, true);
  });

  test('intel status returns file status when enabled', () => {
    enableIntel(path.join(tmpDir, '.planning'));
    const result = runMsdTools(['intel', 'status'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.ok(output.files);
    assert.strictEqual(output.overall_stale, true);
  });

  test('intel validate reports errors for missing files when enabled', () => {
    enableIntel(path.join(tmpDir, '.planning'));
    const result = runMsdTools(['intel', 'validate'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.strictEqual(output.valid, false);
    assert.ok(output.errors.length > 0);
  });

  test('unknown intel subcommand error lists api-surface', () => {
    const result = runMsdTools(['intel', 'nonexistent-subcmd'], tmpDir);
    assert.strictEqual(result.success, false);
    const errorText = result.error || '';
    assert.ok(errorText.includes('api-surface'), 'error message must list api-surface');
  });

  test('flag-looking intel subcommand treated as unknown, not crash', () => {
    const result = runMsdTools(['intel', '--api-surface'], tmpDir);
    assert.strictEqual(result.success, false);
    const errorText = result.error || '';
    assert.ok(errorText.includes('Unknown intel subcommand'), 'must emit typed unknown-subcommand error');
  });

  test('intel api-surface returns disabled message when not enabled', () => {
    const result = runMsdTools(['intel', 'api-surface'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.strictEqual(output.disabled, true);
  });

  test('intel api-surface writes API-SURFACE.md when enabled with populated api-map.json', () => {
    const planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {
        'intelQuery': { method: 'function', handler: 'intelQuery', role: 'query intel files' },
        'intelStatus': { method: 'function', handler: 'intelStatus', role: 'report freshness' },
      },
    });
    const result = runMsdTools(['intel', 'api-surface'], tmpDir);
    assert.strictEqual(result.success, true);
    const output = JSON.parse(result.output);
    assert.ok(output.written, 'result must include written path');
    assert.strictEqual(output.symbolCount, 2);
    const mdContent = fs.readFileSync(output.written, 'utf8');
    assert.ok(mdContent.includes('intelQuery'), 'API-SURFACE.md must list intelQuery symbol');
    assert.ok(mdContent.includes('intelStatus'), 'API-SURFACE.md must list intelStatus symbol');
  });
});

// ─── intelApiSurface ────────────────────────────────────────────────────────

describe('intelApiSurface', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  test('returns disabled response when intel is off', () => {
    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.disabled, true);
    assert.ok(result.message.includes('disabled'));
  });

  test('writes API-SURFACE.md with symbol entries from api-map.json', () => {
    enableIntel(planningDir);
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {
        'authenticate': { method: 'POST', handler: 'authController', role: 'user login' },
        'createUser': { method: 'POST', handler: 'userController', role: 'user registration' },
      },
    });

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.symbolCount, 2);
    assert.ok(result.written.endsWith('API-SURFACE.md'));

    const content = fs.readFileSync(result.written, 'utf8');
    assert.ok(content.includes('authenticate'), 'must include symbol name authenticate');
    assert.ok(content.includes('createUser'), 'must include symbol name createUser');
    assert.ok(content.includes('authController'), 'must include field value authController');
  });

  test('writes API-SURFACE.md with incomplete banner when api-map.json is absent', () => {
    enableIntel(planningDir);
    // No api-map.json written

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.symbolCount, 0);
    assert.ok(result.written.endsWith('API-SURFACE.md'));

    const content = fs.readFileSync(result.written, 'utf8');
    assert.ok(content.includes('Incomplete'), 'must contain Incomplete banner when no entries');
    assert.ok(content.includes('unknown'), 'must say treat absence as "unknown"');
  });

  test('writes API-SURFACE.md with incomplete banner when entries is empty object', () => {
    enableIntel(planningDir);
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: {},
    });

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.symbolCount, 0);

    const content = fs.readFileSync(result.written, 'utf8');
    assert.ok(content.includes('Incomplete'), 'empty entries must still emit incomplete banner');
  });

  test('returns stale=false for fresh api-map.json', () => {
    enableIntel(planningDir);
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: new Date().toISOString() },
      entries: { 'myFunc': { method: 'function' } },
    });

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.stale, false);
  });

  test('returns stale=true for old api-map.json', () => {
    enableIntel(planningDir);
    const oldDate = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString();
    writeIntelJson(planningDir, 'api-map.json', {
      _meta: { updated_at: oldDate },
      entries: { 'myFunc': { method: 'function' } },
    });

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.stale, true);
  });

  test('return shape has written, symbolCount, stale fields', () => {
    enableIntel(planningDir);
    const result = intelApiSurface(planningDir);
    assert.ok('written' in result, 'result must have written field');
    assert.ok('symbolCount' in result, 'result must have symbolCount field');
    assert.ok('stale' in result, 'result must have stale field');
  });
});

// ─── #3885 (ADR-3473 §8.5): intelApiSurface read_error + Incomplete banner ──
//
// intelApiSurface's `symbolCount === 0` branch used to mean ONE thing:
// "api-map.json is absent or not yet populated" — the banner text said so
// unconditionally. An unreadable or malformed api-map.json also produced
// symbolCount:0, so the banner LIED, attributing a read failure to "not yet
// populated". The fix adds `read_error: string | null` to the return value
// and swaps the banner text to the actual reason (`readError`) when one is
// present.
describe('#3885 (ADR-3473 §8.5): intelApiSurface read_error + Incomplete banner', () => {
  let tmpDir;
  let planningDir;
  let surfacedConfigDir;
  let savedEnv;

  beforeEach(() => {
    tmpDir = createTempProject();
    planningDir = path.join(tmpDir, '.planning');
    enableIntel(planningDir);
    surfacedConfigDir = makeSurfacedConfigDir();
    savedEnv = saveSurfacedEnv();
    delete process.env.MSD_RUNTIME;
    process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
    delete process.env.MSD_WORKSTREAM;
    delete process.env.MSD_PROJECT;
  });

  afterEach(() => {
    savedEnv.restore();
    cleanup(surfacedConfigDir);
    cleanup(tmpDir);
  });

  // Monkeypatch fs.readFileSync rather than chmod 0o000 — root bypasses mode
  // bits, so a chmod-based test would pass with zero coverage under root
  // Docker/CI.
  test('unreadableApiMapReportsReadErrorAndTheBannerSaysSo', () => {
    writeIntelJson(planningDir, 'api-map.json', { entries: {} });
    const targetPath = path.join(planningDir, 'intel', 'api-map.json');
    const originalReadFileSync = fs.readFileSync;
    fs.readFileSync = function injectedEaccesFailure(p, ...args) {
      if (p === targetPath) {
        const err = new Error(`EACCES: permission denied, open '${targetPath}'`);
        err.code = 'EACCES';
        throw err;
      }
      return originalReadFileSync.call(fs, p, ...args);
    };
    try {
      const result = intelApiSurface(planningDir);
      assert.strictEqual(result.symbolCount, 0);
      assert.strictEqual(typeof result.read_error, 'string');
      assert.ok(
        result.read_error.includes('api-map.json'),
        `read_error must name the unreadable file, got: ${result.read_error}`,
      );
      const content = fs.readFileSync(result.written, 'utf8');
      assert.ok(
        content.includes(result.read_error),
        'the Incomplete banner must state the actual read failure, not the generic "not yet populated" text',
      );
      assert.ok(
        !content.includes('not yet populated'),
        'a read failure must not be misreported as "not yet populated"',
      );
    } finally {
      fs.readFileSync = originalReadFileSync;
    }
  });

  test('malformedApiMapReportsReadErrorAndTheBannerSaysSo', () => {
    const intelPath = path.join(planningDir, 'intel');
    fs.mkdirSync(intelPath, { recursive: true });
    fs.writeFileSync(path.join(intelPath, 'api-map.json'), '{ this is not valid json', 'utf8');

    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.symbolCount, 0);
    assert.strictEqual(typeof result.read_error, 'string');
    assert.ok(
      result.read_error.includes('api-map.json'),
      `read_error must name the malformed file, got: ${result.read_error}`,
    );
    const content = fs.readFileSync(result.written, 'utf8');
    assert.ok(
      content.includes(result.read_error),
      'the Incomplete banner must state the actual parse failure, not the generic "not yet populated" text',
    );
  });

  // MUST STAY GREEN: an absent api-map.json is normal, not an error — keeps
  // the original "not yet populated" banner text.
  test('absentApiMapReportsReadErrorNullNoError', () => {
    const result = intelApiSurface(planningDir);
    assert.strictEqual(result.symbolCount, 0);
    assert.strictEqual(
      result.read_error,
      null,
      'an absent api-map.json must never be reported as a read error',
    );
    const content = fs.readFileSync(result.written, 'utf8');
    assert.ok(
      content.includes('not yet populated'),
      'absence keeps the original "not yet populated" banner text',
    );
  });
});

describe('#1000 regression: msd-intel-updater emits canonical intel filenames', () => {
  // allow-test-rule: source-text-is-the-product
  // agents/msd-intel-updater.md IS the system prompt the intel-updater agent runs under; asserting its filename references
  // verifies the deployed agent surface contract matches the INTEL_FILES the CLI reads.
  const agentPromptPath = path.join(__dirname, '..', 'agents', 'msd-intel-updater.md');
  const agentPrompt = fs.readFileSync(agentPromptPath, 'utf8');

  test('references every canonical INTEL_FILES name', () => {
    for (const filename of Object.values(INTEL_FILES)) {
      assert.ok(
        agentPrompt.includes(filename),
        `msd-intel-updater.md must instruct writing the canonical intel file "${filename}" (from INTEL_FILES) that the msd-tools intel CLI reads; it was missing.`,
      );
    }
  });

  test('does not reference orphaned short filenames the CLI never reads', () => {
    // Short forms `${key}.json` that are NOT canonical INTEL_FILES values are orphaned —
    // the agent must not emit them. Also forbid the markdown arch.md output.
    const canonical = new Set(Object.values(INTEL_FILES));
    const forbidden = Object.keys(INTEL_FILES)
      .map((k) => `${k}.json`)
      .filter((short) => !canonical.has(short));
    forbidden.push('arch.md');
    for (const shortName of forbidden) {
      // Guard against substring false-positives (e.g. 'files.json' inside 'file-roles.json'):
      // canonical long names never contain these short tokens, verified by the canonical set.
      const offendingLines = agentPrompt
        .split(/\r?\n/)
        .filter((line) => line.includes(shortName));
      assert.strictEqual(
        offendingLines.length,
        0,
        `msd-intel-updater.md must not reference orphaned short name "${shortName}" the intel CLI never reads. Offending line(s):\n${offendingLines.join('\n')}`,
      );
    }
  });
});


// ────────────────────────────────────────────────────────────────────────
// Folded from tests/bug-3258-no-stale-msd-intel-references.test.cjs — consolidation epic #1969 (B3 #1972)
// ────────────────────────────────────────────────────────────────────────
{
  const { describe: __foldDescribe } = require('node:test');
  __foldDescribe("folded:bug-3258-no-stale-msd-intel-references (consolidation epic #1969 B3 #1972)", () => {
// allow-test-rule: source-text-is-the-product — workflow, reference, and docs .md files (see #3258)
// ARE what the runtime loads and what users read; asserting their text content
// tests the deployed skill surface contract, not implementation internals.

'use strict';

// Regression tests for bug #3258.
//
// PR #2790 folded `/msd-intel` into `/msd-map-codebase --query`. After that
// consolidation, five prose occurrences in two source files continued to
// reference the retired `/msd-intel` slash command. Users invoking the wizard
// were directed to a command that no longer exists.
//
// Fix: replace each `/msd-intel` (the retired user-facing slash command) with
// `/msd-map-codebase --query` in:
//   - msd-core/references/planning-config.md
//   - msd-core/workflows/settings.md
//   - docs/INVENTORY.md
//   - docs/USER-GUIDE.md
//   - docs/FEATURES.md
//
// Allowed: `msd-intel-updater` (still-valid agent name, no leading slash),
//          `intel.cjs` / `intel.enabled` / `intel.*` (internal backend, not user command),
//          CHANGELOG.md (historical record), test files themselves.
//
// This test distinguishes `/msd-intel` (the retired slash command, leading slash)
// from `msd-intel-updater` (still-valid agent) by grepping for the literal
// string `/msd-intel` and then asserting no match survives after excluding
// the `-updater` suffix.

const { describe, test } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');

const ROOT = path.join(__dirname, '..');

/** Walk a directory recursively and return absolute paths of all .md files. */
function walkMd(dir) {
  const results = [];
  if (!fs.existsSync(dir)) return results;
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const abs = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      results.push(...walkMd(abs));
    } else if (entry.isFile() && entry.name.endsWith('.md')) {
      results.push(abs);
    }
  }
  return results;
}

/**
 * Return all lines in `src` that contain `/msd-intel` (the retired slash
 * command) but are NOT the agent name `msd-intel-updater`.
 * We match the literal substring `/msd-intel` (with leading slash) and then
 * exclude any line where the match is immediately followed by `-updater`.
 */
function staleLinesIn(src) {
  return src.split('\n').filter((line) => {
    if (!line.includes('/msd-intel')) return false;
    // Remove all occurrences of the valid agent name; if nothing remains, skip.
    const stripped = line.replace(/\/msd-intel-updater/g, '');
    return stripped.includes('/msd-intel');
  });
}

const SOURCE_DIRS = [
  path.join(ROOT, 'commands', 'msd'),
  path.join(ROOT, 'msd-core', 'workflows'),
  path.join(ROOT, 'msd-core', 'references'),
  path.join(ROOT, 'agents'),
  path.join(ROOT, 'docs'),
];

describe('#3258: no stale /msd-intel slash-command references in product source dirs', () => {
  for (const dir of SOURCE_DIRS) {
    const files = walkMd(dir);
    for (const file of files) {
      const rel = path.relative(ROOT, file);

      // Allowed exclusions:
      // - CHANGELOG.md is a historical record; /msd-intel appears in release notes
      // - test files (under tests/) are excluded automatically by SOURCE_DIRS scope
      if (rel === 'CHANGELOG.md') continue;

      test(`${rel} has no stale /msd-intel references`, () => {
        let src;
        try {
          src = fs.readFileSync(file, 'utf8');
        } catch (err) {
          throw new Error(`failed reading ${rel}: ${err.message}`);
        }

        const staleLines = staleLinesIn(src);
        assert.strictEqual(
          staleLines.length,
          0,
          [
            `${rel} contains ${staleLines.length} stale /msd-intel reference(s).`,
            'Replace with /msd-map-codebase --query (retired by PR #2790).',
            'Stale lines:',
            ...staleLines.map((l) => `  ${l.trim()}`),
          ].join('\n'),
        );
      });
    }
  }
});
  });
}