docs(bridge): 默认返回 JSON 判定结果

Author: sincerely90

README.en.md

@@ -33,7 +33,7 @@
 
 **Aisee** stands for **AI-Enhanced Software Engineering**.
 
-Aisee Plugin is an AI software engineering plugin for OpenSpec workflows. It helps teams turn ambiguous ideas into reviewable requirements, UI content specifications, architecture context, OpenSpec changes, project memory, team knowledge guardrails, implementation briefs, verification checks, and archive guardrails.
+Aisee Plugin is an AI software engineering plugin for OpenSpec workflows. It helps teams turn ambiguous ideas into reviewable requirements, UI content specifications, architecture context, OpenSpec changes, project memory, team knowledge guardrails, implementation-stage JSON decisions with optional handoff briefs, verification checks, and archive guardrails.
 
 Aisee **does not replace OpenSpec**. OpenSpec remains the specification state machine and baseline source of truth. Aisee adds structured skills, project memory, team knowledge, JSON context tooling, and engineering handoff rules around OpenSpec.
 
@@ -42,7 +42,7 @@ It is especially relevant for maintainers who want Codex and other coding agents
 - durable requirements and specifications instead of transient chat context;
 - machine-readable context packs and schema packs for implementation, review, and verification;
 - OpenSpec change planning that turns vague intent into reviewable deliverables;
-- implementation briefs that help maintainers and contributors hand off PR-ready work;
+- machine-readable implementation-stage decisions with optional handoff briefs that help maintainers and contributors hand off PR-ready work;
 - verification evidence and archive gates that close the loop before AI-assisted changes are treated as complete.
 
 ## OpenSpec Boundary
@@ -58,7 +58,7 @@ Codex can write, review, and fix code, but the results are less reliable when a
 Aisee supplies that workflow layer:
 
 - it turns intent into durable OpenSpec changes, planning docs, and reusable project memory;
-- it helps maintainers prepare implementation briefs that are easier to review and hand off;
+- it helps maintainers first reduce implementation entry into reusable JSON decisions, and only turn them into human-readable handoff briefs when needed;
 - it lets Codex read against the same context boundaries across implementation, review, verification, and archive;
 - it gives open-source projects clearer engineering constraints for AI-assisted contribution flows.
 
@@ -352,7 +352,7 @@ For existing projects, use `aisee:spec-migrate` to derive OpenSpec baseline spec
 | `aisee:architecture` | Capture software architecture context, technical constraints, reusable capabilities, and artifact hints. |
 | `aisee:change-plan` | Plan independent OpenSpec changes and choose schemas. |
 | `aisee-schema-pack` | Provide and maintain OpenSpec schema packs through the marketplace plugin. |
-| `aisee:implementation-bridge` | Produce implementation briefs and context pack summaries for a single change. |
+| `aisee:implementation-bridge` | Return implementation-stage JSON decisions for a single change by default, and generate handoff briefs only when explicitly needed. |
 | `aisee:verify` | Diagnose artifact, task, source-map, numbering, and evidence gaps. |
 | `aisee:archive-guard` | Provide the final recommendation before `openspec archive`. |
 | `aisee:spec-migrate` | Build OpenSpec baseline specs for existing projects. |

README.md

@@ -33,7 +33,7 @@
 
 **Aisee** 是 **AI-Enhanced Software Engineering** 的缩写。
 
-Aisee Plugin 是一个面向 OpenSpec 工作流的 AI 软件工程插件。它帮助团队把模糊想法整理成可审查的需求、UI 内容规格、技术架构上下文、OpenSpec changes、项目记忆、团队知识 guardrails、实现交接 brief、验证检查和归档门禁。
+Aisee Plugin 是一个面向 OpenSpec 工作流的 AI 软件工程插件。它帮助团队把模糊想法整理成可审查的需求、UI 内容规格、技术架构上下文、OpenSpec changes、项目记忆、团队知识 guardrails、实现阶段 JSON 判定与按需交接、验证检查和归档门禁。
 
 Aisee **不替代 OpenSpec**。OpenSpec 仍然是规范状态机和 baseline 事实源。Aisee 在 OpenSpec 周围补充结构化 skills、project memory、team knowledge、JSON context tooling 和工程交接规则。
 
