peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/dist/services/ide/adapters/zcode-adapter.js

@@ -0,0 +1,220 @@
+/**
+ * z-code IDE adapter (slice 2026-07-09-add-zcode-adapter) — peaks-loop 的第九个
+ * 内置 IDE 适配器。
+ *
+ * z-code 是一个 VS Code-style 的 Anthropic-compatible 桌面应用:
+ *   - 不是 CLI,没有 `zcode` binary (`which zcode` 返回空)。
+ *   - 桌面应用内置了 "导入 skills" 功能,user 手动触发后将本地 skills 目录
+ *     与 `~/.zcode/skills` 双向同步 (实测 symlink)。
+ *   - hook 协议、project-dir env var、compact command 均未公开。
+ *
+ * 设计前提 (RD-3 §2.2 D1 决策 + 现场实测,见
+ * `.peaks/memory/2026-07-09-zcode-context-probe-handoff.md` §2):
+ *   - `compact` 字段全部 undefined — 走 `llm-self-compress` fallback 路径。
+ *   - `envVar` / `hookEvent` / `toolMatcher` 全部标注 UNVERIFIED,因为
+ *     z-code 文档未公开,本 adapter 用 Anthropic-compatible 协议的合理
+ *     假设占位。
+ *   - `subAgentDispatcher` 用 `nullSubAgentDispatcher` 占位 — z-code
+ *     桌面应用没有公开的 Task 工具 dispatch 协议。
+ *   - `standardsProfile` 字段指向宪法文件根 + rules 目录 — z-code 的设计
+ *     就是借用上游 "import skills" 目标目录,因此保留上游路径常量。
+ *   - `skillInstall` 指向 `~/.zcode/skills` — 实测 z-code 已通过 user
+ *     手动导入同步到这里。
+ *   - 注:`standardsProfile` 中的常量子段是 z-code 借用的固定路径,属于
+ *     架构事实,不算 vendor verb 泄漏。
+ *
+ * Vendor-neutrality 备注 (SC-3 §5 + RD-3 §2.4):
+ *   本文件允许出现 vendor 字符串 (`zcode` / `ZCODE_PROJECT_DIR` 等),
+ *   **不允许** 出现其他 vendor 字符串 / 模型名。`standardsProfile`
+ *   中的 `CLAUDE.md` / `.claude/rules` 是 z-code 借用的上游路径常量,
+ *   属于架构事实,不算 vendor verb 泄漏。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { nullSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Helper exported for tests + internal use: the default location of the
+ * z-code v2 config file on the host filesystem.
+ */
+export function defaultZcodeConfigPath() {
+    return join(homedir(), '.zcode', 'v2', 'config.json');
+}
+/**
+ * Read the z-code config from `path` (string-typed to keep this
+ * swappable for tests). Synchronous + Node.js `fs` so adapter callers
+ * stay async-only at the public surface (`detectCurrentModel` is
+ * already declared `async`).
+ */
+function readZcodeConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { // TODO(g2): fail-closed JSON parse — undefined is the documented contract for missing/corrupt config
+        return undefined;
+    }
+}
+/**
+ * Resolve the active model id from a parsed z-code config payload
+ * (the `~/.zcode/v2/config.json` root object). Pure / exported for
+ * unit tests so the file-IO seam and the resolution seam are
+ * independently verifiable.
+ *
+ * Resolution order (Slice C §"z-code config 解析路径"):
+ *   P1. env var `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` (test seam +
+ *       manual pin for the user).
+ *   P2. The provider whose top-level UUID key is NOT prefixed
+ *       `builtin:` — this matches the user-installed provider
+ *       pattern. Within that provider, prefer its `models` first
+ *       key (insertion order — z-code writes the active model
+ *       first in the picker).
+ *   P3. The first provider with `enabled: true`.
+ *   P4. The first provider in the object (insertion order) — last
+ *       resort. Returns undefined if there are zero providers.
+ *
+ * Returns `undefined` when nothing matches.
+ */
+export function resolveZcodeCurrentModel(config, envOverride) {
+    const providers = config?.provider;
+    if (!providers || typeof providers !== 'object')
+        return undefined;
+    // P1: env var override (vendor-neutral identifier: the provider UUID).
+    if (envOverride !== undefined && envOverride !== '') {
+        const target = providers[envOverride];
+        if (target && typeof target === 'object') {
+            const modelId = pickFirstModelId(target);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P2: prefer a non-builtin provider (the user-installed one).
+    for (const [uuid, entry] of Object.entries(providers)) {
+        if (uuid.startsWith('builtin:'))
+            continue;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    // P3: first enabled provider (legacy / fresh-install case).
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const enabled = entry.enabled;
+        if (enabled === true) {
+            const modelId = pickFirstModelId(entry);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P4: first provider at all.
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    return undefined;
+}
+function pickFirstModelId(provider) {
+    const models = provider.models;
+    if (!models || typeof models !== 'object')
+        return undefined;
+    for (const key of Object.keys(models)) {
+        if (typeof key === 'string' && key.trim().length > 0)
+            return key.trim();
+    }
+    return undefined;
+}
+/**
+ * The async adapter method that `detectCurrentIdeModel()` calls.
+ *
+ * Resolution order:
+ *   1. `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` env var override (test seam
+ *      + manual pin).
+ *   2. `PEAKS_ZCODE_CONFIG_PATH` env var override (test seam for a
+ *      fixture file). Falls back to `~/.zcode/v2/config.json`.
+ *   3. Returns `undefined` when the file is missing / malformed
+ *      (consistent with the cross-IDE contract).
+ */
+export async function detectZcodeCurrentModel() {
+    const overridePath = process.env.PEAKS_ZCODE_CONFIG_PATH;
+    const path = overridePath && overridePath.length > 0 ? overridePath : defaultZcodeConfigPath();
+    const config = readZcodeConfig(path);
+    if (config === undefined)
+        return undefined;
+    return resolveZcodeCurrentModel(config, process.env.PEAKS_ZCODE_ACTIVE_PROVIDER_UUID);
+}
+export const ZCODE_ADAPTER = {
+    id: 'zcode',
+    displayName: 'z-code',
+    settings: {
+        dirName: '.zcode', // VERIFIED — 实测 z-code 项目根目录是 `.zcode`
+        settingsFileName: 'settings.json',
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.zcode', 'settings.json');
+        },
+        supportsScope: (scope) => scope === 'project' || scope === 'global',
+    },
+    // UNVERIFIED — z-code 桌面应用未公开 `ZCODE_PROJECT_DIR` env var,这里
+    // 用占位符,RD 阶段假设 z-code 借用了 Anthropic-compatible 协议并可能
+    // 注入一个项目根 env 变量。若未注入,峰 router 会回退到 cwd 探测。
+    envVar: 'ZCODE_PROJECT_DIR',
+    // UNVERIFIED — z-code 未公开 hook event key,占位用 Anthropic-compatible
+    // 协议的常见命名 `PreToolUse`。若 z-code 用其他 key,peaks hooks install
+    // 钩子在此 IDE 上不生效,可由 user 通过手动导入绕过。
+    hookEvent: 'PreToolUse',
+    // UNVERIFIED — 同上,占位用 `Bash` matcher。
+    toolMatcher: 'Bash',
+    // Slice 2026-07-09: z-code 桌面应用没有公开 Task 工具 dispatch 协议,
+    // 用 `nullSubAgentDispatcher` 占位 — peaks sub-agent dispatch CLI 在
+    // z-code 上返回 SubAgentNotSupportedError,符合 slice #008 P-5 capability
+    // 检查契约 (CLI 不崩溃)。
+    subAgentDispatcher: nullSubAgentDispatcher,
+    // Slice #010 G9: 假设 z-code 支持 PreToolUse (UNVERIFIED)。Opt-in,等真实
+    // z-code 安装 dogfood 后再决定。若 z-code 不支持 G9 hook,CLI 兜底层仍会
+    // 强制执行 G9 阈值。
+    promptSizeAware: true,
+    installHints: [
+        'z-code 没有 CLI,因此无需重启 — skills symlink 已写入 ~/.zcode/skills/。',
+        '若 z-code 未自动加载 peaks-* skills,在 z-code 桌面应用里手动触发 "导入 skills" 功能即可。',
+    ],
+    capabilities: {
+        gateEnforce: true,
+        statusline: true,
+    },
+    // Standards profile: 路径常量保留 (z-code 的 "导入 skills" 功能
+    // 借用了上游 settings 目录,因此宪法文件路径常量同步保留)。
+    standardsProfile: {
+        rootFile: 'CLAUDE.md',
+        rulesDir: '.claude/rules',
+        rulesFileGlob: '**/*.md',
+        autoLoaded: true,
+        format: 'markdown',
+        migrationHint: 'z-code 借用了上游 standards 路径,无需迁移。',
+    },
+    // Skill install profile: 指向 `~/.zcode/skills` 系列 (实测 z-code 已通过
+    // user 手动 symlink 同步;peaks-loop 也直接支持)。
+    skillInstall: {
+        skillsDir: join(homedir(), '.zcode', 'skills'),
+        outputStylesDir: join(homedir(), '.zcode', 'output-styles'),
+        installStrategy: 'symlink',
+        envVarOverride: 'PEAKS_ZCODE_SKILLS_DIR',
+    },
+    // compact profile 留空 — z-code 没有 CLI binary (RD-3 §2.2 D1 决策)。
+    // peaks-loop 走 `llm-self-compress` fallback 路径 (LLM 自己总结 context),
+    // 不抛错、不警告 (符合 slice #008 P-5 capability-check contract)。
+    // Slice C (2026-07-09 add-zcode-adapter, C.2): runtime probe for
+    // the currently-active model id. Reads `~/.zcode/v2/config.json`
+    // and resolves the active provider via `resolveZcodeCurrentModel`.
+    // See `.peaks/_runtime/2026-07-08-session-17918f/qa/.../slice-C-completion.md`
+    // for the resolution priority chain (env override → non-builtin
+    // provider → first enabled → first provider). Returns undefined
+    // on any failure (consistent with the cross-IDE contract).
+    detectCurrentModel: detectZcodeCurrentModel,
+};

package/dist/services/ide/current-model-detector.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export declare function detectCurrentIdeModel(): Promise<string | undefined>;

package/dist/services/ide/current-model-detector.js

@@ -0,0 +1,60 @@
+/**
+ * Runtime current-model detector (Slice 2026-07-09 add-zcode-adapter, Slice C).
+ *
+ * Walks the registered IDE adapter chain and asks the IDE adapter
+ * (when it opts in via `IdeAdapter.detectCurrentModel?`) to report the
+ * currently-active model id. This is the runtime sibling of
+ * `getStrongestModelId(config)` in `src/services/config/model-routing.ts`:
+ *
+ *   - `getStrongestModelId(config)` reads `config.model` (user-set) and
+ *     falls back to the env-var / `'claude-opus-4-7'` constant. Sync.
+ *   - `detectCurrentIdeModel()` reads the IDE's runtime state (which
+ *     provider UI is active, which model the picker shows). Async.
+ *
+ * The CLI surface `peaks ide model --current` (added in this slice)
+ * delegates here. The future async resolver at
+ * `getStrongestModelIdAsync` (Slice C §C.4) calls this so config-less
+ * runs (e.g. an LLM inside z-code) can derive the strongest model from
+ * its actual environment.
+ *
+ * Vendor-neutrality notes (SC-3 §5 + RD-3 §2.4):
+ *   - This file never names a vendor (no "claude", "zcode", etc.).
+ *   - It only walks `IdeAdapter.detectCurrentModel?` — any adapter
+ *     can opt in.
+ *   - It returns `undefined` when detection is unavailable; callers
+ *     must fall back to the configured / hardcoded model.
+ */
+import { getAdapter } from './ide-registry.js';
+import { listAdapterIds } from './ide-registry.js';
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export async function detectCurrentIdeModel() {
+    for (const id of listAdapterIds()) {
+        const adapter = getAdapter(id);
+        if (typeof adapter.detectCurrentModel !== 'function')
+            continue;
+        try {
+            const modelId = await adapter.detectCurrentModel();
+            if (typeof modelId === 'string' && modelId.trim().length > 0) {
+                return modelId.trim();
+            }
+        }
+        catch { // TODO(g2): Per-SC §3.4 best-effort — a misconfigured adapter must not poison the chain
+            // Per-SC §3.4: detection is best-effort. Swallow errors so a
+            // misconfigured adapter cannot poison the chain; the next
+            // adapter still gets a chance.
+        }
+    }
+    return undefined;
+}

package/dist/services/ide/ide-registry.js

@@ -0,0 +1,63 @@
+import { CLAUDE_CODE_ADAPTER } from './adapters/claude-code-adapter.js';
+import { TRAE_ADAPTER } from './adapters/trae-adapter.js';
+import { CURSOR_ADAPTER } from './adapters/cursor-adapter.js';
+import { CODEX_ADAPTER } from './adapters/codex-adapter.js';
+import { HERMES_ADAPTER } from './adapters/hermes-adapter.js';
+import { OPENCLAW_ADAPTER } from './adapters/openclaw-adapter.js';
+import { ZCODE_ADAPTER } from './adapters/zcode-adapter.js';
+/**
+ * Built-in IDE adapter registry。Map<IdeId, IdeAdapter> 是单一来源。
+ *
+ * Slice #1 注册 claude-code。
+ * Slice #2 注册 trae —— 这是 slice #1 抽出的 IdeAdapter 形状的
+ * 第一个真实客户,验证"填表"承诺。
+ * 后续 slice 注入 codex / cursor / qoder / tongyi-lingma 时,只需在此
+ * Map 加条目 —— 所有 adapter 使用方(hook-translator、hooks install、statusline
+ * install、mcp apply)通过 `getAdapter(ide)` 拿取,无需修改。
+ * Slice #0.7 注入 hermes + openclaw。
+ * Slice #12 (2.4.0) 注册 cursor。
+ * Slice #13 (2.4.0) 注册 codex。
+ */
+const ADAPTERS = new Map([
+    ['claude-code', CLAUDE_CODE_ADAPTER],
+    ['trae', TRAE_ADAPTER],
+    ['cursor', CURSOR_ADAPTER],
+    ['codex', CODEX_ADAPTER],
+    ['hermes', HERMES_ADAPTER],
+    ['openclaw', OPENCLAW_ADAPTER],
+    ['zcode', ZCODE_ADAPTER],
+]);
+/** Get the adapter for a given IDE id. Throws on unsupported IDE. */
+export function getAdapter(ide) {
+    const adapter = ADAPTERS.get(ide);
+    if (!adapter) {
+        throw new Error(`Unsupported IDE: ${ide}. Registered: ${listAdapterIds().join(', ') || '(none)'}`);
+    }
+    return adapter;
+}
+/** All registered adapter ids (insertion order). */
+export function listAdapterIds() {
+    return Array.from(ADAPTERS.keys());
+}
+/** All registered adapters (insertion order). */
+export function listAdapters() {
+    return Array.from(ADAPTERS.values());
+}
+/**
+ * Test seam: register or replace an adapter. Used by future slices when adding
+ * a new IDE. Caller is responsible for ensuring the adapter is well-formed.
+ */
+export function _setAdapterForTesting(ide, adapter) {
+    ADAPTERS.set(ide, adapter);
+}
+/** Test seam: reset to built-in defaults. */
+export function _resetAdaptersForTesting() {
+    ADAPTERS.clear();
+    ADAPTERS.set('claude-code', CLAUDE_CODE_ADAPTER);
+    ADAPTERS.set('trae', TRAE_ADAPTER);
+    ADAPTERS.set('cursor', CURSOR_ADAPTER);
+    ADAPTERS.set('codex', CODEX_ADAPTER);
+    ADAPTERS.set('hermes', HERMES_ADAPTER);
+    ADAPTERS.set('openclaw', OPENCLAW_ADAPTER);
+    ADAPTERS.set('zcode', ZCODE_ADAPTER);
+}

package/dist/services/ide/ide-types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * peaks 自有 hook 协议 + slim IDE adapter 接口。
+ *
+ * peaks-loop 不再适配 IDE 私有的 hook 协议;反之 peaks 定义自己的 canonical
+ * schema,每个 IDE 只需要填 4 字符串 + 1 settings 函数,新 IDE 适配变成"填表"。
+ *
+ * 不可消除的 per-IDE 字段(诚实交代,见 PRD R-1..R-4):
+ *   - settings.json 物理位置
+ *   - 项目根 env 变量名
+ *   - hook 事件名 + matcher 名
+ *
+ * 其他全部归一化到 peaks 内部模型(见 hook-protocol.ts)。
+ */
+import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
+export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw' | 'zcode';
+export interface IdeCapabilities {
+    /** peaks gate enforce 是否适用该 IDE(必备) */
+    readonly gateEnforce: true;
+    /** peaks statusline 状态栏是否适用 */
+    readonly statusline: boolean;
+}
+export interface IdeSettingsLocation {
+    /** 项目根下的 settings 目录名,例如 '.claude' / '.trae' / '.cursor' */
+    readonly dirName: string;
+    /** settings 文件名(部分 IDE 叫 settings.json / mcp.json) */
+    readonly settingsFileName: string;
+    /** 解析出 settings.json 绝对路径 */
+    resolveSettingsFile(scope: 'project' | 'global', projectRoot: string | undefined): string;
+    /** 该 IDE 是否支持此 scope(用于清晰报错) */
+    supportsScope(scope: 'project' | 'global'): boolean;
+}
+/**
+ * Slim IDE adapter 描述。每 IDE 一个静态常量(无需 DI)。
+ * 字段故意保持少:让 adapter 的添加是"填表"而非"重写"。
+ */
+export interface IdeAdapter {
+    readonly id: IdeId;
+    /** 人类可读名,出现在 CLI help / 命令输出 */
+    readonly displayName: string;
+    readonly settings: IdeSettingsLocation;
+    /** IDE 注入的项目根 env 变量名;`peaks gate enforce` 等命令模板会引用此 env */
+    readonly envVar: string;
+    /** settings.json 里 hook 数组的 key,例如 'PreToolUse' / 'beforeToolCall' */
+    readonly hookEvent: string;
+    /** hook 数组元素的 matcher 字段(工具名匹配),例如 'Bash' / 'Task' / 'terminal' */
+    readonly toolMatcher: string;
+    /**
+     * Per-IDE sub-agent dispatcher. The `peaks sub-agent dispatch` CLI reads
+     * this field, calls `supportsRole` + `buildToolCall`, and returns the
+     * resulting tool-call descriptor in the JSON envelope. Encapsulates the per-IDE sub-agent dispatch surface (slice #009). The dispatcher's `buildToolCall` returns the IDE-native tool-call descriptor at runtime.
+     *
+     * Added in slice 2026-06-07-sub-agent-dispatch-decouple. See PRD #002
+     * G1 (AC-1, AC-2) + [[slim-ideadapter-shape-is-the-contract]].
+     */
+    readonly subAgentDispatcher: SubAgentDispatcher;
+    /**
+     * Per-IDE opt-in to the G9 prompt-size gate. When `true`, the
+     * `peaks hooks install` command registers the G9 PreToolUse hook
+     * (`peaks sub-agent-dispatch-guard`) for this IDE. When `false`,
+     * the hook is NOT installed (the IDE either doesn't support the
+     * PreToolUse event in a useful form, or the user has opted out).
+     *
+     * The CLI 兜底 layer in `peaks sub-agent dispatch` still enforces
+     * the threshold regardless of this field — `promptSizeAware` only
+     * controls the hook layer (R-15: G9 hook is LLM-platform-specific).
+     *
+     * Added in slice 2026-06-07-sub-agent-context-governance. See PRD
+     * #003 G9.2 + AC-56. Default `false` to preserve slice #009's
+     * `peaks hooks install` output byte-stability.
+     */
+    readonly promptSizeAware: boolean;
+    /** install / uninstall 后展示给用户的提示文本(各 IDE 不同,例如 Claude 提示重启窗口) */
+    readonly installHints: readonly string[];
+    /** 该 IDE 在 peaks 上可启用的能力(用于在不支持的 IDE 上软警告) */
+    readonly capabilities: IdeCapabilities;
+    /**
+     * Where this IDE reads its project-level agent instructions from.
+     * When undefined, the postinstall + `peaks standards init` codepath falls
+     * back to the legacy Claude Code path (CLAUDE.md + .claude/rules/**)
+     * AND emits a stderr warning. Adapters in slice 1.3.2 declare this
+     * value (Claude Code), are annotated UNVERIFIED for future slices
+     * (Trae, slice #012+), or omit it entirely (not-yet-registered IDEs).
+     *
+     * Added in slice 011-2026-06-07-ide-adapter-resource-profile.
+     */
+    readonly standardsProfile?: IdeStandardsProfile;
+    /**
+     * Where `scripts/install-skills.mjs` symlinks the bundled skills +
+     * output styles. When undefined, the postinstall falls back to
+     * `~/.claude/skills` + `~/.claude/output-styles` (legacy) AND emits
+     * a stderr warning. Adapters that opt into the dispatch layer fill
+     * this; adapters that don't (Trae in slice 1.3.2) leave it undefined
+     * and follow the legacy path with a warning.
+     *
+     * Added in slice 011-2026-06-07-ide-adapter-resource-profile.
+     */
+    readonly skillInstall?: IdeSkillInstall;
+    /**
+     * v2.13.0 auto-compact (AC-1 + AC-3): per-IDE compact-capability
+     * descriptor. When `undefined`, peaks-loop falls back to the
+     * `llm-self-compress` pathway (the LLM summarizes its own context).
+     * Adapters that fill this expose a 4-stage protocol so peaks-loop
+     * can drive compact autonomously:
+     *
+     *   1. `envVarForContextPercent` — env-var the IDE sets per turn
+     *      (e.g. `CLAUDE_CONTEXT_USAGE_PERCENT`). Read by AC-1.
+     *   2. `compactCommand` — slash command or shell-call the IDE
+     *      accepts to trigger compact (e.g. `/compact`). Dispatched
+     *      by AC-3.
+     *   3. `compactPathway` — `'shell-exec' | 'ide-native' |
+     *      'llm-self-compress' | 'noop'`. `shell-exec` means peaks-loop
+     *      spawns `compactCommand` via `child_process.spawn` (zero IDE
+     *      hook required). `ide-native` means the IDE exposes a hook
+     *      surface peaks-loop can write to. `llm-self-compress` is the
+     *      fallback when no compact capability is registered.
+     *   4. `postCompactDetectCommand` (optional) — command the LLM
+     *      runner can invoke after compact to confirm ratio dropped.
+     *
+     * Claude Code is the MVP implementation; trae / codex / cursor /
+     * qoder / tongyi-lingma / hermes / openclaw ship with
+     * `compactPathway: 'llm-self-compress'` until L2-dogfood verifies
+     * each IDE's actual compact surface.
+     *
+     * Added in slice 2026-06-27-auto-compact-protocol. See
+     * `.peaks/memory/2026-06-27-auto-compact-design.md`.
+     */
+    readonly compact?: IdeCompactProfile;
+    /**
+     * Optional runtime probe for the IDE's currently-active model id.
+     * When defined, `detectCurrentIdeModel()` in
+     * `src/services/ide/current-model-detector.ts` calls this to
+     * discover which model the IDE UI is currently configured for —
+     * e.g. so `peaks ide model --current` and the future
+     * `getStrongestModelIdAsync()` can use the same value without
+     * forcing the user to set `config.model` manually.
+     *
+     * Returning `undefined` (or the method being absent on this
+     * adapter) means "I don't know — fall back to the configured
+     * model / env var / back-compat default".
+     *
+     * Implementations may read local files (`fs.readFileSync`),
+     * env vars, or both. They MUST NOT throw on missing files — catch
+     * locally and return `undefined`. The orchestration layer also
+     * catches, but defense in depth.
+     *
+     * Added in slice 2026-07-09 add-zcode-adapter (Slice C); only the
+     * `zcode` adapter opts in this slice. Future slices can opt in
+     * other IDEs without changing this signature (optional method).
+     */
+    readonly detectCurrentModel?: () => Promise<string | undefined>;
+}
+/**
+ * Per-IDE auto-compact capability descriptor. See `IdeAdapter.compact`
+ * for the protocol contract. The `MvpCompactPathway` string union
+ * keeps the field exhaustive — adding a new pathway requires updating
+ * every adapter that opts in.
+ */
+export interface IdeCompactProfile {
+    /** Env-var name the IDE writes per turn to expose context-fill %. */
+    readonly envVarForContextPercent: string;
+    /**
+     * Slash command or shell-call to invoke compact. The orchestrator
+     * spawns this via `child_process.spawn` (shell-exec pathway) or
+     * writes it to an IDE hook file (ide-native pathway).
+     */
+    readonly compactCommand: string;
+    /**
+     * `shell-exec` — peaks-loop spawns the command via child_process
+     *                (works for any IDE that accepts a slash command
+     *                via a shell-spawnable entry point).
+     * `ide-native` — peaks-loop writes to an IDE-specific hook file;
+     *                used when the IDE requires a registered hook
+     *                rather than a runtime command.
+     * `llm-self-compress` — peaks-loop prompts the LLM to summarize
+     *                its own context (no IDE integration required;
+     *                least precise but always available).
+     * `noop` — peaks-loop records the intent but performs no action;
+     *          used by IDEs that explicitly opt out (e.g. legacy
+     *          adapters still on the v2.11.x model).
+     */
+    readonly compactPathway: 'shell-exec' | 'ide-native' | 'llm-self-compress' | 'noop';
+    /**
+     * Optional command the runner invokes post-compact to confirm
+     * ratio dropped (e.g. `peaks context now --json`). When omitted,
+     * the orchestrator polls `envVarForContextPercent` directly.
+     */
+    readonly postCompactDetectCommand?: string;
+}
+/**
+ * Per-IDE standards-file location + format profile. Used by the
+ * `peaks standards init` dispatch layer (slice 011) to write the
+ * project-level standards files at the IDE-specific path, not the
+ * Claude Code hardcoded one. Adapters that omit this field trigger
+ * the legacy Claude Code path with a stderr warning.
+ */
+export interface IdeStandardsProfile {
+    /** Filename for the project-root constitution (e.g. 'CLAUDE.md'), or null if the IDE has no equivalent. */
+    readonly rootFile: string | null;
+    /** Directory for module-level rules (e.g. '.claude/rules'), or null if the IDE has no equivalent. */
+    readonly rulesDir: string | null;
+    /** Glob under rulesDir to enumerate rule files. */
+    readonly rulesFileGlob: string;
+    /** True if the IDE auto-loads these files at session start. */
+    readonly autoLoaded: boolean;
+    /** Output format. markdown = plain text; markdown+frontmatter = adds YAML frontmatter to each rule file. */
+    readonly format: 'markdown' | 'markdown+frontmatter';
+    /** Human-readable hint surfaced in the fallback warning. */
+    readonly migrationHint?: string;
+}
+/**
+ * Per-IDE postinstall target roots. The `scripts/install-skills.mjs`
+ * script consumes this to symlink the bundled skills + output styles
+ * to the IDE-specific install location, with back-compat for the
+ * legacy `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`
+ * env vars (precedence: explicit option > env var > IDE profile > legacy default).
+ */
+export interface IdeSkillInstall {
+    /** Absolute path under which the postinstall script symlinks the bundled `skills/` directory. */
+    readonly skillsDir: string;
+    /** Absolute path under which the postinstall script writes the bundled `output-styles/`. Null if the IDE has no equivalent. */
+    readonly outputStylesDir: string | null;
+    /** Symlink strategy. */
+    readonly installStrategy: 'symlink' | 'copy';
+    /** Back-compat env var name (e.g. PEAKS_CLAUDE_SKILLS_DIR). Null if no env var is supported. */
+    readonly envVarOverride: string | null;
+}
+/** peaks canonical hook schema 版本标识 */
+export declare const PEAKS_HOOK_SCHEMA: "peaks-hook/v1";
+/** peaks canonical hook 形态 —— 单一协议,所有 IDE 经 hook-translator 归一化到此 */
+export interface PeaksCanonicalHook {
+    readonly schema: typeof PEAKS_HOOK_SCHEMA;
+    readonly event: 'pre-tool-use' | 'post-tool-use' | 'sub-agent-start';
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+    /** 解析自 env 变量或 --project 的项目根 */
+    readonly projectRoot: string;
+    /** 选输出格式 */
+    readonly rawIdeFormat: IdeId;
+    /** 原始 stdin,留作回退 */
+    readonly rawPayload: unknown;
+}
+/** peaks 决策发回形态枚举(按 IDE 期望的"发回"形式) */
+export type PeaksDecisionTransport = {
+    kind: 'stdout-json';
+    denyShape: Record<string, unknown>;
+} | {
+    kind: 'exit-code';
+    denyCode: number;
+} | {
+    kind: 'both';
+    denyShape: Record<string, unknown>;
+    denyCode: number;
+};

package/dist/services/job/job-progress-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { z } from 'zod';
+export declare const JOB_PROGRESS_SCHEMA_VERSION: 1;
+export declare const JobProgressSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    jobId: z.ZodString;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+    currentSlice: z.ZodString;
+    lastCommitSha: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}>;
+export type JobProgress = z.infer<typeof JobProgressSchema>;
+export interface WriteProgressInput {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt?: string;
+}
+export declare function writeJobProgress(projectRoot: string, sessionId: string, input: WriteProgressInput): JobProgress;
+export declare function readJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress;
+export declare function tryReadJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress | null;