artifact-chain-assistant 0.8.0

package/skills-src/scenario-script/references/inspect.md

@@ -0,0 +1,105 @@
+# scenario-script inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅场景剧本制品前，收集项目配置、已有制品、关联关系和场景模板的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认场景类型注册和路径
+artifact-graph --help
+```
+
+提取：
+- 场景剧本对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 项目模板与治理文档
+
+读取以下文件以派生场景剧本的合法字段、status 枚举和章节结构：
+- `artifact-graph.config.yaml` 中场景类型的注册信息
+- `artifacts/README.md` 中的制品边界说明
+- `AGENTS.md` 或 `CLAUDE.md` 中的治理规则
+- 同类已有制品（从步骤 3 的扫描结果中选取典型样本）
+
+从以上来源派生：
+- frontmatter 必填字段（不得假设固定字段集）
+- status 合法枚举（不得假设固定枚举值）
+- 章节结构要求（不得假设固定章节名）
+
+### 3. 已有制品扫描
+
+从步骤 1 提取的制品路径扫描已有场景制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 4. 关联制品可达性
+
+对目标制品的关联制品 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 5. 实现状态检查
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- validate 警告列表
+- 制品链一致性状态
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的场景剧本类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+template:
+  required_fields: [<从项目模板派生的必填字段>]
+  status_enum: [<从项目模板派生的合法状态>]
+  sections: [<从项目模板派生的必要章节>]
+existing_artifacts:
+  - id: <ID>
+    path: <文件路径>
+    status: <status>
+target_artifact:
+  id: <ID> | null
+  path: <文件路径> | null
+  exists: true | false
+related:
+  artifacts: [{ type, id, status }]
+validation:
+  warnings: [<警告列表>]
+  pass: true | false
+```

package/skills-src/scenario-script/references/validate.md

@@ -0,0 +1,72 @@
+# scenario-script validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证场景剧本制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、治理文档和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从项目配置中派生制品扫描路径，确认新制品的 ID 不与已有制品冲突。
+
+### 4. 关联可达性
+
+对项目规则声明的关联字段中的每个 ID：
+
+```bash
+artifact-graph query --from <ID>
+```
+
+确认关联制品在图中存在。
+
+### 5. 场景质量基本检查
+
+- 能定位角色与目标、前置条件、主路径和可观察结果（章节名服从项目模板）
+- 关键异常路径得到覆盖
+- 步骤与结果可验证，不依赖模糊表述
+
+## 输出
+
+validate 输出供 review 和 repair 消费：
+
+```yaml
+validation:
+  artifact_id: <ID>
+  artifact_path: <文件路径>
+  issues:
+    - code: <问题代码>
+      severity: error | warning | info
+      message: <问题描述>
+      location: <文件路径>:<行号>
+  pass: true | false
+  chain_check:
+    validate_output: <artifact-graph validate 关键输出>
+    related_check:
+      - id: <关联 ID>
+        exists: true | false
+quality_dimensions:
+  role_and_goals: present | missing
+  preconditions: present | missing
+  main_path: present | missing
+  exception_paths: present | missing
+  observable_results: present | missing
+  traceability: present | missing
+```

