peaks-loop 4.0.10 → 4.0.12

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

@@ -65,4 +65,20 @@ The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool
 
 If the framework is not obvious from `package.json#scripts.test`, the sub-agent should run `peaks test --json` to introspect the resolved framework + argv before picking a runner.
 
-See the block constant at `src/services/dispatch/test-tool-detection.ts` for the verbatim text.
+See the block constant at `src/services/dispatch/test-tool-detection.ts` for the verbatim text.
+
+## BDD Test Style Verification (effective rid-2026-08-05-bdd-test-style, v4.0.11+)
+
+When you (peaks-qa) verify a slice, you MUST run the BDD test-style verifier on every new or modified `tests/unit/**/*.test.ts` file in the slice's git diff. Use:
+
+```bash
+node -e "
+const { verifyBddStyle } = await import('./src/services/qa/bdd-test-style-verifier.ts');
+const { execSync } = require('node:child_process');
+const files = execSync('git diff --name-only HEAD~1 -- tests/unit', { encoding: 'utf8' })
+  .split('\n').filter(f => f.endsWith('.test.ts'));
+console.log(JSON.stringify(verifyBddStyle({ projectRoot: '.', testFiles: files })));
+"
+```
+
+If the verifier returns `ok: false`, your verdict MUST be `failed: bdd-style-violation` with the structured reason from the verifier (do NOT mark the slice as passing).

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

