peaks-loop 4.0.52 → 4.0.54

package/dist/services/rd/reviewer-dispatch-policy.js

@@ -26,12 +26,33 @@
  * PRD handoff + the project-scoped audit templates (slice v2.12.0
  * Tier 1+2+3 = Group A).
  *
- * The dispatch policy here is the **canonical decision table** consumed
- * by the LLM-side runner and pinned by tests:
- *   - `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts`
- *     (5 → 3 element pinning)
- *   - `tests/unit/rd/deprecated-reviewer-back-compat.test.ts`
- *     (NEW in v2.12.0 — 8 cases; back-compat for the 2 removed slots)
+ * This module holds the machine-readable decision table for that collapse;
+ * the prose the LLM runner actually reads is
+ * `skills/bee/peaks-rd/references/parallel-review-fanout.md`. It used to
+ * describe itself as "consumed by the LLM-side runner", which named no
+ * mechanism — an LLM reads prose, not TypeScript exports — and that is the
+ * reason every export below sat at zero importers until slice F2.
+ *
+ * Pinning is half-done. The two test files this block used to cite —
+ * `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts` (the 5 → 3
+ * element pinning) and
+ * `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (the 8
+ * back-compat cases) — were both deleted in `f17aa377`. The **predicate
+ * half** was re-pinned by `tests/unit/rd/reviewer-dispatch-policy.test.ts`
+ * (`7191140f`, 6 cases: `RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`).
+ * The **decision-table half** — `RD_FANOUT_REVIEWERS`' 3-element
+ * membership, `reviewerListFor`, `karpathySlotIndex`,
+ * `shouldDispatchKarpathy` — still has no pin.
+ *
+ * Slice F2 (rid-f2-ac1-wiring) gave this module its FIRST caller in
+ * `src/cli/commands/sub-agent-shared.ts` (`deprecatedReviewerWarnings`),
+ * invoked from the dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and pinned by
+ * `tests/unit/cli/sub-agent-dispatch-deprecated-reviewer.test.ts`. Before
+ * that, all 13 exports had zero importers across src/ + packages/ +
+ * scripts/, so nothing rejected or rerouted `security-reviewer` /
+ * `perf-baseline-reviewer` on the way in. That import is still the only
+ * one: the other 12 exports below remain unreferenced in this repo.
  *
  * For `config | docs | chore` request types, the slice already skips
  * the entire fanout (SKILL.md line 132 says "Config / docs / chore: no
@@ -47,8 +68,15 @@
  * back-compat window. The `isDeprecatedReviewer(name)` predicate lets
  * dispatchers (or legacy on-disk rd/{security-review,perf-baseline}.md
  * readers) detect a removed slot and route to the new audit skill
- * instead of failing the gate. See Tier 5 (`artifact-prerequisites.ts`)
- * for the matching prereq-side back-compat (`mustContainAny` form).
+ * instead of failing the gate. Tier 5 (`artifact-prerequisites.ts`)
+ * holds the matching prereq-side back-compat: `AUDIT_SECURITY` /
+ * `AUDIT_PERF` accept the legacy `rd/security-review.md` /
+ * `rd/perf-baseline.md` artifacts via `legacyRelativePaths`.
+ *
+ * Both halves are wired as of slice F2 and both ACCEPT the legacy slot.
+ * The dispatch side emits the reroute notice as a warning
+ * (`deprecatedReviewerWarnings`) rather than a refusal, precisely so it
+ * does not disagree with the prereq side about the same deprecation.
  */
 export const RD_REVIEW_REQUEST_TYPES = [
     'feat',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.52",
+  "version": "4.0.54",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -83,7 +83,7 @@
     "schemas/*.json",
     ".claude-plugin/**",
     "config/eslint/.peaks-rules.cjs",
-    "docs/test-style-contract.md",
+    "contracts/test-style-contract.md",
     "README.md",
     "README-en.md",
     "CHANGELOG.md",
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.37",
-    "peaks-loop-mut": "0.1.50",
-    "peaks-loop-shared": "0.0.86",
-    "peaks-loop-shared-channel": "0.0.54"
+    "peaks-loop-internal-runtime": "0.0.39",
+    "peaks-loop-shared": "0.0.88",
+    "peaks-loop-shared-channel": "0.0.56",
+    "peaks-loop-mut": "0.1.52"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-rd/SKILL.md

@@ -65,7 +65,7 @@ Every RD action MUST align with the 4 Karpathy guidelines (full text at `andrej-
 3. **Surgical Changes** — touch only what the user's request requires. Remove imports / variables / functions that *your* changes made unused. Do not refactor adjacent code. Every changed line must trace to the user's request.
 4. **Goal-Driven Execution** — define verifiable success criteria (`peaks request show --role rd` carries ACs from PRD). For multi-step work, state plan + verify checkpoints before acting.
 
