peaks-loop 4.0.31 → 4.0.33

package/dist/services/code-review/ecc-bridge.d.ts

@@ -31,7 +31,7 @@
  * === Source: peaks-rd/references/parallel-review-fanout.md ===
  *
  * Sub-agent 1 contract (Tier 7 v2.11.0): the parent RD loop calls
- * `Agent({ subagent_type: 'everything-claude-code:code-review', ... })`
+ * `Agent({ subagent_type: 'ecc:code-reviewer', ... })`
  * with the diff + handoff in scope, receives the structured envelope,
  * then runs `adaptEccEnvelopeToRdCodeReview(env, { rid, generatedAt })`
  * and writes the resulting body to
@@ -51,18 +51,43 @@ export interface EccEnvelope {
     readonly gateAction: EccGateAction;
 }
 /**
- * 5-state ECC detection result:
+ * The real upstream ECC agent name for the code-review role:
+ * `~/.peaks/agents/ecc/code-reviewer.md`. Upstream ships `<lang>-reviewer`
+ * agents and has NO `code-review.md`, so this is the default the
+ * `ready-via-cache` nextActions name when the caller does not pass the
+ * output of `resolveMaterializedAgentName(['code-reviewer', 'code-review'])`.
+ */
+export declare const DEFAULT_CACHE_ECC_AGENT_NAME = "code-reviewer";
+/**
+ * The native (plugin) ECC agent id dispatched through the Agent tool.
+ * Verified upstream: the plugin is named `ecc` (`.claude-plugin/plugin.json`,
+ * `marketplace.json`) and the agent's frontmatter `name` is `code-reviewer`
+ * (`~/.peaks/agents/ecc/code-reviewer.md`), so the composed id is
+ * `ecc:code-reviewer`. The previous id composed the OLD repo name
+ * (`everything-claude-code`) with a non-existent `code-review` agent, so it
+ * matched no registry entry and the native path silently fell through to
+ * inline review.
+ */
+export declare const DEFAULT_NATIVE_ECC_AGENT_ID = "ecc:code-reviewer";
+/**
+ * 6-state ECC detection result:
  *   - `ready`               — ECC plugin is installed and reachable
- *   - `plugin-missing`      — `everything-claude-code` not in skill list
- *   - `agent-missing`       — plugin present but `code-review` agent absent
+ *   - `ready-via-cache`     — plugin/agent absent, but the materialized ECC
+ *                             review agent (real name `code-reviewer`, NOT
+ *                             `code-review`) exists under `~/.peaks/agents/ecc/`;
+ *                             dispatch a GENERIC sub-agent with that body
+ *   - `plugin-missing`      — `everything-claude-code` not in skill list and no materialized cache
+ *   - `agent-missing`       — plugin present but `code-review` agent absent and no materialized cache
  *   - `dispatch-failed`     — Agent tool call threw before returning envelope
  *   - `envelope-malformed`  — returned value failed `isEccEnvelope` validation
  *
- * The caller (peaks-rd's sub-agent 1 contract) inspects `state` and
- * either proceeds with the envelope or records a degradation note in
- * the request artifact body (`code-review-ecc-degraded-to-inline`).
+ * Fallback order (RD fan-out, 2026-09-09-ecc-dynamic): native plugin →
+ * cache-backed generic agent → inline. The caller (peaks-rd's sub-agent 1
+ * contract) inspects `state` and either proceeds with the envelope or records
+ * a degradation note in the request artifact body
+ * (`code-review-ecc-degraded-to-inline`).
  */
