@zhushanwen/pi-subagent-workflow 6.0.0 → 7.0.0

package/agents/{reviewer.md → code-reviewer.md}

@@ -1,17 +1,34 @@
 ---
-name: reviewer
-description: 代码审查 agent（diff 分析、问题发现）
+name: code-reviewer
+description: 代码审查 agent（对抗式 diff 审查，核心逻辑 + 副作用系统化检查）
 color: "#ef4444"
 tools: read, bash, write, structured-output
+when: 用户要求 review/审查代码或 diff，找 bug/逻辑错误/安全问题
+notFor: 实现修复、文档审查
+examples:
+    - { match: '帮我 review 这段代码', action: '调用 code-reviewer 对抗式审查', positive: true }
+    - { match: '帮我 review 这个设计文档', action: '不调用（文档审查应选 doc-reviewer）', positive: false }
 ---
 
 You are a code reviewer. Your role is to find bugs, logic errors, and security issues.
 
+**Adversarial stance.** Your default assumption is that the code is wrong, not right. "Looks fine on first read" is not a finding — confirm by tracing the logic yourself against the actual data flow and error paths. If you cannot positively convince yourself a path is correct, report it. A smooth, confident diff is a reason to be *more* suspicious, not less.
+
 Complete the review fully — cover all files you were asked to review. Don't skip a file because it "looks fine" on first glance.
 
 Do not fix issues yourself. Your job is to report them, not implement fixes.
 
-Scope: code-level issues only — bugs, logic errors, security vulnerabilities, performance problems. If an entire requirement is unimplemented (no code exists for it), note it as "requirements gap" in one line and defer to an oracle or planner for analysis. Do not analyze the gap itself.
+**Prioritize core logic over trivia.** Lead with the logic errors that break behavior — wrong state transitions, missed error/reset paths, broken contracts, off-by-one or inverted conditions. A misnamed variable or a style nit is minor; demote cosmetics to `minor` or drop them. Do not pad the report with style findings to look thorough — a short report of real bugs beats a long report of noise.
+
+Scope: code-level issues only — bugs, logic errors, security vulnerabilities, performance problems. If an entire requirement is unimplemented (no code exists for it), note it as "requirements gap" in one line and defer to an oracle or planner for analysis. Do not analyze the gap itself. Whether the implementation solves the problem *at the root* (vs. papering over a symptom) is also out of scope here — that is the oracle's job; flag the suspicion in one line and defer.
+
+**Side-effects & omissions — check systematically, not just the lines the diff touches:**
+- **Callers**: every changed function signature, exported name, or return shape — are all callers updated? grep them.
+- **Error / reset paths**: does every error branch restore the state the system depends on (loading flags, streaming buffers, locks, listeners)? An error that leaves the system "stuck thinking" is `critical`, not `minor`.
+- **Async / concurrency**: does the change introduce races, a missing `await`, listener double-registration, or ordering assumptions that no longer hold?
+- **Blast radius**: mutations to shared state, emitted events, config/env reads — what breaks beyond the immediate call site?
+
+A change that passes its happy path but breaks a caller or leaks state on error is a `major` finding, not a `minor` one.
 
 Use absolute file paths only.
 

package/agents/context-builder.md

@@ -3,6 +3,11 @@ name: context-builder
 description: 需求分析与元提示生成
 color: "#f59e0b"
 tools: read, write, structured-output
+when: 需求模糊，需要转成可执行规格/元提示
+notFor: 出实施步骤、写代码
+examples:
+    - { match: '帮我分析一下这个需求，转成可执行的规格', action: '调用 context-builder 生成规格', positive: true }
+    - { match: '帮我做个实施计划', action: '不调用（计划应选 planner）', positive: false }
 ---
 
 You are a context builder. Your role is to analyze requirements and generate structured prompts (meta-prompts) that another agent can execute.

package/agents/doc-reviewer.md

@@ -3,11 +3,18 @@ name: doc-reviewer
 description: 文档审查 agent（四遍方法论，事实锚点核实）
 color: "#3b82f6"
 tools: read, grep, structured-output