@@ -42,7 +42,7 @@ Aisee **不替代 OpenSpec**。OpenSpec 仍然是规范状态机和 baseline 事
 - 用可持久复用的需求与规范，替代只存在于聊天记录里的临时上下文；
 - 用机器可读的 context pack 和 schema pack，为实现、审查和验证提供稳定输入；
 - 用 OpenSpec change planning 把模糊意图拆成可审查、可交付的变更；
-- 用 implementation brief 帮助 maintainer 和 contributor 做 PR / review-ready 交接；
+- 用机器可读的实现阶段 JSON 判定和按需 handoff，帮助 maintainer 和 contributor 做 PR / review-ready 交接；
 - 用 verification evidence 和 archive gates 收口 AI 辅助开发后的验收与归档流程。
 
 ## OpenSpec Boundary
@@ -58,7 +58,7 @@ Codex 能写代码、审代码、修 bug，但在仓库没有显式需求、稳
 Aisee 把这些材料前置为可复用的工作流层：
 
 - 让需求和工程约束以 OpenSpec change、planning docs 和 project memory 的形式持久存在；
-- 帮助维护者把实现意图整理成更容易 review 的 implementation brief；
+- 帮助维护者把实现入口先收敛为可复用的 JSON 判定，并在必要时再整理成人读 handoff；
 - 让 Codex 在实现、review、verify 和 archive 之间读取同一套上下文边界；
 - 为开源仓库提供更明确的 AI 协作约束，降低 maintainer 反复补充背景的成本。
 
@@ -353,7 +353,7 @@ quick-fix / quick-research / 其它轻量 schema
 | `aisee:architecture` | 捕获软件架构上下文、技术约束、可复用能力和 artifact hints。 |
 | `aisee:change-plan` | 规划独立 OpenSpec changes 并选择 schema。 |
 | `aisee-schema-pack` | 通过 marketplace plugin 提供并维护 OpenSpec schema packs。 |
-| `aisee:implementation-bridge` | 生成单个 change 的实现交接 brief 和 context pack 摘要。 |
+| `aisee:implementation-bridge` | 默认返回单个 change 的实现阶段 JSON 判定；仅在明确需要时生成实现交接 brief。 |
 | `aisee:spec-migrate` | 为已有项目整理 OpenSpec baseline specs。 |
 | `aisee:design-spec` | 生成设计规范，不重复 UI 内容规格。 |
 | `aisee:design-assets` | 生成或提取视觉参考和设计素材。 |

docs/workflow.en.md

@@ -155,7 +155,7 @@ aisee context pack --change <change> --for ce-work --knowledge --json
 
 Knowledge matches are reminders only. They do not change the current change's specification source and should not be copied into durable artifacts.
 
-Then use `aisee:implementation-bridge` to produce an Implementation Brief. The brief is an execution index:
+Then use `aisee:implementation-bridge` to return the default JSON decision result. It should return routing and guardrails only; generate an Implementation Brief only when a human-readable handoff is explicitly needed. The brief is an execution index:
 
 - current change and schema;
 - read-first artifacts;

docs/workflow.md

@@ -155,7 +155,7 @@ aisee context pack --change <change> --for ce-work --knowledge --json
 
 Knowledge matches 只作为提醒，不改变当前 change 的规范事实源，也不应复制进长期 artifacts。
 
-然后使用 `aisee:implementation-bridge` 输出 Implementation Brief。Brief 只做执行索引：
+然后使用 `aisee:implementation-bridge` 输出默认的 JSON 判定结果。它应只返回执行路由和 guardrails；只有在明确需要人读交接时，才生成 Implementation Brief。Brief 只做执行索引：
 
 - 当前 change 和 schema。
 - 必读 artifacts。

plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aisee:implementation-bridge
-description: 将单个已确认且已 authored 的 OpenSpec change 转成给 Compound Engineering 执行的最小工程上下文。用于进入 ce-work 前读取 context pack 和当前 change artifacts，输出一次性的 Implementation Brief / context pack 摘要，明确当前 schema、事实源、读取顺序、schema/domain artifacts、apply tracks、source-map 适用性、禁止越界项、验证要求和 ce-plan 是否需要。它不创建平行任务清单，不默认落地新文档，不替代 ce-work，不修补缺失 artifacts。
+description: 将单个已确认且已 authored 的 OpenSpec change 转成给 Compound Engineering 执行的最小工程上下文。用于进入 ce-work 前读取 context pack 和当前 change artifacts，默认只输出 JSON 判定结果与下一步路由结论；仅在用户明确要求人读交接或保存 handoff 时才生成 Implementation Brief。它不创建平行任务清单，不默认落地新文档，不替代 ce-work，不修补缺失 artifacts。
 ---
 
 # aisee:implementation-bridge
@@ -26,7 +26,8 @@ description: 将单个已确认且已 authored 的 OpenSpec change 转成给 Com
 - 读取单个 OpenSpec change。
 - 读取 `aisee context pack --change <change> --for ce-work --json` 和当前 change artifacts。
 - 这些读取都是只读状态检查，由 skill 自动执行；不要求用户手工跑常规命令。
-- 输出给 `ce-work` 的一次性 Implementation Brief / context pack 摘要。
+- 默认输出给 `ce-work` 的 JSON 判定结果与下一步路由结论。
+- 仅在用户明确要求人读交接、保存 handoff 或分批执行索引时，生成人类可读的 Implementation Brief。
 - 明确事实源、读取顺序、执行规则、禁止越界项和验证要求。
 - 判断是否需要先用 `ce-plan` 细化，并要求有效结论回写当前 schema 的 apply tracks；只有 schema 生成 `source-map.md` 时才回写 source-map。
 - 识别实现后是否建议 Tier 2 code review，并把审查代理授权提示写入 Brief。
@@ -53,13 +54,25 @@ description: 将单个已确认且已 authored 的 OpenSpec change 转成给 Com
 - 如果实现需要的文件没有被当前 change 或 context pack 指到，先把它作为 `[IMPLEMENTATION-PATH-GAP]`；schema 生成 `source-map.md` 时回写 source-map，否则回写当前 schema 的 apply tracks 或主 artifact。
 - 未被当前 change 纳入范围的问题，只能进入 Brief 的 `Blockers and Assumptions`、`Follow-up candidates` 或验证风险；不得直接变成当前 change 的实现任务。
 
-## 产物形态
+## 默认产物
 
-Implementation Brief 是实现阶段的交接输出，不是新的规范事实源：
+默认只输出 JSON 判定结果，不默认展开人读摘要。结果应优先来自 `aisee context pack --change <change> --for ce-work --json`，至少覆盖：
 
-- 默认作为当前会话输出，或由 `aisee context pack --change <change> --for ce-work --json` 返回给执行方。
-- 不默认写入 `openspec/changes/<change>/implementation-brief.md` 或其他长期文档。
-- 如果用户明确要求保存，或当前 change 内容过大需要分批交接，优先写入 `aisee/cache/implementation-bridge/<change>/brief-part-NN.md`；如用户指定写入 change 目录，只能标注为 generated handoff / cache，且正文必须指向当前 schema artifacts 和 apply tracks；不得承载这些 artifact 中没有的新事实。
+- 当前 change / schema / status。
+- 是否存在 blocker 或关键风险。
+- `requires_ce_plan` 与 `ce_plan_reason`。
+- `allowed_paths`、`code_paths`、`test_paths`。
+- `apply_tracks` / 回写位置。
+- 推荐下一步：`ce-work`、`ce-plan`、`aisee:change-author` 或停止。
+
+默认不写入 `openspec/changes/<change>/implementation-brief.md` 或其他长期文档，也不默认在会话里展开 `Implementation Brief` 各章节。
+
+## Brief 产物形态
+
+Implementation Brief 是按需的人读交接输出，不是新的规范事实源：
+
+- 只有用户明确要求“生成 Brief / 交接摘要 / 保存 handoff”，或当前 change 内容过大需要分批交接时，才生成。
+- 如果用户明确要求保存，优先写入 `aisee/cache/implementation-bridge/<change>/brief-part-NN.md`；如用户指定写入 change 目录，只能标注为 generated handoff / cache，且正文必须指向当前 schema artifacts 和 apply tracks；不得承载这些 artifact 中没有的新事实。
 - 分批交接时必须先生成 `brief-index.md`，再生成 `brief-part-NN.md`；index 使用 `references/brief-index-template.md`，part 使用 `references/brief-template.md`。
 - 发现 Brief 与 OpenSpec artifacts 不一致时，以 OpenSpec artifacts 为准，并回写对应 artifact，而不是修补 Brief。
 
