peaks-cli 1.4.2 → 2.0.1

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

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { assertValidSessionId } from './sid-naming-guard.js';
+const ARCHIVE_ROOT = '_archive';
+const RUNTIME_DIR = '_runtime';
+function toPosix(p) {
+    return p.split(sep).join('/');
+}
+export function planArchive(projectRoot, sid) {
+    assertValidSessionId(sid);
+    const yyyyMm = sid.slice(0, 7);
+    const sourcePath = join(projectRoot, '.peaks', RUNTIME_DIR, sid);
+    const targetPath = join(projectRoot, '.peaks', ARCHIVE_ROOT, yyyyMm, sid);
+    return {
+        sid,
+        sourcePath: toPosix(sourcePath),
+        targetPath: toPosix(targetPath),
+        sourceExists: existsSync(sourcePath),
+    };
+}
+export function archiveSession(projectRoot, options) {
+    const plan = planArchive(projectRoot, options.sid);
+    if (!plan.sourceExists) {
+        return { moved: [], skipped: [{ sid: options.sid, reason: 'source does not exist' }] };
+    }
+    if (!options.apply) {
+        return { moved: [], skipped: [{ sid: options.sid, reason: 'dry-run' }] };
+    }
+    mkdirSync(join(plan.targetPath, '..'), { recursive: true });
+    renameSync(plan.sourcePath, plan.targetPath);
+    return { moved: [options.sid], skipped: [] };
+}

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

