brainclaw 1.16.0 → 1.18.0

package/dist/core/code-map/query.js

@@ -12,6 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { hashContent } from './extractor.js';
+import { coarseFreshness } from './freshness.js';
 import { readImportsIndex, readManifest, readResolutionIndex, readShard, readSymbolsIndex, } from './store.js';
 // --- lazy read-path freshness budget (spec §6.1) ---
 /** Default per-query lazy-check budget (spec §6.1). */
@@ -26,7 +27,7 @@ export const LAZY_BUDGET = {
  * per-path memoization so a brief() that touches one file from several ranking
  * signals spends a single budget slot.
  */
-function makeLazyChecker(budget = LAZY_BUDGET) {
+export function makeLazyChecker(budget = LAZY_BUDGET) {
     return {
         budget,
         startedAt: Date.now(),
@@ -47,7 +48,7 @@ function budgetExhausted(checker) {
     }
     return checker.exhausted;
 }
-function newAccumulator() {
+export function newAccumulator() {
     return {
         staleChangedPaths: new Set(),
         missingPaths: new Set(),
@@ -62,7 +63,16 @@ function newAccumulator() {
  * served as a *confident* (fresh) result.
  */
 function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd, preferredDirName) {
-    const cached = checker.memo.get(entry.path);
+    // pln#631 — memo key scoped by the store's cwd. Two collision hazards must both be
+    // avoided when a shared checker spans a workspace: keying by PATH collides two
+    // packages' same-named `src/index.ts`; keying by file_id ALONE collides when two
+    // stores share a project_id (the `prj_${basename}` fallback, or a copied
+    // `.brainclaw/config.yaml`) — file_id = sha256(project_id + rel_path), so a shared
+    // id makes the file_id identical too (review F1). Scoping by the store's cwd (unique
+    // per store) is collision-proof either way; single-store keeps cwd constant, so
+    // behavior is identical to before.
+    const memoKey = `${cwd ?? ''} ${entry.file_id}`;
+    const cached = checker.memo.get(memoKey);
     if (cached !== undefined)
         return cached;
     const abs = path.join(projectRoot, entry.path);
@@ -72,19 +82,19 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     }
     catch {
         acc.missingPaths.add(entry.path); // §6.1.2 — deletion.
-        checker.memo.set(entry.path, false);
+        checker.memo.set(memoKey, false);
         return false;
     }
     const shard = readShard(entry.file_id, cwd, preferredDirName);
     if (!shard) {
         // No backing shard to compare against — treat as unchecked, not confident.
         acc.uncheckedPaths.add(entry.path);
-        checker.memo.set(entry.path, false);
+        checker.memo.set(memoKey, false);
         return false;
     }
     // §6.1.3 — cheap gate: mtime + size match => fresh for this read.
     if (stat.mtimeMs === shard.mtime_ms && stat.size === shard.size_bytes) {
-        checker.memo.set(entry.path, true);
+        checker.memo.set(memoKey, true);
         return true;
     }
     // §6.1.4/§6.1.6 — gate tripped: hash only when within budget AND not oversized.
@@ -93,13 +103,13 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     // `partial`. Keep them separable so the badge reason is accurate.
     if (stat.size > maxParseFileBytes) {
         acc.uncheckedPaths.add(entry.path); // structurally unverifiable, not budget.
-        checker.memo.set(entry.path, false);
+        checker.memo.set(memoKey, false);
         return false;
     }
     if (budgetExhausted(checker)) {
         acc.uncheckedPaths.add(entry.path);
         acc.budgetSkippedPaths.add(entry.path);
-        checker.memo.set(entry.path, false);
+        checker.memo.set(memoKey, false);
         return false;
     }
     checker.filesChecked++;
@@ -109,17 +119,30 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     }
     catch {
         acc.uncheckedPaths.add(entry.path);
-        checker.memo.set(entry.path, false);
+        checker.memo.set(memoKey, false);
         return false;
     }
     if (hashContent(live) === shard.file_hash) {
-        checker.memo.set(entry.path, true); // §6.1 — identical despite mtime touch.
+        checker.memo.set(memoKey, true); // §6.1 — identical despite mtime touch.
         return true;
     }
     acc.staleChangedPaths.add(entry.path); // §6.1.5 — confirmed content change.
-    checker.memo.set(entry.path, false);
+    checker.memo.set(memoKey, false);
     return false;
 }
+/**
+ * pln#631 PR3 — validate a single file entry against a SPECIFIC store's live tree
+ * (resolves that store's root + parse budget from its manifest). Lets the cross-package
+ * scan lazy-validate importer rows from a sibling store and drop deleted/stale ones,
+ * upholding the same "no silent stale graph hints" rule intra-package graph rows obey.
+ * Shares the caller's checker (one budget) + records into the caller's acc.
+ */
+export function validateStoreEntry(entry, checker, acc, cwd, preferredDirName) {
+    const manifest = readManifest(cwd, preferredDirName);
+    const root = manifest?.project_root ?? cwd ?? process.cwd();
+    const maxBytes = manifest?.extractor_config.max_parse_file_bytes ?? 1024 * 1024;
+    return validateEntry(entry, checker, acc, root, maxBytes, cwd, preferredDirName);
+}
 /**
  * Derive the response freshness badge from the base manifest status + the
  * outcomes recorded during this query's lazy check (spec §6.1, §9).
@@ -127,7 +150,7 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
  * Precedence: an exhausted budget yields `partial`; otherwise any detected
  * change/deletion yields `stale_changed_files`; else the manifest base status.
  */
-function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex) {
+export function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex) {
     const details = {};
     if (acc.staleChangedPaths.size > 0) {
         details.stale_changed_files = [...acc.staleChangedPaths].sort();
@@ -167,7 +190,7 @@ function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex)
     if (status !== base)
         details.index_status = base;
     void hadConfidentMatch;
-    return { status, details };
+    return { status, coarse: coarseFreshness(status), details };
 }
 const DEFAULT_FIND_LIMIT = 20;
 /** Lowercase token normalization mirroring indexes.ts (spec §5.6 keys). */
@@ -185,25 +208,73 @@ function queryTokens(query) {
     return [...tokens];
 }
 /**
- * Score a symbol index entry against the query. Exact (full-query) token match
- * scores highest; a prefix/substring match scores lower. Exported symbols and
- * components/hooks get a small boost (these are what agents most want to find).
+ * pln#601 — normalize an identifier to a separator/case-INSENSITIVE canonical
+ * form (strip `_`, `-`, `.`, camelCase boundaries collapse to nothing; lowercase).
+ * `EntityRegistry`, `ENTITY_REGISTRY`, and `entity-registry` all → `entityregistry`.
+ * Without this, `scoreEntry` compared raw-lowercased strings, so a Pascal-case
+ * query `EntityRegistry` failed to exact/prefix/substring-match the snake_case
+ * `ENTITY_REGISTRY` and dropped it to the sub-token floor (score 1) alongside 19
+ * unrelated `*Registry` symbols — the Fable-audit "all results score 1 → the agent
+ * re-greps" defect that undercuts the whole "stop grepping blind" value prop.
+ */
+function normIdent(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/**
+ * pln#601 — a path that is a test/spec file (its symbols must not outrank the real
+ * def, and it should not crowd source out of a brief). Recognizes conventions across
+ * ALL supported languages (JS/TS + py/php/java/go/rust/c#/ruby/c/c++), so the
+ * source-over-test bias actually works for the polyglot langs, not just JS/TS.
+ * Exported for the classification regression tests.
  */
-function scoreEntry(entry, query) {
-    const q = query.toLowerCase();
-    const name = entry.name.toLowerCase();
+export function isTestPath(p) {
+    // Directory conventions (all langs): tests/, test/, __tests__/, spec(s)/ (Ruby
+    // RSpec), __mocks__/. NOTE: a source dir literally named `spec/` (e.g. an OpenAPI
+    // `spec/` folder) is an accepted false-positive — RSpec `spec/` is the commoner
+    // meaning now that Ruby is supported, and path alone can't disambiguate.
+    if (/(?:^|[\\/])(?:tests?|__tests__|specs?|__mocks__)[\\/]/i.test(p))
+        return true;
+    const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
+    return (
+    // separator-suffixed: foo.test.ts, foo_test.go, foo-spec.js, foo_spec.rb, foo_test.py
+    /[._-](?:test|spec)\.(?:[cm]?[jt]sx?|py|rb|go|php|java|cs|rs)$/i.test(base) ||
+        // pytest / minitest prefix: test_foo.py, test_foo.rb
+        /^test_.+\.(?:py|rb)$/i.test(base) ||
+        // bare test/spec file: test.ts, spec.rb
+        /^(?:test|spec)\.(?:[cm]?[jt]sx?|py|rb|go)$/i.test(base) ||
+        // xUnit / JUnit PascalCase suffix: FooTest.cs, BarTests.cs, BazTest.java
+        // (case-SENSITIVE capital T so `contest.cs` / `latest.cs` are not false hits)
+        /Tests?\.(?:cs|java)$/.test(base));
+}
+/**
+ * Score a symbol index entry against the query. Matching is separator/case
+ * INSENSITIVE (pln#601): an exact NORMALIZED match scores highest, then prefix,
+ * then substring, then the sub-token floor. Exported symbols + components/hooks
+ * get a small boost; test-file symbols are biased DOWN so a test helper never
+ * outranks the real definition of the same name (the Fable-audit brief-noise
+ * companion to the find defect). Exported for focused ranking tests.
+ */
+export function scoreEntry(entry, query) {
+    const q = normIdent(query);
+    const name = normIdent(entry.name);
     let score = 0;
-    if (name === q)
-        score += 10;
+    if (q.length === 0)
+        score += 1;
+    else if (name === q)
+        score += 10; // exact, style-insensitive
     else if (name.startsWith(q))
-        score += 6;
+        score += 6; // prefix
     else if (name.includes(q))
-        score += 3;
+        score += 3; // substring
     else
         score += 1; // matched only via a sub-token bucket
     score *= entry.score_hint; // exported (1.0) vs internal (0.8)
     if (entry.subtype === 'component' || entry.subtype === 'hook')
         score += 1;
+    // pln#601 — source over test: a test/spec symbol of the same name must not
+    // outrank the real definition (keeps find/brief pointing at source first).
+    if (isTestPath(entry.path))
+        score *= 0.4;
     return score;
 }
 function resolveRoot(ctx) {
@@ -237,20 +308,22 @@ function gatherSymbolEntries(index, query) {
     }
     return out;
 }
-export function find(query, limit, ctx) {
-    const base = baseStatus(ctx);
+/**
+ * Store-local find CORE (pln#631): gather → lazy-validate → score → sort, with NO
+ * cap and NO badge. Accepts an INJECTED checker + acc so a workspace aggregation can
+ * share ONE lazy budget across stores (the checker's memo is file_id-keyed, unique
+ * per store, so sharing never collides same-named files across packages). `find()`
+ * wraps this with a fresh checker/acc + cap + badge for the unchanged single-store
+ * path; `aggregate.ts` fans it out across stores with a shared checker.
+ */
+export function findInStore(query, ctx, checker, acc) {
     const index = readSymbolsIndex(ctx.cwd, ctx.preferredDirName);
     if (!index) {
-        return {
-            query,
-            matches: [],
-            freshness_badge: { status: 'missing_index', details: { hint: 'run refresh' } },
-        };
+        return { matches: [], base: 'missing_index', hasIndex: false, emptyCandidates: true, acc };
     }
+    const base = baseStatus(ctx);
     const root = resolveRoot(ctx);
     const maxBytes = maxParseBytes(ctx);
-    const checker = makeLazyChecker();
-    const acc = newAccumulator();
     const candidates = gatherSymbolEntries(index, query);
     const ranked = [];
     for (const entry of candidates) {
@@ -269,8 +342,21 @@ export function find(query, limit, ctx) {
         });
     }
     ranked.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.name.localeCompare(b.name));
-    const capped = ranked.slice(0, limit ?? DEFAULT_FIND_LIMIT);
-    const badge = deriveBadge(base, acc, checker.exhausted, capped.length > 0, candidates.length === 0);
+    return { matches: ranked, base, hasIndex: true, emptyCandidates: candidates.length === 0, acc };
+}
+export function find(query, limit, ctx) {
+    const checker = makeLazyChecker();
+    const acc = newAccumulator();
+    const r = findInStore(query, ctx, checker, acc);
+    if (!r.hasIndex) {
+        return {
+            query,
+            matches: [],
+            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+        };
+    }
+    const capped = r.matches.slice(0, limit ?? DEFAULT_FIND_LIMIT);
+    const badge = deriveBadge(r.base, acc, checker.exhausted, capped.length > 0, r.emptyCandidates);
     return { query, matches: capped, freshness_badge: badge };
 }
 /** spec §11 — cap related memory at top 5 by relevance. */
@@ -399,6 +485,42 @@ function rankFiles(defining, forwardRows, reverseRows, symbolsIndex, importsInde
     }
     return [...byPath.values()].sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
 }
+/**
+ * pln#601 — reserve most of the §9 reading list for SOURCE files. On a symbol with
+ * many test importers, the reverse-dependent test files (blast radius, +5 each) can
+ * fill the entire {@link BRIEF_FILE_CAP} and crowd out the source files an agent needs
+ * to understand the symbol — the Fable-audit brief-noise defect. At most `maxTest`
+ * test files (~1/4 of the cap, min 2) are admitted UNLESS there aren't enough non-test
+ * files to fill the cap, in which case the deferred tests backfill the empty slots so
+ * the list is never artificially short. Defining files ARE the target and are never
+ * counted as noise (a symbol legitimately defined in a test file still leads the list).
+ * Input is pre-sorted by score; output preserves that order within each bucket.
+ */
+export function reserveSourceSlots(ranked, cap, definingPaths) {
+    const maxTest = Math.max(2, Math.floor(cap / 4)); // e.g. 3 of 12
+    const out = [];
+    const overflowTests = [];
+    let testsIncluded = 0;
+    for (const rf of ranked) {
+        if (out.length >= cap)
+            break;
+        const isNoise = isTestPath(rf.path) && !definingPaths.has(rf.path);
+        if (isNoise && testsIncluded >= maxTest) {
+            overflowTests.push(rf);
+            continue;
+        }
+        out.push(rf);
+        if (isNoise)
+            testsIncluded++;
+    }
+    // Non-test ran out before the cap → backfill the empty slots with deferred tests.
+    for (const rf of overflowTests) {
+        if (out.length >= cap)
+            break;
+        out.push(rf);
+    }
+    return out;
+}
 /** Build a node-id → symbol index entry map (deduped; entries repeat across token buckets). */
 function buildNodeIdIndex(symbolsIndex) {
     const out = new Map();
@@ -495,49 +617,64 @@ function filesMatchingPath(symbolsIndex, target) {
     }
     return out;
 }
-export function brief(target, limit, ctx, memoryReader) {
-    const base = baseStatus(ctx);
+/**
+ * Store-local brief CORE (pln#631 PR2): resolve the target → graph signals →
+ * rankFiles → confident list, with NO cap, NO badge, NO related-memory attach.
+ * Accepts an INJECTED checker + acc so a workspace aggregation can share ONE lazy
+ * budget across stores (memo is cwd-scoped, so sharing is collision-safe). `brief()`
+ * wraps this with a fresh checker/acc + reserve + memory + badge for the unchanged
+ * single-store path; `aggregate.ts` fans it out and merges target-defining stores.
+ */
+export function briefInStore(target, ctx, checker, acc) {
     const symbolsIndex = readSymbolsIndex(ctx.cwd, ctx.preferredDirName);
     if (!symbolsIndex) {
         return {
-            target,
-            suggested_files_to_read: [],
-            related_memory: [],
-            freshness_badge: { status: 'missing_index', details: { hint: 'run refresh' } },
+            defining: [],
+            definingPaths: new Set(),
+            matchKind: 'none',
+            confident: [],
+            base: 'missing_index',
+            hasIndex: false,
+            emptyRanked: true,
+            acc,
         };
     }
+    const base = baseStatus(ctx);
     const importsIndex = readImportsIndex(ctx.cwd, ctx.preferredDirName);
     const resolutionIndex = readResolutionIndex(ctx.cwd, ctx.preferredDirName);
     // Resolve target -> defining symbol entries. A brief orients on a SPECIFIC target,
     // so prefer EXACT name matches when present — otherwise the token index floods the
-    // result with unrelated same-token symbols (e.g. `resolveProjectImports` would pull
-    // in every `resolve*`), burying the real defining file + its graph signals. Fall
-    // back to the fuzzy token set, then to a path match. (find() stays fuzzy by design.)
+    // result with unrelated same-token symbols. Fall back to the fuzzy token set, then
+    // a path match. `matchKind` records which path won so an aggregation can prefer the
+    // stores that actually DEFINE the target over stores that only fuzzy-match a token.
     let defining;
+    let matchKind;
     if (looksLikePathTarget(target)) {
-        // PATH target (pln#593 1b): resolve the exact file; the graph signals (its
-        // imports / dependents / direct tests) then rank below it via rankFiles. Skip
-        // the fuzzy token gather entirely — it floods a path brief with same-token
-        // noise. Degrade to the fuzzy set only if the path resolves to nothing indexed.
         defining = filesMatchingPath(symbolsIndex, target);
-        if (defining.length === 0)
+        if (defining.length > 0)
+            matchKind = 'path';
+        else {
             defining = gatherSymbolEntries(symbolsIndex, target);
+            matchKind = defining.length > 0 ? 'fuzzy' : 'none';
+        }
     }
     else {
         defining = gatherSymbolEntries(symbolsIndex, target);
         const exact = defining.filter((e) => e.name.toLowerCase() === target.toLowerCase());
-        if (exact.length > 0)
+        if (exact.length > 0) {
             defining = exact;
-        else if (defining.length === 0)
+            matchKind = 'exact';
+        }
+        else if (defining.length > 0) {
+            matchKind = 'fuzzy';
+        }
+        else {
             defining = filesMatchingPath(symbolsIndex, target);
+            matchKind = defining.length > 0 ? 'path' : 'none';
+        }
     }
     const root = resolveRoot(ctx);
     const maxBytes = maxParseBytes(ctx);
-    const checker = makeLazyChecker();
-    const acc = newAccumulator();
-    // P1d graph signals. FORWARD: read from defining shards — but only CONFIDENT ones
-    // (validate first; a stale importer shard's edge list is not trusted). REVERSE: from
-    // the resolution index (each importer row is lazy-validated below like any other).
     const definingPaths = new Set(defining.map((e) => e.path));
     const definingByNodeId = new Map(defining.map((e) => [e.node_id, e]));
     const confidentDefiningFileIds = new Map();
@@ -552,31 +689,25 @@ export function brief(target, limit, ctx, memoryReader) {
     const fwd = forwardDeps(confidentDefiningFileIds, nodeIndex, ctx.cwd, ctx.preferredDirName);
     const rev = reverseDeps(resolutionIndex, definingPaths, definingByNodeId);
     const ranked = rankFiles(defining, fwd, rev, symbolsIndex, importsIndex, target);
-    // §6.1 — lazy validate each suggested file; exclude deletions from the confident
-    // list (still recorded in the badge). P1d: a GRAPH-ONLY row that fails validation
-    // (stale / unchecked / deleted) is SUPPRESSED — no silent stale graph hints (Codex).
+    // §6.1 — lazy validate each suggested file; exclude deletions; suppress a graph-only
+    // row that fails validation (no silent stale graph hints).
     const confident = [];
     for (const rf of ranked) {
         const ok = validateEntry({ path: rf.path, file_id: rf.file_id }, checker, acc, root, maxBytes, ctx.cwd, ctx.preferredDirName);
         if (acc.missingPaths.has(rf.path))
-            continue; // deletion: exclude entirely.
+            continue;
         if (rf.graphDerived && !ok)
-            continue; // graph-only + not confident → suppress.
-        // Non-graph stale/unchecked rows still appear (badge flags them) so the agent
-        // knows the file exists but may be out of date.
+            continue;
         confident.push(rf);
     }
-    const cap = Math.min(limit ?? BRIEF_FILE_CAP, BRIEF_FILE_CAP);
-    const capped = confident.slice(0, cap);
-    // Related memory (spec §11): match by the candidate paths + symbol names.
-    const candidatePaths = capped.map((f) => f.path);
-    const symbolNames = [...new Set(defining.map((e) => e.name))];
-    if (symbolNames.length === 0)
-        symbolNames.push(target);
-    const memoryItems = memoryReader(ctx);
-    const related = attachRelatedMemory(memoryItems, candidatePaths, symbolNames);
-    // Attach matching memory ids per file (those whose related_paths/text name it).
-    const suggested = capped.map((f) => {
+    return { defining, definingPaths, matchKind, confident, base, hasIndex: true, emptyRanked: ranked.length === 0, acc };
+}
+/**
+ * Attach related-memory ids per reading-list entry (spec §11). Shared by the
+ * single-store brief() and the workspace aggregation so both surface memory identically.
+ */
+export function attachMemoryIds(capped, related) {
+    return capped.map((f) => {
         const ids = related
             .filter((m) => {
             const fileNorm = f.path.replace(/\\/g, '/');
@@ -588,12 +719,30 @@ export function brief(target, limit, ctx, memoryReader) {
             .map((m) => m.id);
         return { path: f.path, reason: f.reason, score: f.score, related_memory_ids: ids };
     });
-    const badge = deriveBadge(base, acc, checker.exhausted, capped.length > 0, ranked.length === 0);
-    return {
-        target,
-        suggested_files_to_read: suggested,
-        related_memory: related,
-        freshness_badge: badge,
-    };
+}
+export function brief(target, limit, ctx, memoryReader) {
+    const checker = makeLazyChecker();
+    const acc = newAccumulator();
+    const r = briefInStore(target, ctx, checker, acc);
+    if (!r.hasIndex) {
+        return {
+            target,
+            suggested_files_to_read: [],
+            related_memory: [],
+            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+        };
+    }
+    const cap = Math.min(limit ?? BRIEF_FILE_CAP, BRIEF_FILE_CAP);
+    // pln#601 — reserve source slots so test importers can't crowd out source files.
+    const capped = reserveSourceSlots(r.confident, cap, r.definingPaths);
+    // Related memory (spec §11): match by the candidate paths + symbol names.
+    const candidatePaths = capped.map((f) => f.path);
+    const symbolNames = [...new Set(r.defining.map((e) => e.name))];
+    if (symbolNames.length === 0)
+        symbolNames.push(target);
+    const related = attachRelatedMemory(memoryReader(ctx), candidatePaths, symbolNames);
+    const suggested = attachMemoryIds(capped, related);
+    const badge = deriveBadge(r.base, acc, checker.exhausted, capped.length > 0, r.emptyRanked);
+    return { target, suggested_files_to_read: suggested, related_memory: related, freshness_badge: badge };
 }
 //# sourceMappingURL=query.js.map

package/dist/core/code-map/types.js

@@ -61,6 +61,12 @@ const KNOWN_CODE_LANGS = new Set([
     'python',
     'php',
     'java',
+    'go',
+    'rust',
+    'csharp',
+    'ruby',
+    'c',
+    'cpp',
 ]);
 /** A well-formed (lowercase) language id a future provider could register. */
 const CODE_LANG_RE = /^[a-z][a-z0-9_]*$/;
@@ -285,9 +291,21 @@ export const CodeLockSchema = z.object({
     heartbeat_at: z.string(),
     stale_after_ms: z.number().int(),
 });
+/**
+ * spec §9 (pln#601) — the COARSE, surface-uniform rollup of the detailed 7-value
+ * {@link FreshnessStatus}. find/brief/status/work each expose their own precise
+ * status, but an agent wants one consistent top-line signal to decide "trust this
+ * or refresh first" without memorizing which `stale_*` variant applies. `coarse`
+ * collapses the detail: every `stale_*` → `stale`, `missing_index` → `missing`,
+ * `partial`/`fresh` unchanged. Derived (never independently authored) via
+ * `coarseFreshness()` so it can never contradict `status`.
+ */
+export const CoarseFreshnessSchema = z.enum(['fresh', 'stale', 'partial', 'missing']);
 /** Freshness badge attached to every agent-facing read response (spec §9). */
 export const FreshnessBadgeSchema = z.object({
     status: FreshnessStatusSchema,
+    /** pln#601 — coarse rollup of `status`, uniform across all read surfaces. */
+    coarse: CoarseFreshnessSchema.optional(),
     details: z.record(z.string(), z.unknown()).default({}),
 });
 //# sourceMappingURL=types.js.map

package/dist/core/code-map/work-section.js

@@ -18,6 +18,7 @@
  *                      bclaw_work beyond that bounded wait (rule §6 rule 8).
  */
 import { readManifest } from './store.js';
+import { withCoarse } from './freshness.js';
 import { readCodeLock, isLockAbandoned } from './lock.js';
 import { codeMapDir, lockPath } from './paths.js';
 import { JsonlBackend } from './backend.js';
@@ -107,10 +108,10 @@ export async function codeMapWorkSection(cwd, opts = {}) {
                     return {
                         enabled: true,
                         matches: out.matches,
-                        freshness_badge: {
+                        freshness_badge: withCoarse({
                             status: 'partial',
                             details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
-                        },
+                        }),
                         lock_wait_ms: lockWaitMs,
                     };
                 }
@@ -121,10 +122,10 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             return {
                 enabled: true,
                 matches: [],
-                freshness_badge: {
+                freshness_badge: withCoarse({
                     status: 'partial',
                     details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
-                },
+                }),
                 lock_wait_ms: lockWaitMs,
             };
         }
@@ -135,7 +136,7 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             enabled: true,
             missing_index: 'Code Map index is empty for this project. Run `brainclaw code-map refresh --all` (or bclaw_code_refresh) before relying on find/brief.',
             matches: [],
-            freshness_badge: { status: 'missing_index', details: {} },
+            freshness_badge: withCoarse({ status: 'missing_index', details: {} }),
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }
@@ -146,13 +147,13 @@ export async function codeMapWorkSection(cwd, opts = {}) {
         return {
             enabled: true,
             matches: [],
-            freshness_badge: {
+            freshness_badge: withCoarse({
                 status: manifest.freshness.status,
                 details: {
                     stale_file_count: manifest.freshness.stale_file_count,
                     partial_reason: manifest.freshness.partial_reason,
                 },
-            },
+            }),
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }

package/dist/core/codev-responses.js

@@ -15,6 +15,22 @@ export function responseDir(threadSlug, cwd) {
 export function responseFilePath(threadSlug, roundNumber, persona, cwd) {
     return path.join(responseDir(threadSlug, cwd), `round_${roundNumber}_${persona}.json`);
 }
+/**
+ * Persist a full CoDev/ideation phase body to the artifact store (pln#627
+ * Phase C) and return a repo-relative pointer. The inbox thread then carries
+ * only a bounded head + this pointer instead of a multi-hundred-KB rfc dump
+ * (root cause of the 3.8 MB inbox: full phase briefs persisted as messages).
+ * The `.brainclaw/coordination/ideation/<slug>/phases/` dir sits alongside the
+ * existing per-round `responses/` store so a thread's artifacts stay together.
+ */
+export function writePhaseArtifact(threadSlug, label, text, cwd) {
+    const dir = path.join(memoryDir(cwd), 'coordination', 'ideation', sanitizeForPath(threadSlug), 'phases');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${sanitizeForPath(label)}.md`);
+    fs.writeFileSync(filePath, text, 'utf8');
+    const relPath = path.relative(memoryDir(cwd), filePath).split(path.sep).join('/');
+    return { path: filePath, relPath, charCount: text.length };
+}
 export function writeResponse(threadSlug, roundNumber, persona, agent, text, cwd) {
     const filePath = responseFilePath(threadSlug, roundNumber, persona, cwd);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });