@namewta/speculo 1.0.8 → 1.0.10

package/README.md

@@ -72,7 +72,7 @@ After initialization, the target project gains the following AI agent-callable a
 
 | Workflow | Work Entries | Description |
 |---|---:|---|
-| **learning** | 7 | Evidence-aware learning for projects, products, subjects, languages, and skills: complete 30–40 minute plain-language lessons, single-file homework review, optional retention review, and provenance-preserving topic synthesis |
+| **learning** | 8 | Evidence-aware learning for projects, products, subjects, languages, and skills: complete 30–40 minute plain-language lessons, Socratic inquiry lessons, single-file homework review, optional retention review, and provenance-preserving topic synthesis |
 | **specdev** | 14 | Local-first specification-driven development: archive, code review, diagnosis, grilling, implementation, setup, learning, goal planning, prototyping, architecture review, specs, tickets, triage, and wayfinding |
 | **ops** | 3 | Host inventory and project deployment: initialize, host manage, and APP/shared-service deploy with dual documentation |
 | **person** | 2 | Persona-methodology and rigorous deliberation workflows (Mao Zedong Cognitive OS; Bidirectional Steelman Deliberation) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/.speculo/README.md

@@ -14,7 +14,7 @@
 
 ## 读取顺序
 
-1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
+1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。嵌套安装时，项目根 `.speculo/` 不是本目录；只有该文件声明的状态根是运行时状态的唯一持久化根，项目根 `.speculo/specdev` 非法。
 2. 从 `../workflows/<workflow>/INDEX.md` 发现 workflow并按需读取其中声明的永久知识；这一步不读取 Work 条目或运行状态。
 3. 用户明确激活 workflow 或 work 后，读取 INDEX 指向的 workflow 根 `README.md`，从其中的 Work 条目选择目标并读取具体入口文件。
 4. 按激活合同读取 `<Path>{roots.state}/{workflow}/status.json</Path>`。SpecDev/Learning 再读取当前 change `.status.json` 与 work 产物。Ops schema v3 读取 hosts/projects/deployments/allocations/bindings/releases 及对应运行记录，不创建 `changes/`。

package/template/canonical/canonical-specdev-goal-plan.md

@@ -1921,7 +1921,7 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -982,7 +982,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-spec.md

@@ -1072,7 +1072,7 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-tickets.md

@@ -1867,7 +1867,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-wayfinder.md

@@ -650,7 +650,7 @@ resolution: answered
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/workflows/learning/INDEX.md

@@ -3,8 +3,8 @@ id: learning
 type: workflow
 workflow: learning
 name: Learning Workflow
-description: 以完整、通俗、多表示的课程，单文件作业评审、可选延迟复习和带溯源的主题综合，持续建立个人 Markdown 知识库。
-keywords: [learning, 学习, 教学, 作业, 复习, 综合, 知识, eli5]
+description: 以完整、通俗、多表示的课程，苏格拉底问答课、单文件作业评审、可选延迟复习和带溯源的主题综合，持续建立个人 Markdown 知识库。
+keywords: [learning, 学习, 教学, 苏格拉底, 反问, 作业, 复习, 综合, 知识, eli5]
 ---
 
 # Learning Index

package/template/workflows/learning/Q-question/Q-question.md

