peaks-loop 4.1.2 → 4.1.3

package/scripts/watch-tree.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// scripts/watch-tree.mjs
+//
+// The DIRECTORY-TREE half of the dev watcher: walk the inputs, and keep one `fs.watch`
+// handle per directory so a file created in a directory that did not exist at startup
+// is still seen. Split out of `scripts/watch.mjs` (rid-043) along the seam the file
+// already had — everything here touches the filesystem and nothing here knows about
+// builds, debouncing or status lines.
+//
+// `collectDirectories` is injectable (`options.collectDirectories`) and so is the
+// `watch` primitive (`options.watch`), which is how the tests drive the tree without
+// a real timer; both defaults live in `watch.mjs`'s callers, not here.
+
+import { watch as nodeWatch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function getErrorCode(error) {
+  return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+}
+
+function isMissingPathError(error) {
+  return getErrorCode(error) === 'ENOENT';
+}
+
+export async function collectDirectories(root) {
+  const directories = [];
+  const visited = new Set();
+
+  async function visit(directory) {
+    if (visited.has(directory)) {
+      return;
+    }
+
+    visited.add(directory);
+
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (isMissingPathError(error)) {
+        return;
+      }
+
+      throw error;
+    }
+
+    directories.push(directory);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      await visit(join(directory, entry.name));
+    }
+  }
+
+  await visit(root);
+  return directories;
+}
+
+export function createDirectoryTreeWatcher(root, options = {}) {
+  const watch = options.watch ?? nodeWatch;
+  const collect = options.collectDirectories ?? collectDirectories;
+  const onChange = options.onChange ?? (() => {});
+  const watchers = new Map();
+  let refreshPromise = null;
+  let refreshRequested = false;
+  let isClosed = false;
+
+  const syncWatchers = async () => {
+    const directories = await collect(root);
+    const nextDirectories = new Set(directories);
+
+    for (const [directory, watcher] of watchers) {
+      if (nextDirectories.has(directory)) {
+        continue;
+      }
+
+      watcher.close();
+      watchers.delete(directory);
+    }
+
+    for (const directory of directories) {
+      if (watchers.has(directory)) {
+        continue;
+      }
+
+      const watcher = watch(directory, () => {
+        onChange();
+        void requestRefresh();
+      });
+      watchers.set(directory, watcher);
+    }
+  };
+
+  const requestRefresh = async () => {
+    if (isClosed) {
+      return;
+    }
+
+    refreshRequested = true;
+    if (refreshPromise) {
+      return refreshPromise;
+    }
+
+    refreshPromise = (async () => {
+      do {
+        refreshRequested = false;
+        await syncWatchers();
+      } while (refreshRequested && !isClosed);
+    })();
+
+    try {
+      await refreshPromise;
+    } finally {
+      refreshPromise = null;
+    }
+  };
+
+  return {
+    async start() {
+      await requestRefresh();
+    },
+    async close() {
+      isClosed = true;
+
+      if (refreshPromise) {
+        await refreshPromise.catch(() => undefined);
+      }
+
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+
+      watchers.clear();
+    }
+  };
+}

package/scripts/watch.mjs

