peaks-cli 1.3.0 → 1.3.2

package/dist/src/shared/change-id.d.ts

@@ -2,6 +2,20 @@
  * Shared change-id validation and artifact path helpers.
  * All Peaks planner commands must use these to prevent path traversal
  * and keep artifacts inside the Peaks artifact workspace.
+ *
+ * Layout (as of slice 2026-06-05-change-id-as-unit-of-work):
+ *   - Reviewable artifacts (rd/, qa/, prd/, txt/, prd/source/):
+ *       .peaks/<change-id>/<role>/...    (tracked in git)
+ *   - Ephemeral state (live sub-agent progress, spawn records):
+ *       .peaks/_runtime/<session-id>/... (gitignored)
+ *   - The active change-id binding lives at `.peaks/_runtime/current-change`
+ *     (symlink pointing at `.peaks/<change-id>/` for one-minor-release back-compat
+ *     also accepts a plain file with the change-id as its sole content).
+ *
+ * The session id remains in use as a binding (which developer's local
+ * working session is active) but it is NOT the durable scope for
+ * reviewable content — change-id is. Sessions are ephemeral and
+ * gitignored; changes are durable and tracked.
  */
 export declare function isValidChangeId(changeId: string): boolean;
 export declare function isUnsafePathInput(input: string): boolean;
