claude-code-session-manager 0.35.0 → 0.35.1

package/dist/index.html

@@ -7,7 +7,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-zepGuf8m.js"></script>
+    <script type="module" crossorigin src="./assets/index-1DFsiqCu.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
     <link rel="stylesheet" crossorigin href="./assets/index-CPTin6qz.css">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",

package/plugins/session-manager-dev/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-manager-dev",
-  "description": "The default end-to-end development skillset for the Claude Code Session Manager: decompose work into scheduler PRDs (/develop, /prd), triage cross-project feedback (/process-feedback, /my-feedback), roll up operational status and optimize the North-Star KPI (/project-status, /optimize-kpi, /local-project-health), gate with review (/requesting-code-review, /security-review), and document how the project works (/explain-to-me). Together with the session-manager scheduler these form a closed develop → queue → track → review → status → improve loop.",
+  "description": "The default end-to-end development skillset for the Claude Code Session Manager: decompose work into scheduler PRDs (/develop), triage cross-project feedback (/process-feedback, /my-feedback), roll up operational status and optimize the North-Star KPI (/project-status, /optimize-kpi, /local-project-health), gate with review (/requesting-code-review, /security-review), and document how the project works (/explain-to-me). Together with the session-manager scheduler these form a closed develop → queue → track → review → status → improve loop.",
   "version": "0.1.0",
   "author": {
     "name": "Stanislav Georgiev",

package/plugins/session-manager-dev/skills/develop/SKILL.md

@@ -21,8 +21,7 @@ arrives via `/process-feedback`, which evaluates it and then calls this skill. E
 here on is identical regardless of who asked.
 
 **Never** hand-implement the work inline in chat, and never restate rules that live elsewhere:
-single-PRD structure/sizing belongs to `/prd`, the engineering rules belong to `standards.md`.
-Reference them; don't fork them.
+the engineering rules belong to `standards.md`. Reference it; don't fork it.
 
 ## Standards (single source of truth)
 
@@ -48,12 +47,10 @@ can't load skills.
    reuse (per the API-reuse standard — search before writing new code), the test command, and
    any constraints. Capture exact file paths and signatures; they go straight into the PRDs.
 
-3. **Decompose into a series of SMALL, bounded PRDs.** This is the part `/develop` owns that
-   `/prd` doesn't: split a large ask into multiple PRDs and sequence them. For each PRD's
-   *size, command-bounding, `NN` parallel group, and structure*, follow `~/.claude/skills/prd/SKILL.md`
-   — it is the canonical authority; do not restate its rules here. To pick `NN`, **compute the
-   highest in-use number deterministically — never eyeball or narrow-grep the `ls`** (a
-   narrowed pattern like `'^10[0-9]'` silently misses `110+` and collides):
+3. **Decompose into a series of SMALL, bounded PRDs.** Split a large ask into multiple PRDs and
+   sequence them. To pick each PRD's `NN` (parallel group), **compute the highest in-use number
+   deterministically — never eyeball or narrow-grep the `ls`** (a narrowed pattern like
+   `'^10[0-9]'` silently misses `110+` and collides):
    ```bash
    ls ~/.claude/session-manager/scheduled-plans/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
    ```
@@ -62,7 +59,93 @@ can't load skills.
    is unrelated to every existing group. Record each cross-PRD dependency in the dependent
    PRD's notes.
 
-4. **Emit each PRD** to the canonical path per `/prd`'s structure, then **append `## Engineering
+   ### PRD structure and location
+
+   Each individual PRD must follow this structure — this is `/develop`'s single authority on
+   one PRD's structure, location, and scope sizing (the engineering rules stay separate, in
+   `standards.md`).
+
+   You are writing a PRD that will be executed by the user's session-manager scheduler — a
+   system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour
+   token-window resets, with auto-pause on rate-limit and auto-resume.
+
+   **Canonical location — non-negotiable.** PRDs MUST be written to:
+   ```
+   ~/.claude/session-manager/scheduled-plans/prds/<NN>-<kebab-slug>.md
+   ```
+   **Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the
+   project root, the scheduler will not see it and the user loses their token-budget-managed
+   execution. There is exactly one queue for all projects — that's intentional, because the
+   5-hour token budget is global across all of the user's Claude work. The `~` expands to
+   `os.homedir()` so the same convention works for any user on any machine.
+
+   **Filename rules.** `NN` is the 2-digit zero-padded parallel group (picked per the `ls`
+   command above — same `NN` as an independent sibling, or next free `NN` = max+1 when this PRD
+   hard-depends on prior work). `<kebab-slug>` is a short, descriptive kebab-case identifier
+   (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`), kept under 60 chars. Verify your
+   chosen filename doesn't already exist before writing.
+
+   **Required frontmatter:**
+   ```yaml
+   ---
+   title: <one-line human-readable title>
+   cwd: <path to target project — where claude -p will run>
+   estimateMinutes: <integer wall-clock estimate>
+   ---
+   ```
+   `cwd` is critical — without it the job runs in the scheduler's default cwd (session-manager).
+   Always set it to the path of the project the work targets, written as `~/Projects/<repo>`
+   (the parser expands `~` to `os.homedir()` at ingest, so the same PRD works on any machine).
+   Avoid hardcoding an absolute home path (`/home/<you>/Projects/<repo>`); it breaks on any
+   machine with a different home directory.
+
+   **Required body sections, in this order:**
+   ```markdown
+   # Goal
+
+   <2-4 sentences. What the executor will build and why it matters. NO "as a user I want to"
+   framing. Concrete: name the function, the file, the user-visible change.>
+
+   # Acceptance criteria
+
+   - [ ] <each line is a verifiable check the executor can run after building>
+   - [ ] <include explicit file paths, function names, expected behavior>
+   - [ ] a bounded test command passes, e.g. `timeout 300 npm run typecheck` / `pytest -x` /
+     `cargo check` (the run-before-done / never-end-on-red rule lives in standards.md →
+     Execution discipline; the AC just has to name the command).
+
+   # Implementation notes
+
+   <file paths the executor will need to read first; the architectural pattern to follow; any
+   non-obvious constraints. Be specific. Quote function signatures if it saves the executor a
+   Read call.>
+
+   # Out of scope
+
+   <short bulleted list of what NOT to build, to prevent scope creep>
+   ```
+
+   **Self-containment is load-bearing.** The executor (`claude -p`) starts with NO conversation
+   context — only the PRD body and the project files. So: include exact file paths (e.g.
+   `src/main/index.cjs:142`); quote function signatures or relevant code blocks if the executor
+   would have to grep for them; name the libraries/patterns to use (e.g. "use the existing
+   `validatePath` helper in `config.cjs`"); don't reference "the conversation we just had" or
+   "the design we discussed"; if a PRD depends on another PRD's output, say so in
+   `# Implementation notes` AND give it a higher `NN` so it queues after.
+
+   **Scope sizing — keep it SMALL (data-driven, 2026-06).** Across 400+ real runs the median
+   PRD finishes in **~7 minutes**, p90 **~21 min**, p99 **~66 min** — yet authored
+   `estimateMinutes` ran 5–8× too high. Oversized scoping anchors PRDs too big and pushes them
+   into the rare >60-min tail where ~100% of true hangs live (deploy poll-loops, unbounded e2e
+   suites). Target ~15 minutes of wall-clock work per PRD — **hard ceiling ~30 min; if you
+   project more, SPLIT** into sequential `NN` PRDs and document the dependency in each. Set
+   `estimateMinutes` realistically: **p50≈8, p90≈21** — don't write 60/90, it's almost always
+   wrong and hides real outliers. Each execution costs ~$0.50–$2; smaller PRDs = smaller blast
+   radius when a run is rate-limited, timed out, or killed. **`rateLimited` exit-1 is NOT a
+   failure** — it's the scheduler's designed auto-pause; the job auto-resumes at the next
+   window reset. Don't add retry logic for it.
+
+4. **Emit each PRD** to the canonical path and structure above, then **append `## Engineering
    standards` and paste the full contents of `standards.md` verbatim.** This is the
    load-bearing step — it's the only way the standards (incl. Execution discipline) reach the
    headless run. Honor the `PRD_AUTHORING.md` §10 pre-queue checklist.
@@ -99,7 +182,6 @@ single definition of "tracked to done" for both entry paths.
 
 ## References (reuse, don't duplicate)
 
-- `~/.claude/skills/prd/SKILL.md` — canonical single-PRD structure, location, filename rules, scope sizing.
 - `~/.claude/session-manager/scheduled-plans/PRD_AUTHORING.md` — the §1–§10 safety rules.
 - `~/.claude/skills/develop/standards.md` — the engineering + execution-discipline rules inlined into every PRD.
 - `test-driven-development`, `systematic-debugging` — interactive dev sessions.
@@ -110,3 +192,6 @@ single definition of "tracked to done" for both entry paths.
 - Write PRD files directly, then confirm — don't draft them inline in chat for review first.
 - Don't combine unrelated features into one PRD. One focused, completable unit each.
 - Don't add a `parallelGroup` frontmatter key — the filename `NN-` prefix drives grouping.
+- Don't write a PRD to `data/prds/`, `docs/prds/`, the project's own folder, or anywhere outside
+  the canonical path. The user has explicitly flagged this as a recurring problem.
+- Don't leave `cwd` unset hoping for the default. Be explicit.

package/plugins/session-manager-dev/skills/explain-to-me/SKILL.md

@@ -62,7 +62,7 @@ If you can't state it in the present tense without a date or a PRD, cut it.
 - **The Skill Map** — `HUMAN_LEARN/SKILL_MAP.html`, a **separate, dedicated** page
   (NOT a section of index.html) that visualizes the *local-development skill chain*:
   the two intakes (interactive human prompt; agent feedback via `/process-feedback`)
-  converging on `/develop`, which reads `/prd` + `standards.md`, queues onto the
+  converging on `/develop`, which owns PRD authoring + reads `standards.md`, queues onto the
   scheduler, and gates with review/verify — plus `/my-feedback` outbound. It is the
   "how I build on this project" companion to index.html's "how this project works."
   index.html links to it from the nav; it links back.

package/src/main/__tests__/chat-cancel-terminal.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * chat-cancel-terminal.test.cjs — regression for the "stuck thinking" hang.
+ *
+ * Bug (2026-07-05): cancelling an active chat run SIGTERM'd the child, but the
+ * exit handler's `if (!gotResult && !killed)` guard skipped every broadcast
+ * because `killed === true`. No terminal IPC event ever reached the renderer,
+ * so the chat store stayed `running:true` forever — disabled textarea, endless
+ * "running…" spinner, unresponsive chat UI.
+ *
+ * Fix: every run emits EXACTLY ONE terminal event (complete/needs-input/error),
+ * and the exit path emits a fallback `chat:run:error` when a run settled
+ * without one (cancel, crash, silent exit). This test drives the REAL spawn
+ * path (via SM_CLAUDE_BIN pointing at a stub process) and asserts a terminal
+ * event is broadcast on cancel.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/chat-cancel-terminal.test.cjs
+ */
+
+'use strict';
+
+delete process.env.SM_CHAT_CONCURRENCY;
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// A stub "claude" that ignores stdin/args and stays alive until killed —
+// mimics a long-running headless run so cancel() has something to SIGTERM.
+// Shebang + chmod makes it directly spawnable as a single executable (spawn
+// does not split a path on spaces, so SM_CLAUDE_BIN must be one binary).
+const stubPath = path.join(os.tmpdir(), `sm-claude-stub-${process.pid}.cjs`);
+fs.writeFileSync(
+  stubPath,
+  `#!${process.execPath}\nsetInterval(() => {}, 1000);\n`,
+  { mode: 0o755 },
+);
+process.env.SM_CLAUDE_BIN = stubPath;
+
+const cr = require('../chatRunner.cjs');
+
+const tick = () => new Promise((r) => setImmediate(r));
+
+test('cancelling an ACTIVE run broadcasts a terminal event (unsticks the UI)', async () => {
+  const events = [];
+  // Fake BrowserWindow that captures every broadcast.
+  cr.attachWindow({
+    isDestroyed: () => false,
+    webContents: {
+      isDestroyed: () => false,
+      send: (channel, payload) => events.push({ channel, payload }),
+    },
+  });
+
+  cr.run({ tabId: 'T', sessionId: 'S', prompt: 'hello', cwd: process.cwd(), resume: false });
+
+  // Let the spawn happen and started event fire.
+  for (let i = 0; i < 6; i++) await tick();
+  assert.ok(
+    events.some((e) => e.channel === 'chat:run:started'),
+    'started event should fire once the run launches',
+  );
+
+  cr.cancel('T');
+
+  // Wait for SIGTERM → child exit → fallback terminal broadcast.
+  for (let i = 0; i < 40 && !events.some((e) => isTerminal(e.channel)); i++) {
+    await new Promise((r) => setTimeout(r, 25));
+  }
+
+  const terminal = events.filter((e) => isTerminal(e.channel));
+  assert.equal(terminal.length, 1, 'exactly one terminal event is emitted');
+  assert.equal(terminal[0].channel, 'chat:run:error', 'cancel surfaces as an error turn');
+  assert.match(terminal[0].payload.message, /cancel/i, 'message names the cancellation');
+});
+
+function isTerminal(channel) {
+  return (
+    channel === 'chat:run:complete' ||
+    channel === 'chat:run:needs-input' ||
+    channel === 'chat:run:error'
+  );
+}
+
+test.after(() => {
+  try { fs.unlinkSync(stubPath); } catch { /* already gone */ }
+  delete process.env.SM_CLAUDE_BIN;
+});

package/src/main/chatRunner.cjs

@@ -174,6 +174,20 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
       resolve();
     };
 
