@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/common/rules/documentation-standard.md

@@ -0,0 +1,33 @@
+# 开发文档的归属、保真与验证
+
+在 SpecDev 中新增、修改、审查或整理项目文档时读取。本规则负责开发文档的工程要求，不改写全局写作能力。注释继续使用 <Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>；工件冲突遵守 <Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>。
+
+## 一项事实的负责位置
+
+Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、接口说明与 README 描述当前行为；change ADR 保存已经接受的决定和真实取舍；CONTEXT 保存本 change 已确认领域语义；LOG 保存讨论、待验证解释和被替代结论；Evidence 记录实际验证。永久知识仅经 A 晋升，archive 是只读历史。
+
+按读者与任务区分教程和查询参考。教程按前置知识与操作顺序组织，参考限定自身负责的主题。上层文档只说明下属职责并链接具体 owner，不复制整个子模块实现。用户不需要的内部过程不要挤进入口；详细信息需要可定位而不是被删掉。
+
+## 改写前保留完整命题
+
+逐项保留行动者、动作、条件、时间与顺序、必须/可以/禁止、例外、所有权、副作用、失败保证及后果。删掉这些词可能改变行为，不是简单精简。局部使用点仍要有安全调用所需的完整契约；长篇理由、历史和算法说明链接其 owner。参考或生成内容先改真实源，再重建派生文件，不手工改生成物。
+
+正文描述当前机制，不保留“本轮修改”“下一张 PR”“审查者已认可”或只有某次会话才能解释的编号。必要历史与事故证据留在 LOG/ADR/复盘中；真实 issue、公开规范和可定位历史引用不因出现编号就删除。未知理由保持未知，不补写想象中的设计史。
+
+数字和来源没有核实就写未验证，不编造备选方案或测试经历。HTTP API、服务、进程边界和事务边界有实际含义时保留精确术语，不机械替换成 module/seam。
+
+## 运行声明与升级说明
+
+字段、默认值、命令和平台行为查 owning source，并在有执行条件时运行文档给出的实际操作。仅检查文字或链接不能证明命令成功。缺少网络、凭据、平台或权限时，明确未执行项、风险与验证 owner；不换成模拟后声称真实路径已验证。
+
+外部可感知的破坏性变更在引入时同步升级说明：受影响对象、旧新行为、精确迁移步骤、成功确认和真实恢复限制。用户数据已经发布就不是可随意覆盖的开发数据；预发布名称不解除兼容义务。使用目标项目已有升级文档位置，没有惯例时由当前任务批准的项目文档路径承载，不新建 SpecDev 永久 namespace。
+
+双语或多语仅在目标项目要求时同步。保留未改变的已审文本，核对条款含义、术语、代码及链接；哈希或结构一致不证明翻译正确。不要照搬 DSH 的双语三件套、行数对齐和字数配额。
+
+## 文档维护与可见行为
+
+纯文档可以使用链接、示例、类型片段、生成一致性和事实核对，不伪造 TDD 或 E2E。涉及工具说明、prompt、错误消息或 CLI/UI 输出时按行为变更处理，追加实际模型/用户可见证据或明确未验证。执行入口见 <Path>{roots.workflows}/specdev/specdev-i-implement/references/documentation-procedure.md</Path>；C 可仅审查，不获得写入权。
+
+没有所需行为层运行能力时报告缺口，并按原 Gate 保持未通过，不能借文档任务绕过。验收回读修改源和派生物，列出检查、未验证项及明确的新增行为；不用字数变化宣称 Token 或费用节省。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-prose-standard/SKILL.md</Url> 与 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/AGENTS.md</Url>。

package/template/workflows/specdev/common/rules/domain-modeling.md

@@ -1,6 +1,6 @@
 # 领域建模规则
 
-本规则只规范当前 change 内的候选领域知识。G 和 A 的 consolidate-from-code 模式都可以用它整理 change 工件，但它不授权写入永久 namespace；永久知识只能由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 在完成证据、毕业评估和用户确认全部通过后提升。
+本规则只规范当前 change 内的候选领域知识。G 和 A 的 consolidate-from-code 模式都可以用它整理 change 工件，但它不授权写入永久 namespace；永久知识只能由 `<Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path>` 在完成证据、毕业评估和用户确认全部通过后提升。
 
 - 当前 change 的 CONTEXT 只保存已确认、供本 change 下游使用的项目规范语言，不保存普通编程概念、代码导航、一次性状态或讨论历史。
 - 每个术语使用规范名称和 1–2 句定义；不推荐的同义词写入 `_Avoid_`。

package/template/workflows/specdev/common/rules/domain-runtime.md

