peaks-loop 4.0.51 → 4.0.52

package/dist/cli/commands/project-commands.js

@@ -1,11 +1,13 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
 import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { describeMemoryBlockDrops, describeSessionScanFailures, extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
 import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
 import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
+const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
 export function registerProjectCommands(program, io) {
     const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
     addJsonOption(project
@@ -111,7 +113,15 @@ export function registerProjectCommands(program, io) {
                 writtenFiles: result.writtenFiles,
                 memoryDir: result.primaryMemoryDir,
                 indexUpdated: result.updatedIndex
-            }), options.json);
+            }, [
+                // Two drop axes, one channel. `droppedBlocks` = a block was found and
+                // rejected (or a marker-shaped comment was not findable at all);
+                // `scanFailures` = the whole artifact could not be read, so its blocks
+                // were never candidates. `data` is unchanged by either — same contract
+                // as `memory.extract`.
+                ...describeMemoryBlockDrops(result.droppedBlocks),
+                ...describeSessionScanFailures(result.scanFailures)
+            ]), options.json);
         }
         catch (error) {
             printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
@@ -141,7 +151,7 @@ export function registerProjectCommands(program, io) {
         .command('memories')
         .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
         .requiredOption('--project <path>', 'target project root')
-        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)).action((options) => {
         try {
             const result = readProjectMemories(options.project);
             if (options.kind) {

package/dist/cli/commands/request-commands.js

@@ -8,7 +8,7 @@ import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-serv
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
-import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { isUnsafePathInput } from '../../shared/path-safety.js';
 /**
@@ -296,6 +296,9 @@ export function registerRequestCommands(program, io) {
             // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
             // otherwise. Best-effort and fail-silent — never blocks the transition.
             let codegraphRefresh = null;
+            // A2 (2026-09-17): the human-visible half of the refresh outcome. null
+            // when the refresh succeeded or when no codegraph store was in use.
+            let codegraphWarning = null;
             if (role === 'rd' && newState === 'qa-handoff') {
                 try {
                     const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
@@ -319,6 +322,11 @@ export function registerRequestCommands(program, io) {
                     // The refresh is best-effort; never block the transition.
                     codegraphRefresh = { refreshed: false, reason: 'unavailable', note: 'auto codegraph refresh failed after transition' };
                 }
+                // A2 (2026-09-17): never BLOCKING is kept; never VISIBLE is not. A
+                // non-refresh while a codegraph store is in use becomes a warning
+                // line beside the transition's own notes. See
+                // `codegraphRefreshNotice` for why `no-codegraph-dir` stays silent.
+                codegraphWarning = codegraphRefreshNotice(codegraphRefresh);
             }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
@@ -360,13 +368,16 @@ export function registerRequestCommands(program, io) {
             // transition is not a slice boundary), preCompact is null and
             // we emit a `preCompactCheckpoint: null` field so LLM callers
             // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, preCompact !== null
-                ? [
-                    `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
-                        ? String(preCompact.data.ratio)
-                        : 'unknown'} (zone=pre-compact)`
-                ]
-                : []), options.json);
+            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, [
+                ...(preCompact !== null
+                    ? [
+                        `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
+                            ? String(preCompact.data.ratio)
+                            : 'unknown'} (zone=pre-compact)`
+                    ]
+                    : []),
+                ...(codegraphWarning === null ? [] : [codegraphWarning])
+            ]), options.json);
         }
         catch (error) {
             if (error instanceof InvalidArgumentError) {

package/dist/cli/commands/slice-commands.js

@@ -35,7 +35,7 @@ export function registerSliceCommands(program, io) {
         'Each stage reports pass / fail / skipped. ' +
         'Exit 0 only if every stage passes or is skipped.')
         .option('--project <path>', 'target project root', '.')
-        .option('--rid <rid>', 'request id; defaults to the active current-change binding')
+        .option('--rid <rid>', 'request id; REQUIRED — there is no binding to fall back to, and slice check fails without it')
         .option('--refresh-fanout', 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist', false)
         .option('--run-tests', 'opt in to the FULL test suite at the boundary (default is the changed-only suite via `vitest run --changed`); use the peaks-test skill to run the full suite standalone', false)
         .option('--skip-tests', 'skip the unit-test stage entirely (e.g. docs-only slices); use the peaks-test skill to run the full suite manually if you want a separate check', false)
@@ -60,7 +60,7 @@ export function registerSliceCommands(program, io) {
             }
         }
         catch (error) {
-            printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path is a peaks repo, --rid is correct, and .peaks/_runtime/current-change is valid']), options.json ?? false);
+            printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, [`Verify the project path is a peaks repo and --rid names a slice (letters, digits, dots, underscores or dashes): ${options.rid ?? '(no --rid given)'}`]), options.json ?? false);
             process.exitCode = 1;
         }
     });

package/dist/services/artifacts/artifact-prerequisites.js

@@ -237,10 +237,32 @@ const PRD_CONTENT = {
     description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
     mustContain: ['## Goals', '## Acceptance']
 };
+// R10 (2026-09-16): the second marker used to be the bare `test(` inside
+// `mustContain` — i.e. ALL markers required. That made the gate satisfiable
+// only by MENTIONING the literal string in prose, never by honest test code,
+// because this repo's own BDD Test Style Contract
+// (`skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md:170`) names BOTH
+// idioms — "The first string-literal argument of `it()` / `test()` MUST
+// describe business behavior" — and `it(` is the dominant one by ~8x.
+// Measured 2026-09-16 (`grep -rho '\bit(' tests | wc -l`, same for `test(`):
+// `it(` 3015 vs `test(` 372 across `tests/`; the three test files slice
+// 2026-09-16-codegraph-index-integrity added contain `it(` 58 / `test(` 0.
+// The gate was in fact passing on artifacts whose ONLY `test(` was prose —
+// including this repo's own generated template `buildTestCases`
+// (`src/services/evidence/evidence-generator.ts`), which literally reads
+// "no new tests; behavior preserved" and satisfied the marker anyway.
+// Both idioms are therefore accepted via `mustContainAny` — an existing
+// field on this type, already used by PERF_BASELINE / AUDIT_SECURITY /
+// MUT_REPORT — while `## Test cases` stays a hard `mustContain`.
+// Do NOT "tighten" this back to a single idiom in `mustContain`: that
+// restores exactly the pass-by-mentioning hole `headingMustContain` was
+// introduced to close (see the field doc comment above), and no honest test
+// file in this repo could then satisfy the gate.
 const UNIT_TESTS = {
     relativePath: 'qa/test-cases/<rid>.md',
     description: 'Unit test files for the implemented changes (enforces peaks-rd Gate B2)',
-    mustContain: ['## Test cases', 'test(']
+    mustContain: ['## Test cases'],
+    mustContainAny: ['test(', 'it(']
 };
 const QA_INITIATED = {
     relativePath: 'qa/.initiated',

package/dist/services/codegraph/codegraph-autorefresh.d.ts

@@ -6,6 +6,22 @@ export type CodegraphAutorefreshResult = {
     reason: 'no-codegraph-dir' | 'index-failed' | 'unavailable';
     note: string;
 };
+/**
+ * The operator-facing line for a refresh that did not happen, or `null` when
+ * there is nothing to report. The ONE place the report/no-report rule lives,
+ * shared by both slice-boundary call sites (`peaks job checkpoint --state
+ * done` and `peaks request transition rd:qa-handoff`) so the two cannot
+ * drift into disagreeing about what counts as visible.
+ *
+ * Returns the result's own `note` verbatim rather than rebuilding a
+ * sentence: that note is where the reason (exit code / upstream error line)
+ * and the remedy live, and a second wording here would be a second truth.
+ *
+ * `no-codegraph-dir` is deliberately SILENT — see the header's A2 note. A
+ * store that exists and did not refresh is a warning; a project that never
+ * set codegraph up is not a defect to report at every slice boundary.
+ */
+export declare function codegraphRefreshNotice(result: CodegraphAutorefreshResult): string | null;
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -15,8 +15,8 @@
 // hook install surface needed), fires exactly once at the true slice
 // boundary, and needs no IDE hook plumbing.
 //
-// The refresh is best-effort and FAIL-SILENT — it never throws and never
-// blocks the checkpoint/transition ok envelope:
+// The refresh is best-effort and never throws, and it never blocks the
+// checkpoint/transition ok envelope:
 //   - No `<projectRoot>/.codegraph/` directory → skip (codegraph was
 //     never initialized for this project; `peaks codegraph init` is a
 //     one-time setup the orchestrator owns).
@@ -29,6 +29,24 @@
 //     human-readable note.
 //   - Any unexpected error → return `unavailable` with a note.
 //
+// A2 (`2026-09-17-codegraph-msg-and-refresh`). The old header said
+// "FAIL-SILENT", and it was: both call sites discarded this result's `note`,
+// so a refresh that DID NOT HAPPEN and one that did were indistinguishable
+// to the operator — the same silent-failure class this job exists to close.
+// "Never blocks the caller" is the correct half and is KEPT; "never tells
+// anyone" was not.
+//
+// The two halves are split by whether a refresh was EXPECTED:
+//   - `no-codegraph-dir` → the project has no codegraph store (or has a
+//     foreign, never-initialized one). Nothing was expected, so nothing is
+//     reported: warning on every slice boundary of every project that never
+//     opted in is noise that trains the reader to skip the line that
+//     matters. The note is still in the JSON envelope.
+//   - `index-failed` / `unavailable` → a store EXISTS and is in use, so the
+//     refresh was expected and did not happen. That is a real failure and
+//     `codegraphRefreshNotice` turns it into an operator-visible warning
+//     naming the reason and the remedy.
+//
 // We do NOT auto-init a genuinely fresh (no `.codegraph/` dir) project:
 // the orchestrator owns that one-time setup. The dangling self-heal above
 // IS an auto-init, but `codegraph init` (WITHOUT `--index`) is fast (~1 s)
@@ -39,6 +57,28 @@ import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
+/**
+ * The operator-facing line for a refresh that did not happen, or `null` when
+ * there is nothing to report. The ONE place the report/no-report rule lives,
+ * shared by both slice-boundary call sites (`peaks job checkpoint --state
+ * done` and `peaks request transition rd:qa-handoff`) so the two cannot
+ * drift into disagreeing about what counts as visible.
+ *
+ * Returns the result's own `note` verbatim rather than rebuilding a
+ * sentence: that note is where the reason (exit code / upstream error line)
+ * and the remedy live, and a second wording here would be a second truth.
+ *
+ * `no-codegraph-dir` is deliberately SILENT — see the header's A2 note. A
+ * store that exists and did not refresh is a warning; a project that never
+ * set codegraph up is not a defect to report at every slice boundary.
+ */
+export function codegraphRefreshNotice(result) {
+    if (result.refreshed)
+        return null;
+    if (result.reason === 'no-codegraph-dir')
+        return null;
+    return result.note;
+}
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -62,6 +102,12 @@ function isCodegraphPeaksLoopManaged(projectRoot) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+// A2: the remedy half of an operator-visible failure note. Phrased like the
+// existing follow-up-index warning in `codegraph-exclude-repair.ts` so the
+// two read as one voice; it names the command the LLM/orchestrator re-runs,
+// never a verb the user is asked to type (Human-NL-Choice-Only — the same
+// posture that warning already ships with).
+const REFRESH_REMEDY = 'Run `peaks codegraph index --project <root>` to refresh the codegraph index.';
 function firstMeaningfulLine(text) {
     const trimmed = text.trim();
     if (trimmed.length === 0)
@@ -105,7 +151,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
                 return {
                     refreshed: false,
                     reason: 'index-failed',
-                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`,
                 };
             }
             // That init just wrote upstream's 99-rule default `exclude`
@@ -126,7 +172,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
             return {
                 refreshed: false,
                 reason: 'index-failed',
-                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`,
             };
         }
         return { refreshed: true };
@@ -135,7 +181,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'unavailable',
-            note: `auto codegraph refresh unavailable: ${errorMessage(error)}`,
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`,
         };
     }
 }

package/dist/services/codegraph/codegraph-config-repair-writer.d.ts

@@ -0,0 +1,88 @@
+/** Suffix of the byte-exact pre-repair copy kept next to the config. */
+export declare const CODEGRAPH_CONFIG_BACKUP_SUFFIX = ".bak";
+export type CodegraphExcludeRepairPlan = {
+    /** True when at least one rule would actually be dropped. */
+    readonly changed: boolean;
+    /** The `exclude` array after the removal. */
+    readonly exclude: readonly string[];
+    /** Rules actually present in `exclude` and dropped, in config order. */
+    readonly removedRules: readonly string[];
+};
+/**
+ * Pure: given the current `exclude` list and the rules to drop, return
+ * the new list. No fs, no clock, no serialization.
+ *
+ * A rule named in `rulesToRemove` but absent from `exclude` is NOT
+ * invented — the result is a subset of the input, so a caller can
+ * never add a rule by accident. Removing an already-absent rule is a
+ * no-op, which is what makes the whole repair idempotent: feeding the
+ * repaired list back in yields `changed: false`.
+ */
+export declare function repairCodegraphExclude(input: {
+    readonly exclude: readonly string[];
+    readonly rulesToRemove: readonly string[];
+}): CodegraphExcludeRepairPlan;
+/**
+ * Pure: given the current `include` list and the patterns to append, return
+ * the new list. The mirror of `repairCodegraphExclude`, in the other
+ * direction — a SUPERSET operation instead of a subset one.
+ *
+ * A pattern already present is not appended twice: the include reconciler
+ * already guarantees that, but this function is the writer's own last line
+ * of defence, and a duplicated glob in a third-party config would be a
+ * visible defect even though it changes no matching behaviour.
+ */
+export declare function repairCodegraphInclude(input: {
+    readonly include: readonly string[];
+    readonly patternsToAdd: readonly string[];
+}): {
+    readonly changed: boolean;
+    readonly include: readonly string[];
+    readonly addedPatterns: readonly string[];
+};
+export type CodegraphConfigRepairPlan = {
+    /** Rules from the exclude reconciler to drop. */
+    readonly rulesToRemove: readonly string[];
+    /** Patterns from the include reconciler to append. */
+    readonly includePatternsToAdd: readonly string[];
+};
+export type CodegraphConfigRepairOutcome = {
+    readonly applied: false;
+    readonly reason: 'nothing-to-repair';
+    readonly removedRules: readonly string[];
+    readonly addedIncludePatterns: readonly string[];
+} | {
+    readonly applied: true;
+    readonly configPath: string;
+    readonly backupPath: string;
+    readonly removedRules: readonly string[];
+    readonly addedIncludePatterns: readonly string[];
+    readonly excludeCountBefore: number;
+    readonly excludeCountAfter: number;
+    readonly includeCountBefore: number;
+    readonly includeCountAfter: number;
+};
+/**
+ * Apply BOTH config repairs to `<projectRoot>/.codegraph/config.json` in one
+ * atomic rewrite.
+ *
+ * No-op (and no write, no mtime change, no backup) when both lists are
+ * empty. Otherwise: back up the original bytes to `config.json.bak`, then
+ * rewrite the file with `exclude` reduced by exactly the rules that were
+ * both requested and present, and `include` extended by exactly the
+ * patterns that were both requested and absent.
+ *
+ * ONE rewrite, not two. A caller that widened `include` in one write and
+ * dropped the newly-offending `exclude` rules in a second would leave a
+ * window in which the config on disk is worse than it started (the widened
+ * include admits a file that a surviving rule then hides from the index),
+ * and would need two backups to stay rollback-exact. One rewrite through
+ * the same-directory temp file has neither property.
+ *
+ * Throws only on real fs/parse failures and on the containment refusal
+ * above — the caller decides whether that is fatal (`repair-exclude` /
+ * `repair-index` → non-zero exit) or a surfaced warning (`init` → keep
+ * going, the init itself already succeeded). Both are refusals BEFORE
+ * anything is written, so a throw can never half-apply.
+ */
+export declare function applyCodegraphConfigRepair(projectRoot: string, repair: CodegraphConfigRepairPlan): CodegraphConfigRepairOutcome;