peaks-cli 1.2.0 → 1.2.2

package/dist/src/cli/commands/core-artifact-commands.js

@@ -274,10 +274,11 @@ export function registerCoreAndArtifactCommands(program, io) {
         .description('Extract stable project memory from skill artifacts into project .peaks/memory')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
-        .option('--dry-run', 'preview writes without changing files', true)
-        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into project .peaks/memory (default behavior)')).action((options) => {
         try {
-            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
+            const shouldApply = options.dryRun !== true;
+            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: shouldApply });
             printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
         }
         catch (error) {
@@ -290,10 +291,11 @@ export function registerCoreAndArtifactCommands(program, io) {
         .description('Back up project .peaks/memory into the artifact workspace')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--workspace <path>', 'artifact workspace path')
-        .option('--dry-run', 'preview copies without changing files', true)
-        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
+        .option('--dry-run', 'preview copies without changing files')
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup (default behavior)')).action((options) => {
         try {
-            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: options.apply === true });
+            const shouldApply = options.dryRun !== true;
+            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: shouldApply });
             printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
         }
         catch (error) {

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

@@ -25,5 +25,9 @@ export type DoctorOptions = {
     skillPresenceProbe?: () => SkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
     statusLineInstalledProbe?: () => boolean;
+    /** Returns true when a Peaks workspace session (.peaks/.session.json) exists. */
+    workspaceInitializedProbe?: () => boolean;
+    /** Platform string (defaults to process.platform); injectable for tests. */
+    platform?: NodeJS.Platform;
 };
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

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

@@ -10,6 +10,7 @@ import { loadSkillRegistry } from '../skills/skill-registry.js';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
 import { planStatusLineInstall } from '../skills/statusline-settings-service.js';
 import { findProjectRoot } from '../config/config-safety.js';
+import { CLI_VERSION } from '../../shared/version.js';
 const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
 const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function defaultCodegraphProbe() {
@@ -26,15 +27,29 @@ function defaultCodegraphProbe() {
 }
 function defaultStatusLineInstalledProbe() {
     const projectRoot = findProjectRoot(process.cwd());
-    if (projectRoot === null)
-        return false;
+    // Check both scopes: a user may have installed the statusLine globally, which
+    // the project-only check would miss and falsely report as "not installed".
     try {
-        return planStatusLineInstall('project', projectRoot).alreadyInstalled;
+        if (projectRoot !== null && planStatusLineInstall('project', projectRoot).alreadyInstalled) {
+            return true;
+        }
+    }
+    catch {
+        /* fall through to global */
+    }
+    try {
+        return planStatusLineInstall('global').alreadyInstalled;
     }
     catch {
         return false;
     }
 }
+function defaultWorkspaceInitializedProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null)
+        return false;
+    return existsSync(join(projectRoot, '.peaks', '.session.json'));
+}
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
     /peaks\s+memory\s+extract[^\n]*--apply/,
@@ -203,6 +218,34 @@ export async function runDoctor(options = {}) {
             }
         }
     }
+    // Workspace guard: an active workflow presence (peaks-solo) with no workspace
+    // session means the skill was anchored but `peaks workspace init` never ran —
+    // the #1 reported failure where .peaks/ artifacts are never created. This
+    // turns the SKILL.md "MUST create the workspace" prose into an executable check.
+    const workspaceProbe = options.workspaceInitializedProbe ?? defaultWorkspaceInitializedProbe;
+    let workspaceInitialized = false;
+    try {
+        workspaceInitialized = workspaceProbe();
+    }
+    catch {
+        workspaceInitialized = false;
+    }
+    if (presence !== null && !workspaceInitialized) {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: false,
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/.session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+        });
+    }
+    else {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: true,
+            message: presence === null
+                ? 'No active skill presence; workspace guard not applicable'
+                : `Workspace session present for active skill ${presence.skill}`
+        });
+    }
     // Discoverability nudge: when a skill is actively orchestrating but the
     // out-of-band statusLine isn't installed, the user has no terminal-level
     // signal that Peaks is in control. Suggest installing it (non-failing).
@@ -230,6 +273,26 @@ export async function runDoctor(options = {}) {
                 : 'Peaks statusLine not installed (no active skill; install optional)'
         });
     }