@@ -1,30 +1,24 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { watch as nodeWatch } from 'node:fs';
-import { readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { installBundledSkills } from './install-skills.mjs';
+import { collectDirectories, createDirectoryTreeWatcher } from './watch-tree.mjs';
 
 export const WATCHED_INPUTS = ['src', 'schemas', 'skills'];
 export const DEFAULT_BUILD_COMMAND = ['pnpm', ['run', 'build']];
 
+export { collectDirectories, createDirectoryTreeWatcher };
+
 function getErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-function getErrorCode(error) {
-  return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
-}
-
 function isAbortError(error) {
   return error instanceof Error && error.name === 'AbortError';
 }
 
-function isMissingPathError(error) {
-  return getErrorCode(error) === 'ENOENT';
-}
-
 export function runCommand(command, args, options = {}) {
   return new Promise((resolvePromise, rejectPromise) => {
     let child;
@@ -80,122 +74,6 @@ export function runCommand(command, args, options = {}) {
   });
 }
 
-export async function collectDirectories(root) {
-  const directories = [];
-  const visited = new Set();
-
-  async function visit(directory) {
-    if (visited.has(directory)) {
-      return;
-    }
-
-    visited.add(directory);
-
-    let entries;
-    try {
-      entries = await readdir(directory, { withFileTypes: true });
-    } catch (error) {
-      if (isMissingPathError(error)) {
-        return;
-      }
-
-      throw error;
-    }
-
-    directories.push(directory);
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) {
-        continue;
-      }
-
-      await visit(join(directory, entry.name));
-    }
-  }
-
-  await visit(root);
-  return directories;
-}
-
-export function createDirectoryTreeWatcher(root, options = {}) {
-  const watch = options.watch ?? nodeWatch;
-  const collect = options.collectDirectories ?? collectDirectories;
-  const onChange = options.onChange ?? (() => {});
-  const watchers = new Map();
-  let refreshPromise = null;
-  let refreshRequested = false;
-  let isClosed = false;
-
-  const syncWatchers = async () => {
-    const directories = await collect(root);
-    const nextDirectories = new Set(directories);
-
-    for (const [directory, watcher] of watchers) {
-      if (nextDirectories.has(directory)) {
-        continue;
-      }
-
-      watcher.close();
-      watchers.delete(directory);
-    }
-
-    for (const directory of directories) {
-      if (watchers.has(directory)) {
-        continue;
-      }
-
-      const watcher = watch(directory, () => {
-        onChange();
-        void requestRefresh();
-      });
-      watchers.set(directory, watcher);
-    }
-  };
-
-  const requestRefresh = async () => {
-    if (isClosed) {
-      return;
-    }
-
-    refreshRequested = true;
-    if (refreshPromise) {
-      return refreshPromise;
-    }
-
-    refreshPromise = (async () => {
-      do {
-        refreshRequested = false;
-        await syncWatchers();
-      } while (refreshRequested && !isClosed);
-    })();
-
-    try {
-      await refreshPromise;
-    } finally {
-      refreshPromise = null;
-    }
-  };
-
-  return {
-    async start() {
-      await requestRefresh();
-    },
-    async close() {
-      isClosed = true;
-
-      if (refreshPromise) {
-        await refreshPromise.catch(() => undefined);
-      }
-
-      for (const watcher of watchers.values()) {
-        watcher.close();
-      }
-
-      watchers.clear();
-    }
-  };
-}
-
 export async function rebuildOnce(options = {}) {
   const runner = options.runner ?? runCommand;
   const installer = options.installer ?? installBundledSkills;

package/skills/peaks-status/SKILL.md

@@ -52,33 +52,50 @@ peaks project memories --project <repo> --json  # load durable memory
 
 ## Step 1: Read the current state
 
-Use only existing CLI primitives (no new commands). **Important contract note**: `peaks session list` does NOT support `--project` (verified by dogfood 2026-06-04); it returns all sessions globally. To scope to the current project, read `.peaks/.session.json` for the bound `sessionId`, then use `peaks session info <sid>` for the bound session's full state, and filter `peaks session list` output by `projectRoot` to find other sessions in the same project.
+Use only existing primitives (no new commands). **Important contract note**: `peaks session list` does NOT support `--project` (verified by dogfood 2026-06-04); it returns all sessions globally. To scope to the current project, read `.peaks/.session.json` for the bound `sessionId`, then use `peaks session info <sid>` for the bound session's full state, and filter `peaks session list` output by `projectRoot` to find other sessions in the same project.
+
+### 1a. The three paths that have an MCP tool — ONE call
+
+`peaks_status` returns `peaks skill presence --json`, `peaks session list --json` and — when `rid` and `role` are given — `peaks request show <rid> --role <role> --json --project <project>`. Each CLI result comes back VERBATIM under its own key (`skill-presence`, `session-list`, `request-show`); a key is absent when that call was not run. Call it once and read the keys.
+
+- Pass `rid` and `role` only when a specific request is in flight (the `rid` from Step 1c). When it is not, call with just `project` and read the two keys that come back.
+- If the tool is not available, or the call fails, or the result carries `isError`, **fall back to Step 1b** — do not report a partial read as if it were the whole picture. A failed call is a failed call; the keys you did not get are not "nothing there".
+
+### 1b. Bash fallback — the same three commands, always available
+
+Run these when 1a did not answer (MCP not installed / not registered / call failed). They are the SAME argv the tool runs, so the output is identical:
 
 ```bash
 # 1. Active skill presence
 peaks skill presence --json
 
-# 2. The bound session id (from .peaks/.session.json — local read, no CLI)
-sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
-
-# 3. The bound session's full state
-peaks session info "$sid" --json
-
 # 4. All sessions globally (then post-filter to current project)
 peaks session list --json
 # Note: this returns all sessions across all projects; the wrapper filters by
 # matching `projectRoot` against the bound session's `projectRoot` to show only
 # the sessions for THIS project. Sessions from other projects are ignored.
 
+# 6. Per-request detail (if a specific rid is in flight) — one call per role
+peaks request show <rid> --role <role> --json --project <project>
+# e.g. --role rd for the RD artifact, --role qa for the QA report
+```
+
+### 1c. Paths with no MCP tool — always Bash
+
+```bash
+# 2. The bound session id (from .peaks/.session.json — local read, no CLI)
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 3. The bound session's full state
+peaks session info "$sid" --json
+
 # 5. Per-request role state (PRD / RD / QA / TXT for the bound project)
 peaks project dashboard --project <repo> --json
-
-# 6. Per-request detail (if a specific rid is in flight)
-peaks request show <rid> --role rd --project <repo> --json
-peaks request show <rid> --role qa --project <repo> --json
 ```
 
-All 6 calls are read-only. Total cost: sub-second. (The original draft said "5 calls"; the corrected count is 6 because the post-filter step is now explicit.)
+`peaks project dashboard` is deliberately **not** in the MCP surface: it shells out to `git` to resolve the project root, which the read-only definition forbids. It stays on Bash.
+
+All of these calls are read-only. Total cost: sub-second.
 
 ## Step 2: Render the status table
 
@@ -136,7 +153,8 @@ Then yield control.
 ## Hard rules (do NOT skip)
 
 - **Never write to `.peaks/_runtime/<sid>/`.** This skill is read-only on the workspace; it only reads existing CLI state.
-- **Never add a new `peaks <cmd>`.** Use only the existing read-only CLI primitives: `peaks skill presence`, `peaks session list`, `peaks session info`, `peaks project dashboard`, `peaks request show`. **Note**: `peaks session list` does not support `--project`; filter its output by `projectRoot` post-hoc.
+- **Never add a new `peaks <cmd>`.** Use only the existing read-only CLI primitives: `peaks skill presence`, `peaks session list`, `peaks session info`, `peaks project dashboard`, `peaks request show` — plus the `peaks_status` MCP tool, which is those same argv behind one call. **Note**: `peaks session list` does not support `--project`; filter its output by `projectRoot` post-hoc.
+- **A failed MCP call is not an empty answer.** If `peaks_status` is unavailable or returns `isError`, run the Step 1b commands. Never render a table from the keys that happened to come back while a failed key is silently missing.
 - **Never auto-progress the workflow.** The status table is informational only. The user chooses what to do via `AskUserQuestion`. Never silent about what comes next — always present the 3 options.
 - **Never expose sensitive data in the table.** Do NOT include full PRD bodies, full tech-doc bodies, or any test code in the table. Just state names, paths, and counts.