peaks-loop 4.0.10 → 4.0.12

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

@@ -2,7 +2,15 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname, join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
-import { getSessionMeta } from '../session/session-manager.js';
+import { getSessionId, getSessionMeta } from '../session/session-manager.js';
+// Slice 4.0.8 compat shim: the canonical write path lives in
+// `presence-lease-service.ts`. The legacy shim dynamically imports
+// it inside `setSkillPresence` so the cold path of the legacy
+// `getSkillPresence` / `checkStalePresence` / `clearStalePresenceOnRotation`
+// read paths stays cheap. The static imports below are reserved for
+// the migration window and are referenced through the dynamic
+// `leaseMod.*` accessor at runtime.
+import { listPresenceLeases } from './presence-lease-service.js';
 // Re-export the 4.0.8 compat surface so legacy callers
 // (`presence-service` consumers in `code-mode-gate-commands.ts`,
 // `mode-enforcement.ts`, `code-job-shape-commands.ts`, etc.) keep
@@ -37,14 +45,13 @@ function getCurrentOuterSessionId() {
         return claude;
     return undefined;
 }
-// As of slice 2026-06-05-peaks-runtime-layer the orchestrator's
-// active-skill marker lives under `.peaks/_runtime/active-skill.json`.
-// The legacy `.peaks/.active-skill.json` path is preserved as a
-// read-only fallback for one minor release so older CLI versions (or
-// trees that have not been migrated by `peaks workspace reconcile`)
-// keep working without a forced re-init.
-const PRESENCE_FILE = join('.peaks', '_runtime', 'active-skill.json');
-const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
+// Slice 4.0.11 statusline-sid-scoped-lease C: the deprecated
+// project-level single-slot presence files
+// `.peaks/_runtime/active-skill.json` and `.peaks/.active-skill.json`
+// are REMOVED from this module. The canonical sid-scoped lease
+// projection (`.peaks/_runtime/<sid>/leases/presence-*.json`) is the
+// only source of truth. The legacy constants `PRESENCE_FILE` and
+// `PRESENCE_FILE_LEGACY` are deleted; readers use `listPresenceLeases`.
 const SESSION_FILE = join('.peaks', '_runtime', 'session.json');
 const SESSION_FILE_LEGACY = '.peaks/.session.json';
 function resolveProjectRoot(override) {
@@ -52,36 +59,6 @@ function resolveProjectRoot(override) {
         return resolve(override);
     return findProjectRoot(process.cwd()) ?? process.cwd();
 }
-function resolvePresencePath(projectRootOverride) {
-    return resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE);
-}
-/**
- * Back-compat read for the active-skill marker. Prefers the new
- * canonical `.peaks/_runtime/active-skill.json`; falls back to the
- * legacy `.peaks/.active-skill.json` for one minor release.
- *
- * Returns the parsed SkillPresence object, or null when neither
- * file is present / valid. The legacy file is never written by
- * current code — only the new path receives writes.
- */
-function readSkillPresenceBackCompat(projectRootOverride) {
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
-    const pathToRead = existsSync(presencePath) ? presencePath : legacyPath;
-    if (!existsSync(pathToRead))
-        return null;
-    try {
-        const raw = readFileSync(pathToRead, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
-            return null;
-        }
-        return { presence: parsed, path: pathToRead };
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-}
 /**
  * Resolve the active peaks session id from
  * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
@@ -112,6 +89,43 @@ export function getCurrentSessionId(projectRootOverride) {
         return null;
     }
 }
+/**
+ * Slice 4.0.11 statusline-sid-scoped-lease C: read the canonical
+ * sid-scoped lease projection and project the freshest in-flight
+ * lease into the legacy `SkillPresence` shape that the public
+ * `getSkillPresence` / `checkStalePresence` /
+ * `clearStalePresenceOnRotation` consumers expect. The projection
+ * is lossy (the lease does not carry `outerSessionId`; `setAt`
+ * maps to `startedAt`; `lastHeartbeat` is reused as `lastHeartbeat`).
+ *
+ * Returns `null` when the bound session has no in-flight leases
+ * (`running` or `preparing`); terminalized leases are ignored so
+ * the read does not resurrect a stale skill on a fresh session.
+ */
+function readSkillPresenceFromLease(projectRootOverride) {
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const sessionId = getSessionId(projectRoot);
+    if (sessionId === null)
+        return null;
+    const leases = listPresenceLeases(projectRoot, sessionId);
+    const inFlight = leases.filter((l) => l.status === 'running' || l.status === 'preparing');
+    if (inFlight.length === 0)
+        return null;
+    inFlight.sort((a, b) => b.lastHeartbeat.localeCompare(a.lastHeartbeat));
+    const lease = inFlight[0];
+    if (lease === undefined)
+        return null;
+    // The lease carries `callerId` (the adapter / harness session id),
+    // not the legacy `outerSessionId` field. Project it for back-compat
+    // with `clearStalePresenceOnRotation`'s outer-mismatch check.
+    return {
+        skill: lease.skill,
+        sessionId,
+        outerSessionId: lease.callerId,
+        setAt: lease.startedAt,
+        lastHeartbeat: lease.lastHeartbeat
+    };
+}
 /**
  * Look up the outer-session-id that was bound to the *current* peaks
  * session, i.e. the one written to the per-session
@@ -160,23 +174,14 @@ function getBoundOuterSessionId(projectRootOverride) {
  * legacy `.peaks/.active-skill.json` for one minor release.
  */
 function getPreviousOuterSessionId(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
+    const result = readSkillPresenceFromLease(projectRootOverride);
     if (result === null)
         return undefined;
-    const parsed = result.presence;
-    if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
-        return parsed.outerSessionId;
-    }
-    // Legacy field name. Honour it on the read side so v1.2.x
-    // presence files do not show as a false mismatch.
-    if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
-        return parsed.claudeSessionId;
+    if (typeof result.outerSessionId === 'string' && result.outerSessionId.length > 0) {
+        return result.outerSessionId;
     }
     return undefined;
 }