+    // Runtime/platform diagnostic for the "statusLine shows nothing" reports.
+    // Surfaces (a) the running peaks version — a stale global install predating
+    // the statusLine feature is a common cause — and (b) on Windows, the fact that
+    // the bare `peaks statusline` command must resolve in the shell Claude Code
+    // spawns, which fails when the npm global bin dir is not on that shell's PATH.
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32') {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (win32): if the statusLine shows nothing in git bash, verify \`peaks\` resolves on PATH in the shell Claude Code uses (run \`peaks -v\` there), reinstall globally with \`npm i -g peaks-cli@latest\` if the version is older than ${CLI_VERSION}, then re-run \`peaks statusline install\` and reload Claude Code`
+        });
+    }
+    else {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (${platform}): statusLine command is \`peaks statusline\``
+        });
+    }
     const probe = options.codegraphProbe ?? defaultCodegraphProbe;
     try {
         const result = probe();

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -6,6 +6,7 @@ export type SkillPresence = {
     mode?: SkillPresenceMode;
     gate?: string;
     sessionId?: string;
+    claudeSessionId?: string;
     setAt: string;
     lastHeartbeat?: string;
 };

package/dist/src/services/skills/skill-presence-service.js

@@ -10,6 +10,16 @@ export const VALID_SKILL_PRESENCE_MODES = [
 export function isSkillPresenceMode(value) {
     return VALID_SKILL_PRESENCE_MODES.includes(value);
 }
+/**
+ * The current Claude Code session id, exposed to Bash tool calls via the
+ * CLAUDE_CODE_SESSION_ID environment variable. Stamping it onto the presence
+ * file lets the read-only status line tell whether the recorded skill belongs
+ * to the live session (show it) or a previous one (render idle).
+ */
+function getCurrentClaudeSessionId() {
+    const value = process.env.CLAUDE_CODE_SESSION_ID;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 const SESSION_FILE = '.peaks/.session.json';
 function resolveProjectRoot(override) {
@@ -40,12 +50,14 @@ export function exportSkillPresence(projectRootOverride) {
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
+    const claudeSessionId = getCurrentClaudeSessionId();
     const now = new Date().toISOString();
     const presence = {
         skill,
         ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
         ...(sessionId ? { sessionId } : {}),
+        ...(claudeSessionId ? { claudeSessionId } : {}),
         setAt: now,
         lastHeartbeat: now
     };

package/dist/src/services/skills/skill-statusline-service.d.ts

@@ -4,6 +4,7 @@ export type StatusLineStdin = {
         project_dir?: string;
     };
     cwd?: string;
+    session_id?: string;
 };
 export type StatusLineState = 'active' | 'idle' | 'stale' | 'invalid-presence';
 export type StatusLinePresence = {
@@ -11,6 +12,7 @@ export type StatusLinePresence = {
     mode?: string;
     gate?: string;
     setAt?: string;
+    claudeSessionId?: string;
 };
 export type StatusLineModel = {
     state: StatusLineState;

package/dist/src/services/skills/skill-statusline-service.js

@@ -65,7 +65,8 @@ function readPresenceReadOnly(projectRoot) {
                 skill: candidate.skill,
                 ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
                 ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
-                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {})
+                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {}),
+                ...(typeof candidate.claudeSessionId === 'string' ? { claudeSessionId: candidate.claudeSessionId } : {})
             },
             invalid: false
         };
@@ -87,6 +88,15 @@ export function buildStatusLineModel(stdin, nowMs) {
     if (presence === null) {
         return { state: 'idle', projectRoot, presence: null, ageMs: null };
     }
+    // Session binding: when the presence was stamped with a Claude session id and
+    // the live session (from stdin) is a different one, the recorded skill belongs
+    // to a previous session — render idle instead of a stale "active" skill. When
+    // either id is absent (legacy presence, or harness that omits session_id) we
+    // fall back to the time-based behavior below for backward compatibility.
+    const liveSessionId = typeof stdin?.session_id === 'string' && stdin.session_id.length > 0 ? stdin.session_id : null;
+    if (presence.claudeSessionId && liveSessionId && presence.claudeSessionId !== liveSessionId) {
+        return { state: 'idle', projectRoot, presence: null, ageMs: null };
+    }
     const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
     const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
     const state = ageMs !== null && ageMs > STALE_THRESHOLD_MS ? 'stale' : 'active';

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.0";
+export declare const CLI_VERSION = "1.2.2";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.0";
+export const CLI_VERSION = "1.2.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/schemas/doctor-report.schema.json

@@ -14,7 +14,7 @@
           "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), statusline:<topic> (whether the out-of-band Claude Code statusLine is installed), 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)."
+            "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)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }

package/skills/peaks-solo/SKILL.md

@@ -44,9 +44,35 @@ peaks-solo (orchestrate only)
 
 ## Peaks-Cli Startup sequence (MANDATORY — execute in order)
 
-### Peaks-Cli Step 1: Mode selection (MUST run before presence:set)
+### Peaks-Cli Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
 
-When the user invokes Peaks-Cli Solo without explicitly naming an execution profile, use `AskUserQuestion` BEFORE any other action. Present the recommended full-auto path as the first/default option with a practical description for each:
+The instant Peaks-Cli Solo is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
+
+```bash
+# Session ID is auto-generated when omitted; the command returns it in the JSON output
+peaks workspace init --project <repo> --json
+peaks skill presence:set peaks-solo --project <repo> --gate startup
+```
+
+If `workspace init` fails with "required option '--session-id' not specified", the CLI version predates auto-generation. Generate a session ID manually and pass it:
+
+```bash
+SESSION_ID="$(date +%Y-%m-%d)-session-$(openssl rand -hex 3)"
+peaks workspace init --project <repo> --session-id "$SESSION_ID" --json
+peaks skill presence:set peaks-solo --project <repo> --gate startup
+```
+
+> `<repo>` is the **git project root** (the directory containing `.git`). In a monorepo / single-repo-multi-package layout, this is the repo root, NOT a sub-package — `.peaks/` lives at the repo root so every package shares one workspace. If unsure, run `git rev-parse --show-toplevel` and use that path. Never let `.peaks/` land inside a sub-package directory.
+
+**There is no request too lightweight to skip this.** "分析下这个项目", "看一下代码", "分析项目", "解释一下架构", a one-line question — all of them still create the workspace and set presence first. The workspace is cheap; a missing `.peaks/` is the #1 reported failure.
+
+**Anti-bail-out rule (BLOCKING):** You MUST NOT exit the peaks-solo workflow, hand control back, or produce a final answer before Step 0 has run. If you catch yourself thinking "this is just analysis, I don't need the workflow" — STOP. Run Step 0, set presence, then continue. A pure-analysis request runs the **lightweight analysis branch** (project scan + standards dry-run + handoff with a Standards-increment section), but it still anchors the workspace and keeps presence active. Declining to anchor is a workflow violation.
+
+`presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
+
+### Peaks-Cli Step 1: Mode selection
+
+After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Cli Solo without explicitly naming an execution profile, use `AskUserQuestion` to pick the profile. Present the recommended full-auto path as the first/default option with a practical description for each:
 
 1. **Full auto (Recommended)** — Peaks-Cli handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
 2. **Assisted** — Peaks-Cli proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
@@ -66,9 +92,9 @@ Map the user's selection to the `--mode` flag value (used by `peaks skill presen
 
 If the user already names a profile in their invocation (e.g. `/peaks-solo --full-auto`, "用全自动模式"), skip this question and use the named profile directly.
 
-### Peaks-Cli Step 2: Set skill presence
+### Peaks-Cli Step 2: Re-set skill presence with the chosen mode
 
-Only after the mode is known (user selected or explicitly named), run:
+Step 0 already set presence with no mode. Now that the mode is known (user selected or explicitly named), re-run presence:set so the header/status line shows the profile:
 
 ```bash
 peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
@@ -144,7 +170,7 @@ For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` t
 
 ### Workspace initialization gate
 
-Before ANY role handoff or artifact write, Peaks-Cli Solo MUST create the workspace. 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/.session.json`.
 
 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.
 
@@ -760,7 +786,7 @@ Use `standards init` for first-time creation and `standards update` for existing
 
 Do not hand-write standards file mutations inside the skill.
 
-For project-analysis requests such as "分析项目", the handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
+For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-solo` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
 
 - whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
 - which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;

package/skills/peaks-txt/SKILL.md

@@ -118,7 +118,7 @@ Stable memory body.
 <!-- peaks-memory:end -->
 ```
 
-The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact> --apply` only after the user or active profile allows durable project memory writes.
+The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact>` to write durable project memories; pass `--dry-run` to preview without writing.
 
 ## Matt Pocock skills integration
 
@@ -190,13 +190,13 @@ peaks understand show --project <repo> --json
 # 4. Discover external capabilities before recommending memory or context tools
 peaks capabilities --json
 
-# 5. Memory extraction — dry-run by default, apply only when authorized
-peaks memory extract --project <repo> --artifact <artifact-path> --dry-run --json
-peaks memory extract --project <repo> --artifact <artifact-path> --apply --json
+# 5. Memory extraction — writes by default, use --dry-run to preview
+peaks memory extract --project <repo> --artifact <artifact-path> --json
+peaks memory extract --project <repo> --artifact <artifact-path> --dry-run --json   # preview only
 peaks skill presence:clear --project <repo>                      # handoff capsule complete, remove presence indicator
 ```
 
-The final `--apply` call requires explicit user or profile authorization. Without it, keep the capsule under `.peaks/<session-id>/txt/` and reference artifact paths from other roles instead of duplicating their content.
+The default `peaks memory extract` call writes to `.peaks/memory`. Pass `--dry-run` to preview without writing.
 
 ### Transition verification gates (MANDATORY — run the command, see the output)