peaks-loop 4.0.10 → 4.0.11

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.0.11 — 2026-08-05 (BDD test-style + statusline bugs)
+
+**BDD given-when-then test style** (rid-2026-08-05-bdd-test-style, 5 slice / 19 commit):
+- `scripts/migrate-to-bdd.mjs` — TS Compiler API-based AST migrator that rewrites every `it()` / `test()` / `describe()` to the given-when-then contract (it description with `when X` or `should Y` + 3-line `// given:` / `// when:` / `// then:` body comment). Idempotent.
+- `src/services/qa/bdd-test-style-verifier.ts` — peaks-qa verification-time verifier that scans `git diff HEAD~1 -- '*.test.ts'` and rejects non-BDD slices (LLM-only enforcement, since callerId from `process.env.CLAUDE_CODE_SESSION_ID` cannot distinguish LLM vs human in Claude Code).
+- `src/reporters/bdd-reporter.ts` — vitest custom reporter (flag-enabled via `--reporter ./src/reporters/bdd-reporter.ts`) emitting `Feature: <file>` / `Scenario: <describe>` / `Given|When|Then` document view.
+- `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md` + `peaks-qa/references/qa-sub-agent-dispatch.md` — `## BDD Test Style Contract` / `## BDD Test Style Verification` soft-constraint sections added.
+- `docs/test-style-contract.md` — LLM test-style guide included in npm `files` array (downstream opt-in).
+- 26 test files migrated across 11 commits (one per top-level directory); 12 files already BDD-form (idempotent migrator skipped silently); 49 unit-test files total now in BDD shape.
+- 49/49 unit tests behaviour-preserved (488 passed / 25 skipped / 0 introduced failures).
+
+**Statusline bug fixes** (3 rid this release):
+- `skill-statusline-service.ts` `readActiveLeaf`: stale `queued` dispatch entries no longer pollute statusline as in-flight leaves. `terminalStatuses` set extended.
+- `presence-lease-service.ts` `setPresenceLease`: lease object now persists `mode` (was being silently dropped — regression from 4.0.8 Presence Lease Graph introduction). `[full-auto]` / `[assisted]` / `[swarm]` / `[strict]` tags now render.
+- `audit/enforcers/active-skill-resolver.ts` legacy fall-back: per-caller `active-skill-*.json` legacy walk now reads and propagates `mode` (was hard-coded `mode: null`).
+
+**Build-chain repair** (silences `npx tsc -p tsconfig.build.json` regression):
+- `src/reporters/bdd-reporter.ts` no longer imports the un-exported `TestModule` / `TestCase` from `vitest/reporters`. Local minimal interfaces (`BddTestModuleLike` / `BddTestCaseLike`) match the runtime shape vitest passes to reporter hooks.
+- Build now succeeds end-to-end; the `dist/` artifacts (which `bin/peaks.js` actually loads) reflect the source-level fixes.
+
+**Cleanup tail** (5 rid carried over from b1 sweep):
+- 63 request artifacts re-staged to terminal state (handed-off / verdict-issued / complete / sc-handoff → done).
+- 8 OpenSpec proposal drift detected and routed through `peaks request transition`.
+- One envelope-test-output log dropped from project root (was orphan inside `.gitignore:5 *.log` but never deleted).
+
+**Lockstep bump.** peaks-loop-shared `0.0.40 → 0.0.41` (CLI_VERSION re-stamped to 4.0.11).
+
 ## 4.0.10 — 2026-08-04 (path-canonicalize + statusline-read-isolation)
 
 **Windows statusline fixed.** `peaks-loop@4.0.9` always rendered `peaks empty` on Windows Git Bash. Root cause: the session-binding reader used strict `===` to compare `projectRoot`; the binding had been written with backslashes (`C:\Users\...`) but `peaks skill presence:set --project C:/Users/...` arrived with forward slashes, and Node treats them as distinct strings. The 4.0.8 fail-closed `PEAKS_SESSION_NOT_BOUND` gate then blocked the presence marker write, and the statusline never had a real skill to display.

package/config/eslint/.peaks-rules.cjs

