peaks-loop 4.0.0-beta.9 → 4.0.3

package/skills/peaks-code/references/worktree-governance.md

@@ -0,0 +1,123 @@
+# Worktree governance — 3-layer design
+
+> **Source of truth.** This document is the canonical reference for peaks-loop's worktree posture. The SKILL.md `## Worktree governance` chapter carries the heading + 1-line pointers; the full design lives here. Editing peaks-loop source propagates to every consumer project on `npm install`.
+
+## The problem this solves
+
+Sub-agents using raw `git worktree add` to escape governance:
+
+1. The superpowers chain ends in `superpowers:using-git-worktrees` SKILL.md line 96 (`git worktree add "$path" -b "$BRANCH_NAME"`). An LLM that follows `brainstorming` → `writing-plans` → `subagent-driven-development` → `using-git-worktrees` will land on raw `git worktree add` without ever touching peaks-loop's hooks.
+2. Worktrees created outside peaks-loop's governance are invisible to `peaks worktree auth grant|revoke|status` — the L2 hook gate cannot deny or grant them.
+3. Worktree-only artifacts (`.peaks/_runtime/<sessionId>/<role>/requests/<rid>.md` written from inside a worktree) may be lost when the worktree is pruned mid-run. Lesson 1 of [[2026-07-27-rid-016-monorepo-delete-5-subpackages]] documents the failure mode.
+
+## Three-layer design (defence in depth)
+
+| Layer | Mechanism | Strength | Failure mode |
+|---|---|---|---|
+| L1 | Sub-agent system prompt `MUST NOT` on the superpowers chain | Weak — LLM may forget | Prose-only; no enforcement |
+| L2 | PreToolUse hook → `peaks gate enforce` → `evaluateWorktreeAuth` | Medium — sees every tool call but cannot intercept Skill selection | Hook bypassed if user disables `peaks hooks install` |
+| L3 | IDE `permissions.deny: ["UseSkill(superpowers:using-git-worktrees)"]` | Strongest — IDE refuses Skill BEFORE LLM sees it | Requires `peaks hooks install` to have run; bypassed by `--dangerously-skip-permissions` |
+
+The 3 layers stack. L3 is the strongest because it operates BELOW the LLM's tool-call decision: the Skill never appears in the LLM's tool list, so the LLM cannot choose to invoke it.
+
+## L1 — Sub-agent system prompt
+
+The explicit `MUST NOT` block lives in:
+- `peaks-rd/references/rd-sub-agent-dispatch.md`
+- `peaks-qa/...`
+- `peaks-ui/...`
+- `peaks sub-agent dispatch` CLI prompt template
+
+Each prompt template carries the block:
+> MUST NOT follow the superpowers chain (`brainstorming` → `writing-plans` → `subagent-driven-development` → `using-git-worktrees`) for worktree decisions. The chain is reference material, not a workflow. For worktree operations, use `peaks worktree spawn --rid <id> --ttl <duration> --purpose <text>` (or, until that ships, fall back to L2 hook gate + manual `peaks worktree auth grant`).
+
+L1 is the weakest layer because the LLM is the decision-maker and may forget the block under load. L3 exists to catch L1 failures.
+
+## L2 — Hook + lifecycle gate
+
+`peaks hooks install` writes a PreToolUse hook that calls `peaks gate enforce` BEFORE the IDE permission system. For worktree operations:
+
+```bash
+# User authorizes a worktree operation
+peaks worktree auth grant \
+  --rid rid-2026-07-29-worktree-spawn \
+  --reason "RD sub-agent for worktree spawn slice" \
+  --ttl 5m
+# Output: grant token, single-use by default
+```
+
+The token authorizes exactly one `git worktree add` matching the granted scope (path / branch / rid). 5 deny codes:
+- `REQUIRED` — no grant on file, request denied
+- `EXPIRED` — TTL elapsed, re-authorize
+- `REQUEST_MISMATCH` — git args don't match the granted scope
+- `CONSUMED` — token already used (single-use)
+- `FILE_INVALID` — grant file unreadable / corrupted
+
+Implementation: `src/services/hooks/worktree-authorization-gate.ts`. Sediment: `.peaks/memory/2026-07-27-worktree-user-auth-hard-gate.md`.
+
+## L3 — IDE `permissions.deny`
+
+`peaks hooks install` ALSO writes a `permissions.deny` block into the IDE settings.json:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "UseSkill(superpowers:using-git-worktrees)"
+    ]
+  }
+}
+```
+
+The deny entry is wrapped in the IDE's `UseSkill(...)` envelope (Claude Code's permission-system syntax). Claude Code refuses to invoke any Skill listed there BEFORE the LLM sees the Skill's name in the available-tool list.
+
+Single source of truth: `SUPERPOWERS_DENIED_SKILLS` in `src/services/skills/hooks-settings-service.ts`. To deny a new skill, append its id there and re-run `peaks hooks install`.
+
+Sediment: `.peaks/memory/2026-07-29-worktree-layer3-deny.md`.
+
+## Sub-agent worktree contract (mandatory)
+
+Every sub-agent dispatched by peaks-rd / peaks-qa / peaks-ui / peaks-sc / peaks-txt MUST:
+
+1. **Use `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>`** for any worktree operation. Raw `git worktree add` is forbidden.
+2. **Treat the superpowers chain as reference material only.** It MAY inform PRD / RD planning but MUST NOT drive tool selection.
+3. **Write artifacts under `.peaks/_runtime/<sessionId>/<role>/requests/` in the MAIN checkout.** Dispatch with `--project .` (the main workdir), NOT `--project .claude/worktrees/...`. Worktrees are ephemeral; main is durable.
+
+## Operator runbook
+
+- **Manual authorization**: `peaks worktree auth grant|revoke|status` (L2 surface).
+- **Inspect L3 state**: `peaks hooks status` reports `permissionsDenyEntries` (desired) + `permissionsDenyOnDisk` (reality).
+- **Refresh L3 deny block**: `peaks hooks uninstall && peaks hooks install` re-writes the block from `SUPERPOWERS_DENIED_SKILLS`.
+- **Diagnose L3 failures**: the on-disk `permissions.deny` is the source of truth. If a Skill bypasses the deny, the IDE permission system is broken (not peaks-loop's problem).
+
+## Future rid path
+
+| rid | Layer | Goal | Status |
+|---|---|---|---|
+| rid-L1 | L1 | Hard-coded prompt hardening across all dispatch templates | Pending |
+| rid-L2-extended | L2 | `peaks worktree spawn` with lease lifecycle, removing manual `peaks worktree auth grant` loop | Pending |
+| rid-L3-extended | L3 | Append new deny skills to `SUPERPOWERS_DENIED_SKILLS` as needed | Trigger-only |
+
+## Related memories
+
+- [[2026-07-27-worktree-user-auth-hard-gate]] — L2 baseline, shipped earlier.
+- [[2026-07-29-worktree-layer3-deny]] — L3 Minimal Viable rationale.
+- [[2026-07-29-worktree-l2-extended-part1]] — lease foundation + spawn/release CLI.
+- [[2026-07-29-worktree-l2-extended-part2]] — renew/list/gc/status + hook integration + dispatch bridge + lifecycle e2e.
+- [[2026-07-29-worktree-l2-extended-part3]] — auto-release on terminal finalization.
+- [[2026-07-29-worktree-l2-extended-part4]] — observability emitter + v3 schema.
+- [[2026-07-29-worktree-l2-extended-part5]] — leak rate + cross-session aggregation.
+- [[2026-07-29-worktree-l2-extended-part6-9]] — stats summary + v3.1 schema + container contract bridge.
+
+## Lease observability (Parts 4-6)
+
+The L2 ecosystem emits a `lease` category into the existing observability stream (`.peaks/_runtime/<sid>/metrics/slices.jsonl`). Seven `kind` values: `spawn` / `renew` / `release` / `gc` / `autoRelease` / `autoRelease-failed` / `autoRelease-skipped`. Two CLIs read the stream:
+
+- `peaks lease-metrics [--session <sid>] [--project <root>] [--rate] [--all-sessions] [--json]` — per-kind counts + 5-event tail. With `--rate`, adds `estimatedActive` / `estimatedLeaked` / `avgLifetimeMs` / `p99LifetimeMs`. With `--all-sessions`, aggregates across every session under `.peaks/_runtime/`. The two flags are independent; `--rate --all-sessions` is the project-wide leak view.
+- `peaks lease-stats --project <root> --json` — project-wide summary: counts + rate + per-rid (top 20) + per-role + per-isolation breakdown. Always aggregates cross-session. Use this when you want a "status board" rather than the raw event stream.
+
+The `estimated` prefix is intentional: the canonical "alive" set is the on-disk lease files in `.peaks/_runtime/<sid>/worktree-leases/` (queryable via `peaks worktree list`). The aggregation is a metrics-stream view — useful for time-series dashboards, but the FS state is the source of truth for "is this lease still alive right now?".
+
+For dashboards: pipe the JSON envelope into `jq`, paste into a `peaks lease-stats --json` reader, or feed into the `peaks audit metrics` flow. The schema is the same `ObservabilityEvent` v1 used by slice / dispatch / cycle events.
+- [[2026-07-27-rid-016-monorepo-delete-5-subpackages]] — Lesson 1: worktree-only artifact fragility.
+- [[2026-07-24-peaks-code-bridge-002-rootcause]] — peaks-code ↔ superpowers bridge baseline.

package/skills/peaks-code/test-prompts.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "prompt": "/peaks-code https://example.feishu.cn/wiki/PRODUCT_DOC_ID 是产品文档。请根据这份产品文档，对 /Users/yuanyuan/Desktop/work/platform-rag-web 这个前端项目进行迭代开发。目前只是前端项目，没有后端 swagger.json，可以先 mock，等后面有真实 swagger.json 数据时再联调替换。允许修改目标仓代码，这是实战测试。",
+    "expected": "peaks-code 选择 full-auto/实战路径，使用本仓 skills 目录下的 peaks-prd/rd/ui/qa/sc/txt，Feishu 走 headed gstack/browse/dist/browse 可见浏览器登录 handoff，先校验 https 和批准的 Feishu/Lark tenant 域名，生成 .peaks/_runtime/<session-id>/prd|rd|qa|txt 脱敏中间产物；RD 完成实现、单测、CR、安全检查、dry-run 后必须进入 QA；前端 RD 自测和 QA 验证都必须使用 headed gstack/browse/dist/browse 有头浏览器端到端验证并确认可见浏览器；QA 完成 API/mock 验证、浏览器 E2E、报告、安全和性能检查。若 QA 报告存在失败、阻塞、缺失或未验证项，必须回到 RD 修复并再次 QA，直到 QA 全部通过或生成 blocked handoff；full-auto 可用 Claude Code goal 维持 RD fixes until QA passes all acceptance items 的控制目标；不得保留登录 URL、cookie、headers、tokens、storage state、browser traces、raw browser/network state 或 PII/SSO/MFA 截图/日志。"
+  },
+  {
+    "id": 2,
+    "prompt": "/peaks-code 对 /Users/yuanyuan/Desktop/work/platform-rag-web 做前端需求迭代，需求来自需要登录的 Feishu 产品文档；如果浏览器登录没打开或文档仍不可读，需要阻塞并告诉我具体要做什么，不要用 unauthenticated fetch，也不要绕过 SSO/MFA。",
+    "expected": "流程必须验证可见浏览器 handoff，不能降级到 fetch；登录或访问失败时生成 blocked PRD/TXT 胶囊，只记录脱敏状态和下一步，不保存登录 URL、cookie、headers、tokens、storage state、浏览器 traces，或包含 PII/SSO/MFA 内容的截图和日志。"
+  }
+]

package/skills/peaks-doctor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: peaks-doctor
 description: Orchestrate peaks-loop's L3 doctor (peaks audit + peaks doctor + peaks openspec from-doctor) for project health. Use when the user asks for a project health check, doctor report, audit, or wants to convert doctor findings into OpenSpec change records. Coordinates the L2 audit framework + the L3.2 doctor + the L3.3 from-doctor proposal generator. Triggers on `/peaks-doctor`, "peaks doctor", "项目健康", "doctor report", "health check", "check the project", "audit my repo".
-internal: true
+visibility: internal
 ---
 ---
 

package/skills/peaks-ide/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: peaks-ide
 description: Orchestrate peaks-loop's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, "set up peaks for my IDE", "switch peaks to Trae", "what did peaks install", "uninstall peaks hooks". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.
-internal: true
+visibility: internal
 ---
 ---
 

package/skills/peaks-solo/SKILL.md

@@ -163,6 +163,27 @@ multiSelect: false
 | 用户主动说"沉淀这个" | **立即问** | `user_explicit` |
 | LLM 识别 ≥ 2 个 reuse signals | **附带 4-section brief 问** | `llm_suggested` |
 
+### 5.3 4-level precedence for keyword triage (rid-020b)
+
+When the user's NL description contains a 24h-mode keyword (`24h` / `通宵` / `夜跑` / `通宵跑` / `夜机` / `不计成本` / `不停机`) AND a code-domain keyword, apply the 4-level precedence table to pick the leaf:
+
+| # | Precedence | If matched | Routes to |
+|---|---|---|---|
+| 1 | peaks-* skill name (highest) | user names `/peaks-code` or `/peaks-content` or `/peaks-doctor` explicitly | named leaf, regardless of 24h keyword |
+| 2 | keyword match | `24h` / `通宵` / `夜跑` etc. present | add `code-domain-evidence` column to triage table; default to `/peaks-code` for code work |
+| 3 | code-domain evidence | change-id / src path / `peaks-code` mention in NL | `/peaks-code` (with `--24h` flag passed via `peaks code run --24h`) |
+| 4 | default (lowest) | none of the above | peaks-solo self-planning fallback (§4) |
+
+### 5.4 24h keyword sub-section (special cases)
+
+Three explicit edge cases — peaks-solo still routes to the named leaf, but the LLM MUST add the 24h flag at the right invocation:
+
+| 24h keyword NL snippet | Default leaf | 24h flag injection |
+|---|---|---|
+| `24h 跑 dispatcher` / `24h triage` | /peaks-solo (self) | — (peaks-solo has no 24h flag; record sediment) |
+| `24h 内容` / `24h 公众号` / `24h 博客` | /peaks-content | peaks-solo surfaces `AskUserQuestion` asking the user to add the 24h flag at the leaf dispatch |
+| `24h 体检` / `24h doctor` / `24h health` | /peaks-doctor | peaks-solo surfaces `AskUserQuestion` asking the user to add the 24h flag at the leaf dispatch |
+
 ---
 
 ## 6. Out of scope (HC-11 锁死)

package/skills/peaks-solo/references/triage-decision-table.md

@@ -16,6 +16,7 @@
 | 跑测试 / test / vitest / unit test | → | /peaks-test |
 | 恢复 / resume / 继续 / 接上次 | → | /peaks-resume |
 | 不知道 / 随便 / 帮我 / 你帮我决定 / 我想做点东西 | → | peaks-solo triage (this skill) |
+| 24h / 通宵 / 通宵跑 / 夜跑 / 夜机 / 不计成本 / 不停机 (code-domain-evidence) | → | /peaks-code (with `--24h` via `peaks code run --24h`; see SKILL.md §5.3) |
 | 切片 / slice / 拆解任务 / 大任务拆小 | → | /peaks-slice-decompose |
 | 想法 / brain-storm / 创意 / 探索思路 | → | /peaks-ide |
 | 最终审查 / final review / 验收 / 4-dim evidence | → | /peaks-final-review |
@@ -29,3 +30,8 @@
 3. **(e) "都不对" → 自规划兜底。** 走 SKILL.md §4。
 4. **空表条目:** "研究 / 信息查询 / GitHub trending / top 10" 等一次性信息查询,**当前 skill 池没有专属 leaf**,peaks-solo 直接走自规划(deep-search / WebSearch)。
 5. **本表是 opportunistic 表,**不是 exhaustive 表。S2/S3 后续可在 dogfood 中发现新关键词补行。
+6. **24h keyword row (rid-020b):** when the NL contains a 24h keyword AND code-domain evidence (e.g. `peaks-code` mentioned, a `src/` change-id, or `peaks code run`), add a `code-domain-evidence` column to the AskUserQuestion and pre-select `/peaks-code` with the `--24h` flag surfaced as a follow-up. The 4-level precedence in SKILL.md §5.3 wins on ties.
+7. **Special case rows (rid-020b):**
+   - `24h dispatcher` / `24h triage` → peaks-solo (self); record sediment after.
+   - `24h 内容` / `24h 公众号` / `24h 博客` → /peaks-content; surface AskUserQuestion asking the user to add the 24h flag.
+   - `24h 体检` / `24h doctor` → /peaks-doctor; surface AskUserQuestion asking the user to add the 24h flag.

package/skills/peaks-sop/test-prompts.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": 1,
+    "prompt": "我想要一个发布流程：先写好 CHANGELOG，再跑通测试，最后才能发布。帮我做成一个 SOP，我不想自己写 JSON。",
+    "expected": "peaks-sop 访谈出 phases（如 draft/review/ship）和门禁，调用 peaks sop init --apply 生成骨架，把门禁写进 sop.json（changelog 用 file-exists、tests 用 command 并提示需要 --allow-commands），跑 peaks sop lint 到 ok:true，用 peaks sop check 验证每个门禁，再 peaks sop register 注册。全程不让用户手写 JSON。"
+  },
+  {
+    "id": 2,
+    "prompt": "我的 SOP lint 报错说门禁绑定了未知阶段，帮我修。",
+    "expected": "peaks-sop 读 lint findings 定位违例门禁，在 sop.json 里把门禁的 phase 改成已声明的阶段（或补声明该阶段），重新 peaks sop lint 直到 ok:true，不直接 register 未通过 lint 的 SOP。"
+  },
+  {
+    "id": 3,
+    "prompt": "这个发布 SOP 真的能在测试没过时把我拦住吗？我想先确认再用。",
+    "expected": "peaks-sop 用 peaks sop check 在好/坏两种状态下验证门禁返回 pass/fail，再用 peaks sop advance --to ship --dry-run 干跑确认门禁未通过时阻断推进且不落盘，向用户展示阻断行为后再交付。"
+  }
+]

package/dist/cli/commands/agent-commands.d.ts

@@ -1,20 +0,0 @@
-/**
- * peaks agent * CLI surface — Slice: ECC 64 agents soft-optional
- * integration (per spec §7.2 line 818).
- *
- * Registers the new `peaks agent` top-level command with two
- * subcommands:
- *   - `peaks agent run <name> [--target <path>]`  — shell out to
- *     `npx ecc agent run <name> --target <path> --json` when ECC
- *     is installed; soft-fail with the 4-option install prompt
- *     when it isn't.
- *   - `peaks agent list`                          — emit the 12
- *     canonical ECC agents (the wrapper hardcodes the
- *     most-used subset; the full 64-agent list is
- *     discoverable at runtime via `npx ecc agent list`).
- *
- * The wrapper service is `src/services/agent/ecc-agent-service.ts`.
- */
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerAgentCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/agent-commands.js

@@ -1,48 +0,0 @@
-import { runEccAgent, validateEccAgent, CANONICAL_ECC_AGENTS, } from '../../services/agent/ecc-agent-service.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
-export function registerAgentCommands(program, io) {
-    const agent = program
-        .command('agent')
-        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-loop shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-loop diagnostics still run via `peaks doctor scan`.');
-    addJsonOption(agent
-        .command('run <name>')
-        .description(`Run an ECC agent by name (e.g. 'security-reviewer', 'code-reviewer'). The canonical subprocess is \`npx ecc agent run <name> --target <path> --json\`.`)
-        .option('--target <path>', 'project root or file to analyze (default: cwd)')
-        .option('--enable', 'enable the ECC subprocess for this call (overrides default-off; soft-fails with the 4-option install prompt when ECC is missing)')).action(async (name, options) => {
-        const validationError = validateEccAgent(name);
-        if (validationError !== null) {
-            printResult(io, fail('agent.run', 'INVALID_AGENT_NAME', validationError, { agent: name }, [
-                'Use `peaks agent list` to see the canonical 12 agents',
-            ]), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        const projectRoot = options.target ?? process.cwd();
-        try {
-            const result = runEccAgent({
-                agent: name,
-                projectRoot,
-                enableAgent: options.enable === true,
-            });
-            const data = { ...result, projectRoot };
-            const nextActions = [];
-            if (result.reason === 'flag-enabled-but-ecc-missing') {
-                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-loop native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §7.2.');
-            }
-            const envelope = ok('agent.run', data, [...result.warnings], nextActions);
-            printResult(io, envelope, options.json);
-        }
-        catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('agent.run', 'AGENT_RUN_FAILED', message, { agent: name, projectRoot, spawned: false }, [message]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(agent
-        .command('list')
-        .description(`List the 12 canonical ECC agents (peaks-loop ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
-        const envelope = ok('agent.list', { agents: CANONICAL_ECC_AGENTS.map((a) => ({ name: a.name, description: a.description })) }, [], ['Run any agent with: `peaks agent run <name> --target <path>`']);
-        printResult(io, envelope, options.json);
-    });
-}

package/dist/cli/commands/classify-classify-commands.d.ts

@@ -1,19 +0,0 @@
-/**
- * peaks classify CLI (Slice L1a + L1b).
- *
- * Subcommands:
- *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
- *     Classify the current diff via the heuristic + return a JSON envelope
- *     with the chosen level, gate set, and audit log.
- *   - peaks classify override --level <level> --reason "<text>" --project <path>
- *     Force a level; writes the override to the audit log.
- *   - peaks classify upgrade --level <level> --reason "<text>" --project <path>
- *     Same as override but explicitly framed as an upgrade (audit log
- *     records the upgrade event separately from override).
- *
- * Downgrade is REFUSED (per spec §4: "peaks classify downgrade" always
- * errors out). LLM may ask; the CLI never grants.
- */
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/classify-classify-commands.js

@@ -1,151 +0,0 @@
-/**
- * peaks classify CLI (Slice L1a + L1b).
- *
- * Subcommands:
- *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
- *     Classify the current diff via the heuristic + return a JSON envelope
- *     with the chosen level, gate set, and audit log.
- *   - peaks classify override --level <level> --reason "<text>" --project <path>
- *     Force a level; writes the override to the audit log.
- *   - peaks classify upgrade --level <level> --reason "<text>" --project <path>
- *     Same as override but explicitly framed as an upgrade (audit log
- *     records the upgrade event separately from override).
- *
- * Downgrade is REFUSED (per spec §4: "peaks classify downgrade" always
- * errors out). LLM may ask; the CLI never grants.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { classifyTask } from '../../services/classify/classify-service.js';
-import { TASK_LEVELS } from '../../services/classify/classify-types.js';
-import { loadPreferences } from '../../services/preferences/preferences-service.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
-const CLASSIFY_AUDIT_FILE = 'classify-audit.jsonl';
-function getSignalsFromGitDiff(projectRoot) {
-    // Use git diff --stat to extract file count + line count. Fall back to
-    // zeros if git is unavailable (e.g. fresh repo with no commits).
-    let stdout;
-    try {
-        const { execFileSync } = require('node:child_process');
-        stdout = execFileSync('git', ['diff', '--shortstat', 'HEAD'], {
-            cwd: projectRoot,
-            stdio: ['ignore', 'pipe', 'ignore'],
-            maxBuffer: 32 * 1024 * 1024,
-        }).toString('utf8');
-    }
-    catch {
-        return { filesChanged: 0, linesChanged: 0, touchesDependencies: false, touchesMigrationScripts: false, isPureRefactor: true, keywords: [] };
-    }
-    const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
-    const filesChanged = lines.length;
-    let added = 0;
-    let removed = 0;
-    let touchesDependencies = false;
-    let touchesMigrationScripts = false;
-    for (const line of lines) {
-        const match = /(\d+)\s+insertion.*?(\d+)\s+deletion/.exec(line);
-        if (match) {
-            added += Number(match[1]);
-            removed += Number(match[2]);
-        }
-        if (/(package\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|go\.mod)/.test(line)) {
-            touchesDependencies = true;
-        }
-        if (/(migrate|codemod|backfill|schema)/.test(line)) {
-            touchesMigrationScripts = true;
-        }
-    }
-    // isPureRefactor: heuristic — if added lines / removed lines < 0.1 OR
-    // no new exports were added, treat as refactor. For L2.2 the signal is
-    // binary (true/false). Default: true (no behavior change is the safe
-    // assumption; flip to false when keyword 'add' / 'new' / 'feature' present).
-    const isPureRefactor = true;
-    return {
-        filesChanged,
-        linesChanged: added + removed,
-        touchesDependencies,
-        touchesMigrationScripts,
-        isPureRefactor,
-        keywords: [],
-    };
-}
-function appendAuditEntry(projectRoot, entry) {
-    const auditDir = join(projectRoot, '.peaks/_runtime');
-    if (!existsSync(auditDir)) {
-        try {
-            mkdirSync(auditDir, { recursive: true });
-        }
-        catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-    }
-    const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
-    let body = '';
-    try {
-        if (existsSync(auditPath)) {
-            body = readFileSync(auditPath, 'utf8');
-        }
-    }
-    catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-    body += JSON.stringify(entry) + '\n';
-    try {
-        writeFileSync(auditPath, body);
-    }
-    catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-}
-function isTaskLevel(value) {
-    return TASK_LEVELS.includes(value);
-}
-export function registerClassifyCommands(program, io) {
-    const classify = program
-        .command('classify')
-        .description('L1a task classification: 5-level heuristic (typo/bug/feature/refactor/migration) + override/upgrade + audit log');
-    addJsonOption(classify
-        .command('run')
-        .description('Classify the current diff (git diff HEAD) into one of 5 task levels')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--override <level>', 'force a level (one of typo|bug|feature|refactor|migration); requires --reason')
-        .option('--reason <text>', 'reason for the override (mandatory when --override is set)')).action(async (options) => {
-        try {
-            const prefs = await loadPreferences(options.project);
-            const signals = getSignalsFromGitDiff(options.project);
-            let override;
-            if (options.override !== undefined) {
-                if (!isTaskLevel(options.override)) {
-                    printResult(io, fail('classify.run', 'INVALID_LEVEL', `level must be one of: ${TASK_LEVELS.join(', ')}`, { provided: options.override }, ['Pass one of typo, bug, feature, refactor, migration']), options.json);
-                    process.exitCode = 1;
-                    return;
-                }
-                if (options.reason === undefined || options.reason.length === 0) {
-                    printResult(io, fail('classify.run', 'REASON_REQUIRED', '--reason is required when --override is set', {}, ['Provide a non-empty reason for the override']), options.json);
-                    process.exitCode = 1;
-                    return;
-                }
-                override = { level: options.override, reason: options.reason };
-            }
-            const result = classifyTask(override !== undefined
-                ? { signals, conservatism: prefs.classifyConservatism, override }
-                : { signals, conservatism: prefs.classifyConservatism }, prefs.classifyRules.feature_threshold_files, prefs.classifyRules.feature_threshold_lines);
-            appendAuditEntry(options.project, result.audit);
-            printResult(io, ok('classify.run', result, [], [
-                `gate set for level "${result.level}": ${result.gateSet.stages.join(', ')}`,
-                `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`,
-            ]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('classify.run', 'CLASSIFY_RUN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Run peaks classify --help for usage']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // Downgrade is REFUSED per spec §4. Surface this as a hard fail.
-    classify
-        .command('downgrade')
-        .description('REFUSED per spec §4 — peaks-loop never downgrades a classification; ask the user to override explicitly')
-        .requiredOption('--level <level>', 'attempted level')
-        .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--json', 'print machine-readable JSON envelope')
-        .action(async (options) => {
-        printResult(io, fail('classify.downgrade', 'DOWNGRADE_REFUSED', 'peaks classify downgrade is refused per spec §4. Use --override (with reason) on `classify run` to force a level; the CLI never downgrades a classification unilaterally.', { attemptedLevel: options.level, reason: options.reason }, ['Use `peaks classify run --override <level> --reason "<text>"` instead']), options.json);
-        process.exitCode = 2;
-    });
-}

package/dist/cli/commands/contract-commands.d.ts

@@ -1,26 +0,0 @@
-/**
- * `peaks contract` CLI commands — 2.7.0 slice-dag-dispatcher MVP
- * (slice 1.2.c — LLM-side contract writer).
- *
- * Round-2 fix #5 (upgrade placeholder prompt) tells the LLM-side
- * runner to execute `peaks contract write --project <root> ...` to
- * persist its slice's public surface so the orchestrator can splice
- * the contract into downstream dispatch prompts via
- * `formatContractInjection`. This file is the actual implementation
- * of that command — without it, the round-2 prompt would direct the
- * LLM to a CLI that doesn't exist (the round-5 audit caught this).
- *
- * The command is a thin wrapper over `writeContract` from
- * `src/services/dispatch/contract-store.ts`; it accepts the same
- * shape, splits the comma-separated `--exports` / `--types` /
- * `--signatures` flag values into arrays, and surfaces the result
- * via the standard `ok` / `fail` envelope used across peaks-loop.
- *
- * Skill-first / CLI-auxiliary red line: users do not invoke this
- * directly. The peaks-code / peaks-rd LLM-side runner (the
- * IDE-resident sub-agent that finished a slice) calls this command
- * after the slice completes.
- */
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerContractCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/contract-commands.js

@@ -1,114 +0,0 @@
-import { fail, ok, getErrorMessage } from '../../shared/result.js';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { writeContract } from '../../services/dispatch/contract-store.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-const INPUT_LIMIT_BYTES = 256 * 1024;
-/** Split a comma-separated flag value into a trimmed string array. */
-function splitCsv(value) {
-    if (value === undefined)
-        return [];
-    return value
-        .split(',')
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-}
-export function registerContractCommands(program, io) {
-    const contract = program
-        .command('contract')
-        .description('Slice contract store (skill-first / CLI-auxiliary). These commands ' +
-        'are primitives that peaks-code / peaks-rd SKILL.md compose. The LLM-side ' +
-        'runner (the IDE-resident sub-agent that finished a slice) calls ' +
-        '`peaks contract write` to persist the slice\'s public surface; the ' +
-        'orchestrator picks it up on the next dispatch run via listContracts() ' +
-        'and splices it into downstream prompts via formatContractInjection().');
-    // ─────────────────────────────────────────────────────────────────
-    // peaks contract write --project <root> --session-id <sid>
-    //   --slice-id <id> --exports <a,b> --types <x,y> --signatures <s1,s2>
-    //   [--broadcast-to <b1,b2>] [--completed-at <iso>]
-    // ─────────────────────────────────────────────────────────────────
-    addJsonOption(contract
-        .command('write')
-        .description('2.7.0 slice-dag-dispatcher MVP: persist a finished slice\'s public ' +
-        'surface (exports / types / publicSignatures) to disk at ' +
-        '.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json. ' +
-        'The orchestrator picks it up on the next dispatch run. Idempotent: ' +
-        're-running with the same inputs overwrites in place; the SHA-256 ' +
-        'contractHash is content-derived so a contract write from a different ' +
-        'runner (re-execution) is detected as a content change.')
-        .option('--project <path>', 'target project root (defaults to cwd)')
-        .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
-        .requiredOption('--slice-id <id>', 'slice id; must be non-empty; used as the contract filename basename')
-        .option('--exports <list>', 'comma-separated public export names (e.g. "validateDag,topologicalLevels")')
-        .option('--types <list>', 'comma-separated public type names (e.g. "SliceDag,SliceNode")')
-        .option('--signatures <list>', 'comma-separated public function/method signatures (e.g. "validateDag(dag: SliceDag): void")')
-        .option('--broadcast-to <list>', 'comma-separated downstream slice ids that should auto-inherit this contract (e.g. "B,C,D")')
-        .option('--completed-at <iso>', 'ISO 8601 timestamp; defaults to now()')).action((options) => {
-        const asJson = options.json === true;
-        const projectRoot = options.project ?? process.cwd();
-        // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
-        const sid = options.sessionId
-            ?? process.env.PEAKS_SESSION_ID
-            ?? getCurrentSessionId(projectRoot)
-            ?? 'unknown-sid';
-        const sliceId = options.sliceId;
-        if (sliceId === undefined || sliceId.length === 0) {
-            printResult(io, fail('contract.write', 'MISSING_SLICE_ID', '--slice-id is required', { path: null, contract: null }, [
-                'Re-run with --slice-id <id> (must be non-empty; used as the contract filename basename).'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        const exports = splitCsv(options.exports);
-        const types = splitCsv(options.types);
-        const signatures = splitCsv(options.signatures);
-        const broadcastTo = splitCsv(options.broadcastTo);
-        // Cap the combined input to protect the file IO from runaway values
-        // (e.g. a 10MB comma-separated --signatures flag).
-        const inputSize = sliceId.length +
-            sid.length +
-            exports.join(',').length +
-            types.join(',').length +
-            signatures.join(',').length +
-            broadcastTo.join(',').length +
-            (options.completedAt?.length ?? 0);
-        if (inputSize > INPUT_LIMIT_BYTES) {
-            printResult(io, fail('contract.write', 'INPUT_TOO_LARGE', `combined input size ${inputSize} bytes exceeds ${INPUT_LIMIT_BYTES} (likely oversized --exports/--types/--signatures lists)`, { path: null, contract: null }, [
-                'Split the slice into smaller surfaces or omit optional fields.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const input = {
-                sliceId,
-                sessionId: sid,
-                exports,
-                types,
-                publicSignatures: signatures,
-                ...(broadcastTo.length > 0 ? { broadcastTo } : {}),
-                ...(options.completedAt !== undefined ? { completedAt: options.completedAt } : {})
-            };
-            const result = writeContract(projectRoot, sid, input);
-            printResult(io, ok('contract.write', {
-                path: result.path,
-                contractHash: result.contract.contractHash,
-                sliceId: result.contract.sliceId,
-                sessionId: result.contract.sessionId,
-                completedAt: result.contract.completedAt,
-                exportCount: result.contract.exports.length,
-                typeCount: result.contract.types.length,
-                signatureCount: result.contract.publicSignatures.length,
-                broadcastTo: result.contract.broadcastTo ?? []
-            }, [], [
-                `Contract written; orchestrator will pick it up on the next \`peaks sub-agent dispatch --from-dag\` run.`,
-                `Re-running with the same inputs is idempotent (overwrites in place).`
-            ]), asJson);
-        }
-        catch (err) {
-            printResult(io, fail('contract.write', 'WRITE_ERROR', getErrorMessage(err), { path: null, contract: null }, [
-                'See error message; check that --project is a writable directory and --slice-id is a valid filename basename (no path separators).'
-            ]), asJson);
-            process.exitCode = 1;
-        }
-    });
-}