-export function exportSkillPresence(projectRootOverride) {
-    return resolvePresencePath(projectRootOverride);
-}
 // ============================================================================
 // Slice 020 — caller-keyed active-skill marker (D6).
 // ============================================================================
@@ -336,12 +341,12 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
             catch { /* fall through to legacy write */ }
         })();
     }
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const presenceDir = dirname(presencePath);
-    if (!existsSync(presenceDir)) {
-        mkdirSync(presenceDir, { recursive: true });
-    }
-    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Slice 4.0.11 statusline-sid-scoped-lease A: the canonical write
+    // path is now exclusively `presence-lease-service.setPresenceLease`.
+    // The legacy single-slot marker file write was removed in this
+    // slice: every `setSkillPresence` call flows through the sid-scoped
+    // lease + presence-index machinery above. The legacy
+    // `active-skill.json` file is NOT recreated here.
     // Skill-activation side effect: ensure `.peaks/memory/` and a full-shape
     // empty `index.json` exist for the project. This is the user-facing fix
     // for "stock projects never get a memory directory or index". Every peaks
@@ -354,26 +359,17 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     return presence;
 }
 export function getSkillPresence(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
-    if (result === null)
-        return null;
-    const { presence, path: presencePath } = result;
-    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
-        const currentSessionId = getCurrentSessionId(projectRootOverride);
-        if (currentSessionId && presence.sessionId !== currentSessionId) {
-            try {
-                unlinkSync(presencePath);
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // best effort
-            }
-            return null;
-        }
-    }
-    return presence;
+    // Slice 4.0.11 statusline-sid-scoped-lease C: read from the
+    // canonical sid-scoped lease projection. The legacy
+    // `unlinkSync(presencePath)` purge on session-mismatch is
+    // removed: the lease projection is keyed off the bound session
+    // id, so a mismatch cannot happen — `listPresenceLeases`
+    // already filters by the session-id resolved from the workspace
+    // binding.
+    return readSkillPresenceFromLease(projectRootOverride);
 }
 export function checkStalePresence(opts) {
-    const result = readSkillPresenceBackCompat(opts?.projectRootOverride);
+    const result = readSkillPresenceFromLease(opts?.projectRootOverride);
     // `opts?.currentOuter === undefined` is the omitted-key case. A
     // falsy string `''` is an explicit "no signal" (used by tests to
     // simulate a CLI run with no harness env vars).
@@ -389,7 +385,7 @@ export function checkStalePresence(opts) {
             recordedOuterSessionId: undefined
         };
     }