@@ -0,0 +1,41 @@
+export interface RuntimeSessionInfo {
+    sid: string;
+    mtimeMs: number;
+    ageHours: number;
+}
+export interface CleanupOptions {
+    olderThanHours: number;
+    graceHours: number;
+}
+export interface CleanupResult {
+    deleted: string[];
+    skipped: {
+        sid: string;
+        reason: string;
+    }[];
+}
+export declare function runtimeDirPath(projectRoot: string): string;
+export declare function listRuntimeSessions(projectRoot: string): RuntimeSessionInfo[];
+export declare function planRuntimeCleanup(sessions: RuntimeSessionInfo[], options: CleanupOptions): {
+    eligible: string[];
+    skipped: {
+        sid: string;
+        reason: string;
+    }[];
+};
+export declare function executeRuntimeCleanup(projectRoot: string, options: CleanupOptions & {
+    apply: boolean;
+}): CleanupResult;
+export interface SubAgentInvalidPlan {
+    invalid: string[];
+    invalidSidFormat: string[];
+}
+export declare function subAgentDirPath(projectRoot: string): string;
+export declare function invalidSidsArchivePath(projectRoot: string): string;
+export declare function listInvalidSubAgentSids(projectRoot: string): string[];
+export declare function executeSubAgentClean(projectRoot: string, options: {
+    apply: boolean;
+}): {
+    moved: string[];
+    skipped: string[];
+};

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

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isBareSid, isValidSessionId } from './sid-naming-guard.js';
+const RUNTIME_DIR = '_runtime';
+export function runtimeDirPath(projectRoot) {
+    return join(projectRoot, '.peaks', RUNTIME_DIR);
+}
+export function listRuntimeSessions(projectRoot) {
+    const dir = runtimeDirPath(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+        const sid = e.name;
+        const fullPath = join(dir, sid);
+        const stat = statSync(fullPath);
+        const ageHours = (now - stat.mtimeMs) / (1000 * 3600);
+        return { sid, mtimeMs: stat.mtimeMs, ageHours };
+    });
+}
+export function planRuntimeCleanup(sessions, options) {
+    const eligible = [];
+    const skipped = [];
+    const cutoffHours = options.olderThanHours + options.graceHours;
+    for (const s of sessions) {
+        if (s.ageHours >= cutoffHours) {
+            eligible.push(s.sid);
+        }
+        else {
+            skipped.push({ sid: s.sid, reason: `fresh: age=${s.ageHours.toFixed(1)}h < cutoff=${cutoffHours}h` });
+        }
+    }
+    return { eligible, skipped };
+}
+export function executeRuntimeCleanup(projectRoot, options) {
+    const sessions = listRuntimeSessions(projectRoot);
+    const plan = planRuntimeCleanup(sessions, options);
+    if (options.apply) {
+        const dir = runtimeDirPath(projectRoot);
+        for (const sid of plan.eligible) {
+            rmSync(join(dir, sid), { recursive: true, force: true });
+        }
+    }
+    return { deleted: plan.eligible, skipped: plan.skipped };
+}
+const SUBAGENT_DIR = '_sub_agents';
+const INVALID_ARCHIVE = '_archive/invalid-sids';
+export function subAgentDirPath(projectRoot) {
+    return join(projectRoot, '.peaks', SUBAGENT_DIR);
+}
+export function invalidSidsArchivePath(projectRoot) {
+    return join(projectRoot, '.peaks', INVALID_ARCHIVE);
+}
+export function listInvalidSubAgentSids(projectRoot) {
+    const dir = subAgentDirPath(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .filter((name) => isBareSid(name) || !isValidSessionId(name));
+}
+export function executeSubAgentClean(projectRoot, options) {
+    const invalid = listInvalidSubAgentSids(projectRoot);
+    const moved = [];
+    if (options.apply && invalid.length > 0) {
+        const archiveDir = invalidSidsArchivePath(projectRoot);
+        mkdirSync(archiveDir, { recursive: true });
+        for (const sid of invalid) {
+            const from = join(subAgentDirPath(projectRoot), sid);
+            const to = join(archiveDir, sid);
+            if (existsSync(to)) {
+                // collision — append timestamp suffix
+                const stamped = `${sid}-${Date.now()}`;
+                renameSync(from, join(archiveDir, stamped));
+            }
+            else {
+                renameSync(from, to);
+            }
+            moved.push(sid);
+        }
+    }
+    return { moved: options.apply ? moved : invalid, skipped: [] };
+}

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

@@ -17,6 +17,14 @@ export type WorkspaceInitOptions = {
      * (live sub-agent progress, spawn records).
      */
     changeId?: string;
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: opt out of writing the
+     * consumer-project `.claude/settings.local.json` file. Default
+     * (`false`) writes the file so the [Fact-Forcing Gate] is bypassed
+     * for tool calls inside `.peaks/**`. The CLI surfaces this as
+     * `--no-claude-hooks`.
+     */
+    noClaudeHooks?: boolean;
 };
 export type WorkspaceInitReport = {
     sessionId: string;
@@ -27,6 +35,22 @@ export type WorkspaceInitReport = {
     previousSessionId: string | null;
     changeId: string | null;
     changeIdAction: 'bound' | 'preserved' | 'none';
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: what the consumer-project
+     * `.claude/settings.local.json` materialization did this call.
+     *   - written:        the file was freshly written
+     *   - refreshed:      the file already existed and was rewritten to
+     *                     match the current peaks-cli release's template
+     *   - already-current: the file already matched the template; no
+     *                     rewrite needed
+     *   - skipped:        the caller passed noClaudeHooks=true
+     * The LLM and the user both see this in the JSON envelope so they
+     * can decide whether the bypass is in effect.
+     */
+    claudeSettings: {
+        action: 'written' | 'refreshed' | 'already-current' | 'skipped';
+        path: string;
+    };
 };
 export declare class InvalidSessionIdError extends Error {
     readonly code = "INVALID_SESSION_ID";

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

@@ -1,8 +1,10 @@
-import { mkdir } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
 import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
 import { setCurrentChangeId } from '../../shared/change-id.js';
+import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME } from './claude-settings-template.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
 const PROHIBITED_SUFFIXES = ['session', 'work', 'task', 'test', 'temp', 'tmp'];
 // Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
@@ -173,6 +175,126 @@ export async function initWorkspace(options) {
         bound,
         previousSessionId,
         changeId: resolvedChangeId,
-        changeIdAction
+        changeIdAction,
+        claudeSettings: await materializeClaudeSettingsLocal(options.projectRoot, options.noClaudeHooks === true)
     };
 }
+/**
+ * The peaks-managed snippet appended to the consumer project's
+ * `.peaks/.gitignore` so the local-only settings file never lands
+ * in a commit. Marked with a managed-by header so we can detect (and
+ * not double-append) on subsequent inits.
+ */
+const PEAKS_GITIGNORE_HEADER = '# >>> peaks-cli managed snippet (slice 2.0.1-bug3) — do not edit by hand';
+const PEAKS_GITIGNORE_FOOTER = '# <<< peaks-cli managed snippet';
+const PEAKS_GITIGNORE_SNIPPET = [
+    PEAKS_GITIGNORE_HEADER,
+    '# Consumer-project .claude/settings.local.json: written by `peaks workspace init`',
+    '# to bypass Claude Code [Fact-Forcing Gate] for .peaks/** writes. Local-only.',
+    '.claude/settings.local.json',
+    PEAKS_GITIGNORE_FOOTER,
+    ''
+].join('\n');
+/**
+ * Materialize the consumer-project `.claude/settings.local.json` and
+ * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
+ * `claudeSettings` descriptor that the caller surfaces in the JSON
+ * envelope.
+ *
+ * The function is idempotent: re-running on an already-materialized
+ * project is a no-op (the file is rewritten only when its content
+ * diverges from the current peaks-cli release's template, which
+ * keeps the consumer up to date as the template evolves).
+ *
+ * Even when the caller passes `noClaudeHooks: true`, the function
+ * still writes a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has an offline
+ * recovery path: copy the file contents into
+ * `.claude/settings.local.json` manually. The recovery path is
+ * documented in
+ * `skills/peaks-solo/references/anchoring-and-session-info.md`.
+ */
+async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks) {
+    const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
+    const settingsPath = join(projectRoot, settingsRel);
+    const template = buildClaudeSettingsLocalJson();
+    const serialized = JSON.stringify(template, null, 2) + '\n';
+    // Always drop a copy of the template under .peaks/ so the
+    // --no-claude-hooks recovery flow has a known source-of-truth on
+    // disk. The file is gitignored by the snippet below.
+    await writeOfflineTemplateCopy(projectRoot, serialized);
+    if (noClaudeHooks) {
+        return { action: 'skipped', path: settingsRel };
+    }
+    // Best-effort: ensure .claude/ exists, then write the file. We do
+    // not assertSafeSettingsPath here (the .claude/ dir is local to
+    // the consumer and we trust it on first init; the existing
+    // hooks-settings-service applies the safety check for the Bash
+    // gate-enforce path).
+    await mkdir(join(projectRoot, '.claude'), { recursive: true });
+    let action = 'written';
+    if (existsSync(settingsPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(settingsPath, 'utf8');
+            if (existing === serialized) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as "needs refresh" so the consumer
+            // always ends up with a valid template on disk.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(settingsPath, serialized, 'utf8');
+    }
+    // Ensure the consumer's .peaks/.gitignore covers the local-only
+    // settings file. The snippet is appended only when the header is
+    // missing, so subsequent inits do not double-append.
+    await upsertPeaksGitignoreSnippet(projectRoot);
+    return { action, path: settingsRel };
+}
+/**
+ * Always write (or refresh) a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has a known
+ * source-of-truth on disk for the manual recovery flow. This file is
+ * tracked in git (not gitignored) because it is the recovery anchor
+ * — if the consumer needs to re-create their .claude/settings.local.json
+ * they can copy this file verbatim.
+ */
+async function writeOfflineTemplateCopy(projectRoot, serialized) {
+    const copyPath = join(projectRoot, '.peaks', '.claude-settings-template.json');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    await writeFile(copyPath, serialized, 'utf8');
+}
+/**
+ * Append the peaks-managed `.claude/settings.local.json` snippet to
+ * the consumer project's `.peaks/.gitignore`. Preserves any user-
+ * managed entries above the snippet. Idempotent: re-running on a
+ * project that already has the snippet is a no-op.
+ */
+async function upsertPeaksGitignoreSnippet(projectRoot) {
+    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    let existing = '';
+    if (existsSync(gitignorePath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            existing = await readFile(gitignorePath, 'utf8');
+        }
+        catch {
+            existing = '';
+        }
+    }
+    if (existing.includes(PEAKS_GITIGNORE_HEADER)) {
+        return;
+    }
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const next = existing + separator + (existing.length > 0 ? '\n' : '') + PEAKS_GITIGNORE_SNIPPET;
+    await writeFile(gitignorePath, next, 'utf8');
+}

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

@@ -0,0 +1,7 @@
+export declare function isLegacyDecisionDotfile(name: string): boolean;
+export declare function stateDirPath(projectRoot: string): string;
+export interface CollectResult {
+    moved: string[];
+    skipped: string[];
+}
+export declare function collectLegacyDecisionDotfiles(projectRoot: string): CollectResult;

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

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
+import { join, posix } from 'node:path';
+/**
+ * Spec §8.4 + §8.5 — `.peaks/_state/` collects one-time decision dotfiles.
+ * Migrates from legacy `.peaks/<name>` flat layout.
+ *
+ * `stateDirPath` returns a POSIX-normalized logical path so callers and tests
+ * can compare against a platform-independent string (the .peaks tree is a
+ * config key, not a direct fs call). `mkdirSync` / `renameSync` below use
+ * the platform-native `join` so files actually land on disk.
+ */
+const LEGACY_DOTFILES = [
+    '.peaks-init-hooks-decision.json',
+    '.peaks-openspec-opt-in.json',
+];
+const STATE_DIR_NAME = '_state';
+export function isLegacyDecisionDotfile(name) {
+    return LEGACY_DOTFILES.includes(name);
+}
+export function stateDirPath(projectRoot) {
+    return posix.join(projectRoot, '.peaks', STATE_DIR_NAME);
+}
+export function collectLegacyDecisionDotfiles(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    // Use the platform-native join for actual filesystem operations;
+    // `stateDirPath` (POSIX) is only the public/portable surface for callers.
+    const stateDir = join(projectRoot, '.peaks', STATE_DIR_NAME);
+    mkdirSync(stateDir, { recursive: true });
+    const moved = [];
+    const skipped = [];
+    for (const name of LEGACY_DOTFILES) {
+        const from = join(peaksDir, name);
+        const to = join(stateDir, name);
+        if (!existsSync(from))
+            continue;
+        if (existsSync(to)) {
+            throw new Error(`DOTFILE_COLLISION: ${name} already exists in ${stateDir} (${readFileSync(to, 'utf8').length} bytes); refusing to overwrite`);
+        }
+        renameSync(from, to);
+        moved.push(name);
+    }
+    return { moved, skipped };
+}

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

@@ -303,7 +303,10 @@ export function setCurrentChangeId(projectRoot, changeId, options = {}) {
             catch { /* best effort */ }
         }
     }
-    symlinkSync(targetDir, bindingPath);
+    // On Windows, use a 'junction' (directory hard link) which doesn't
+    // require developer mode / admin. POSIX uses a regular 'dir' symlink.
+    const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+    symlinkSync(targetDir, bindingPath, linkType);
 }
 /**
  * Canonical on-disk path to a change-id's reviewable artifacts

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.4.2";
+export declare const CLI_VERSION = "2.0.1";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.4.2";
+export const CLI_VERSION = "2.0.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.4.2",
+  "version": "2.0.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",
@@ -33,7 +33,12 @@
     "!skills/**/test-prompts.json",
     "!skills/**/.DS_Store",
     "output-styles/**",
-    "schemas/*.json"
+    "schemas/*.json",
+    ".claude-plugin/**",
+    "README.md",
+    "README-en.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
@@ -54,6 +59,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "@alibaba-group/open-code-review": "1.3.1",
     "@colbymchenry/codegraph": "0.7.10",
     "commander": "^12.1.0",
     "fzf": "^0.5.2",

package/schemas/doctor-report.schema.json

@@ -13,7 +13,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration|L3):[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), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
           },
           "ok": { "type": "boolean" },