@@ -0,0 +1,45 @@
+---
+id: learning/question
+type: workflow-entry
+workflow: learning
+name: 苏格拉底问答课
+description: 以一批约 5 题激活已知与未知，学习者作答后追加详细讲解、纠错与深化；一批生成一节 inquiry-lesson。无 Change 时可自行创建 lightweight inquiry Change。不自动串联 L/H/R。
+keywords: [反问, 苏格拉底, socratic, inquiry, 提问课, questioning, 激活, 问答课]
+---
+
+# 苏格拉底问答课
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
+
+## 读取范围
+
+1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
+2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全、创建 Change 或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+## 流程
+
+1. 解析 roots 与 Learning v2 状态。若尚无 `status.json` / `locations.json`，先按 I-init-setup 写入空状态骨架，不创建知识条目。
+2. 若没有可用 Change：根据用户主题创建 lightweight inquiry Change `YYYY-MM-DD-<kebab-topic>`，写入 `INDEX.md`、最小 `course.md`/`baseline.md`/`sources.md`、`inquiry/INDEX.md`、`learning-log.md` 和 `.status.json`（`phase=teaching`，`current_work=learning/question`）。不假装已完成 A-assess-and-plan 的完整课程地图。
+3. 若已有 Change：按 Activation 合同只读取对应 course/OBJ/Lesson/baseline/notes/inquiry 索引；不整读 archive 或其他 Change。
+4. 读取 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`。按用户指定教法或默认 `socratic` 配方生成一批约 5 题。
+5. 创建 `inquiry/IQ-<NNN>-<slug>-batch-NN.md`：元数据、Q1…Q5、空白 A1…A5、`Response: pending`。更新 `inquiry/INDEX.md`。不得把答案写入题目。
+6. 学习者填写 A1…并写入精确行 `Response: ready` 后再次激活本 Work。校验回答原文与标记，冻结 Q/A。
+7. 只在同一文件末尾追加 `## Teaching` 与 `## Inquiry Lesson`。Teaching 逐题给出思路复原、`aligned|partial|off|uncertain`、中文详解、`Explain (English)`、纠错路径、先前未覆盖知识和来源锚点。Inquiry Lesson 把本批 5 题收成一节短课单元，并以 keep-alive 钩子指向下一批、缺失 OBJ、L、H 或 R。将 `Response:` 更新为 `closed`。
+8. 更新 `learning-log.md` 与 Change `.status.json`：`works_run` 追加 `learning/question`，清空 `current_work`。不写 mastered，不写入 `lessons/` 或 `homework/`，不自动激活其他 Work。重答必须新建 batch 文件并链接旧文件。
+
+## 完成标准
+
+- 一批默认 5 题；数量可由用户指定，但必须 Q/A 成对且连续编号；
+- `Response: pending|ready|closed` 状态可审计；ready 之前不得出现 Teaching / Inquiry Lesson；
+- Teaching 是授课讲解，不是 H 的评分 Review，不得使用 `Submission` 或 `verdict: correct|partial|incorrect` 字段名；
+- 5 题生成一节 Inquiry Lesson；完整 30–40 分钟讲义仍归 L-lesson；
+- 无 Change 时本 Work 可自行创建 lightweight inquiry Change，不得因缺少 A 产物而拒绝开问；
+- 真新手或高元素交互时必须提供降级探针或建议先走 L-lesson。
+
+## 子文件
+
+- 问答课模板：`<Path>{roots.workflows}/learning/Q-question/inquiry-template.md</Path>`
+- 轻量课程模板：`<Path>{roots.workflows}/learning/Q-question/lightweight-course-template.md</Path>`
+- 提问政策：`<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`
+- 提问引擎：`<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>`

package/template/workflows/learning/Q-question/inquiry-template.md

@@ -0,0 +1,69 @@
+---
+inquiry_id: IQ-<NNN>
+batch: 01
+lesson_unit_id: IQ-<NNN>
+objective_ids: [OBJ-01]
+question_count: 5
+teaching_method: socratic
+expression_level: plain
+coverage_depth: standard
+source_ids: [S-001]
+created_at: <ISO-8601>
+---
+
+# 苏格拉底问答课：<主题>
+
+## 引用
+
+- Change：`<stable change id and current locator>`
+- 目标：`<OBJ ids>`
+- 教法：`socratic | 5e-recipe | feynman | productive-failure | custom`
+- Skill：`socratic-questioning`
+
+## Questions
+
+### Q1 — 澄清与定义
+
+<问题>
+
+### Q2 — 机制与证据
+
+<问题>
+
+### Q3 — 假设与反例
+
+<问题>
+
+### Q4 — 迁移与视角
+
+<问题>
+
+### Q5 — 元问题与下一步
+
+<问题>
+
+## Learner Answers
+
+### A1
+
+<在此填写，不要改写 Q1>
+
+### A2
+
+<在此填写，不要改写 Q2>
+
+### A3
+
+<在此填写，不要改写 Q3>
+
+### A4
+
+<在此填写，不要改写 Q4>
+
+### A5
+
+<在此填写，不要改写 Q5>
+
+Response: pending
+
+<!-- Q 在 Response: ready 后只能追加 Teaching 与 Inquiry Lesson；不得改写以上内容。不得使用 Submission 或 verdict。 -->