+    // Guarantees the renderer receives EXACTLY ONE terminal event
+    // (complete / needs-input / error) per run. Without this, a cancelled or
+    // killed run exits with `killed=true` and the old exit-guard broadcast
+    // nothing — leaving the chat store stuck at running:true forever (disabled
+    // textarea, "running…" spinner, unresponsive UI). Every terminal broadcast
+    // funnels through here so the exit path can emit a fallback only when the
+    // run settled without one.
+    let terminalSent = false;
+    const emitTerminal = (channel, payload) => {
+      if (terminalSent) return;
+      terminalSent = true;
+      broadcast(channel, payload);
+    };
+
     const claudeBin = resolveClaudeBin();
     const childEnv = cleanChildEnv({ PATH: pathWithUserBins() });
 
@@ -209,7 +223,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
         detached: true, // own process group so killTree can SIGTERM descendants
       });
     } catch (err) {
-      broadcast('chat:run:error', {
+      emitTerminal('chat:run:error', {
         tabId,
         sessionId,
         message: `spawn failed: ${err?.message ?? String(err)}`,
@@ -237,7 +251,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
 
     // Hard wall-clock ceiling — SIGTERM + SIGKILL on expiry
     const killTimer = setTimeout(() => {
-      broadcast('chat:run:error', {
+      emitTerminal('chat:run:error', {
         tabId,
         sessionId,
         message: 'run exceeded 30-minute wall-clock ceiling',
@@ -253,7 +267,6 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
     let lineBuffer = '';
     let finalAssistantText = '';
     let stderrBuffer = '';
-    let gotResult = false;
 
     const processLine = (line) => {
       if (!line) return;
@@ -273,7 +286,6 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
           }
         }
       } else if (event.type === 'result') {
-        gotResult = true;
         // Use the authoritative `result` field when available; fall back to
         // accumulated assistant text (same content, different source).
         const text = typeof event.result === 'string' ? event.result : finalAssistantText;
@@ -281,21 +293,21 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
         if (event.subtype === 'success') {
           const signal = parseStopSignal(text);
           if (signal) {
-            broadcast('chat:run:needs-input', {
+            emitTerminal('chat:run:needs-input', {
               tabId,
               sessionId,
               questions: signal.questions,
               raw: text,
             });
           } else {
-            broadcast('chat:run:complete', { tabId, sessionId, finalMessage: text });
+            emitTerminal('chat:run:complete', { tabId, sessionId, finalMessage: text });
             // Record durable exchange off the hot path — UI must not wait on Haiku
             recordExchange({ sessionId, cwd, prompt, result: text }).catch((err) => {
               console.error('[chatRunner] recordExchange failed:', err?.message ?? err);
             });
           }
         } else {
-          broadcast('chat:run:error', {
+          emitTerminal('chat:run:error', {
             tabId,
             sessionId,
             message: `run ended with result subtype: ${event.subtype ?? 'unknown'}`,
@@ -319,7 +331,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
 
     child.on('error', (err) => {
       clearTimeout(killTimer);
-      broadcast('chat:run:error', {
+      emitTerminal('chat:run:error', {
         tabId,
         sessionId,
         message: err?.message ?? String(err),
@@ -332,15 +344,28 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume }) {
       // Flush any partial line that didn't end with \n
       if (lineBuffer.trim()) processLine(lineBuffer.trim());
 
-      if (!gotResult && !killed) {
-        const errDetail = stderrBuffer.trim()
-          ? `: ${stderrBuffer.trim().slice(0, 300)}`
-          : '';
-        broadcast('chat:run:error', {
-          tabId,
-          sessionId,
-          message: `process exited without a result event (code=${code} signal=${signal})${errDetail}`,
-        });
+      // Emit a fallback terminal event for any run that ended without one — a
+      // cancel/SIGTERM (killed=true), a crash before a result, or a silent
+      // exit. `emitTerminal` no-ops if the run already sent complete/needs-
+      // input/error, so the normal success path never double-fires. This is
+      // what unsticks the renderer's running flag after Cancel.
+      if (!terminalSent) {
+        if (killed) {
+          emitTerminal('chat:run:error', {
+            tabId,
+            sessionId,
+            message: 'run cancelled',
+          });
+        } else {
+          const errDetail = stderrBuffer.trim()
+            ? `: ${stderrBuffer.trim().slice(0, 300)}`
+            : '';
+          emitTerminal('chat:run:error', {
+            tabId,
+            sessionId,
+            message: `process exited without a result event (code=${code} signal=${signal})${errDetail}`,
+          });
+        }
       }
       settle();
     });

package/src/main/lib/claudeBin.cjs

@@ -18,6 +18,9 @@ const os = require('node:os');
 let cached = null;
 
 function resolveClaudeBin() {
+  // Explicit override wins and is never cached — lets operators pin a binary
+  // and lets tests point the runner at a controllable stub process.
+  if (process.env.SM_CLAUDE_BIN) return process.env.SM_CLAUDE_BIN;
   if (cached) return cached;
   // Merged candidate list — was forked in scheduler vs pluginInstall before.
   const home = os.homedir();

package/plugins/session-manager-dev/skills/prd/SKILL.md

@@ -1,134 +0,0 @@
----
-name: prd
-description: >-
-  Write a PRD for the session-manager scheduler queue (the right place for
-  token-budget-managed work). Use this whenever the user says "make this a PRD",
-  "queue this up", "add to the scheduler", or asks for a PRD without specifying a
-  target location. Keywords: prd, queue, scheduler, scheduled-plans, token budget.
----
-
-# /prd — author one scheduler PRD
-
-**Role:** `/prd` is the single authority on one PRD's *structure, location, and scope sizing*. It does not own the engineering rules (that's `standards.md`) and does not decompose a large ask into multiple PRDs (that's `/develop`). Never restate rules that live in `standards.md` — reference and append them.
-
-You are writing a PRD that will be executed by the user's session-manager scheduler — a system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour token-window resets, with auto-pause on rate-limit and auto-resume.
-
-## Canonical location — non-negotiable
-
-PRDs MUST be written to:
-
-```
-~/.claude/session-manager/scheduled-plans/prds/<NN>-<kebab-slug>.md
-```
-
-**Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the project root, the scheduler will not see it and the user loses their token-budget-managed execution. There is exactly one queue for all projects — that's intentional, because the 5-hour token budget is global across all of the user's Claude work. The `~` expands to `os.homedir()` so the same convention works for any user on any machine.
-
-## Filename rules
-
-- `NN` is the **parallel group** (2-digit zero-padded). Jobs in the same group run in parallel up to a concurrency cap; groups run serially. Pick `NN` by reading the existing files in `~/.claude/session-manager/scheduled-plans/prds/` and choosing:
-  - The same `NN` as a sibling that's logically independent and can run in parallel.
-  - The next unused `NN` if this PRD has a hard dependency on prior work landing first.
-- `<kebab-slug>` is a short, descriptive kebab-case identifier (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`). Keep under 60 chars.
-
-Compute the current max `NN` **deterministically** before writing — do NOT eyeball the `ls` or narrow the pattern (a grep like `'^10[0-9]'` silently misses `110+` and overwrites/mis-groups a PRD):
-
-```bash
-ls ~/.claude/session-manager/scheduled-plans/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
-```
-
-The last line is the highest in use; the next free group is **max+1**. Use that for an independent/dependent PRD, or reuse a specific sibling's `NN` only when you deliberately want it in that parallel group. Verify your chosen filename doesn't already exist before writing.
-
-## Required frontmatter
-
-```yaml
----
-title: <one-line human-readable title>
-cwd: <path to target project — where claude -p will run>
-estimateMinutes: <integer wall-clock estimate>
----
-```
-
-`cwd` is critical. Without it the job runs in the scheduler's default cwd (session-manager). Always set it to the path of the project the work targets. **Write it as `~/Projects/<repo>`** — the parser expands `~` to `os.homedir()` at ingest, so the same PRD works on Linux and macOS. Avoid hardcoding an absolute home path (`/home/<you>/Projects/<repo>`); it breaks on any machine with a different home directory.
-
-## Required body sections (in this order)
-
-```markdown
-# Goal
-
-<2-4 sentences. What the executor will build and why it matters. NO "as a user I want to" framing. Concrete: name the function, the file, the user-visible change.>
-
-# Acceptance criteria
-
-- [ ] <each line is a verifiable check the executor can run after building>
-- [ ] <include explicit file paths, function names, expected behavior>
-- [ ] a bounded test command passes, e.g. `timeout 300 npm run typecheck` / `pytest -x` / `cargo check` (the run-before-done / never-end-on-red rule lives in standards.md → Execution discipline; the AC just has to name the command).
-
-# Implementation notes
-
-<file paths the executor will need to read first; the architectural pattern to follow; any non-obvious constraints. Be specific. Quote function signatures if it saves the executor a Read call.>
-
-# Out of scope
-
-<short bulleted list of what NOT to build, to prevent scope creep>
-```
-
-## Self-containment is load-bearing
-
-The executor (`claude -p`) starts with NO conversation context — only this PRD body and the project files. So:
-
-- Include exact file paths (`src/main/index.cjs:142`).
-- Quote function signatures or relevant code blocks if the executor would have to grep for them.
-- Name the libraries / patterns to use (e.g. "use the existing `validatePath` helper in `config.cjs`").
-- Don't reference "the conversation we just had" or "the design we discussed."
-- If the PRD depends on another PRD's output, say so in `# Implementation notes` AND give it a higher `NN` so it queues after.
-
-## Scope sizing — keep it SMALL (data-driven, 2026-06)
-
-Across 400+ real runs the median PRD finishes in **~7 minutes**, p90 **~21 min**, p99 **~66 min** — yet authored `estimateMinutes` ran **5–8× too high**. Oversized scoping is the root problem: it anchors PRDs too big and pushes them into the rare >60-min tail where ~100% of true hangs live (deploy poll-loops, unbounded e2e suites).
-
-- **Target ~15 minutes of wall-clock work per PRD. Hard ceiling ~30 min — if you project more, SPLIT** into sequential `NN` PRDs and document the dependency in each.
-- Set `estimateMinutes` realistically: **p50≈8, p90≈21**. Don't write 60/90 — it's almost always wrong and it hides real outliers.
-- Each execution costs ~$0.50–$2; the 5-hour token window is global. Smaller PRDs = smaller blast radius when a run is rate-limited, timed out, or killed.
-- **`rateLimited` exit-1 is NOT a failure** — it's the scheduler's designed auto-pause; the job auto-resumes at the next window reset. Don't add retry logic for it.
-
-## Execution discipline — append it, don't restate it
-
-The runtime rules (bound every command, verify-before-done, fail-loud, stay-in-AC,
-negative-assertion-exits-0) have a single home: the **Execution discipline** section of
-`~/.claude/skills/develop/standards.md`. Don't paraphrase them here — they drift.
-
-Long hangs — not bad code — are the dominant *real* failure (the watchdog only fires at 4
-hours, so an unbounded command burns hours), so these rules are load-bearing and MUST reach
-the headless executor in the PRD body:
-
-- If this PRD is being authored **via `/develop`**, that skill already appends `standards.md`
-  verbatim — nothing to do here.
-- If you are authoring a PRD **directly** (`/prd` alone), **append the Execution discipline
-  section from `standards.md` to the PRD body** (under an `## Execution discipline` heading)
-  before queueing. That is the only way the bounded-command / verify-before-done rules reach
-  `claude -p`.
-
-The one rule worth echoing inline because it shapes the AC: **wrap every test/build/deploy/poll
-command in a hard timeout** (`timeout 300 npm run typecheck`, `timeout 120 npx playwright test
-one.spec.ts` — shard e2e to one spec, never a full suite; `curl --max-time 15`; bound any
-`until/while`). Never queue a publish that polls an endpoint until a condition — the #1 hang
-offender (PRD_AUTHORING §1/§5).
-
-## Workflow
-
-1. Read existing PRDs in `~/.claude/session-manager/scheduled-plans/prds/` to pick `NN`.
-2. Write the file with the structure above.
-3. Confirm to the user:
-   - The filename (so they can see it queued).
-   - The chosen `parallelGroup` (NN) and the rationale (parallel-with-X / serial-after-Y).
-   - The chosen `cwd` (so they can correct if it's wrong).
-   - Estimated wall time + a token-cost ballpark.
-4. Tell the user the PRD will fire when the scheduler's policy says — they can click "Run now" in the SchedulePanel to execute immediately, or wait for `when-available` polling.
-
-## What NOT to do
-
-- Don't write the PRD to `data/prds/`, `docs/prds/`, the project's own folder, or anywhere outside the canonical path. The user has explicitly flagged this as a recurring problem.
-- Don't combine multiple unrelated features into one PRD. Each PRD is one focused, completable unit.
-- Don't add a parallelGroup field to the frontmatter — the scheduler reads the filename prefix.
-- Don't leave `cwd` unset hoping for the default. Be explicit.
-- Don't write the PRD body inline in the chat for review *before* writing the file. Write the file directly, then confirm. The user wants the PRD queued, not draft-reviewed in chat.