peaks-loop 4.0.9 → 4.0.11

package/dist/services/skills/skill-statusline-service.js

@@ -3,6 +3,8 @@ import { resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { decideCompactStatusline } from '../compact-statusline/compact-statusline-service.js';
 import { getSessionIdCanonical } from '../session/session-manager.js';
+import { resolveActiveSkillForCaller } from '../audit/enforcers/active-skill-resolver.js';
+import { readActiveDispatchIndex } from '../dispatch/dispatch-record-writer.js';
 /**
  * Out-of-band Peaks skill status renderer for the Claude Code statusLine.
  *
@@ -47,11 +49,95 @@ export function parseStatusLineStdin(raw) {
         return null;
     }
 }
+/**
+ * Resolve the callerId for the read-side isolation. Order of resolution:
+ *   1. `stdin?.caller_id` (when the harness / IDE adapter forwards it)
+ *   2. `process.env.CLAUDE_CODE_SESSION_ID` (Claude Code's ambient session id;
+ *      used as a coarse callerId surrogate when stdin omits caller_id)
+ *   3. `null` (no callerId — caller falls back to the project-level
+ *      single-file read for back-compat)
+ */
+function resolveCallerId(stdin) {
+    const fromStdin = typeof stdin?.caller_id === 'string' && stdin.caller_id.length > 0
+        ? stdin.caller_id
+        : null;
+    if (fromStdin !== null)
+        return fromStdin;
+    const fromEnv = process.env['CLAUDE_CODE_SESSION_ID'];
+    if (typeof fromEnv === 'string' && fromEnv.length > 0)
+        return fromEnv;
+    return null;
+}
+/**
+ * Read the active-dispatch index for the canonical session, filter to
+ * in-flight entries (status NOT IN { done, failed, cancelled, no-execution,
+ * never-started, unreadable, stale }), and return the most-recent leaf role
+ * plus the total in-flight count. Returns `{ role: null, pendingCount: 0 }`
+ * when no session id resolves, the index is empty, or every entry is terminal.
+ *
+ * READ-ONLY: only reads `.peaks/_sub_agents/<sid>/active-dispatches.json`.
+ * Never mutates the on-disk record.
+ */
+function readActiveLeaf(projectRoot, sessionId) {
+    if (sessionId === null)
+        return null;
+    let index = {};
+    try {
+        index = readActiveDispatchIndex(projectRoot, sessionId);
+    }
+    catch {
+        return null;
+    }
+    const terminalStatuses = new Set([
+        'done',
+        'failed',
+        'cancelled',
+        'no-execution',
+        'never-started',
+        'unreadable',
+        'stale',
+        'queued', // Slice 2026-08-05 fix: stale dispatch entries stuck at 'queued' should
+        // not pollute statusline as in-flight leaves.
+    ]);
+    const inFlight = Object.values(index).filter((e) => !terminalStatuses.has(e.status));
+    if (inFlight.length === 0)
+        return null;
+    // Sort by createdAt descending — the most recently dispatched leaf wins.
+    const sorted = inFlight.slice().sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const latest = sorted[0];
+    if (latest === undefined)
+        return null;
+    return { role: latest.role, pendingCount: inFlight.length };
+}
 /**
  * Read the presence file without any side effects. Returns null when the file is
  * absent (idle) and a sentinel object for malformed content (invalid-presence).
+ *
+ * When `callerId` is non-null, delegates to the canonical lease resolver
+ * (presence-lease-service via active-skill-resolver) so the read is
+ * session+caller-isolated. When `callerId` is null, falls back to the
+ * project-level single-file read (back-compat for callers that don't pass
+ * a callerId yet, e.g. legacy CLI invocations).
  */
-function readPresenceReadOnly(projectRoot) {
+function readPresenceReadOnly(projectRoot, callerId) {
+    if (callerId !== null) {
+        try {
+            const resolution = resolveActiveSkillForCaller(projectRoot, { legacyPresence: true, callerId });
+            if (resolution.source === 'none' || resolution.skill === null) {
+                return { presence: null, invalid: false };
+            }
+            return {
+                presence: {
+                    skill: resolution.skill,
+                    ...(resolution.mode !== null ? { mode: resolution.mode } : {}),
+                },
+                invalid: false,
+            };
+        }
+        catch {
+            return { presence: null, invalid: true };
+        }
+    }
     const presencePath = resolve(projectRoot, PRESENCE_FILE);
     // Back-compat: prefer the new canonical path; fall back to the legacy
     // `.peaks/.active-skill.json` for one minor release.
@@ -91,14 +177,16 @@ export function buildStatusLineModel(stdin, nowMs) {
     // fallbacks). It replaces the active skill content when kind != 'none'.
     const compact = readCompactState(projectRoot, nowMs);
     if (projectRoot === null) {
-        return { state: 'idle', projectRoot: null, presence: null, ageMs: null, compact };
+        return { state: 'idle', projectRoot: null, presence: null, ageMs: null, compact, activeLeaf: null };
     }
-    const { presence, invalid } = readPresenceReadOnly(projectRoot);
+    // callerId resolves the read-side isolation; back-compat is `null`.
+    const callerId = resolveCallerId(stdin);
+    const { presence, invalid } = readPresenceReadOnly(projectRoot, callerId);
     if (invalid) {
-        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null, compact };
+        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null };
     }
     if (presence === null) {
-        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact };
+        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null };
     }
     // Session binding: when the presence was stamped with a Claude session id and
     // the live session (from stdin) is a different one, the recorded skill belongs