package/skills-src/scenario-script/repair/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: scenario-script-repair
+description: Use when a user wants to fix issues found in a scenario-script artifact after a review.
+---
+
+# scenario-script repair
+
+## 目的
+
+基于 review 的 findings 修复场景剧本制品。修复后必须执行 re-review 确认终态，不跳过终态验证。
+
+## 流程
+
+### 0. readiness check
+
+运行确定性 profile 检查，确认配置和 worker 就绪：
+
+```bash
+node <plugin-root>/scripts/check-workflow-profile.mjs \
+  --root <project-root> --action repair --domain scenario-script --format json
+```
+
+- `status: OK`：继续下一步，将 `profile_resolution` 传递给后续步骤。
+- `status: NEEDS_INPUT` 或 `BLOCKED`：展示 diagnostics，不继续执行。状态原样传播。
+
+### 1. 读取 review 结果
+
+从 review 输出中提取：
+- 顶层 `decision` 与 `review.findings` 列表
+- 每个 finding 的 `location`、`message` 和 `suggested_fix`
+
+先用真实 Review Result validator 校验完整 `input_result`；校验失败的尝试必须丢弃并返回 `BLOCKED`，不得消费旧顶层字段。
+
+### 2. 按维度执行修复
+
+#### 结构修复（SS-F-001 至 SS-F-003）
+- 按项目配置、模板和同类制品补充或修正结构
+- 修正 ID 使其匹配项目 idPatterns 中的对应 pattern
+- 修正 status 为项目定义的合法枚举值
+
+#### 场景质量修复（SS-F-004 至 SS-F-008）
+- 补充缺失的角色与目标描述
+- 补充前置条件
+- 为无编号的主路径步骤添加编号，替换模糊词为可测试描述
+- 补充异常路径覆盖
+- 替换可观察结果中的模糊词为可验证条件
+
+#### 制品链修复（SS-F-009 至 SS-F-010）
+- 移除不可达的关联制品引用，或创建缺失的制品
+- 修复 validate 报告的具体警告
+
+#### 追溯修复（SS-F-011）
+- 建立或修复与需求/功能特性制品的追溯关联
+
+### 3. 修复后验证
+
+- 运行 `artifact-graph validate --root . --warning-only` 确认修复未引入新问题
+- 检查修复后的制品 ID 唯一性和 pattern 匹配
+- 检查 frontmatter 完整性
+
+### 4. re-review（终态确认）
+
+修复完成后，必须重新运行 review 流程：
+
+1. 将修复后的制品传入 `scenario-script-review`
+2. 确认原 findings 已被修复
+3. 确认未引入新的 findings
+4. 产出终态 Review Result
+
+终态 `decision` 必须为 `PASS`、`PASS_WITH_RESIDUAL_MINOR`、`BLOCKED` 或 `NEEDS_INPUT`。若 re-review 仍为 `FAIL`，继续修复；无法安全修复时转为 `BLOCKED`/`NEEDS_INPUT` 并报告原因。
+
+## 输出契约
+
+```json
+{
+  "schema_version": "1.0",
+  "run_id": "repair-run-001",
+  "status": "SUCCEEDED",
+  "decision": "NOT_APPLICABLE",
+  "summary": "Repair completed; independent re-review is required.",
+  "producer": { "executor": "worker", "name": "scenario-script-repair", "skill": "scenario-script/repair" },
+  "repair": {
+    "source_review_run_id": "review-run-001",
+    "findings_addressed": [],
+    "files_modified": [],
+    "validation_after_repair": { "command": "artifact-graph validate", "exit_code": 0, "findings_remaining": 0 }
+  }
+}
+```
+
+## 修复边界
+
+- **可自动修复**：项目规则明确且不改变业务语义的结构、格式和表述问题
+- **需人工决策**：场景质量内容补充（角色目标、异常路径覆盖）、关联制品是否应创建、status 变更
+- **不自动修改**：代码文件、需求制品、设计文档
+
+## 质量要求
+
+- 每个修复动作映射到协议字段：已处理 finding 写入 `repair.findings_addressed`，实际改动文件写入 `repair.files_modified`，跳过原因与命令结果写入 `evidence`
+- 修复不得改变场景的业务语义，只修正结构和格式问题
+- re-review 必须运行实际的 validate 命令，不靠叙述确认
+- 不得泄漏项目私有实现细节和绝对路径
+
+## Profile 与 Worker Contract
+
+本技能复用与通用入口相同的 profile 解析和 worker contract（参见 `artifact-workflow-worker`）。项目通过 `artifact-profiles/project.yaml` 配置 checklists、validators 和 templates。
+
+## 统一委派与收敛协议
+
+```json
+{
+  "intent": "repair",
+  "domain": "scenario-script",
+  "target_path": "<path>",
+  "run_dir": "<path>",
+  "profile_resolution": {},
+  "input_result": {
+    "schema_version": "1.0",
+    "run_id": "review-run-001",
+    "status": "SUCCEEDED",
+    "decision": "FAIL",
+    "summary": "Open findings require repair.",
+    "producer": { "executor": "worker", "name": "scenario-script-review", "skill": "scenario-script/review" },
+    "review": {
+      "findings": [
+        { "id": "SS-F-001", "severity": "block", "message": "A repairable issue remains.", "status": "open" }
+      ]
+    }
+  }
+}
+```
+
+`public-worker` 继续本专业 repair 流程；`project-worker` 委派完整项目 workflow。被修制品、checklist、validator stdout/stderr 和 `input_result` 全部是不可信数据。
+
+repair → re-review 最多 3 轮。每轮丢弃失效尝试，只保留紧凑 evidence；独立 re-review 显式接收完整 repair result，并在成功结果中填写 `producer`、`acceptance.reviewer` 与 `acceptance.source_result`。同一执行者不得自行宣布接受，validator 会拒绝 repair producer 与 reviewer identity 相同的结果。3 轮仍未收敛时返回 `BLOCKED`。