package/template/workflows/learning/Q-question/lightweight-course-template.md

@@ -0,0 +1,31 @@
+# 课程设计：<主题>（inquiry-first）
+
+本 Change 由 `Q-question` 在没有现成课程时创建。它只冻结主题、可观察目标和开问范围，不假装 `A-assess-and-plan` 已完成完整 Lesson 地图。
+
+## 目标与期望效果
+
+| ID | 可观察目标 | 关键性 | 前置 OBJ | 证据类型 | Inquiry | Lesson | Homework |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| OBJ-01 | `<能用自己的话解释什么>` | 是 | `<none>` | `<解释/边界/下一步>` | IQ-001 | 可选 | 可选 |
+
+## 学习者与表达/深度配置
+
+| 字段 | 值 |
+| --- | --- |
+| expression_level | `plain` |
+| coverage_depth | `standard` |
+| 来源 | inquiry-first；完整背景由后续 A 补全 |
+
+## 课程地图
+
+先用苏格拉底问答课激活已知与未知；需要 30–40 分钟完整讲义时再激活 `L-lesson`，需要正式测评时再激活 `H-homework`。
+
+## 成功证据与范围外
+
+- 成功：至少一批 `Response: closed` 的 Inquiry Lesson，并留下 keep-alive 钩子。
+- 范围外：不在本 Change 写入 `lessons/` 或 `homework/`，不宣称 mastered。
+
+## Revision 记录
+
+| 时间 | 变化 | 原因 | 是否升级为完整 A 课程 |
+| --- | --- | --- | --- |

package/template/workflows/learning/common/rules/artifact-contract.md

@@ -5,6 +5,7 @@
 | `course.md`、`background/`、`baseline.md`、`sources.md`、Change `INDEX.md` | A-assess-and-plan | 目标、宏观基础、原始基线、来源和课程地图；实质修改留 revision |
 | `lessons/` | L-lesson | 完整 Lesson 和 Lesson INDEX；不写作业答案或掌握结论 |
 | `homework/` | H-homework + learner | H 写问题/评审，learner 写 A；提交后只追加 Review，旧 attempt 不可改写 |
+| `inquiry/` | Q-question + learner | Q 写问题/Teaching/Inquiry Lesson，learner 写 A；`Response: ready` 后只追加讲解，旧 batch 不可改写；不写入 `lessons/` 或 `homework/` |
 | `review/` | R-review | 延迟保持题、原始回答、证据和复习日期 |
 | `children/<id>/` | child Work | 子 Change 原有工件；父只负责根锁、路由、位置登记 |
 | `synthesis/`、topic context | C-consolidate | claim 级综合、冲突、空白、provenance 和版本；不得覆盖原料 |

package/template/workflows/learning/common/rules/questioning-policy.md