-Cross-references: Slice 1 PRD §AC-1. The 4-point assertion guard that PRD named was deleted in `f17aa377`; the block below is held by documentation only. The canonical skill id is `andrej-karpathy-skills:karpathy-guidelines`.
+Cross-references: Slice 1 PRD §AC-1. The 4-point assertion guard that PRD named was deleted in `f17aa377`; it is re-pinned by `tests/unit/skills/karpathy-injection.test.ts`, which fails if any of the 4 titles above is dropped. The canonical skill id is `andrej-karpathy-skills:karpathy-guidelines`.
 
 ## Scope directory (slice 10 — read scopeDir from envelope)
 

package/skills/bee/peaks-rd/references/rd-fanout-contracts.md

@@ -20,10 +20,12 @@ end of implementation, RD fires 3 sub-agents in parallel via
 > `.peaks/project-scan/{security-template, perf-template, audit-output-schema}.md`.
 > The handoff presence is enforced by the `AUDIT_REQUIRES_HANDOFF` prereq.
 > The 1-minor-release back-compat window (`v2.12.0`) keeps the old
-> `rd/{security-review,perf-baseline}.md` paths readable via `mustContainAny` —
+> `rd/{security-review,perf-baseline}.md` paths readable via
+> `legacyRelativePaths` —
 > see `RD_DEPRECATED_REVIEWERS` in
 > `src/services/rd/reviewer-dispatch-policy.ts`. The two unit tests that
-> once pinned this were deleted in `f17aa377` and have not been replaced.
+> once pinned this were deleted in `f17aa377`; see §"Deprecated reviewer
+> back-compat" for which half has been re-pinned since and which has not.
 
 ## The 3 sub-agents
 
@@ -72,15 +74,16 @@ end of implementation, RD fires 3 sub-agents in parallel via
 > - ~~Sub-agent — security-reviewer~~ — moved to standalone
 >   `peaks-security-audit` skill; output `audit/security-<rid>.md`. The legacy
 >   path `.peaks/_runtime/<sessionId>/rd/security-review.md` remains
->   readable via `mustContainAny` for the v2.12.0 1-minor-release window.
+>   readable via `legacyRelativePaths` for the v2.12.0 1-minor-release window.
 > - ~~Sub-agent — perf-baseline-reviewer~~ — moved to standalone
 >   `peaks-perf-audit` skill; output `audit/perf-<rid>.md`. The legacy path
 >   `.peaks/_runtime/<sessionId>/rd/perf-baseline.md` remains readable
->   via `mustContainAny` for the v2.12.0 1-minor-release window.
+>   via `legacyRelativePaths` for the v2.12.0 1-minor-release window.
 >
 > See `RD_DEPRECATED_REVIEWERS` in
 > `src/services/rd/reviewer-dispatch-policy.ts`. The unit test that once
-> pinned this was deleted in `f17aa377` and has not been replaced.
+> pinned this was deleted in `f17aa377`; see §"Deprecated reviewer
+> back-compat" for what replaced it.
 
 ## Hard prohibitions on all 3 sub-agents (single block)
 
@@ -199,13 +202,26 @@ failing the gate.
 - **Legacy review artifact paths**
   (`.peaks/_runtime/<sessionId>/rd/security-review.md`,
   `.peaks/_runtime/<sessionId>/rd/perf-baseline.md`) are accepted via
-  `mustContainAny: [...]` on the `AUDIT_SECURITY` / `AUDIT_PERF` prereqs
+  `legacyRelativePaths` on the `AUDIT_SECURITY` / `AUDIT_PERF` prereqs
   during the back-compat window. v2.13.0 hard-deletes the legacy paths.
 
