peaks-cli 1.3.4 → 1.3.5

package/dist/src/services/skills/hooks-settings-service.js

@@ -10,36 +10,24 @@ import { getAdapter } from '../ide/ide-registry.js';
 // values are computed lazily inside each public function call.
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
-/** Sentinel substring identifying a peaks-managed sub-agent-progress hook entry. */
-export const HOOK_PROGRESS_SENTINEL = 'peaks progress start';
 /** Default (claude-code) hook command — kept as a stable export for tests. */
 export const HOOK_ENFORCE_COMMAND = `peaks gate enforce --project "\${CLAUDE_PROJECT_DIR}"`;
-/** Default (claude-code) progress command — kept as a stable export for tests. */
-export const HOOK_PROGRESS_COMMAND = `peaks progress start --project "\${CLAUDE_PROJECT_DIR}" --reason "auto-spawn for sub-agent Task" --quiet`;
 function resolveHookSpec(ide) {
     const adapter = getAdapter(ide);
     if (ide === 'claude-code') {
         return {
             hookEnforceCommand: `peaks gate enforce --project "\${${adapter.envVar}}"`,
-            hookProgressCommand: `peaks progress start --project "\${${adapter.envVar}}" --reason "auto-spawn for sub-agent ${adapter.subAgentToolMatcher}" --quiet`,
             hookEnforceSentinel: HOOK_ENFORCE_SENTINEL,
-            hookProgressSentinel: HOOK_PROGRESS_SENTINEL,
             hookEnforceMatcher: adapter.toolMatcher, // 'Bash'
-            hookProgressMatcher: adapter.subAgentToolMatcher, // 'Task' (slice 2026-06-06-sub-agent-spawn-bug-and-decouple — adapter now self-reports sub-agent tool name)
-            hookEnforceEvent: adapter.hookEvent, // 'PreToolUse'
-            hookProgressEvent: adapter.hookEvent // 'PreToolUse' for Claude
+            hookEnforceEvent: adapter.hookEvent // 'PreToolUse'
         };
     }
     if (ide === 'trae') {
         return {
             hookEnforceCommand: `peaks hook handle --project "\${${adapter.envVar}}"`,
-            hookProgressCommand: `peaks progress start --project "\${${adapter.envVar}}" --reason "auto-spawn for sub-agent ${adapter.subAgentToolMatcher}" --quiet`,
             hookEnforceSentinel: 'peaks hook handle',
-            hookProgressSentinel: HOOK_PROGRESS_SENTINEL,
             hookEnforceMatcher: adapter.toolMatcher, // 'terminal'
-            hookProgressMatcher: adapter.subAgentToolMatcher, // 'Task' (UNVERIFIED for Trae; matches prior hardcoded literal so byte-level install output is unchanged)
-            hookEnforceEvent: adapter.hookEvent, // 'beforeToolCall'
-            hookProgressEvent: adapter.hookEvent // 'beforeToolCall' (no separate progress event yet for Trae)
+            hookEnforceEvent: adapter.hookEvent // 'beforeToolCall'
         };
     }
     // Future adapters (codex, cursor, qoder, tongyi-lingma) — not yet registered.
@@ -51,6 +39,10 @@ function resolveHookSpec(ide) {
 function resolveIde(options) {
     return options?.ide ?? 'claude-code';
 }
+/** Slice #013: read the skipProgress opt-in flag. Slice #014: the underlying install no longer emits the progress-start entry, so the flag is effectively a no-op (kept for API stability). */
+function resolveSkipProgress(options) {
+    return options?.skipProgress === true;
+}
 /** Resolve settings root dir for a scope. */
 function resolveSettingsRoot(scope, projectRoot) {
     if (scope === 'global')
@@ -101,24 +93,104 @@ function entryIsPeaksManaged(entry, sentinels) {
         return sentinels.some((sentinel) => cmd.includes(sentinel));
     });
 }
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export function readInstalledEntriesFromSettings(settings, ide) {
+    const sentinels = resolveLegacySentinels(ide);
+    // Walk every event key the settings file has, not just the
+    // adapter-declared one. A pre-#014 install could have left a
+    // progress-start entry on a different event than the gate-enforce
+    // entry (Trae: both on beforeToolCall, but a stale install on a
+    // future IDE could split them).
+    const hooksRoot = settings.hooks;
+    if (!hooksRoot || typeof hooksRoot !== 'object' || Array.isArray(hooksRoot))
+        return [];
+    const result = [];
+    for (const eventKey of Object.keys(hooksRoot)) {
+        const entries = readHookEntriesFromHooks(hooksRoot, eventKey);
+        for (const entry of entries) {
+            if (!entryIsPeaksManaged(entry, sentinels))
+                continue;
+            const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+            // Find the first matching sentinel inside the entry's command
+            // handlers. For each handler, find the first sentinel substring
+            // it contains. We pick the first handler's first matching
+            // sentinel (entries have a single command in practice).
+            const firstHandler = Array.isArray(entry.hooks) ? entry.hooks[0] : undefined;
+            const cmd = typeof firstHandler?.command === 'string' ? firstHandler.command : '';
+            const sentinel = sentinels.find((s) => cmd.includes(s));
+            if (matcher === '' || sentinel === undefined)
+                continue;
+            result.push({ matcher, sentinel });
+        }
+    }
+    return result;
+}
 /**
  * Compute the per-IDE peaks hook entries to merge into the settings file.
  * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
  * remains exported (computed for claude-code) for backward compat.
+ *
+ * Slice #013 (`--no-progress` flag): when `skipProgress` is true, the
+ * progress-start entry is omitted from the returned list. Install with this
+ * flag will (a) NOT emit the progress hook entry, and (b) will idempotently
+ * remove any previously-installed progress entry (sentinel-based merge).
+ *
+ * Slice #014 (refactor — full removal): only the gate-enforce entry is
+ * ever emitted. The `skipProgress` parameter is kept for API stability
+ * but is a no-op — the returned list is always single-entry. The progress
+ * entry's sentinel is included in the legacy sentinel set so uninstall
+ * can find + remove any stale progress-start entry that an older
+ * `peaks hooks install` may have written before this slice.
  */
-function resolveHookEntries(ide) {
+function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
     return [
-        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent },
-        { sentinel: spec.hookProgressSentinel, matcher: spec.hookProgressMatcher, command: spec.hookProgressCommand, event: spec.hookProgressEvent }
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
     ];
 }