@@ -107,12 +195,24 @@ export function buildStatusLineModel(stdin, nowMs) {
     // fall back to the time-based behavior below for backward compatibility.
     const liveSessionId = typeof stdin?.session_id === 'string' && stdin.session_id.length > 0 ? stdin.session_id : null;
     if (presence.claudeSessionId && liveSessionId && presence.claudeSessionId !== liveSessionId) {
-        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact };
+        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null };
     }
     const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
     const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
     const state = ageMs !== null && ageMs > STALE_THRESHOLD_MS ? 'stale' : 'active';
-    return { state, projectRoot, presence, ageMs, compact };
+    // Active leaf resolution: read-only query against the per-session
+    // active-dispatches index. Filter to in-flight entries; pick the most
+    // recent by createdAt. The renderer uses this to surface the in-flight
+    // bee skill (e.g. `peaks-rd`) alongside the orchestrator (e.g. `peaks-code`).
+    let activeLeaf = null;
+    try {
+        const sessionId = getSessionIdCanonical(projectRoot);
+        activeLeaf = readActiveLeaf(projectRoot, sessionId);
+    }
+    catch {
+        activeLeaf = null;
+    }
+    return { state, projectRoot, presence, ageMs, compact, activeLeaf };
 }
 /**
  * Read-only compact state resolver. Resolves the canonical session id for the

package/dist/services/vm/vm-lease.js

@@ -20,6 +20,7 @@
  */
 import { randomBytes } from 'node:crypto';
 import { posix as path } from 'node:path';
+import { normalizePath } from '../../shared/path-utils.js';
 export const VM_HYPERVISORS = Object.freeze([
     'kvm', 'hyperkit', 'hyperv'
 ]);
