peaks-loop 4.0.53 → 4.1.0

package/scripts/sync-version.mjs

@@ -9,13 +9,27 @@ if (typeof version !== 'string' || version.length === 0) {
   throw new Error('package.json version must be a non-empty string');
 }
 
+// Emitted SINGLE-quoted, not via `JSON.stringify`. `JSON.stringify` quotes with
+// `"`, and the repo's own prettier config (`package.json#prettier`,
+// `singleQuote: true`) is what the husky gate runs over this tracked file — so a
+// double-quoted emit made `prettier --check` fail on version.ts after every run.
+// This script runs in `build` / `prepack` / `prepublish` / `pretest`, so every
+// build dirtied a tracked file against a `prettierUnformatted` ceiling of 0
+// (reproduced + fixed in slice S5a, 2026-09-19). A version that cannot be
+// written as a single-quoted TS literal throws instead of being escaped: the
+// alternative is silently emitting broken source, which is the same failure the
+// RUNTIME_VERSION writer below refuses with a throw.
+if (/['\\\r\n]/.test(version)) {
+  throw new Error(`package.json version cannot be emitted as a single-quoted literal: ${version}`);
+}
+
 // Slice 3a — version.ts lives in the peaks-loop-shared workspace package.
 // The shared package is `private: true` and is consumed via workspace:*,
 // so its own package.json `version` field is irrelevant for downstream
 // consumers; we always emit the main peaks-loop version.
 writeFileSync(
   resolve('packages/peaks-loop-shared/src/version.ts'),
-  `export const CLI_VERSION = ${JSON.stringify(version)};\n`,
+  `export const CLI_VERSION = '${version}';\n`
 );
 
 // Slice 2026-09-11 (runtime-version-lockstep) — sync RUNTIME_VERSION.
@@ -23,17 +37,21 @@ writeFileSync(
 // `RUNTIME_VERSION` under a comment stating it tracks the peaks-loop root
 // version, but nothing wrote it: v4.0.37 was tagged with the constant still
 // at 4.0.36 and publish.yml's gate-cli-version step aborted before npm
-// publish. The literal is replaced in place, single-quoted — the exact
-// shape the gate greps — because the file also holds the package's public
-// exports and must never be regenerated wholesale. A literal we cannot
+// publish. The literal is replaced in place, preserving whichever quote the
+// declaration currently uses — the file also holds the package's public
+// exports and must never be regenerated wholesale, and since the gate reads
+// the VALUE (rid 2026-10-03-release-gate-quote-brittle) the writer must not
+// re-assert one quote style either. A literal we cannot
 // find throws instead of no-op'ing: that silence is how the drift reached CI.
 const runtimeIndexPath = resolve('packages/peaks-loop-internal-runtime/src/index.ts');
 const runtimeIndex = readFileSync(runtimeIndexPath, 'utf8');
-const runtimeDecl = /(export const RUNTIME_VERSION = ')[^']*(';)/;
+const runtimeDecl = /(export const RUNTIME_VERSION = (['"]))[^'"]*\2(;)/;
 if (!runtimeDecl.test(runtimeIndex)) {
-  throw new Error(`${runtimeIndexPath}: could not find "export const RUNTIME_VERSION = '...';"`);
+  throw new Error(
+    `${runtimeIndexPath}: could not find export const RUNTIME_VERSION = '<version>'; (single- or double-quoted)`
+  );
 }
-const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2`);
+const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2$3`);
 if (syncedRuntimeIndex !== runtimeIndex) {
   writeFileSync(runtimeIndexPath, syncedRuntimeIndex);
 }
@@ -102,4 +120,3 @@ for (const ext of ['js', 'd.ts', 'd.ts.map']) {
 // that a stale packages/peaks-loop-shared/dist/version.js is
 // actually removed. If you need the unlink pinned, that test has
 // to be written — the one named here no longer exists.
-

package/scripts/watch.mjs

@@ -72,7 +72,10 @@ export function runCommand(command, args, options = {}) {
         return;
       }
 
-      settle(rejectPromise, new Error(`${command} ${args.join(' ')} failed with exit code ${code}`));
+      settle(
+        rejectPromise,
+        new Error(`${command} ${args.join(' ')} failed with exit code ${code}`)
+      );
     });
   });
 }
@@ -383,7 +386,10 @@ async function main() {
   await watchMode.start();
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
   main().catch((error) => {
     process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
     process.exitCode = 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/SKILL.md

@@ -207,7 +207,7 @@ Before the first planning action, run `peaks fresh-context preflight --prompt "<
 | `0.85 ≤ ratio < 0.95` | **pre-compact zone** | `peaks code auto-compact` fires **automatically** (deferred only when in-flight sub-agent batch is running; fires the moment the batch lands). The LLM does not prompt the user. In practice peaks-loop already fired at the 0.80 tier above, so this band is today the "already fired" zone; `peaks code context-now` reports `action: 'auto-compact-now'` from 0.85 up. |
 | `ratio ≥ 0.95` | **red-line (Karpathy §4)** | `peaks code auto-compact` invoked immediately; `peaks code context-now` returns `action: 'red-line'`. **Since 4.0.47 the red line REQUESTS the compaction and says it is waiting — it does NOT block sub-agent dispatch, and it does not refuse to advance.** Keep working and re-probe with `peaks code context-now`; the harness performs the compaction, and nothing peaks-loop can do lowers the ratio on its own, so blocking here was a deadlock rather than a gate. If the ratio keeps climbing and no compaction lands, report that and hand control back — do not stall. `--bypass-red-line` is a no-op. |
 
-**Probe primitive (single source of truth):** `peaks code context-now --json`. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks code auto-compact` on `auto-compact-now` or `red-line` without user confirmation.
+**Probe primitive:** `peaks code context-now --json` — authoritative for `ratio` and for the `action` tier **from 0.85 up**. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks code auto-compact` on `auto-compact-now` or `red-line` without user confirmation. **It has no 0.80 tier** (see the tier table above): the `0.80 ≤ ratio < 0.85` band belongs to `peaks skill presence`'s `auto-fire`, and that probe runs every turn. **Read both probes and act on whichever fires first — the earlier of the two governs, so 0.80, not 0.85.**
 
 **Enforcement layers (defense in depth):**
 1. `src/services/code/auto-compact-orchestrator.ts` — `evaluateAutoCompactDecision` default-returns `shouldCompact: true` for both `pre-compact` and `red-line`. Only deferral is `inFlightBatch.hasInFlightBatch` (D6.e); no LLM/human approval branch.

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. |