golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

enhance(#3885): no silent swallow, and no verdict manufactured from dropped data (#3925)

Browse Source 
* test(#3885): failing-first coverage for the depth bound and the manufactured wave verdict

ADR-3473 §8.5 says a swallowed failure may not become an authoritative-looking
answer. Three families do exactly that today; this commit pins each one RED.

Measured on this tree, 2026-08-27:

  intel query, .planning/intel/file-roles.json nested 12000 deep
    -> exit 1, "Error: Maximum call stack size exceeded"
       searchJsonEntries / matchesInValue carry no depth parameter at all.
       The MAX_JSON_SEARCH_DEPTH = 48 bound existed in the retired SDK lineage
       (sdk/src/query/intel.ts at 11918dcc3^) and the surviving .cts lineage
       never received it.

  same fixture nested 48 and 49 deep
    -> both return total=1 at exit 0, truncated=undefined
       Nothing distinguishes "searched to the bottom" from "stopped looking".

  query phase-plan-index, a plan whose depends_on names an unresolvable token
    -> warnings: ["Plan 03-02: declared wave: 2 but depends_on DAG places it
                  in wave 1"]
       The token is never mentioned. computeDependencyLevels drops the edge
       with `if (!resolvedDep) continue;`, every plan becomes a root, and the
       tool then reports the author's correct wave: as the thing that is wrong.

  countPhasePlansAndSummaries with fs.readdirSync throwing EACCES
    -> hasContext:false, indistinguishable from a phase that simply has no
       CONTEXT.md. context_read_error is undefined.

The shapes these tests assert against, chosen here so the implementation has a
target rather than inventing one later: `truncated: boolean` on the intel query
result, `unresolved: Array<{plan, token}>` from computeDependencyLevels, and
`context_read_error: string | null` per analyzed phase.

Deliberately green, and they must stay that way — each stops the fix from
over-firing:

  depth 48 is found and NOT flagged truncated (the ceiling is inclusive)
  a shallow miss reports no truncation           (noise control, N1)
  10,000 siblings at depth 2 are unaffected      (the bound is DEPTH, N2)
  a genuine wave: mismatch on a fully-resolved DAG still warns (N3)
  a genuinely missing directory is absent, not an error
  the emitted depends_on display mapping still passes an unresolved token
    through verbatim — already pinned by the existing #3785 test, so no
    duplicate was added

T31 asserts at the consumer's output per ADR-3180 Decision 4(b): it runs the
real CLI and reads the emitted JSON, because a unit assertion on
computeDependencyLevels would have passed throughout #3427's life.

Design:      .gsd/phase/feat-3885-no-silent-swallow/40-design.md
Test matrix: .gsd/phase/feat-3885-no-silent-swallow/50-test-matrix.md

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* enhance(#3885): no silent swallow, and no verdict manufactured from dropped data

Implements ADR-3473 §8.5. A failure or a gap in the input stops being absorbed
into an output that reads as authoritative.

The recursion bound, restored but NOT verbatim (src/intel.cts)

  MAX_JSON_SEARCH_DEPTH = 48 is threaded through searchJsonEntries and
  matchesInValue, which carried no depth parameter at all. The bound existed in
  the retired SDK lineage (sdk/src/query/intel.ts at 11918dcc3^) and the
  surviving .cts lineage never received it — §8.3's "a consolidation may not
  delete an invariant along with the surface that held it", demonstrated.

  Measured before: a .planning/intel file nested 12000 deep exits 1 with
  "Error: Maximum call stack size exceeded". Reachable from a project document.

  The original returned a bare `false` at the ceiling. Restoring that verbatim
  would trade a crash for a silent "no match" when the truth is "I stopped
  looking" — the same class this epic exists to close, and ADR-3473 Decision 4
  forbids it. So the bound carries a truncation signal:

    nesting 47 -> found,     truncated false
    nesting 48 -> found,     truncated false      (the ceiling is inclusive)
    nesting 49 -> not found, truncated TRUE
    nesting 12000 -> exit 0, truncated TRUE, no RangeError

  A shallow document that simply has no match reports truncated FALSE — the
  flag means "I stopped early", never "I found nothing", or it would be noise.
  The bound is on DEPTH: 10,000 siblings at depth 2 are unaffected.

The dropped edge is named, and stops being blamed on the author (src/phase.cts)

  computeDependencyLevels dropped every unresolvable depends_on token with a
  bare `continue`. Each drop makes a plan a root, so the whole phase collapses
  to wave 1 — and cmdPhasePlanIndex then reported the author's CORRECT wave: as
  the thing that was wrong.

  Before:
    warnings: ["Plan 03-02: declared wave: 2 but depends_on DAG places it in
                wave 1"]
  After:
    warnings: ["Plan 03-02: depends_on token \"nonexistent-token-3427\" does not
                resolve to any plan in this phase — edge dropped, wave placement
                for this plan may be unreliable"]

  The suppression is PER PLAN, never blanket: a plan with a fully-resolved DAG
  and a genuinely wrong wave: still gets the mismatch warning. resolveDependencyId
  stays two-tier — the shortFormToId third tier is §8.3/Phase 6's rule and is
  deliberately not built here. The emitted depends_on display mapping still
  passes an unresolved token through verbatim (#3785).

No artifact from failed inputs (gsd-core/workflows/review.md, #3352)

  A failed lane leaves no result file, so "every lane failed" is exactly "the
  aggregate JSONL has zero lines" — the gate condition already existed as a
  byproduct. REVIEWS.md is no longer written in that case, and the commit step
  is skipped with it. A budget-SKIPPED lane also leaves no file and is NOT
  counted as a failure. Per-lane output and non-empty .err are preserved to
  .review-diagnostics/ before `rm -rf "{run_dir}"` destroys the only record that
  the lanes failed at all; the commit step names one file, never a glob, so the
  diagnostics are not swept in.

Unreadable is not absent (roadmap.cts, gap-checker.cts, init.cts x2)

  Four callers collapsed an EACCES on a phase directory into [] and reported
  hasContext:false — byte-identical to a phase that simply has no CONTEXT.md.
  Each now names the directory it could not read. A genuinely missing directory
  stays absent rather than becoming an error, which is what keeps the fix from
  over-firing.

Fatal errno folded into a retry set: audited, no defect found

  Reported as a verified negative rather than padded with a change.
  withPlanningLock was fixed by #1884/PR #3472; acquireStateLock by #3776;
  atomicRenameWithRetry and estimate-cli's renameWithRetry are correct by
  construction — bounded set {EPERM,EBUSY,EACCES}, bounded attempts, and they
  return or rethrow the final error rather than swallowing it. estimate-cli's
  sole caller surfaces that rethrow as write_error in its JSON output.
  Manufacturing a diff to make the checkbox look worked-on is the Goodhart
  outcome Decision 6 exists to prevent.

Disclosed: R46 (the commit step names one file, never a glob) is a real
regression guard but is NOT independently failing-first — the commit fence is
byte-identical pre- and post-fix, so it only fails pre-fix through its shared
extraction dependency. Recorded rather than claimed as fail-first.

Design:      .gsd/phase/feat-3885-no-silent-swallow/40-design.md
Test matrix: .gsd/phase/feat-3885-no-silent-swallow/50-test-matrix.md

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#3885): escape untrusted tokens, and stop cleanup destroying unpreserved evidence

Two review findings, both real, both in my own change.

An isolated adversarial review found the evidence-preservation block never
checked mkdir/cp exit status while `rm -rf "{run_dir}"` ran unconditionally in
a SEPARATE fenced block. A disk-full or unwritable phase directory therefore
still destroyed the only copy of the failed lanes' output — reintroducing the
exact #3352 data loss this item exists to stop, inside the fix for it.

Preservation and cleanup are now one block, because each fenced block is a
separate execution and a shell variable cannot carry between them. mkdir -p and
each cp are exit-checked; cleanup runs only when preservation succeeded, and a
failure warns naming the intact run directory. "Nothing to preserve" is not a
failure and still cleans up. Driven three ways: success removes run_dir, failure
leaves it intact with the warning, nothing-to-preserve removes it. The failure is
induced by a file-vs-directory conflict rather than chmod 0o000, which root
bypasses.

The new unresolved-depends_on warning embedded a user-authored token verbatim:

  warnings: ["Plan 03-02: depends_on token \"evil
  Plan 03-01: FORGED WARNING\" does not resolve ..."]

The JSON wire form is safe, and the security reviewer judged it non-exploitable
for that reason. It is escaped anyway through formatDiagnosticToken — the helper
#3884 added one phase earlier for exactly this class. warnings[] is an array a
consumer naturally prints line by line, and not reusing the sibling fix is the
generative-fix-divergence shape this epic exists to close. The same treatment is
applied to context_read_error / phase_dir_read_error, which embed a phase
directory path a repository can choose, and to the fs error message, which
echoes the raw path itself.

Known limit L5 recorded: the bound is on DEPTH only. A 300,000-element shallow
array yields a 14.5MB reply with truncated:false. Correct per §8.5 and per
negative space N2, disclosed rather than left to be discovered.

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#3885): unreadable is not absent in intel.cts either, and a corrupt snapshot is not "no snapshot"

Blocker from the round-2 isolated review, and it is my own inconsistency:
this phase applied "unreadable is not absent" to phase directories and left it
broken in the file it was already editing.

  chmod 000 .planning/intel/file-roles.json
  gsd-tools intel query <term>
  -> {"matches":[],"total":0,"truncated":false}  exit 0

safeReadJson swallowed every read failure and returned null, so an EACCES was
byte-indistinguishable from an absent file AND from a genuine no-match. Now it
separates three states: ENOENT stays silently absent, because not every project
has every intel file and intelQuery loops over all of them expecting misses;
EACCES/EIO and malformed JSON are both surfaced naming the file. A corrupt intel
file previously read as "no matches" too — same defect, same fix.

Threading that outcome through the other three callers found something worse
than the reported case. intelDiff returned no_baseline:true for a corrupt or
unreadable snapshot — not a silent failure but an actively FALSE verdict, telling
the caller they never took a snapshot when they did. That is §8.5's headline
case, so it is fixed and tested rather than noted. intelStatus and
intelApiSurface collapsed the same way; intelApiSurface additionally printed a
"not yet populated" banner that was simply untrue.

Every row is failing-first, including the absent-file ones — the field is new,
so it does not exist pre-fix at all. Those rows are not pre-fix pins; they pin
that the fix does not OVER-fire on the ordinary absent case, which is what would
turn this into noise on every project lacking an intel file. IO failure is
injected by monkeypatching fs and restoring in finally, never chmod 0o000 — root
bypasses mode bits, so the reviewer's manual chmod repro is not reproducible as
a test.

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(#3885): build the pathological intel fixture as text, not by stringifying a nested object

The remote runner came back red on Linux with two failures, both
T4: deeplyNestedIntelDoesNotOverflowTheStack, while the same test passed on
macOS. The product was never at fault.

writeNestedFixture(12000) built a 12,000-deep JavaScript OBJECT and then
JSON.stringify'd it. JSON.stringify recurses once per level, so it overflowed
the TEST PROCESS's stack — the error was thrown before the CLI was ever spawned.
Linux's container stack is smaller than macOS's, which is the whole of the
platform difference.

Measured, with the same document built as JSON TEXT so nothing in the building
process recurses:

  depth=100    rc=0 truncated=true
  depth=5000   rc=0 truncated=true
  depth=12000  rc=0 truncated=true
  depth=60000  rc=0 truncated=true

V8 parses this shape iteratively; only stringify recurses. The bound works at
every depth tried.

The fixture is now built by string concatenation. That is also the more faithful
input — a real deeply nested JSON document on disk is exactly what the bound
guards, where a stringified object was only ever a way to produce one.

The depth stays 12000. Lowering it would have made the test pass by weakening it
to accommodate a fixture bug, and 12000 is a legitimate pathological input the
product handles. T4 remains a genuine fail-first: rebuilt against the parent of
the commit that added the bound, the string-built depth-12000 fixture still
drives the CLI to rc=1 with "Error: Maximum call stack size exceeded".

A comment records why the fixture is text, so it is not "simplified" back into a
macOS-green / Linux-red test.

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#3885): backfill the changeset PR number

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(#3885): normalize path separators before splicing into the workflow's bash

CI red on one lane — test (windows-latest, 24, shard 3/3). macOS, Linux and the
remote runner were all green.

  AssertionError: commit must name the single REVIEWS.md file; got:
    --files C:UsersRUNNER~1AppDataLocalTempgsd-3352-phasedir-mOKmuy/03-REVIEWS.md

Every backslash in C:\Users\RUNNER~1\AppData\Local\Temp\... was eaten. The
harness spliced an OS-native temp path into the extracted bash, and bash consumes
\U, \A, \L and \T as escapes on an unquoted expansion. The same loss broke
RUN_DIR, so "rm -rf" targeted a path that never existed and the run directory
survived — which is the other two assertions.

This is a fixture defect, not a product one, and that was checked rather than
assumed. In production the phase directory is toPosixPath-normalized at every
call site that serializes it (bin/lib/init.cjs:951, 1381, 1461, 1529, 1595), and
the run directory is created by "mktemp -d" running inside the bash block itself
(gsd-core/workflows/review.md:163), which emits POSIX-style output even under
Git-Bash on Windows. Neither ever carries a backslash where the workflow reads it.

The file's pre-existing #3034 harness splices raw native paths too, but only ever
inside double-quoted assignments, so it never tripped this — my new harness
followed that convention faithfully into the one place where it does not hold.
Both now splice through toPosixPath from shell-command-projection, the
established seam, which is a no-op on POSIX and mirrors what production does.

No assertion was weakened. "commit must name the single REVIEWS.md file" and
"the run dir must still be destroyed" still assert exactly that; only how the
fixture supplies its path changed. Nothing is skipped on Windows — a t.skip()
here would have hidden the question of whether the exposure was real, which is
the question that mattered.

Driven both ways: a synthetic C:\Users\RUNNER~1\... input reproduces the exact CI
string when unfixed and yields C:/Users/RUNNER~1/... when fixed; a POSIX input
produces a byte-identical shape, proving the normalization is idempotent.

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(#3885): stop the harness making the deleted run dir its own cwd

Windows shard 3/3 stayed red after the separator fix, on two assertions the
separator fix never touched:

  AssertionError: the run dir must still be destroyed
  AssertionError: nothing to preserve is not a failure — run dir must still be removed

The separators were a real bug and fixing them fixed the --files assertion. They
were not this bug, and two CI cycles went into the wrong axis before I stopped
converting path forms and looked at what the harness actually does.

runWriteReviewsFlow passed cwd: runDir to runHook, so the child bash process's
working directory WAS the directory the block under test then removes with
rm -rf "$RUN_DIR". POSIX allows a process to delete its own cwd — verified
locally, cd "$d"; rm -rf "$d" removes it cleanly — and Windows does not: a live
process's working directory cannot be removed. So on Windows the directory
survived and both assertions failed, on macOS and Linux it vanished and they
passed. Nothing to do with slashes.

Harness-only. Production never cd's into the run directory; every reference is by
absolute path, and RUN_DIR is created by mktemp -d inside the bash block itself
(gsd-core/workflows/review.md:165) rather than injected. review.md is unchanged.

Fix: the child now runs with its cwd in an unrelated temp directory that the
block under test never deletes. Neither assertion was weakened, and nothing is
skipped on Windows — the tests in this file carry no platform guard and run
there unconditionally, which is how this surfaced at all.

Honest limit: the Windows failure mode cannot be reproduced on macOS, because
POSIX permits the very thing Windows refuses. The diagnosis is grounded in that
documented divergence and in the fact that only the Windows lane failed, but the
green outcome on windows-latest is unverified until CI runs it.

Refs #3885

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-08-27 04:12:47 -04:00
committed by GitHub
parent 941b62249e
commit 929e02cb2c
19 changed files with 2346 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

564
tests/intel.test.cjs
View File

@@ -425,6 +425,252 @@ describe('intelQuery', () => {
});
});
// ─── #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.GSD_RUNTIME;
process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
delete process.env.GSD_WORKSTREAM;
delete process.env.GSD_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 = runGsdTools(['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.GSD_RUNTIME;
process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
delete process.env.GSD_WORKSTREAM;
delete process.env.GSD_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', () => {
@@ -482,6 +728,92 @@ describe('intelStatus', () => {
});
});
// ─── #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.GSD_RUNTIME;
process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
delete process.env.GSD_WORKSTREAM;
delete process.env.GSD_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', () => {
@@ -544,6 +876,131 @@ describe('intelDiff', () => {
});
});
// ─── #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.GSD_RUNTIME;
process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
delete process.env.GSD_WORKSTREAM;
delete process.env.GSD_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', () => {
@@ -1107,6 +1564,113 @@ describe('intelApiSurface', () => {
});
});
// ─── #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.GSD_RUNTIME;
process.env.CLAUDE_CONFIG_DIR = surfacedConfigDir;
delete process.env.GSD_WORKSTREAM;
delete process.env.GSD_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: gsd-intel-updater emits canonical intel filenames', () => {
// allow-test-rule: source-text-is-the-product
// agents/gsd-intel-updater.md IS the system prompt the intel-updater agent runs under; asserting its filename references