peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/workspace/claude-settings-template.js

@@ -0,0 +1,254 @@
+/**
+ * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
+ * consumer-project `.claude/settings.local.json` file.
+ *
+ * The template is a PreToolUse hook allow-list that bypasses the
+ * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
+ * the peaks-managed `.peaks/` workspace. Without this bypass,
+ * `peaks workspace init` (Step 0 of every peaks-code session) is
+ * unrunnable in a consumer project because the gate blocks the very
+ * first Write.
+ *
+ * The template is a pure-data function (no filesystem, no clock) so
+ * it can be unit-tested in isolation and so the on-disk file matches
+ * the in-memory template byte-for-byte.
+ *
+ * One matcher is emitted:
+ *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
+ *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
+ *      for those paths, non-zero (deny → fall through to gate) for
+ *      everything else.
+ *
+ * The previous `Bash` matcher (which whitelisted a fixed `peaks
+ * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
+ * [Fact-Forcing Gate] is an Edit/Write concern (it forces the LLM
+ * to quote user instructions before any file write), and the Bash
+ * matcher was emitting `process.exit(1)` with no stderr on every
+ * non-peaks Bash call — a non-blocking "No stderr output" noise
+ * decoration in the Claude Code UI even though the underlying tool
+ * call still proceeded. Bash command enforcement is now owned by
+ * `peaks gate enforce`, which `peaks hooks install` injects into the
+ * consumer project's `.claude/settings.json` and which exits 0
+ * silently for any command not guarded by a registered SOP gate.
+ */
+export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
+/**
+ * Informational version of the offline template shape. Bumped when the
+ * template's hooks tree (matchers, allow-list content, wrapper format)
+ * changes in a way that should trigger a refresh of stale on-disk
+ * copies. The comparator (`templateContentMatches`) is the source of
+ * truth for refresh decisions — this constant exists so a developer
+ * reading the diff can correlate a template change with a deliberate
+ * bump. Future work may write a version-marker file to short-circuit
+ * the comparator; for now the constant is informational only.
+ *
+ * History:
+ *   1.0.0 — initial template with `Write|Edit|MultiEdit` and `Bash`
+ *           matchers (slice 2.0.1-bug3-fact-forcing-bypass)
+ *   1.1.0 — added `node -e "..."` wrapper contract
+ *           (slice fix-claude-settings-template-hook-node-wrapper)
+ *   1.2.0 — removed the `Bash` matcher; Edit/Write fact-forcing
+ *           bypass is the only emit. Bash enforcement is owned by
+ *           `peaks gate enforce` in `settings.json`.
+ *   1.3.0 — added the v3.1.2 `Bash` PreToolUse matcher that runs
+ *           `peaks code gate-step-08 --project .` (Step 0.8 mechanical
+ *           gate). The existing Write|Edit|MultiEdit matcher is
+ *           preserved. The new matcher's exit code is the load-bearing
+ *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
+ */
+export const TEMPLATE_VERSION = '1.3.0';
+/**
+ * Compare two serialized template strings for semantic equivalence.
+ *
+ * Returns `true` iff both strings parse to objects whose
+ * `hooks.PreToolUse` arrays are structurally identical (same length;
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ *
+ * Returns `false` on any `JSON.parse` error, shape mismatch, or
+ * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
+ * the result — the comparison is on the parsed AST, not on bytes.
+ *
+ * This is the comparator `initWorkspace` uses to decide whether to
+ * refresh a stale `.peaks/.claude-settings-template.json` on disk.
+ */
+export function templateContentMatches(generated, onDisk) {
+    let parsedGenerated;
+    let parsedOnDisk;
+    try {
+        parsedGenerated = JSON.parse(generated);
+    }
+    catch {
+        return false;
+    }
+    try {
+        parsedOnDisk = JSON.parse(onDisk);
+    }
+    catch {
+        return false;
+    }
+    if (!isTemplateShape(parsedGenerated) || !isTemplateShape(parsedOnDisk)) {
+        return false;
+    }
+    const generatedEntries = parsedGenerated.hooks.PreToolUse;
+    const onDiskEntries = parsedOnDisk.hooks.PreToolUse;
+    if (generatedEntries.length !== onDiskEntries.length) {
+        return false;
+    }
+    for (let i = 0; i < generatedEntries.length; i += 1) {
+        const a = generatedEntries[i];
+        const b = onDiskEntries[i];
+        if (a.matcher !== b.matcher) {
+            return false;
+        }
+        if (!sameHooksArray(a.hooks, b.hooks)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isTemplateShape(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    if (typeof candidate.hooks !== 'object' || candidate.hooks === null) {
+        return false;
+    }
+    const hooksObj = candidate.hooks;
+    return Array.isArray(hooksObj.PreToolUse);
+}
+function sameHooksArray(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        const ha = a[i];
+        const hb = b[i];
+        if (ha.type !== hb.type || ha.command !== hb.command) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Wrap an inner JavaScript payload as a shell-evaluable `node -e "..."`
+ * one-liner. The returned string is what Claude Code writes verbatim
+ * into `.claude/settings.local.json` under the `command` field. Per
+ * Node.js docs (https://nodejs.org/api/process.html#processargv), when
+ * using `-e` there is no script-file slot, so `process.argv[1]` is the
+ * first user-passed extra argument. This is consistent across Windows,
+ * macOS, and Linux.
+ *
+ * Every `"` character in the inner JS must be JSON-escaped as `\\"`
+ * so that the surrounding wrapper `node -e "..."` parses correctly:
+ * the shell sees the escape and passes a literal `"` to Node. A
+ * single missed escape closes the wrapper early and the entire hook
+ * regresses to the bash-syntax-error class of bug.
+ *
+ * @param js Inner JavaScript payload. Must be a single statement or a
+ *           sequence of statements joined with `;`. The wrapper does
+ *           not insert any `;` between the payload and the closing
+ *           `"` because Node accepts a trailing expression with `;`
+ *           already terminated by the payload itself.
+ */
+function wrapAsNodeOneLiner(js) {
+    // Only `"` needs JSON-escaping: the wrapper uses double quotes, so an
+    // unescaped inner `"` would close the wrapper prematurely. Backslashes
+    // do NOT need escaping here — bash inside a `"..."` wrapper reduces
+    // `\\` to `\`, so any `\X` in the inner JS reaches Node as `\X`,
+    // which is what regex literals like `/\.peaks\//` need. Adding a
+    // second `\\` → `\\` pass would double-escape backslashes and break
+    // every regex literal the inner JS contains.
+    const escaped = js.replace(/"/g, '\\"');
+    return `node -e "${escaped}"`;
+}
+/**
+ * Build the Write|Edit|MultiEdit matcher command. The command reads
+ * the candidate file path from argv[2] and exits 0 iff the path
+ * contains `.peaks/_runtime/` or `.peaks/_runtime/<sessionId>/` (the change-id
+ * segment is the next path component after `.peaks/`). All other
+ * paths exit 1 so the gate fires normally.
+ *
+ * The matcher is intentionally narrow: it only fires for tools that
+ * take a `file_path` (Write/Edit/MultiEdit) and for the Bash
+ * subcommand allow-list. It does NOT silently allow arbitrary paths
+ * under `.peaks/_runtime/<sessionId>/` — only those matching the documented
+ * pattern. Future slice work can broaden the allow-list if the
+ * peaks-code workflow needs more paths.
+ */
+function buildWriteHookCommand() {
+    // Path-matching: allow when the path contains `.peaks/_runtime/`
+    // OR when the second `.peaks/` segment starts with anything that
+    // looks like a change-id (kebab-case slug). Exit 0 for allow, exit
+    // 1 for deny. The candidate path arrives on `process.argv[1]` per
+    // Node.js argv layout under `-e` (cross-platform consistent).
+    const js = 'const p=process.argv[1]||"";' +
+        'if(p.includes(".peaks/_runtime/"))process.exit(0);' +
+        'const m=p.match(/\\.peaks\\/([a-z0-9][a-z0-9.-]*)\\//);' +
+        'if(m&&m[1]&&m[1]!=="_runtime"&&m[1]!=="_dogfood"&&m[1]!=="_sub_agents"&&m[1]!=="memory"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
+        'process.exit(1)';
+    return wrapAsNodeOneLiner(js);
+}
+/**
+ * Build the full template object. The shape is the subset of Claude
+ * Code's `.claude/settings.local.json` schema that PreToolUse hooks
+ * need — we do not emit the `permissions` block because the fact-
+ * forcing gate is a core feature that PreToolUse hooks can short-
+ * circuit but that the `permissions` block cannot.
+ *
+ * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
+ * matcher is emitted. Bash command enforcement is the responsibility
+ * of `peaks gate enforce`, which `peaks hooks install` injects into
+ * `.claude/settings.json` (not `.claude/settings.local.json`).
+ */
+export function buildClaudeSettingsLocalJson() {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: 'Write|Edit|MultiEdit',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: buildWriteHookCommand()
+                        }
+                    ]
+                },
+                {
+                    // v3.1.2 Step 0.8 — Mechanical PreToolUse gate. Runs
+                    // `peaks code gate-step-08 --project .` before every Bash
+                    // tool call. Exit 0 = allow (with structured stdout
+                    // describing the decision + optional `Next: slice #N+1 of
+                    // M (<currentSlice>)` line when progress.json exists). Exit
+                    // 2 = block (stderr contains the BLOCKED: ... reason).
+                    // The existing Write|Edit|MultiEdit matcher is preserved.
+                    matcher: 'Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: buildBashGateStep08Command()
+                        }
+                    ]
+                }
+            ]
+        }
+    };
+}
+/**
+ * v3.1.2: build the Bash matcher command that runs `peaks code
+ * gate-step-08`. We invoke the CLI directly (not via `node -e "..."`)
+ * because the CLI is the only legitimate source of the structured
+ * decision + Next: slice context. Exit code is the load-bearing
+ * signal — 0 = allow, 2 = block. The hook installer is idempotent:
+ * `templateContentMatches` compares the parsed matcher entries, so
+ * re-running `peaks workspace init` on a project that already has the
+ * Bash hook is a no-op (already-current).
+ */
+function buildBashGateStep08Command() {
+    // The hook receives the tool call on stdin. We ignore stdin and
+    // delegate entirely to `peaks code gate-step-08`, which reads
+    // .peaks/_runtime/<sessionId>/job-shape.json and last-prompt.txt.
+    // `${CLAUDE_PROJECT_DIR}` resolves to the consumer project's root
+    // (Claude Code's standard convention).
+    return 'peaks code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
+}