@@ -147,4 +147,24 @@ Touch only what you must. Clean up only your own mess. When editing existing cod
 Define success criteria. Loop until verified. "Add validation" → write tests for invalid inputs, then make them pass. "Fix the bug" → write a test that reproduces it, then make it pass. For multi-step tasks, state a brief plan with verify checkpoints. Strong success criteria let you loop independently. Weak criteria require constant clarification.
 ```
 
-Sub-agents MUST NOT silently drop this block. The regression test `tests/unit/skills/karpathy-prompt-injection.test.ts` asserts this block is present. The canonical skill id for the full guidelines text is `andrej-karpathy-skills:karpathy-guidelines`.
+Sub-agents MUST NOT silently drop this block. The regression test `tests/unit/skills/karpathy-prompt-injection.test.ts` asserts this block is present. The canonical skill id for the full guidelines text is `andrej-karpathy-skills:karpathy-guidelines`.
+
+## BDD Test Style Contract (effective rid-2026-08-05-bdd-test-style, v4.0.11+)
+
+When you (the LLM sub-agent) write new or modified unit tests in `tests/unit/**`, every `it()` / `test()` block MUST follow the given-when-then contract:
+
+1. The first string-literal argument of `it()` / `test()` MUST describe business behavior in the form `when X, should Y` — must include either the word "when" (state / pre-condition) or "should" (observable outcome).
+2. The body callback (the second argument) MUST start with exactly 3 leading comments:
+   ```typescript
+   // given: <precondition — system / user state>
+   // when: <action — what is invoked>
+   // then: <expected outcome — what is asserted>
+   ```
+3. Legacy `// arrange:` / `// act:` / `// assert:` AAA markers MUST NOT appear in tests you write.
+
+Run `node scripts/migrate-to-bdd.mjs --dry-run <file>` before writing new tests to inspect the contract, or use the Slice B verifier's rule directly:
+
+- description: must contain `/(\bwhen\b|\bshould\b)/`
+- first 3 body comments: must match `/^\s*\/\/\s*given\s*:/`, `/^\s*\/\/\s*when\s*:/`, `/^\s*\/\/\s*then\s*:/`
+
+If your tests fail peaks-qa's `bdd-test-style-verifier` (see Slice B), the slice will be returned-to-rd. Fix the violations, do NOT bypass the check.

package/skills/peaks-code/SKILL.md

@@ -102,6 +102,10 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 
 **Step 0.7 resume rule (read-FIRST):** on resume, `peaks code gate-step-08` reads `progress.json` first and surfaces `Next: slice #N of M (<currentSlice>)` so the orchestrator picks up at the right slice without re-reading the artifact tree.
 
+### Peaks-Loop Step 0.51 — `orchestrator-can-do` probe (slice 2026-08-05, lesson-encoded CLI)
+
+> **Before deciding to push a slice to the next session**, run `peaks code orchestrator-can-do --slice-spec '<text>' --json`. The command evaluates 4 boundary questions (source code? sub-agent available? requires user decision? context sustainable?) and returns whether the slice can be done in the current session. Default to `canDoInSession=true` unless hard blockers are present; sub-agent dispatch (`peaks sub-agent dispatch rd`) is the canonical delegation path for source-code changes. This encodes the 2026-08-05 lesson — orchestrator MUST NOT Edit/Write `src/` directly, but MUST delegate via sub-agent dispatch. See `.peaks/memory/2026-08-05-peaks-code-orchestrator-capability-misjudgment.md`.
+
 ### Peaks-Loop Step N+2: Auto-compact at the warning line (v2.13.0 zero-pause contract)
 
 > **Zero-pause contract.** When context usage crosses the pre-compact threshold, peaks-loop **automatically fires `peaks compact auto --execute` — the LLM does NOT prompt the user to run `/compact` manually**. Stale prose that says "ask the user to compact" silently stalls the workflow. The v2.13.0 contract makes auto-compact a system responsibility, not a user action.
@@ -127,6 +131,8 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 
 If the prose audit (`peaks audit red-lines`) flags any of the above, the slice is **blocked** until the prose is rewritten.
 
+See also: references/session-overload-signal-index.md for the 7-signal lookup table the LLM consults before deciding to open a new session.
+
 ## CLI Drift Index (sediment 2026-07-09)
 
 > **Reading guide:** Verified against peaks-loop 4.0.0-beta.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing.

package/skills/peaks-code/references/session-overload-signal-index.md

@@ -0,0 +1,60 @@
+# Session Overload Signal Index
+
+> Single-source lookup for the LLM-side "should I open a new session?" decision.
+> Slice 2026-08-05-session-overload-signal-index.
+
+## What this doc is
+
+When the LLM senses context pressure, it must consult these 7 signals before
+deciding to (a) auto-compact, (b) refuse the next slice, or (c) ask the user to
+open a new session. The contract is: **LLM never re-asks the user about
+cost/length/context** (red line #2 of `references/job-loop.md`). This index is
+the lookup table the LLM must consult in lieu of intuition.
+
+## The 7 signals
+
+| # | Signal source | Threshold | File / CLI | LLM action |
+|---|---|---|---|---|
+| 1 | prompt size (main session) | 50% / 75% / 80% / 90% | `src/services/context/threshold.ts`; probe via `peaks code context-now` | soft-warn at 50%; consider compact at 75%; MUST NOT auto-compact mid-batch (D6.e); Job mode ≥ 0.85 ⇒ MANDATORY `peaks compact auto --execute` |
+| 2 | auto-compact zone | 0.85 pre-compact / 0.95 red-line | `src/services/code/auto-compact-orchestrator.ts`; `--enforce-job-mode` flag | Auto-fires `peaks compact auto --execute`; LLM MUST NOT prompt user to compact (zero-pause contract v2.13.0) |
+| 3 | sub-agent dispatch prompt size | 50% / 75% / 80% | `src/services/context/context-guard.ts`; `peaks sub-agent-dispatch-guard` PreToolUse hook | soft-warn at 50%; CONTEXT_NEAR_LIMIT at 75%; hard-reject at 80% (CLI + hook double-guard) |
+| 4 | statusline compact bar | visual | `src/services/compact-statusline/compact-statusline-service.ts` | ambient UI; surfaces queued/preparing/compacting/verifying/completed/failed/stalled |
+| 5 | in-flight batch deferral | D6.e | `src/services/code/auto-compact-modes.ts` | defer compact until batch lands (NOT "new session") |
+| 6 | compact stalled | 120s heartbeat timeout | `compact-lifecycle-store.ts` | ambient "stalled" detail in statusline |
+| 7 | sub-agent heartbeat missing | per-role TTL | `peaks sub-agent heartbeat`; `peaks heartbeat-watch` | orchestrator-side warning, not LLM-driven "new session" |
+
+## Hard rules
+
+- peaks-code SKILL.md red line #2 (see `references/job-loop.md`):
+  **Re-ask the user about cost / length / context is forbidden**.
+  The LLM MUST NOT prompt the user to open a new session based on overload
+  intuition alone; it MUST consult the 7 signals above and prefer auto-compact /
+  sub-agent dispatch guard / heartbeat-watch first.
+- "Open a new session" is a **last resort** after auto-compact has been
+  attempted and the slice cannot fit. The user's role is to receive the
+  handoff capsule, not to micro-manage session lifecycle.
+
+## Decision flowchart
+
+```
+LLM senses context pressure
+  ├─► Probe `peaks code context-now --json`
+  │   ├─ ratio < 0.50  → continue (no action)
+  │   ├─ 0.50 ≤ ratio < 0.75 → soft-warn; continue
+  │   ├─ 0.75 ≤ ratio < 0.85 → compact-zone candidate
+  │   │     ├─ Job mode → MUST auto-compact now
+  │   │     └─ non-Job  → wait for next idle turn, then compact
+  │   ├─ 0.85 ≤ ratio < 0.95 → pre-compact zone; auto-compact MUST fire
+  │   └─ ratio ≥ 0.95       → red-line; synchronous gate (Karpathy §4)
+  ├─► Check statusline compact bar (signal #4)
+  │   ├─ queued / preparing / compacting / verifying → wait
+  │   ├─ failed → read failure reason, do NOT spawn new session
+  │   └─ stalled (>120s) → surface to user as a blocker, not a new-session ask
+  └─► Check sub-agent dispatch guard (signal #3)
+      ├─ 75% CONTEXT_NEAR_LIMIT → warn, continue with smaller prompt
+      └─ 80% PROMPT_TOO_LARGE → hard-reject; refactor the prompt
+
+Only after ALL three checks above have been attempted without resolution:
+emit the `peaks session split-handoff` capsule (NOT in this slice; follow-up)
+and the user opens a new session in their own time.
+```