peaks-loop 4.0.10 → 4.0.12

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 4.0.12 — 2026-08-05 (5-slice optimization bundle)
+
+**publish.yml strict tag gate** (slice 1, commit `f60f7597`):
+- New `gate-strict-tag-format` step inserted after `Checkout` (publish.yml lines 104-130). Runs `git describe --tags --exact-match HEAD` and validates against `^v[0-9]+\.[0-9]+\.[0-9]+$`; rejects `v1` / `v4.0` / `v4.0.11-rc1` / `v4.0.11+sha` shapes with `::error title=strict-tag-format::`.
+- Drift guard: `tests/unit/publish-tag-strict.test.ts` (4 cases).
+
+**PreToolUse:Bash hook JSON output validation** (slice 2, commit `eb13e44c`):
+- Regression fix for the 2026-07-27 root cause. `.claude/settings.json` line 14 + `src/services/skills/hooks-settings-service.ts:86` both now append ` --json` to the `peaks gate enforce` hook command.
+- Drift guard: `tests/unit/hooks/gate-enforce-template-json-flag.test.ts` (3 cases).
+- PRD mis-reference correction noted: the actual hook template owner is `hooks-settings-service.ts`, not `claude-settings-template.ts` (the latter carries `peaks code gate-step-08`, a different hook path).
+
+**Session-overload signal index** (slice 3, commit `6ef12bde`):
+- New `skills/peaks-code/references/session-overload-signal-index.md` (60 lines): 7-signal lookup table (prompt size / auto-compact zone / sub-agent dispatch guard / statusline compact bar / in-flight batch deferral / compact stalled / sub-agent heartbeat) with thresholds + files + LLM actions + decision flowchart.
+- SKILL.md Step N+2 section gets a 1-line "See also" pointer (+141 bytes; under 30000 cap).
+- Codifies red line: LLM MUST NOT re-ask user about cost/length/context (cite `references/job-loop.md:59` red line #2).
+
+**active-skill.json → sid-scoped lease projection** (slice 4, 3 sub-slices):
+- Slice 4-A (`dc350c2c`): `skill-presence-service.ts` write path removed; `presence-marker-detector.ts` deprecated-constant comments added.
+- Slice 4-B (`7699f70f`): `skill-statusline-service.ts` `readPresenceReadOnly` rewritten to canonical-only (drops `legacyPresence: true`, enumerates `listPresenceLeases`, deletes `PRESENCE_FILE` / `PRESENCE_FILE_LEGACY`). Fixes the "new session statusline empty" issue (root cause: outerSessionId drift between session.json and the global single-slot file).
+- Slice 4-C (`1b08a62c`): doctor / sc / migration / hooks / skills / reconcile-command all migrated to canonical lease reads. New `STALE_SINGLE_SLOT_FILES` workspace-layout check surfaces orphan `.peaks/_runtime/active-skill.json` as a "stale single-slot presence" diagnostic (not an error). Drift guard: `tests/unit/workspace/active-skill-json-cleanup.test.ts` (3 cases).
+- Multi-session on one project is now safe (each session writes its own `presence-<callerId>.json` under `.peaks/_runtime/<sid>/presence-index/`; the deprecated single-slot global file no longer races).
+
+**Orchestrator-can-do probe CLI** (slice 5, commit `52736c82`):
+- New `peaks code orchestrator-can-do --slice-spec <text> --json` command (the 2026-08-05 lesson converted into a downstream-inheritable CLI). Evaluates 4 boundary questions (source code? sub-agent available? requires user decision? context sustainable?) and returns `{ canDoInSession, blockers, warnings, suggestions, contextRatio, subAgentAvailable }`.
+- SKILL.md gains a Step 0.51 paragraph pointing at it (LLM must run this probe before deciding to push a slice to the next session).
+- 17 unit tests cover all 4 boundary branches.
+- Anti-fake-green pattern: any future orchestrator capability judgment MUST call this CLI rather than re-derive the 4-question matrix from intuition.
+
+**Lockstep bump.** peaks-loop-shared `0.0.41 → 0.0.42` (CLI_VERSION re-stamped to 4.0.12); peaks-loop-mut `0.1.14 → 0.1.15`; peaks-loop-shared-channel `0.0.18 → 0.0.19`.
+
+## 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/cli/commands/code-commands.js

@@ -26,6 +26,7 @@ import { registerCodeRunCommand } from './code-run-command.js';
 import { registerCodeModeGateCommands } from './code-mode-gate-commands.js';
 import { registerCodeJobShapeCommands } from './code-job-shape-commands.js';
 import { registerCodeRuntimeCommands } from './code-runtime-commands.js';
+import { registerCodeOrchestratorCanDoCommand } from './code-orchestrator-can-do.js';
 const STEP_ORDER = [
     'load-memory',
     'standards-preflight',
@@ -114,5 +115,6 @@ export function registerCodeCommands(program, io) {
     registerCodeModeGateCommands(code, io);
     registerCodeJobShapeCommands(code, io);
     registerCodeRuntimeCommands(code, io);
+    registerCodeOrchestratorCanDoCommand(code, io);
     registerCodeRunCommand(code, io);
 }

package/dist/cli/commands/code-orchestrator-can-do.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — CLI shim for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Thin entry point that wires the `orchestrator-can-do` subcommand
+ * to the parent `code` command. The actual probe logic lives in
+ * `../../services/code/orchestrator-can-do.ts`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`) — the peaks-code orchestrator
+ * MUST delegate source-code changes via sub-agent dispatch, not via
+ * direct Edit/Write. The probe returns a structured verdict so the LLM
+ * does not need to vibes-call "can this slice run in the current session".
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeOrchestratorCanDoCommand(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-orchestrator-can-do.js

@@ -0,0 +1,75 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — CLI shim for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Thin entry point that wires the `orchestrator-can-do` subcommand
+ * to the parent `code` command. The actual probe logic lives in
+ * `../../services/code/orchestrator-can-do.ts`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`) — the peaks-code orchestrator
+ * MUST delegate source-code changes via sub-agent dispatch, not via
+ * direct Edit/Write. The probe returns a structured verdict so the LLM
+ * does not need to vibes-call "can this slice run in the current session".
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { evaluateOrchestratorCanDo, OrchestratorCanDoError, ORCHESTRATOR_PRECOMPACT_RATIO, ORCHESTRATOR_REDLINE_RATIO, } from '../../services/code/orchestrator-can-do.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+export function registerCodeOrchestratorCanDoCommand(code, io) {
+    addJsonOption(code
+        .command('orchestrator-can-do')
+        .description('2026-08-05 lesson: probe whether the LLM orchestrator can execute a slice in the ' +
+        'current session. Evaluates 4 boundary questions (source-code touched? sub-agent ' +
+        'available? requires user decision? context sustainable?) and returns a structured ' +
+        'verdict with canDoInSession, blockers, warnings, and concrete next-action ' +
+        'suggestions. Default to canDoInSession=true unless hard blockers are present; ' +
+        'sub-agent dispatch (`peaks sub-agent dispatch rd`) is the canonical delegation path ' +
+        'for source-code changes.')
+        .requiredOption('--slice-spec <text>', 'short description of the slice (e.g. "modify src/services/foo.ts")')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')
+        .option('--peaks-bin <path>', 'peaks binary path (test seam; default: peaks on PATH)')).action(async (opts) => {
+        try {
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const peaksBin = opts.peaksBin ?? 'peaks';
+            const result = await evaluateOrchestratorCanDo({
+                sliceSpec: opts.sliceSpec,
+                projectRoot,
+                probeSubAgentAvailable: () => probeSubAgentAvailableWithBin(projectRoot, peaksBin),
+                probeContextRatio: () => probeContextRatioWithBin(projectRoot, peaksBin),
+            });
+            printResult(io, ok('code.orchestrator-can-do', result, [...result.warnings], [...result.suggestions, ...summaryLines(result)]), opts.json);
+            if (!result.canDoInSession)
+                process.exitCode = 1;
+        }
+        catch (err) {
+            if (err instanceof OrchestratorCanDoError) {
+                printResult(io, fail('code.orchestrator-can-do', err.code, err.message, null, [
+                    'Pass --slice-spec <text> describing what the slice should change',
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('code.orchestrator-can-do', 'PROBE_FAILED', getErrorMessage(err), null, [
+                'Verify --slice-spec is non-empty and --project is a valid path',
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function summaryLines(result) {
+    const lines = [];
+    lines.push(`verdict: ${result.canDoInSession ? 'canDoInSession=true' : 'canDoInSession=false (blockers present)'}; ` +
+        `q1=src[${result.q1SourceCodeTouched ? 'Y' : 'N'}] q2=subagent[${result.q2SubAgentAvailable ? 'Y' : 'N'}] ` +
+        `q3=user-decision[${result.q3RequiresUserDecision ? 'Y' : 'N'}] q4=ratio=${result.contextRatio.toFixed(2)} ` +
+        `(red-line ${ORCHESTRATOR_REDLINE_RATIO} / pre-compact ${ORCHESTRATOR_PRECOMPACT_RATIO})`);
+    return lines;
+}
+async function probeSubAgentAvailableWithBin(projectRoot, peaksBin) {
+    const { probeSubAgentAvailable } = await import('../../services/code/orchestrator-can-do.js');
+    return probeSubAgentAvailable(projectRoot, peaksBin);
+}
+async function probeContextRatioWithBin(projectRoot, peaksBin) {
+    const { probeContextRatio } = await import('../../services/code/orchestrator-can-do.js');
+    return probeContextRatio(projectRoot, peaksBin);
+}

package/dist/cli/commands/workspace/reconcile-command.js

@@ -26,9 +26,12 @@ export function registerWorkspaceReconcileCommand(workspace, io) {
         'By default (no --apply) the command performs four actions:\n' +
         '  1. Migrates legacy runtime files into .peaks/_runtime/: ' +
         '.peaks/.session.json -> .peaks/_runtime/session.json, ' +
-        '.peaks/.active-skill.json -> .peaks/_runtime/active-skill.json, ' +
         '.peaks/sop-state/ -> .peaks/_runtime/sop-state/ ' +
-        '(idempotent; no-op if already on the new layout).\n' +
+        '(idempotent; no-op if already on the new layout). ' +
+        'Single-slot presence files (.peaks/.active-skill.json and ' +
+        '.peaks/_runtime/active-skill.json) are no longer migrated; ' +
+        'they were removed in slice 4.0.11 and should be deleted ' +
+        'manually if present.\n' +
         '  2. Re-points .peaks/_runtime/session.json to the canonical session ' +
         'using a 4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
         'latest any-file mtime -> dir-name sort.\n' +

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/code/orchestrator-can-do.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Slice 2026-08-05-orchestrator-can-do-probe — service layer for
+ * `peaks code orchestrator-can-do`.
+ *
+ * Encodes the 2026-08-05 lesson (`.peaks/memory/2026-08-05-peaks-code-
+ * orchestrator-capability-misjudgment.md`): the peaks-code orchestrator
+ * MUST NOT Edit/Write `src/` files directly, but MUST delegate via
+ * `peaks sub-agent dispatch`. The decision "can this slice run in the
+ * current session" must be a structured probe — not a vibes call.
+ *
+ * The probe answers 4 boundary questions:
+ *   Q1 — Is the change to source code? (keywords: src/, *.ts, *.tsx,
+ *        *.js, package.json, tsconfig, workflows/). If yes → NOT a
+ *        blocker; orchestrator delegates to sub-agent.
+ *   Q2 — Can a sub-agent be dispatched? (probe `peaks sub-agent
+ *        dispatch --role rd --help`). If no → blocker.
+ *   Q3 — Does the slice require user decisions? (keywords: design,
+ *        decide, ?, 选择, 决定). If yes → soft warning, NOT a blocker
+ *        (the LLM should AskUserQuestion, which is cheap).
+ *   Q4 — Is context usage sustainable? (probe `peaks code context-now
+ *        --json`). ratio ≥ 0.95 → blocker (red-line); ≥ 0.85 →
+ *        blocker (auto-compact-now).
+ *
+ * Decision rule:
+ *   canDoInSession === (blockers.length === 0)
+ *
+ * Concrete suggestion when canDoInSession=true and slice touches
+ * source code:
+ *   `peaks sub-agent dispatch rd --prompt "<slice-spec>" --request-id
+ *   <rid> --project . --batch-id <uuid>`
+ *
+ * Pure-function module. The CLI shim (code-orchestrator-can-do.ts)
+ * adapts the envelope into the program's `ResultEnvelope<T>` shape.
+ */
+/** Slice 2026-08-05-orchestrator-can-do-probe: red-line threshold. */
+export declare const ORCHESTRATOR_REDLINE_RATIO = 0.95;
+/** Slice 2026-08-05-orchestrator-can-do-probe: pre-compact threshold. */
+export declare const ORCHESTRATOR_PRECOMPACT_RATIO = 0.85;
+/** Source-code keywords that signal "do NOT Edit/Write directly". */
+export declare const SOURCE_CODE_KEYWORDS: readonly string[];
+/** Decision-marker keywords that signal "needs user AskUserQuestion". */
+export declare const DECISION_KEYWORDS: readonly string[];
+export interface ContextProbe {
+    /** 0.0–1.0; ≥0.85 = pre-compact; ≥0.95 = red-line. */
+    readonly ratio: number;
+    /** Source tag from `peaks code context-now`. */
+    readonly source: string;
+}
+export interface OrchestratorCanDoInput {
+    readonly sliceSpec: string;
+    readonly projectRoot: string;
+    /**
+     * Test seam — caller injects probe results. Production CLI builds
+     * these via `probeSubAgentAvailable` + `probeContextRatio`. When the
+     * test seam is set, the CLI's actual probes are skipped.
+     */
+    readonly probeSubAgentAvailable?: () => Promise<boolean>;
+    readonly probeContextRatio?: () => Promise<ContextProbe>;
+}
+export interface OrchestratorCanDoResult {
+    /** canDoInSession === (blockers.length === 0). */
+    readonly canDoInSession: boolean;
+    readonly blockers: readonly string[];
+    readonly warnings: readonly string[];
+    readonly suggestions: readonly string[];
+    readonly contextRatio: number;
+    readonly subAgentAvailable: boolean;
+    /** Diagnostic — which of the 4 boundary questions fired. */
+    readonly q1SourceCodeTouched: boolean;
+    readonly q2SubAgentAvailable: boolean;
+    readonly q3RequiresUserDecision: boolean;
+    readonly q4ContextRatio: number;
+}
+export declare class OrchestratorCanDoError extends Error {
+    readonly code: 'MISSING_SLICE_SPEC' | 'PROBE_FAILED';
+    constructor(message: string, code: 'MISSING_SLICE_SPEC' | 'PROBE_FAILED');
+}
+/**
+ * Q1: does the slice touch source code? Pure keyword scan over
+ * the slice-spec string. Case-insensitive substring match.
+ */
+export declare function detectSourceCodeTouched(sliceSpec: string): boolean;
+/**
+ * Q3: does the slice require user decisions? Pure keyword scan
+ * over the slice-spec string.
+ */
+export declare function detectRequiresUserDecision(sliceSpec: string): boolean;
+/**
+ * Q2: probe `peaks sub-agent dispatch --role rd --help`. Returns
+ * true when the subprocess exits 0. Resolves to false on spawn
+ * failure or non-zero exit.
+ */
+export declare function probeSubAgentAvailable(projectRoot: string, peaksBin?: string): Promise<boolean>;
+/**
+ * Q4: probe `peaks code context-now --json`. Parses the data.ratio
+ * field. Falls back to {ratio: 0, source: 'unavailable'} when the
+ * subprocess fails or returns malformed JSON.
+ */
+export declare function probeContextRatio(projectRoot: string, peaksBin?: string): Promise<ContextProbe>;
+/**
+ * Build the structured OrchestratorCanDoResult. Pure over the 4 Q
+ * signals + sliceSpec. Decision rule is: canDoInSession === !blockers.
+ */
+export declare function buildOrchestratorCanDoResult(input: OrchestratorCanDoInput, signals: {
+    q1SourceCodeTouched: boolean;
+    q2SubAgentAvailable: boolean;
+    q3RequiresUserDecision: boolean;
+    q4ContextRatio: number;
+}): OrchestratorCanDoResult;
+/**
+ * Evaluate a slice-spec end-to-end. Probes Q2/Q4 via subprocess
+ * (overridable via test seams in `input`). Q1/Q3 are pure.
+ */
+export declare function evaluateOrchestratorCanDo(input: OrchestratorCanDoInput): Promise<OrchestratorCanDoResult>;