-    const recorded = result.presence.outerSessionId;
+    const recorded = result.outerSessionId;
     // Suppress false-positives when NEITHER side recorded an outer
     // session id (legacy project, no harness signal). Two unknowns
     // are not a swap — they are "no signal available yet".
@@ -399,7 +395,7 @@ export function checkStalePresence(opts) {
         return {
             stale: false,
             reason: null,
-            presence: result.presence,
+            presence: result,
             currentOuterSessionId: current,
             recordedOuterSessionId: recorded
         };
@@ -408,7 +404,7 @@ export function checkStalePresence(opts) {
         return {
             stale: false,
             reason: null,
-            presence: result.presence,
+            presence: result,
             currentOuterSessionId: current,
             recordedOuterSessionId: recorded
         };
@@ -416,7 +412,7 @@ export function checkStalePresence(opts) {
     return {
         stale: true,
         reason: 'outer-session-mismatch',
-        presence: result.presence,
+        presence: result,
         currentOuterSessionId: current,
         recordedOuterSessionId: recorded
     };
@@ -444,11 +440,11 @@ export function checkStalePresence(opts) {
  * decide what the "rotated-out" id was.
  */
 export function clearStalePresenceOnRotation(opts) {
-    const result = readSkillPresenceBackCompat(opts.projectRootOverride);
+    const result = readSkillPresenceFromLease(opts.projectRootOverride);
     if (result === null) {
         return { cleared: false, reason: 'no-presence' };
     }
-    const recorded = result.presence.outerSessionId;
+    const recorded = result.outerSessionId;
     const current = opts.currentOuterSessionId;
     // If the recorded outer id matches the new (current) outer id,
     // this presence is NOT stale — the user just reconnected from
@@ -483,24 +479,25 @@ export function clearStalePresenceOnRotation(opts) {
     };
 }
 export function touchSkillHeartbeat(projectRootOverride) {
-    const result = readSkillPresenceBackCompat(projectRootOverride);
-    if (result === null)
+    // Slice 4.0.11 statusline-sid-scoped-lease C: read from the
+    // canonical sid-scoped lease projection. The legacy
+    // unlink-on-session-mismatch purge is removed: the lease is
+    // keyed off the bound session id, so the mismatch path cannot
+    // fire (a lease under session A is never returned when the bound
+    // session is B).
+    const presence = readSkillPresenceFromLease(projectRootOverride);
+    if (presence === null)
         return null;
-    const { presence, path: presencePath } = result;
-    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
-        const currentSessionId = getCurrentSessionId(projectRootOverride);
-        if (currentSessionId && presence.sessionId !== currentSessionId) {
-            try {
-                unlinkSync(presencePath);
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // best effort
-            }
-            return null;
-        }
-    }
+    // Slice 4.0.11 statusline-sid-scoped-lease A: the legacy write to
+    // the single-slot marker file was removed. Heartbeat refresh now
+    // lives exclusively in `presence-lease-service.setPresenceLease`
+    // (the canonical sid-scoped lease). This function remains as a
+    // read-only back-compat shim for the 4-B / 4-C sub-slices; callers
+    // still receive the in-memory `presence` (with the new
+    // `lastHeartbeat` stamped) but the legacy `active-skill.json` file
+    // is no longer touched. The canonical lease / presence-index
+    // entries are the source of truth for heartbeat freshness.
     presence.lastHeartbeat = new Date().toISOString();
-    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
     return presence;
 }
 export function clearSkillPresence(projectRootOverride) {
@@ -518,12 +515,25 @@ export function clearSkillPresence(projectRootOverride) {
     // `.peaks/.active-skill.json` so a stale marker from a prior CLI
     // version cannot resurrect after a fresh `clear`. The canonical
     // lease + index entries are NOT touched by this shim — they
-    // remain under the workflow's terminalize lock until
-    // `terminalizeWorkflow` or the next workflow init reclaims them.
-    const presencePath = resolvePresencePath(projectRootOverride);
-    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    // Slice 4.0.11 statusline-sid-scoped-lease C: the deprecated
+    // single-slot presence files (`.peaks/_runtime/active-skill.json`
+    // and `.peaks/.active-skill.json`) are removed. The canonical
+    // sid-scoped lease projection (under
+    // `.peaks/_runtime/<sid>/leases/`) is untouched here — workflow
+    // leases route through `terminalizeWorkflow`, NOT this shim.
+    //
+    // This shim remains as a best-effort stale-file cleanup for
+    // projects that still carry the deprecated single-slot file from
+    // a pre-4.0.11 CLI version. After one minor release the legacy
+    // paths are gone and the loop is a no-op. Returns true when a
+    // stale file was actually removed.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const candidates = [
+        resolve(projectRoot, '.peaks', '_runtime', 'active-skill.json'),
+        resolve(projectRoot, '.peaks', '.active-skill.json')
+    ];
     let cleared = false;
-    for (const p of [presencePath, legacyPath]) {
+    for (const p of candidates) {
         if (!existsSync(p))
             continue;
         try {

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

@@ -1,28 +1,34 @@
-import { existsSync, readFileSync } from 'node:fs';
 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 { listPresenceLeases } from './presence-lease-service.js';
 import { readActiveDispatchIndex } from '../dispatch/dispatch-record-writer.js';
 /**
  * Out-of-band Peaks skill status renderer for the Claude Code statusLine.
  *
  * Claude Code invokes the configured statusLine command on every turn and pipes
- * a JSON session payload on stdin. This renderer reads the durable presence file
- * (`.peaks/_runtime/active-skill.json`, with a one-minor-release back-compat
- * fallback to `.peaks/.active-skill.json`) and prints a single line that
- * Claude Code paints at the bottom of the terminal. Because it is rendered
- * by the harness — not emitted as LLM tokens — the signal cannot be forgotten
- * by the model, cannot be confused with normal output, and survives context
- * compaction.
+ * a JSON session payload on stdin. This renderer reads the canonical
+ * sid-scoped lease projection
+ * (`.peaks/_runtime/<sid>/leases/presence-<caller>-<workflow>.json` +
+ * the per-caller index under `presence-index/<caller>.json`) and prints a
+ * single line that Claude Code paints at the bottom of the terminal. Because
+ * it is rendered by the harness — not emitted as LLM tokens — the signal
+ * cannot be forgotten by the model, cannot be confused with normal output,
+ * and survives context compaction.
  *
  * This module is intentionally READ-ONLY. Unlike getSkillPresence in
  * skill-presence-service.ts, it never deletes or rewrites the presence file:
  * the statusLine runs on every turn and must have zero side effects.
+ *
+ * Slice 2026-08-05-statusline-sid-scoped-lease-B: the read no longer falls
+ * back to the project-level `.peaks/_runtime/active-skill.json` (or its
+ * legacy `.peaks/.active-skill.json`). The canonical lease projection is
+ * the only source. When `callerId === null` (non-IDE caller), the read
+ * picks the most recent in-flight lease across all callers; this is the
+ * documented back-compat path.
  */
-const PRESENCE_FILE = '.peaks/_runtime/active-skill.json';
-const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
 const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function resolveCwdFromStdin(stdin) {
     const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
@@ -96,6 +102,8 @@ function readActiveLeaf(projectRoot, sessionId) {
         '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)
@@ -111,16 +119,23 @@ function readActiveLeaf(projectRoot, sessionId) {
  * 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).
+ * Both branches now route through the canonical sid-scoped lease projection
+ * (slice 2026-08-05-statusline-sid-scoped-lease-B):
+ *   - `callerId !== null` → `resolveActiveSkillForCaller` with the canonical
+ *     (non-legacy) lease projection, filtered to this callerId.
+ *   - `callerId === null` → enumerate `listPresenceLeases` for the
+ *     canonical session and pick the most recent in-flight lease. Back-compat
+ *     for non-IDE callers (e.g. legacy CLI invocations) that have no callerId.
+ *
+ * No fallback to `.peaks/_runtime/active-skill.json` (or its legacy path):
+ * the canonical lease projection is the single source of truth. When no
+ * in-flight leases exist, the read returns `{ presence: null, invalid: false }`
+ * and the renderer falls back to the idle state.
  */
 function readPresenceReadOnly(projectRoot, callerId) {
     if (callerId !== null) {
         try {
-            const resolution = resolveActiveSkillForCaller(projectRoot, { legacyPresence: true, callerId });
+            const resolution = resolveActiveSkillForCaller(projectRoot, { callerId });
             if (resolution.source === 'none' || resolution.skill === null) {
                 return { presence: null, invalid: false };
             }
@@ -136,36 +151,55 @@ function readPresenceReadOnly(projectRoot, callerId) {
             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.
-    const pathToRead = existsSync(presencePath) ? presencePath : resolve(projectRoot, PRESENCE_FILE_LEGACY);
-    if (!existsSync(pathToRead)) {
+    // callerId === null branch: enumerate the canonical session dir's leases
+    // and pick the most recent in-flight lease. This is the back-compat path
+    // for non-IDE callers that don't supply a callerId.
+    let sessionId = null;
+    try {
+        sessionId = getSessionIdCanonical(projectRoot);
+    }
+    catch {
+        return { presence: null, invalid: false };
+    }
+    if (sessionId === null) {
         return { presence: null, invalid: false };
     }
+    let leases = [];
     try {
-        const parsed = JSON.parse(readFileSync(pathToRead, 'utf8'));
-        if (!parsed || typeof parsed !== 'object') {
-            return { presence: null, invalid: true };
-        }
-        const candidate = parsed;
-        if (typeof candidate.skill !== 'string' || candidate.skill.length === 0) {
-            return { presence: null, invalid: true };
-        }
-        return {
-            presence: {
-                skill: candidate.skill,
-                ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
-                ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
-                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {}),
-                ...(typeof candidate.claudeSessionId === 'string' ? { claudeSessionId: candidate.claudeSessionId } : {})
-            },
-            invalid: false
-        };
+        leases = listPresenceLeases(projectRoot, sessionId);
     }
     catch {
         return { presence: null, invalid: true };
     }
+    const inFlight = leases
+        .filter((l) => l.status === 'preparing' || l.status === 'running')
+        .filter((l) => typeof l.skill === 'string' && l.skill.length > 0);
+    if (inFlight.length === 0) {
+        return { presence: null, invalid: false };
+    }
+    // Most recent wins — sort by `lastHeartbeat` desc, fall back to `startedAt`.
+    const sorted = inFlight.slice().sort((a, b) => {
+        const hb = b.lastHeartbeat.localeCompare(a.lastHeartbeat);
+        if (hb !== 0)
+            return hb;
+        return b.startedAt.localeCompare(a.startedAt);
+    });
+    const latest = sorted[0];
+    if (latest === undefined || typeof latest.skill !== 'string' || latest.skill.length === 0) {
+        return { presence: null, invalid: false };
+    }
+    // Leases on disk may carry an optional `mode` field (the lease constructor
+    // spreads `input.mode` when present); the typed `SkillPresenceLease` does
+    // not declare it, so widen the read shape here.
+    const latestMode = latest.mode;
+    return {
+        presence: {
+            skill: latest.skill,
+            ...(typeof latestMode === 'string' && latestMode.length > 0 ? { mode: latestMode } : {}),
+            setAt: latest.startedAt,
+        },
+        invalid: false,
+    };
 }
 export function buildStatusLineModel(stdin, nowMs) {
     const cwd = resolveCwdFromStdin(stdin);

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.10",
+  "version": "4.0.12",
   "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": "0.0.41",
-    "peaks-loop-shared-channel": "0.0.19",
-    "peaks-loop-mut": "0.1.15"
+    "peaks-loop-mut": "0.1.16",
+    "peaks-loop-shared-channel": "0.0.20",
+    "peaks-loop-shared": "0.0.43"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"