@@ -0,0 +1,123 @@
+/**
+ * peaks-loop ESLint rules bundle (npm-package exports)
+ *
+ * rid-2026-08-05-jsts-lint-bundle — LLM auto-fix loop trigger.
+ *
+ * This file is a JSON-shape glue config. It does NOT define custom
+ * rules. It composes upstream packages only:
+ *
+ *   - eslint:recommended
+ *   - plugin:@typescript-eslint/recommended-type-checked
+ *   - plugin:import/recommended
+ *   - plugin:import/typescript
+ *
+ * Framework-specific rules (eslint-plugin-react, eslint-plugin-vue,
+ * eslint-plugin-svelte, eslint-plugin-nestjs, etc.) are LAYER 3 and
+ * loaded dynamically by `peaks code lint` via `npx --package <pkg>
+ * -- eslint`. They are NOT installed in this package's devDependencies
+ * (sediment §二 G-lint-1 turn-5 red line).
+ *
+ * --fix / --write / prettier are FORBIDDEN at the peaks code lint
+ * wrapper entry; the wrapper is a read-only verifier, not a formatter
+ * (sediment §二 G-lint-2). The thresholds below are intentionally
+ * permissive (warn, not error) so peaks-loop 4.0.10 baseline can adopt
+ * the bundle without auto-failing.
+ */
+'use strict';
+
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+  root: false,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    project: ['./tsconfig.json', './tsconfig.build.json'],
+    tsconfigRootDir: __dirname + '/..'
+  },
+  env: {
+    node: true,
+    es2022: true
+  },
+  plugins: ['@typescript-eslint', 'import'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended-type-checked',
+    'plugin:import/recommended',
+    'plugin:import/typescript'
+  ],
+  settings: {
+    'import/resolver': {
+      typescript: {
+        alwaysTryTypes: true,
+        project: ['./tsconfig.json', './tsconfig.build.json']
+      },
+      node: {
+        extensions: ['.js', '.ts', '.tsx', '.jsx']
+      }
+    }
+  },
+  ignorePatterns: [
+    'node_modules/',
+    'dist/',
+    'coverage/',
+    'output-styles/',
+    'skills/',
+    'agents/',
+    'bin/',
+    'scratch/',
+    'examples/'
+  ],
+  rules: {
+    // L1 (eslint built-in) — always on, no plugin package required.
+    complexity: ['warn', { max: 10 }],
+    'max-lines-per-function': [
+      'warn',
+      { max: 50, skipComments: true, skipBlankLines: true }
+    ],
+    'max-params': ['warn', { max: 4 }],
+    'no-magic-numbers': [
+      'warn',
+      { ignore: [0, 1, -1, 100, 1000] }
+    ],
+    'no-explicit-any': 'warn',
+    'prefer-const': 'warn',
+    'no-var': 'error',
+    eqeqeq: ['warn', 'always', { null: 'ignore' }],
+
+    // L2 (@typescript-eslint) — type-aware; requires the
+    // recommended-type-checked base. configured via the extends above.
+    '@typescript-eslint/consistent-type-imports': [
+      'warn',
+      { prefer: 'type-imports' }
+    ],
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    '@typescript-eslint/no-implicit-any': 'warn',
+    // G-lint-1 §二 enum → as const: warn-only (escape hatch preserved).
+    '@typescript-eslint/no-restricted-syntax': [
+      'warn',
+      {
+        selector: 'TSEnumDeclaration',
+        message: 'Use "as const" union instead of TS enum.'
+      }
+    ],
+
+    // L2 (eslint-plugin-import) — boundary hygiene.
+    'import/no-duplicates': 'warn',
+    'import/no-unresolved': 'off',
+    'import/named': 'off',
+    'import/default': 'off',
+    'import/namespace': 'off'
+  },
+  overrides: [
+    {
+      files: ['*.test.ts', '*.test.tsx', 'tests/**/*.ts', 'tests/**/*.tsx'],
+      rules: {
+        'no-magic-numbers': 'off',
+        complexity: 'off',
+        'max-lines-per-function': 'off',
+        '@typescript-eslint/no-explicit-any': 'off'
+      }
+    }
+  ]
+};

