peaks-loop 4.0.5 → 4.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.5",
+  "version": "4.0.7",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -98,9 +98,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.9",
-    "peaks-loop-shared": "0.0.35",
-    "peaks-loop-shared-channel": "0.0.14"
+    "peaks-loop-shared-channel": "0.0.16",
+    "peaks-loop-shared": "0.0.37",
+    "peaks-loop-mut": "0.1.12"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"

package/scripts/install-skills.mjs

@@ -762,6 +762,143 @@ export function installBundledOutputStyles(options = {}) {
   return { installed, skipped };
 }
 
+/**
+ * Slice 2026-08-02 — auto-register bundled output style.
+ *
+ * Real user feedback (2026-08-02): `npm i -g peaks-loop@latest` on a
+ * fresh 0-1 project copied `peaks-skill-swarm.md` into
+ * `~/.claude/output-styles/` but never wrote
+ * `outputStyle: 'peaks-skill-swarm'` into `~/.claude/settings.json`.
+ * Result: Claude Code loaded no Peaks output style in new sessions.
+ *
+ * The fix: when `peaks-skill-swarm.md` is present in the bundled output
+ * styles directory AND `~/.claude/settings.json` does NOT yet declare
+ * `outputStyle`, merge in `outputStyle: 'peaks-skill-swarm'` while
+ * preserving every other key. If the user already set `outputStyle`,
+ * leave it alone — the user is the source of truth.
+ *
+ * Resolution precedence:
+ *   1. options.settingsFile  (explicit override / test hook)
+ *   2. PEAKS_CLAUDE_SETTINGS_FILE env var  (CI override)
+ *   3. homedir-relative `<homedir>/.claude/settings.json`  (default)
+ *
+ * Soft-fail contract: every error path (missing file, malformed JSON,
+ * missing bundled style file, permission denied) is logged to stderr
+ * and returns `{ skipped: true, ... }` instead of throwing. The
+ * postinstall must never fail on this step because the bundled file
+ * itself was already written successfully.
+ */
+function resolveSettingsFilePath(options = {}) {
+  if (typeof options.settingsFile === 'string' && options.settingsFile.length > 0) {
+    return resolve(options.settingsFile);
+  }
+  const envOverride = process.env.PEAKS_CLAUDE_SETTINGS_FILE;
+  if (typeof envOverride === 'string' && envOverride.length > 0) {
+    return resolve(envOverride);
+  }
+  return resolve(homedir(), '.claude', 'settings.json');
+}
+
+export function installBundledOutputStyleDefault(options = {}) {
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || process.env.PEAKS_SKIP_OUTPUT_STYLE_DEFAULT === '1') {
+    return { skipped: true, reason: 'PEAKS_SKIP_OUTPUT_STYLE_DEFAULT=1' };
+  }
+
+  const bundledStylesDir = resolve(
+    options.targetRoot
+      ?? process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR
+      ?? join(homedir(), '.claude', 'output-styles')
+  );
+  const settingsPath = resolveSettingsFilePath(options);
+  const bundledStyleName = 'peaks-skill-swarm.md';
+  const bundledStylePath = join(bundledStylesDir, bundledStyleName);
+
+  // Read the existing settings.json (if any) FIRST so a malformed file
+  // surfaces as a parse error (more actionable to the user than the
+  // generic "bundled style not present" message). Malformed JSON is a
+  // user-authored file we MUST NOT clobber — log and skip.
+  let existing = null;
+  if (existsSync(settingsPath)) {
+    const stats = getPathStats(settingsPath);
+    if (!stats || !stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) {
+      process.stderr.write(
+        `peaks install-skills: refusing to overwrite non-regular settings.json at ${settingsPath}\n`
+      );
+      return { skipped: true, reason: 'settings.json is not a regular file' };
+    }
+    try {
+      const raw = readFileSafely(settingsPath, 'Claude settings.json path changed during read');
+      const parsed = JSON.parse(raw);
+      if (!isPlainObject(parsed)) {
+        process.stderr.write(
+          `peaks install-skills: refusing to overwrite settings.json that is not a JSON object at ${settingsPath}\n`
+        );
+        return { skipped: true, reason: 'settings.json is not a JSON object' };
+      }
+      existing = parsed;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(
+        `peaks install-skills: failed to parse settings.json at ${settingsPath}: ${message}; leaving untouched\n`
+      );
+      return { skipped: true, reason: 'settings.json parse error' };
+    }
+  }
+
+  // Pre-condition: the bundled style file must be present in the
+  // dispatched target. If it's not, we MUST NOT inject
+  // `outputStyle: 'peaks-skill-swarm'` — Claude Code would then fail
+  // to load the style and fall back to default anyway, leaving the
+  // user with broken state. Skipping is the safe default.
+  if (!existsSync(bundledStylePath)) {
+    return { skipped: true, reason: `bundled output style not present at ${bundledStylePath}` };
+  }
+
+  // User-authored outputStyle wins — never overwrite.
+  if (existing !== null && typeof existing.outputStyle === 'string' && existing.outputStyle.length > 0) {
+    return { skipped: true, reason: `user-defined outputStyle already set: ${existing.outputStyle}` };
+  }
+
+  const next = existing === null
+    ? { outputStyle: 'peaks-skill-swarm' }
+    : { ...existing, outputStyle: 'peaks-skill-swarm' };
+
+  const existingJson = existing === null ? null : `${JSON.stringify(existing, null, 2)}\n`;
+  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
+  if (existingJson === nextJson) {
+    return { skipped: true, reason: 'no change' };
+  }
+
+  try {
+    writeFileAtomically(
+      settingsPath,
+      nextJson,
+      'Claude settings.json path changed during write',
+      () => {
+        if (!existsSync(settingsPath)) return;
+        const stats = getPathStats(settingsPath);
+        if (!stats || !stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) {
+          throw new Error('Claude settings.json path is not a regular file');
+        }
+      }
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `peaks install-skills: failed to write settings.json at ${settingsPath}: ${message}\n`
+    );
+    return { skipped: true, reason: 'write error', error: message };
+  }
+
+  return {
+    installed: true,
+    created: existing === null,
+    updated: existing !== null,
+    settingsPath,
+    outputStyle: 'peaks-skill-swarm',
+  };
+}
+
 /**
  * Slice 7/7 — bundled agents (Claude Code sub-agent prompts).
  *
@@ -1205,6 +1342,40 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
     if (outputStylesResult.skipped.length > 0) {
       process.stderr.write(`Peaks output styles skipped because local files already exist: ${outputStylesResult.skipped.join(', ')}\n`);
     }
+
+    // Slice 2026-08-02 — auto-register bundled output style.
+    //
+    // After the bundled style file lands in `~/.claude/output-styles/`,
+    // we also need Claude Code to actually USE it — otherwise the user
+    // (real feedback 2026-08-02: fresh 0-1 project like
+    // `Desktop\ticket-cross`) sees the default style in new sessions.
+    //
+    // This step reads `~/.claude/settings.json`, and only if the user
+    // hasn't set `outputStyle` yet, writes
+    // `outputStyle: 'peaks-skill-swarm'` while preserving every other
+    // key. Malformed settings.json / IO errors / non-regular files are
+    // soft-failed to stderr (the bundled file is already on disk, so
+    // postinstall never aborts here).
+    //
+    // The `targetRoot` here mirrors the dispatch target of
+    // `installBundledOutputStyles()` above so the env-var override
+    // path (test fixtures + CI) stays consistent: if the bundled
+    // style file was dispatched to an env-overridden dir, the
+    // auto-register step checks THAT dir, not the user's homedir.
+    try {
+      const dispatchTargetRoot = process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR
+        ?? join(homedir(), '.claude', 'output-styles');
+      const styleDefaultResult = installBundledOutputStyleDefault({ targetRoot: dispatchTargetRoot });
+      if (styleDefaultResult.installed) {
+        process.stdout.write(
+          `Peaks output style auto-registered: ${styleDefaultResult.outputStyle}\n` +
+            `  → wrote ${styleDefaultResult.settingsPath}\n`
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`Peaks output style default was not installed: ${message}\n`);
+    }
     if (userConfigResult.created) {
       process.stdout.write('Peaks user config created: ~/.peaks/config.json\n');
     }

package/skills/peaks-code/SKILL.md

@@ -63,6 +63,41 @@ This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary**
 
 When 24h mode is active and an in-flight sub-agent batch is detected, the LLM MAY persist its current turn context to disk through the `session spill-demo` helper. Creates a `SpillRecord` in `.peaks/_runtime/<sessionId>/spill/`. Round-trip is idempotent; existing in-flight deferral still works without spill/hydrate. **Opt-in experimental** — not required.
 
+## 24h mode explicit scope (slice 4.0.7-PR-meta-2, locked 2026-08-02)
+
+The 4.0.7 dogfood pass on `ice-cola` surfaced a flow-level bug: 24h mode's "no AskUserQuestion" intent was over-extended by the LLM to **all** user instructions, including the Code-Change Red Line (the prose-only rule "you MUST NOT edit application source directly without going through peaks-rd"). The LLM routed 22 files / 632 lines of `Edit` calls straight through without a single `peaks sub-agent dispatch rd`. The fix below makes the scope explicit so future LLM sessions cannot make the same over-extension.
+
+### What 24h mode BYPASSES (the AskUserQuestion gates)
+
+24h mode is `peaks session 24h-mode transition --state 24H_ACTIVE`. Once active, the LLM MAY auto-proceed (recommended = chosen) at the following `peaks-code` steps without an AskUserQuestion:
+
+- `step-0.5-openspec-opt-in` — OpenSpec opt-in
+- `step-0.6-audit-goal` — audit + goal confirmation
+- `step-0.7-resume-detection` — resume vs new-work
+- `step-0.55-1x-upgrade` — 1.x → 2.0 upgrade detection (still surfaces the gate at the moment-of-impact, but does not pause to ASK)
+- `step-1-mode-select` — full-auto / assisted / strict / swarm mode pick
+- `step-2.5-session-title` — human-readable session title
+- `phase-2-prd-confirm` — PRD's `Goals / Non-goals / Acceptance criteria` confirm (24h mode picks a recommended set; user can still reject post-hoc via the verdict loop)
+- `phase-3-swarm-gate-b` — swarm selection (full-auto recommended; 24h mode skips the AskUserQuestion but still records the choice)
+- `phase-6-qa-gate-d` — QA verdict gate (24h mode auto-proceeds; the verdict log is the audit trail)
+- `phase-10-txt-memory-extract` — Step 11 memory sediment (24h mode auto-runs the extract)
+- `step-n+1-final-review` — final review (24h mode auto-fires the 4-dim review; user can still inspect the artifact post-hoc)
+
+### What 24h mode DOES NOT BYPASS (the hard rules)
+
+24h mode is **only** a "no AskUserQuestion" override. It is NOT a "skip the entire peaks-code flow" override. The following peaks-code rules are **always** enforced under 24h mode:
+
+- **Code-Change Red Line** (prose rule + slice 4.0.7-PR-meta-1 Edit-enforcement hook). Every code change goes through `peaks-code → peaks-rd → peaks-qa → verdict`. The LLM MUST NOT edit `src/**` directly. Use `peaks sub-agent dispatch rd`.
+- **Sub-agent dispatch** for non-trivial work. Even in 24h mode, the LLM is not exempt from dispatching `peaks-rd` / `peaks-qa`. The `--apply` flag in 24h mode picks the recommended option in the dispatch envelope, but the dispatch still happens (slice 4.0.7-PR-meta-4).
+- **Worktree authorization** (slice 2026-07-29-worktree-layer3-deny). 24h mode does NOT widen Layer 3's deny list. The 3-layer governance (L1 prose + L2 hook + L3 IDE permissions.deny) remains in force.
+- **Request state machine transitions** (`spec-locked → implemented → qa-handoff → handed-off`). 24h mode is not a state-machine bypass.
+- **External side effects** (`git push`, `git tag`, `npm publish`, `npm install -g peaks-loop`, `peaks global install`). The 5 commit-boundary hard-floor actions always pause, even in 24h mode.
+- **Reverse 2.x → 1.x migration**, **git reset --hard**, **force-push to protected branches**. Same hard-floor logic.
+
+### The single-sentence rule (paste into any new peaks-code session that flips 24h mode)
+
+> 24h mode lets the LLM auto-proceed at the AskUserQuestion gates (mode select, step confirm, swarm pick, etc.). It does **not** let the LLM skip the peaks-code 11-step flow, edit `src/**` directly, or bypass request-state transitions.
+
 ## Peaks-Loop Superpowers 协作边界 (BRIDGE — MANDATORY, effective 2026-07-24)
 
 Pins the boundary between `peaks-code` and the **superpowers** skill family (`brainstorming`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `test-driven-development`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-superpowers`, `using-git-worktrees`, `finishing-a-development-branch`). Closed under slice 2026-07-24-peaks-code-bridge-002-rootcause.
@@ -114,7 +149,7 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 | `0.85 ≤ ratio < 0.95` | **pre-compact zone** | `peaks compact auto --execute` fires **automatically** (deferred only when in-flight sub-agent batch is running; fires the moment the batch lands). The LLM does not prompt the user. |
 | `ratio ≥ 0.95` | **red-line (Karpathy §4)** | synchronous gate — `peaks compact auto --execute` invoked immediately; `peaks code context-now` returns `action: 'red-line'` and refuses to advance until ratio drops below 0.85. **Karpathy §4 automatic exception** — LLM cannot opt out. |
 
-**Probe primitive (single source of truth):** `peaks code context-now --json`. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks compact auto --execute` on `auto-compact-now` or `red-line` without user confirmation.
+**Probe primitive (single source of truth):** `peaks code context-now --json --project <path>`. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks compact auto --execute` on `auto-compact-now` or `red-line` without user confirmation. **Always pass `--project` explicitly** — the CLI does not auto-resolve cwd (see Drift Index D-013).
 
 **Enforcement layers (defense in depth):**
 1. `src/services/code/auto-compact-orchestrator.ts` — `evaluateAutoCompactDecision` default-returns `shouldCompact: true` for both `pre-compact` and `red-line`. Only deferral is `inFlightBatch.hasInFlightBatch` (D6.e); no LLM/human approval branch.
@@ -127,18 +162,21 @@ Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.
 
 If the prose audit (`peaks audit red-lines`) flags any of the above, the slice is **blocked** until the prose is rewritten.
 
-## CLI Drift Index (sediment 2026-07-09)
+## CLI Drift Index (sediment 2026-07-09, refreshed 2026-08-02)
 
-> **Reading guide:** Verified against peaks-loop 4.0.0-beta.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing.
+> **Reading guide:** Verified against peaks-loop 4.0.6. Each drift below is annotated inline at the relevant step with a `> CLI reality check`. On `error: unknown option ...`, **read the inline reality check first** before guessing. The 4.0.7 dogfood pass (ice-cola surface probe) re-validated all entries; D-001 was rewritten (the pre-4.0.7 entry was the inverse of 4.0.6's actual behavior).
 
 | Drift ID | Step | Symptom | Fix | Inline location |
 |---|---|---|---|---|
-| **D-001** | 0.8 | `peaks code detect-job --is-job ...` rejected with `error: unknown option '--is-job'` | Use `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single\|rotating>` | §Step 0.8 first paragraph |
+| **D-001** | 0.8 | `peaks code detect-job --is-job ...` requires the flag (4.0.6+); pre-4.0.6 the flag was rejected. Either way, you must pass `--is-job <bool> --rationale <text> --suggested-job-id <slug>` | `peaks code detect-job --is-job <true\|false> --rationale "<1-3 sentences>" --suggested-job-id <slug>` | §Step 0.8 first paragraph |
 | **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5 |
 | **D-003** | 0.8 | `JOB_SHAPE_NOT_DECIDED` exception expected but never thrown | Current behavior is `peaks job status` reports `done: 0` passively — treat as recoverable miss, not hard error | §Step 0.8 third paragraph |
 | **D-010** | 11c | `peaks memory extract` returns `extractedCount: 0` despite `<!-- peaks-memory:start -->` existing | Block requires YAML frontmatter (`title:` + `kind:` + `---`) + closing `<!-- peaks-memory:end -->`. Bare `peaks-memory:start` is parsed silently but produces no writes | §Step 11c + 11d |
+| **D-013** | N+2 | `peaks code context-now --json` (no `--project`) rejected with `error: required option '--project <path>' not specified` | Always pass `--project <path>` (use `.` for the cwd). The CLI does not auto-resolve cwd because monorepos + CI have surprising cwd semantics. | §Step N+2 probe primitive |
+| **D-014** | 0.8 | `peaks code detect-job` / `read-job-shape` / `peaks workflow plan read --type <type>` / `peaks route --goal <g>` all reported `NO_ACTIVE_SESSION` even when `.peaks/_runtime/session.json` was a valid binding. The 4 CLIs read `getSkillPresence` (the `.peaks/.active-skill.json` file, set only by `peaks skill presence:set <skill>`) instead of the canonical binding. Fixed in 4.0.7 PR-2 via `resolveActiveSessionId` shared resolver — no action required at the call site, but if you see a `NO_ACTIVE_SESSION` error, run `peaks workspace init --project <path>` first. | §Step 0.8 third paragraph + §Step 1 mode select |
+| **D-015** | 0.8 | `peaks code should-pause --step step-1-mode-select` reports `stale-presence: no-presence` even when 24h-mode is active. 24h-mode never sets skill presence by design (no sub-skill flips). Fixed in 4.0.7 PR-3 — gate short-circuits the stale-presence check when `24h-state.json#state === '24H_ACTIVE'`. | §Step 1 mode select + §24h mode |
 
-> **Sediment lesson (master record):** `.peaks/memory/peaks-code-runbook-4-0-0-beta-6-skill-md-cli-d-001-d-002-d-003-d-010.md`
+> **Sediment lesson (master record):** `.peaks/memory/peaks-code-runbook-4-0-0-beta-6-skill-md-cli-d-001-d-002-d-003-d-010.md` (pre-4.0.7); `.peaks/memory/2026-08-02-ice-cola-dogfood-surface-probe.md` (4.0.7 fixes).
 
 ## Peaks-Loop GStack integration