@@ -0,0 +1,35 @@
+# SpecDev 运行合同
+
+只在用户明确激活当前 Work 后读取；当前入口已明确时不重入领域 Skill，也不先执行初始化。项目与必要资源明确即可直接使用，无需 Speculo CLI 或安装元数据。
+
+## 启动顺序
+
+1. 明确项目根、方法资源根与获批业务数据根。已有安装时验证真实 workspace 与 roots；没有安装时使用明确根参数，方法资源可以只读。相对参数基于项目根，cwd 只作线索；不静默切换项目。根冲突、越界链接或重叠安装事务仅阻塞依赖该根的写入。详见 <Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>。
+2. 读取当前请求和所选 Work；按 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path> 检索相关知识 ID/关键词，再回读少量原文与 provenance。没有相关知识不要求先初始化知识目录。
+3. 有 change 时定位用户指定对象或唯一合法候选，读取 README 的唯一 Outcome、当前负责工件和接续点。只枚举 changes 直接子目录，排除 archive；多个候选真实消歧。只读代码/架构审查、知识审计、capture 和初始化不强造 change。
+4. 按实际分支读取必要参考。创建、恢复、完成、取消或归档时读取 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path>；轻量/完整输入或事实冲突读取 <Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>；实际交接、并行、父子集成才加载 <Path>{roots.workflows}/specdev/common/rules/operating-governance.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>。
+5. 写前核对路径、原 owner、实际写入者、相关 pending transaction、lock 和 recovery evidence。失败/阻塞记录在原 README、计划、Evidence 或操作回执；真实交接只更新原负责位置。完成产物、适用验证并回读，返回证据和下一入口。
+
+新普通流程不读写全局 status、change status 或 Work 调用镜像。发现旧活动协议、混合权威或转换 pending 标记时停止受影响写入，保留原件并交显式转换；README 存在不证明转换已完成。旧归档仅走独立历史只读定位。
+
+## 工件与能力
+
+小请求使用 README 中等价范围、AC 与验证；用户明确要求 Spec/Ticket/Goal 时交付指定工件。复杂需求可经 W → G → S → T → P → I 逐步形成合同，不要求全部 Work 串行必跑。Ticket frontmatter 拥有本票状态、依赖、写集与 Skill binding；有票的 Map/Goal 只管导航、依赖、Gate、集成和恢复，无票 Goal 由计划清单负责进度。整体结论只在 README，归档事实只在目录位置与回执。
+
+真实使用的 Spec/Ticket/Map/Goal、DESIGN、调查、远程账本 schema 与验证继续有效。并发上限、worktree 与集成尝试策略只在实际启用时由原 Goal/项目约定提供来源；缺省 current 单写入者、严格串行/direct-parent。Lead 自己实现也计入实现并发，只读 review/research/test-observation 不新增数字上限。GitHub labels 等实际工具配置仅对应分支读取；未知配置保留，缺标签只阻塞有关远程写入。
+
+UI 候选缺省 3 个，配置范围 2–4；用户明确数量覆盖默认及上限。W 每会话最多完成一张调查票。专业分支保留：R performance 先测量，D evidence-triage 不以观察冒充根因，I documentation 在原授权范围维护当前工程事实。
+
+## 写入边界
+
+实现只写获批项目路径；Work 不写 CLI-owned back/install/managed/baselines，不要求创建空 namespace。ADR/context 的提升、纠错、替代和清理由 A 原网关处理，research/非标准 store 只有声明的 owner 才可写。DESIGN 首次 approved-intent 和后续 promotion 都由 A 专用网关发布；P 嵌入调用保持原 owner，不启动归档。详见 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>。
+
+提交、推送、合并/父分支更新、来源 branch/worktree 清理、发布、部署、远程写入、归档移动、永久知识改写和不可逆迁移仍由 owning 入口核对具体授权。同一目标/动作/范围批准复用；新增副作用、范围或漂移才补充确认。文本、Outcome 和 owner 字符串都不能创造授权。
+
+只阻塞重叠写集及依赖分支，继续独立已授权工作。普通多文件修改没有整体原子保证；恢复先检查已落地结果，不能因报告缺失重复操作。同次任务已加载且未变化的规则可复用。
+
+## 验证与路由
+
+按当前分支运行 <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> 的适用 stage；传明确项目/方法/数据根，不用 CLI 包装器作为普通 Work 前置。prototype 传具体 UI-NNN/LOGIC-NNN；完成/取消按 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path> 核验真实证据，票全 done 不替代整体验收。归档后以实际目标运行 archived 验证。
+
+场景出口见 <Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>。T 的 capture、publish、PR 和独立 TRI 各有原账本 owner；未请求远程动作不创建空账本或新完成门。completed/cancelled 不自动授权外部动作，已承诺而未结束的外部交付仍阻塞封存。已完成/归档来源的复盘另建 review-only change，不改写历史。

package/template/workflows/specdev/common/rules/engineering-evidence.md

@@ -0,0 +1,31 @@
+# 专业分支的工程证据
+
+本规则只约束新运行的 R.performance、I.documentation 和 D.evidence-triage；既有工件与主持久化 schema 不升级。普通 Work 不要求额外记录。记录是某次 checkpoint 的观察，不拥有 Ticket/Goal/change 状态、授权或恢复锁；不能用它代替原 Evidence、诊断和验收。
+
+## 写入原 owner
+
+在原工件正文添加 `Engineering Evidence` 小节及一个标记为 `json specdev-engineering-evidence` 的代码围栏，里面是一个 JSON 对象。performance 位于 <Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>；incident 位于 <Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>；documentation 位于原本票 <Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path> 或原 <Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>。禁止写到另一模式的 owner，旧归档与旧完成证据不回填。
+
+公共字段：`version: 1`、`kind`、实际源码/输入的 `checkpoint`、非空 `evidence` 字符串数组。指针使用原 Path/来源定位约定，不写机器绝对路径、密钥或未脱敏数据。记录每次真实观察，恢复时追加新 checkpoint 的证据；不能更改旧事实来制造成功。
+
+## Performance
+
+`operation` 是用户操作，`outcome` 为 baseline、improved、no-gain 或 inconclusive，`uncertainty` 解释测量局限。没有样本时只能 inconclusive。baseline/candidate 各含实际 `checkpoint`、`entrypoint`、`environment`、`clock`、`workload`、64 位 `workload_digest`、`unit`（ms/bytes/ops/s）、`direction`（lower/higher）、`cache`（cold/warm/not-applicable）、`excluded_costs` 字符串数组和有限非负 `samples` 数组。
+
+普通 R 调查只记录 baseline 或 inconclusive；improved/no-gain 需已有可比较的 baseline 与 candidate。比较除源码 checkpoint 外的工作量、入口、环境、时钟、单位、方向、缓存与排除成本必须一致。improved 还需 `behavior_verification: passed`，并且样本算术均值沿目标方向改善。满足这些必要条件仍不证明超过噪声、具备统计显著性、内存可接受或测量真实，Lead 必须回读数据与行为证据。
+
+## Documentation
+
+记录 `owner_paths`（真实源指针数组）、`outcome`（verified/partial/blocked）、`visible_behavior_changed` 布尔值、`behavior_verification`（passed/failed/not-run/not-applicable），以及非空 `claims` 数组。每项 claim 有 subject、method（command/source/manual）、state（verified/unverified）和 evidence。未验证项必须写 reason；verified 的 command 项还必须有 command、`executed: true`、`exit_code: 0` 和非空 output 原始结果摘要数组。
+
+总体 verified 要求所有声明 verified；可见行为改变时必须有 passed 的行为证据。partial/blocked 是诚实的阶段结果，不授予 Ticket done。工具仍不能认证 Agent 自报，Lead 继续核对真实命令、输出和来源。
+
+## Incident
+
+记录非空 facts、unknowns、next_checks 字符串数组；`feedback_loop_ready: false` 与 `root_cause_confirmed: false` 必须明确。这是事件证据截面，不是根因结论。正式 diagnosis 的红灯、假设和状态仍由原诊断规则验证；未来获得红灯后保留原事件观察，转入正常 D 流程，不把旧观察改写成当时已确认。
+
+## 验证入口
+
+新分支分别执行现有校验器的 `--engineering performance`、`--engineering documentation` 或 `--stage diagnosis --engineering incident`，输入当前 change。可与原 `--repo` 和适用 `--stage` 结合。没有标记记录的历史工件继续按原规则验证；显式专业模式缺少记录会失败，已有标记记录在普通 change 校验中也会检查。
+
+代码块语法是 `json specdev-engineering-evidence`，不是新文件类型。校验器只读，无论成功、失败或不完整都不写状态、不创建缺失工件、不执行命令、不获取授权。源记录、结构校验、真实工具执行和宿主观察是不同证据，报告时分别说明。