package/dist/reporters/bdd-reporter.d.ts

@@ -0,0 +1,36 @@
+import type { Reporter } from 'vitest/reporters';
+/** Minimal shape of vitest's TestModule tree node. Vitest 4.1.10 does
+ * not export these types publicly; this mirrors the runtime shape
+ * the reporter hooks actually receive. */
+interface BddTestModuleLike {
+    moduleId?: string;
+    relativeModuleId?: string;
+    children: {
+        tests(): Iterable<BddTestCaseLike>;
+        suites(): Iterable<BddTestModuleLike>;
+    };
+}
+interface BddTestCaseLike {
+    name: string;
+    fullName?: string;
+    state?: 'passed' | 'failed' | 'skipped';
+    result?: () => unknown;
+}
+declare class BddReporter implements Reporter {
+    /** Key: relative module id; Value: per-feature rendered scenarios. */
+    private readonly features;
+    /**
+     * Vitest calls `onTestModuleEnd` after a module finishes. We use it
+     * to drain the per-module scenarios into the document map and
+     * mark the file's pass/fail status.
+     */
+    onTestModuleEnd(testModule: BddTestModuleLike): void;
+    /**
+     * Final emit. We deliberately print to stdout with `console.log`
+     * (vitest captures stdout when needed) and never call `process.exit`
+     * — that is the orchestrator's job. Failure reasons surface as plain
+     * text so a downstream LLM prompt can grep for `FAILED:`.
+     */
+    onTestRunEnd(): void;
+}
+export default BddReporter;

package/dist/reporters/bdd-reporter.js