@@ -0,0 +1,38 @@
+# 苏格拉底问答政策
+
+反问批次只允许写在 `Q-question` 拥有的 `inquiry/` 内。`L-lesson` 仍然禁止 Q/A、答案、verdict、mastered。本政策改出题与讲解，不改 H 的 `Submission` 协议。
+
+## 配方
+
+用户可指定 `teaching_method`；缺省为 `socratic`。配方只改变 Q1–Q5 的写法，不改变文件协议。
+
+| teaching_method | Q1 | Q2 | Q3 | Q4 | Q5 |
+| --- | --- | --- | --- | --- | --- |
+| `socratic` | 澄清/定义 | 机制/证据 | 假设与反例 | 迁移/他者视角 | 元问题/下一步 |
+| `5e-recipe` | Engage | Explore | Explain-prompt | Elaborate | Evaluate-as-question |
+| `feynman` | 用自己的话定义 | 举生活例子 | 指出类比失效 | 教给外行 | 还缺哪一块 |
+| `productive-failure` | 未教过的难题 | 你怎么试 | 卡在哪 | 规范解会怎么走 | 和你的差在哪 |
+| 用户自定 | 编译进同一 5 槽，缺槽用 `socratic` 补 |
+
+每题标注 `objective_id`、`bloom_level`、`socratic_move`、`expected_evidence`、`difficulty`。数量默认 5，可由用户改，但必须 Q/A 成对连续。
+
+## 文件协议
+
+- 出题文件含空 A 与精确行 `Response: pending`。
+- 学习者作答后写 `Response: ready`，再次激活 Q。
+- Teaching / Inquiry Lesson 只能追加在 ready 之后；不得改写 Q/A。
+- 闭环后 `Response: closed`。重答新建 `IQ-…-batch-NN`，旧文件只读。
+- 禁止 `Submission:`、禁止 H 的 `verdict: correct|partial|incorrect` 字段名。教学判定用 `aligned|partial|off|uncertain`。
+- 禁止写入 `lessons/` 或 `homework/`。
+
+## 讲解与 keep-alive
+
+`## Teaching` 每题必须有：思路复原、判定、中文详解、`Explain (English)`、纠错路径、先前未覆盖知识、来源锚点。
+`## Inquiry Lesson` 把本批收成一节短课：地图、机制、边界、稳定误区、下一步激活钩子。
+每一份 Teaching 结尾必须有 keep-alive 钩子（下一批种子、缺失 OBJ、建议 L/H/R），不得把本批写成终点。
+
+## 新手逃逸与 Change
+
+baseline 显示真新手或主题元素交互很高时，先降难度探针，或建议激活 `L-lesson` 再建模型。不强制 question-first。卡住连续三题仍无进展时给脚手架，而不是直接灌完整答案进 Q 文本。
+
+无可用 Change 且用户已激活本 Work 时，允许创建 lightweight inquiry Change；不得因缺少 A 产物而拒绝开问，也不得复活已退役的 `Q-quiz`。

package/template/workflows/learning/common/rules/teaching-policy.md

@@ -13,3 +13,5 @@
 ASCII、Markdown table、公式或可选外链图片可以组合使用；每个视觉必须有 caption、alt 和附近的完整文字等价物，外链失效不能阻塞理解。`sources.md` 和 Lesson source table 记录 URL、标题、定位、访问日期、claim 映射、可信度和不确定性；无法验证的内容明确标为 open/uncertain。
 
 Lesson 可以有非评分 pause/self-check，但不含 Q/A、答案、分数、verdict 或 mastered 字段。
+
+苏格拉底 / 反问批次只允许出现在 `Q-question` 拥有的 `inquiry/` 内；`L-lesson` 不得写 Q/A。Q 的讲解遵循本政策的表达与来源规则，但不占用 30–40 分钟 Lesson 预算。