@@ -121,7 +134,16 @@ aisee context pack --change <change> --for ce-work --json
 7. 当前 schema 的 apply tracks，通常是 `tasks.md`
 8. context pack 明确给出的相关代码路径、测试路径、路由、API、模型和配置
 
-## Implementation Brief 输出必须包含
+## 默认 JSON 判定结果应包含
+
+- 当前 change / schema / status。
+- blocker / risk / gap 判定。
+- `requires_ce_plan`、`ce_plan_reason`、`reusable_workflow_candidates`。
+- `allowed_paths`、`code_paths`、`test_paths`、`unmapped_reference_paths`。
+- `apply_tracks`、completion gate、建议回写位置。
+- 推荐下一步及停止条件。
+
+## 当明确要求生成人读 Brief 时，输出必须包含
 
 ```md
 # Implementation Brief

plugins/aisee-plugin/skills/aisee-implementation-bridge/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "aisee:implementation-bridge"
   short_description: "把已 authored 的 OpenSpec change 转成交给 CE 的最小工程上下文"
-  default_prompt: "使用 $aisee:implementation-bridge 读取当前 change 的 context pack 和 artifacts，生成进入 ce-work 前的最小实现交接摘要。"
+  default_prompt: "使用 $aisee:implementation-bridge 读取当前 change 的 context pack 和 artifacts，默认只输出进入 ce-work 前的最小 JSON 判定结果与下一步路由结论；仅在用户明确要求 Brief / handoff 时才生成人读摘要。"

plugins/aisee-plugin/skills/aisee-implementation-bridge/evals/evals.json

@@ -11,32 +11,33 @@
       "id": "implementation-bridge-001",
       "name": "handoff-authored-change-to-ce-work",
       "scenario": "implementation-handoff",
-      "prompt": "change 已 authored，context pack 无 blocker。帮我给 ce-work 生成一个最小 Implementation Brief，告诉它该读什么、能改哪些路径、是否需要 ce-plan。",
+      "prompt": "change 已 authored，context pack 无 blocker。帮我判断能否进入 ce-work，并只给出最小 JSON 判定结果：该读什么、能改哪些路径、是否需要 ce-plan。",
       "context": {
         "files": [],
         "assumptions": [
           "当前 change 已存在 context pack。"
         ]
       },
-      "expected_output": "应优先消费 context pack 和 gaps，生成一次性实现交接摘要；明确 allowed paths、verification、review recommendation 和 ce-plan 是否需要；不得创建平行长期任务清单或直接写代码。",
+      "expected_output": "应优先消费 context pack 和 gaps，默认只输出一次性的 JSON 判定结果与下一步路由；明确 allowed paths、verification、review recommendation 和 ce-plan 是否需要；不得创建平行长期任务清单、默认展开 Brief 正文或直接写代码。",
       "expected_outputs": [
         "先读当前 change 的机器可读上下文。",
-        "输出 Implementation Brief 关键栏位。",
+        "输出 JSON 判定关键字段。",
         "当 requires_ce_plan=false 时直接推荐 ce-work。"
       ],
       "must_ask": [],
       "must_include": [
-        "read first",
+        "requires_ce_plan",
         "allowed paths",
         "verification",
         "review recommendation"
       ],
       "must_not": [
         "不得创建平行长期任务清单。",
+        "不得默认输出完整 Implementation Brief。",
         "不得替代 ce-work、ce-code-review 或 aisee:verify。"
       ],
       "quality_checks": [
-        "Brief 只做交接索引，不复制全部 artifacts 正文。",
+        "默认输出应保持为 JSON 判定，不展开整段人读摘要。",
         "scope 和写回位置必须来自当前 change。"
       ],
       "fact_source_constraints": [