@aipper/aiws-spec 0.0.31 → 0.0.33

package/templates/workspace/.agents/skills/ws-intake/SKILL.md

@@ -26,6 +26,8 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
 
 必需输出：
 - `Intake file:` 实际写入的 `plan/*.intake.md`
+- `Deep Interview:` 9 维分析：Why/非目标/影响面/假设/替代方案/约束/优先级/成功度量/风险
+- `Codebase Knowns:` 来自代码库的已知信息（通过 explore 已确认的事实、模式、配置值等，标注信息来源路径）
 - `Current question:` 当前正在处理的问题
 - `Open Questions:` 尚未冻结的问题列表
 - `Frozen Decisions:` 已冻结结论
@@ -44,37 +46,54 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`，读取真值文件并输出约束摘要。
 2) 读取当前任务描述；若存在最新 `plan/*.intake.md`，先读取其中的：
+   - `Deep Interview`
    - `Open Questions`
    - `Resolved Questions`
    - `Frozen Decisions`
    - `Draft Scope`
    - `Draft Verify`
-3) 初始化或续写问题队列：
+3) **Deep Interview 层**：在拆解问题前先收集高维信息：
+   a) **Why 探询**：问"为什么要做？不做会怎样？谁提出的？什么场景？"
+   b) **非目标（Non-goals）**：显式记录什么不在范围内，需用户确认
+   c) **影响面（Stakeholders）**：识别受影响的用户、模块、团队
+   d) **假设显式化**：列出隐含假设，请用户确认
+   e) **替代方案**：问"考虑过其他方案吗？为什么选这个？"
+   f) **约束挑战**：对每条约束问"如果不存在会怎样？"——区分硬约束与自设约束
+   g) **优先级**：Must-have / Should-have / Nice-to-have
+   h) **成功度量**：问"上线后怎么判断成功？"——量化指标，无法量化则记入风险
+   i) **风险预判**：识别 3-5 个最关键风险
+   j) 结果写入 intake 草案的 `Deep Interview` 小节
+4) **探码后问**：在对每个 Open Question 提问或沟通前，先用 `explore` 检索代码库中是否已有足够信息回答该问题。探查到的已知信息记录在 intake 草案中（见输出要求的 Codebase Knowns），不再问用户。记录每个问题属于以下哪一类：
+   - `codebase: answered` — 代码库已可回答，跳过提问
+   - `codebase: partial` — 代码库有部分信息，补充提问未覆盖的部分
+   - `user: required` — 必须问用户
+4) 初始化或续写问题队列：
    - 把当前任务拆成 `N` 条待决问题
    - 每条问题都要写成一句明确的决策句，而不是模糊话题
-   - 状态只允许：`open` / `in_discussion` / `frozen` / `deferred`
-4) 选择唯一的当前问题：
+    - 状态只允许：`open` / `in_discussion` / `frozen` / `deferred`
+5) 选择唯一的当前问题：
    - 优先取已有 `in_discussion`
-   - 否则取最影响 `Goal / Scope / Verify / Binding` 的 `open`
-5) 对当前问题输出并沟通：
+    - 否则取最影响 `Goal / Scope / Verify / Binding` 的 `open`
+6) 对当前问题输出并沟通：
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
-   - `Exit condition:` 这条问题在什么条件下算谈完
-6) 只推进当前问题：
+    - `Exit condition:` 这条问题在什么条件下算谈完
+7) 只推进当前问题：
    - 允许围绕这 1 条问题多轮问答
    - 若用户回答引出新问题：加入 `Open Questions`
    - 若当前问题已经有明确结论：标记为 `frozen`
-   - 若当前问题故意留到后面：标记为 `deferred`
-7) 每次落盘 `plan/<timestamp>-<slug>.intake.md`，至少包含：
+    - 若当前问题故意留到后面：标记为 `deferred`
+8) 每次落盘 `plan/<timestamp>-<slug>.intake.md`，至少包含：
+   - `Deep Interview`
    - `Context`
    - `Open Questions`
    - `Resolved Questions`
    - `Frozen Decisions`
    - `Draft Scope`
    - `Draft Verify`
-   - `Ready for ws-plan: yes/no`
-8) 判断是否可以移交给 `$ws-plan`：
+    - `Ready for ws-plan: yes/no`
+9) 判断是否可以移交给 `$ws-plan`：
    - 若仍有关键问题未冻结：`Ready for ws-plan: no`，`Next: 继续 $ws-intake`
    - 若关键问题已冻结，剩余仅是实现细节或已标记 `deferred`：`Ready for ws-plan: yes`，`Next: $ws-plan`
 

package/templates/workspace/.agents/skills/ws-preflight/SKILL.md

@@ -31,9 +31,10 @@ description: 预检（提交前快速检查与建议）
 - 使用者已经知道当前仓库能否继续进入后续阶段，以及必须遵守的约束与下一步入口。
 
 执行步骤（强制）：
-1) 定位项目根目录：
-   - 优先：`git rev-parse --show-toplevel`
-   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+1) 定位项目根目录（submodule 感知）：
+   - 优先：`git rev-parse --show-superproject-working-tree`（若当前在 submodule 内则返回 superproject 根）
+   - 若为空（不在 submodule 内）：`git rev-parse --show-toplevel`
+   - 若两者都失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
 2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.agents/skills/ws-req-review/SKILL.md

@@ -8,7 +8,7 @@ description: 需求评审（对齐真值与验收）
 目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+1) 定位项目根目录：先尝试 `git rev-parse --show-superproject-working-tree`（submodule 感知上溯到 superproject 根）；若为空再用 `git rev-parse --show-toplevel`。都失败则停止并让用户确认根目录。
 2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.agents/skills/ws-research/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ws-research
+description: 使用时机：需要技术调研、定位影响面、收集实现信息但不直接改代码时。触发词：调研、研究、research、分析依赖、影响面、技术方案。注意：产物只落盘 changes/<id>/analysis/，不修改业务文件。
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在正式实现前，对不明确的技术问题做只读调研，并把结论落盘为可追溯的分析产物。
+
+定位：
+- ws-dev / ws-plan 的辅助入口，不是独立 workflow stage。
+- 只读探索代码库、外部文档或依赖关系，不直接修改业务文件。
+- 若分析过程中发现需要改代码，必须退出本 Skill 并回到 ws-dev 或 ws-plan。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前绑定到 `Req_ID` 或 `Problem_ID` 的 change 上下文
+- 明确的调研问题清单
+
+必需输出：
+- 分析报告落盘：`changes/<id>/analysis/<timestamp>-research.md`
+- 报告中必须包含：
+  - 调研问题与结论
+  - 信息来源（文件路径/外部文档链接）
+  - 不确定项与风险标记
+  - 对后续实现的建议或阻断项
+- `Next:` 指向 ws-dev、ws-plan 或 ws-review
+
+阻断条件：
+- 没有明确的调研问题
+- 当前不在 change 上下文中
+- 调研过程中发现需要写代码（应回到 ws-dev）
+- 调研深度超出本次 change scope（应记录原因并回到 ws-plan 更新范围）
+
+完成判定：
+- 分析报告已落盘到 `changes/<id>/analysis/`
+- 报告中问题与结论一一对应
+- `Next` 已给出明确路由
+
+步骤（建议）：
+1) 先读取真值文件，确认 change 上下文与调研问题
+2) 只读探索相关代码库区域：
+   - 用搜索工具定位关键文件/模块
+   - 阅读相关代码片段
+   - 必要时查阅外部文档
+3) 汇总发现，标注不确定项：
+   - 对每个问题给出结论或待确认标记
+   - 标明信息来源（文件路径/行号/外部链接）
+4) 落盘分析报告到 `changes/<id>/analysis/<timestamp>-research.md`
+5) 回到主流程：`$ws-dev` 或 `$ws-plan`
+
+安全：
+- 不修改任何业务文件
+- 不写入 secrets
+- 不执行破坏性命令
+- 不确定的结论必须显式标注

package/templates/workspace/.agents/skills/ws-review/SKILL.md

@@ -31,7 +31,7 @@ description: 评审（提交前审计与证据落盘）
 - 审计证据已落盘，主要风险和下一步已明确，可作为 commit/deliver 前置输入。
 
 步骤（建议）：
-1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+1) 先做 preflight：定位项目根目录（submodule 感知：若在 submodule 内自动上溯到 superproject 根），读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
 2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据

package/templates/workspace/.aiws/tools/ws_change_check.py

@@ -323,6 +323,13 @@ def extract_first_id(labels: List[str], text: str) -> str:
     return ""
 
 
+def normalize_optional_id(value: str) -> str:
+    normalized = (value or "").strip()
+    if normalized.upper() in {"N/A", "NA", "NONE", "NULL", "-"}:
+        return ""
+    return normalized
+
+
 def split_declared_values(value: str) -> List[str]:
     parts = re.split(r"[,;\n]+", value or "")
     out: List[str] = []
@@ -910,8 +917,8 @@ def validate_change(
             warnings.append("proposal.md does not reference AI_WORKSPACE.md (recommended)")
 
         change_id_decl = extract_id("Change_ID", t)
-        req_id = extract_id("Req_ID", t)
-        prob_id = extract_id("Problem_ID", t)
+        req_id = normalize_optional_id(extract_id("Req_ID", t))
+        prob_id = normalize_optional_id(extract_id("Problem_ID", t))
         contract_row_decl = extract_first_id(["Contract_Row", "Contract_Row(s)"], t)
         plan_file_decl = extract_first_id(["Plan_File", "Plan file"], t)
         evidence_path_decl = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], t)
@@ -1009,8 +1016,8 @@ def validate_change(
                 else:
                     plan_text = read_text(plan_abs)
                     plan_change_id = extract_id("Change_ID", plan_text)
-                    plan_req_id = extract_id("Req_ID", plan_text)
-                    plan_prob_id = extract_id("Problem_ID", plan_text)
+                    plan_req_id = normalize_optional_id(extract_id("Req_ID", plan_text))
+                    plan_prob_id = normalize_optional_id(extract_id("Problem_ID", plan_text))
                     plan_contract_row = extract_first_id(["Contract_Row", "Contract_Row(s)"], plan_text)
                     plan_file_from_plan = extract_first_id(["Plan_File", "Plan file"], plan_text)
                     plan_evidence_path = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], plan_text)

package/templates/workspace/.claude/commands/ws-goal.md

@@ -0,0 +1,34 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-goal -->
+# ws goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在 AIWS 约束下完成一个目标导向的自主执行闭环。
+- 启动时自动恢复未完成的 goal。
+
+执行建议：
+0) 检查 `.aiws/goals/` 目录：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行。
+1) 先运行 `/ws-preflight` 对齐真值文件（`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+2) 接受用户输入的 goal objective。
+3) 按 `ws-goal-contract.md` 的目标模板写入 `.aiws/goals/<goal-id>.md` 工件文件。
+4) 输出 completion audit checklist（含验真步骤）。
+5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
+   a) 简单（≤5 文件、配置/doc 为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
+   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线，完成后更新 goal status=complete
+   c) 路由决策记入 goal 文件 Audit Trail
+6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 ws-dev
+7) 每轮结束后自动执行 completion audit，确认目标是否完成。
+8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
+   a) Review 检查（按改动类型）：
+      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
+      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
+      - 混合类：以上两种合并
+   b) 简单路径：git add → commit → push，更新 goal status=complete
+   c) 复杂路径：走 ws-commit → ws-finish → archive change，更新 goal status=complete
+   d) 不通过：记录 blocker → 继续 fix 循环
+<!-- AIWS_MANAGED_END:claude:ws-goal -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/skills/ws-intake/SKILL.md

@@ -10,22 +10,44 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
 - 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
 - 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
+## Deep Interview 层（前置探询）
+
+在逐题澄清前，先做一轮 Deep Interview 收集高维信息：
+
+1. **Why 探询**：问"为什么要做？不做会怎样？谁提出的？什么场景？"——理解动机，追溯 trigger。
+2. **非目标（Non-goals）**：显式记录什么不在范围内，防止 scope creep。需用户确认。
+3. **影响面（Stakeholders）**：识别受影响的用户、模块、团队。
+4. **假设显式化**：列出隐含假设，逐条请用户确认。
+5. **替代方案**：问"考虑过其他方案吗？为什么选这个？"未探索则标记为风险。
+6. **约束挑战**：对每条约束问"如果不存在会怎样？"——区分硬约束与自设约束。
+7. **优先级**：Must-have / Should-have / Nice-to-have，明确 scope 底线。
+8. **成功度量**：问"上线后怎么判断成功？"——量化指标，无法量化则记入风险。
+9. **风险预判**：识别 3-5 个最关键风险，写入 intake 草案。
+
+输出：以上 9 项归入 intake 草案的 `Deep Interview` 小节。
+
 执行要求：
 1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
 3) 把当前任务拆成 `Open Questions`，状态只允许 `open / in_discussion / frozen / deferred`。
-4) 每次只推进 1 个当前问题，并显式输出：
+4) **探码后问**：在对每个 Open Question 提问或沟通前，先用 `explore` 检索代码库中是否已有足够信息回答该问题。探查到的已知信息记录在 intake 草案中，不再问用户。标记每个问题的信息来源：
+   - `codebase: answered` — 代码库已可回答，跳过提问
+   - `codebase: partial` — 代码库有部分信息，补充提问未覆盖的部分
+   - `user: required` — 必须问用户
+5) 每次只推进 1 个当前问题，并显式输出：
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
    - `Exit condition:`
-5) 当前问题在没有被标记成 `frozen` 或 `deferred` 前，不进入下一题。
-6) 每轮都要把 intake 草案写盘，至少包含：
+6) 当前问题在没有被标记成 `frozen` 或 `deferred` 前，不进入下一题。
+7) 每轮都要把 intake 草案写盘，至少包含：
+   - `Deep Interview` — 9 维分析：Why/非目标/影响面/假设/替代方案/约束/优先级/成功度量/风险
    - `Context`
+   - `Codebase Knowns` — 来自代码库的已知信息：通过 explore 已确认的事实、现有模式、配置值等。标注信息来源路径。
    - `Open Questions`
    - `Resolved Questions`
    - `Frozen Decisions`
    - `Draft Scope`
    - `Draft Verify`
    - `Ready for ws-plan: yes/no`
-7) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。
+8) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。

package/templates/workspace/.opencode/command/ws-goal.md

@@ -0,0 +1,39 @@
+---
+description: 目标协议：设定可审计的 goal 目标并执行完成闭环
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-goal -->
+# ws goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件，驱动完成闭环。
+
+前置条件：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+
+执行流程：
+0) 检查 `.aiws/goals/` 目录：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+4) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
+5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
+   a) 简单（≤5 文件、配置/doc/规范为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
+   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线（ws-plan → ws-dev → review → ws-commit → ws-finish），完成后更新 goal status=complete
+   c) 将路由决策写入 goal 文件 Audit Trail
+6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 `ws-dev`
+7) 每轮 execution 结束后执行 completion audit，比对 checklist 判断 goal 是否达成；未达成则继续下一轮。
+8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
+   a) Review 检查（按改动类型）：
+      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
+      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
+      - 混合类：以上两种合并
+   b) 简单路径：`git add` 目标产出文件 → `git commit -m "goal(<goal-id>): <objective 摘要>"` → `git push` → 更新 goal status=complete
+   c) 复杂路径：走 `ws-commit` → `ws-finish` → archive change → 更新 goal status=complete
+   d) 不通过：记录 blocker → 继续 fix 循环
+<!-- AIWS_MANAGED_END:opencode:ws-goal -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-preflight.md

@@ -9,9 +9,10 @@ description: 预检：读取真值文件并输出约束摘要
 目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：
-   - 优先：`git rev-parse --show-toplevel`
-   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+1) 定位项目根目录（submodule 感知）：
+   - 优先：`git rev-parse --show-superproject-working-tree`（submodule 内上溯到 superproject 根）
+   - 若为空：`git rev-parse --show-toplevel`
+   - 若两者都失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
 2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.opencode/command/ws-req-review.md

@@ -9,7 +9,7 @@ description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
 目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+1) 定位项目根目录：先尝试 `git rev-parse --show-superproject-working-tree`（submodule 感知上溯）；若为空再用 `git rev-parse --show-toplevel`。都失败则停止并让用户确认根目录。
 2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.opencode/commands/ws-preflight.md

@@ -9,9 +9,10 @@ description: 预检：读取真值文件并输出约束摘要
 目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：
-   - 优先：`git rev-parse --show-toplevel`
-   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+1) 定位项目根目录（submodule 感知）：
+   - 优先：`git rev-parse --show-superproject-working-tree`（submodule 内上溯到 superproject 根）
+   - 若为空：`git rev-parse --show-toplevel`
+   - 若两者都失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
 2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.opencode/commands/ws-req-review.md

@@ -9,7 +9,7 @@ description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
 目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+1) 定位项目根目录：先尝试 `git rev-parse --show-superproject-working-tree`（submodule 感知上溯）；若为空再用 `git rev-parse --show-toplevel`。都失败则停止并让用户确认根目录。
 2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.opencode/lib/aiws-context.js

@@ -833,10 +833,44 @@ Read and follow the context below.
 
   const activeChange = ctx.getActiveChange()
   if (activeChange) {
-    const phaseSummary = ctx.getPhaseSummary(activeChange.id)
-    parts.push("<change-context>")
-    parts.push(phaseSummary)
-    parts.push("</change-context>")
+    // Prefer STATE.md (derived from journal by aiws change state --write)
+    let stateContent = ""
+    try {
+      const statePath = join(ctx.directory, ".aiws", "changes", activeChange.id, "STATE.md")
+      if (existsSync(statePath)) {
+        stateContent = readFileSync(statePath, "utf8")
+      }
+    } catch {
+      // STATE.md not available, fall back to phase summary
+    }
+
+    if (stateContent) {
+      parts.push("<change-state-state-md>")
+      parts.push("## Current Change State (from STATE.md)")
+      parts.push(stateContent.trimEnd())
+      parts.push("</change-state-state-md>")
+    } else {
+      const phaseSummary = ctx.getPhaseSummary(activeChange.id)
+      parts.push("<change-context>")
+      parts.push(phaseSummary)
+      parts.push("</change-context>")
+    }
+
+    // .ws-change.json baseline
+    try {
+      const wsChangePath = join(ctx.directory, ".aiws", "changes", activeChange.id, ".ws-change.json")
+      if (existsSync(wsChangePath)) {
+        const wsChangeRaw = readFileSync(wsChangePath, "utf8")
+        const wsChange = JSON.parse(wsChangeRaw)
+        parts.push("<change-baseline>")
+        parts.push("## Change Baseline (.ws-change.json)")
+        parts.push(`Base Branch: ${wsChange.base_branch || "unknown"}`)
+        parts.push(`Template ID: ${wsChange.template_id || "unknown"}`)
+        parts.push("</change-baseline>")
+      }
+    } catch {
+      // .ws-change.json not available
+    }
 
     // Continuation resume recommendation
     try {

package/templates/workspace/.opencode/oh-my-opencode.json.example

@@ -55,12 +55,17 @@
           "git diff"
         ],
         "write_allow_paths": [
+          ".aiws/tmp/",
+          ".aiws/changes/*/analysis/",
+          ".aiws/changes/*/review/",
+          ".aiws/changes/*/evidence/",
           ".agentdocs/tmp/",
           "changes/*/analysis/",
           "changes/*/review/",
           "changes/*/evidence/"
         ],
         "deny_paths": [
+          ".aiws/secrets/",
           "secrets/",
           ".env*"
         ],