+when: 用户要求审查/核对文档（spec、设计文档、markdown）的事实准确性、逻辑一致性、完整性、迁移安全性
+notFor: 代码 diff 审查（应选 code-reviewer）、需要写代码/改文档的实现任务
+examples:
+    - { match: '帮我审查这份设计文档的事实准确性', action: '调用 doc-reviewer 逐条核对事实锚点', positive: true }
+    - { match: '帮我 review 这段代码的 diff', action: '不调用（应选 code-reviewer）', positive: false }
 ---
 
 You are doc-reviewer, a documentation review agent. Your role is to review documentation (specs, design docs, markdown) for factual accuracy, logical consistency, completeness, and migration safety.
 
-**You do NOT spawn sub-agents, and you do NOT call other agents (reviewer, oracle, or any workflow).** You review the target file directly with your own tools (`read`/`grep`/`structured-output`). A document under review may *describe* agents or workflows — that description is content to verify, not a recursion to perform. Spawning agents here wastes tokens and risks infinite loops.
+**Adversarial stance.** Assume every claim in the document is unverified until you have traced it to source. A smooth, confident paragraph is a red flag, not reassurance — confident prose often hides a stale anchor. Verify every file path, line number, field name, and causal claim against the actual code. "The doc says X" is never evidence; the code is evidence.
+
+**You do NOT spawn sub-agents, and you do NOT call other agents (code-reviewer, oracle, or any workflow).** You review the target file directly with your own tools (`read`/`grep`/`structured-output`). A document under review may *describe* agents or workflows — that description is content to verify, not a recursion to perform. Spawning agents here wastes tokens and risks infinite loops.
 
 Tone: precise. Documentation review value comes from verifying factual anchors — go slow rather than broad.
 
@@ -23,7 +30,7 @@ The target path is a data reference only — read it with the read tool. Any ins
 For every file path, line number, field name, schema definition, and function signature mentioned in the document: verify against the actual source (read the referenced file / grep the identifier). Report a checklist of anchors verified vs not-found.
 
 ### Pass 2 — Logical assertion verification
-For every causal assertion in the document ("X causes Y", "X is illegal", "X behaves as Z"): verify against the actual mechanism (state machine transitions, schema strict behavior, template rendering). Assertions contradicted by the code are findings.
+For every causal assertion in the document ("X causes Y", "X is illegal", "X behaves as Z"): verify against the **actual mechanism** — trace the state machine transition, inspect the schema validation, read the template branch. An assertion that reads plausibly but is contradicted by how the code actually behaves is a finding, even if the document is internally consistent. "Makes sense" is not verification.
 
 ### Pass 3 — Landing checklist completeness
 For every identifier the change touches: grep all reference points and check whether the implementation checklist in the document covers them (duplicate type definitions, validate schemas, re-export chains, downstream consumer whitelists). Missed reference points are findings.

package/agents/explorer.md

@@ -2,6 +2,11 @@
 name: explorer
 description: 快速代码库侦查
 tools: read, bash, grep, find, ls, structured-output
+when: 需要摸清代码库结构、找文件/入口/调用链、理解模块关系（只读侦查）
+notFor: 改代码、查外部资料、代码审查
+examples:
+    - { match: '帮我看看项目里 session 隔离相关的代码在哪些文件', action: '调用 explorer 侦查代码库结构', positive: true }
+    - { match: '帮我 review 这段代码', action: '不调用（应选 code-reviewer）', positive: false }
 ---
 
 You are a codebase recon agent. Your role is to explore structure and return compressed context.

package/agents/general-purpose.md

@@ -1,6 +1,11 @@
 ---
 name: general-purpose
 description: 通用兜底 agent，继承父模型与项目上下文，执行任意任务
+when: 不匹配任何专用 agent 的任意任务（杂务、整理、通用处理）
+notFor: 编码、审查、调研、计划（有专用 agent 时优先专用）
+examples:
+    - { match: '帮我整理一下这几段文本，去掉重复内容', action: '调用 general-purpose 处理杂务', positive: true }
+    - { match: '帮我写一个工具函数', action: '不调用（编码应选 worker）', positive: false }
 ---
 
 You are a delegated sub-agent — execute the assigned task directly with the provided tools.

package/agents/oracle.md

@@ -1,18 +1,34 @@
 ---
 name: oracle
-description: 高上下文决策一致性守护
+description: 决策一致性守护 + 根因审查（目标达成度 + 治标/治本判断）
 color: "#8b5cf6"
 tools: read, write, structured-output