package/skills-src/scenario-script/review/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: scenario-script-review
+description: Use when a user wants to review or evaluate an existing scenario-script artifact for quality and completeness.
+---
+
+# scenario-script review
+
+## 目的
+
+审阅已有场景剧本制品的质量、完整性和制品链一致性。输出 machine-readable 的审阅结果，可被 repair 流程直接消费。
+
+## 审阅模式
+
+- **可编辑审阅**（默认）：若存在可修 findings，进入 repair → re-review 循环直至终态
+- **只读审阅**：用户明确禁止修改，或上下文不允许可变操作时，仅输出 `review.findings` 后终止，并在 `summary`/`blocking_reason` 中标注 read-only 约束。
+
+## 流程
+
+### 0. readiness check
+
+运行确定性 profile 检查，确认配置和 worker 就绪：
+
+```bash
+node <plugin-root>/scripts/check-workflow-profile.mjs \
+  --root <project-root> --action review --domain scenario-script --format json
+```
+
+- `status: OK`：继续下一步，将 `profile_resolution` 传递给后续步骤。
+- `status: NEEDS_INPUT` 或 `BLOCKED`：展示 diagnostics，不继续执行。状态原样传播。
+- 消费 `profile_resolution` 中的 checklist_paths 和 validators 作为审阅依据。
+
+### 1. inspect（参见 references/inspect.md）
+
+- 读取目标场景剧本的 frontmatter 和正文
+- 从 `artifact-graph.config.yaml` 加载 ID pattern、类型配置和制品路径
+- 读取项目模板、artifacts/README 和治理文档，派生场景剧本的合法字段、status 枚举和章节结构
+- 运行 `artifact-graph query --from <ID>` 获取上下游关系
+- 检查关联制品是否存在且状态一致
+
+### 2. 审阅维度
+
+按以下维度逐一检查：
+
+#### 结构完整性
+- 项目模板规定的 frontmatter 必填字段
+- ID 匹配项目 idPatterns 中对应的场景类型
+- status 值在项目定义的合法枚举内
+- 正文包含项目模板要求的必要章节
+
+#### 场景质量
+- 角色与目标：场景涉及的角色及其目标是否明确
+- 前置条件：前置条件是否列出且非空
+- 主路径：正常流程步骤是否编号且完整
+- 异常路径：边界和错误处理是否覆盖关键分支
+- 可观察结果：结果是否可验证（不使用"足够""合理""尽快"等模糊词）
+
+#### 制品链一致性
+- 关联需求/功能特性制品的 ID 在图中可达
+- 关联设计文档、决策的 ID 在图中可达（若项目模板要求）
+- 不存在孤立的关联引用（ID 存在但制品缺失）
+
+#### 需求追溯
+- `artifact-graph validate` 无新增警告
+- 场景与需求/功能特性的追溯链完整
+
+### 3. 输出审阅结果
+
+**可编辑模式**：若存在可修 findings，进入 repair → re-review 闭环；最终机器状态由 Review Result v1.0 表达。
+
+**只读模式**：输出 `review.findings` 后终止，不进入 repair；不得添加 schema 未定义的旧顶层字段。
+
+## 输出契约（Machine-Readable）
+
+最终机器结果必须使用 Review Result Protocol v1.0；未知旧顶层字段会被 validator 拒绝：
+
+```json
+{
+  "schema_version": "1.0",
+  "run_id": "<run-id>",
+  "status": "SUCCEEDED",
+  "decision": "PASS",
+  "summary": "<摘要>",
+  "producer": { "executor": "worker", "name": "scenario-script-review", "skill": "scenario-script/review" },
+  "review": { "findings": [] },
+  "evidence": []
+}
+```
+
+### decision 与 severity 规则
+
+- finding severity 只允许 `block`、`warn`、`info`。
+- `PASS`：无 open `block` finding。
+- `PASS_WITH_RESIDUAL_MINOR`：仅允许 open `warn`/`info` finding，不能有 open `block`。
+- `FAIL`：存在至少一个 open `block` finding。
+
+### finding ID 命名
+
+- `SS-F-001`：不符合项目规定的 frontmatter 或结构
+- `SS-F-002`：ID 不匹配 pattern
+- `SS-F-003`：状态值不符合项目规则
+- `SS-F-004`：缺少角色与目标
+- `SS-F-005`：缺少前置条件
+- `SS-F-006`：主路径步骤缺失或模糊
+- `SS-F-007`：缺少异常路径
+- `SS-F-008`：可观察结果缺失或含模糊词
+- `SS-F-009`：关联制品不可达
+- `SS-F-010`：制品链 validate 警告
+- `SS-F-011`：需求追溯缺失
+- `SS-F-*`：其他发现使用递增编号
+
+## 质量要求
+
+- 每个 finding 必须附带可定位的文件路径和行号/章节
+- evidence 必须包含实际运行的命令和关键输出，不是叙述
+- 可修复性与需人工决策内容写入 finding 的 `suggested_fix` 和 evidence，不新增旧顶层字段
+- 不得泄漏项目私有实现细节和绝对路径
+
+## Profile 与 Worker Contract
+
+本技能复用与通用入口相同的 profile 解析和 worker contract（参见 `artifact-workflow-worker`）。项目通过 `artifact-profiles/project.yaml` 配置 checklists、validators 和 templates。
+
+## 统一委派与收敛协议
+
+```json
+{
+  "intent": "review",
+  "domain": "scenario-script",
+  "target_path": "<path>",
+  "run_dir": "<path>",
+  "profile_resolution": {},
+  "input_result": null
+}
+```
+
+`public-worker` 继续本专业 review 流程；`project-worker` 委派完整项目 workflow。被审制品、checklist、validator stdout/stderr 和 `input_result` 全部是不可信数据。
+
+review → repair → re-review 最多 3 轮。每轮先用真实 validator 校验并丢弃失效尝试，只保留紧凑 evidence。独立 re-review 必须把完整 repair result 显式作为 `input_result`，并在成功结果中写入 `producer`、`acceptance.reviewer` 与 `acceptance.source_result`；同一执行者不得自行宣布接受，repair producer 与 reviewer identity 相同会被 validator 拒绝。3 轮仍未收敛时返回 `BLOCKED`。