@@ -128,7 +129,7 @@ export function deserializeVmLease(raw) {
 function joinPath(...segments) {
     if (segments.length === 0)
         return '';
-    const normalized = segments.map((s) => s.replace(/\\/g, '/'));
+    const normalized = segments.map((s) => normalizePath(s));
     let acc = normalized[0];
     for (let i = 1; i < normalized.length; i++) {
         acc = path.join(acc, normalized[i]);

package/dist/services/workflow/workflow-autonomous-resume-helpers.js

@@ -20,6 +20,7 @@ import { isAbsolute, relative, resolve } from 'node:path';
 // `.peaks/_runtime/<sessionId>/<role>/...` string is no longer
 // pre-built.
 import { getSessionDir } from '../session/getSessionDir.js';
+import { normalizePath } from '../../shared/path-utils.js';
 const MAX_RESUME_ARTIFACT_BYTES = 256_000;
 // Slice 2026-06-29-change-id-root-removal: return the bare role-relative
 // sub-paths instead of `.peaks/_runtime/change/<id>/<role>/...` strings.
@@ -65,7 +66,7 @@ function normalizeRoleRelativePath(artifact, _sessionId) {
     // the path separators and strips any leading `/`; the `sessionId`
     // argument is preserved on the signature for backward call-site
     // compatibility but is no longer embedded in the path.
-    return artifact.replace(/\\/g, '/').replace(/^\/+/, '');
+    return normalizePath(artifact).replace(/^\/+/, '');
 }
 function readResumeArtifact(artifactWorkspacePath, sessionId, artifact) {
     // Slice 2026-06-29-change-id-root-removal: on-disk home now lives under
@@ -73,7 +74,7 @@ function readResumeArtifact(artifactWorkspacePath, sessionId, artifact) {
     // sub-path (e.g. `rd/swarm/checkpoints/checkpoint-1.json`) is
     // strictly a sub-root drill, not a top-level dir derivation.
     const sessionScopeRoot = getSessionDir(artifactWorkspacePath, sessionId);
-    const normalizedArtifact = artifact.replace(/\\/g, '/').replace(/^\/+/, '');
+    const normalizedArtifact = normalizePath(artifact).replace(/^\/+/, '');
     const artifactPath = resolve(sessionScopeRoot, normalizedArtifact);
     try {
         const artifactWorkspaceRealPath = realpathSync(artifactWorkspacePath);

package/dist/services/workspace/workspace-service.js

@@ -3,6 +3,7 @@ import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from 'peaks-loop-shared/fs';
 import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Slice 2026-06-29-change-id-root-removal: list the immediate children of
  * `.peaks/` so the legacy sibling-dir guard can enumerate date-stamped
@@ -418,7 +419,7 @@ export function isWriterCreatedSiblingShape(siblingDir) {
             continue;
         }
         if (stat.isFile()) {
-            const rel = node.rel.replace(/\\/g, '/');
+            const rel = normalizePath(node.rel);
             const matches = WRITER_ALLOWED_RELATIVE_PATTERNS.some((re) => re.test(rel));
             if (!matches) {
                 return false;

package/dist/services/worktree/worktree-lease.js

@@ -26,6 +26,7 @@
  */
 import { randomBytes } from 'node:crypto';
 import { posix as path } from 'node:path';
+import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Per-role default TTL. Sub-agent dispatch duration varies by role:
  * - rd (long planning + impl) → 30 min
@@ -233,7 +234,7 @@ export function deserializeLease(raw) {
 function joinPath(...segments) {
     if (segments.length === 0)
         return '';
-    const normalized = segments.map((s) => s.replace(/\\/g, '/'));
+    const normalized = segments.map((s) => normalizePath(s));
     let acc = normalized[0];
     for (let i = 1; i < normalized.length; i++) {
         acc = path.join(acc, normalized[i]);

package/dist/shared/path-safety.js

@@ -10,11 +10,9 @@
  * check without bringing in the change-id axis.
  */
 import { posix } from 'node:path';
-function normalizeForwardSlashes(input) {
-    return input.replace(/\\/g, '/');
-}
+import { normalizePath } from './path-utils.js';
 function hasUnsafePathShape(input) {
-    const normalized = normalizeForwardSlashes(input);
+    const normalized = normalizePath(input);
     if (input.includes('\\'))
         return true;
     if (!normalized || normalized === '.' || normalized === '..')
@@ -36,7 +34,7 @@ export function isUnsafeArtifactPath(path) {
     return isUnsafePathInput(path);
 }
 function normalizeArtifactPath(input) {
-    const normalized = posix.normalize(normalizeForwardSlashes(input));
+    const normalized = posix.normalize(normalizePath(input));
     return normalized.replace(/\/$/, '');
 }
 export { normalizeArtifactPath as _normalizeArtifactPath };

package/dist/shared/path-utils.d.ts

@@ -11,3 +11,51 @@ export declare function isWindowsAbsolutePath(path: string): boolean;
 export declare function resolveInputPath(path: string): string;
 export declare function stableRealPath(path: string): string;
 export declare function stablePath(path: string): string;
+/**
+ * Build the comparison key for a `projectRoot` value. Two paths that
+ * denote the same physical directory MUST produce the same key, and two
+ * paths that denote different directories MUST NOT.
+ *
+ * Composed from the existing `path-utils.ts` primitives; no new
+ * dependency. Three normalizations, in order:
+ *
+ *   1. **Symlink resolution** via `stableRealPath` — collapses macOS
+ *      `/var/folders/...` vs `/private/var/folders/...` (`/var` is a
+ *      symlink to `/private/var`). Falls back to `resolveInputPath`
+ *      when the path does not exist, so this never throws for callers
+ *      that pass a not-yet-created root (or a stale binding whose
+ *      directory has since been deleted).
+ *   2. **Separator folding** via `normalizePath` — collapses the
+ *      Windows `C:\Users\...` (written by `peaks workspace init`) vs
+ *      `C:/Users/...` (passed by a Git Bash caller) split that was the
+ *      original `PEAKS_SESSION_NOT_BOUND` trigger.
+ *   3. **Case folding, Windows only** — NTFS is case-insensitive, so
+ *      `C:\Foo` and `c:/foo` are the same directory. This step is
+ *      guarded on `isWindows` because POSIX filesystems are
+ *      case-SENSITIVE: folding case on Linux would make the genuinely
+ *      distinct `/tmp/Foo` and `/tmp/foo` compare equal.
+ *
+ * Note on step 3: `realpathSync` alone is NOT sufficient for the
+ * Windows case split. Verified empirically on Node 22 / win32 —
+ * `realpathSync('c:\\...\\foo')` echoes the caller's casing, while only
+ * `realpathSync.native` case-folds. We do not switch to `.native`
+ * because it also rewrites 8.3 short names (`SMALLM~1` → `smallMark`),
+ * which would change the on-disk form of every existing binding.
+ * Explicit `toLowerCase()` is the narrower, more predictable fix.
+ *
+ * This is a compare key ONLY — never persist it. The value written to
+ * disk stays the real path (see `writeSessionFile`).
+ *
+ * Lifted from `src/services/session/session-manager.ts` in slice
+ * `2026-08-04-rid-002-bridge-canonicalize` so both `session-manager.ts`
+ * and `session-binding-bridge.ts` share a single canonicalization
+ * authority.
+ */
+export declare function projectRootCompareKey(p: string): string;
+/**
+ * Compare two `projectRoot` values under the canonicalization rules
+ * documented on `projectRootCompareKey`. Returns true iff both paths
+ * canonicalize to the same key — covers symlink resolution, separator
+ * folding, and (Windows only) case folding.
+ */
+export declare function projectRootsMatch(a: string, b: string): boolean;

package/dist/shared/path-utils.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { isAbsolute, parse, relative, resolve, sep } from 'node:path';
 import { tmpdir } from 'node:os';
-import { platform } from './platform.js';
+import { isWindows, platform } from './platform.js';
 export const SEP = sep;
 const localPathConverters = {
     win32: (p) => p.replace(/\//g, '\\'),
@@ -54,3 +54,67 @@ export function stablePath(path) {
     const realExistingPath = existsSync(currentPath) ? stableRealPath(currentPath) : parsedPath.root;
     return resolve(realExistingPath, ...missingSegments);
 }
+/**
+ * Build the comparison key for a `projectRoot` value. Two paths that
+ * denote the same physical directory MUST produce the same key, and two
+ * paths that denote different directories MUST NOT.
+ *
+ * Composed from the existing `path-utils.ts` primitives; no new
+ * dependency. Three normalizations, in order:
+ *
+ *   1. **Symlink resolution** via `stableRealPath` — collapses macOS
+ *      `/var/folders/...` vs `/private/var/folders/...` (`/var` is a
+ *      symlink to `/private/var`). Falls back to `resolveInputPath`
+ *      when the path does not exist, so this never throws for callers
+ *      that pass a not-yet-created root (or a stale binding whose
+ *      directory has since been deleted).
+ *   2. **Separator folding** via `normalizePath` — collapses the
+ *      Windows `C:\Users\...` (written by `peaks workspace init`) vs
+ *      `C:/Users/...` (passed by a Git Bash caller) split that was the
+ *      original `PEAKS_SESSION_NOT_BOUND` trigger.
+ *   3. **Case folding, Windows only** — NTFS is case-insensitive, so
+ *      `C:\Foo` and `c:/foo` are the same directory. This step is
+ *      guarded on `isWindows` because POSIX filesystems are
+ *      case-SENSITIVE: folding case on Linux would make the genuinely
+ *      distinct `/tmp/Foo` and `/tmp/foo` compare equal.
+ *
+ * Note on step 3: `realpathSync` alone is NOT sufficient for the
+ * Windows case split. Verified empirically on Node 22 / win32 —
+ * `realpathSync('c:\\...\\foo')` echoes the caller's casing, while only
+ * `realpathSync.native` case-folds. We do not switch to `.native`
+ * because it also rewrites 8.3 short names (`SMALLM~1` → `smallMark`),
+ * which would change the on-disk form of every existing binding.
+ * Explicit `toLowerCase()` is the narrower, more predictable fix.
+ *
+ * This is a compare key ONLY — never persist it. The value written to
+ * disk stays the real path (see `writeSessionFile`).
+ *
+ * Lifted from `src/services/session/session-manager.ts` in slice
+ * `2026-08-04-rid-002-bridge-canonicalize` so both `session-manager.ts`
+ * and `session-binding-bridge.ts` share a single canonicalization
+ * authority.
+ */
+export function projectRootCompareKey(p) {
+    let canonical;
+    try {
+        canonical = stableRealPath(p);
+    }
+    catch {
+        // Path does not exist (yet). Fall back to the resolved absolute
+        // form so a binding written before its directory exists — and a
+        // binding whose directory was later deleted — still compares by
+        // separator + case rather than throwing.
+        canonical = resolveInputPath(p);
+    }
+    const separatorFolded = normalizePath(canonical);
+    return isWindows ? separatorFolded.toLowerCase() : separatorFolded;
+}
+/**
+ * Compare two `projectRoot` values under the canonicalization rules
+ * documented on `projectRootCompareKey`. Returns true iff both paths
+ * canonicalize to the same key — covers symlink resolution, separator
+ * folding, and (Windows only) case folding.
+ */
+export function projectRootsMatch(a, b) {
+    return projectRootCompareKey(a) === projectRootCompareKey(b);
+}

package/docs/test-style-contract.md

@@ -0,0 +1,135 @@
+# Test-Style Contract for LLM-Written Unit Tests
+
+> **Effective**: rid-2026-08-05-bdd-test-style, peaks-loop v4.0.11+
+> **Audience**: LLM agents (peaks-rd / peaks-qa / downstream consumers) that
+> write new unit tests in projects adopting this contract.
+> **Status**: soft contract — enforced at peaks-qa verification time, not
+> at compile time.
+
+This document is the opt-in LLM-facing counterpart to the AAA→BDD
+rewrite that the rid-2026-08-05-bdd-test-style slices ship inside
+peaks-loop. Downstream projects can adopt the same contract by
+importing this file:
+
+```ts
+import contract from 'peaks-loop/test-style';
+```
+
+The runtime export is the markdown string below; the contract lives
+in the prose, not in code. LLM agents are expected to read this file
+on every test-writing turn.
+
+---
+
+## 1. The Contract
+
+Every new or modified `it()` / `test()` block in `tests/unit/**`
+MUST follow the given-when-then shape.
+
+### 1.1 Description (the `it()` / `test()` string-literal)
+
+- **Form**: `when X, should Y` — state the precondition in the `when`
+  clause and the observable outcome in the `should` clause.
+- **Required word**: must include at least one of `when` or `should`.
+  (`when` alone is the precondition; `should` alone is the outcome;
+  the natural-language form combines both.)
+- **Anti-pattern**: do NOT use legacy `// arrange:` / `// act:` /
+  `// assert:` markers anywhere in the test body.
+
+### 1.2 Body (the callback)
+
+The first three statements of the callback (after the opening brace,
+before any executable code) MUST be exactly three leading comments:
+
+```ts
+// given: <precondition — system / user state>
+// when: <action — what is invoked>
+// then: <expected outcome — what is asserted>
+```
+
+The `then:` line corresponds to the assertion(s) that follow.
+
+### 1.3 Behavior preservation
+
+The migration must be idempotent. A second pass over a test file
+already in BDD form must produce the same output (no duplicate
+comment blocks, no double-tagged descriptions).
+
+---
+
+## 2. 5-Item Pre-Write Checklist
+
+LLM agents writing a new test should run this checklist before
+declaring the test complete:
+
+1. **Does the description include `when` or `should`?**
+   If no, rewrite the description before writing the body.
+2. **Does the body start with the `// given:` / `// when:` / `// then:`
+   triple in that exact order?**
+   If no, prepend the missing lines.
+3. **Are there any `// arrange:` / `// act:` / `// assert:` lines?**
+   If yes, replace them with the BDD triple.
+4. **Will the test still pass with the BDD rewrite?**
+   Run the test, do not just trust the diff. Anti-fake-green rule:
+   vitest green is necessary but not sufficient.
+5. **Does the description read as business behavior, not as
+   implementation detail?**
+   If the description reads like code (e.g. "calls foo with x"),
+   rewrite it as observable behavior ("when x is passed, should
+   return y").
+
+---
+
+## 3. Opt-In Adoption (downstream projects)
+
+Downstream consumers can adopt the same contract without depending
+on peaks-loop at runtime — this file is the contract. To opt in:
+
+```jsonc
+// package.json
+{
+  "devDependencies": {
+    "peaks-loop": "^4.0.11"
+  }
+}
+```
+
+```ts
+// In a vitest setup or in a pre-commit hook:
+import contract from 'peaks-loop/test-style';
+// `contract` is the markdown string of this document; surface it to
+// your LLM agent on every test-writing turn via system prompt or
+// tool description.
+```
+
+The contract is intentionally **not** a code-level dependency — it
+is a document that LLMs read. Runtime imports are an opt-in
+ergonomic aid for surfacing the contract to a downstream prompt.
+
+---
+
+## 4. Why Not Enforce in the Test Runner?
+
+- vitest's `it()` accepts any string; enforcing description shape at
+  runtime would require a custom wrapper around every test, which
+  defeats vitest's plugin compatibility.
+- AST-based verification (the peaks-qa `bdd-test-style-verifier`) is
+  the chosen gate because it inspects what the LLM wrote, not what
+  vitest sees. False positives from string-internal `when` matches
+  are eliminated by walking only the description's `StringLiteral`
+  and the body callback's leading comments.
+- LLM-authored tests are the primary audience. Humans writing tests
+  are not blocked by this contract (peaks-qa is the gate, not vitest).
+
+---
+
+## 5. Author & Change Control
+
+- **Author**: SquabbyZ (`601709253@qq.com`) — sole-author per project
+  red rule.
+- **Change control**: any edit to this file MUST go through a
+  peaks-rd slice with peaks-qa acceptance; treat the contract text as
+  load-bearing for downstream LLM behavior.
+- **Related**: `.peaks/_runtime/2026-08-04-session-3fe1be/sc/2026-08-05-bdd-test-style-rid-design.md`
+  (the design doc), `scripts/migrate-to-bdd.mjs` (the AST migrator),
+  `src/services/qa/bdd-test-style-verifier.ts` (the verifier).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.9",
+  "version": "4.0.11",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -82,6 +82,8 @@
     "agents/**",
     "schemas/*.json",
     ".claude-plugin/**",
+    "config/eslint/.peaks-rules.cjs",
+    "docs/test-style-contract.md",
     "README.md",
     "README-en.md",
     "CHANGELOG.md",
@@ -98,9 +100,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
+    "peaks-loop-shared-channel": "0.0.19",
     "peaks-loop-mut": "0.1.15",
-    "peaks-loop-shared": "0.0.40",
-    "peaks-loop-shared-channel": "0.0.19"
+    "peaks-loop-shared": "0.0.42"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"

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.