peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/workflow/workflow-state-store.js

@@ -0,0 +1,95 @@
+/**
+ * Slice 2026-06-13-peaks-workflow-skip — workflow state store.
+ *
+ * Per-slice ephemeral runtime state, keyed by rid. Lives under
+ * `.peaks/_runtime/<sessionId>/workflow-state/<rid>.json` (gitignored
+ * alongside the rest of `.peaks/_runtime/`).
+ *
+ * Today only the skip-marker shape is persisted. Future workflow-edit
+ * primitives (e.g. `peaks workflow inject`, `peaks workflow unskip`)
+ * can extend the schema additively.
+ *
+ * Design:
+ *   - Synchronous read (the state file is tiny, < 200 bytes; not worth
+ *     an async I/O layer for it).
+ *   - Synchronous write (same rationale; the file is in the user's
+ *     own `.peaks/_runtime/` and the write is bounded by the
+ *     dispatcher that already has the file handle).
+ *   - Tolerate malformed JSON: returns null on parse error so the
+ *     caller can treat "no state" as "no skip applied" rather than
+ *     blowing up the workflow.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const STATE_FILE_NAME = 'workflow-state.json';
+function stateFilePath(projectRoot, sessionId, rid) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'workflow-state', `${rid}.json`);
+}
+/**
+ * Read the skip-state for a rid, or `null` if no state file exists or
+ * the file is malformed. The caller is expected to treat `null` as
+ * "no skip applied; evaluate all gates normally".
+ */
+export function readSkipState(projectRoot, sessionId, rid) {
+    const path = stateFilePath(projectRoot, sessionId, rid);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isWorkflowSkipState(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Write (or overwrite) the skip-state for a rid. Returns the absolute
+ * path to the file that was written. Caller is responsible for
+ * surfacing this in the envelope as `persistedTo`.
+ */
+export function writeSkipState(projectRoot, sessionId, state) {
+    const path = stateFilePath(projectRoot, sessionId, state.rid);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    return path;
+}
+/**
+ * Delete the skip-state file for a rid. Idempotent: missing file is
+ * a no-op (returns false). Used by `peaks workflow unskip` (v2) and
+ * by the rollback path of `applySkip` if the caller passes
+ * `--dry-run` and we want to clean up any preview state.
+ */
+export function deleteSkipState(projectRoot, sessionId, rid) {
+    const path = stateFilePath(projectRoot, sessionId, rid);
+    if (!existsSync(path)) {
+        return false;
+    }
+    unlinkSync(path);
+    return true;
+}
+function isWorkflowSkipState(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    if (typeof v.rid !== 'string')
+        return false;
+    if (!Array.isArray(v.skippedGates))
+        return false;
+    if (!v.skippedGates.every((g) => typeof g === 'string'))
+        return false;
+    if (typeof v.skipReason !== 'string')
+        return false;
+    if (typeof v.skipAppliedAt !== 'string')
+        return false;
+    if (typeof v.skipAppliedBy !== 'string')
+        return false;
+    if (v.callerKind !== 'human' && v.callerKind !== 'llm' && v.callerKind !== 'script')
+        return false;
+    return true;
+}

package/dist/services/workspace/claude-settings-template.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 declare 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 declare 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 declare function templateContentMatches(generated: string, onDisk: string): boolean;
+type ClaudeHookCommand = {
+    type: 'command';
+    command: string;
+};
+type ClaudePreToolUseEntry = {
+    matcher: string;
+    hooks: ClaudeHookCommand[];
+};
+type ClaudeSettingsLocal = {
+    hooks: {
+        PreToolUse: ClaudePreToolUseEntry[];
+    };
+};
+/**
+ * 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 declare function buildClaudeSettingsLocalJson(): ClaudeSettingsLocal;
+export {};

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;