-**Pinning:** none. The routing + legacy-path acceptance live in
-`RD_DEPRECATED_REVIEWERS` / `isDeprecatedReviewer` in
-`src/services/rd/reviewer-dispatch-policy.ts`; the unit test that pinned
-them (8 cases) was deleted in `f17aa377` and has not been replaced.
+**Pinning — half of it.** The **predicate half**
+(`RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`) is pinned by
+`tests/unit/rd/reviewer-dispatch-policy.test.ts` (`7191140f`, 6 cases), and
+its dispatch-side *use* by
+`tests/unit/cli/sub-agent-dispatch-deprecated-reviewer.test.ts`
+(slice F2, `rid-f2-ac1-wiring`) — that one drives the real dispatch action
+and fails if the reroute notice stops being emitted.
+
+The **decision-table half** (`RD_FANOUT_REVIEWERS`' 3-element membership,
+`reviewerListFor`, `karpathySlotIndex`, `shouldDispatchKarpathy`) has **no
+pin**: the file that carried it was deleted in `f17aa377` and was not
+replaced. The routing + legacy-path acceptance live in
+`src/services/rd/reviewer-dispatch-policy.ts`; the module had **no caller
+at all** until slice F2 wired `deprecatedReviewerWarnings`
+(`src/cli/commands/sub-agent-shared.ts`) into the dispatch chokepoint. The
+dispatch side therefore ACCEPTS the legacy slot and warns, rather than
+refusing — matching the prereq-side acceptance above.
 
 ## Gate C evidence (RD-side, type-specific)
 

package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md