-export type EccDetectState = 'ready' | 'plugin-missing' | 'agent-missing' | 'dispatch-failed' | 'envelope-malformed';
+export type EccDetectState = 'ready' | 'ready-via-cache' | 'plugin-missing' | 'agent-missing' | 'dispatch-failed' | 'envelope-malformed';
 export interface EccDetectResult {
     readonly state: EccDetectState;
     readonly pluginInstalled: boolean;
@@ -105,39 +130,93 @@ export declare function adaptEccEnvelopeToRdCodeReview(env: EccEnvelope, opts: {
     generatedAt: string;
 }): RdCodeReviewDoc;
 /**
- * 5-state detector — mirrors `detectOcr`'s shape (state enum + warnings
+ * 6-state detector — mirrors `detectOcr`'s shape (state enum + warnings
  * + nextActions). The caller passes in the result of its own probe:
  *
  * - `pluginInstalled`: did the skill list scan find `everything-claude-code`?
  * - `agentAvailable`: did the Agent tool say `code-review` is registered?
+ * - `cacheAgentAvailable`: does the resolved materialized agent exist
+ *   (`~/.peaks/agents/ecc/<cacheAgentName>.md`, default `code-reviewer`)?
  * - `dispatchError`: optional — the Agent tool threw before returning.
  * - `envelope`: optional — what came back (if anything).
  *
- * The detector never blocks: when state !== `ready`, the parent RD
- * loop records a `code-review-ecc-degraded-to-inline` note and falls
- * back to inline review. This matches `detectOcr`'s soft-fail policy.
+ * The detector never blocks: when the state is not dispatchable
+ * (`ready` / `ready-via-cache`), the parent RD loop records a
+ * `code-review-ecc-degraded-to-inline` note and falls back to inline
+ * review. This matches `detectOcr`'s soft-fail policy.
+ *
+ * Backward compat: the native id is `DEFAULT_NATIVE_ECC_AGENT_ID`
+ * (`ecc:code-reviewer` — plugin `ecc`, agent `code-reviewer`). A registry
+ * that still exposes the OLD `everything-claude-code` plugin id will not
+ * match it, so the operator should pin the id explicitly. peaks-loop
+ * cannot enumerate the user's plugin registry: detection stays
+ * caller-supplied (`pluginInstalled` / `agentAvailable`), never probed here.
  */
 export declare function detectEcc(input: {
     readonly pluginInstalled: boolean;
     readonly agentAvailable: boolean;
+    /**
+     * Did the caller find the materialized review agent (written by
+     * `peaks ecc install` / `materializeEccAgents`) under `~/.peaks/agents/ecc/`?
+     * When true and the native plugin path is unavailable, `state` becomes
+     * `ready-via-cache` so the RD loop can dispatch a generic sub-agent with
+     * the materialized body.
+     */
+    readonly cacheAgentAvailable?: boolean;
+    /**
+     * Resolved materialized agent name — pass
+     * `resolveMaterializedAgentName(['code-reviewer', 'code-review'])` from
+     * `peaks-loop-mut`. Defaults to `code-reviewer` (the real upstream name);
+     * upstream has no `code-review.md`.
+     */
+    readonly cacheAgentName?: string;
     readonly dispatchError?: unknown;
     readonly envelope?: unknown;
 }): EccDetectResult;
 /**
  * Convenience: run `detectEcc` and `adaptEccEnvelopeToRdCodeReview`
  * in one call. The parent RD loop calls this after the Agent tool
- * returns. When `detectEcc` returns state !== 'ready', the caller
- * should NOT call `adaptEccEnvelopeToRdCodeReview` — fall back to
- * inline review instead.
+ * returns. When `detectEcc` returns a non-dispatchable state
+ * (`plugin-missing` / `agent-missing` / `dispatch-failed` /
+ * `envelope-malformed`), the caller should NOT call
+ * `adaptEccEnvelopeToRdCodeReview` — fall back to inline review instead.
+ *
+ * Both `ready` (native plugin) and `ready-via-cache` (materialized generic
+ * agent) adapt the envelope through the SAME bridge.
  */
 export declare function runEccCodeReview(input: {
     readonly rid: string;
     readonly generatedAt: string;
     readonly pluginInstalled: boolean;
     readonly agentAvailable: boolean;
+    readonly cacheAgentAvailable?: boolean;
+    /** Resolved materialized agent name (see `detectEcc`); defaults to `code-reviewer`. */
+    readonly cacheAgentName?: string;
     readonly dispatchError?: unknown;
     readonly envelope?: unknown;
 }): {
     detect: EccDetectResult;
     doc: RdCodeReviewDoc | null;
 };
+/**
+ * The exact JSON shape the generic (cache-backed) sub-agent MUST return.
+ * Kept as a const so the RD reference docs and the prompt builder cannot
+ * drift: `isEccEnvelope` is the authoritative validator.
+ */
+export declare const ECC_OUTPUT_CONTRACT: string;
+/**
+ * Compose the plugin-free dispatch prompt for sub-agent 1.
+ *
+ * `instructions` is the body of the materialized review agent
+ * (`~/.peaks/agents/ecc/code-reviewer.md` — resolve the real name with
+ * `resolveMaterializedAgentName`, never hardcode `code-review.md`);
+ * `diff` is the slice diff. The
+ * composed prompt is handed to a GENERIC sub-agent (no ECC plugin needed)
+ * and its reply is validated with `isEccEnvelope`, then rendered by
+ * `adaptEccEnvelopeToRdCodeReview` — the same bridge the native path uses.
+ */
+export declare function buildCacheBackedEccPrompt(input: {
+    readonly rid: string;
+    readonly instructions: string;
+    readonly diff: string;
+}): string;

package/dist/services/code-review/ecc-bridge.js

@@ -1,3 +1,27 @@
+/**
+ * The real upstream ECC agent name for the code-review role:
+ * `~/.peaks/agents/ecc/code-reviewer.md`. Upstream ships `<lang>-reviewer`
+ * agents and has NO `code-review.md`, so this is the default the
+ * `ready-via-cache` nextActions name when the caller does not pass the
+ * output of `resolveMaterializedAgentName(['code-reviewer', 'code-review'])`.
+ */
+export const DEFAULT_CACHE_ECC_AGENT_NAME = 'code-reviewer';
+/**
+ * The native (plugin) ECC agent id dispatched through the Agent tool.
+ * Verified upstream: the plugin is named `ecc` (`.claude-plugin/plugin.json`,
+ * `marketplace.json`) and the agent's frontmatter `name` is `code-reviewer`
+ * (`~/.peaks/agents/ecc/code-reviewer.md`), so the composed id is
+ * `ecc:code-reviewer`. The previous id composed the OLD repo name
+ * (`everything-claude-code`) with a non-existent `code-review` agent, so it
+ * matched no registry entry and the native path silently fell through to
+ * inline review.
+ */
+export const DEFAULT_NATIVE_ECC_AGENT_ID = 'ecc:code-reviewer';
+/** Materialized path hint for the cache-backed agent, e.g. `~/.peaks/agents/ecc/code-reviewer.md`. */
+function materializedAgentPath(name) {
+    const resolved = name !== undefined && name.length > 0 ? name : DEFAULT_CACHE_ECC_AGENT_NAME;
+    return `~/.peaks/agents/ecc/${resolved}.md`;
+}
 /**
  * Validate a raw value as an EccEnvelope. Accepts the strict shape
  * only — extra fields are tolerated (forward-compat for ECC adding
@@ -82,7 +106,7 @@ export function adaptEccEnvelopeToRdCodeReview(env, opts) {
         `## Summary`,
         '',
         `- generatedAt: ${opts.generatedAt}`,
-        `- source: everything-claude-code:code-review (Tier 7 bridge)`,
+        `- source: ${DEFAULT_NATIVE_ECC_AGENT_ID} (Tier 7 bridge)`,
         `- gateAction: ${env.gateAction}`,
         `- passed: ${env.passed}`,
         `- violations: ${env.violations.length}`,
@@ -146,43 +170,87 @@ function renderFindings(violations) {
     return ['## Findings', '', ...bullets, ''].join('\n');
 }
 /**
- * 5-state detector — mirrors `detectOcr`'s shape (state enum + warnings
+ * 6-state detector — mirrors `detectOcr`'s shape (state enum + warnings
  * + nextActions). The caller passes in the result of its own probe:
  *
  * - `pluginInstalled`: did the skill list scan find `everything-claude-code`?
  * - `agentAvailable`: did the Agent tool say `code-review` is registered?
+ * - `cacheAgentAvailable`: does the resolved materialized agent exist
+ *   (`~/.peaks/agents/ecc/<cacheAgentName>.md`, default `code-reviewer`)?
  * - `dispatchError`: optional — the Agent tool threw before returning.
  * - `envelope`: optional — what came back (if anything).
  *
- * The detector never blocks: when state !== `ready`, the parent RD
- * loop records a `code-review-ecc-degraded-to-inline` note and falls
- * back to inline review. This matches `detectOcr`'s soft-fail policy.
+ * The detector never blocks: when the state is not dispatchable
+ * (`ready` / `ready-via-cache`), the parent RD loop records a
+ * `code-review-ecc-degraded-to-inline` note and falls back to inline
+ * review. This matches `detectOcr`'s soft-fail policy.
+ *
+ * Backward compat: the native id is `DEFAULT_NATIVE_ECC_AGENT_ID`
+ * (`ecc:code-reviewer` — plugin `ecc`, agent `code-reviewer`). A registry
+ * that still exposes the OLD `everything-claude-code` plugin id will not
+ * match it, so the operator should pin the id explicitly. peaks-loop
+ * cannot enumerate the user's plugin registry: detection stays
+ * caller-supplied (`pluginInstalled` / `agentAvailable`), never probed here.
  */
 export function detectEcc(input) {
     const warnings = [];
     const nextActions = [];
+    const cacheAgentAvailable = input.cacheAgentAvailable === true;
+    const cacheAgentPath = materializedAgentPath(input.cacheAgentName);
     if (!input.pluginInstalled) {
+        if (cacheAgentAvailable) {
+            return {
+                state: 'ready-via-cache',
+                pluginInstalled: false,
+                agentAvailable: false,
+                warnings: [
+                    'ECC Claude Code plugin is not installed; using the cache-backed generic agent instead.'
+                ],
+                nextActions: [
+                    `Dispatch a generic sub-agent with the body of \`${cacheAgentPath}\` (see \`buildCacheBackedEccPrompt\`).`,
+                    'Refresh the materialized copy with `peaks ecc install`.',
+                    'Install the `ecc` plugin for the native path (optional; native plugin → cache-backed → inline).'
+                ]
+            };
+        }
         return {
             state: 'plugin-missing',
             pluginInstalled: false,
             agentAvailable: false,
             warnings,
             nextActions: [
-                'Install the `everything-claude-code` plugin (Claude Code marketplace).',
-                'Until installed, peaks-rd falls back to inline code review (degradation note: code-review-ecc-degraded-to-inline).'
+                'Install the `ecc` plugin (Claude Code marketplace).',
+                'Or run `peaks ecc install` to populate the cache-backed generic agent path.',
+                'Until one of the two is available, peaks-rd falls back to inline code review (degradation note: code-review-ecc-degraded-to-inline).'
             ]
         };
     }
     if (!input.agentAvailable) {
+        if (cacheAgentAvailable) {
+            return {
+                state: 'ready-via-cache',
+                pluginInstalled: true,
+                agentAvailable: false,
+                warnings: [
+                    '`ecc` is installed but its `code-reviewer` agent is not registered; using the cache-backed generic agent instead.'
+                ],
+                nextActions: [
+                    `Dispatch a generic sub-agent with the body of \`${cacheAgentPath}\` (see \`buildCacheBackedEccPrompt\`).`,
+                    'Verify the plugin is enabled in your Claude Code settings (MCP servers / agent registry) to restore the native path.'
+                ]
+            };
+        }
         return {
             state: 'agent-missing',
             pluginInstalled: true,
             agentAvailable: false,
             warnings: [
-                '`everything-claude-code` is installed but its `code-review` agent is not registered.'
+                '`ecc` is installed but its `code-reviewer` agent is not registered.'
             ],
             nextActions: [
                 'Verify the plugin is enabled in your Claude Code settings (MCP servers / agent registry).',
+                `If your registry still exposes the old \`everything-claude-code\` plugin id, pin the native agent id explicitly (\`${DEFAULT_NATIVE_ECC_AGENT_ID}\`) instead of relying on detection.`,
+                'Or run `peaks ecc install` to populate the cache-backed generic agent path.',
                 'Until resolved, peaks-rd falls back to inline code review.'
             ]
         };
@@ -226,17 +294,69 @@ export function detectEcc(input) {
 /**
  * Convenience: run `detectEcc` and `adaptEccEnvelopeToRdCodeReview`
  * in one call. The parent RD loop calls this after the Agent tool
- * returns. When `detectEcc` returns state !== 'ready', the caller
- * should NOT call `adaptEccEnvelopeToRdCodeReview` — fall back to
- * inline review instead.
+ * returns. When `detectEcc` returns a non-dispatchable state
+ * (`plugin-missing` / `agent-missing` / `dispatch-failed` /
+ * `envelope-malformed`), the caller should NOT call
+ * `adaptEccEnvelopeToRdCodeReview` — fall back to inline review instead.
+ *
+ * Both `ready` (native plugin) and `ready-via-cache` (materialized generic
+ * agent) adapt the envelope through the SAME bridge.
  */
 export function runEccCodeReview(input) {
     const detect = detectEcc(input);
-    if (detect.state !== 'ready' || input.envelope === undefined) {
+    const dispatchable = detect.state === 'ready' || detect.state === 'ready-via-cache';
+    if (!dispatchable || input.envelope === undefined) {
         return { detect, doc: null };
     }
-    // Detect.state === 'ready' implies input.envelope passed isEccEnvelope; the runtime
+    // A dispatchable state implies input.envelope passed isEccEnvelope; the runtime
     // type is therefore EccEnvelope, not `unknown`. Cast is justified by detect's contract.
     const env = input.envelope;
     return { detect, doc: adaptEccEnvelopeToRdCodeReview(env, { rid: input.rid, generatedAt: input.generatedAt }) };
 }
+/**
+ * The exact JSON shape the generic (cache-backed) sub-agent MUST return.
+ * Kept as a const so the RD reference docs and the prompt builder cannot
+ * drift: `isEccEnvelope` is the authoritative validator.
+ */
+export const ECC_OUTPUT_CONTRACT = [
+    'Return ONLY a single JSON object (no prose, no markdown fence) with this exact shape:',
+    '{',
+    '  "passed": boolean,',
+    '  "violations": [{ "kind": string, "line": number, "snippet": string, "hint": string }],',
+    '  "gateAction": "pass" | "warn" | "block"',
+    '}',
+    '`kind` is one of: correctness, type-safety, error-handling, mutation, file-size, naming, dead-code, regression, contract-drift, other.',
+    '`gateAction: "block"` requires at least one violation; `pass` requires an empty violations array.'
+].join('\n');
+/**
+ * Compose the plugin-free dispatch prompt for sub-agent 1.
+ *
+ * `instructions` is the body of the materialized review agent
+ * (`~/.peaks/agents/ecc/code-reviewer.md` — resolve the real name with
+ * `resolveMaterializedAgentName`, never hardcode `code-review.md`);
+ * `diff` is the slice diff. The
+ * composed prompt is handed to a GENERIC sub-agent (no ECC plugin needed)
+ * and its reply is validated with `isEccEnvelope`, then rendered by
+ * `adaptEccEnvelopeToRdCodeReview` — the same bridge the native path uses.
+ */
+export function buildCacheBackedEccPrompt(input) {
+    return [
+        '# Code review (ECC cache-backed generic agent)',
+        '',
+        `Request: ${input.rid}`,
+        '',
+        `## Agent instructions (materialized from ${DEFAULT_NATIVE_ECC_AGENT_ID})`,
+        '',
+        input.instructions.trim(),
+        '',
+        '## Diff under review',
+        '',
+        '```diff',
+        input.diff.trim(),
+        '```',
+        '',
+        '## Required output',
+        '',
+        ECC_OUTPUT_CONTRACT
+    ].join('\n');
+}

package/dist/services/dashboard/project-dashboard-service.d.ts

@@ -12,12 +12,6 @@ export type ProjectDashboardOpenSpec = {
     count: number;
     changes: OpenSpecChangeSummary[];
 };
-export type ProjectDashboardUnderstand = {
-    exists: boolean;
-    graphExists: boolean;
-    graphPath: string;
-    parseError?: string;
-};
 export type ProjectDashboardDoctor = {
     ok: boolean;
     passed: number;
@@ -69,7 +63,6 @@ export type ProjectDashboard = {
     okPolicy: DashboardOkPolicy;
     requests: ProjectDashboardRequests;
     openspec: ProjectDashboardOpenSpec;
-    understand: ProjectDashboardUnderstand;
     doctor: ProjectDashboardDoctor;
     runbookHealth: ProjectDashboardRunbookHealth;
     capabilities: ProjectDashboardCapabilities;

package/dist/services/dashboard/project-dashboard-service.js

@@ -1,6 +1,5 @@
 import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
 import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
-import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
 import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
 import { requiredSkillNames } from 'peaks-loop-shared/paths';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
@@ -107,10 +106,9 @@ export async function loadProjectDashboard(options) {
     const clock = options.clock ?? defaultClock;
     const sampleSize = options.sampleCapabilities ?? 8;
     const okPolicy = options.okPolicy ?? 'workspace-only';
-    const [items, openspecReport, understandReport, doctorAndRunbook] = await Promise.all([
+    const [items, openspecReport, doctorAndRunbook] = await Promise.all([
         listRequestArtifacts({ projectRoot: options.projectRoot }),
         scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
-        scanUnderstandAnything({ projectRoot: options.projectRoot }),
         loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
     ]);
     const okVerdict = resolveDashboardOk({
@@ -133,12 +131,6 @@ export async function loadProjectDashboard(options) {
             count: openspecReport.changes.length,
             changes: openspecReport.changes
         },
-        understand: {
-            exists: understandReport.exists,
-            graphExists: understandReport.graph.exists,
-            graphPath: understandReport.graph.path,
-            ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
-        },
         doctor: doctorAndRunbook.doctor,
         runbookHealth: doctorAndRunbook.runbookHealth,
         capabilities: buildCapabilitiesSummary(sampleSize),

package/dist/services/preferences/preferences-types.d.ts

@@ -76,7 +76,16 @@ export interface ProjectPreferences {
      * dispatch *shape* (worker graph vs flat dispatch).
      */
     readonly swarmMode: boolean;
+    /**
+     * Legacy UA opt-in prompt decision. The UA knowledge-graph surface was
+     * removed in 2026-09-09 (project analysis is codegraph-first); the field
+     * is retained only so legacy `.peaks/preferences.json` files keep parsing.
+     */
     readonly uaPrompt: UaPromptDecision;
+    /**
+     * Legacy AgentShield opt-in prompt decision. The ECC AgentShield
+     * subprocess was removed in 4.0.0-beta.11; retained for legacy parse.
+     */
     readonly agentShieldPrompt: UaPromptDecision;
     readonly classifyConservatism: ClassifyConservatism;
     readonly classifyRules: ClassifyRuleOverrides;
@@ -84,15 +93,15 @@ export interface ProjectPreferences {
     /** Loop Autonomous (L4 14.5) toggle. Default: false — never auto-enable. */
     readonly loopAutonomousEnabled: boolean;
     /**
-     * L2.3 P2-a: ECC AgentShield subprocess toggle. Default: false.
+     * L2.3 P2-a: ECC AgentShield subprocess toggle — **frozen, no-op**.
      *
-     * When true, `peaks audit static` spawns `npx ecc-agentshield scan --json`
-     * and merges its findings into the audit report. When false (default),
-     * the audit runs peaks-loop-only and the subprocess is never spawned.
+     * Slice 3 of 4.0.0-beta.11 removed the ECC AgentShield subprocess
+     * entirely (upstream ships no `ecc-agentshield` binary). The field is
+     * retained only so legacy `.peaks/preferences.json` files still parse
+     * (`static-service.ts` calls `loadPreferences` for back-compat and
+     * ignores the value). Setting it to `true` has no effect.
      *
-     * The preference is independent of whether ECC is installed — i.e.
-     * `agentShieldEnabled: true` with ECC missing surfaces a soft
-     * "ECC not installed" warning and the audit still completes.
+     * Default: false.
      */
     readonly agentShieldEnabled: boolean;
     /**

package/dist/services/recommendations/capability-seed-items.js

@@ -98,7 +98,6 @@ export const seedCapabilityItems = [
     capability('gitnexus.repo-intelligence', 'gitnexus', 'GitNexus Repository Intelligence', 'cli', 'repo-intelligence', ['engineer'], 'medium', 'local-repo-scan', 'Use local project scanning through Peaks RD.', 'Repository Intelligence', '仓库智能分析', 'Repository intelligence should be proxied through Peaks before use.', '仓库智能分析应先通过 Peaks 代理边界再使用。'),
     capability('claude-code-best-practice.workflow-guidance', 'claude-code-best-practice', 'Claude Code Best Practice', 'doc', 'workflow-guidance', ['engineer'], 'low', 'peaks-built-in-rules', 'Use Peaks built-in workflow and review rules.', 'Claude Code Best Practice', 'Claude Code 最佳实践', 'Guidance for Claude Code engineering workflows.', 'Claude Code 工程工作流指导。'),
     capability('superpowers.workflow-methodology', 'superpowers', 'Superpowers Methodology', 'workflow', 'workflow-methodology', ['product', 'engineer'], 'low', 'peaks-workflow-route', 'Use Peaks route/autonomous plans.', 'Superpowers Methodology', 'Superpowers 方法论', 'Workflow and artifact methodology reference.', '工作流与 artifact 方法论参考。'),
-    capability('understand-anything.knowledge-graph', 'understand-anything', 'Understand Anything Knowledge Graph', 'skill', 'project-analysis', ['engineer', 'product', 'qa'], 'low', 'peaks-codegraph-or-rd-scan', 'Use peaks codegraph or peaks RD project scan when Understand Anything is not installed. Optionally suggest installing it via Claude Code: /plugin marketplace add Lum1104/Understand-Anything then /plugin install understand-anything.', 'Understand Anything Knowledge Graph', 'Understand Anything 知识图谱', 'Multi-agent project knowledge graph that Peaks reads from .understand-anything/knowledge-graph.json when it has been generated by the Understand Anything plugin in Claude Code.', '通过 Claude Code 的 Understand Anything 插件生成的多 agent 知识图谱，Peaks 在 .understand-anything/knowledge-graph.json 存在时读取它作为项目分析证据。'),
     capability('penpot.design-source', 'penpot', 'Penpot Design Source', 'doc', 'design-source', ['designer', 'engineer'], 'medium', 'manual-design-input', 'Ask for exported design notes or screenshots.', 'Penpot Design Source', 'Penpot 设计来源', 'Design-source reference for UI planning.', '用于 UI 规划的设计来源参考。'),
     capability('gstack.product-stack-guidance', 'gstack', 'Product Stack Guidance', 'doc', 'product-guidance', ['product'], 'low', 'peaks-prd', 'Use peaks-prd for product goals and non-goals.', 'Product Stack Guidance', '产品栈指导', 'Product and startup stack guidance reference.', '产品与创业栈指导参考。'),
     capability('awesome-design-md.design-reference', 'awesome-design-md', 'Design Markdown Reference', 'doc', 'design-reference', ['designer', 'engineer'], 'low', 'peaks-ui-visual-direction', 'Use peaks-ui to define visual direction and interaction constraints.', 'Design Reference', '设计参考', 'Design markdown examples and inspiration.', '设计 markdown 示例与灵感。'),

package/dist/services/recommendations/installed-capability-detector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Read-only "is this capability already satisfied on this machine?"
+ * detector for the capability catalog (`peaks capability status` /
+ * `peaks capabilities --source ...`).
+ *
+ * Slice B1 of 2026-09-09-ecc-dynamic-and-cleanup: the previous
+ * `getInstalledCapabilityIds()` returned `[]` unconditionally, so the
+ * catalog could never report anything as installed. This module answers
+ * the question from evidence that already exists on disk — no install
+ * side effect, no network, no subprocess:
+ *
+ *   - `everything-claude-code.*` — satisfied when the ECC cache is
+ *     populated (`~/.peaks/cache/ecc-installed.json` + at least one
+ *     cached/materialized agent).
+ *   - a source that maps to an npm package — satisfied when that package
+ *     (or its `.bin` shim) is present in the project's `node_modules`.
+ *
+ * Every probe is fail-soft: a throw degrades to "not installed" so the
+ * catalog never breaks because a probe failed.
+ */
+export type InstalledCapabilityProbe = {
+    /** Project whose `node_modules` is probed. */
+    readonly projectRoot: string;
+    /** Override for tests; defaults to `<projectRoot>/node_modules`. */
+    readonly nodeModulesDir?: string;
+    /** Override for tests; defaults to a live ECC cache probe. */
+    readonly eccCacheAvailable?: boolean;
+};
+/**
+ * Return the capabilityIds whose acquisition is already satisfied.
+ * Sorted + de-duplicated so the JSON envelope is stable across runs.
+ */
+export declare function detectInstalledCapabilityIds(probe: InstalledCapabilityProbe): string[];

package/dist/services/recommendations/installed-capability-detector.js

@@ -0,0 +1,76 @@
+/**
+ * Read-only "is this capability already satisfied on this machine?"
+ * detector for the capability catalog (`peaks capability status` /
+ * `peaks capabilities --source ...`).
+ *
+ * Slice B1 of 2026-09-09-ecc-dynamic-and-cleanup: the previous
+ * `getInstalledCapabilityIds()` returned `[]` unconditionally, so the
+ * catalog could never report anything as installed. This module answers
+ * the question from evidence that already exists on disk — no install
+ * side effect, no network, no subprocess:
+ *
+ *   - `everything-claude-code.*` — satisfied when the ECC cache is
+ *     populated (`~/.peaks/cache/ecc-installed.json` + at least one
+ *     cached/materialized agent).
+ *   - a source that maps to an npm package — satisfied when that package
+ *     (or its `.bin` shim) is present in the project's `node_modules`.
+ *
+ * Every probe is fail-soft: a throw degrades to "not installed" so the
+ * catalog never breaks because a probe failed.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasMaterializedEccAgents, listCachedAgents } from 'peaks-loop-mut';
+import { seedCapabilityItems } from './capability-seed-items.js';
+const ECC_SOURCE_ID = 'everything-claude-code';
+/**
+ * `sourceId` → npm package whose presence in `node_modules` satisfies the
+ * item's acquisition. Deliberately explicit: the catalog mixes repos,
+ * skills packages, MCP servers, and docs, and only a small subset is
+ * actually an npm dependency we can probe. Adding an entry here is the
+ * only change needed to make that source's items detectable.
+ */
+const NPM_PACKAGE_BY_SOURCE = {
+    codegraph: 'codegraph'
+};
+function packagePresent(nodeModulesDir, packageName) {
+    try {
+        return (existsSync(join(nodeModulesDir, packageName)) ||
+            existsSync(join(nodeModulesDir, '.bin', packageName)));
+    }
+    catch {
+        return false;
+    }
+}
+function eccCacheAvailable() {
+    try {
+        // Cached agents imply the manifest + sha dir exist; the materialized
+        // plugin-free copy is checked independently so a hand-populated
+        // `~/.peaks/agents/ecc/` still counts as satisfied.
+        return listCachedAgents().length > 0 || hasMaterializedEccAgents();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return the capabilityIds whose acquisition is already satisfied.
+ * Sorted + de-duplicated so the JSON envelope is stable across runs.
+ */
+export function detectInstalledCapabilityIds(probe) {
+    const nodeModulesDir = probe.nodeModulesDir ?? join(probe.projectRoot, 'node_modules');
+    const eccAvailable = probe.eccCacheAvailable ?? eccCacheAvailable();
+    const installed = new Set();
+    for (const item of seedCapabilityItems) {
+        if (item.sourceId === ECC_SOURCE_ID) {
+            if (eccAvailable)
+                installed.add(item.capabilityId);
+            continue;
+        }
+        const packageName = NPM_PACKAGE_BY_SOURCE[item.sourceId];
+        if (packageName !== undefined && packagePresent(nodeModulesDir, packageName)) {
+            installed.add(item.capabilityId);
+        }
+    }
+    return [...installed].sort();
+}

package/dist/services/scan/orphan-service.js

@@ -26,7 +26,7 @@ const PARENT_COMMANDS = new Set([
     'qa', 'sc', 'txt', 'code-review', 'rd', 'sh', 'config', 'audit', 'codegraph',
     'context', 'agent', 'capability', 'classify', 'gstack', 'gate',
     'hook', 'hooks', 'log', 'loop', 'memory', 'perf', 'playwright', 'preferences',
-    'project', 'retrospective', 'slice', 'statusline', 'understand', 'workflow',
+    'project', 'retrospective', 'slice', 'statusline', 'workflow',
     'migrate', 'mcp', 'doctor', 'help'
 ]);
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);

package/dist/services/slice/multi-pass-orchestrator.js

@@ -65,7 +65,6 @@ export async function decompose(rid, prdMarkdown, projectRoot, opts = {}) {
     const wantFile = granularity === 'file' || granularity === 'both' || granularity === 'auto';
     const passes = [];
     let codegraph = zeroCodegraph();
-    let understandAnything = zeroUnderstand();
     let pass1WorkUnits = [];
     if (wantService) {
         const result1 = await decomposeSlices(rid, prdMarkdown, projectRoot, opts);
@@ -77,7 +76,6 @@ export async function decompose(rid, prdMarkdown, projectRoot, opts = {}) {
             internalEdges: v1EdgesToV2(result1.dependencyDAG.edges)
         });
         codegraph = result1.codegraph;
-        understandAnything = result1.understandAnything;
     }
     if (wantFile) {
         if (pass1WorkUnits.length > 0) {
@@ -115,7 +113,6 @@ export async function decompose(rid, prdMarkdown, projectRoot, opts = {}) {
                 internalEdges: v1EdgesToV2(result.dependencyDAG.edges)
             });
             codegraph = result.codegraph;
-            understandAnything = result.understandAnything;
         }
     }
     let crossPassEdges = [];
@@ -136,7 +133,6 @@ export async function decompose(rid, prdMarkdown, projectRoot, opts = {}) {
         crossPassEdges,
         llmArbitrations,
         codegraph,
-        understandAnything,
         partial: false
     };
 }
@@ -214,12 +210,3 @@ function zeroCodegraph() {
         note: 'no decomposition run'
     };
 }
-function zeroUnderstand() {
-    return {
-        kgNodes: 0,
-        kgEdges: 0,
-        available: false,
-        fallback: 'structural-only',
-        note: 'no decomposition run'
-    };
-}

package/dist/services/slice/slice-decompose-import-edges.d.ts

@@ -4,5 +4,5 @@
  * the 800 LOC cap (mechanical verbatim move). `buildDependencyEdges` is
  * the only exported entry point; the rest are internal helpers.
  */
-import type { DependencyEdge, ImportEdge, KnowledgeGraph, WorkUnit } from './slice-decompose-types.js';
-export declare function buildDependencyEdges(wus: readonly WorkUnit[], importEdges: readonly ImportEdge[], kg: KnowledgeGraph | null, projectRoot: string): DependencyEdge[];
+import type { DependencyEdge, ImportEdge, WorkUnit } from './slice-decompose-types.js';
+export declare function buildDependencyEdges(wus: readonly WorkUnit[], importEdges: readonly ImportEdge[], projectRoot: string): DependencyEdge[];