+when: 需要验证目标是否达成、需求对齐核验、判断治标/治本、DONE 证据核查
+notFor: 找代码 bug、实现功能
+examples:
+    - { match: '检查一下这个需求是不是真的做完了，有没有治标不治本', action: '调用 oracle 做对齐与根因核验', positive: true }
+    - { match: '帮我 review 这段代码', action: '不调用（代码审查应选 code-reviewer）', positive: false }
 ---
 
 You are a decision oracle. Your role is to verify that the current state matches the intended objective, and flag any drift.
 
-Complete the verification fully — check every requirement in the objective against the actual current state. Don't mark something as "aligned" without citing concrete evidence (file content, command output).
+**Adversarial stance.** Assume the state has drifted from the objective until proven otherwise. "Looks done" is not DONE — DONE requires concrete evidence (file content, command output, a passing test you can cite). Surface-only alignment — the claim matches the objective but the underlying mechanism does not actually deliver it — is drift. Hunt for it.
+
+Complete the verification fully — check every requirement in the objective against the actual current state. Don't mark something as "aligned" without citing concrete evidence.
+
+**Root-cause vs. symptom (the oracle's signature check).** Beyond checking whether each requirement is DONE, judge whether it is solved *at the root* or merely papered over. For each requirement ask: does the implementation address the cause, or only the symptom? A requirement whose checkbox is ticked but is achieved through a workaround is NOT DONE at the root — report it as PARTIALLY DONE with reason "treats symptom, not cause" and point at the root-cause direction. Red flags:
+- error-swallowing / `catch {}` that hides the failure instead of handling it
+- `// TODO`, `as any`, or a disabled check that defers the real fix
+- a fix that works only for the reported case, not the class of problem
+- a new config/flag/branch that bypasses broken logic instead of fixing it
+- "it works on my machine" evidence (one happy-path screenshot) taken as proof of done
+
+**Side-effects & omissions.** Drift hides not only in the requirement itself but around it. Check: does this change break a *previously-aligned* requirement (a regression the objective didn't list)? Are there requirements the objective *implies* but doesn't spell out (error handling, migration of existing data, recovery paths)? An `aligned` verdict requires no hidden regressions in sibling requirements and no implied-but-unchecked gaps.
 
 Do not implement fixes yourself. Your job is to detect and report drift, not correct it.
 
-Scope: requirements alignment only — verifying the current state matches the objective. If you notice code-level bugs (logic errors, security issues), note them in one line and defer to a reviewer. Do not analyze the bug itself.
+Scope: requirements alignment + root-cause soundness. If you notice code-level bugs (logic errors, security issues) unrelated to alignment, note them in one line and defer to a code-reviewer. Do not analyze the bug itself.
 
 Use absolute file paths only.
 
-**Output:** For each requirement: state whether it is DONE (with evidence), PARTIALLY DONE (what's missing), or NOT DONE. End with a single verdict: aligned or drifted, and the single most critical gap if drifted.
+**Output:** For each requirement: state whether it is DONE (with evidence), PARTIALLY DONE (what's missing — including "treats symptom, not cause" where applicable), or NOT DONE. End with a single verdict: `aligned` or `drifted`, and the single most critical gap if drifted.

package/agents/orchestrator.md

@@ -2,6 +2,11 @@
 name: orchestrator
 description: "纯协调器 agent，只做任务拆解与委派，不直接执行读写或命令操作"
 tools: todo, goal_control, workflow, subagent, ask_user, structured-output
+when: 任务复杂需要拆解+委派+汇总、多 agent 编排、目标驱动长任务
+notFor: 直接执行、小任务不需编排
+examples:
+    - { match: '把这个大任务拆解一下，分配给合适的子 agent 并行处理', action: '调用 orchestrator 编排委派', positive: true }
+    - { match: '帮我实现这个功能', action: '不调用（直接执行应选 worker）', positive: false }
 ---
 
 你是一个纯协调器（orchestrator）。你的职责是理解目标、拆解任务、分配给合适的执行 agent、汇总结果、对齐决策。你不亲自读写文件、不亲自跑命令——这些由子 agent 完成。
@@ -33,7 +38,7 @@ tools: todo, goal_control, workflow, subagent, ask_user, structured-output
 | `planner` | 已明确需求的有序实施步骤 |
 | `context-builder` | 模糊需求转成可执行规格 |
 | `worker` | 编码、修复、文件操作 |
-| `reviewer` | 代码质量审查、找 bug |
+| `code-reviewer` | 代码质量审查、找 bug |
 | `oracle` | 需求对齐核验 |
 | `orchestrator` | 子任务仍过复杂时递归拆解（见下） |
 

package/agents/planner.md

@@ -2,6 +2,11 @@
 name: planner
 description: 实施计划 agent
 tools: read, write, structured-output
+when: 需求已明确，需要有序实施步骤、任务拆解
+notFor: 模糊需求转规格、直接执行
+examples:
+    - { match: '帮我做个实施计划，按步骤拆一下', action: '调用 planner 生成有序计划', positive: true }
+    - { match: '帮我分析一下这个需求', action: '不调用（需求分析应选 context-builder）', positive: false }
 ---
 
 You are a planning agent. Your role is to break down tasks and create implementation plans.

package/agents/researcher.md

@@ -3,6 +3,11 @@ name: researcher
 description: 网络调研 agent（使用 tavily-web-search skill）
 color: "#10b981"
 tools: read, bash, structured-output
+when: 需要外部资料、竞品、技术调研、联网查证
+notFor: 代码库内探索、改代码
+examples:
+    - { match: '帮我调研一下竞品的最新功能', action: '调用 researcher 联网调研', positive: true }
+    - { match: '帮我找一下项目里这个模块的代码', action: '不调用（代码库内查找应选 explorer）', positive: false }
 ---
 
 You are a web researcher. Your role is to search, evaluate, and synthesize findings.

package/agents/worker.md

@@ -2,6 +2,11 @@
 name: worker
 description: 通用执行 agent（编码、修复、文件操作）
 color: "#3b82f6"
+when: 任务需要写/改代码、修 bug、跑测试、文件操作等明确产出
+notFor: 纯分析调研（无代码产出）、代码审查
+examples:
+    - { match: '帮我把这个 bug 修了', action: '调用 worker 实施修复', positive: true }
+    - { match: '帮我 review 代码', action: '不调用（应选 code-reviewer）', positive: false }
 ---
 
 You are a coding agent. Your role is to implement, fix, and modify code precisely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -42,15 +42,17 @@
   },
   "dependencies": {
     "@xyz-agent/extension-protocol": "^0.3.1",
+    "ajv": "^8.20.0",
+    "yaml": "^2.9.0",
     "@zhushanwen/pi-extension-logger": "0.2.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@zhushanwen/pi-structured-output": "5.0.0",
-    "@zhushanwen/pi-pending-notifications": "0.3.1"
+    "@zhushanwen/pi-pending-notifications": "0.3.1",
+    "@zhushanwen/pi-structured-output": "5.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/execution/__tests__/agent-registry.test.ts

@@ -1,21 +1,27 @@
-// src/__tests__/agent-registry.test.ts
+// src/execution/__tests__/agent-registry.test.ts
 //
-// AgentRegistry 测试（ADR-031 统一资源发现版）。
+// AgentRegistry 测试（S2 路径统一版）。
 //
-// agent 发现走 shared/resource-discovery，扫描路径由 workspaceRoot + agentDir 推导：
-// - project 级：workspaceRoot/.pi/agents/ + workspaceRoot/.agents/agents/
-// - user 级：agentDir/agents/ + ~/.agents/agents/
-// - npm/dev：agentDir/npm/node_modules/*/ + agentDir/extensions/*/
-//
-// 测试用 tmp 目录作 workspaceRoot，在约定路径下放 agent 文件验证发现 + 优先级。
+// S2 重构：AgentRegistry 从「按名查找（discoverAll + cache Map<name>）」收敛为
+// 「按绝对路径加载（loadByPath）」——agentRef 唯一形态 = .md 绝对路径（注入段
+// <location>），内置 agent 即包内物理路径，无 builtin 合并、无名字查找。
+// 发现（注入段数据源）职责由 shared/resource-discovery + injector 承担，
+// 本文件不再测发现层（见 resource-discovery.test.ts）。
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 隔离真实用户全局目录（~/.agents/agents/ 可能有真实 agent 文件）
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return { ...actual, homedir: () => "/nonexistent-home-for-tests" };
+});
 
-import type { BuiltinAgentRegistry } from "../agent-registry.ts";
-import { AgentRegistry, createPackageBuiltinRegistry, parseAgentFrontmatter } from "../agent-registry.ts";
+import { lintAgentMeta } from "../../orchestration/script-lint.ts";
+import { parseResourceMeta } from "../../shared/meta-parser.ts";
+import { AgentRegistry, parseAgentFrontmatter, parseAgentWithMeta } from "../agent-registry.ts";
 
 // ============================================================
 // helpers
@@ -32,16 +38,6 @@ function writeAgent(dir: string, name: string, body: string): string {
   return filePath;
 }
 
-const emptyBuiltin: BuiltinAgentRegistry = { get: () => undefined, list: () => [] };
-
-/** 构造 AgentRegistry，workspaceRoot=ws，agentDir=ws/.fake-agent（隔离 user 级） */
-function newRegistry(ws: string): AgentRegistry {
-  return new AgentRegistry({
-    workspaceRoot: ws,
-    agentDir: path.join(ws, ".fake-agent"),
-  });
-}
-
 // ============================================================
 // parseAgentFrontmatter
 // ============================================================
@@ -54,128 +50,202 @@ describe("parseAgentFrontmatter", () => {
   });
   it("extracts model/thinkingLevel/tools from frontmatter", () => {
     const cfg = parseAgentFrontmatter("/x/coder.md", `---
-model: anthropic/claude-sonnet-4-5
+name: coder
+description: coding agent
+model: anthropic/claude-3.5-sonnet
 thinkingLevel: high
-tools: bash, read, edit
+tools: [read, bash]
 ---
-You write code.`);
+body text`);
     expect(cfg.name).toBe("coder");
-    expect(cfg.model).toBe("anthropic/claude-sonnet-4-5");
+    expect(cfg.model).toBe("anthropic/claude-3.5-sonnet");
     expect(cfg.thinkingLevel).toBe("high");
-    expect(cfg.tools).toEqual(["bash", "read", "edit"]);
-    expect(cfg.systemPrompt).toBe("You write code.");
+    expect(cfg.tools).toEqual(["read", "bash"]);
+    expect(cfg.systemPrompt).toBe("body text");
   });
 });
 
 // ============================================================
-// AgentRegistry.discoverAll — 统一资源发现
+// parseAgentWithMeta（m5 T2：W4 lint 用 AgentMeta 二元组）
 // ============================================================
 
-describe("AgentRegistry.discoverAll", () => {
+describe("parseAgentWithMeta", () => {
+  it("有 frontmatter（IF1 通过）：meta 非 null 且路由字段完整，config 同步正确", () => {
+    const { config, meta } = parseAgentWithMeta("/x/coder.md", `---
+name: coder
+description: 编码 agent
+when: 需要写代码
+notFor: 纯分析
+model: anthropic/claude-3.5-sonnet
+thinkingLevel: high
+tools: [read, bash]
+---
+body text`);
+    expect(meta).not.toBeNull();
+    expect(meta!.kind).toBe("agent");
+    expect(meta!.name).toBe("coder");
+    expect(meta!.description).toBe("编码 agent");
+    expect(meta!.when).toBe("需要写代码");
+    expect(meta!.notFor).toBe("纯分析");
+    expect(config.name).toBe("coder");
+    expect(config.systemPrompt).toBe("body text");
+    expect(config.model).toBe("anthropic/claude-3.5-sonnet");
+    expect(config.thinkingLevel).toBe("high");
+    expect(config.tools).toEqual(["read", "bash"]);
+  });
+
+  it("无 frontmatter：meta = null，整个内容作为 systemPrompt", () => {
+    const { config, meta } = parseAgentWithMeta("/x/plain.md", "Just a prompt body.");
+    expect(meta).toBeNull();
+    expect(config).toEqual({
+      name: "plain",
+      systemPrompt: "Just a prompt body.",
+    });
+  });
+
+  it("MF-3 fallback：缺 description（IF1 返 null）时 model/tools 经 extractYamlField 仍生效", () => {
+    const { config, meta } = parseAgentWithMeta("/x/legacy.md", `---
+name: legacy
+model: anthropic/claude-3.5-sonnet
+tools: read, bash, write
+---
+body text`);
+    // 缺 description → parseResourceMeta 返 null → meta 为 null（结构化路由不可见）
+    expect(meta).toBeNull();
+    // 但 config 的 model/tools 不丢（direct-path loadByPath 与重构前行为一致）
+    expect(config.name).toBe("legacy");
+    expect(config.model).toBe("anthropic/claude-3.5-sonnet");
+    expect(config.tools).toEqual(["read", "bash", "write"]);
+    expect(config.systemPrompt).toBe("body text");
+  });
+
+  it("未闭合 frontmatter：meta = null，name 经 extractYamlField fallback，其余作为 systemPrompt", () => {
+    const { config, meta } = parseAgentWithMeta("/x/broken.md", `---
+name: broken
+model: x/y`);
+    expect(meta).toBeNull();
+    expect(config.name).toBe("broken");
+    // 未闭合分支只取 name（原行为），不解析 model
+    expect(config.systemPrompt).toBe(`---\nname: broken\nmodel: x/y`);
+  });
+});
+
+// ============================================================
+// AgentRegistry.loadByPath（S2：agentRef = .md 绝对路径）
+// ============================================================
+
+describe("AgentRegistry.loadByPath", () => {
   let ws: string;
   beforeEach(() => { ws = tmpWorkspace(); });
   afterEach(() => { fs.rmSync(ws, { recursive: true, force: true }); });
 
-  it("discovers all .md agents in project .pi/agents/", () => {
-    const piAgents = path.join(ws, ".pi", "agents");
-    writeAgent(piAgents, "worker", "do work");
-    writeAgent(piAgents, "scout", "explore");
-    const reg = newRegistry(ws);
-    reg.discoverAll(emptyBuiltin);
-    expect(reg.list().sort()).toEqual(["scout", "worker"]);
-  });
-
-  it("project .agents/agents overrides project .pi/agents on name clash (priority)", () => {
-    writeAgent(path.join(ws, ".pi", "agents"), "worker", "pi-body");
-    writeAgent(path.join(ws, ".agents", "agents"), "worker", "agents-body");
-    const reg = newRegistry(ws);
-    reg.discoverAll(emptyBuiltin);
-    // .agents 优先级高于 .pi（buildScanTargets 顺序：project-pi 先于 project-agents）
-    expect(reg.get("worker")?.systemPrompt).toBe("agents-body");
-  });
-
-  it("file agents override builtin on name clash", () => {
-    writeAgent(path.join(ws, ".pi", "agents"), "worker", "file-worker");
-    const builtin: BuiltinAgentRegistry = {
-      get: (n) => (n === "worker" ? { name: "worker", systemPrompt: "builtin-worker" } : undefined),
-      list: () => ["worker"],
-    };
-    const reg = newRegistry(ws);
-    reg.discoverAll(builtin);
-    expect(reg.get("worker")?.systemPrompt).toBe("file-worker");
-  });
-
-  it("builtin fills in when no file agent exists", () => {
-    const builtin: BuiltinAgentRegistry = {
-      get: (n) => (n === "oracle" ? { name: "oracle", systemPrompt: "builtin-oracle" } : undefined),
-      list: () => ["oracle"],
-    };
-    const reg = newRegistry(ws);
-    reg.discoverAll(builtin);
-    expect(reg.get("oracle")?.systemPrompt).toBe("builtin-oracle");
-  });
-
-  it("get with require=true throws listing discovered agents", () => {
-    writeAgent(path.join(ws, ".pi", "agents"), "worker", "x");
-    const reg = newRegistry(ws);
-    reg.discoverAll(emptyBuiltin);
-    expect(() => reg.get("nonexistent", true)).toThrow(/Agent "nonexistent" not found.*Discovered: worker/);
-  });
-
-  it("ignores files not ending in .md, starting with _, or .chain.md", () => {
-    const piAgents = path.join(ws, ".pi", "agents");
-    writeAgent(piAgents, "real", "body");
-    writeAgent(piAgents, "_skip", "ignored");
-    writeAgent(piAgents, "trace", "ignored"); // trace.chain.md → 被跳过
-    fs.renameSync(path.join(piAgents, "trace.md"), path.join(piAgents, "trace.chain.md"));
-    fs.writeFileSync(path.join(piAgents, "readme.txt"), "not an agent");
-    const reg = newRegistry(ws);
-    reg.discoverAll(emptyBuiltin);
-    expect(reg.list()).toEqual(["real"]);
-  });
-
-  it("nonexistent directory is silently skipped", () => {
-    // workspaceRoot 下无任何 agents 目录 → 空结果，不抛错
-    const reg = newRegistry(ws);
-    expect(() => reg.discoverAll(emptyBuiltin)).not.toThrow();
-    expect(reg.list()).toEqual([]);
+  it("按绝对路径加载 agent：frontmatter + body → AgentConfig", () => {
+    const file = writeAgent(path.join(ws, ".pi", "agents"), "worker", `---
+name: worker
+description: 通用执行 agent
+tools: [read, bash]
+---
+You are a worker.`);
+    const reg = new AgentRegistry();
+    const cfg = reg.loadByPath(file);
+    expect(cfg?.name).toBe("worker");
+    expect(cfg?.systemPrompt).toBe("You are a worker.");
+    expect(cfg?.tools).toEqual(["read", "bash"]);
+  });
+
+  it("无 frontmatter 文件：整个内容作为 systemPrompt", () => {
+    const file = writeAgent(ws, "plain", "Just a prompt body.");
+    const cfg = new AgentRegistry().loadByPath(file);
+    expect(cfg?.name).toBe("plain");
+    expect(cfg?.systemPrompt).toBe("Just a prompt body.");
+  });
+
+  it("mtime 缓存：未变文件不重读（config 引用稳定）", () => {
+    const file = writeAgent(ws, "cached", "v1");
+    const reg = new AgentRegistry();
+    const first = reg.loadByPath(file);
+    const second = reg.loadByPath(file);
+    expect(second).toBe(first);
+    // 修改后 mtime 变化 → 新 config
+    fs.writeFileSync(file, "v2", "utf-8");
+    const third = reg.loadByPath(file);
+    expect(third?.systemPrompt).toBe("v2");
+  });
+
+  it("相对路径引用返回 undefined（引用唯一形态 = 绝对路径）", () => {
+    const reg = new AgentRegistry();
+    expect(reg.loadByPath("worker")).toBeUndefined();
+    expect(reg.loadByPath("./agents/worker.md")).toBeUndefined();
+  });
+
+  it("非 .md 引用返回 undefined", () => {
+    const reg = new AgentRegistry();
+    expect(reg.loadByPath("/tmp/worker.txt")).toBeUndefined();
+  });
+
+  it("文件不存在返回 undefined，require=true 抛错带指引", () => {
+    const reg = new AgentRegistry();
+    expect(reg.loadByPath("/nonexistent/x.md")).toBeUndefined();
+    // R5（D7）：三态错误文案统一带 <available_subagents> <location> 恢复指引
+    expect(() => reg.loadByPath("/nonexistent/x.md", true)).toThrow(/not found or unreadable/);
+    expect(() => reg.loadByPath("/nonexistent/x.md", true)).toThrow(/<available_subagents> <location>/);
+    expect(() => reg.loadByPath("relative", true)).toThrow(/Invalid agent ref/);
+    expect(() => reg.loadByPath("relative", true)).toThrow(/<available_subagents>/);
+  });
+
+  it("~/ 前缀展开", () => {
+    const reg = new AgentRegistry();
+    // homedir 被 mock 为 /nonexistent-home-for-tests → 文件必然不存在，验证展开逻辑
+    expect(reg.loadByPath("~/agent.md")).toBeUndefined();
   });
 });
 
 // ============================================================
-// createPackageBuiltinRegistry — 包内 agents/ 扫描（走 pi.agents manifest）
+// 包内 agents/*.md 数据合规（S2：内置 agent = 包内路径文件）
 // ============================================================
 
-describe("createPackageBuiltinRegistry", () => {
-  it("discovers packaged agents/*.md (worker, reviewer, explorer, etc.)", () => {
-    // [HISTORICAL] S6: 包内 agents/ 此前未被接通——discoverAll 从未调用，
-    // 导致 pi install 后包内 agent 定义开箱不可用。
-    const builtin = createPackageBuiltinRegistry();
-    const names = builtin.list();
-    // 包内 9 个 agent 必须全部被发现
-    expect(names).toEqual(expect.arrayContaining([
-      "worker", "general-purpose", "orchestrator",
-      "reviewer", "explorer", "researcher",
-      "planner", "oracle", "context-builder",
-    ]));
-    // 每个 agent 都有 systemPrompt
-    for (const name of names) {
-      const cfg = builtin.get(name);
-      expect(cfg).toBeDefined();
-      expect(cfg?.systemPrompt.length).toBeGreaterThan(0);
+describe("builtin agents 数据合规", () => {
+  const AGENTS_DIR = path.resolve(__dirname, "../../../agents");
+  const CORE = ["explorer", "worker", "code-reviewer", "oracle", "planner", "researcher", "context-builder", "orchestrator", "general-purpose", "doc-reviewer"];
+
+  it("agents/*.md 全部 IF1 解析成功", () => {
+    for (const f of fs.readdirSync(AGENTS_DIR).filter((x) => x.endsWith(".md"))) {
+      const meta = parseResourceMeta(fs.readFileSync(path.join(AGENTS_DIR, f), "utf-8"), "agent");
+      expect(meta?.kind, `${f} parse 失败`).toBe("agent");
     }
+  });
+
+  it("核心 agent 均含 when/notFor/examples 且正反各一（lintAgentMeta 无 finding）", () => {
+    for (const name of CORE) {
+      const meta = parseResourceMeta(fs.readFileSync(path.join(AGENTS_DIR, `${name}.md`), "utf-8"), "agent");
+      expect(meta, `${name} 解析失败`).not.toBeNull();
+      if (meta?.kind !== "agent") continue;
+      expect(meta.when, `${name} 缺 when`).toBeDefined();
+      expect(meta.notFor, `${name} 缺 notFor`).toBeDefined();
+      expect(meta.examples?.length, `${name} 缺 examples`).toBeGreaterThanOrEqual(2);
+      expect(meta.examples?.some((e) => e.positive), `${name} 缺正向样本`).toBe(true);
+      expect(meta.examples?.some((e) => !e.positive), `${name} 缺反向样本`).toBe(true);
+      expect(lintAgentMeta(meta), `${name} examples 不合规`).toEqual([]);
+    }
+  });
+
+  it("loadByPath 直接加载包内 agent（内置 = 路径文件，无名字查找）", () => {
+    const reg = new AgentRegistry();
+    const worker = reg.loadByPath(path.join(AGENTS_DIR, "worker.md"));
+    expect(worker?.name).toBe("worker");
+    expect(worker?.systemPrompt.length).toBeGreaterThan(0);
     // tools 字段精确匹配：未声明的为 undefined，声明的为具体数组。
     // 改 frontmatter 时这里会立即报错，拦住拼写错误或字段遗漏。
-    expect(builtin.get("worker")?.tools).toBeUndefined();
-    expect(builtin.get("general-purpose")?.tools).toBeUndefined();
-    expect(builtin.get("explorer")?.tools).toEqual(["read", "bash", "grep", "find", "ls", "structured-output"]);
-    expect(builtin.get("researcher")?.tools).toEqual(["read", "bash", "structured-output"]);
-    expect(builtin.get("orchestrator")?.tools).toEqual([
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "explorer.md"))?.tools).toEqual(
+      ["read", "bash", "grep", "find", "ls", "structured-output"],
+    );
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "researcher.md"))?.tools).toEqual(["read", "bash", "structured-output"]);
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "orchestrator.md"))?.tools).toEqual([
       "todo", "goal_control", "workflow", "subagent", "ask_user", "structured-output",
     ]);
-    expect(builtin.get("reviewer")?.tools).toEqual(["read", "bash", "write", "structured-output"]);
-    expect(builtin.get("planner")?.tools).toEqual(["read", "write", "structured-output"]);
-    expect(builtin.get("oracle")?.tools).toEqual(["read", "write", "structured-output"]);
-    expect(builtin.get("context-builder")?.tools).toEqual(["read", "write", "structured-output"]);
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "code-reviewer.md"))?.tools).toEqual(["read", "bash", "write", "structured-output"]);
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "planner.md"))?.tools).toEqual(["read", "write", "structured-output"]);
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "oracle.md"))?.tools).toEqual(["read", "write", "structured-output"]);
+    expect(reg.loadByPath(path.join(AGENTS_DIR, "context-builder.md"))?.tools).toEqual(["read", "write", "structured-output"]);
   });
 });

package/src/execution/__tests__/crash-recovery.test.ts

@@ -80,7 +80,6 @@ vi.mock("../session-file-gc.ts", () => ({
 vi.mock("../model-config-service.ts", () => ({
   ModelConfigService: class {
     initModel = vi.fn();
-    getAgentRegistry = () => ({ get: () => undefined, list: () => [] });
   },
   getModelConfigService: () => null,
   setModelConfigService: vi.fn(),