-/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. */
+/**
+ * Legacy sentinel set used by uninstall + status to find and remove stale
+ * progress-start entries written by pre-#014 installs. The progress-start
+ * sentinel is the literal substring that older installs emitted.
+ */
+const LEGACY_PROGRESS_START_SENTINEL = 'peaks progress start';
+function resolveLegacySentinels(ide) {
+    if (ide === 'trae') {
+        return ['peaks hook handle', LEGACY_PROGRESS_START_SENTINEL];
+    }
+    return [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
+}
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
 export const PEAKS_HOOK_ENTRIES = (() => {
     const spec = resolveHookSpec('claude-code');
     return [
-        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent },
-        { sentinel: spec.hookProgressSentinel, matcher: spec.hookProgressMatcher, command: spec.hookProgressCommand, event: spec.hookProgressEvent }
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
     ];
 })();
 function isInstalledForIde(settings, ide) {
@@ -133,8 +205,43 @@ function isInstalledForIde(settings, ide) {
     }
     return false;
 }
+/**
+ * Slice #014: detect the "stale progress entry after pre-#014 install"
+ * case. The desired shape is gate-enforce-only. If the file currently
+ * has a peaks-managed progress-start entry (left behind by a pre-#014
+ * install), the install is NOT a no-op — it must strip the stale
+ * entry. This helper returns true exactly when the desired shape is
+ * fully reflected on disk: gate-enforce present AND no legacy
+ * progress-start present.
+ */
+function shapeMatchesDesired(settings, ide) {
+    const desiredEntries = resolveHookEntries(ide);
+    const desiredSentinels = new Set(desiredEntries.map((e) => e.sentinel));
+    const allPeaksSentinels = resolveLegacySentinels(ide);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        const present = readHookEventEntries(settings, eventKey);
+        const peaksPresent = present.filter((e) => entryIsPeaksManaged(e, allPeaksSentinels));
+        // (a) every peaks-managed entry currently on disk must match the
+        //     desired sentinel set (no stale entries the caller wants removed).
+        for (const entry of peaksPresent) {
+            const entrySentinels = (entry.hooks ?? []).map((h) => allPeaksSentinels.find((s) => String(h.command ?? '').includes(s))).filter((s) => Boolean(s));
+            if (entrySentinels.some((s) => !desiredSentinels.has(s))) {
+                return false;
+            }
+        }
+        // (b) every desired entry must be on disk.
+        for (const sentinel of desiredSentinels) {
+            const has = peaksPresent.some((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(sentinel)));
+            if (!has)
+                return false;
+        }
+    }
+    return true;
+}
 export function planHookInstall(scope, projectRoot, options) {
     const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
     const root = resolveSettingsRoot(scope, projectRoot);
     const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
     assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
@@ -152,24 +259,29 @@ export function planHookInstall(scope, projectRoot, options) {
     };
 }
 /** Merge all peaks-managed hook entries into settings, preserving all other keys and hooks. */
