peaks-cli 1.2.9 → 1.3.0

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

@@ -0,0 +1,464 @@
+/**
+ * Reconcile service for `.peaks/2026-MM-DD-session-<6hex>/` directories.
+ *
+ * Reconcile scans the project root's `.peaks/` directory, identifies a
+ * canonical session via a 4-tier heuristic, re-points
+ * `.peaks/_runtime/session.json` (the canonical new home of the
+ * binding; legacy `.peaks/.session.json` is read-only back-compat),
+ * and (optionally, with apply === true) deletes empty / abandoned
+ * session dirs older than olderThanMs.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the top-level orchestrator
+ * also runs `migrateOldRuntimeState` at the start so pre-migration
+ * trees have their `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * / `.peaks/sop-state/` files moved into `.peaks/_runtime/`.
+ *
+ * Pure hand-rolled; uses only node:fs, node:path, and the existing
+ * session-manager helper for writing the binding. No new dependencies.
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
+const META_FILE = 'session.json';
+// As of slice 2026-06-05-peaks-runtime-layer these old paths are the
+// back-compat read-only fallbacks; the canonical new home is
+// `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
+// location on disk. The leading dot is dropped when computing the
+// new basename (e.g. `.session.json` → `session.json`), so the new
+// layout is `.peaks/_runtime/{session.json,active-skill.json,sop-state/}`.
+const RUNTIME_OLD_PATHS = [
+    '.session.json',
+    '.active-skill.json',
+    'sop-state'
+];
+const RUNTIME_DIR = join('.peaks', '_runtime');
+/**
+ * Map a legacy path basename (e.g. `.session.json`) to its canonical
+ * new basename (e.g. `session.json`). The dot is dropped so the new
+ * layer reads naturally. Directories pass through unchanged.
+ */
+function runtimeNewBasename(oldBasename) {
+    if (oldBasename.startsWith('.') && oldBasename.length > 1) {
+        return oldBasename.slice(1);
+    }
+    return oldBasename;
+}
+/**
+ * Walk the project root's `.peaks/` directory and return an entry per
+ * session dir matching the standard naming pattern, sorted by name
+ * ascending (the most recent is last by sort order, since the date
+ * prefix dominates the lexicographic order).
+ *
+ * Each entry's `lastActivity` is the mtime of the inner `session.json`
+ * file, or null if that file is missing. `artifactCount` is the count
+ * of files under the dir excluding `session.json` itself.
+ */
+export function discoverSessions(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        if (!SESSION_ID_PATTERN.test(name))
+            continue;
+        const dir = join(peaksRoot, name);
+        let stat;
+        try {
+            // lstatSync: false for symlinks (prevents rm -rf from following a
+            // malicious symlink that points outside the project root).
+            stat = lstatSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const metaPath = join(dir, META_FILE);
+        let lastActivity = null;
+        if (existsSync(metaPath)) {
+            try {
+                lastActivity = statSync(metaPath).mtimeMs;
+            }
+            catch {
+                lastActivity = null;
+            }
+        }
+        let childNames;
+        try {
+            childNames = readdirSync(dir);
+        }
+        catch {
+            childNames = [];
+        }
+        let artifactCount = 0;
+        for (const child of childNames) {
+            if (child === META_FILE)
+                continue;
+            artifactCount += 1;
+        }
+        entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
+    }
+    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return entries;
+}
+/**
+ * 4-tier canonical selection. Tiers evaluated in order; first one that
+ * yields a session id wins.
+ *
+ *   1. active-skill sessionId, if it matches a real entry
+ *   2. entry with the most recent `session.json` mtime
+ *   3. entry with the most recent mtime of any file inside it
+ *   4. entry whose dir name sorts last lexicographically
+ */
+export function pickCanonicalSession(entries, activeSkillSessionId) {
+    if (entries.length === 0)
+        return null;
+    // Tier 1
+    if (activeSkillSessionId !== null) {
+        const hit = entries.find((e) => e.sessionId === activeSkillSessionId);
+        if (hit !== undefined) {
+            return { sessionId: hit.sessionId, source: 'active-skill' };
+        }
+    }
+    // Tier 2
+    let tier2Best = null;
+    for (const e of entries) {
+        if (e.lastActivity === null)
+            continue;
+        if (tier2Best === null || e.lastActivity > tier2Best.lastActivity) {
+            tier2Best = { sessionId: e.sessionId, lastActivity: e.lastActivity };
+        }
+    }
+    if (tier2Best !== null) {
+        return { sessionId: tier2Best.sessionId, source: 'latest-session-json-mtime' };
+    }
+    // Tier 3
+    let tier3Best = null;
+    let tier3Mtime = -Infinity;
+    for (const e of entries) {
+        const mtime = newestMtimeRecursive(e.path);
+        if (mtime === null)
+            continue;
+        if (mtime > tier3Mtime) {
+            tier3Mtime = mtime;
+            tier3Best = { sessionId: e.sessionId, path: e.path };
+        }
+    }
+    if (tier3Best !== null) {
+        return { sessionId: tier3Best.sessionId, source: 'latest-any-file-mtime' };
+    }
+    // Tier 4
+    const sortedAsc = [...entries].sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    const last = sortedAsc[sortedAsc.length - 1];
+    if (last !== undefined) {
+        return { sessionId: last.sessionId, source: 'dir-name-sort' };
+    }
+    return null;
+}
+function newestMtimeRecursive(dirPath) {
+    let best = null;
+    let stack = [dirPath];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let names;
+        try {
+            names = readdirSync(current);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const childPath = join(current, name);
+            let stat;
+            try {
+                stat = statSync(childPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                stack.push(childPath);
+                continue;
+            }
+            if (stat.mtimeMs > (best ?? -Infinity)) {
+                best = stat.mtimeMs;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Write `.peaks/.session.json` to bind the project to `canonicalSessionId`.
+ * Preserves the projectRoot. The previous binding is returned so the CLI
+ * can surface the re-point delta.
+ */
+export function repointSessionJson(projectRoot, canonicalSessionId, repointedFrom) {
+    setCurrentSessionBinding(projectRoot, canonicalSessionId);
+    return { repointedFrom, repointedTo: canonicalSessionId };
+}
+/**
+ * Identify deletion candidates. A session is a candidate when:
+ *   - the resolved `lastActivity` is older than `ageThresholdMs`, AND
+ *   - the dir is "empty or auto-only" (artifactCount === 0, OR the
+ *     only file is `session.json` which is auto-generated).
+ *
+ * If `lastActivity` is null (no `session.json` inside), the session's
+ * own dir mtime is used as a fallback so empty dirs without inner
+ * metadata are still fair-game.
+ */
+export function findDeletionCandidates(entries, ageThresholdMs) {
+    const now = Date.now();
+    const candidates = [];
+    for (const e of entries) {
+        const isEmptyOrAutoOnly = e.artifactCount === 0;
+        if (!isEmptyOrAutoOnly)
+            continue;
+        const mtime = e.lastActivity !== null
+            ? e.lastActivity
+            : readDirMtime(e.path);
+        if (mtime === null)
+            continue;
+        if (now - mtime < ageThresholdMs)
+            continue;
+        candidates.push(e);
+    }
+    return candidates;
+}
+function readDirMtime(dirPath) {
+    try {
+        return statSync(dirPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Apply or report deletion of the given candidates. When `apply` is
+ * false, just return `wouldDelete` and do not touch disk. When `apply`
+ * is true, actually `rm -rf` each dir and accumulate any per-dir
+ * errors in the result.
+ */
+export function applyDeletions(candidates, apply) {
+    if (!apply) {
+        return {
+            deleted: [],
+            wouldDelete: candidates.map((c) => c.sessionId),
+            errors: []
+        };
+    }
+    const deleted = [];
+    const errors = [];
+    for (const c of candidates) {
+        try {
+            rmSync(c.path, { recursive: true, force: true });
+            deleted.push(c.sessionId);
+        }
+        catch (error) {
+            errors.push({
+                sessionId: c.sessionId,
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return { deleted, wouldDelete: [], errors };
+}
+/**
+ * Read the orchestrator's active-skill marker and extract the
+ * session id. As of slice 2026-06-05-peaks-runtime-layer the
+ * canonical home is `.peaks/_runtime/active-skill.json`; the legacy
+ * `.peaks/.active-skill.json` is consulted as a one-minor-release
+ * back-compat fallback (the new path wins when both exist).
+ *
+ * Returns null when the file is missing or malformed.
+ */
+function readActiveSkillSessionId(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'active-skill.json');
+    const legacyPath = join(projectRoot, '.peaks', '.active-skill.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        // Sync read: tiny file, no I/O benefit from async
+        const { readFileSync } = require('node:fs');
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
+ *
+ * Move the legacy runtime files at:
+ *   - `.peaks/.session.json`
+ *   - `.peaks/.active-skill.json`
+ *   - `.peaks/sop-state/`
+ * into their new canonical home at:
+ *   - `.peaks/_runtime/session.json`
+ *   - `.peaks/_runtime/active-skill.json`
+ *   - `.peaks/_runtime/sop-state/`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new
+ *     layout produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
+ *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
+ *     rename throws (e.g. cross-device move on Windows). Errors are
+ *     collected per file and returned in the `errors` array so the
+ *     reconcile envelope can surface them without blocking the rest of
+ *     the migration.
+ *   - Creates `.peaks/_runtime/` on demand if any of the old paths
+ *     are present.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
+ *   *old* relative paths (e.g. `.peaks/.session.json`) that were
+ *   successfully moved, in move order. `errors` lists per-file
+ *   failures with the old path and a human-readable message.
+ */
+export function migrateOldRuntimeState(projectRoot) {
+    const root = resolve(projectRoot);
+    const peaksRoot = join(root, '.peaks');
+    const newDir = join(root, RUNTIME_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const rel of RUNTIME_OLD_PATHS) {
+        const oldPath = join(peaksRoot, rel);
+        if (!existsSync(oldPath))
+            continue;
+        // Skip if the corresponding new path already exists — we treat the
+        // new path as authoritative when both exist, so the old file would
+        // only be stale data.
+        const newPath = join(newDir, runtimeNewBasename(rel));
+        if (existsSync(newPath)) {
+            // Best-effort cleanup of the stale old file so a re-run stays
+            // idempotent and the tree converges on the new layout.
+            try {
+                rmSync(oldPath, { recursive: true, force: true });
+            }
+            catch (error) {
+                errors.push({
+                    path: rel,
+                    message: `Could not remove stale legacy file after migration: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+            continue;
+        }
+        try {
+            // Ensure the new parent dir exists. `mkdirSync(dirname(newPath), { recursive: true })`
+            // covers both the file case (`.peaks/_runtime`) and the
+            // directory case (`.peaks/_runtime/sop-state`).
+            mkdirSync(dirname(newPath), { recursive: true });
+            try {
+                renameSync(oldPath, newPath);
+            }
+            catch (renameError) {
+                // Cross-device or locked-file fallback: copy + unlink.
+                const stat = lstatSync(oldPath);
+                if (stat.isDirectory()) {
+                    // Recursive copy for the sop-state dir.
+                    copyDirRecursiveSync(oldPath, newPath);
+                    rmSync(oldPath, { recursive: true, force: true });
+                }
+                else {
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+            }
+            migratedFiles.push(join('.peaks', rel));
+        }
+        catch (error) {
+            errors.push({
+                path: rel,
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return { migratedFiles, errors };
+}
+function copyDirRecursiveSync(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    for (const name of readdirSync(src)) {
+        const childSrc = join(src, name);
+        const childDest = join(dest, name);
+        const stat = lstatSync(childSrc);
+        if (stat.isDirectory()) {
+            copyDirRecursiveSync(childSrc, childDest);
+        }
+        else {
+            copyFileSync(childSrc, childDest);
+        }
+    }
+}
+/**
+ * Top-level orchestrator. Wires migration (added in slice
+ * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
+ * deletion-candidate selection, and deletion into a single result.
+ */
+export function reconcileWorkspace(options) {
+    const projectRoot = resolve(options.projectRoot);
+    const apply = options.apply === true;
+    const ageThresholdMs = options.olderThanMs;
+    // Migration runs FIRST. The canonical-session logic still consults
+    // the session-manager helper which already reads the new path first
+    // and falls back to the old path; moving the old file out of the way
+    // before that read means the new path is the only path observed by
+    // `getSessionIdCanonical` after this call returns.
+    const migration = migrateOldRuntimeState(projectRoot);
+    const migrateErrors = migration.errors.map((e) => ({
+        kind: 'migrate',
+        path: e.path,
+        message: e.message
+    }));
+    const sessions = discoverSessions(projectRoot);
+    const activeSkillSessionId = readActiveSkillSessionId(projectRoot);
+    const canonical = pickCanonicalSession(sessions, activeSkillSessionId);
+    const previousBinding = getSessionIdCanonical(projectRoot);
+    let repointedFrom = previousBinding;
+    let repointedTo = null;
+    let repointed = false;
+    if (canonical !== null) {
+        if (previousBinding !== canonical.sessionId) {
+            const repoint = repointSessionJson(projectRoot, canonical.sessionId, previousBinding);
+            repointedFrom = repoint.repointedFrom;
+            repointedTo = repoint.repointedTo;
+            repointed = true;
+        }
+        else {
+            // No-op: re-point the same binding so lastActivity is refreshed
+            const repoint = repointSessionJson(projectRoot, canonical.sessionId, previousBinding);
+            repointedFrom = repoint.repointedFrom;
+            repointedTo = repoint.repointedTo;
+        }
+    }
+    const deletionCandidates = findDeletionCandidates(sessions, ageThresholdMs);
+    const deletionResult = applyDeletions(deletionCandidates, apply);
+    return {
+        projectRoot,
+        sessions,
+        canonicalSessionId: canonical === null ? null : canonical.sessionId,
+        canonicalSource: canonical === null ? null : canonical.source,
+        repointedFrom,
+        repointedTo,
+        deletionCandidates,
+        deleted: deletionResult.deleted,
+        wouldDelete: deletionResult.wouldDelete,
+        ageThresholdMs,
+        apply,
+        repointed,
+        migratedFiles: migration.migratedFiles,
+        errors: [...migrateErrors, ...deletionResult.errors]
+    };
+}

package/dist/src/services/workspace/reconcile-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Type envelope for the `peaks workspace reconcile` CLI command.
+ *
+ * The reconcile command scans `.peaks/2026-MM-DD-session-<6hex>/` directories
+ * under the project root, identifies a canonical session via a 4-tier
+ * heuristic (active-skill binding -> most-recent session.json mtime ->
+ * most-recent any-file mtime -> dir-name sort), re-points
+ * `.peaks/.session.json`, and (optionally) deletes empty / abandoned
+ * session dirs older than a configurable age threshold.
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export type SessionEntry = {
+    /** Directory name (e.g. "2026-06-04-session-89f7cb"). */
+    sessionId: string;
+    /** Absolute path to the session directory. */
+    path: string;
+    /** mtime of `session.json` inside the dir in ms since epoch; null if missing. */
+    lastActivity: number | null;
+    /**
+     * Count of files under the session dir, EXCLUDING `session.json`
+     * (which is auto-generated by `peaks workspace init`). A count of
+     * 0 means the dir is empty / abandoned.
+     */
+    artifactCount: number;
+};
+export type DeletionCandidateReason = 'empty-or-auto-only' | 'older-than-threshold';
+export type ReconcileResult = {
+    /** Absolute project root the command operated on. */
+    projectRoot: string;
+    /** All discovered `.peaks/2026-MM-DD-session-<6hex>/` directories, sorted by name. */
+    sessions: SessionEntry[];
+    /** The session id selected by the 4-tier canonical heuristic. */
+    canonicalSessionId: string | null;
+    /**
+     * The tier that decided the canonical pick (1..4), where tier 1 is
+     * active-skill and tier 4 is lexicographic last. Null when there are
+     * no sessions at all.
+     */
+    canonicalSource: 'active-skill' | 'latest-session-json-mtime' | 'latest-any-file-mtime' | 'dir-name-sort' | null;
+    /** The session id the binding pointed at before reconcile. Null if no prior binding. */
+    repointedFrom: string | null;
+    /** The session id the binding now points at. Null if there were no sessions. */
+    repointedTo: string | null;
+    /** Sessions that match the age-threshold + empty-or-auto-only deletion rule. */
+    deletionCandidates: SessionEntry[];
+    /** Actual deletions performed (only populated when `apply === true`). */
+    deleted: string[];
+    /** Sessions that WOULD be deleted if `--apply` were set (only populated when `apply === false`). */
+    wouldDelete: string[];
+    /** Age threshold in ms used to compute deletion candidates. */
+    ageThresholdMs: number;
+    /** Whether `--apply` was set. */
+    apply: boolean;
+    /** Whether the canonical session id differs from the prior binding. */
+    repointed: boolean;
+    /**
+     * Old-path runtime files that `migrateOldRuntimeState` moved into
+     * `.peaks/_runtime/` during this reconcile run. Each entry is the
+     * legacy path relative to the project root (e.g. ".peaks/.session.json",
+     * ".peaks/.active-skill.json", ".peaks/sop-state"). Empty when the
+     * tree is already on the new layout (idempotent re-runs return []).
+     *
+     * Added in slice 2026-06-05-peaks-runtime-layer; additive — older
+     * consumers can ignore this field.
+     */
+    migratedFiles: string[];
+    /**
+     * Errors encountered during the migration step. Each entry has a
+     * `kind: 'migrate'` discriminator so consumers can tell migration
+     * errors apart from deletion errors. The shape is additive.
+     */
+    errors: Array<{
+        sessionId: string;
+        message: string;
+    } | {
+        kind: 'migrate';
+        path: string;
+        message: string;
+    }>;
+};
+export type ReconcileOptions = {
+    projectRoot: string;
+    /** When true, actually `rm -rf` the deletion candidates. */
+    apply: boolean;
+    /**
+     * Age threshold in milliseconds; sessions whose mtime-based
+     * `lastActivity` is older than this AND whose `artifactCount === 0`
+     * (or 1 if the only file is `session.json`) are deletion candidates.
+     * Default: 7 days in the CLI layer.
+     */
+    olderThanMs: number;
+};

package/dist/src/services/workspace/reconcile-types.js

@@ -0,0 +1,13 @@
+/**
+ * Type envelope for the `peaks workspace reconcile` CLI command.
+ *
+ * The reconcile command scans `.peaks/2026-MM-DD-session-<6hex>/` directories
+ * under the project root, identifies a canonical session via a 4-tier
+ * heuristic (active-skill binding -> most-recent session.json mtime ->
+ * most-recent any-file mtime -> dir-name sort), re-points
+ * `.peaks/.session.json`, and (optionally) deletes empty / abandoned
+ * session dirs older than a configurable age threshold.
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export {};

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

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

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -30,9 +30,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)

package/skills/peaks-solo/references/runbook.md

@@ -18,6 +18,7 @@ peaks doctor --json
 peaks project dashboard --project <repo> --json
 peaks skill runbook peaks-solo --json
 peaks workspace init --project <repo> --json
+peaks workspace reconcile --project <repo> --json
 peaks scan archetype --project <repo> --json
 # → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
 # → copy libraries[] into .peaks/<session-id>/rd/project-scan.md under `## Library versions`
@@ -131,6 +132,7 @@ peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
 # 9. Peaks-Cli OpenSpec archive (exit gate; only after QA pass, when openspec/ exists)
 peaks openspec validate <cid> --project <repo> --json
 peaks openspec archive <cid> --project <repo> --apply --json
+peaks workspace reconcile --project <repo> --apply --older-than 7
 
 # 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
 #     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md. Inside the