package/templates/workspace/.opencode/skills/ws-intake/SKILL.md

@@ -10,6 +10,47 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 - 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
 - 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
+## Deep Interview 层（前置探询）
+
+在逐题澄清前，先做一轮 Deep Interview 收集高维信息：
+
+### 1. Why 探询
+先问"为什么要做这个？背后的业务/用户价值是什么？"——理解动机后再谈方案。延伸探询：
+- "如果不做这个，会有什么后果？"（量化不做的代价，确认 urgency）
+- "这个需求最早是谁提出的？在什么场景下触发的？"（追溯原始 trigger，避免需求被转述变形）
+
+### 2. 非目标（Non-goals）
+显式记录什么不在本次范围内——防止 scope creep 和后续争论。
+例如："这次不做用户权限管理，只做内容展示层""这个版本不做国际化"。
+非目标与目标同等重要，需用户确认后写入 intake 草案。
+
+### 3. 影响面（Stakeholders）
+识别这个改动会影响谁：
+- 终端用户（使用行为是否会变？）
+- 其他模块或系统（API 耦合、数据依赖）
+- 其他团队（是否需要跨团队协调？谁需要参与评审？）
+
+### 4. 假设显式化
+从当前理解中识别隐含假设，逐条列出并请用户确认。例如：你假设了用户已登录/有权限；你假设了数据规模不超过 X；你假设了这个功能只有 Y 场景用到。
+
+### 5. 替代方案
+在选定方案前，先问"是否考虑过其他方案？为什么选了当前这个？"——记录已探明的替代路径和淘汰理由。
+如果用户明确没考虑过替代方案，在 intake 草案中标记 `Alternatives not explored` 作为风险项。
+
+### 6. 约束挑战
+对每条约束问"如果这条约束不存在会怎样？"——区分硬约束（不可变）和自设约束（可协商）。
+
+### 7. 优先级
+Must-have / Should-have / Nice-to-have 三层分类，明确 scope 底线。
+
+### 8. 成功度量
+不仅仅是"验收标准通过"，更要问"这个功能上线后，怎么判断它成功了？"——量化指标（DAU、转化率、响应时间、错误率等）。如果无法量化则记入风险。
+
+### 9. 风险预判
+识别 3-5 个最关键风险（技术方案、时间窗口、外部依赖、安全合规），写入 intake 草案。
+
+输出：以上 9 项归入 intake 草案的 `Deep Interview` 小节。
+
 ## 发散-收敛两子阶段
 
 当需求模糊、方向不明确时，intake 分两子阶段推进：