@@ -0,0 +1,159 @@
+// src/reporters/bdd-reporter.ts
+//
+// rid-2026-08-05-bdd-test-style Slice C — vitest custom reporter that
+// emits a pure BDD document view of the run. Designed for business
+// reviewers and downstream LLM prompts; it is NOT a replacement for
+// the default reporter.
+//
+// Why a custom reporter:
+//   The default reporter focuses on pass/fail and timing. The BDD
+//   reporter transcribes `Feature: <file>` / `Scenario: <describe> ->
+//   it` into a single human-readable document so a non-engineer can
+//   scan what the suite actually exercises.
+//
+// Why no new dep:
+//   vitest 4.1.10 (frozen 2026-07-25) ships the `Reporter` interface
+//   in `vitest/reporters`. The custom reporter must have a `default`
+//   export — the CLI loads it via `runner.import(path)` and validates
+//   `customReporterModule.default` is defined (see vitest cli-api chunks
+//   line 11371). Importing the `Reporter` type from vitest does not add
+//   a runtime dep; tsc resolves it through vitest's dts shim.
+//
+// Why a flag-only reporter:
+//   Per rid design section 4 Slice C, the default vitest run is
+//   unchanged. This file is opt-in via:
+//
+//     pnpm vitest run --reporter ./src/reporters/bdd-reporter.ts <file>
+//
+// Anti-fake-green rule (CLI silent-catch):
+//   The reporter does not swallow vitest result shapes. Every state
+//   branch (`passed` / `failed` / `skipped`) is rendered explicitly so
+//   downstream reviewers cannot misread a hidden failure.
+//
+// Karpathy note:
+//   The reporter deliberately emits ONE document per file with the
+//   4-line Feature/Scenario/Given/When/Then shape — no extra layout
+//   metadata, no JSON sidecar. Anything beyond what the spec asked
+//   for is excluded by Simplicity First.
+class BddReporter {
+    /** Key: relative module id; Value: per-feature rendered scenarios. */
+    features = new Map();
+    /**
+     * Vitest calls `onTestModuleEnd` after a module finishes. We use it
+     * to drain the per-module scenarios into the document map and
+     * mark the file's pass/fail status.
+     */
+    onTestModuleEnd(testModule) {
+        const moduleId = testModule.relativeModuleId ?? testModule.moduleId ?? '';
+        const file = basename(moduleId);
+        const scenarios = [];
+        collectScenarios(testModule, file, scenarios);
+        this.features.set(file, scenarios);
+    }
+    /**
+     * Final emit. We deliberately print to stdout with `console.log`
+     * (vitest captures stdout when needed) and never call `process.exit`
+     * — that is the orchestrator's job. Failure reasons surface as plain
+     * text so a downstream LLM prompt can grep for `FAILED:`.
+     */
+    onTestRunEnd() {
+        const lines = [];
+        const features = [];
+        for (const [feature, scenarios] of this.features) {
+            const ok = scenarios.every((s) => s.state === 'passed' || s.state === 'skipped');
+            features.push({ feature, scenarios, ok });
+        }
+        // Deterministic order: alphabetical by file basename so two runs on
+        // the same diff produce byte-identical docs (avoids noisy diffs).
+        features.sort((a, b) => a.feature.localeCompare(b.feature));
+        for (const f of features) {
+            lines.push(`Feature: ${f.feature}`);
+            if (f.scenarios.length === 0) {
+                // Empty file still surfaces the Feature line so the document
+                // is a faithful list of files the runner touched.
+                lines.push('');
+                continue;
+            }
+            for (const s of f.scenarios) {
+                lines.push(`  Scenario: ${s.scenario || '<root>'}`);
+                lines.push(`    Given ${s.title}`);
+                lines.push(`    When  vitest runs this test`);
+                if (s.state === 'passed') {
+                    lines.push(`    Then  should pass`);
+                }
+                else if (s.state === 'skipped') {
+                    lines.push(`    Then  should skip`);
+                }
+                else {
+                    const reason = s.error ? ` (${truncate(s.error, 200)})` : '';
+                    lines.push(`    Then  FAILED: ${s.title}${reason}`);
+                }
+            }
+            lines.push('');
+        }
+        console.log(lines.join('\n'));
+    }
+}
+function basename(path) {
+    // vitest module ids are POSIX-style even on Windows; split on '/'
+    // then on '\\' as a defensive fallback.
+    const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return idx === -1 ? path : path.slice(idx + 1);
+}
+/**
+ * Walk a `TestModule` recursively and collect rendered scenarios.
+ * `describe` blocks contribute their name to the Scenario label;
+ * tests declared at module root produce a `<root>` Scenario so the
+ * structure is uniform.
+ */
+function collectScenarios(entity, file, out) {
+    const visited = new WeakSet();
+    const walk = (node, scenarioLabel) => {
+        if (node === null || typeof node !== 'object')
+            return;
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        const obj = node;
+        if (obj.type === 'test') {
+            const tc = node;
+            const result = tc.result ? tc.result() : undefined;
+            const resultObj = (result ?? {});
+            const state = (resultObj.state === 'passed' || resultObj.state === 'failed' || resultObj.state === 'skipped')
+                ? resultObj.state
+                : 'skipped';
+            const err = resultObj.state === 'failed' && resultObj.errors && resultObj.errors[0]
+                ? (resultObj.errors[0].message ?? 'unknown failure')
+                : undefined;
+            out.push({
+                scenario: scenarioLabel,
+                title: tc.name,
+                state,
+                error: err,
+            });
+            return;
+        }
+        // For a suite/module, descend with the suite's name pushed.
+        const suiteName = obj.name ?? '';
+        const childSuiteLabel = suiteName || scenarioLabel;
+        if (obj.children) {
+            try {
+                for (const t of obj.children.tests()) {
+                    walk(t, childSuiteLabel);
+                }
+                for (const s of obj.children.suites()) {
+                    walk(s, childSuiteLabel);
+                }
+            }
+            catch {
+                // Defensive: vitest internals may throw on teardown. We do not
+                // mask the document — we just stop collecting from this node.
+            }
+        }
+    };
+    walk(entity, '');
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 3)}...`;
+}
+export default BddReporter;

package/dist/services/audit/enforcers/active-skill-resolver.js

@@ -127,7 +127,10 @@ export function resolveActiveSkillForCaller(projectRoot, opts) {
                 const raw = readFileSync(filePath, 'utf8');
                 const parsed = JSON.parse(raw);
                 if (typeof parsed.skill === 'string' && parsed.skill.length > 0) {
-                    return { skill: parsed.skill, callerId, sessionId, mode: null, source: 'file' };
+                    const legacyMode = typeof parsed.mode === 'string' && parsed.mode.length > 0
+                        ? parsed.mode
+                        : null;
+                    return { skill: parsed.skill, callerId, sessionId, mode: legacyMode, source: 'file' };
                 }
             }
             catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)

package/dist/services/qa/bdd-test-style-verifier.d.ts

@@ -0,0 +1,88 @@
+/**
+ * src/services/qa/bdd-test-style-verifier.ts
+ *
+ * rid-2026-08-05-bdd-test-style Slice B — peaks-qa verification-time
+ * BDD test-style verifier. This is the read-only, post-edit companion
+ * to the `scripts/migrate-to-bdd.mjs` AST migrator shipped in Slice A.
+ *
+ * Purpose:
+ *   When peaks-qa runs its verification gate, it picks up the git diff
+ *   for the slice and asks this module whether the new / modified test
+ *   files comply with the BDD given-when-then style. The verdict is
+ *   surfaced as either `ok` (and the slice can advance) or one of two
+ *   structured failure reasons (`missing-given-when-then` or
+ *   `description-no-should-when`) that the caller turns into a
+ *   `qa-handoff` rejection back to peaks-rd.
+ *
+ * Why a real AST and not a regex:
+ *   The Slice A migrator established the convention: test files have
+ *   multi-line `it(...)` calls, nested arrow bodies, and string
+ *   literals that often contain words like "when" inside the assertion
+ *   message (not in the description). A regex pass on the raw source
+ *   would false-positive on string internals. The TypeScript Compiler
+ *   API (already a dev dep via vitest) lets us:
+ *     1. Inspect the first `StringLiteral` argument of an `it` /
+ *        `test` / `describe` call without scanning comments or
+ *        string content inside the body.
+ *     2. Walk only the leading-comment ranges that sit before the
+ *        first statement of the callback block, so a `// when:`
+ *        inside an `expect(actual).toEqual('when X happens')` is
+ *        correctly ignored.
+ *
+ * No new dependencies. The verifier is intentionally synchronous and
+ * pure (input source + path list -> verdict) so peaks-qa can call it
+ * from a deterministic verification step without subprocess overhead.
+ *
+ * Anti-fake-green (CLI silent-catch rule):
+ *   This module throws on parse failure. It does NOT swallow parse
+ *   errors and return `{ ok: true }` — that would silently green-light
+ *   malformed test files. A parse error is a structural problem; the
+ *   caller must surface it.
+ */
+/** Structured failure reasons the verifier can return. */
+export type BddStyleFailureReason = 'missing-given-when-then' | 'description-no-should-when';
+/** Successful verdict — includes the count of inspected `it`/`test` calls. */
+export interface BddStyleOk {
+    readonly ok: true;
+    readonly scanned: number;
+}
+/** Structured failure verdict — the file/line makes the rejection actionable. */
+export interface BddStyleFail {
+    readonly ok: false;
+    readonly reason: BddStyleFailureReason;
+    readonly file: string;
+    readonly line: number;
+    /** For `description-no-should-when`: the original description. */
+    readonly description?: string;
+    /** For `missing-given-when-then`: a stable string the caller can compare. */
+    readonly expected?: string;
+}
+export type BddStyleVerdict = BddStyleOk | BddStyleFail;
+/** Public input surface — keep small so the contract is hard to misuse. */
+export interface VerifyBddStyleInput {
+    readonly projectRoot: string;
+    readonly testFiles: readonly string[];
+}
+/**
+ * Verify that every `it(...)` / `test(...)` call in the given test
+ * files follows the BDD given-when-then contract.
+ *
+ * Contract:
+ *   1. The first `StringLiteral` argument of every `it` / `test` call
+ *      MUST match `/(\bwhen\b|\bshould\b)/` (word-boundary anchored,
+ *      case-insensitive). A regex on the raw description is correct
+ *      here because the description itself is a literal — there is
+ *      no nested template literal to misread.
+ *   2. The callback body (the second argument when it is an arrow /
+ *      function expression with a block) MUST have a `// given:`,
+ *      `// when:`, `// then:` triple at the top, in that order,
+ *      within the first 3 leading-comment ranges before the first
+ *      statement. The `// arrange:` / `// act:` / `// assert:` AAA
+ *      legacy is NOT accepted — the contract is given-when-then
+ *      only.
+ *
+ * Returns the FIRST failure encountered (file order, then
+ * top-to-bottom line order). A structured `BddStyleFail` is what the
+ * caller maps to `qa-handoff` rejection.
+ */
+export declare function verifyBddStyle(input: VerifyBddStyleInput): BddStyleVerdict;