package/template/workflows/specdev/common/rules/error-handling.md

@@ -0,0 +1,40 @@
+# 错误、状态保证与恢复
+
+在设计、实现或审查失败、重试、取消、后台任务和恢复时读取。此规则决定失败后的工程判断；既有授权、状态 owner 与远程操作协议仍分别拥有执行权，不在这里创建账本或更换恢复网关。
+
+## 先定义失败后仍成立的事实
+
+预期失败使用可区分的类型或稳定代码，保存必要原因和处理信息；不要解析展示文案来选择恢复分支。无法预期的缺陷可以作为异常报告，但不能被 catch 转成成功。对每个可能改变状态的操作，记录实际处理者、报告者、清理责任及失败后的保证：
+
+| 已知副作用 | 可以作出的判断 | 下一步 |
+|---|---|---|
+| 未开始或确认未发生 | 未产生本次效果 | 仍需核对授权、取消与重试条件 |
+| 已确认全部提交 | 效果已发生 | 回读结果，不能再次创建相同效果 |
+| 已确认部分发生 | 只有已核实部分可信 | 停止依赖完整结果的工作，按 owner 的补偿或继续协议处理 |
+| 结果未知 | 无法保证没发生或已成功 | 保留原操作标识，先对账；不能声称回滚或安全重试 |
+
+捕获异常不撤销已经发生的修改，记录日志不等于完成恢复。只有受影响状态的 owner 能证明后续操作的前置条件仍成立；否则停止依赖该状态的工作、弃用无效实例或升级处理。无关、独立且已授权工作仍可继续。
+
+## 重试、取消与无进展
+
+重试必须说明安全重复的依据、执行 owner、取消途径和预算。只读、可幂等重试和需要先确认副作用的操作分别处理；“发生了超时”本身不能证明可重复。持续监督需要可释放的生命周期和可见降级，不伪装为有限次数操作。
+
+使用现有 config/Plan 的预算，不在下游偷偷扩大次数。只读操作也可能依赖已变化输入，仍需核实范围。
+
+同一输入、同一方法、同一失败且没有新证据时，不通过更换 Agent、清空 attempts 或重复问用户来制造进展。恢复既有 Goal/Ticket 时沿用原失败记录，由 Lead 说明新增证据或方法变化后再派发。远程对账与 marker 去重由 <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path> 路由到原远程协议；进入远程分支后再读取，不在普通错误审查中加载传输实现。
+
+取消只说明发出了取消请求，不保证远端副作用或子进程已经停止。传播 signal 后仍需等待属于本操作的完成信号；清理失败和业务失败分别报告，不能用后者隐藏前者。
+
+取消必须说明停止接收、停止执行和外部工作终止各自的时点；无法确认终止时保留未知状态和后续核实责任。
+
+## 面向用户的结果
+
+最终说明必须指出受影响操作、已知影响、尚不确定的结果、系统当前处置和下一安全动作。失效状态持续存在时，提示也应持续可见；错误提示组件不能随已关闭的来源界面一起消失。保留有效数据，不为展示瞬时错误清空它。使用目标项目原有语言和诊断机制；敏感内部信息不进入公开文案。主要报告渠道失败时有独立的安全回退。
+
+S 把适用保证写成行为合同，T-tickets 指定验证，I 落实和记录，D 调查实际失败，C 追踪所有可达路径。验证应观察外部状态、文件、事件、退出或用户可见结果，不只断言异常被捕获。
+
+## 判断示例
+
+请求创建 PR 后超时，应先按稳定 marker 查询原目标；直接重发可能重复创建。读取无副作用的数据遇到临时网络错误，在预算、取消和环境允许时可以重试。这两个场景不能共享无条件 retry。
+
+方法参考：DeepSeek Harness 的错误处理标准，固定参考版本见 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-error-handling/SKILL.md</Url>；这里采用 SpecDev 原有 owner 和持久化，不导入其运行时实现。

package/template/workflows/specdev/common/rules/evidence-and-verification.md

@@ -34,7 +34,7 @@ required 模式下，Lead 在最新父分支与 source commit 的 candidate 状
 
 ## 3. Agent 声明
 
-subagent 只返回候选命令与结果，不写 Evidence。Lead 重读 workspace/Git、必要时复跑或核对输出后落盘；外部 provider 自报、截图、模拟和推断在此之前标记 `unverified`。review/research/test-observation agent 不拥有 E2E Gate。
+任务执行者 只返回候选命令与结果，不写 Evidence。Lead 重读 workspace/Git、必要时复跑或核对输出后落盘；外部 provider 自报、截图、模拟和推断在此之前标记 `unverified`。review/research/test-observation agent 不拥有 E2E Gate。
 
 ## 4. 失败分类与完整性
 
@@ -53,3 +53,19 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
 
 Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成，不替代本文件的完整记录。