-function withHooksInstalledForIde(settings, ide) {
+function withHooksInstalledForIde(settings, ide, _skipProgress = false) {
     const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
         ? settings.hooks
         : {};
-    // Per-IDE entries may map to different events (Trae: both on beforeToolCall;
-    // Claude: both on PreToolUse). Group by event so each event array is
-    // independently merged.
+    // Per-IDE entries may map to different events (Trae: gate-enforce on
+    // beforeToolCall; Claude: gate-enforce on PreToolUse). Group by event
+    // so each event array is independently merged.
     const ourByEvent = new Map();
     for (const spec of resolveHookEntries(ide)) {
         const list = ourByEvent.get(spec.event) ?? [];
         list.push(spec);
         ourByEvent.set(spec.event, list);
     }
-    const sentinels = resolveHookEntries(ide).map((e) => e.sentinel);
+    // Slice #014: the legacy sentinel set includes the progress-start
+    // sentinel so a pre-#014 install's stale progress-start entry is
+    // stripped by the filter (the file converges on the new
+    // gate-enforce-only shape, idempotently). The desired set (passed
+    // in below) only contains the gate-enforce sentinel.
+    const allSentinels = resolveLegacySentinels(ide);
     const nextHooks = { ...existingHooks };
     for (const [eventKey, ourEntries] of ourByEvent) {
         const existing = readHookEntriesFromHooks(nextHooks, eventKey);
-        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, allSentinels));
         const ourFormatted = ourEntries.map((spec) => ({
             matcher: spec.matcher,
             hooks: [{ type: 'command', command: spec.command }]
@@ -189,17 +301,25 @@ function withHooksInstalledForIde(settings, ide) {
 }
 export function applyHookInstall(scope, projectRoot, options) {
     const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
     const root = resolveSettingsRoot(scope, projectRoot);
     const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
     assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
     const exists = existsSync(settingsPath);
     const settings = exists ? readJsonObjectFile(settingsPath) : {};
     const spec = resolveHookSpec(ide);
+    // Slice #014: `alreadyInstalled` reflects the FULL desired shape
+    // (gate-enforce-only + no stale progress-start entry). Pre-#014
+    // installs that left a progress-start entry behind will be treated
+    // as not-yet-installed, so the merge strips the stale entry on the
+    // next install call. This is the only path that converges the file
+    // on the new shape; pure presence-checks are insufficient.
+    const alreadyInstalled = shapeMatchesDesired(settings, ide);
     const baseResult = {
         scope,
         settingsPath,
         exists,
-        alreadyInstalled: isInstalledForIde(settings, ide),
+        alreadyInstalled,
         desiredCommand: spec.hookEnforceCommand,
         sentinel: spec.hookEnforceSentinel,
         matcher: spec.hookEnforceMatcher
@@ -220,7 +340,12 @@ export function removeHookInstall(scope, projectRoot, options) {
     }
     const settings = readJsonObjectFile(settingsPath);
     const existingHooks = settings.hooks ?? {};
-    const sentinels = resolveHookEntries(ide).map((e) => e.sentinel);
+    // Slice #014: uninstall must remove the gate-enforce entry AND any
+    // legacy progress-start entry that a pre-#014 install left behind.
+    // The legacy sentinel set covers both shapes so the uninstall
+    // converges the file on "no peaks-managed entries", regardless of
+    // what shape the file was in when the user ran uninstall.
+    const sentinels = resolveLegacySentinels(ide);
     const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
     let removedAny = false;
     const nextHooks = { ...existingHooks };

package/dist/src/shared/incrementing-number.d.ts

@@ -11,14 +11,6 @@
  * @returns Next available number (1, 2, 3, ...)
  */
 export declare function getNextNumber(dirPath: string): number;
-/**
- * Build a numbered filename from a number and description.
- * Format: 001-description-slug.md
- *
- * @param number - The file number (will be zero-padded to 3 digits)
- * @param description - Human-readable description (converted to kebab-case slug)
- * @returns Formatted filename like "001-feature-name.md"
- */
 export declare function buildNumberedFilename(number: number, description: string): string;
 /**
  * Get the next numbered file path in a directory.

package/dist/src/shared/incrementing-number.js

@@ -34,13 +34,23 @@ export function getNextNumber(dirPath) {
  * @param description - Human-readable description (converted to kebab-case slug)
  * @returns Formatted filename like "001-feature-name.md"
  */
+// Windows supports up to 255 chars per filename component (and 260 for the
+// full path). Pre-#015 the slug was silently truncated to 50 chars, which
+// produced orphaned artefacts (the on-disk file no longer matched the
+// request-id and the state machine could not find it). 255 is the OS-level
+// ceiling; if a requestId exceeds that, `mkdir` / `writeFile` will surface a
+// real ENAMETOOLONG error instead of a silent mismatch. We reserve 4 chars
+// for the `<NNN>-` numeric prefix and 3 chars for the `.md` suffix, so
+// the slug may be at most 248 chars (giving 4 + 248 + 3 = 255 total).
+const MAX_FILENAME_LENGTH = 255;
+const MAX_FILENAME_SLUG_LENGTH = MAX_FILENAME_LENGTH - 7;
 export function buildNumberedFilename(number, description) {
     const padded = String(number).padStart(3, '0');
     const slug = description
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '')
-        .slice(0, 50); // Limit slug length
+        .slice(0, MAX_FILENAME_SLUG_LENGTH);
     return `${padded}-${slug}.md`;
 }
 /**

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.4";
+export declare const CLI_VERSION = "1.3.5";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.4";
+export const CLI_VERSION = "1.3.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-qa/references/qa-fanout-contract.md

@@ -40,7 +40,7 @@ issues 3 dispatch calls in a **single message**:
 peaks sub-agent dispatch qa-business \
   --prompt "<qa-business contract below, plus runtime args: project=<repo>,
              session-id=<sid>, request-id=<rid>.
-             Write your evidence at .peaks/<sid>/qa/test-reports/<rid>.md
+             Write your evidence at .peaks/_runtime/<sid>/qa/test-reports/<rid>.md
              and return ONLY the path. While running, call
              peaks sub-agent heartbeat --record <dispatchRecordPath>
              --status running --progress <pct> --note '<text>' at least every 30s;
@@ -48,11 +48,11 @@ peaks sub-agent dispatch qa-business \
   --request-id <rid> --session-id <sid> --project <repo> --json
 
 peaks sub-agent dispatch qa-perf \
-  --prompt "<qa-perf contract below, plus runtime args; output .peaks/<sid>/qa/performance-findings.md>" \
+  --prompt "<qa-perf contract below, plus runtime args; output .peaks/_runtime/<sid>/qa/performance-findings.md>" \
   --request-id <rid> --session-id <sid> --project <repo> --json
 
 peaks sub-agent dispatch qa-security \
-  --prompt "<qa-security contract below, plus runtime args; output .peaks/<sid>/qa/security-findings.md>" \
+  --prompt "<qa-security contract below, plus runtime args; output .peaks/_runtime/<sid>/qa/security-findings.md>" \
   --request-id <rid> --session-id <sid> --project <repo> --json
 ```
 
@@ -80,9 +80,9 @@ string. The recommended names above are hints, not a hard list.
 
 | Sub-agent | Reads | Writes | Must not depend on |
 |---|---|---|---|
-| `qa-business` (or subdivisions) | PRD body, RD planning, codegraph, project scan, existing system | `qa/test-reports/<rid>.md` | perf / security output (run in parallel) |
-| `qa-perf` | RD planning, codegraph, perf baselines from prior slices | `qa/performance-findings.md` | business / security output |
-| `qa-security` | PRD body (trust model), codegraph, RD planning, existing security notes | `qa/security-findings.md` | business / perf output |
+| `qa-business` (or subdivisions) | PRD body, RD planning, codegraph, project scan, existing system | `.peaks/_runtime/<sid>/qa/test-reports/<rid>.md` | perf / security output (run in parallel) |
+| `qa-perf` | RD planning, codegraph, perf baselines from prior slices | `.peaks/_runtime/<sid>/qa/performance-findings.md` | business / security output |
+| `qa-security` | PRD body (trust model), codegraph, RD planning, existing security notes | `.peaks/_runtime/<sid>/qa/security-findings.md` | business / perf output |
 
 The reducer merges all 3 outputs into the final QA verdict. None of
 the 3 sub-agents reads another sub-agent's output (no peer-to-peer

package/skills/peaks-rd/SKILL.md

@@ -119,21 +119,6 @@ On the first presence:set in a project, ensure the out-of-band status bar is ins
 peaks statusline install --project <repo>   # idempotent; skips if already installed
 ```
 
-**Auto-spawn a progress watch terminal once per slice (BLOCKING on the first phase transition).** The user opens a fresh VSCode window per slice, not per Bash call. Without a separate progress terminal the user has no live signal that the sub-agent is alive — the only signal they have is the static statusline. So at the first phase transition of every slice, fire `peaks progress start` ONCE. The CLI auto-spawns a new terminal tab running `peaks progress watch` and the user can close the new tab at any time. Do NOT re-invoke on every phase change — one per slice is the contract. The LLM-side cost of this one invocation is one Bash call plus a small JSON envelope; the watch side is a 1s file poll that does not consume LLM tokens.
-
-```bash
-# At the first phase transition of a slice (after the first
-# peaks progress step), fire the watch:
-peaks progress start --project <repo> --reason "rd-implementing for <rid>"
-
-# On every subsequent phase transition, only update the
-# progress file — the watch is already running in another tab:
-peaks progress step --project <repo> --request-id <rid> --role rd \
-  --step "running pnpm test" --phase running
-```
-
-If `peaks progress start` is unsupported on the current platform (no terminal emulator, headless container, etc.) it returns a recoverable error envelope. Surface that in the RD handoff so the user knows the auto-spawn failed; the sub-agent can still emit `peaks progress step` writes that the user reads from the on-disk file. The auto-spawn is convenience, not a gate.
-
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-solo/references/runbook.md

@@ -20,12 +20,12 @@ peaks skill runbook peaks-solo --json
 peaks workspace init --project <repo> --json
 peaks workspace reconcile --project <repo> --json
 peaks scan archetype --project <repo> --json
-# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
-# → copy libraries[] into .peaks/<session-id>/rd/project-scan.md under `## Library versions`
+# → copy archetype, frontendOnly, signals into .peaks/_runtime/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
+# → copy libraries[] into .peaks/_runtime/<session-id>/rd/project-scan.md under `## Library versions`
 peaks scan libraries --project <repo> --json
 # → if archetype != greenfield AND archetype != unknown:
 peaks scan existing-system --project <repo> --json
-# → copy tokens, sources, conventions, inconsistencies into .peaks/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
+# → copy tokens, sources, conventions, inconsistencies into .peaks/_runtime/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
 
 # 1. Peaks-Cli Standards preflight + apply
 #    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
@@ -55,7 +55,7 @@ peaks request transition <rid> --role prd --state handed-off --project <repo> --
 
 # 3. Peaks-Cli Swarm parallel — sub-agent fan-out (peaks sub-agent dispatch, NOT Skill tool)
 #    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
-#    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
+#    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then launches one
 #    `peaks sub-agent dispatch <role>` call per sub-agent in the same message.
 #    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
 #    prompt template; the role's required artefact paths are listed there.
@@ -80,36 +80,36 @@ peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-
 #     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
 # 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):
 peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
-ls .peaks/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
-# feature / refactor → ls .peaks/<sid>/rd/tech-doc.md
-# bugfix             → ls .peaks/<sid>/rd/bug-analysis.md
-ls .peaks/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+ls .peaks/_runtime/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/_runtime/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/_runtime/<sid>/rd/bug-analysis.md
+ls .peaks/_runtime/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
 # ui (only when in plan):
-ls .peaks/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
+ls .peaks/_runtime/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
 # Apply the degradation rules in the main SKILL.md if any artefact is missing.
 # → Peaks-Cli Gate B convergence check. Assisted/Strict: [CONFIRM]
 
 # 4. Peaks-Cli RD planning artifact (the file required by the prerequisite gate)
-#    feature / refactor → write .peaks/<id>/rd/tech-doc.md
-#    bugfix             → write .peaks/<id>/rd/bug-analysis.md
+#    feature / refactor → write .peaks/_runtime/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/_runtime/<id>/rd/bug-analysis.md
 #    config             → no planning artifact required at this state
 #    docs / chore       → no planning artifact required
 peaks request transition <rid> --role rd --state implemented --project <repo> --json
 
 # 5. Peaks-Cli Code review + security review BEFORE qa-handoff transition.
 #    Produce the evidence files the CLI gate enforces:
-#      - .peaks/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
-#      - .peaks/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#      - .peaks/_runtime/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/_runtime/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
 #    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
 peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
 
 # 6. Peaks-Cli QA validation (AUTO-PROCEED from RD in full-auto)
 #    Before each QA transition, produce the evidence files the CLI gate enforces:
-#      Before qa:running        → .peaks/<id>/qa/test-cases/<rid>.md
+#      Before qa:running        → .peaks/_runtime/<id>/qa/test-cases/<rid>.md
 peaks request transition <rid> --role qa --state running --project <repo> --json
-#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
-#                                 + .peaks/<id>/qa/security-findings.md
-#                                 + .peaks/<id>/qa/performance-findings.md (feature/refactor only)
+#      Before qa:verdict-issued → .peaks/_runtime/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/_runtime/<id>/qa/security-findings.md
+#                                 + .peaks/_runtime/<id>/qa/performance-findings.md (feature/refactor only)
 peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
 # → Peaks-Cli Gate D check. Assisted/Strict: [CONFIRM]
 
@@ -135,12 +135,12 @@ peaks openspec archive <cid> --project <repo> --apply --json
 peaks workspace reconcile --project <repo> --apply --older-than 7
 
 # 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
-#     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md. Inside the
+#     peaks-txt writes the handoff capsule to .peaks/_runtime/<id>/txt/handoff.md. Inside the
 #     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
 #     stable project fact surfaced this session.
 #
 # 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
-#      grep -n "peaks-memory:start" .peaks/<id>/txt/handoff.md
+#      grep -n "peaks-memory:start" .peaks/_runtime/<id>/txt/handoff.md
 #      Record the count. This is the skill doing the work, not a CLI command —
 #      we deliberately do not ship a `peaks memory scan` because the LLM is
 #      the only consumer and the LLM has grep.
@@ -148,7 +148,7 @@ peaks workspace reconcile --project <repo> --apply --older-than 7
 # 10b. AskUserQuestion (only if 10a returned count >= 1):
 #      "The TXT handoff has N peaks-memory:start blocks. Persist to .peaks/memory/?
 #       (a) Apply all — `peaks memory extract --project <repo>
-#                            --artifact .peaks/<id>/txt/handoff.md --apply --json`
+#                            --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json`
 #       (b) Apply selectively — re-edit handoff.md first, then re-apply
 #       (c) Skip for now — blocks stay in the handoff only, no .peaks/memory/ write"
 #      If 10a returned 0 AND the session surfaced a stable project fact
@@ -156,7 +156,7 @@ peaks workspace reconcile --project <repo> --apply --older-than 7
 #      back and embed at least one block before Solo can advance.
 
 # 10c. After the user picks (a) or (b), run:
-peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
+peaks memory extract --project <repo> --artifact .peaks/_runtime/<id>/txt/handoff.md --apply --json
 #      --apply is REQUIRED to write .peaks/memory/; without it the command only
 #      previews. The extract regenerates index.json in the same call.
 

package/skills/peaks-solo/references/swarm-dispatch-contract.md

@@ -16,7 +16,7 @@ Return a compact JSON envelope — do not write prose.
 ## Hard prohibitions
 - Do NOT call Skill(skill="..."). You are the role.
 - Do NOT call `peaks skill presence:set` — the main loop owns .peaks/.active-skill.json.
-  If you need to record state, write to .peaks/<session-id>/system/sub-agent-<role>.json.
+  If you need to record state, write to .peaks/_runtime/<session-id>/system/sub-agent-<role>.json.
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
 - Do NOT ask the user interactive questions. If you need clarification, return
   {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
@@ -47,14 +47,14 @@ Steps:
 3. Read <project-scan-path> for component library / CSS framework.
 4. Run the prototype fidelity gate: Figma file? PRD visuals? Headed browser?
 5. Write TWO artefacts:
-   - .peaks/<sid>/ui/design-draft.md
-   - .peaks/<sid>/ui/requests/<rid>.md
+   - .peaks/_runtime/<sid>/ui/design-draft.md
+   - .peaks/_runtime/<sid>/ui/requests/<rid>.md
 6. Return:
    {
      "role": "ui",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/ui/design-draft.md", ".peaks/_runtime/<sid>/ui/requests/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }
@@ -80,15 +80,15 @@ Steps:
    into rd/project-scan.md.
 5. Read <existing-system-path> if archetype is legacy-*.
 6. Write the type-appropriate planning artefact:
-   - feature | refactor  → .peaks/<sid>/rd/tech-doc.md
-   - bugfix              → .peaks/<sid>/rd/bug-analysis.md
+   - feature | refactor  → .peaks/_runtime/<sid>/rd/tech-doc.md
+   - bugfix              → .peaks/_runtime/<sid>/rd/bug-analysis.md
    - config | docs | chore → no planning artefact required. Return skipped.
 7. Return:
    {
      "role": "rd-planning",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/rd/tech-doc.md"],   // or [] when skipped
+     "artefacts": [".peaks/_runtime/<sid>/rd/tech-doc.md"],   // or [] when skipped
      "warnings": [],
      "blockedReason": null
    }
@@ -106,14 +106,14 @@ Steps:
 2. peaks request show <rid> --role prd --project <repo> --json
 3. peaks request show <rid> --role rd  --project <repo> --json
 4. Read <project-scan-path>.
-5. Write .peaks/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
+5. Write .peaks/_runtime/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
    acceptance items (use **Acceptance:** A1, A2 style).
 6. Return:
    {
      "role": "qa-test-cases",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/qa/test-cases/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/qa/test-cases/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }

package/dist/src/cli/commands/progress-close-kill.d.ts

@@ -1,51 +0,0 @@
-/**
- * Best-effort close of a spawned `peaks progress watch`
- * window. Used by `peaks progress close` (manual escape
- * hatch) and by the watch-side auto-exit when the sub-agent
- * hits a terminal phase.
- *
- * The close is best-effort by design: we never throw from
- * individual signals. One failed close primitive is a UX
- * paper cut, not a correctness bug — the caller still clears
- * the spawn record after this returns.
- *
- * Cross-platform strategy:
- *
- *   - macOS: pkill the watch process by command pattern
- *     (matches the project path, so we never close the
- *     wrong window), then send AppleScript to Terminal.app
- *     to close the window by `custom title`. Terminal.app
- *     is the dominant macOS terminal, and `custom title` is
- *     the only stable identifier we can target from outside
- *     the running shell.
- *   - Linux: pkill the watch process, then try `wmctrl -c
- *     peaks-cli-progress` to close the terminal window by
- *     WM class (set in `progress start` for alacritty /
- *     kitty; gnome-terminal / konsole / xfce4-terminal
- *     close on their own when the child exits). wmctrl is
- *     not always installed; we silently no-op on
- *     "command not found" (exit 127) and surface other
- *     errors as warnings.
- *   - Windows: `taskkill /F /FI "WINDOWTITLE eq
- *     peaks-cli:*"` to kill the cmd.exe wrapper. We use
- *     the title prefix because the exact title includes the
- *     `--reason` suffix which we do not know here.
- *
- * The kill is intentionally not a single primitive (e.g.
- * `process.kill(-pid, 'SIGTERM')` on the process group).
- * The launcher's PID is the spawn-time PID (osascript on
- * macOS, gnome-terminal on Linux), not the long-lived
- * watch process — and the long-lived process is the one we
- * actually need to terminate to make the terminal close.
- * Targeting by command pattern (pkill) + window title
- * (AppleScript / wmctrl / taskkill) is more reliable than
- * PID chasing across detached children.
- */
-import type { ProgressSpawnRecord } from '../../services/progress/progress-service.js';
-export type KillSpawnedTerminalResult = {
-    /** Each signal that was successfully sent. */
-    signals: string[];
-    /** Soft failures (e.g. pkill matched no process, wmctrl missing). */
-    warnings: string[];
-};
-export declare function killSpawnedTerminal(record: ProgressSpawnRecord, canonicalProjectRoot: string, currentPlatform: NodeJS.Platform): Promise<KillSpawnedTerminalResult>;