@@ -56,3 +70,48 @@ export declare function buildArtifactRelativePathInRoot(projectRoot: string, cha
  */
 export declare function buildArtifactRelativePath(changeId: string, ...segments: string[]): string;
 export declare function isPathInsideArtifactRoot(path: string, artifactRoot: string): boolean;
+/**
+ * Read the active change-id binding for a project. Returns null when
+ * no binding exists or the binding is malformed / escapes the project
+ * root. As of slice 2026-06-05-change-id-as-unit-of-work this is the
+ * primary routing key for reviewable artifact writes — RD/QA/PRD
+ * services should call this (rather than guess from the session id)
+ * to decide which `.peaks/<change-id>/` directory to write into.
+ */
+export declare function getCurrentChangeId(projectRoot: string): string | null;
+/**
+ * Source of the resolved change-id binding. Useful for tests that
+ * need to confirm whether the binding came from the canonical
+ * `_runtime/current-change` symlink or the legacy `current-change`
+ * plain-file path.
+ */
+export declare function getCurrentChangeIdSource(projectRoot: string): {
+    changeId: string;
+    source: 'symlink' | 'file';
+} | null;
+/**
+ * Write a change-id binding for a project. Two forms are supported
+ * (the same as `getCurrentChangeId` reads):
+ *
+ *   - `{ form: 'symlink' }` (default): creates
+ *     `.peaks/_runtime/current-change` as a symlink pointing at
+ *     `.peaks/<changeId>/`. Requires the target dir to exist (the
+ *     caller is responsible for `initWorkspace` + the change-id dir).
+ *   - `{ form: 'file' }`: writes the change-id as the sole content of
+ *     `.peaks/_runtime/current-change`. The legacy plain-file form.
+ *
+ * Idempotent: re-running with the same changeId + form is a no-op.
+ * Re-running with a different changeId on an existing symlink throws —
+ * the caller must remove the binding first (or use a different path).
+ */
+export declare function setCurrentChangeId(projectRoot: string, changeId: string, options?: {
+    form?: 'symlink' | 'file';
+}): void;
+/**
+ * Canonical on-disk path to a change-id's reviewable artifacts
+ * (`.peaks/<change-id>/`). Writes that target reviewable content
+ * (RD/QA/PRD/txt) should land here regardless of which session
+ * is active. Ephemeral state (live sub-agent progress, spawn records)
+ * stays in the session dir (`.peaks/_runtime/<session-id>/...`).
+ */
+export declare function getChangeArtifactRoot(projectRoot: string, changeId: string): string;

package/dist/src/shared/change-id.js

@@ -2,11 +2,25 @@
  * Shared change-id validation and artifact path helpers.
  * All Peaks planner commands must use these to prevent path traversal
  * and keep artifacts inside the Peaks artifact workspace.
+ *
+ * Layout (as of slice 2026-06-05-change-id-as-unit-of-work):
+ *   - Reviewable artifacts (rd/, qa/, prd/, txt/, prd/source/):
+ *       .peaks/<change-id>/<role>/...    (tracked in git)
+ *   - Ephemeral state (live sub-agent progress, spawn records):
+ *       .peaks/_runtime/<session-id>/... (gitignored)
+ *   - The active change-id binding lives at `.peaks/_runtime/current-change`
+ *     (symlink pointing at `.peaks/<change-id>/` for one-minor-release back-compat
+ *     also accepts a plain file with the change-id as its sole content).
+ *
+ * The session id remains in use as a binding (which developer's local
+ * working session is active) but it is NOT the durable scope for
+ * reviewable content — change-id is. Sessions are ephemeral and
+ * gitignored; changes are durable and tracked.
  */
-import { posix, join } from 'node:path';
-import { getNextNumber, buildNumberedFilename } from './incrementing-number.js';
-import { getSessionId } from '../services/session/session-manager.js';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { posix, join, basename } from 'node:path';
 import { findProjectRoot } from '../services/config/config-safety.js';
+import { isInsidePath } from './path-utils.js';
 const CHANGE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
 function normalizeForwardSlashes(input) {
     return input.replace(/\\/g, '/');
@@ -86,22 +100,21 @@ export function isUnsafeArtifactPath(path) {
  */
 export function buildArtifactRelativePathInRoot(projectRoot, changeId, ...segments) {
     validateChangeIdOrThrow(changeId);
+    // As of slice 2026-06-05-change-id-as-unit-of-work, reviewable
+    // artifacts (RD/QA/PRD/txt) are routed to the change-id-scoped
+    // directory `.peaks/<change-id>/<segments-joined>`. The session id
+    // is the binding for ephemeral state (live sub-agent progress,
+    // spawn records) only and is NOT part of the reviewable-artifact
+    // path. Pre-1.3.1 trees get their old session-scoped files migrated
+    // to the change-id dir by `peaks workspace reconcile`.
     const resolvedProjectRoot = projectRoot && projectRoot.length > 0
         ? projectRoot
         : (findProjectRoot(process.cwd()) ?? process.cwd());
-    const sessionId = getSessionId(resolvedProjectRoot);
-    if (sessionId && segments.length > 0 && segments[0]) {
-        const role = normalizeForwardSlashes(segments[0]);
-        const dirPath = join(resolvedProjectRoot, '.peaks', sessionId, role);
-        if (isUnsafeArtifactPath(role) || isUnsafeArtifactPath(sessionId)) {
-            throw new ChangeIdValidationError(changeId);
-        }
-        const number = getNextNumber(dirPath);
-        const filename = buildNumberedFilename(number, changeId);
-        const candidatePath = `.peaks/${sessionId}/${role}/${filename}`;
-        return normalizeArtifactPath(candidatePath);
-    }
-    // Fallback: no session or no segments - use legacy behavior
+    // Use segments verbatim as the sub-path. This preserves the
+    // legacy behavior where `buildArtifactRelativePath(changeId, 'rd', 'architecture')`
+    // produces `.peaks/<changeId>/rd/architecture` (the caller specifies
+    // the full sub-path, including any custom filename like
+    // `architecture`, `001-foo.md`, `swarm/workers/rd-impl-001`, etc.).
     const joined = segments.map((segment) => normalizeForwardSlashes(segment)).join('/');
     const candidatePath = `.peaks/${changeId}/${joined}`;
     if (isUnsafeArtifactPath(joined) || isUnsafeArtifactPath(candidatePath)) {
@@ -138,3 +151,168 @@ export function isPathInsideArtifactRoot(path, artifactRoot) {
     const normalizedRoot = normalizeArtifactPath(artifactRoot);
     return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
 }
+// ---------------------------------------------------------------------------
+// Change-id binding (.peaks/_runtime/current-change)
+// ---------------------------------------------------------------------------
+//
+// The active change-id binding lives at `.peaks/_runtime/current-change`.
+// Two forms are accepted (back-compat for the legacy file-based binding
+// that pre-dates the runtime-layer refactor):
+//
+//   1. Symlink: the symlink target resolves to `.peaks/<change-id>/`
+//      inside the project root. This is the canonical form that
+//      `peaks workspace init --change-id <id>` writes.
+//
+//   2. Plain file: the file's first non-empty line is the change-id.
+//      Older `peaks workspace init` (pre-1.3.1) wrote the change-id
+//      as a plain file at `.peaks/current-change`. We still read it.
+//
+// In either case the change-id is validated against CHANGE_ID_PATTERN
+// (letters/digits/dots/underscores/dashes, no `..`) and the resolved
+// path must stay inside the project root (defense against a symlink
+// pointing outside).
+//
+// The binding is read by RD/QA/PRD services when they need to know
+// which `.peaks/<change-id>/` directory to write reviewable artifacts
+// into, and by reconciliation to figure out which slice each legacy
+// session file belongs to.
+const CURRENT_CHANGE_REL = '_runtime/current-change';
+const LEGACY_CURRENT_CHANGE_REL = 'current-change';
+const CHANGE_DIR_PATTERN = /^[A-Za-z0-9._-]+$/;
+function safeReadBinding(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    const realPeaks = (() => {
+        try {
+            return realpathSync(peaksRoot);
+        }
+        catch {
+            return peaksRoot;
+        }
+    })();
+    for (const rel of [CURRENT_CHANGE_REL, LEGACY_CURRENT_CHANGE_REL]) {
+        const bindingPath = join(peaksRoot, rel);
+        if (!existsSync(bindingPath))
+            continue;
+        try {
+            const stat = lstatSync(bindingPath);
+            if (stat.isSymbolicLink()) {
+                const targetPath = realpathSync(bindingPath);
+                if (!isInsidePath(targetPath, realPeaks))
+                    return null;
+                const targetId = basename(targetPath);
+                if (!CHANGE_DIR_PATTERN.test(targetId) || targetId === '.' || targetId === '..')
+                    return null;
+                return { changeId: targetId, source: 'symlink' };
+            }
+            const raw = readFileSync(bindingPath, 'utf-8').trim();
+            if (!raw || !CHANGE_DIR_PATTERN.test(raw) || raw === '.' || raw === '..')
+                return null;
+            return { changeId: raw, source: 'file' };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Read the active change-id binding for a project. Returns null when
+ * no binding exists or the binding is malformed / escapes the project
+ * root. As of slice 2026-06-05-change-id-as-unit-of-work this is the
+ * primary routing key for reviewable artifact writes — RD/QA/PRD
+ * services should call this (rather than guess from the session id)
+ * to decide which `.peaks/<change-id>/` directory to write into.
+ */
+export function getCurrentChangeId(projectRoot) {
+    return safeReadBinding(projectRoot)?.changeId ?? null;
+}
+/**
+ * Source of the resolved change-id binding. Useful for tests that
+ * need to confirm whether the binding came from the canonical
+ * `_runtime/current-change` symlink or the legacy `current-change`
+ * plain-file path.
+ */
+export function getCurrentChangeIdSource(projectRoot) {
+    return safeReadBinding(projectRoot);
+}
+/**
+ * Write a change-id binding for a project. Two forms are supported
+ * (the same as `getCurrentChangeId` reads):
+ *
+ *   - `{ form: 'symlink' }` (default): creates
+ *     `.peaks/_runtime/current-change` as a symlink pointing at
+ *     `.peaks/<changeId>/`. Requires the target dir to exist (the
+ *     caller is responsible for `initWorkspace` + the change-id dir).
+ *   - `{ form: 'file' }`: writes the change-id as the sole content of
+ *     `.peaks/_runtime/current-change`. The legacy plain-file form.
+ *
+ * Idempotent: re-running with the same changeId + form is a no-op.
+ * Re-running with a different changeId on an existing symlink throws —
+ * the caller must remove the binding first (or use a different path).
+ */
+export function setCurrentChangeId(projectRoot, changeId, options = {}) {
+    validateChangeIdOrThrow(changeId);
+    const form = options.form ?? 'symlink';
+    const peaksRoot = join(projectRoot, '.peaks');
+    const bindingPath = join(peaksRoot, CURRENT_CHANGE_REL);
+    // Ensure `_runtime/` exists.
+    const runtimeDir = join(peaksRoot, '_runtime');
+    if (!existsSync(runtimeDir)) {
+        // Lazy import: do not pull fs/promises at the top to keep the
+        // module's import graph minimal.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { mkdirSync } = require('node:fs');
+        mkdirSync(runtimeDir, { recursive: true });
+    }
+    if (form === 'file') {
+        writeFileSync(bindingPath, changeId + '\n', 'utf-8');
+        return;
+    }
+    // symlink form: point at .peaks/<changeId>/
+    const targetDir = join(peaksRoot, changeId);
+    if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    if (existsSync(bindingPath)) {
+        // Re-running with a different changeId is a configuration error;
+        // surface it loudly so the caller (peaks workspace init) can decide
+        // whether to --allow-session-rebind for the underlying session.
+        try {
+            const existing = readFileSync(bindingPath, 'utf-8').trim();
+            if (existing !== changeId) {
+                if (existsSync(join(peaksRoot, changeId))) {
+                    unlinkSync(bindingPath);
+                }
+                else {
+                    throw new Error(`current-change binding points at "${existing}" but caller asked to set "${changeId}". ` +
+                        `Remove .peaks/_runtime/current-change first or pass the existing changeId.`);
+                }
+            }
+            else {
+                return; // identical — no-op
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('current-change binding points'))
+                throw error;
+            // Could not read the existing binding (e.g. it's a broken symlink).
+            // Replace.
+            try {
+                unlinkSync(bindingPath);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    symlinkSync(targetDir, bindingPath);
+}
+/**
+ * Canonical on-disk path to a change-id's reviewable artifacts
+ * (`.peaks/<change-id>/`). Writes that target reviewable content
+ * (RD/QA/PRD/txt) should land here regardless of which session
+ * is active. Ephemeral state (live sub-agent progress, spawn records)
+ * stays in the session dir (`.peaks/_runtime/<session-id>/...`).
+ */
+export function getChangeArtifactRoot(projectRoot, changeId) {
+    validateChangeIdOrThrow(changeId);
+    return join(projectRoot, '.peaks', changeId);
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.0";
+export declare const CLI_VERSION = "1.3.2";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.0";
+export const CLI_VERSION = "1.3.2";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.0",
-  "description": "Peaks CLI and short skill family for Claude Code automation.",
+  "version": "1.3.2",
+  "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",
   "type": "module",
@@ -9,6 +9,14 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SquabbyZ/peaks-cli.git"
+  },
+  "homepage": "https://github.com/SquabbyZ/peaks-cli",
+  "bugs": {
+    "url": "https://github.com/SquabbyZ/peaks-cli/issues"
+  },
   "bin": {
     "peaks": "./bin/peaks.js"
   },

package/schemas/doctor-report.schema.json

@@ -13,8 +13,8 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
-            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }

package/skills/peaks-qa/SKILL.md

@@ -62,6 +62,7 @@ This is the hard-block replacement for the previous "wait for the user" prose. W
 
 When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
 - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-qa.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo has already chosen the mode.

package/skills/peaks-rd/SKILL.md

@@ -39,6 +39,7 @@ The full hard-block contract is defined in `peaks-qa` (see "Hard contracts for b
 
 When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
 - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-rd.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo has already chosen the mode. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
@@ -46,7 +47,7 @@ When this skill is launched as a sub-agent via `Task(subagent_type="general-purp
 
 What the sub-agent **MUST** still do, from this skill's contract:
 
-0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to.
+0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to. Note: `peaks request init` is **dry-run by default**. Pass `--apply` to actually create the artifact.
 2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role ui` if UI is in the swarm plan).
 3. Standards preflight (dry-run only; Solo owns the apply step).
 4. Project-scan read; create `rd/project-scan.md` only if Solo flagged it missing in the dispatch prompt.

package/skills/peaks-solo/SKILL.md

@@ -262,6 +262,12 @@ peaks session title $(cat .peaks/.session.json | python3 -c "import sys,json; pr
 
 If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.
 
+## Sub-agent session sharing (MANDATORY — one conversation = one sid)
+
+When peaks-solo dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt, peaks-sc), the sub-agent prompt MUST include the parent's session id. The sub-agent then passes `--session-id <parent-sid>` for any session-creating CLI call (e.g. `peaks request init --session-id <parent-sid>`). The sub-agent MUST NOT call `peaks workspace init` — that would create a new session dir and orphan the parent's binding. The sub-agent reads `.peaks/_runtime/session.json` to discover the parent's sid (or the orchestrator passes it explicitly). Sub-agents also accept the parent's sid via the new `peaks session info --active` primitive when they need a one-shot read.
+
+Note: `peaks request init` is **dry-run by default** — the JSON response has `applied: false` and no file is written unless `--apply` is passed. This is the same safe-by-default pattern as `peaks workspace migrate --apply`. Sub-agents that need to actually create a slice must add `--apply`.
+
 ## Boundaries
 
 Peaks-Cli Solo may:
@@ -755,6 +761,15 @@ Maintenance: when adding new CLI commands to the runbook, mirror them into both
 
 Repair loop details: see `## Mandatory RD QA repair loop` above for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
 
+## RD micro-cycle (TDD small-step rapid-test loop)
+
+> **Slice 内部**的修复 / refactor / lint 修复走 micro-cycle（5-10s/cycle）。
+> Slice 边界走 `peaks slice check`（一次性 4 项自检）。
+> 不要把 micro-cycle 跟边界 check 混用——前者 100ms 反馈循环，后者 30s+ 全套。
+> 完整手册：`references/micro-cycle.md`。
+> 摘要：micro-cycle 内只跑 `vitest run <file> -t "<name>"`；边界跑 `peaks slice check`（tsc + vitest + 3-way + verify-pipeline）。
+> 硬约束：违反任一"micro-cycle 内禁止触发"列表 = workflow violation；边界不全绿 = 禁止 ship。
+
 ## Peaks-Cli Project standards preflight
 
 Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks-Cli CLI:
@@ -805,8 +820,9 @@ These commands harden the workflow against silent skips. Use them in the runbook
 | `peaks request repair-status <rid> --project <path>` | Count RD↔QA repair cycles from `--reason` transition notes ("QA cycle N: ...") | Before every RD repair iteration in step 7 | Cycle count reached the 3-cycle cap |
 | `peaks scan request-type-sanity --project <path> --type <type>` | Cross-verify declared `--type` against the actual `git diff` file mix (catches "feature mis-declared as docs" workflow violations) | After PRD type lock-in AND after each RD repair iteration | Declared type disagrees with the file mix |
 | `peaks scan libraries --project <path>` | Enumerate every dependency + devDependency + peerDependency + optionalDependency with parsed major version; output goes to `## Library versions` in `rd/project-scan.md`. Read-only. | At Solo step 0.6 (alongside `peaks scan archetype`) | Always exits 0 (warnings in JSON envelope; never blocks) |
+| `peaks slice check [--rid <rid>] [--project <path>]` | 4-stage slice 边界 check (typecheck + unit-tests + review-fanout + gate-verify-pipeline). Aggregate pass/fail; non-zero exit if any stage fails. See "Slice 边界 check" below for usage rules (boundary only, never inside a micro-cycle). | At slice 边界（post-micro-cycle, pre-peaks-qa）| Any stage fails |
 
-Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these four commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.
+Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these five commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.
 
 ## Peaks-Cli Completion handoff
 

package/skills/peaks-solo/references/micro-cycle.md

@@ -0,0 +1,155 @@
+# RD micro-cycle (TDD 小步快测)
+
+> 参考 TDD 模式的红绿循环。设计目标：把 1 行 bug fix 的反馈循环从
+> ~30s（全 suite + verify-pipeline）压到 ~100ms（单测 + 心算）。
+
+## 什么时候用 micro-cycle
+
+- 在 **RD 实现** 阶段，**slice 内部** 做小修复 / refactor / lint fix / 微调时
+- 节奏：5-10 秒一个 micro-cycle
+
+## 什么时候**不**用 micro-cycle
+
+- slice 边界（一个 RD 任务结束 / 用户说 ship / 一个 logical change 整体完成）→ 走 `peaks slice check`
+- 新增 slice / 跨模块 refactor / 依赖升级 → 直接走 peaks-rd 主流程
+- `--type docs` / `--type chore` → 没有 acceptance 表面，micro-cycle 不适用
+
+## The cycle (硬约束顺序)
+
+### 1. RED — 写/改一个 unit test 反映 bug
+
+```bash
+vim tests/unit/<file>.test.ts  # 加 1 个 test 反映 bug
+```
+
+约束：**先写测试，再写实现**。LLM 写完实现再补 test 属于反向 TDD，等同于 skip micro-cycle。
+
+### 2. 跑这一个 test（确认 red）
+
+```bash
+npx vitest run tests/unit/<file>.test.ts \
+  -t "<new test name>" \
+  --no-coverage
+```
+
+预期：test FAIL。**如果已经 pass → 你的测试没反映 bug，回去重写**。
+
+### 3. GREEN — 修实现
+
+```bash
+vim src/<file>.ts
+```
+
+约束：**minimal change**，不要顺手"改进"无关代码。
+
+### 4. 跑这一个 test（确认 green）
+
+```bash
+npx vitest run tests/unit/<file>.test.ts \
+  -t "<new test name>" \
+  --no-coverage
+```
+
+预期：test PASS。**如果还 FAIL → 你的实现不对，回去修**。
+
+### 5. 局部回扫 — 跑同 file 的所有 test
+
+```bash
+npx vitest run tests/unit/<file>.test.ts --no-coverage
+```
+
+目的：防"改一处坏一处"。比全 suite 快 10-50×。
+
+### 6. 写一个 commit message（先不 commit）
+
+```bash
+git add -p
+# commit message: [micro-cycle] <slice-id>: <one-line summary>
+```
+
+## micro-cycle 内**禁止**触发
+
+| 命令 | 理由 |
+|---|---|
+| `npx vitest run`（无 filter）| 30s+，micro-cycle 内禁止 |
+| `npx tsc --noEmit` | 边界点才跑 |
+| `peaks workflow verify-pipeline` | 边界点才跑 |
+| 3-way fan-out（code-review / security-review / perf-baseline）| 边界点 + RD-internal 才跑 |
+| `peaks request transition <rid> --state qa-handoff` | micro-cycle 内**不切 slice 状态** |
+
+**违反任何一条 = workflow violation**（slice 边界才能跑全套）。
+
+## 边界 check（slice 结束）
+
+当一个 slice 内的所有 micro-cycle 都 green 且用户/agent 准备进入 peaks-qa 时，**必须**跑：
+
+```bash
+peaks slice check [--rid <rid>] [--project <path>] [--json]
+```
+
+这个命令编排：
+1. `npx tsc --noEmit`（typecheck）
+2. `npx vitest run`（全 suite）
+3. 3-way fan-out（code-review + security-review + perf-baseline）
+4. `peaks workflow verify-pipeline --rid <rid> --project <path>`
+
+4 个 check 全绿 + verify-pipeline pass → 才进 `peaks request transition --state qa-handoff`，让 peaks-qa 接管。
+
+## Micro-cycle → 边界 check → QA 的串联
+
+```
+peaks-rd 启动一个 slice
+  ↓
+  bug 1 → micro-cycle (红绿, ~10s)
+  bug 2 → micro-cycle
+  bug 3 → micro-cycle
+  ...
+  ↓ 全部 green
+peaks slice check  # 4 项检查全绿
+  ↓
+peaks request transition --state qa-handoff
+  ↓
+peaks-qa 接管 (full gate machinery)
+  ↓
+verdict=pass → SC + TXT → handoff
+verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
+```
+
+## Anti-patterns（明确禁止）
+
+- ❌ 写实现先于测试（反向 TDD）
+- ❌ micro-cycle 内跑全 suite（`vitest run`）
+- ❌ micro-cycle 内调 `peaks workflow verify-pipeline`
+- ❌ 1 个 micro-cycle 改 < 1 行代码（合并到下一个相关变更）
+- ❌ skip 边界 check 直接 ship
+- ❌ 在 micro-cycle 内修改 reviewed artifacts（code-review / security-review / perf-baseline）— 等边界再 regenerate
+- ❌ micro-cycle 跨 PR/branch（一次 PR 内的所有 micro-cycles 才合在一起 review）
+
+## 跟其他 skill 的边界
+
+| 阶段 | 谁负责 | 节奏 |
+|---|---|---|
+| RD slice 内部 | peaks-solo (main loop) | micro-cycle（5-10s 一个） |
+| RD slice 边界 | peaks-solo 调用 `peaks slice check` | 一次 |
+| QA test execution | peaks-qa (sub-agent or inline) | slice 级 |
+| 3-way fan-out (CR + sec + perf) | peaks-rd (sub-agent) | slice 级（RD 内部一次 + 边界 check 一次） |
+| TXT handoff | peaks-txt | slice 级 |
+| SC commit-boundaries | peaks-sc | slice 级 |
+
+## 为什么这套比当前 peaks-solo 的设计合理
+
+- **快**：micro-cycle ~100ms（vs 30s 全 suite），改 10 个 bug 从 5 分钟降到 30 秒
+- **稳**：边界 check 不省，4 项检查（tsc + vitest + 3-way + verify-pipeline）一次全跑
+- **清晰**：LLM 看到一个 explicit "禁止" 列表 + 强制 sequence，比"建议"更不容易越界
+- **可观测**：micro-cycle 走单测 → 边界跑 verify-pipeline，每步都有 JSON envelope 验证
+
+## 跟 peaks-solo SKILL.md 的对账
+
+- `peaks slice check` = 边界命令
+- micro-cycle = slice 内部
+- 3-way fan-out = peaks-rd 内部 + `peaks slice check` 末尾
+- `peaks workflow verify-pipeline` = 边界 check
+- `peaks request transition` = 边界切状态
+- peaks-qa 接管 = 边界 + `verdict != pass` 时的下一轮
+
+完整流程见 SKILL.md。

package/skills/peaks-txt/SKILL.md

@@ -15,6 +15,8 @@ Before any analysis or tool call, immediately run:
 peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate startup
 ```
 
+**When invoked as a sub-agent (peaks-solo swarm):** do NOT call `peaks skill presence:set` (Solo owns the active-skill marker) and do NOT spawn your own session. Use the parent's sid — read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI. The new `peaks session info --active` reads the canonical binding for you.
+
 On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
 
 ```bash

package/skills/peaks-ui/SKILL.md

@@ -30,6 +30,7 @@ UI's headed-browser inspection hits the same auth walls. The flow is identical t
 
 When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
 - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-ui`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-ui.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo has already chosen the mode.