+
+## 6. 按改动选择检查与复用证据
+
+先固定当前真实 base/head、dirty 写集、配置和消费者，选择能在本次回归上失败的最窄检查；动态配置、Worker、子进程、发布构件或跨模块接口需显式选择真实入口。CI 负责目标项目规定的全量矩阵，本地不因 commit/push 机械重跑刚通过且仍有效的检查；原 required Gate 不因此降级。
+
+复用记录须给出原证据、代码/输入/配置/Skill 摘要、命令选择、环境和仍成立的原因。基线合入、head 改变、配置/依赖/生成器或被测输入变化时重估失效范围；不能把不相关改动当作所有证据永久无效，也不能沿用旧 head 的完成结论。readiness、skipped、pending、环境失败和未运行分别报告。
+
+异步、资源、CI 或测试删除使用 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；失败后的状态和安全继续使用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。验证结果须关联真实退出、事件、文件或输出，不能只相信组件/Agent 自报。
+
+## 7. 特殊行为与文档证据
+
+纯文档使用可执行示例、链接、类型与生成一致性、源码语义核对；不适用代码 TDD/E2E时明确理由。prompt、工具定义、错误或 UI/CLI 字符串改变属于行为变化，检查真实模型/用户可见内容，不只检查 Markdown。UI 原型、mock、真实服务器演示分别标记；录制证据对应准确提交、环境、运行方式和片段，不能拼接不同运行冒充一次成功，也不强制无关任务录 GIF。
+
+性能测量必须有真实用户操作、可比较工作量/时钟/冷暖状态、原始样本与端到端结论；微基准改善不能代替整体收益。专业分支仅在原报告追加 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>，结构通过不证明测量、翻译或工具执行真实。
+
+删除、合并测试的决定需记录旧行为/错误/兼容/回归到新用例的覆盖承接；无法证明就保留。新准入规则至少有一个从真实执行入口失败的反例，并在恢复基线后确认通过。

package/template/workflows/specdev/common/rules/operating-governance.md

@@ -1,6 +1,6 @@
 # 运行治理细则
 
-规划、写入、并发、恢复、验收或归档时读取。
+仅真实交接、并行写入、共享所有权或父子集成时读取；普通启动不要求加载全部治理。
 
 
 1. **先发现、后询问**：仓库、配置、schema、测试和文档能回答的事实先探索；只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
@@ -12,10 +12,10 @@
 7. **偏差显式化**：计划与事实冲突时停止、记录、修订，不静默扩大范围或改写契约。
 8. **状态单一来源**：Ticket frontmatter 是单 Ticket 状态权威；Map 和 Goal Plan 是投影与编排。
 9. **知识以当前真相为目标**：归档保留历史，永久知识只保留仍真实且经实现验证的结论。
-10. **恢复依赖权威工件**：跨 Work 或 Agent 边界时同步 active change 的 `current_work`，成功完成后去重更新 `works_run`，返回下一 Work 和权威工件的完整路径。
+10. **恢复依赖权威工件**：跨 Work 或 Agent 的实际交接在原 README/计划/Evidence 记录 owner、范围、未决动作和下一步，不维护 Work 调用镜像；返回下一 Work 和权威工件完整路径。
 11. **本地执行权威**：远程 Issue/PR/URL 只作为来源或完成投影；Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
 12. **完成与归档分离**：本地完成按 change completion 合同决定；远程 close 失败不回滚完成，但必须 reconcile 或 waive 后才归档。
-13. **Lead 与隔离正交**：Lead 固定拥有 SpecDev 状态、Evidence 与父分支；是否派遣 subagent 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
+13. **Lead 与隔离正交**：Lead 固定拥有原计划、Evidence 与父分支；是否派遣 任务执行者 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
 14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
 15. **父子权威隔离**：父实现 change 只拥有 Ready 子 change 的组合 Ticket DAG、serialization、全局 workspace/资源和实现进度投影；子 change 继续拥有全部行为与实现合同。一个未完成子 change 只能属于一个未完成父实现 change。
 

package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md

@@ -1,6 +1,6 @@
 # Parent Implementation Orchestration
 
-本规则只约束 Ready Spec/Tickets 之后的跨 change 实现，供统一 P-goal-plan、兼容 P-goal-plan、I-implement 与 A-archive-and-consolidate 读取。
+本规则只约束 Ready Spec/Tickets 之后的跨 change 实现，供统一 P-goal-plan、I-implement 与 A-archive-and-consolidate 读取。
 
 ## 输入边界
 
@@ -16,11 +16,11 @@
 
 ## 唯一所有权
 
-一个 active/blocked 子 change 最多属于一个未完成父实现 change。v1 不支持父实现 change 嵌套。父 Lead 是父工件、全部 SpecDev 状态写入、E2E、repository/ref integration queue 和父分支推进的唯一 owner；implementation agent 只写授权项目 workspace。
+一个 active/blocked 子 change 最多属于一个未完成父实现 change。v1 不支持父实现 change 嵌套。父 Lead 是父工件、父计划及授权 Evidence 写入、E2E、repository/ref integration queue 和父分支推进的唯一 owner；implementation agent 只写授权项目 workspace。
 
 ## I-implement 调用
 
-父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate，但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 P Goal（旧 O 入口保留恢复键），不要求用户重新激活 change。
+父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate，但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 P Goal，不要求用户重新激活 change。
 
 ## 归档与完成
 

package/template/workflows/specdev/common/rules/path-ownership.md

@@ -15,21 +15,21 @@
 
 1. 可能并行的 Ticket，其 writable paths 不得相交；glob 按覆盖关系判断。
 2. shared path 只由专用 owner Ticket 修改；消费者 Ticket 只读。Lead 负责集成，不以冲突解决替代 shared owner。
-3. implementation subagent 只写其 Packet 与 Ticket 授权路径；Lead 自行实现也受同一边界约束。
+3. 实现执行者 只写其 Packet 与 Ticket 授权路径；Lead 自行实现也受同一边界约束。
 4. review/research/test-observation agent 只读项目与 SpecDev 工件。
 5. 越界前停止并按 deviation control 提出 ownership change；不得先改后报。
 6. 上游 Ticket 改变目录/合同后，下游基于已集成父分支重新解析路径和 preflight。
 
 ## 3. Ticket workspace strategy
 