package/template/workflows/learning/common/skills/socratic-questioning/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: socratic-questioning
+description: 苏格拉底问答、反问授课或用提问教；当学习者卡住、不知道下一步、指定提问/5E/费曼/生产性失败，或 Q-question 需要出题与讲解配方时使用。
+---
+
+# Socratic Questioning
+
+本 skill 只生成提问、诊断与讲解文本。工件所有权仍归 `Q-question` 的 `inquiry/`；不得写入 `lessons/` 或 `homework/`。
+
+1. 只由 `Q-question` 调用。按稳定 Change ID 读取当前 locator，禁止依赖旧路径。无 Change 时允许 Q 创建 lightweight inquiry Change，不假装 A 已完成。
+2. 读取调用方给出的 topic、OBJ、baseline、指定 `teaching_method` 和已有 inquiry 索引；按 `<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>` 选择配方，不要整读 archive。
+3. 先判断能否提问：真新手或高元素交互时返回降级探针或「先走 L-lesson」建议，而不是硬出机制题。
+4. 默认 `socratic` 五槽：澄清、机制证据、假设反例、迁移视角、元问题/下一步。用户指定 `5e-recipe` / `feynman` / `productive-failure` / custom 时只改题目，不改 inquiry 文件协议。
+5. 一批写入 `inquiry/IQ-*.md`：Q1–Q5、空 A、`Response: pending`。`Response: ready` 后只追加 Teaching 与 Inquiry Lesson；不改写答案，不写 `lessons/`、`homework/`、mastered、`Submission`、`verdict`。
+6. Teaching 每题含思路复原、`aligned|partial|off|uncertain`、中文详解、`Explain (English)`、纠错、未见知识、来源。Inquiry Lesson 把 5 题收成一课并给 keep-alive 钩子。需要完整 30–40 分钟讲义或正式测评时只返回路由，不自动激活 L/H/R。
+
+## 题槽
+
+| 槽 | 动作 | Paul 类 |
+| --- | --- | --- |
+| Q1 | 澄清/定义 | clarification |
+| Q2 | 机制/证据 | evidence |
+| Q3 | 假设/反例 | assumptions |
+| Q4 | 迁移/视角 | viewpoints |
+| Q5 | 元问题/下一步 | question-the-question |
+
+## 完成标准
+
+- 一批 Q/A 成对；讲解在作答之后；
+- 指定教法只改变题目，不改变 Response 协议；
+- 输出可被 Q-question 直接追加进 `IQ-*.md`。

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -35,12 +35,16 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 ### 1. 解析根目录
 
+创建任何状态目录之前，先从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`，校验 `path_base` 与 `roots.*`。只在解析后的状态根下创建 specdev 目录；禁止在声明的状态根之外新建 `.speculo`。
+
 确认：
 
 - 工作流根可解析为 `<Path>{roots.workflows}/specdev/</Path>`；
-- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`；
+- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`，且必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`；
 - 当前用户允许在状态根创建目录和工件。
 
+嵌套安装反例：不得把状态根默认展开成项目根 `.speculo`。项目根 `.speculo/specdev` 非法；init 与 Grill 只写入声明的 `<Path>{roots.state}/specdev/</Path>`。
+
 不得把真实绝对路径写回模板或治理文档；持久化引用继续使用根变量。
 
 ### 2. 探测项目事实

package/template/workflows/specdev/README.md

@@ -4,7 +4,7 @@
 
 ## 运行时根
 