@@ -18,6 +59,12 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 - 目标：快速探索 2-3 个可能方向，不深入任何单一方向
 - 输出：每个方向的 1-2 段摘要 + 关键风险 + 依赖
 - 时限：不超过 3 轮对话
+- **探码前问**：在向用户提问前，先使用 `explore` agent 探查代码库中是否已有答案。需要探查的维度包括：
+  - 现有配置文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`package.json`、`tsconfig.json` 等）
+  - 已有实现模式（grep 关键词、查找类似功能的实现文件）
+  - 已有文档或注释（相关模块的 README、代码注释）
+  - 已有测试文件（理解测试模式和边界条件）
+- 探查到的信息直接作为发散阶段的输入，不需要再向用户重复确认已经在代码库中找到的事实。
 
 ### 收敛阶段（Converge）
 - 目标：从发散结果中选择 1 个方向，逐条冻结具体问题
@@ -43,28 +90,36 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
 3) 把当前任务拆成 `Open Questions`，状态只允许 `open / in_discussion / frozen / deferred`。
-4) 每次只推进 1 个当前问题，并显式输出：
+
+4) **探码后问**：在对每个 Open Question 提问前，先 spawn `explore` agent 探查代码库。如果代码库中已有足以回答该问题的信息，在 intake 草案的相应章节记录该信息，并跳过该问题的提问。只有当代码库无法回答时，才把该问题交给用户。记录每个问题属于以下哪一类：
+   - `codebase: answered` — 代码库已可回答，跳过提问
+   - `codebase: partial` — 代码库有部分信息，补充提问未覆盖的部分
+   - `user: required` — 必须问用户
+
+5) 每次只推进 1 个当前问题，并显式输出：
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
     - `Exit condition:`
 - 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