-Goal Plan 创建时选择 Ticket workspace strategy，默认 `current`。`current` 模式的 Ticket 使用当前分支、当前 workspace 和严格串行执行；允许一个 implementation subagent 写入当前 workspace，但前一 Ticket 必须完成 commit、Lead 验收和 direct-parent 验证后才能开始下一个。`required` 模式每个 Ticket 使用唯一来源 worktree `specdev-worktree/<ticket-id>`，并通过 candidate-merge 集成。没有 Ticket 的获批 Direct Spec 继续由 current workspace 唯一 owner 执行；只读调查不创建实现 worktree。
+Goal Plan 创建时选择 Ticket workspace strategy，默认 `current`。`current` 模式的 Ticket 使用当前分支、当前 workspace 和严格串行执行；允许一个 实现执行者 写入当前 workspace，但前一 Ticket 必须完成 commit、Lead 验收和 direct-parent 验证后才能开始下一个。`required` 模式每个 Ticket 使用唯一来源 worktree `specdev-worktree/<ticket-id>`，并通过 candidate-merge 集成。没有 Ticket 的获批 Direct Spec 继续由 current workspace 唯一 owner 执行；只读调查不创建实现 worktree。
 
-workspace/implementation owner 可以是 Lead 或动态 implementation subagent；integration owner 固定为 Lead。current 模式 Lead 在父分支直接验收和推进，required 模式 Lead 建立 parent-candidate、运行适用 E2E 并推进父分支。required 生命周期由 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理，current 生命周期由 I-implement 的 direct-parent 规则管理。
+workspace/implementation owner 可以是 Lead 或动态 实现执行者；integration owner 固定为 Lead。current 模式 Lead 在父分支直接验收和推进，required 模式 Lead 建立 parent-candidate、运行适用 E2E 并推进父分支。required 生命周期由 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理，current 生命周期由 I-implement 的 direct-parent 规则管理。
 
 ## 4. 并发
 
-required 模式 implementation subagent 上限取 Goal Plan、config 和平台能力共同约束，Lead 不计入。current 模式保持单 writer 串行安全不变量，Ticket 严格串行。review/research/test-observation agent 不设置 SpecDev 数字上限，但 Lead 必须避免重复工作与可变环境争用。
+required 模式 实现执行者 上限取 Goal Plan、config 和平台能力共同约束，Lead 参与实现时计入。current 模式保持单 writer 串行安全不变量，Ticket 严格串行。review/research/test-observation agent 不设置 SpecDev 数字上限，但 Lead 必须避免重复工作与可变环境争用。
 
-子 change 属于父 Implementation Map 时，再取父 Implementation Plan 的全局 implementation subagent 上限与 workspace 策略；该上限跨全部成员合计。无 dependency 的组合 Ready Tickets 若 writable/shared paths 重叠，也必须在父 Map 建立 serialization。相同 repository/ref 的 parent integration 严格串行；一次父 HEAD 推进会使其他成员旧 candidate 失效。
+子 change 属于父 Implementation Map 时，再取父 Implementation Plan 的全局 实现执行者 上限与 workspace 策略；该上限跨全部成员合计。无 dependency 的组合 Ready Tickets 若 writable/shared paths 重叠，也必须在父 Map 建立 serialization。相同 repository/ref 的 parent integration 严格串行；一次父 HEAD 推进会使其他成员旧 candidate 失效。
 
 **完成标准**：每个项目写入映射到唯一 change、Ticket、owner 和来源 worktree；shared 与父分支写入 owner 唯一。

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

@@ -2,6 +2,12 @@
 
 本规则是 SpecDev 中“文件、目录、工件与工具引用”的唯一规范。入口 work、子流程、模板、规则、Schema、Skill、工具说明和治理文档均必须遵守。
 
+## 直接使用与根
+
+先明确 projectRoot、methodRoot（方法包根）、stateRoot（领域共同数据父根）；specdevRoot 为 stateRoot/specdev，不持久化新 context JSON。已安装时验证真实 workspace，显式参数与安装 roots 冲突即拒绝；无安装时方法资源可只读，业务写入仍限获批项目内根。相对参数统一基于 projectRoot，不静默改用 cwd 或另一项目。实际路径逐层检查链接、大小写、父类型、包含关系、已有目标与有关事务；仅字符串前缀不足以证明安全。
+
+{roots.*} 只使用既有 alias。安装时来自 workspace；完整离线包由导出资源映射解析；普通自包含 Work 的 references/assets/scripts 相对 Skill 根。没有明确写根仍可只读审查，缺 Node/摘要工具可提供草案但不能伪造检查通过。诊断可显示绝对路径，持久工件使用项目相对或对象内 locator。
+
 ## 1. 工作流目录中的引用
 
 引用 `<Path>{roots.workflows}/specdev/</Path>` 下的任何文件或目录时，必须写出完整根变量与完整相对路径：
@@ -12,8 +18,8 @@
 
 正确示例：
 
-- `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
-- `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/config-template.json</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/orchestration-protocol.md</Path>`
 - `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
 - `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
 - `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
@@ -21,9 +27,9 @@
 不得使用：
 
 - 裸文件名；
-- 相对路径；
+- 未声明相对基准的跨包路径；
 - 仅写目录名；
-- 指向内部文件的 Markdown 相对链接；
+- 跨包偶然目录关系的 Markdown 相对链接；
 - 省略 Path 标签的反引号路径。
 
 ## 2. 状态目录中的引用
@@ -44,7 +50,7 @@
 
 目录引用必须以 `/` 结束；文件引用不得以 `/` 结束。
 
