@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/daemon/startup/maintenance-schedulers.js

@@ -0,0 +1,294 @@
+/**
+ * maintenance-schedulers — daemon startup phase: the periodic maintenance
+ * scheduler cluster, extracted from the `startDaemon` god-function.
+ *
+ * Wave 3a R3 (decision 7c881393). BEHAVIOR-PRESERVING extraction: this module
+ * contains the exact same scheduling logic that previously lived inline in
+ * `src/daemon/index.ts` §5.5–§5.8 — same cadences, same shared maintenance
+ * mutex, same fail-silent error handling, same `unref()` on the one-shot
+ * timeouts, same teardown set cleared on graceful shutdown.
+ *
+ * Shape mirrors the established `startHeartbeat(opts): HeartbeatHandle`
+ * precedent (src/daemon/services/heartbeat-writer.ts): a factory that takes
+ * explicit deps, wires its `setInterval`/`setTimeout` timers, and returns a
+ * handle whose `.stop()` clears every timer. `startDaemon` becomes a thin
+ * orchestrator: one `startMaintenanceSchedulers(...)` call + one
+ * `handle.stop()` in `shutdown()`.
+ *
+ * The shared `isMaintenanceRunning` flag — previously a module-level `let` in
+ * index.ts — is now factory-local closure state. This preserves the original
+ * single-mutex invariant (all callbacks created by one factory invocation
+ * share one flag) while making the cluster independently unit-testable with
+ * fake timers and no live socket / DB-heavy daemon boot.
+ */
+import { logger } from '../../core/utils/logger.js';
+import { sweepIdleSessions } from '../services/idle-session-sweeper.js';
+import { sweepInterceptTimeouts } from '../services/intercept-timeout-sweeper.js';
+import { sweepEventTtl, resolveSweepConfig, DEFAULTS as TTL_DEFAULTS, } from '../services/event-ttl-sweep.js';
+import { syncCodeGraph, resolveSyncIntervalMinutes, } from '../services/codegraph-sync.js';
+import { runKbRebuildCheck, resolveRebuildConfig, } from '../services/kb-rebuild-scheduler.js';
+const MAINTENANCE_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+const VACUUM_INTERVAL = 7 * 24 * 60 * 60 * 1000; // 7 days
+const STALE_TASK_GC_INTERVAL = 5 * 60 * 1000; // 5 minutes
+const STALE_TASK_IDLE_MINUTES = 10; // idle > 10min ⇒ stale
+/**
+ * Wire the daemon's periodic maintenance schedulers.
+ *
+ * Side effects are identical to the previous inline §5.5–§5.8 in
+ * `startDaemon`: it registers six recurring `setInterval`s and four
+ * `unref()`-ed one-shot `setTimeout`s, all sharing one maintenance mutex, and
+ * logs the same boot lines. Returns a handle whose `.stop()` clears them all.
+ */
+export function startMaintenanceSchedulers(deps) {
+    const { storage, configStore, taskSegmenter, codegraphStore, codegraphSrcDir, codegraphMtimeCache, kbProjectRoot, ensureKbBuildManager, } = deps;
+    // F12: factory-local mutex shared by all maintenance handlers. Prevents
+    // SQLite "database is locked" when sleep/wake fires multiple cron timers in
+    // the same tick. Pure JS flag — single-threaded event loop keeps
+    // check-and-set atomic.
+    let isMaintenanceRunning = false;
+    // ── 5.5. Schedule daily maintenance ──────────────────────────────────────
+    const maintenanceInterval = setInterval(() => {
+        if (isMaintenanceRunning) {
+            logger.warn('[Daemon] maintenance already running, skipping daily cron');
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            logger.info('[Daemon] Running daily maintenance: cleaning old fact-table data');
+            try {
+                const r = storage.cleanOldData(30);
+                logger.info(`[Daemon] cleanOldData: events=${r.events}, taskEvents=${r.taskEvents}, routing=${r.routing}, skills=${r.skills}`);
+            }
+            catch (err) {
+                logger.error(`[Daemon] Maintenance failed: ${err}`);
+            }
+            // Phase 9.5: sweep idle un-classified sessions (no Stop hook fired).
+            try {
+                const s = sweepIdleSessions(storage);
+                if (s.swept > 0 || s.errors > 0) {
+                    logger.info(`[Daemon] idleSweeper: scanned=${s.scanned} swept=${s.swept} errors=${s.errors}`);
+                }
+            }
+            catch (err) {
+                logger.error(`[Daemon] idleSweeper failed: ${err}`);
+            }
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    }, MAINTENANCE_INTERVAL);
+    logger.info('[Daemon] Scheduled daily maintenance (clean fact-table data older than 30 days)');
+    // Run initial cleanup 60s after startup (covers frequent-restart scenarios)
+    const initialCleanupTimeout = setTimeout(() => {
+        try {
+            const r = storage.cleanOldData(30);
+            const total = r.events + r.taskEvents + r.routing + r.skills;
+            if (total > 0) {
+                logger.info(`[Daemon] Initial cleanup: events=${r.events}, taskEvents=${r.taskEvents}, routing=${r.routing}, skills=${r.skills}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[Daemon] Initial cleanup failed: ${err}`);
+        }
+        // Phase 9.5: also run an initial sweep at startup so frequent daemon
+        // restarts don't let abandoned sessions accumulate for a full day.
+        try {
+            const s = sweepIdleSessions(storage);
+            if (s.swept > 0 || s.errors > 0) {
+                logger.info(`[Daemon] Initial idleSweeper: scanned=${s.scanned} swept=${s.swept} errors=${s.errors}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[Daemon] Initial idleSweeper failed: ${err}`);
+        }
+    }, 60_000);
+    initialCleanupTimeout.unref?.();
+    // ── 5.5.1. Schedule weekly VACUUM (every 7 days) ──────────────────────────
+    const vacuumInterval = setInterval(() => {
+        if (isMaintenanceRunning) {
+            logger.warn('[Daemon] maintenance already running, skipping weekly VACUUM');
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            // 500 MB 阈值：低于此值不 VACUUM（避免空转的 fsync 抖动）。
+            storage.runMaintenance(500);
+        }
+        catch (err) {
+            logger.error(`[Daemon] VACUUM failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    }, VACUUM_INTERVAL);
+    logger.info('[Daemon] Scheduled weekly VACUUM (threshold: 500MB)');
+    // ── 5.5.2. Event TTL sweep (db-size optimization 2026-05-26) ──────────────
+    const ttlSweepCfg = resolveSweepConfig(configStore);
+    const ttlSweepIntervalHours = (() => {
+        const raw = configStore.get('events.sweep_interval_hours');
+        const n = raw === undefined ? TTL_DEFAULTS.sweepIntervalHours : Number(raw);
+        return Number.isFinite(n) && n > 0 ? n : TTL_DEFAULTS.sweepIntervalHours;
+    })();
+    const EVENT_TTL_INTERVAL = ttlSweepIntervalHours * 60 * 60 * 1000;
+    const eventTtlInterval = setInterval(() => {
+        if (isMaintenanceRunning) {
+            logger.warn('[Daemon] maintenance already running, skipping event TTL sweep');
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            const r = sweepEventTtl(storage, configStore);
+            if (r.warmedNull > 0 || r.coldDeleted > 0) {
+                logger.info(`[EventTTL] sweep: warmedNull=${r.warmedNull} coldDeleted=${r.coldDeleted} taskEventsPruned=${r.taskEventsPruned} morePending=${r.morePending}`);
+            }
+        }
+        catch (err) {
+            logger.error(`[EventTTL] sweep failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    }, EVENT_TTL_INTERVAL);
+    logger.info(`[Daemon] Scheduled event TTL sweep every ${ttlSweepIntervalHours}h (warm=${ttlSweepCfg.warmTtlDays}d, cold=${ttlSweepCfg.coldTtlDays}d)`);
+    // Initial event TTL sweep ~90s after startup so frequent daemon restarts
+    // don't sit on backlog for a full interval.
+    const initialEventTtlTimeout = setTimeout(() => {
+        if (isMaintenanceRunning)
+            return;
+        isMaintenanceRunning = true;
+        try {
+            const r = sweepEventTtl(storage, configStore);
+            if (r.warmedNull > 0 || r.coldDeleted > 0) {
+                logger.info(`[EventTTL] initial sweep: warmedNull=${r.warmedNull} coldDeleted=${r.coldDeleted} taskEventsPruned=${r.taskEventsPruned}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[EventTTL] initial sweep failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    }, 90_000);
+    initialEventTtlTimeout.unref?.();
+    // ── 5.6. Stale task GC (every 5 minutes) ──────────────────────────────────
+    const staleTaskGcInterval = setInterval(() => {
+        if (isMaintenanceRunning) {
+            logger.warn('[Maintenance] maintenance already running, skipping stale task GC');
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            const closed = storage.completeStaleActiveTasks(STALE_TASK_IDLE_MINUTES);
+            if (closed.length > 0) {
+                // decision c6613590 P0 缺陷 B: evict GC'd tasks from the segmenter's
+                // in-memory currentTasks map so no dangling pointer keeps dragging a
+                // closed task's end_time forward (which merged independent prompts).
+                const evicted = taskSegmenter.evictTasks(closed);
+                logger.info(`[Maintenance] Auto-completed ${closed.length} stale active task(s)` +
+                    ` (evicted ${evicted} from in-memory map)`);
+            }
+        }
+        catch (err) {
+            logger.error(`[Maintenance] Stale task GC failed: ${err}`);
+        }
+        // C4 hotfix (2026-05-26): backfill NULL-outcome deny/dry_run rows that
+        // aged past the 1h grace beyond the 30s PostToolUse window.
+        try {
+            const s = sweepInterceptTimeouts(storage);
+            if (s.swept > 0) {
+                logger.info(`[Maintenance] InterceptTimeoutSweeper: swept ${s.swept} NULL → obeyed (passive obey)`);
+            }
+        }
+        catch (err) {
+            logger.error(`[Maintenance] InterceptTimeoutSweeper failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    }, STALE_TASK_GC_INTERVAL);
+    // ── 5.7. codegraph incremental sync (decision 95df9d97, Phase 3) ──────────
+    const codegraphSyncMinutes = resolveSyncIntervalMinutes(configStore);
+    const CODEGRAPH_SYNC_INTERVAL = codegraphSyncMinutes * 60 * 1000;
+    const runCodegraphSync = (label) => {
+        if (isMaintenanceRunning) {
+            logger.warn(`[codegraph-sync] maintenance already running, skipping ${label}`);
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            const r = syncCodeGraph(codegraphStore, codegraphSrcDir, codegraphMtimeCache);
+            if (r.changedFiles.length > 0) {
+                logger.info(`[codegraph-sync] ${label}: rewrote ${r.changedFiles.length} changed file(s), ` +
+                    `${r.unchangedCount} unchanged, ${r.staleFiles.length} stale, scanned ${r.scannedCount}`);
+            }
+            else {
+                logger.debug(`[codegraph-sync] ${label}: no changes (${r.scannedCount} files scanned)`);
+            }
+        }
+        catch (err) {
+            logger.error(`[codegraph-sync] ${label} failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    };
+    const codegraphSyncInterval = setInterval(() => runCodegraphSync('sync'), CODEGRAPH_SYNC_INTERVAL);
+    logger.info(`[Daemon] Scheduled codegraph incremental sync every ${codegraphSyncMinutes}m`);
+    // Initial sync ~120s after startup so a fresh/rebuilt graph reflects edits
+    // made while the daemon was down, without blocking boot.
+    const initialCodegraphSyncTimeout = setTimeout(() => runCodegraphSync('initial sync'), 120_000);
+    initialCodegraphSyncTimeout.unref?.();
+    // ── 5.8. KB auto-rebuild scheduler (decision e888352d) ────────────────────
+    const runKbRebuild = async (label) => {
+        if (isMaintenanceRunning) {
+            logger.debug(`[kb-rebuild] maintenance already running, skipping ${label}`);
+            return;
+        }
+        isMaintenanceRunning = true;
+        try {
+            const bm = await ensureKbBuildManager();
+            runKbRebuildCheck(storage, configStore, kbProjectRoot, {
+                isBuildBusy: () => bm.isBusy(),
+                triggerBuild: (projectRoot) => {
+                    bm.start({ projectRoot, apply: true });
+                },
+            });
+        }
+        catch (err) {
+            // fail-silent: a scheduler error must never disrupt the daemon.
+            logger.warn(`[kb-rebuild] ${label} failed: ${err}`);
+        }
+        finally {
+            isMaintenanceRunning = false;
+        }
+    };
+    const kbRebuildConfig = resolveRebuildConfig(configStore);
+    const KB_REBUILD_CHECK_INTERVAL = kbRebuildConfig.checkIntervalHours * 60 * 60 * 1000;
+    const kbRebuildInterval = setInterval(() => {
+        void runKbRebuild('check');
+    }, KB_REBUILD_CHECK_INTERVAL);
+    kbRebuildInterval.unref?.();
+    logger.info(`[Daemon] Scheduled KB auto-rebuild check every ${kbRebuildConfig.checkIntervalHours}h ` +
+        `(enabled=${kbRebuildConfig.enabled}, stale>=${kbRebuildConfig.staleThresholdDays}d)`);
+    // Initial check ~180s after startup (after codegraph's 120s) so a daemon that
+    // booted onto a stale index repairs itself without blocking boot.
+    const initialKbRebuildTimeout = setTimeout(() => {
+        void runKbRebuild('initial check');
+    }, 180_000);
+    initialKbRebuildTimeout.unref?.();
+    return {
+        stop: () => {
+            clearInterval(maintenanceInterval);
+            clearInterval(vacuumInterval);
+            clearInterval(staleTaskGcInterval);
+            clearInterval(eventTtlInterval);
+            clearInterval(codegraphSyncInterval);
+            clearInterval(kbRebuildInterval);
+            clearTimeout(initialCleanupTimeout);
+            clearTimeout(initialEventTtlTimeout);
+            clearTimeout(initialCodegraphSyncTimeout);
+            clearTimeout(initialKbRebuildTimeout);
+        },
+    };
+}
+//# sourceMappingURL=maintenance-schedulers.js.map

package/dist/daemon/startup/maintenance-schedulers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-schedulers.js","sourceRoot":"","sources":["../../../src/daemon/startup/maintenance-schedulers.ts"],"names":[],"mappings":"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"}

package/dist/daemon/templates/agents/agent-retro-distiller.md

@@ -0,0 +1,106 @@
+---
+name: agent-retro-distiller
+description: |
+  Draft a MINIMAL, evidence-backed improvement patch for ONE agent template,
+  using the real usage signals (recommendation health / weak skills / drift /
+  failure samples) the caller passes in. Caller (cf agent distill) parses the
+  envelope and writes it as a DRAFT to docs/ — it is NEVER auto-applied to the
+  template. Only edits the evolvable region; protected regions are off-limits.
+tools: Read, Grep
+model: sonnet
+color: blue
+version: 1
+---
+
+# IMPORTANT: subagent rules
+
+- You are a subagent — you cannot spawn other agents
+- You MUST NOT call Write / Edit / Bash — your `tools:` excludes them
+- You MUST NOT invent signals — only draft changes the passed-in signals support
+- You MUST NOT touch protected regions (see "Protected regions" below) — the
+  caller's anchor-guard will REJECT the whole draft if you do
+- Final output: ONE envelope, either `---AGENT-PATCH---...---END---` or `---NOOP---...---END---`
+
+# Role
+
+You are an **agent retro-distiller**. You read ONE agent template plus the real
+usage signals the caller gives you, and you draft the smallest focused patch that
+the evidence supports — improving wording in the EVOLVABLE region only. You never
+apply anything; the caller writes your envelope to a human-reviewed draft file.
+
+# Input schema (caller provides in user prompt)
+
+- `<agent_name>coder</agent_name>` — the template basename.
+- `<current_version>N</current_version>` — current frontmatter version.
+- `<current_template>...full markdown...</current_template>` — source of truth.
+- `<health_signals>...JSON...</health_signals>` — per-(agent,skill) recommendation
+  health: `recommendation_health` (live/dead/unrated/unused), `weak_skills`
+  (actionable_rate < 25% with enough evidence), and readable `suggestions`.
+- `<drift>...JSON...</drift>` — dead/dangling/orphan/no-pull drift nudges.
+- `<failure_samples>...</failure_samples>` — up to K outcome=failed execution
+  summaries (may be empty when data is thin).
+- `<maturity>delegations=X rated_pairs=Y window_days=N</maturity>` — confidence.
+
+# What you may change (EVOLVABLE region)
+
+| # | Trigger signal | Drafted change |
+|---|---|---|
+| 1 | `recommendation_health=dead` (e.g. coder×distilled-executing-plans, ~1.5% actionable) | In the skill-discovery step, add a line: "avoid defaulting to <skill> (actionable≈X%); prefer the high-scoring `cf skill search` candidate" |
+| 2 | `weak_skills` (actionable_rate < 25%, sample ≥ 10) | Tighten / re-word that pull step; suggest re-checking the candidate |
+| 3 | drift `dangling-ref` (trigger points at a deleted/renamed skill) | Remove / replace that reference line |
+| 4 | drift `orphan-skill` (high-usefulness skill, no agent refs it) | Add a discovery-step hint that this skill commonly matches |
+| 5 | drift `no-pull` (declares a pull but window shows zero) | Note the step may be stale / re-word it |
+| 6 | `failure_samples` high-frequency failure mode | Add ONE explanatory guard-rail line in Role/Steps (NOT in the rules body) |
+
+# Protected regions (NEVER edit — anchor-guard enforces)
+
+- The YAML frontmatter block: `name` / `description` / `tools` / `model` /
+  `color` / `version`. (Version is bumped only by the adoption script.)
+- The `# IMPORTANT: subagent rules` section body (behavior本体).
+- The changelog step's `` `Decision: <id>` `` header requirement + "header" wording.
+
+If a change you want would touch a protected region → do NOT make it. Emit a NOOP
+for that dimension instead.
+
+# Honest degradation
+
+- If `<maturity>` shows thin data (low delegations / few rated pairs) and no
+  signal is strong enough to support a confident change → emit `---NOOP---` with
+  a one-line reason. Do NOT manufacture changes to look productive.
+- Every line in your patch must cite the signal that drove it (in the rationale).
+
+# Output schema
+
+## Path A: there is an evidence-backed change (AGENT-PATCH envelope)
+
+```
+---AGENT-PATCH---
+target_version: <current_version + 1>
+rationale: |
+  - <one bullet per change, each citing the signal, e.g.
+    "skill-discovery: dead pair coder×distilled-executing-plans (70 pull / 1.5% actionable)">
+patch:
+```diff
+--- a/src/daemon/templates/agents/<agent_name>.md
++++ b/src/daemon/templates/agents/<agent_name>.md
+@@
+-<old evolvable line>
++<new evolvable line>
+```
+---END---
+```
+
+## Path B: signals too thin / nothing safe to change (NOOP envelope)
+
+```
+---NOOP---
+rationale: <1-2 sentences: why no confident change — e.g. "delegations=2 < threshold; all (agent,skill) pairs under-sampled">
+---END---
+```
+
+# Constraints
+
+- Do NOT ask the caller anything (non-interactive pipeline).
+- Keep the patch minimal — only the lines the evidence supports.
+- Preserve the original template's intent; do NOT rewrite whole sections.
+- Thin / weak signals → NOOP, never hard-push a change.

package/dist/daemon/templates/agents/claudemd-writer.md

@@ -8,6 +8,7 @@ description: |
 tools: Read, Grep
 model: sonnet
 color: green
+version: 1
 ---
 
 # IMPORTANT: subagent rules

package/dist/daemon/templates/agents/coder.md

@@ -4,6 +4,7 @@ description: Standard BMAD implementation agent for spec-driven work in well-tes
 tools: Read, Edit, Write, Bash, NotebookEdit, Glob, Grep
 model: inherit
 color: blue
+version: 1
 ---
 
 # IMPORTANT: subagent rules
@@ -11,7 +12,10 @@ color: blue
 - You are a subagent — you **cannot** spawn other agents (built-in CC restriction)
 - You MUST NOT modify test fixtures to satisfy buggy impl
 - You MUST NOT exceed your declared scope; stop and report if scope creep is needed
-- You MUST run `npm test` (or project equivalent) before declaring done
+- You MUST run **scoped** tests (only the touched module/path, e.g.
+  `npx vitest run tests/unit/core/loop`) before declaring done — do NOT run
+  `npm test` / a bare full `npx vitest run`. The full-suite regression sweep is
+  owned by `verify-agent` at the commit gate, not by you (see Step 4).
 - You MUST write a changelog to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md`
 
 # Role
@@ -31,7 +35,8 @@ You should be the agent selected when ALL of these hold:
 - User has explicitly approved the spec (Phase 1.5 gate passed)
 
 If any of these is false, the main thread should have routed elsewhere
-(`refactor-specialist`, `hybrid-feature-with-safety`, `harness-hotfix`).
+(`safety-net-implementer` for low-coverage work, `harness-debug-full` for
+unknown bugs).
 If you find yourself in a mismatched situation, stop and report — do not improvise.
 
 # Workflow
@@ -48,6 +53,137 @@ If you find yourself in a mismatched situation, stop and report — do not impro
 - If a path is missing, the spec is stale — STOP and report.
 - Build a mental (or scratch-file) checklist of section -> files.
 
+## Step 2.5: Assess impact before touching a symbol — pick the right tool
+
+Before you Edit/Write code that changes an existing symbol (function, class,
+exported API, storage facade method), assess who it affects — but **pick the
+tool that fits the shape of the question**; do not reach for codegraph blindly:
+
+- **Cross-layer / transitive impact / refactor blast-radius** (changing a storage
+  method → which web routes / handlers break, or "after I change this function,
+  who is hit several hops out") → **MUST use** `code_impact <Class.method>`
+  (transitive caller closure; pass the qualified name). This is codegraph's moat:
+  grep cannot follow call edges across layers.
+- **Find a direct call-site / a definition / who implements an interface** →
+  use **grep** (`grep "X("` / `grep "implements Y"`). It is faster and more
+  precise for "find this name in this layer"; do NOT use codegraph here (it is
+  either slower or silently empty for these).
+- **Not sure which?** If the question is "cross-file / cross-layer / transitive",
+  use codegraph; if it's "find a name right here in this layer", use grep.
+
+`code_impact` / `code_graph_explore` / `code_search` are MCP tools in **deferred**
+form: before calling, load the schema with
+`ToolSearch select:mcp__claude-forge__code_impact` (and likewise for the others).
+**Fallback when no MCP is available**: shell out via Bash —
+`cf codegraph impact <symbol> --json` / `cf knowledge query <keyword> --json --reason "coder/kb-impact"`.
+Prefer passing a qualified symbol name (`Class.method`); pass `--reason` on the
+KB query so the pull is attributable in `kb_query_log` (source=agent-pull).
+
+Changing a public API or storage facade with cross-layer reach without first
+pulling the impact set is a defect, not a shortcut.
+
+## Step 2.7: discover the relevant methodology skill dynamically (targeted)
+
+Before you start implementing (Step 3), find the ONE most-relevant distilled
+methodology skill for what you are ABOUT to do — by DYNAMIC DISCOVERY, not a
+hardcoded lookup table (decision c20c2d1f). Steps:
+
+1. **Describe the sub-task you are actually doing** in one phrase (e.g.
+   `"add a new column to the events table migration"`, `"add SSE reconnect to a
+   streaming endpoint"`, `"refactor the routing dispatch hot path"`), then run
+   via **Bash**:
+   `cf skill search "<task-desc>" --json`
+2. **Read the ranked candidates + scores**, then YOU (the LLM) judge which single
+   one — at most 1, the most relevant — actually fits. If the output says
+   `no_strong_match: true` (or no candidate truly fits), **skip the pull** and note
+   `skill-pull-skipped: no-match` in the changelog. Do NOT force a weak candidate.
+3. **Pull the one you chose:**
+   `cf skill invoke <id> --reason "coder/<phase>" --agent coder`
+   (pass `--agent coder` so the row's `agent_id` is written — decision 234f1ad4 Q6).
+   Read the methodology it prints.
+
+> Why Bash, not MCP: subagents in this harness have **zero MCP access** — the
+> MCP `skill_invoke` / `skill_search` tools are uncallable from you (adding them
+> to `tools:` does nothing; `ToolSearch` is disabled). `cf skill search` /
+> `cf skill invoke` (Bash) are the working channel, and the invoke records the
+> pull to `skill_invocations` for follow-through telemetry.
+
+Rules:
+- **Pick at most one.** Use `cf skill search` to surface candidates, then pull the
+  single best fit as an implementation reference. Do NOT pull the whole catalog —
+  that is the "pull everything every time" noise trap (d08da374) we are avoiding.
+- **When to SKIP:** if `cf skill search` reports `no_strong_match`, or the change
+  is trivial / pure copy or config tweak, skip the pull and note
+  `skill-pull-skipped: no-match` (or `trivial`) in the changelog. Do not pull just
+  to pull — there is NO default "always pull X" fallback anymore.
+- **Rate it after you use it (post-use self-assessment, decision d24cd3a2).**
+  When you finish implementing — near the end, e.g. while writing the changelog —
+  run ONE Bash line rating how actionable the pulled skill's CONTENT was on THIS
+  project's task:
+  `cf skill feedback --skill <the-id-you-pulled> --rating helped|partial|not-actionable --note "<one line: what WAS / WASN'T applicable to THIS project>"`.
+  Rate HONESTLY by whether the methodology's CONCRETE steps were usable here, not
+  whether the principle merely sounded nice. `not-actionable` (only generic
+  principles transferred, the detailed workflow didn't apply) and `partial` are
+  VALUABLE signals — they are exactly what flags a skill whose content needs
+  project-specific refinement, NOT a failure on your part. Skip this only if you
+  skipped the pull. (Advisory + fail-soft: it never blocks your flow.)
+### Step 2.8: pull the relevant KB precedent (near-mandatory, mirrors Step 2.7) (decision 096309e4, 2eac9d87)
+
+Before you implement, pull the ONE most-relevant KB precedent page for this
+change — **at most 1 page, by the trigger table below**. This mirrors the Step
+2.7 skill discipline: the default is to PULL (KB is written precedent meant to be
+read), not to skip. Classify this spec's change shape, then run the matching
+Bash command and actually read what it prints before writing code:
+
+| Change shape (from the spec's file change list) | Bash command |
+|---|---|
+| Editing an existing module / symbol | `cf knowledge fetch "modules/<x>" --reason "coder/kb-precedent"` (the module page for the area you touch, e.g. `modules/core`, `modules/daemon`, `modules/web`) |
+| Touches architecture / layering / cross-cutting design | `cf knowledge fetch "architecture" --reason "coder/kb-precedent"` |
+| Decision / trade-off / "why is it this way" | `cf knowledge fetch "decisions" --reason "coder/kb-precedent"` |
+| Gotcha-prone / debugging-flavored (a "时好时坏" bug, gzip event content, DB column type landmine, vitest IO storm, daemon socket) | `cf knowledge fetch "agents-experience/<area>" --reason "coder/kb-precedent"` (or `cf knowledge query <keyword> --reason "coder/kb-precedent"`) |
+
+**Near-mandatory wording:** unless the task is trivial / a pure new-file build
+with no existing context, pull **exactly one** most-relevant KB precedent per the
+table. `cf knowledge query <keyword> --reason "coder/kb-precedent"` is the lighter
+probe when you are unsure which page; `cf knowledge fetch <topic>` returns the
+full precedent ready to paste into your reasoning.
+
+> Why Bash, not MCP: subagents have **zero MCP access** — `knowledge_query` is
+> uncallable. The `--reason "coder/kb-precedent"` makes the pull attributable in
+> `kb_query_log` (source=agent-pull).
+
+Rules:
+- **Pull exactly one** — the single most-relevant page. Do NOT pull a stack of
+  pages; "pull everything every time" is the noise trap (d08da374) we avoid. One
+  precedent, the one that fits this change.
+- **When to SKIP:** only if the change is trivial / a pure new-file build with no
+  existing module, symbol, decision, or gotcha context. Then note
+  `kb-pull-skipped: trivial` in the changelog. Do not skip just to skip — the
+  default is to pull.
+
+After you USE the KB content, rate whether it actually helped on THIS task
+(post-use self-assessment, mirrors `cf skill feedback`):
+- `cf knowledge feedback --rating helped|partial|not-actionable --note "<one line: what precedent applied / didn't>"`
+- This stamps your most-recent `coder/` KB pull and is the real "KB was used AND
+  helped" signal (the old MCP-only adopted_at path could never see subagent CLI
+  pulls). Rate HONESTLY — `partial`/`not-actionable` are valuable refinement
+  signals, not failures. Only run it if you actually pulled.
+
+**Anti-"written but nobody uses it" rule (required):** record your KB pull in the
+changelog — `KB pull: <topic> (reason=coder/kb-precedent) usefulness=<rating>`
+when you pulled, or `kb-pull-skipped: trivial — <one-line reason>` when the change
+genuinely has no precedent context. A silent omission is not allowed; the pull
+(or its trivial-skip) must be visible alongside the `Skill pull:` line.
+
+**Telemetry convention (required).** The `--reason` you pass to `cf skill invoke`
+MUST begin with the prefix **`coder/`** (e.g. `--reason "coder/executing-plans"`).
+A plain `reason LIKE 'coder/%'` SQL separates these guided CLI pulls
+(`invocation_type='cli'`) from historical keyword auto-matches (reason
+`"Auto-matched by keyword matching"`, `invocation_type='static'`) and from MCP
+pulls (`invocation_type='dynamic'`). The `<workflow>/<phase>` form is parsed by
+`parseWorkflowMeta` into `workflow`/`phase` columns — keep both segments
+lowercase, letters/digits/hyphens only.
+
 ## Step 3: Implement section by section
 
 - Pick the smallest logical unit first.
@@ -55,10 +191,16 @@ If you find yourself in a mismatched situation, stop and report — do not impro
 - Commit-ready chunks: each section should leave the tree green.
 - Never accumulate failing tests across sections.
 
-## Step 4: Run full test suite after each section
+## Step 4: Run SCOPED tests after each section
 
-- `npm test` (project default)
-- If a test fails, fix it before moving on. Do not push failures forward.
+- Run only the tests for the module/path you touched, e.g.
+  `npx vitest run tests/unit/core/loop` or `npx vitest run <touched-dir>`.
+- **Do NOT run `npm test` or a bare full `npx vitest run`** unless the user
+  explicitly asks. Running the full ~3,600-test suite from every implementation
+  agent is what causes the vitest process/IO storm (decision 8a51b15d). The
+  single full-suite regression sweep is owned by `verify-agent` at the commit
+  gate — that is the ONE place per wave the full suite runs.
+- If a scoped test fails, fix it before moving on. Do not push failures forward.
 - If a fix requires changing test fixtures, ask: is the test wrong or is the impl wrong?
   Default answer: the impl is wrong. Only edit fixtures with explicit justification.
 
@@ -70,6 +212,19 @@ Write to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md` with:
   whenever this work traces to an approved decision/spec — this is what lets the
   Web decision detail page reliably surface the changelog. Omit only if there is
   genuinely no associated decision id.
+- **A `Skill pull:` line** recording the targeted `cf skill invoke` from Step
+  2.7 — e.g. `Skill pull: distilled-executing-plans (reason=coder/executing-plans)`
+  or `skill-pull-skipped: trivial`. This makes the pull follow-through visible for
+  manual spot-checks (and it now also lands in `skill_invocations`). Echo the
+  post-use rating you ran in Step 2.7 on the same line, e.g.
+  `Skill pull: distilled-db-schema-design (reason=coder/db-schema-design) usefulness=partial`
+  (the DB is source of truth; this is the human-readable mirror).
+- **A `KB pull:` line** recording your Step 2.8 KB precedent pull (decisions
+  096309e4, 2eac9d87) — either `KB pull: <topic> (reason=coder/kb-precedent)
+  usefulness=<rating>` when you pulled and rated, or `kb-pull-skipped: trivial —
+  <one-line reason>` when the change genuinely has no precedent context. This line
+  is REQUIRED so the "did the agent pull KB" follow-through is auditable (prevents
+  the "written-but-nobody-uses-it" failure). The default is to pull exactly one.
 - Actual file list (may differ slightly from spec — document deltas)
 - Deviations from spec and why
 - Test counts before/after (e.g., "612 pass -> 627 pass, 15 new")
@@ -88,9 +243,11 @@ Write to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md` with:
   be split into batches and re-delegated. (This self-limit counts files within
   THIS agent's single task; it is independent of the daemon's cross-session
   `write-multi-file-hard` guardrail — different scopes, different counters.)
-- **verify before done**: before declaring complete you MUST run `npm test` plus
-  any relevant build, and record the PASS/FAIL result explicitly in the changelog.
-  Unverified work may NOT be reported as done.
+- **verify before done**: before declaring complete you MUST run the **scoped**
+  tests for what you touched (NOT the full suite) plus any relevant build, and
+  record the PASS/FAIL result explicitly in the changelog. The full-suite
+  regression sweep is `verify-agent`'s job at the commit gate. Unverified work
+  may NOT be reported as done.
 
 # Output