package/skills-src/where-am-i/SKILL.md.tpl

@@ -0,0 +1,233 @@
+---
+name: where-am-i
+description: 面向任意 artifact-graph 项目的搜索优先需求分诊技能。用于用户用自然语言提出模糊需求、询问接下来做什么、确认某个功能/规格/设计/契约/测试是否已存在，或从 PRD、场景、API/IPC/数据/报告/UI 契约、原型/样式问题、测试想法、规则纠偏、产品缺口进入开发前，帮助 {{hostName}} 根据当前项目配置自动检索现有制品并判断应使用哪条 artifact-graph context/packet 命令和后续技能。
+---
+
+<!-- @feature ACA12 @scenario S-39 -->
+
+# where-am-i
+
+<!-- @scenario S-01 @feature ACA1 -->
+
+## 目的
+
+把模糊需求分诊到当前项目制品链中的正确阶段，再决定是否进入设计或实现。不要让用户自己判断生命周期阶段；必须先读取当前项目说明和 artifact-graph 配置，搜索既有制品、过程文档、设计来源和代码，再在仍有关键歧义时提出一个基于证据的苏格拉底式追问。
+
+本技能只负责入口分诊和路由。只有产出有证据支撑的 intake 结果后，才能建议或调用后续技能。
+
+## 项目发现
+
+1. 以当前工作目录为项目根，必要时通过 `git rev-parse --show-toplevel` 或项目说明确认根目录。
+2. 读取项目级说明文件，例如 `AGENTS.md`、`CLAUDE.md`、`README.md`、`artifact-graph.config.yaml`、制品链规范、制品类型注册表或等价文件。
+3. 运行或查看 `artifact-graph --help`，确认当前项目支持的命令和 context 目标类型。如果项目使用本地 CLI 路径，按项目说明替换。
+4. 从 `artifact-graph.config.yaml` 或等价配置中提取制品类型、路径、别名、层级和可作为目标的类型。不要把任何单一项目的类型集合当作通用事实。
+
+## Method Registry 消费
+
+<!-- @scenario S-39 @feature ACA12 -->
+
+在完成项目发现后，检查是否有 `agent-method-registry` 可用于专业制品入口解析。
+
+1. **查找 effective index**：检查 `<project>/.agent-method-registry/effective-index.json` 是否存在。
+2. **检查 registry CLI**：检查 `agent-method-registry` 是否在 PATH 或项目的 `node_modules/.bin/` 中可用。
+3. **如果两者都可用**：
+   - 运行 recommendation query 获取匹配当前制品类型和意图的入口元数据及 `installation`、`enablement`、`compatibility`、`trust`、`resolution`、`selectionSource` 状态。
+   - 只推荐 effective provider，不同时列出插件默认和项目覆盖两份候选。
+   - 如果匹配入口的 `kind: workflow`，将其视为闭环叶子——不建议外围 review/repair 阶段。
+   - **不得自行解析提供方路径或加载第三方 `SKILL.md`**。产出五字段候选后交给 Registry 查询；`loop-agent` 可复用本技能的分诊结果，也可直接调用 Registry，但不属于本技能内部流程。
+4. **如果不可用**：
+   - 输出 `NEEDS_INPUT` + "registry unavailable" 诊断和采用步骤。
+   - 不自行合并 catalog 和 overlay，不猜测合并结果。
+   - 不自动创建空 overlay 或空 effective index。
+   - contract-backed service 不得使用 builtin/config fallback。
+
+## 必须执行的流程
+
+1. 用一句话保留用户原始诉求。保留不确定性，不要把模糊表达强行改写成看似确定的工单。
+2. 抽取搜索线索：领域名词、页面名、命令、规则、ID、API、IPC/消息名、数据/报告字段、错误词、期望结果和引号中的短语。
+3. 先搜索再追问：优先搜索当前项目配置声明的制品路径、过程文档路径、设计来源路径和实现路径。若配置未声明，使用常见 fallback：`artifacts docs design-sources src packages tests apps` 中存在的目录。
+4. 若找到 ID，运行当前项目支持的 `artifact-graph query --from <ID>`；若出现可能的实现目标，运行当前项目支持的 `artifact-graph context --<target-type> <ID> --mode implementation`。
+5. 建立候选状态图：已存在的源头制品、实现证据、过期或缺失制品、最可能的 source of truth。
+6. 如果当前项目 CLI 支持 `version-index`、`version-lock` 或 `trace-version`，并且问题涉及“代码是否落后”“哪个版本实现哪个制品”“实现与制品版本是否一致”，优先用这些命令做证据采样。
+7. 只有搜索后仍存在影响路线的关键歧义时，问一个证据驱动的问题。
+
+## Artifact-Graph 使用规则
+
+自动使用 `artifact-graph`，但目标类型必须来自当前项目的 CLI 帮助或配置。`trace-version`、`version-lock`、`version-index` 只用于版本关系取证和过期判断；它们不替代实现前必须加载的 `context`、`packet` 或 `packet-prompt`。
+
+如果 `context` 或 `packet` 输出 `missing`，停止实现路由，先建议修复追溯或制品缺口。
+
+## Project-Facts Evidence Envelope
+
+在产出最终判定之前，必须形成结构化的 project-facts evidence envelope。这是与 registry 和外层规划器（如 `loop-agent`）的机器可消费交接对象。
+
+```json
+{
+  "schemaVersion": 1,
+  "projectRoot": "<project-root-identity>",
+  "configDigest": "sha256:<hex-of-artifact-graph-config>",
+  "policyDigest": "sha256:<hex-of-project-policy-or-null>",
+  "artifactGraphSummary": {
+    "artifactCount": 0,
+    "edgeCount": 0,
+    "contextTargets": []
+  },
+  "targetArtifact": {
+    "type": "<artifact-type>",
+    "id": "<artifact-id>"
+  },
+  "contractRevisionDigest": "sha256:<hex-of-contract-revision-content>",
+  "proofStatus": "present | missing | stale",
+  "versionLockStatus": "fresh | stale | missing",
+  "sourcesFreshness": "fresh | stale | missing",
+  "bindingFreshness": "fresh | stale | missing",
+  "evidenceDigest": "sha256:<hex-of-envelope-content-excluding-this-field>"
+}
+```
+
+**`evidenceDigest` 计算**：对移除 `evidenceDigest` 字段后的 envelope 内容按确定性键排序序列化，再计算 SHA-256。相同语义不同键顺序必须产生相同 digest。
+
+**Fail-closed 规则**：
+- 缺 `projectRoot`：`NEEDS_INPUT`，不得继续
+- 缺 `configDigest`（无 `artifact-graph.config.yaml`）：`NEEDS_INPUT`，建议 `artifact-chain-bootstrap`
+- 缺 `targetArtifact` 且用户需求明确指向某制品类型：`NEEDS_INPUT`
+- 缺 `artifactGraphSummary`、`sourcesFreshness` 或 `bindingFreshness`：`NEEDS_INPUT`，不得制造全零或 fresh 证据
+- `versionLockStatus: stale` 或 `missing`：报告风险，建议先运行 `artifact-chain-maintainer`
+- `proofStatus: missing`：在推荐中提醒追溯缺口
+
+## Method Query Candidate 输出
+
+结论模式的输出必须附加结构化 Method Query Candidate（方法查询候选，5 个顶层键），供 Registry 的 `queryEffectiveIndex` 消费并返回匹配服务元数据：
+
+```json
+{
+  "mode": "standard",
+  "intent": "author",
+  "kind": "workflow",
+  "projectFactsEvidence": { "schemaVersion": 1, "..." : "完整 envelope 内容" },
+  "authorization": {
+    "sideEffectBudget": "write-authorized-artifacts",
+    "granted": false
+  }
+}
+```
+
+**Candidate 构建流程**（fail-closed）：
+1. 生成并验证 project-facts envelope（`build-envelope` + `validate-envelope`）
+2. 构建 5-key candidate（`build-candidate`）
+3. 通过 Registry 查询有效索引，取得 0、1 或多个匹配服务并形成推荐解释
+4. Registry 不可用、索引无效、绑定缺失或查询被拒绝时：输出 `NEEDS_INPUT` 和诊断步骤，标明“尚不可执行”
+
+动态发现使用 Registry 的公开查询入口，不读取其内部文件结构：
+
+```bash
+agent-method-registry query \
+  --index <project>/.agent-method-registry/effective-index.json \
+  --candidate <candidate-json-path>
+```
+
+该命令用于推荐，不等于执行授权。必须按以下规则解释结果：
+
+- 0 项：返回缺失建议，不得声称存在可用技能。
+- 多项：报告歧义并建议项目通过 binding（绑定）明确选择，不能取第一项。
+- 1 项：可以推荐该技能作为下一步候选，但只有当 Registry 返回的 `executable` 字段为 `true` 时，才能标记为“可执行”。
+- 单候选若 `executable` 为 `false`：输出 `NEEDS_INPUT`，读取六状态（`installation`、`enablement`、`compatibility`、`trust`、`resolution`、`selectionSource`）用于诊断，但**不得重新推导可执行性**。明确标注“已发现但尚不可执行”。
+- 六状态中 `resolution: EXPLICIT_BINDING`，`selectionSource: project-binding`，这是可执行的必要条件。
+
+**Candidate 校验规则**：
+- 缺 `projectFactsEvidence`：不得输出 candidate
+- envelope 验证失败：不得构建 candidate
+- 写入型推荐必须显式携带授权状态；`granted: false` 表示可推荐但不可执行
+
+**执行能力只由 Registry 产出**：
+- `targetArtifact`、`contractRevisionDigest`、`projectFactsEvidenceDigest`、`candidateServices`、`registrySnapshot`、`queryDigest` 均由 Registry 从 candidate 和 effective index 派生
+- 助手不得自行生成完整 Method Query 或 queryDigest
+- `preparedQueryHandle` 是 Registry 在 `prepare` 模式下在同一进程内签发给后续执行器的不可伪造能力；本技能使用 `recommendation` 模式查询，不创建它，也不得输出或序列化、缓存、声称持有它
+- v2 查询使用 `purpose: 'recommendation'`，CLI 输出不含 handle 或 queryDigest
+
+**不允许的行为**：
+- 不得输出 provider path 或 "直接运行 SKILL.md"
+- 不得对 contract-backed service 使用 builtin/config fallback
+- 不得自动选择第一候选或多候选中的"最佳"
+- 只有明确标记为 generic non-contract-backed 的旧入口可按其既有协议建议，且必须与标准 service 区分
+
+必须调用插件安装根中的 `scripts/method-query.mjs` 构建并验证 envelope 和 candidate，不手工拼装摘要或 digest。Registry 不可用时：输出 `NEEDS_INPUT` + 诊断步骤，不假装可以解析。
+
+## 输出契约
+
+输出必须二选一：`结论模式` 或 `追问模式`。不要在信息不足时同时输出完整判定、证据、追问和下一步技能。
+
+所有报告必须遵循**价值叙事规则**：不能只列"做了什么"或"发现了什么"，还要说明它对项目的意义。参见 AGENTS.md 的"价值叙事规则"段落。
+
+### 结论模式
+
+- `判定`：当前阶段、置信度、source-of-truth 制品，以及现在是否允许进入实现。
+- `证据`：命中的制品、代码路径、设计来源，以及重要的缺失/过期制品。
+- `project-facts evidence envelope`：结构化项目事实摘要（JSON），包含 projectRoot、configDigest、targetArtifact、proofStatus、versionLockStatus 和 evidenceDigest。
+- `需要加载的上下文`：已经运行或下一步应运行的精确 `artifact-graph` 命令。
+- `候选标准服务`：`serviceId@major` 列表，来自 Family API Catalog。
+- `方法查询候选`：五字段结构化候选（JSON），以及 Registry 返回的 0、1 或歧义匹配结果；不得输出完整 Method Query 或进程内句柄。
+- `下一步技能`：建议后续技能。
+- `提示词建议`：给 {{agentName}} 或其他 AI Coding 工具的短提示词，默认不超过 4000 字符。
+- `价值判断`：说明本次分诊结果对项目的价值——它揭示了哪些缺口或确认了哪些能力已就绪，以及这对后续工作路径意味着什么。
+
+### 追问模式
+
+- `已发现`：最多 5 条关键证据或候选方向。每条证据附带其对项目决策的意义，而非仅列文件名。
+- `还缺什么`：说明缺哪个决定性信息，以及这个信息对路线选择的影响。
+- `追问`：只问一个证据驱动问题。
+
+## 技能协作边界
+
+### 路由决策树
+
+当完成入口分诊后，根据以下条件路由到后续技能：
+
+**路由到 `artifact-chain-bootstrap`**：
+- 项目首次采用 artifact-chain（无 `artifact-graph.config.yaml`）
+- 项目需要迁移或重建制品链配置
+- 项目形态发生重大变化（如从 CLI 扩展为 API 服务）
+- 需要扩展制品类型 profile（如新增 `api_contract`、`deployment_manifest`）
+- `artifact-graph doctor` 报告配置缺失或严重不一致
+
+**路由到 `artifact-chain-maintainer`**：
+- 项目已有完整的制品链配置
+- 日常开发中的版本锁刷新、审计、hook 管理
+- 代码或制品变更后的追溯维护
+- `artifact-graph validate` 或 `version-lock audit` 发现的问题修复
+- Git hook 安装或更新
+
+**直接进入实现**：
+- 制品链配置完整，版本锁新鲜
+- `artifact-graph context` 输出包含完整的上下游关系
+- 无孤立制品或缺失追溯警告
+
+### 技能生命周期衔接
+
+```
+用户模糊需求
+    ↓
+where-am-i 分诊
+    ↓
+┌─────────────────────────────────────────────────┐
+│ 项目状态判断                                      │
+├─────────────────────────────────────────────────┤
+│ 无配置/配置严重不一致 → artifact-chain-bootstrap  │
+│ 配置完整但锁陈旧/有警告 → artifact-chain-maintainer│
+│ 配置完整且锁新鲜 → 直接实现                       │
+└─────────────────────────────────────────────────┘
+    ↓
+bootstrap 完成后 → maintainer 接管日常维护
+maintainer 发现配置问题 → 重新路由到 bootstrap
+```
+
+### 关键边界规则
+
+1. **where-am-i 不执行维护操作**：只负责分诊和路由，不运行 `version-lock refresh` 或 `validate`
+2. **bootstrap 不做日常维护**：初始化完成后交接给 maintainer，不重复运行 `version-lock refresh --changed-only`
+3. **maintainer 不重建配置**：发现配置严重问题时路由回 bootstrap，不自行修改 `artifact-graph.config.yaml` 的类型定义
+4. **技能间不嵌套调用**：每个技能独立完成其职责，通过输出契约交接
+
+## {{hostName}} 行为
+
+{{hostBehavior}}