-嵌套安装反例：项目根 `.speculo/specdev` 不是状态根。change 必须位于 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 或 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
+嵌套安装反例：项目根 `.speculo/specdev` 不是状态根。change 必须位于 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 或新归档 `<Path>{roots.state}/specdev/changes/archive/{change}/</Path>`；旧 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>` 只读保留。
 
 ## 3. 项目代码路径
 
@@ -121,4 +127,7 @@ SpecDev 不假定运行时一定提供项目根变量。Ticket、Evidence、诊
 
 本文件是 SpecDev 内部动态工件协议，不是通用 Agent Skills 的文件格式规范。独立标准 Skill 的静态 references/assets 使用相对路径；workflow 私有 Skill 声明 compatibility 后继续使用本 Path 合同。已有持久化引用不批量迁移。
 
-实际执行前可以使用只读 `speculo resolve <project-root> --path '<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>'` 展开单个指针。解析器先打开字面 workspace 路径，拒绝未知 alias、未替换变量、通配符、越界路径与链接跳转；不执行 shell、不授予文件写入权限。完整命令由已获授权调用方使用参数数组构造，不把 Path 标记或用户文本直接交给 shell。
+已有安装可选使用只读 `speculo resolve <project-root> --path '<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>'` 展开单个指针。解析器先打开字面 workspace 路径，拒绝未知 alias、未替换变量、通配符、越界路径与链接跳转；不执行 shell、不授予文件写入权限。完整命令由已获授权调用方使用参数数组构造，不把 Path 标记或用户文本直接交给 shell。
+
+
+change 内 Markdown 点击链接相对当前文件，对象内 locator 相对稳定 change 根；项目文件 locator 相对项目根，二者不得混淆。新归档移动后通过稳定名称与实际唯一位置解析；不改不可变批准、revision 或原型摘要绑定字节。旧 archive 只读解析保留原格式，不能凭空合成新 Outcome。链接可迁移不等于授权可迁移，真实 owner 与写集仍需核对。

package/template/workflows/specdev/common/rules/readiness-and-depth.md

@@ -27,6 +27,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 - 外部行为和可观察产出明确；
 - IN、REUSE、OUT 无冲突；
 - 高影响决策已锁定；
+- UI 范围按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 硬引用已批准 change DESIGN、基线版本和原型，确认/摘要未失效；
 - 没有会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
 - 依赖存在且无循环；
 - `writable_paths`、`read_only_paths` 和 `shared_paths` 使用项目相对 Path 标签；
@@ -37,12 +38,16 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 - Deep Ticket 有迁移、兼容、监控、回滚和批准点，或逐项说明不适用；
 - 单个全新上下文可以完成，否则必须拆分。
 
-详细检查位于 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`。
+详细检查位于 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>`。
 
 ## 3. Spec Readiness
 
 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 只有在外部行为、范围、公共接口、数据、安全、兼容、迁移和验收合同不存在高影响未知项时，才可设置 `ready_for_tickets: true`。
 
+UI 范围的 Ready Spec 同样要求已批准且未漂移的 change DESIGN 和页面/状态 AC 映射；纯后端或 LOGIC-only 无此要求。
+
+轻量 README 的 scope/acceptance/verification 使用同样的外部行为、风险与可判定 AC 门；没有独立票不要求 Spec YAML 或 Map。Deep、真实并行、跨 change 或复杂设计依赖必须使用完整工件；用户明确产物要求不因轻量分支降低。
+
 ## 4. 假设规则
 
 - 低影响、可逆的默认值可以作为显式假设继续；

package/template/workflows/specdev/common/rules/test-reliability.md

@@ -0,0 +1,37 @@
+# 可重复的测试与有效反例
+
+新增、修改或调查异步、资源、时钟、并发、进程或 CI 易抖动测试时读取。检查选择和执行证据由 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 拥有；本规则只规定测试怎样可靠地观察目标行为。
+
+## 按真实拓扑设计隔离
+
+从实际测试配置与 CI 定义确认同文件用例、不同 worker、不同测试进程和共享主机的 job 是否可能重叠。进程隔离不隔离端口、可预测目录、数据库、外部服务和继承的子进程。
+
+每个资源都有获取者、原子分配动作、可观察就绪、立即登记的清理和清理完成信号。测试服务器绑定 loopback 的系统分配端口后再读取地址，不先扫描“空闲端口”；目录使用独立临时根，数据库/会话使用独立 namespace。稳定录制 ID 与临时地址在 fixture 内映射，不强迫真实资源复用固定地址。仅作解析输入的 URL 或路径不属于已获取资源。
+
+不得为了掩盖一个 fixture 的冲突把整个套件串行化。共享资源修复涉及跨进程隔离时，使用独立并发进程证明隔离，而不只把同一文件中的测试顺序执行。
+
+## 全局变量、时钟与平台
+
+优先注入依赖而不是修改进程全局状态。必须修改 env、cwd、timer、locale、模块 mock 或 fetch 拦截时，保存“缺失/存在及原值”，立即登记恢复，并在最小作用域用 finally 恢复；必要时增加失败兜底。拦截只覆盖本 fixture 的精确请求。
+
+平台拥有的语义从真实读回结果确认。不要假定时间戳精度、环境变量大小写、信号、权限或文件句柄关闭语义跨平台相同；确实不适用的场景明确跳过并说明原因，不削弱所有平台断言。超时预算依据真实 lane 与被等待操作，setup/teardown 一并考虑。用例预算应明显大于被测试的超时。
+
+## 同步与彻底清理
+
+等待 readiness、handshake、状态、promise 或外部可观察条件；sleep 只可作为已经完成状态的展示停留，不作为正确性的依据。竞态使用 barrier/deferred 明确制造重叠，不靠随机重复碰运气。
+
+清理要停止新工作、解除监听、恢复全局修改，并等待子进程 exit、server close、worker termination 或等价信号。仅调用 abort/close/kill 不代表清理完成。测试需能在断言失败后仍清理，并在存在晚到回调时验证它不能污染下一个测试。
+
+清理失败保留原故障及清理故障，不吞掉其中一个。
+
+## 有效 red、负向对照与测试删除
+
+有效 red 必须来自目标行为断言。编译错误、没选中测试、fixture 初始化失败、探针未执行、timeout 杀死子进程都不是目标回归证据。强制变异先证明修改落在真实执行路径，观察预期断言失败，再还原并复跑基线。
+
+新增静态或工件准入规则，要从实际顶层 runner 投入故意无效输入并观察预期拒绝；只单测未接入的辅助函数不算落实。对于普通回归，在实际可行且安全时观察修复前失败。无法重现的部分明确未验证。
+
+删除旧测试前逐项核对它所保护的行为、错误、兼容和历史回归在新测试中的承接位置与有效证据。新的公共接口测试存在，不证明旧测试全部冗余；缺失承接则保留或补齐。不要用 sleep、宽断言、吞错、重试、归一化或跳过来制造绿色。真实外部服务允许的有界重试须由该测试政策明确批准，并报告重试与跳过。
+
+覆盖率和测试数量不能证明等价。结构检查、可执行反例和真实宿主观察分别报告，不把第一层写成第三层。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-ci-test-reliability/SKILL.md</Url>。使用目标项目的框架和真实 CI，不照搬 DSH 的工具、覆盖率或超时常量。

package/template/workflows/specdev/common/rules/workflow-routing.md

@@ -20,13 +20,26 @@
 | 开发完成后需要理解当前 change 或追问实现 | L-learn-change | 返回用户 / 继续提问 / Triage / A |
 | 架构健康扫描 | R-review-architecture | G / T |
 
-同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
+同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff/COMMAND.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
 
 
 本地已清晰请求不强制绕行 Triage。完成后要记账才选 publish；尚未成 Change、只想先留 inbox 记录才选 capture。publish、reconcile 与 capture 写不同远程对象，可先后执行。G 是单 change Grill，P-prototype 是 UI 设计，不与统一 P-goal-plan 混淆。W 发现候选后逐个交 G/S/T；单 change 拆票后可交 P 规划，多个 child 创建父 Goal 前仍须全部 Ready。原缺陷诊断 D、风险分诊、远程 reconcile、完成后发布投影和记事项捕获职责不删除。
 
 ## 复盘与交付路由
 
-开发环境/流程复盘 → <Path>{roots.workflows}/specdev/R-retro/R-retro.md</Path>。代码讲解仍为 L；Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path> 的对应模式；确定性修复回到 D/I，不由 T 接管代码。
+开发环境/流程复盘 → <Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>。代码讲解仍为 L；Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path> 的对应模式；确定性修复回到 D/I，不由 T 接管代码。
 
 长任务在阶段边界按产物与待决问题选择继续、压缩上下文或 handoff；交接只携带准确 owner、SHA、输入和未闭合动作，不硬编码特定模型的上下文阈值，不自动启动其他会话。
+
+## 专业分支与相邻请求
+
+| 请求 | 入口/分支 | 不因此触发 |
+|---|---|---|
+| 测量哪个用户操作值得优化 | R-review-architecture / performance | 不直接实现，不先发明性能阈值 |
+| 已有性能故障需要确认根因 | D-diagnose-bugs | 不把微基准替代原始症状 |
+| 一次性事件暂时无法重现 | D / evidence-triage | 不标记 root-cause-confirmed，不创建 Ready 修复 |
+| 已批准的文档维护 | I-implement / documentation | 不新建文档 workflow，不伪造 TDD |
+| 只审查文档或某个 commit | C-code-review | 不写项目、不把单 commit 扩大到 HEAD |
+| 理解已实现 change | L-learn-change | 不改 Learning workflow，不永久晋升 |
+
+只读调查或审查不是后续修改授权。清晰的小请求继续走原适用阶段，不因增加专业分支强制进入 W/G/Triage；无差异、无候选和证据不足均可诚实返回，不制造工作量。

package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md

@@ -1,94 +1,45 @@
-# 状态、持久化与恢复细则
+# 工件生命周期与恢复
 
-创建、恢复、迁移、关闭或归档 change 时读取；普通路由只读激活合同。
+创建、恢复、结束或归档 change 时读取。安装与业务运行分开；新项目不预造空目录、全局状态或工作调用记录。
 
-## 持久化约定
+## 身份与位置
 
-`speculo init` 创建固定状态骨架：
+change 的稳定身份是同一项目、领域内的 `YYYY-MM-DD-topic[-NN]` 目录名，日期为创建日期，不随归档重命名。真实首次创建时选择未占用名称；检查 active、新 archive 和旧历史，重名或多位置阻塞。只有需要相应内容时才建目录。
 
-- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
-- 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
-- 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
-- 捕获账本（可选，缺失合法）：`<Path>{roots.state}/specdev/capture.md</Path>`
+- 活动/已结束未归档对象：<Path>{roots.state}/specdev/changes/{change}/README.md</Path>。
+- 新封存对象：<Path>{roots.state}/specdev/changes/archive/{change}/README.md</Path>。
+- 既有历史：<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>，原位只读，保留原 schema、许可、模式和字节。
+- 直接 A 无 change 的必要维护回执：<Path>{roots.state}/specdev/maintenance/{date}-{topic}[-NN].md</Path>，只在跨会话/跨对象恢复需要时创建。
+- 工程 docs：<Path>{roots.state}/docs/README.md</Path>，明确请求基线后按需存在；它是跨领域工程事实，不是 SpecDev 独占知识 store。
 
-刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据：配置使用 baseline 三方合并，登记的状态 schema 使用显式 migrator，其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup；冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
+归档实际位置和原回执表示封存；不在 README 增加 archived、archive_path 或全局 active/archived 列表。新 archive 不嵌套月份。旧历史移动须另有明确计划，验证所有 locator 和 DESIGN 摘要；不可变正文不做路径替换。
 
-初始化设置 work 首次运行时生成配置并创建空的永久 namespace：
+## 唯一整体结论
 
-- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
-- 追踪规则：`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
-- 领域布局：`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
-- 永久 ADR：`<Path>{roots.state}/specdev/adr/</Path>`
-- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
-- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
+每个新 change README 正文恰有一行：
 
-初始化只保证永久目录存在，不写知识内容。只有 A-archive-and-consolidate 在 change 完成、实现证据验证、毕业评估和用户确认后，才能创建、合并或改写这些永久 namespace 中的内容；其他 Works 只读。
+```text
+Outcome: active
+```
 
-单个 change 可以包含：
+合法值只有 `active | completed | cancelled`，ASCII 大小写和格式固定；不从标题、YAML、清单、代码围栏或时间推断。重复/缺失/非法 Outcome、同义 YAML status 或新旧混合权威均拒绝写入。README 保存目的、当前接续和验收导航；完成/取消必须先通过 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>，结论文本本身不是证据。
 
-- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
+简单任务清单、范围、AC 和验证在 README；无独立 Ticket 的 Goal 用 goal-plan 清单；有 Ticket 则票和对应 Evidence 负责进度。迁出进度的位置改成导航，不能双写。复杂 Spec、Ticket、Map、Goal、Implementation、DESIGN 与专用工具合同保留真实消费者需要的字段。
 
+## owner 与独有事实
 
+不默认创建 leadership epoch、空批准槽或每 Work 记录。实际交接、并行、worktree/集成发生时，在原计划、Ticket Evidence 或操作回执记录唯一负责者、获批写集、输入、真实交接与下一步。复杂任务 owner 从原 implementation-plan/goal-plan 的 `lead` 读取。无 Goal 且动作确需 owner 时，README 的 `## Ownership` 内保存 `Owner: <session locator>` 与 `Evidence: <对象内相对路径>[#anchor]`，证据指向实际会话/交接；设计 bootstrap 还保存 `Work: specdev/prototype` 且依据正文绑定该 Work。普通只读不预建所有权记录，字段不创造授权。
 