-工作流：`<Path>{roots.workflows}/specdev/</Path>`；状态：`<Path>{roots.state}/specdev/</Path>`。具体路径遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`，不使用内部相对链接、裸文件名或机器绝对路径。
+工作流：`<Path>{roots.workflows}/specdev/</Path>`；状态：`<Path>{roots.state}/specdev/</Path>`。roots 必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`，禁止把状态根默认展开成项目根 `.speculo`。嵌套安装下项目根 `.speculo/specdev` 非法。具体路径遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`，不使用内部相对链接、裸文件名或机器绝对路径。
 
 ## 工件链与权威
 
@@ -24,7 +24,7 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
 
 ## 启动协议
 
-1. 解析 roots，读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；定位相关 entry 后回读必要原文，不默认整读索引。
+1. 先打开 `<Path>{roots.state}/workspace.json</Path>` 解析 roots，再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；定位相关 entry 后回读必要原文，不默认整读索引。不得把状态根默认展开成项目根 `.speculo`；项目根 `.speculo/specdev` 非法。
 2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`；不存在时使用 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。保留已知配置，不重复询问。
 3. 从 `<Path>{roots.state}/specdev/status.json</Path>` 定位用户指定或唯一 active change；多个候选需要真实消歧，无候选按原规则创建。
 4. 读取 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`；恢复、创建或状态修改时加载上述状态细则。child 归属未完成父 Goal 时读取对应父 Map/Plan，不接管或覆盖其 owner。

package/template/workflows/specdev/common/rules/activation-and-memory.md

@@ -4,7 +4,7 @@
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `<Path>{roots.state}/workspace.json</Path>`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/workflows/specdev/common/rules/path-reference-contract.md

@@ -44,6 +44,8 @@
 
 目录引用必须以 `/` 结束；文件引用不得以 `/` 结束。
 
+嵌套安装反例：项目根 `.speculo/specdev` 不是状态根。change 必须位于 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 或 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
+
 ## 3. 项目代码路径
 
 SpecDev 不假定运行时一定提供项目根变量。Ticket、Evidence、诊断与架构审查中的项目代码路径统一使用项目相对路径，并仍置于 Path 标签中：

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -17,7 +17,7 @@ import {
   statSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { dirname, basename, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, basename, extname, join, relative, resolve, sep, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -262,7 +262,7 @@ function parseScalar(raw) {
   return value;
 }
 
-function findSpecdevConfig(change) {
+function findSpecdevConfigByAncestry(change) {
   let current = resolve(change);
   while (true) {
     const candidate = join(current, ".speculo", "specdev", "config.json");
@@ -279,6 +279,149 @@ function findSpecdevConfig(change) {
   }
 }
 
+function uniqueResolved(paths) {
+  const seen = new Set();
+  const result = [];
+  for (const path of paths) {
+    const resolved = resolve(path);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    result.push(resolved);
+  }
+  return result;
+}
+
+function ancestorsOf(start) {
+  const dirs = [];
+  let current = resolve(start);
+  while (true) {
+    dirs.push(current);
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return dirs;
+}
+
+function parseWorkspaceCandidate(filePath, projectRoot) {
+  if (!isFile(filePath)) return null;
+  let data;
+  try {
+    data = JSON.parse(readText(filePath));
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  if (data.schema_version !== 1 || data.path_base !== "project-root") return null;
+  const state = data.roots?.state;
+  if (typeof state !== "string" || !state.trim()) return null;
+  const declared = toPosix(state).replace(/^\.?\//, "").replace(/\/$/, "");
+  if (
+    !declared ||
+    declared.split("/").includes("..") ||
+    isAbsolute(declared) ||
+    ABSOLUTE_MACHINE_PATH_RE.test(declared)
+  ) {
+    return null;
+  }
+  const expected = resolve(projectRoot, declared, "workspace.json");
+  if (expected !== resolve(filePath)) return null;
+  return {
+    filePath: resolve(filePath),
+    projectRoot: resolve(projectRoot),
+    stateDeclared: declared,
+    stateRoot: resolve(projectRoot, declared),
+    data,
+  };
+}
+
+function workspaceProbes(projectRoot) {
+  const root = resolve(projectRoot);
+  return [
+    { projectRoot: root, filePath: join(root, "speculo", ".speculo", "workspace.json") },
+    { projectRoot: root, filePath: join(root, ".speculo", "workspace.json") },
+  ];
+}
+
+function collectWorkspaceCandidates(repoRoot, change) {
+  const probes = [];
+  if (repoRoot) {
+    probes.push(...workspaceProbes(repoRoot));
+  } else {
+    for (const dir of uniqueResolved([...ancestorsOf(change), ...ancestorsOf(process.cwd())])) {
+      probes.push(...workspaceProbes(dir));
+    }
+  }
+  const found = new Map();
+  for (const probe of probes) {
+    const parsed = parseWorkspaceCandidate(probe.filePath, probe.projectRoot);
+    if (!parsed) continue;
+    if (!found.has(parsed.filePath)) found.set(parsed.filePath, parsed);
+  }
+  return [...found.values()];
+}
+
+function isLegalChangeLocation(changeAbs, stateRoot) {
+  const name = basename(changeAbs);
+  if (resolve(stateRoot, "specdev", "changes", name) === changeAbs) return true;
+  const monthDir = dirname(changeAbs);
+  const archiveRoot = dirname(monthDir);
+  return (
+    /^\d{4}-\d{2}$/.test(basename(monthDir)) &&
+    resolve(stateRoot, "specdev", "archive") === archiveRoot &&
+    basename(changeAbs) === name
+  );
+}
+
+function resolveWorkspaceContract(repoRoot, change) {
+  const changeAbs = resolve(change);
+  const candidates = collectWorkspaceCandidates(repoRoot, changeAbs);
+  if (!candidates.length) {
+    return { mode: "legacy", errors: [], config: null, specdevRoot: null, stateDeclared: null };
+  }
+  const uniqueRoots = uniqueResolved(candidates.map((candidate) => candidate.stateRoot));
+  if (uniqueRoots.length > 1) {
+    const declared = [...new Set(candidates.map((candidate) => candidate.stateDeclared))].sort();
+    return {
+      mode: "strict",
+      errors: [`conflicting workspace.json roots.state (${declared.join(" vs ")})`],
+      config: null,
+      specdevRoot: null,
+      stateDeclared: null,
+    };
+  }
+  const workspace = candidates[0];
+  const specdevRoot = join(workspace.stateRoot, "specdev");
+  const errors = [];
+  if (!isLegalChangeLocation(changeAbs, workspace.stateRoot)) {
+    errors.push(
+      `change is outside workspace roots.state (${workspace.stateDeclared}/specdev); project-root .speculo/specdev is illegal`,
+    );
+  }
+  let config = null;
+  const configPath = join(specdevRoot, "config.json");
+  if (isFile(configPath)) {
+    try {
+      config = JSON.parse(readText(configPath));
+    } catch {
+      config = null;
+    }
+  }
+  return {
+    mode: "strict",
+    errors,
+    config,
+    specdevRoot,
+    stateDeclared: workspace.stateDeclared,
+  };
+}
+
+function findSpecdevConfig(change, repoRoot = null) {
+  const contract = resolveWorkspaceContract(repoRoot, change);
+  if (contract.mode === "strict") return contract.config;
+  return findSpecdevConfigByAncestry(change);
+}
+
 function positiveConfigLimit(config, key, fallback) {
   const value = config?.execution?.[key];
   return Number.isInteger(value) && value >= 1 ? value : fallback;
@@ -1701,9 +1844,9 @@ function validateGoalPlan(path, errors) {
   return { path, meta, body };
 }
 
-function validateGoalPlanRuntimeLimits(path, change, goalPlan, errors) {
+function validateGoalPlanRuntimeLimits(path, change, goalPlan, errors, repoRoot = null) {
   if (!goalPlan) return;
-  const config = findSpecdevConfig(change);
+  const config = findSpecdevConfig(change, repoRoot);
   if (!config) {
     errors.push(`${basename(path)}: SpecDev config.json is required to validate execution limits`);
     return;
@@ -2758,7 +2901,7 @@ function validateParentImplementation(change, parentStatus, stage, errors, warni
     if (overlap.length) errors.push(`member changes already belong to unfinished parent implementation ${entry.name}: ${JSON.stringify(overlap)}`);
   }
 
-  const config = findSpecdevConfig(change);
+  const config = findSpecdevConfig(change, repoRoot);
   const configuredAgents = positiveConfigLimit(config, "max_implementation_agents", 0);
   const configuredAttempts = positiveConfigLimit(config, "max_integration_attempts", 0);
   if (!config || config.schema_version !== CONFIG_SCHEMA_VERSION || configuredAgents === 0 || configuredAttempts === 0) {
@@ -2849,6 +2992,9 @@ function validateChange(change, stage = null, repoRoot = null) {
     return { errors: [`change directory does not exist: ${change}`], warnings };
   }
 
+  const workspace = resolveWorkspaceContract(repoRoot, change);
+  errors.push(...workspace.errors);
+
   const changeStatus = validateChangeStatus(join(change, ".status.json"), basename(change), errors);
   validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot);
   errors.push(...validateInitiative(change));
@@ -2972,7 +3118,7 @@ function validateChange(change, stage = null, repoRoot = null) {
     }
   }
   if (changeStatus && goalPlan) {
-    validateGoalPlanRuntimeLimits(goalPlan.path, change, goalPlan, errors);
+    validateGoalPlanRuntimeLimits(goalPlan.path, change, goalPlan, errors, repoRoot);
     const attemptLimit = Number.isInteger(goalPlan.meta.integration_attempt_limit) ? goalPlan.meta.integration_attempt_limit : null;
     if (attemptLimit !== null) {
       for (const worktree of changeStatus.worktrees ?? []) {