peaks-loop 4.1.1 → 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-audit/SKILL.md

@@ -56,7 +56,7 @@ The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, a
 When a workflow surfaces a human need (a sentence, a ticket summary, a voice note, a vague "I want X"), call `peaks-audit` BEFORE any other skill:
 
 ```text
-need expressed  →  peaks audit-goal  →  (user accepts goal)  →  peaks-prd  →  peaks-rd  →  peaks-qa
+need expressed  →  peaks audit goal  →  (user accepts goal)  →  peaks-prd  →  peaks-rd  →  peaks-qa
                        ▲
                        │
               you are here on first contact
@@ -80,14 +80,14 @@ Do NOT invoke peaks-audit when the user is asking for a code review, a test run,
 ### Intended CLI form (L2.4 — not yet registered in `src/cli/commands/audit-commands.ts`)
 
 ```bash
-peaks audit-goal --need "<natural language description of the need>" --json
+peaks audit goal --need "<natural language description of the need>" --json
 ```
 
 > **Deviation note:** at the time of this writing, only `peaks audit red-lines` and `peaks audit static` are registered as `peaks audit` subcommands. The `audit-goal` subcommand is **not yet wired** in `src/cli/commands/audit-commands.ts`. Callers reach the primitive through the TypeScript module below. The CLI registration is tracked separately and must not be conflated with the primitive itself.
 
 ### Service-layer form (authoritative, used today)
 
-`peaks audit-goal` is a thin wrapper around the `auditGoal()` function in `src/services/audit/audit-goal-service.ts`. Two integration paths exist today:
+`peaks audit goal` is a thin wrapper around the `auditGoal()` function in `src/services/audit/audit-goal-service.ts`. Two integration paths exist today:
 
 **1. Direct TypeScript call** (used by `src/services/final-review/final-review-service.ts`, `src/services/slice/llm-arbitrator.ts`, `src/services/slice/multi-pass-orchestrator.ts`):
 

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.
 

package/dist/services/codegraph/codegraph-include-reconciler.d.ts

@@ -1,10 +0,0 @@
-export type CodegraphIncludeNormalizePlan = {
-    readonly changed: boolean;
-    readonly include: readonly string[];
-    readonly addedPatterns: readonly string[];
-};
-export declare function normalizeCodegraphInclude(input: {
-    readonly include: readonly string[];
-    readonly candidateExtensions: readonly string[];
-}): CodegraphIncludeNormalizePlan;
-export declare function upstreamUnnamedIncludeExtensions(): readonly string[];

package/dist/services/codegraph/codegraph-include-reconciler.js

@@ -1,160 +0,0 @@
-// src/services/codegraph/codegraph-include-reconciler.ts
-//
-// Slice-002 of `2026-09-16-codegraph-index-integrity` — the INCLUDE axis
-// of the config repair. It answers one question:
-//
-//   "Which extensions does upstream's extractor support but upstream's own
-//    default `include` template never names, and which of those does THIS
-//    project's `include` still not admit?"
-//
-// Why this exists (the real defect, measured): upstream
-// `@colbymchenry/codegraph` decides what to parse from its own
-// `EXTENSION_MAP` (37 extensions in 0.7.10), but `init` writes a 32-entry
-// `DEFAULT_CONFIG.include` template that names only 32 of them. Five
-// supported extensions are therefore absent from every fresh config:
-// `.mjs`, `.cjs`, `.pyw`, `.hxx`, `.rake`. Upstream's `mergeConfig` has no
-// separate override channel — `config.json`'s `include` replaces the
-// defaults wholesale — so a fresh clone indexes none of them while
-// `peaks codegraph status` still prints `[OK] Index is up to date`. On this
-// repo that was 31 tracked files (30 `.mjs` + 1 `.cjs`) absent from a
-// 1220-row index. It is the same class of defect as upstream's default
-// `exclude` template colliding with real source directories, which slice S2
-// of `2026-09-12-codegraph-exclude-integrity` already self-heals at the
-// `init` seam; the include axis was simply never reconciled.
-//
-// Genericity (binding — mirrors the exclude reconciler): no hardcoded
-// extension list, no hardcoded rule names, no project-specific paths. The
-// candidate set is COMPUTED from upstream's own two tables (`EXTENSION_MAP`
-// in `dist/extraction/grammars.js`, `DEFAULT_CONFIG` in `dist/types.js`),
-// and every candidate is confirmed against upstream's own decision pair
-// (`isLanguageSupported(detectLanguage(...))` — the same two functions
-// `extraction/index.js` calls). Upstream can add an extension tomorrow and
-// this module picks it up with no edit here; the "five" above is a
-// measurement, not a constant in the code.
-//
-// Additive, never clobbering: a project's `include` is append-only from
-// here. No user entry is removed, reordered or rewritten, and an extension
-// any existing entry already admits is left alone. Append-only is the same
-// posture `codegraph-exclude-repair.ts` takes toward a third-party config
-// file it edits.
-//
-// Scope: PURE (`normalizeCodegraphInclude`) plus ONE read-only adapter
-// (`upstreamIncludeCandidateExtensions`, which reads the installed upstream
-// package). Nothing in this module writes a file.
-//
-// NOTE FOR FUTURE EDITORS: glob literals contain the two-character
-// sequence that ends a block comment, so every comment in this file uses
-// `//` lines — INCLUDING the exported API documentation, which is why this
-// file has no `/** ... */` blocks. Do not convert them.
-import { createRequire } from 'node:module';
-import { dirname, extname, join } from 'node:path';
-import { compileCodegraphGlobs } from './codegraph-exclude-reconciler.js';
-// ─────────────────────────────────────────────────────────────────────
-// Which extensions does this project's `include` already admit?
-// ─────────────────────────────────────────────────────────────────────
-// The pattern upstream's own template uses for a bare extension: all 32
-// entries of `DEFAULT_CONFIG.include` have exactly this shape, and they are
-// matched with `picomatch(..., { dot: true })` — the same engine, and the
-// same options, that `matchesCodegraphGlob` delegates to. So an appended
-// pattern is indistinguishable in form from an upstream-authored one.
-function includePatternForExtension(extension) {
-    return `**/*${extension}`;
-}
-// A synthetic path used ONLY to ask "does any existing rule admit a file
-// with this extension". A root-level probe answers that question exactly
-// for every pattern shape upstream itself writes, because `picomatch`'s
-// trailing-slash-star-star prefix matches zero path segments (measured:
-// the `.mjs` pattern matches both `probe.mjs` and `a/b/probe.mjs`).
-//
-// KNOWN PROXY LIMIT, stated rather than hidden: a path-narrowed rule such as
-// a `src`-prefixed brace list of js/mjs does NOT match the root-level probe,
-// so an extension admitted only under a subdirectory is treated as
-// uncovered and the bare extension pattern is appended. That errs ADDITIVE —
-// the index admits more tracked files, never fewer — and it is pinned by a
-// test rather than left to be discovered. A false "already covered" cannot
-// occur for any pattern upstream's template can produce, and if it did its
-// only effect would be to leave the gap the inspector already reports.
-function extensionProbePath(extension) {
-    return `codegraph-include-probe${extension}`;
-}
-// Compiled ONCE per rule, never per (candidate x rule) pair — see
-// `compileCodegraphGlobs`. The `matchers` list is the include list the
-// candidate is tested against: the caller's entries first, then the
-// patterns this same pass has already decided to append, so a duplicate
-// candidate cannot append twice without re-parsing the list each time
-// (perf audit S10: the re-parse was 0.25 / 2.15 / 23.4 / 234.4 ms at
-// 32 / 320 / 3,200 / 32,000 rules, plus a spread array per candidate).
-function isExtensionAdmitted(extension, matchers) {
-    const probe = extensionProbePath(extension);
-    return matchers.some((matcher) => matcher.matchesAny(probe));
-}
-// Pure: given the current `include` list and the extensions upstream
-// supports but its own template omits, return the list with the uncovered
-// ones appended. No fs, no clock, no serialization.
-//
-// The result is always a SUPERSET of the input, in the input's order, so a
-// caller can never remove or reorder a user entry. Appending an extension
-// the list already admits is a no-op, which is what makes the whole
-// normalization idempotent: feeding the repaired list back in yields
-// `changed: false`.
-//
-// Candidates are de-duplicated by their EFFECT, not by string equality:
-// each candidate is tested against the input list PLUS the patterns this
-// call has already appended, so a duplicate candidate cannot append twice.
-export function normalizeCodegraphInclude(input) {
-    const addedPatterns = [];
-    // The include list as this pass sees it, compiled once. Appending a
-    // pattern extends the list by ONE compiled rule instead of re-parsing
-    // every entry on the next candidate (see `isExtensionAdmitted`).
-    const matchers = [compileCodegraphGlobs(input.include)];
-    for (const candidate of input.candidateExtensions) {
-        const extension = candidate.startsWith('.') ? candidate : `.${candidate}`;
-        if (isExtensionAdmitted(extension, matchers)) {
-            continue;
-        }
-        const pattern = includePatternForExtension(extension);
-        addedPatterns.push(pattern);
-        matchers.push(compileCodegraphGlobs([pattern]));
-    }
-    if (addedPatterns.length === 0) {
-        return { changed: false, include: input.include, addedPatterns: [] };
-    }
-    return {
-        changed: true,
-        include: [...input.include, ...addedPatterns],
-        addedPatterns
-    };
-}
-let cachedCandidateExtensions = null;
-// The extensions upstream's extractor supports but its own default
-// `include` template never names, as dotted extensions — measured against
-// the installed `@colbymchenry/codegraph` 0.7.10 as `.mjs`, `.cjs`,
-// `.pyw`, `.hxx`, `.rake`, in that order.
-//
-// Derived entirely from upstream's own data:
-//
-//   1. `EXTENSION_MAP` keys are the extension universe the extractor knows.
-//   2. The extensions upstream's template already names are read off
-//      `DEFAULT_CONFIG.include` — the entry's own extension, so the
-//      comparison is extension-to-extension and cannot be confused by a
-//      template that switches glob syntax.
-//   3. A candidate is kept only when upstream's own support decision
-//      accepts it, so a table entry with no grammar behind it is never
-//      repaired into the config.
-//
-// Returns the same array on every call (module-level cache); the two
-// modules only define tables and functions, so the load is cheap and
-// Node's `require` cache makes later calls free.
-export function upstreamUnnamedIncludeExtensions() {
-    if (cachedCandidateExtensions === null) {
-        const require = createRequire(import.meta.url);
-        const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
-        const distDir = join(dirname(packageJsonPath), 'dist');
-        const types = require(join(distDir, 'types.js'));
-        const grammars = require(join(distDir, 'extraction', 'grammars.js'));
-        const namedByTemplate = new Set(types.DEFAULT_CONFIG.include.map((entry) => extname(entry).toLowerCase()));
-        cachedCandidateExtensions = Object.keys(grammars.EXTENSION_MAP).filter((extension) => !namedByTemplate.has(extension.toLowerCase()) &&
-            grammars.isLanguageSupported(grammars.detectLanguage(`probe${extension}`)));
-    }
-    return cachedCandidateExtensions;
-}