-## 状态字段
+每个实现 Ticket 的 Evidence 在 `## Workspace Execution Record` 下以唯一 JSON object 保留实际执行记录（原 worktree 字段），不创建全局 array 镜像；其中保留 base SHA、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、candidate/result SHA、验证与 E2E disposition。current 使用 current/direct-parent；required 使用 source/parent-candidate，清理后也保留集成证据。父计划只导航，不另复制一套结果。
 
-`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 保留各自 schema v3；新 Ticket/Map 使用附加 plan_contract_version: 1，config 使用 schema v6，Goal Plan 使用 schema v6，Implementation Map/Plan 使用 schema v1，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
+语言、用户工具和数量来自当前请求/既有项目说明；实际并发、worktree 与尝试上限由原 Goal/项目约定负责，原 Goal/Implementation Plan 的 `## Execution Policy Source` 说明实际策略来源；已有 config 仍校验相应上限，Lead 自己实现计入并发。旧 config 的真实远程/验证用途可选保留；未知独有字段不能以简化为由丢弃。默认 UI 3 个、配置 2–4、明确用户数量覆盖，均不变。
 
-- `schema_version`（数字）：全局状态 schema 版本，固定为 `5`。
-- `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。
-- `active`（对象数组）：当前活跃 change 的严格索引；每项只能包含 `change`，格式 `"YYYY-MM-DD-<kebab-topic>"`。
-- `archived`（去重字符串数组）：已归档 change 名称。详细归档时间、路径和 promotion 摘要只存在于 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>`。
+## 创建、恢复和历史边界
 
