peaks-cli 1.2.9 → 1.3.1

package/dist/src/services/workspace/workspace-service.d.ts

@@ -8,6 +8,15 @@ export type WorkspaceInitOptions = {
      * — the CLI surfaces this as `--allow-session-rebind`.
      */
     allowSessionRebind?: boolean;
+    /**
+     * Optional change-id to bind as the active unit of work. When set,
+     * `peaks workspace init` also writes a `.peaks/_runtime/current-change`
+     * symlink pointing at `.peaks/<changeId>/`, so RD/QA/PRD services
+     * know which `<change-id>` directory to write reviewable artifacts
+     * into. The session id is still the binding for ephemeral state
+     * (live sub-agent progress, spawn records).
+     */
+    changeId?: string;
 };
 export type WorkspaceInitReport = {
     sessionId: string;
@@ -16,6 +25,8 @@ export type WorkspaceInitReport = {
     alreadyExisted: string[];
     bound: boolean;
     previousSessionId: string | null;
+    changeId: string | null;
+    changeIdAction: 'bound' | 'preserved' | 'none';
 };
 export declare class InvalidSessionIdError extends Error {
     readonly code = "INVALID_SESSION_ID";

package/dist/src/services/workspace/workspace-service.js

@@ -2,7 +2,16 @@ import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
 import { getSessionId, setCurrentSessionBinding } from '../session/session-manager.js';
-const SUBDIRECTORIES = [
+import { setCurrentChangeId } from '../../shared/change-id.js';
+/**
+ * Per-slice subdirectories created **inside the change-id dir**
+ * (`.peaks/<change-id>/...`). These are the reviewable
+ * artifacts and are tracked in git. The `system/` subdir is
+ * intentionally NOT in this list — it lives under the session
+ * dir (`.peaks/_runtime/<session-id>/system/`), since it holds
+ * live sub-agent progress and spawn records, which are ephemeral.
+ */
+const CHANGE_ARTIFACT_SUBDIRECTORIES = [
     'prd/source',
     'prd/requests',
     'ui/requests',
@@ -12,7 +21,14 @@ const SUBDIRECTORIES = [
     'qa/requests',
     'qa/screenshots',
     'sc',
-    'txt',
+    'txt'
+];
+/**
+ * Per-session subdirectories created **inside the session dir**
+ * (`.peaks/_runtime/<session-id>/...`). These are the ephemeral
+ * state and are gitignored.
+ */
+const SESSION_EPHEMERAL_SUBDIRECTORIES = [
     'system'
 ];
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
@@ -61,9 +77,26 @@ export function validateSessionId(sessionId) {
 }
 export async function initWorkspace(options) {
     validateSessionId(options.sessionId);
-    const sessionRoot = join(options.projectRoot, '.peaks', options.sessionId);
+    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work):
+    //   - Reviewable artifacts (rd/, qa/, prd/, txt/) are created at
+    //     `.peaks/<change-id>/<role>/` (tracked in git) when a change-id
+    //     is given. This is the canonical home for cross-session content.
+    //   - The session dir `.peaks/_runtime/<session-id>/` (gitignored)
+    //     holds only ephemeral state — currently `system/` (live
+    //     sub-agent progress + spawn records). The session id remains
+    //     the binding for that ephemeral state.
+    //
+    // The CLI accepts `--change-id <id>` to bind the change. The legacy
+    // session-scoped layout (`.peaks/<session-id>/<role>/<file>`) is
+    // no longer used by writes; pre-1.3.1 trees get their session
+    // files migrated to the change-id dir by `peaks workspace reconcile`.
+    const runtimeRoot = join(options.projectRoot, '.peaks', '_runtime');
+    const sessionRoot = join(runtimeRoot, options.sessionId);
     const created = [];
     const alreadyExisted = [];
+    // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
+    //    with ONLY ephemeral subdirs (`system/`). The session dir is
+    //    gitignored.
     if (await isDirectory(sessionRoot)) {
         alreadyExisted.push('.');
     }
@@ -71,7 +104,7 @@ export async function initWorkspace(options) {
         await mkdir(sessionRoot, { recursive: true });
         created.push('.');
     }
-    for (const sub of SUBDIRECTORIES) {
+    for (const sub of SESSION_EPHEMERAL_SUBDIRECTORIES) {
         const full = join(sessionRoot, sub);
         if (await isDirectory(full)) {
             alreadyExisted.push(sub);
@@ -81,7 +114,45 @@ export async function initWorkspace(options) {
             created.push(sub);
         }
     }
-    // Bind this session as the project's current one.
+    // 2. If a change-id is given, also create the change-id dir at
+    //    `.peaks/<change-id>/` (tracked) with the reviewable subdirs.
+    //    When the caller did NOT specify a change-id, this step is
+    //    skipped — reviewable writes for this session are then blocked
+    //    until a change-id is bound (or the user re-runs init with
+    //    `--change-id`). Surfaces in `changeIdAction: 'none'`.
+    let resolvedChangeId = null;
+    let changeIdAction = 'none';
+    if (options.changeId !== undefined && options.changeId.length > 0) {
+        resolvedChangeId = options.changeId;
+        const changeDir = join(options.projectRoot, '.peaks', resolvedChangeId);
+        if (await isDirectory(changeDir)) {
+            alreadyExisted.push(resolvedChangeId);
+        }
+        else {
+            await mkdir(changeDir, { recursive: true });
+            created.push(resolvedChangeId);
+        }
+        for (const sub of CHANGE_ARTIFACT_SUBDIRECTORIES) {
+            const full = join(changeDir, sub);
+            if (await isDirectory(full)) {
+                alreadyExisted.push(sub);
+            }
+            else {
+                await mkdir(full, { recursive: true });
+                created.push(sub);
+            }
+        }
+        // 3. Bind the change-id so RD/QA/PRD services know where to write
+        //    reviewable artifacts. The binding is a symlink at
+        //    `.peaks/_runtime/current-change` pointing at the change-id dir.
+        setCurrentChangeId(options.projectRoot, resolvedChangeId);
+        changeIdAction = 'bound';
+    }
+    else if (options.changeId !== undefined && options.changeId.length === 0) {
+        // Empty string — same as undefined; treat as no change-id.
+        changeIdAction = 'none';
+    }
+    // 4. Bind this session as the project's current one.
     //
     // Single source of truth: `peaks workspace init` is the only CLI entry point
     // that takes an explicit --session-id, so it owns the binding to .session.json.
@@ -112,7 +183,7 @@ export async function initWorkspace(options) {
         // etc.) regardless of whether the per-session metadata file is present.
         // Refuse to rebind without explicit authorization.
         previousSessionId = existingSessionId;
-        const existingSessionDir = join(options.projectRoot, '.peaks', existingSessionId);
+        const existingSessionDir = join(runtimeRoot, existingSessionId);
         if (await isDirectory(existingSessionDir) && !options.allowSessionRebind) {
             const { readdirSync } = await import('node:fs');
             const entries = readdirSync(existingSessionDir);
@@ -127,5 +198,14 @@ export async function initWorkspace(options) {
         setCurrentSessionBinding(options.projectRoot, options.sessionId);
         bound = true;
     }
-    return { sessionId: options.sessionId, sessionRoot, created, alreadyExisted, bound, previousSessionId };
+    return {
+        sessionId: options.sessionId,
+        sessionRoot,
+        created,
+        alreadyExisted,
+        bound,
+        previousSessionId,
+        changeId: resolvedChangeId,
+        changeIdAction
+    };
 }

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.2.9";
+export declare const CLI_VERSION = "1.3.1";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.9";
+export const CLI_VERSION = "1.3.1";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.9",
-  "description": "Peaks CLI and short skill family for Claude Code automation.",
+  "version": "1.3.1",
+  "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"
   },
@@ -30,9 +38,12 @@
   "scripts": {
     "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
     "prepack": "npm run build",
+    "prepublish": "node ./scripts/sync-version.mjs",
     "postinstall": "node ./scripts/install-skills.mjs",
+    "predev": "node ./scripts/sync-version.mjs",
     "dev": "tsx src/cli/index.ts",
     "dev:watch": "node ./scripts/watch.mjs",
+    "pretest": "node ./scripts/sync-version.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "pretest:coverage": "node ./scripts/pretest-coverage.mjs",

package/skills/peaks-solo/SKILL.md

@@ -294,9 +294,9 @@ For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` t
 
 ### Workspace initialization gate
 
-The workspace is created in Step 0 (Startup sequence) as a mandatory first action — before any analysis, role handoff, or artifact write, and regardless of how lightweight the request is. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/.session.json`.
+The workspace is created in Step 0 (Startup sequence) as a mandatory first action — before any analysis, role handoff, or artifact write, and regardless of how lightweight the request is. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/_runtime/session.json` (the canonical home as of slice `2026-06-05-peaks-runtime-layer`; the legacy `.peaks/.session.json` is read-only back-compat for one minor release).
 
-When `peaks workspace init` is run without `--session-id`, it automatically generates a new session ID using today's date and a random hex suffix. If `.peaks/.session.json` already exists with a valid session, the existing session is reused.
+When `peaks workspace init` is run without `--session-id`, it automatically generates a new session ID using today's date and a random hex suffix. If a valid session binding exists at `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json` for pre-migration trees), the existing session is reused.
 
 **Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs (e.g. `2026-05-25-auth-system`), create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
 
@@ -304,9 +304,23 @@ When `peaks workspace init` is run without `--session-id`, it automatically gene
 peaks workspace init --project <repo> --json
 ```
 
-The workspace initialization creates this structure under `.peaks/<session-id>/` (where `<session-id>` is auto-generated as `YYYY-MM-DD-session-<6位hex>`):
+The workspace initialization creates this structure under `.peaks/`:
 
 ```
+# Canonical home for all per-project ephemeral state (active-skill
+# marker, session binding, sop-state). All writes go here; reads also
+# tolerate the legacy paths (`.peaks/.active-skill.json`,
+# `.peaks/.session.json`, `.peaks/sop-state/`) for one minor release
+# so a fresh upgrade does not break in-flight workflows. Older trees
+# are auto-migrated by `peaks workspace reconcile --apply`.
+.peaks/_runtime/
+├── active-skill.json   # orchestrator presence marker (peaks-solo / -rd / -qa / -ui / -sc / -sop / -txt)
+├── session.json        # project → session binding (the only single-session source of truth)
+└── sop-state/          # current phase + history; definitions live globally in ~/.peaks
+
+# Per-slice artifact dirs (auto-generated, one per session). Files
+# inside ARE tracked by the 提交中间产物 convention.
+.peaks/<session-id>/
 prd/source/      # PRD source documents (Feishu exports, pasted content)
 prd/requests/    # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
 ui/requests/     # UI request artifacts (visual direction, taste reports)
@@ -741,6 +755,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:
@@ -791,8 +814,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