@@ -109,7 +109,7 @@ Any RD/QA/SC sub-agent dispatched by `peaks sub-agent dispatch --from-dag` (or b
 
 **Where the orchestrator reads the values from**: `data.orchestratorVisibleHint` (one line, copy verbatim) and `data.artifactsPublicPaths` (the public list of artifact paths the sub-agent will own). The CLI fills these in; the orchestrator just transcribes.
 
-**Regression guard**: none. The unit test that parsed `rd-sub-agent-dispatch.md` and asserted the G11.5 heading is present was deleted in `f17aa377`. The heading is held by convention only — do not delete it.
+**Regression guard**: `tests/unit/skills/g11-5-title-lock.test.ts` — it pins this file's G11.5 heading and the `⏳ Spawning sub-agent via Task tool: <description>` form. The original guard (the unit test that parsed `rd-sub-agent-dispatch.md` and asserted the G11.5 heading is present) was deleted in `f17aa377`; the pin was restored in slice D2 (2026-09-18), which found that the AC-3 title-lock had covered only the peaks-code sibling of this file. Do not delete the heading.
 
 ---
 

package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md

@@ -42,6 +42,7 @@ schemaVersion: '2.0'
 ---
 ```
 
+> The `gateEvidence` block above is the **feature-shaped** set, shown because it is the largest one. It is not a template to copy by hand: the producer derives the block from the request `type` (see the `gateEvidence` rule below), so a `config` slice's carries two keys and a `docs` / `chore` slice's capsule carries no such block at all.
 ## Field rules
 
 - `requestId` — kebab-case; matches the PRD `requestId`.
@@ -50,7 +51,11 @@ schemaVersion: '2.0'
 - `decisions[]` — every decision an LLM made that an implementer could question. `id` is local; `summary` is one line; `rationale` is ≤ 2 sentences.
 - `risks[]` — same shape; `mitigation` is required. A risk without a mitigation is a red line (gate blocked).
 - `nextActions[]` — verb-first; what peaks-qa should do next, in order.
-- `gateEvidence` — paths to the gate files peaks-qa will validate. Missing keys → Gate C failure.
+- `gateEvidence` — paths to the gate files peaks-qa will validate. **DERIVED, never hand-written**: the producer computes it from the request `type` (`src/services/prd/gate-evidence-derivation.ts`), and Gate C reads the same `rd:qa-handoff` row, so the block and the gate cannot disagree. It declares that row's evidence, plus `projectScan` (Gate A's artifact — declared only where Gate C runs, since a path nothing verifies should not be declared):
+  - `feature` / `refactor` / `bugfix` → **5 keys**: `projectScan`, `prdHandoff`, `codeReview`, `securityReview`, `perfBaseline`
+  - `config` → **2 keys**: `projectScan`, `securityReview`. `CONFIG_TABLE['rd:qa-handoff']` is the security review alone, so a config slice has **no** `prdHandoff`; and its security evidence is the genuinely ridless `rd/security-review.md`, not `audit/security-<rid>.md`.
+  - `docs` / `chore` → **no `gateEvidence` block at all**. Those types have no `rd:qa-handoff` row: there is no evidence to declare and nothing for Gate C to check, so the block is omitted rather than filled with an unverified statement. Such a capsule is byte-identical to a pre-B2 one.
+  **The Gate C failure rule is scoped to the types above** — where that gate runs: a declared path that does not exist fails `peaks request transition --state qa-handoff` (`PREREQUISITES_MISSING`), naming the key. Two shapes are deliberately NOT failures: a capsule for a type with no `rd:qa-handoff` row (the check does not run), and an **empty** declaration (`gateEvidence: {}`) — a weak claim, not a false one, since the type's artifacts remain enforced by the table itself, so an empty map cannot open the gate. When the request type cannot be resolved at all, the block is omitted rather than half-declared.
 - `schemaVersion: '2.0'` — pinned (bumped from `'1.0'` in v2.11.0); bump only when the field set changes.
 
 > **v2.11.0 Group A change:** `schemaVersion` was bumped to `'2.0'`. The consumers listed under §Validation anchor on that value, so a file still carrying `'1.0'` is rejected at read time.

package/skills/peaks-code/references/periodic-checkpoint.md

@@ -20,14 +20,16 @@ checkpoint as often as it wants.
 
 > **Slice 2026-06-24-efficiency-4p-bundle / G1 (P0.1) — frequency lock**:
 > The `--reason periodic` row above is hard-locked at **20 tool calls**.
-> The threshold is a textual contract between SKILL.md (line 79) and
-> this reference doc; the LLM runner is expected to fire
-> `peaks session checkpoint --reason periodic` once every 20 tool calls
+> The threshold is a textual contract between `startup-sequence.md` (Step N:
+> Periodic checkpoint) and this reference doc; the LLM runner is expected to
+> fire `peaks session checkpoint --reason periodic` once every 20 tool calls
 > (i.e. on each 20-call mark, not "approximately every 20"). The CLI
 > does **not** expose a `--periodic-every <n>` override flag — the
 > cadence is owned by the skill, not the CLI. Any patch that relaxes
-> this must update both files in lockstep; no guard fails on the drift
-> — the test that pinned the cadence was deleted in `f17aa377`.
+> this must update both files in lockstep —
+> `tests/unit/skills/periodic-checkpoint-cadence.test.ts` fails on the
+> drift (it pins the number in both files, the hard-lock wording, and the
+> CLI's lack of the override).
 
 ## Checkpoint CLI contract
 

package/skills/peaks-code/references/startup-sequence.md

@@ -19,7 +19,7 @@ When a NEW conversation opens on a session whose `lastActivity` is from today AN
 
 ### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
 
-Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `periodic-checkpoint.md` (no guard fails on a missed cadence — the test that did was deleted in `f17aa377`).
+Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `periodic-checkpoint.md` (the cadence is pinned by `tests/unit/skills/periodic-checkpoint-cadence.test.ts`, which fails if either file's number drifts).
 
 ### Peaks-Loop Step 0.6: Audit + Goal (NEW)
 

package/skills/peaks-final-review/SKILL.md

@@ -230,6 +230,6 @@ When handing off, emit: rid, `allPass`, `needsAttention[]`, output path, source
 | `src/services/final-review/final-review-types.ts` | `FinalReviewOutput`, `DimensionEvidence`, verdict/evidence/confidence enums. |
 | `src/services/audit/audit-goal-service.ts:16` | Line of evidence that `LlmRunner` is reusable across audit + final-review (service-level integration). |
 | `tests/unit/final-review/final-review-service.test.ts` | Service-level unit tests (8 cases: evidence inlining, the no-evidence⇒no-`pass` gate, prompt bounds, plus contract guards). |
-| `docs/superpowers/plans/2026-06-25-slice-topology-multipass-phase-4.md:127` | Phase-4 plan prose (Task 14). |
+| *(retired — no file)* | The Phase-4 plan prose (Task 14) this row used to cite was deleted in `e6e35842`; no file on this tree carries it, and nothing pins it since. |
 | `skills/bee/peaks-qa/SKILL.md` | Upstream QA skill — 4-dim review is downstream of all QA gates. |
 | `skills/peaks-audit/SKILL.md` | Sibling skill — produces the `audit-goal` JSON that this skill consumes. |