-5) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
-6) 每轮都要把 intake 草案写盘，至少包含：
+6) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
+7) 每轮都要把 intake 草案写盘，至少包含：
+   - `Deep Interview` — 9 维分析：Why/非目标/影响面/假设/替代方案/约束/优先级/成功度量/风险
    - `Context`
+   - `Codebase Knowns` — 来自代码库的已知信息：在提问前通过 explore 已确认的事实、现有模式、配置值等。标注每项的信息来源路径
    - `Open Questions`
    - `Resolved Questions`
    - `Frozen Decisions`
    - `Draft Scope`
    - `Draft Verify`
    - `Ready for ws-plan: yes/no`
-7) 错误状态节点（Error States）：
+8) 错误状态节点（Error States）：
    - 在 intake 草案中专设 `Error States` 小节，覆盖已知失败模式：
      - 网络/超时/第三方依赖不可用时的系统行为
      - 数据一致性（并发写入、部分失败、脏数据）
      - 输入校验边界（空、超大、非预期类型）
    - 若识别到需要回滚的场景：在 `Error States` 中写明回滚条件与回滚方式。
-8) 回滚规范（Rollback Spec）：
+9) 回滚规范（Rollback Spec）：
    - 当 intake 涉及现有数据迁移、API 契约变更、配置漂移修复时，必须包含 `Rollback Plan` 小节。
    - `Rollback Plan` 至少包含：触发条件、回滚步骤、验证回滚成功的方式、副作用清单。
-9) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。
+10) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。

package/templates/workspace/.opencode/skills/ws-preflight/SKILL.md

@@ -32,9 +32,10 @@ description: 使用时机：新会话开始、仓库首次操作时。触发词
 - 使用者已经知道当前仓库能否继续进入后续阶段，以及必须遵守的约束与下一步入口。
 
 执行步骤（强制）：
-1) 定位项目根目录：
-   - 优先：`git rev-parse --show-toplevel`
-   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+1) 定位项目根目录（submodule 感知）：
+   - 优先：`git rev-parse --show-superproject-working-tree`（submodule 内上溯到 superproject 根）
+   - 若为空：`git rev-parse --show-toplevel`
+   - 若两者都失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
 2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`

package/templates/workspace/.opencode/skills/ws-req-review/SKILL.md

@@ -8,7 +8,7 @@ description: 使用时机：需要评审需求、验收条件、合同时。触
 目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
 
 执行步骤（强制）：
-1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+1) 定位项目根目录：先尝试 `git rev-parse --show-superproject-working-tree`（submodule 感知上溯）；若为空再用 `git rev-parse --show-toplevel`。都失败则停止并让用户确认根目录。
 2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
    - `AI_PROJECT.md`
    - `REQUIREMENTS.md`