-`active[].change` 必须唯一，且不得同时出现在 `archived`。`current_work`、`works_run` 和 `claimed_investigations` 只存在于 change 自有 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`：开始 Work 时设置 `current_work`；暂停或可恢复阻塞时保留；成功完成时加入 `works_run` 并清空；取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载，不写入全局索引。
+首次真实任务才创建 README 和实际需要的其他工件。简单形态参考 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/change-readme-template.md</Path>；实际需要 owner、验证或取消记录时读取 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/change-record-examples.md</Path>，不预填空槽。默认目录发现只枚举 changes 直接子目录，不递归把 ticket、archive 或临时目录当 change。指定历史再查询新 archive/旧月份 archive；同身份多位置报冲突。
 
-`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning UI 设计候选字段均为可配置正整数；候选默认值与上限必须落在 2-4 且默认值不大于上限。仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
+恢复重读原 owner、输入摘要、实际 writer、Git/工具结果与未决动作。结果未保存不等于操作没发生；超时不证明 writer 结束。仅使受影响证据失效，不清零尝试、不抢锁，不改完成历史。review-only、performance、documentation、evidence-triage 留原报告或 Evidence，不能伪造问题已解决。
 
-`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent；required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录；父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态，必须保留全部集成与 E2E 证据。
+新 writer 不新增或更新旧 status 镜像。发现旧活动 status、未知 schema、混合协议或 <Path>{roots.state}/specdev/.markdown-conversion-pending</Path> 时只读盘点，停止重叠写入并交显式转换 owner；不自动升级、不因 README 存在跳过。pending 不证明互斥，也不能按年龄删除。旧 archive 原位冻结，历史 reader 不产生可写新对象。
 
-领域状态枚举：
-
-- change：`active | blocked | completed | archived`
-- Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
-- Investigation status：`open | closed`
-- Investigation resolution：`answered | out-of-scope | superseded | cancelled | null`
-- Planning Depth：`lite | standard | deep`
-- Worktree：`planned | active | review | integrating | integrated | removed | blocked`
-
-
-
-## 路径分配
-
-1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
-2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
-3. 项目代码、测试和用户要求的项目文档写入项目路径；Evidence 仅保存项目相对指针。
-4. 长期知识候选先在 change 内形成；只有 A 在完成证据、毕业评估和用户确认全部通过后，才提升到对应永久 namespace。
-
-
-## 扩展工件与兼容
-
-W 可写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`：它只拥有候选 change 边界与目标指针，不复制各 child 的状态。父 Goal 的 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 使用 goal-tickets-map 指针合同，权威仍是父 Implementation Map/Plan。旧 O restore key 不变；旧票继续可读，未完成旧票在新执行前由 Lead 显式补全调用绑定、交付约束并重新过门禁，不自动迁移、重置状态或改写他人事务。
+CLI 刷新先 staging/验证再原子替换并保全未知 runtime；Work 不修改 <Path>{roots.state}/back/</Path>、安装元数据或命令 sidecar。安装故障只在与本次路径冲突时阻塞相关动作。