package/dist/services/qa/bdd-test-style-verifier.js

@@ -0,0 +1,268 @@
+/**
+ * src/services/qa/bdd-test-style-verifier.ts
+ *
+ * rid-2026-08-05-bdd-test-style Slice B — peaks-qa verification-time
+ * BDD test-style verifier. This is the read-only, post-edit companion
+ * to the `scripts/migrate-to-bdd.mjs` AST migrator shipped in Slice A.
+ *
+ * Purpose:
+ *   When peaks-qa runs its verification gate, it picks up the git diff
+ *   for the slice and asks this module whether the new / modified test
+ *   files comply with the BDD given-when-then style. The verdict is
+ *   surfaced as either `ok` (and the slice can advance) or one of two
+ *   structured failure reasons (`missing-given-when-then` or
+ *   `description-no-should-when`) that the caller turns into a
+ *   `qa-handoff` rejection back to peaks-rd.
+ *
+ * Why a real AST and not a regex:
+ *   The Slice A migrator established the convention: test files have
+ *   multi-line `it(...)` calls, nested arrow bodies, and string
+ *   literals that often contain words like "when" inside the assertion
+ *   message (not in the description). A regex pass on the raw source
+ *   would false-positive on string internals. The TypeScript Compiler
+ *   API (already a dev dep via vitest) lets us:
+ *     1. Inspect the first `StringLiteral` argument of an `it` /
+ *        `test` / `describe` call without scanning comments or
+ *        string content inside the body.
+ *     2. Walk only the leading-comment ranges that sit before the
+ *        first statement of the callback block, so a `// when:`
+ *        inside an `expect(actual).toEqual('when X happens')` is
+ *        correctly ignored.
+ *
+ * No new dependencies. The verifier is intentionally synchronous and
+ * pure (input source + path list -> verdict) so peaks-qa can call it
+ * from a deterministic verification step without subprocess overhead.
+ *
+ * Anti-fake-green (CLI silent-catch rule):
+ *   This module throws on parse failure. It does NOT swallow parse
+ *   errors and return `{ ok: true }` — that would silently green-light
+ *   malformed test files. A parse error is a structural problem; the
+ *   caller must surface it.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import ts from 'typescript';
+/** Test runners whose first string-arg is the test description. */
+const TEST_NAMES = new Set(['it', 'test']);
+/**
+ * Verify that every `it(...)` / `test(...)` call in the given test
+ * files follows the BDD given-when-then contract.
+ *
+ * Contract:
+ *   1. The first `StringLiteral` argument of every `it` / `test` call
+ *      MUST match `/(\bwhen\b|\bshould\b)/` (word-boundary anchored,
+ *      case-insensitive). A regex on the raw description is correct
+ *      here because the description itself is a literal — there is
+ *      no nested template literal to misread.
+ *   2. The callback body (the second argument when it is an arrow /
+ *      function expression with a block) MUST have a `// given:`,
+ *      `// when:`, `// then:` triple at the top, in that order,
+ *      within the first 3 leading-comment ranges before the first
+ *      statement. The `// arrange:` / `// act:` / `// assert:` AAA
+ *      legacy is NOT accepted — the contract is given-when-then
+ *      only.
+ *
+ * Returns the FIRST failure encountered (file order, then
+ * top-to-bottom line order). A structured `BddStyleFail` is what the
+ * caller maps to `qa-handoff` rejection.
+ */
+export function verifyBddStyle(input) {
+    let scanned = 0;
+    for (const rel of input.testFiles) {
+        const absPath = resolve(input.projectRoot, rel);
+        const source = readFileSync(absPath, 'utf8');
+        const sourceFile = ts.createSourceFile(rel, source, ts.ScriptTarget.ESNext, 
+        /* setParentNodes */ true, ts.ScriptKind.TS);
+        let earliestFail = null;
+        const recordFail = (fail) => {
+            if (earliestFail === null) {
+                earliestFail = fail;
+                return;
+            }
+            const { line: existingLine } = earliestFail;
+            if (fail.line < existingLine)
+                earliestFail = fail;
+        };
+        const visit = (node) => {
+            if (earliestFail !== null)
+                return;
+            if (ts.isCallExpression(node)) {
+                const callee = node.expression;
+                if (ts.isIdentifier(callee) && TEST_NAMES.has(callee.text)) {
+                    scanned += 1;
+                    const descCheck = checkDescription(node, sourceFile, rel);
+                    if (descCheck !== null) {
+                        recordFail(descCheck);
+                        return;
+                    }
+                    const bodyCheck = checkBody(node, sourceFile, rel);
+                    if (bodyCheck !== null) {
+                        recordFail(bodyCheck);
+                        return;
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        if (earliestFail !== null)
+            return earliestFail;
+    }
+    return { ok: true, scanned };
+}
+/**
+ * Inspect the first string-literal argument of an `it` / `test` call.
+ *
+ * - If the first argument is not a string literal, treat it as a
+ *   failure (the BDD contract requires a literal description).
+ * - If the literal text does not contain "when" or "should" as a
+ *   whole word, return a `description-no-should-when` failure.
+ */
+function checkDescription(call, sourceFile, relPath) {
+    const firstArg = call.arguments[0];
+    if (firstArg === undefined || !ts.isStringLiteralLike(firstArg)) {
+        const pos = call.getStart(sourceFile);
+        const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+        return {
+            ok: false,
+            reason: 'description-no-should-when',
+            file: relPath,
+            line: line + 1,
+            description: '<non-literal first argument>',
+            expected: 'first argument must be a string literal containing "when" or "should"',
+        };
+    }
+    const description = firstArg.text;
+    if (!hasWhenOrShould(description)) {
+        const pos = firstArg.getStart(sourceFile);
+        const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+        return {
+            ok: false,
+            reason: 'description-no-should-when',
+            file: relPath,
+            line: line + 1,
+            description,
+            expected: 'description must contain the word "when" or "should" (BDD style)',
+        };
+    }
+    return null;
+}
+/**
+ * Inspect the callback body of an `it` / `test` call for the
+ * `// given:` / `// when:` / `// then:` triple.
+ *
+ * Rules (Slice A migrator + design §4.B):
+ *   - The second argument must be an arrow / function expression
+ *     with a block body. If it is missing or not a block (e.g. an
+ *     expression-body arrow `it('x', () => expect(y).toBe(z))`),
+ *     we still need the comments — but expression-body arrows
+ *     cannot host them. In that case we fall back to inspecting
+ *     the leading comments before the entire call expression,
+ *     which matches the Slice A migrator's `isAlreadyMigrated`
+ *     check shape.
+ *   - The three comments must be the FIRST THREE leading-comment
+ *     ranges before the relevant body / first-statement anchor.
+ *   - The order must be `given` → `when` → `then`. A re-ordered
+ *     triple is rejected.
+ */
+function checkBody(call, sourceFile, relPath) {
+    const body = getCallbackBlock(call);
+    if (body !== null) {
+        return checkBlockLeadingComments(body, sourceFile, relPath);
+    }
+    // Expression-body arrow or non-block callback: comments cannot
+    // live inside the body. The Slice A migrator only inserts the
+    // triple on block bodies, so an expression-body form is by
+    // definition non-BDD and must fail. This keeps the contract
+    // symmetric with the migrator.
+    const pos = call.getStart(sourceFile);
+    const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+    return {
+        ok: false,
+        reason: 'missing-given-when-then',
+        file: relPath,
+        line: line + 1,
+        expected: 'block-body callback with // given: / // when: / // then: comments at the top',
+    };
+}
+function getCallbackBlock(call) {
+    const callback = call.arguments[1];
+    if (callback === undefined)
+        return null;
+    if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback))
+        return null;
+    if (!callback.body || !ts.isBlock(callback.body))
+        return null;
+    return callback.body;
+}
+function checkBlockLeadingComments(block, sourceFile, relPath) {
+    // TypeScript's `getLeadingCommentRanges` API is unreliable for
+    // comment-only blocks: with `setParentNodes: true`, an empty
+    // block (no statements, only comments) has no anchor to attach
+    // the comments to, so the API returns zero ranges. To get a
+    // deterministic answer, we scan the block's text directly and
+    // pick the first three non-empty lines.
+    //
+    // The block's text spans `{` ... `}`. We extract the body,
+    // split on lines, and check the first three non-empty lines for
+    // the BDD triple. This is AST-driven (we use the block's source
+    // range from the SourceFile, not a global regex) and survives
+    // both empty-body and populated-body cases.
+    const blockStart = block.getStart(sourceFile) + 1; // skip `{`
+    const blockEnd = block.end - 1; // skip `}`
+    const body = sourceFile.text.slice(blockStart, blockEnd);
+    const lines = body.split(/\r?\n/);
+    const nonEmpty = [];
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        nonEmpty.push(line);
+        if (nonEmpty.length === 3)
+            break;
+    }
+    if (nonEmpty.length < 3 || !matchesBddTriple(nonEmpty)) {
+        return makeMissingCommentFailure(block, sourceFile, relPath);
+    }
+    return null;
+}
+function makeMissingCommentFailure(block, sourceFile, relPath) {
+    // Report the line of the opening `{` + 1 — the line that should
+    // contain the first comment of the BDD triple. This gives the
+    // caller a stable pointer even when the block is empty.
+    const pos = block.getStart(sourceFile) + 1;
+    const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+    return {
+        ok: false,
+        reason: 'missing-given-when-then',
+        file: relPath,
+        line: line + 1,
+        expected: '// given: / // when: / // then: triple at the top of the block body',
+    };
+}
+/**
+ * Match the three leading comments against the BDD triple. Each
+ * entry must be a `// <keyword>:` line (with optional trailing
+ * whitespace); the keywords must appear in `given`, `when`, `then`
+ * order, case-insensitive.
+ */
+function matchesBddTriple(triple) {
+    if (triple.length !== 3)
+        return false;
+    // Each entry must be a `// <keyword>:` line, optionally followed
+    // by descriptive text. The Slice A migrator's `buildCommentBlock`
+    // produces `// given: the test setup` / `// when:  the function
+    // under test is invoked` / `// then:  the result matches the
+    // expectation` — the `when` line uses two spaces after the colon
+    // for visual alignment with `given:` and `then:`, so the regex
+    // is intentionally permissive about trailing text.
+    const patterns = [
+        /^\s*\/\/\s*given\s*:/i,
+        /^\s*\/\/\s*when\s*:/i,
+        /^\s*\/\/\s*then\s*:/i,
+    ];
+    return patterns.every((pat, i) => pat.test(triple[i] ?? ''));
+}
+/** True when `text` contains `when` or `should` as a whole word. */
+function hasWhenOrShould(text) {
+    return /(\bwhen\b|\bshould\b)/i.test(text);
+}

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

@@ -142,6 +142,7 @@ export function setPresenceLease(input) {
         graphRef,
         skill: input.skill,
         ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        ...(input.mode ? { mode: input.mode } : {}),
         depth: input.depth ?? 0,
         startedAt: now,
         lastHeartbeat: now,

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

@@ -96,6 +96,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)

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.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": "0.0.41",
     "peaks-loop-shared-channel": "0.0.19",
-    "peaks-loop-mut": "0.1.15"
+    "peaks-loop-mut": "0.1.15",
+    "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.