package/dist/services/workspace/migrate-1-4-1-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004.
+ *
+ * Cleanup command for projects upgraded from peaks-loop 1.4.1 → 1.4.2.
+ *
+ * Slice 006 (1.4.0) moved the canonical per-session root to
+ * `.peaks/_runtime/<sid>/`. Per-request artifacts (PRD, RD, QA, SC requests)
+ * were written to the new root, but per-session artifacts (tech-doc.md,
+ * code-review.md, test-cases/<rid>.md, etc.) were kept at the legacy
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+ * `resolvePrerequisiteAbsolutePathWithFallback` accepts either location, so
+ * the functional behavior is correct, but the user's filesystem has visible
+ * dual-path duplication ("飘逸" — the user's term for the UX).
+ *
+ * R004 ships this command to physically move the legacy per-session files
+ * into the canonical `_runtime/<sid>/<role>/` location. After this runs,
+ * the project has a single canonical tree; the legacy `<sid>/<role>/`
+ * directories are removed (only if empty after the move).
+ *
+ * Default: dry-run. Pass `--apply` to actually move.
+ */
+export declare const PER_SESSION_ARTIFACT_TYPES: readonly ["rd/tech-doc.md", "rd/code-review.md", "rd/security-review.md", "rd/perf-baseline.md", "rd/bug-analysis.md", "qa/security-findings.md", "qa/performance-findings.md"];
+export declare const PER_REQUEST_ARTIFACT_TYPES: readonly ["qa/test-cases/<rid>.md", "qa/test-reports/<rid>.md"];
+export type MigrationPlanEntry = {
+    readonly sessionId: string;
+    readonly relativePath: string;
+    readonly from: string;
+    readonly to: string;
+    readonly sha256: string;
+    readonly reason: 'legacy-only' | 'identical-content-already-canonical' | 'content-mismatch' | 'no-legacy-file';
+};
+export type MigrationResult = {
+    readonly plan: ReadonlyArray<MigrationPlanEntry>;
+    readonly applied: boolean;
+    readonly movedCount: number;
+    readonly conflictCount: number;
+    readonly deletedEmptyDirs: ReadonlyArray<string>;
+    readonly errors: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+};
+export declare function planMigrate1_4_1(projectRoot: string): MigrationResult;
+export declare function applyMigrate1_4_1(projectRoot: string): MigrationResult;

package/dist/services/workspace/migrate-1-4-1-service.js

@@ -0,0 +1,195 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004.
+ *
+ * Cleanup command for projects upgraded from peaks-loop 1.4.1 → 1.4.2.
+ *
+ * Slice 006 (1.4.0) moved the canonical per-session root to
+ * `.peaks/_runtime/<sid>/`. Per-request artifacts (PRD, RD, QA, SC requests)
+ * were written to the new root, but per-session artifacts (tech-doc.md,
+ * code-review.md, test-cases/<rid>.md, etc.) were kept at the legacy
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+ * `resolvePrerequisiteAbsolutePathWithFallback` accepts either location, so
+ * the functional behavior is correct, but the user's filesystem has visible
+ * dual-path duplication ("飘逸" — the user's term for the UX).
+ *
+ * R004 ships this command to physically move the legacy per-session files
+ * into the canonical `_runtime/<sid>/<role>/` location. After this runs,
+ * the project has a single canonical tree; the legacy `<sid>/<role>/`
+ * directories are removed (only if empty after the move).
+ *
+ * Default: dry-run. Pass `--apply` to actually move.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+export const PER_SESSION_ARTIFACT_TYPES = [
+    'rd/tech-doc.md',
+    'rd/code-review.md',
+    'rd/security-review.md',
+    'rd/perf-baseline.md',
+    'rd/bug-analysis.md',
+    'qa/security-findings.md',
+    'qa/performance-findings.md',
+];
+export const PER_REQUEST_ARTIFACT_TYPES = [
+    'qa/test-cases/<rid>.md',
+    'qa/test-reports/<rid>.md',
+];
+import { createHash } from 'node:crypto';
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function enumerateLegacySessions(projectRoot) {
+    // Legacy per-session dirs: `.peaks/_runtime/<sid>/` (NOT `.peaks/_runtime/<sid>/`).
+    // We skip well-known non-session entries.
+    const SKIP = new Set(['memory', 'PROJECT.md', 'retrospective', 'scope', '.peaks-init-hooks-decision.json', 'session.json', '.session.json', '_runtime', '_sub_agents', 'change', 'caller', 'callers', 'sop-state', 'system', 'active-skill.json', '.active-skill.json']);
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(peaksRoot)) {
+        if (SKIP.has(entry))
+            continue;
+        if (entry.startsWith('.'))
+            continue;
+        // Treat any directory under .peaks/ that doesn't match a known non-session
+        // directory as a candidate session id. The session id is a dated prefix.
+        if (entry.match(/^\d{4}-\d{2}-\d{2}-session-/))
+            out.push(entry);
+    }
+    return out;
+}
+function listRequestIdsForSession(legacySessionRoot) {
+    // Per-request artifacts use file id like `001-r001.md`. We scan the
+    // requests dir to find existing rids.
+    const ids = new Set();
+    for (const role of ['prd', 'rd', 'qa', 'sc']) {
+        const dir = join(legacySessionRoot, role, 'requests');
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            const m = f.match(/^\d+-(r\d+)\.md$/);
+            if (m && m[1])
+                ids.add(m[1]);
+        }
+    }
+    return [...ids];
+}
+function buildPlan(projectRoot) {
+    const plan = [];
+    for (const sid of enumerateLegacySessions(projectRoot)) {
+        const legacyRoot = join(projectRoot, '.peaks', sid);
+        const canonicalRoot = join(projectRoot, '.peaks', '_runtime', sid);
+        // Per-session files (no <rid> template).
+        for (const rel of PER_SESSION_ARTIFACT_TYPES) {
+            const from = join(legacyRoot, rel);
+            if (!existsSync(from))
+                continue;
+            const content = readFileSync(from, 'utf8');
+            const hash = sha256(content);
+            const to = join(canonicalRoot, rel);
+            if (existsSync(to)) {
+                const existing = readFileSync(to, 'utf8');
+                if (sha256(existing) === hash) {
+                    plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'identical-content-already-canonical' });
+                }
+                else {
+                    plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'content-mismatch' });
+                }
+            }
+            else {
+                plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'legacy-only' });
+            }
+        }
+        // Per-request files (with <rid> template).
+        const rids = listRequestIdsForSession(legacyRoot);
+        for (const rel of PER_REQUEST_ARTIFACT_TYPES) {
+            for (const rid of rids) {
+                const expanded = rel.replace('<rid>', rid);
+                const from = join(legacyRoot, expanded);
+                if (!existsSync(from))
+                    continue;
+                const content = readFileSync(from, 'utf8');
+                const hash = sha256(content);
+                const to = join(canonicalRoot, expanded);
+                if (existsSync(to)) {
+                    const existing = readFileSync(to, 'utf8');
+                    if (sha256(existing) === hash) {
+                        plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'identical-content-already-canonical' });
+                    }
+                    else {
+                        plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'content-mismatch' });
+                    }
+                }
+                else {
+                    plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'legacy-only' });
+                }
+            }
+        }
+    }
+    return plan;
+}
+export function planMigrate1_4_1(projectRoot) {
+    const plan = buildPlan(projectRoot);
+    return {
+        plan,
+        applied: false,
+        movedCount: 0,
+        conflictCount: plan.filter((p) => p.reason === 'content-mismatch').length,
+        deletedEmptyDirs: [],
+        errors: [],
+    };
+}
+export function applyMigrate1_4_1(projectRoot) {
+    const plan = buildPlan(projectRoot);
+    const errors = [];
+    let movedCount = 0;
+    const deletedEmptyDirs = [];
+    const movedFiles = [];
+    for (const entry of plan) {
+        try {
+            if (entry.reason === 'legacy-only') {
+                // Move: ensure target dir exists, then rename.
+                mkdirSync(join(entry.to, '..'), { recursive: true });
+                renameSync(entry.from, entry.to);
+                movedFiles.push(entry.from);
+                movedCount++;
+            }
+            else if (entry.reason === 'identical-content-already-canonical') {
+                // Skip the move but delete the duplicate source.
+                try {
+                    rmSync(entry.from);
+                }
+                catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            }
+            else if (entry.reason === 'content-mismatch') {
+                // Conflict: do NOT delete the source. Mark for manual review.
+                errors.push({ path: entry.from, message: `content mismatch; review manually (target ${entry.to})` });
+            }
+        }
+        catch (err) {
+            errors.push({ path: entry.from, message: err.message });
+        }
+    }
+    // After all moves, clean up legacy session dirs. They're now empty
+    // (all files moved; per-role subdirs are also empty). Force-remove the
+    // entire tree — if any non-empty dir remains it's a pre-existing file
+    // that wasn't part of the migrate plan, which is fine to keep.
+    for (const sid of new Set(plan.map((p) => p.sessionId))) {
+        const legacyRoot = join(projectRoot, '.peaks', sid);
+        try {
+            if (existsSync(legacyRoot)) {
+                rmSync(legacyRoot, { recursive: true, force: true });
+                deletedEmptyDirs.push(legacyRoot);
+            }
+        }
+        catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    return {
+        plan,
+        applied: true,
+        movedCount,
+        conflictCount: plan.filter((p) => p.reason === 'content-mismatch').length,
+        deletedEmptyDirs,
+        errors,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { MigrateOptions, MigrateResult } from './migrate-types.js';
+export declare function migrateWorkspace(options: MigrateOptions): Promise<MigrateResult>;