agent-project-sdlc 0.1.19 → 0.1.20

package/README.md

@@ -26,10 +26,11 @@ npx sdlc-harness init --adopt
 | Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects, including legacy seed guidance migration. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
 | Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
+| Harness Python tools | `tools/*.py` | Package-managed local workflow tools, including `transition.py`, Python validators and overview generation helpers. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
 | Stage task control | `plan.yaml`, `make validate-plan`, `npx sdlc-harness validate-plan` | Keeps each stage's agent work in small `TASK-*` tasks with `phase` metadata and scoped paths/gates. |
 | Natural-language control | `AGENTS.md` plus workflow skills | Lets users say things like "continue", "start development", "run tests" or "requirements changed"; agents map these to workflow actions. |
-| Optional parallel execution contract | `plan.yaml#parallel_execution` | Enabled only when users explicitly request multi-agent, parallel or multi-worktree execution; supports runtime-managed subagents or user-orchestrated worker prompts. |
+| Default parallel scheduling contract | `plan.yaml#parallel_execution` | Stage tasks default to a safe-parallelism check; suitable work uses Codex native subagents first, with user-orchestrated and worktree fallbacks. |
 | Workflow skills | `<harnessRoot>/skills/pjsdlc_*/SKILL.md` | Provides role prompts for product, architecture, development, implementation docs, review, testing, release and RFC recalibration. |
 | Project-local skill overrides | `<harnessRoot>/pjsdlc_managed/override_skills/<skill_name>.md` + `npx sdlc-harness sync` | Appends project-specific role instructions to generated Skill output without editing managed Skill files. |
 | Local policy overrides | `<harnessRoot>/pjsdlc_managed/policies/*.local.yaml` | Preserves project-specific policy additions separately from package defaults. |
@@ -61,16 +62,17 @@ npx sdlc-harness sync
 
 The sync output is the package base Skill plus one appended `Local Override` block. Override files support either a plain project-local snippet or a complete `SKILL.md` with `name` and `description` frontmatter. Complete Skill overrides are appended, not replaced: `sync` validates the override `name`, merges the override `description` into the generated top-level metadata, strips the override frontmatter, and appends the full body. After sync, users or their agents should review the merged Skill for semantic conflicts in phase boundaries, `allowed_paths`, `required_gates`, commit/release rules and completion checks. Unknown skill names block sync so misspellings do not silently fail.
 
-## Optional Parallel Execution
+## Default Parallel Scheduling
 
-The default workflow is serial. Agents should only create `parallel_execution` in `plan.yaml` when the user explicitly asks for multi-agent, parallel or multi-worktree execution.
+The default workflow evaluates each stage task for safe parallelism. When the task can be split safely, the main agent creates `parallel_execution.trigger: "workflow_default"` in `plan.yaml` and uses Codex native subagents first. If the task is not safe to split, the main agent keeps the workflow serial and records the reason. Explicit user requests for multi-agent, parallel or multi-worktree execution use `trigger: "user_requested"`.
 
-- `runtime_managed`: use only when the current agent runtime can spawn subagents. The main agent assigns workers, waits for results, reviews, merges or cherry-picks, and runs the total gate.
+- `runtime_managed` with `runtime.provider: "codex_native_subagents"`: the default path. The main agent assigns workers, waits for results, reviews, merges or cherry-picks, and runs the total gate.
 - `user_orchestrated`: use when the runtime cannot spawn subagents. The main agent generates copyable worker prompts, and the user manually opens Codex conversations or worktrees and pastes them.
+- `codex_exec_worktree`: fallback for high-risk writes or user-requested hard isolation. The first version does not add a `sdlc-harness parallel run` CLI.
 
 `parallel_execution` does not store duplicate current phase or current task fields. Agents read phase from `<harnessRoot>/state/lifecycle.yaml#current_phase` and task selection from `<harnessRoot>/state/plan.yaml#current_task_id`.
 
-The CLI does not promise to automatically launch Codex agents. Workers do not need to communicate with each other; the main agent owns final fact-source updates such as PRD, plan, implementation docs, test results and generated overviews.
+SPRINTING write workers must use disjoint `owned_paths`, and each owned path must be within the current task `allowed_paths`. Workers do not own final PRD, plan, implementation docs, review/test/release reports, generated overviews or release actions; the main agent remains the integration owner.
 
 ## Stage Task Control
 
@@ -80,7 +82,7 @@ Release docs are current-state facts, not a version ledger. New release work sho
 
 The generic rule is that any workflow promoting a draft task into a formal `TASK-*` in `plan.yaml` must remove the source draft from its draft queue in the same state update. The formal task is then recovered only from `plan.yaml`; completed history lives in implementation docs, git, PR and CI records. The built-in Harness draft queue is currently `plan.draft.yaml.tasks[]`, which means unadopted development drafts only. `/devloop` treats the development queue as exhausted only when both `plan.yaml.tasks[]` and `plan.draft.yaml.tasks[]` have no executable task.
 
-Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING`, the PM workflow updates the PRD through one `TASK-*`, then `validate-pm` and `python3 tools/transition.py --to ARCHITECTING` return the project to design. Requirement changes after `SPRINTING` still use RFC recalibration.
+Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING`, the PM workflow updates the PRD through one `TASK-*`, then `validate-pm` and `python3 tools/transition.py --to ARCHITECTING` return the project to design. Requirement or design changes after `SPRINTING` use RFC recalibration; `SPRINTING`, `REVIEWING`, `TESTING` and `RELEASING` can enter the controlled interrupt with `python3 tools/transition.py --to RFC_RECALIBRATION`, then return to `SPRINTING` after `validate-rfc`.
 
 `validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths.
 

package/assets/agents/AGENTS_CORE.md

@@ -168,12 +168,12 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 - “开始开发 / 做当前任务 / 做下一个任务” → 等价 `/dev`。
 - “开始循环：写任务，执行任务 / 把开发循环跑完” → 等价 `/devloop`。
 - “跑测试 / 验证一下” → 运行当前 task 或阶段对应 gate。
-- “并行 / 多 agent / 多 worktree / parallel” → 只有用户显式提出时，才创建或使用 `parallel_execution` 合同；默认 workflow 不启用并行。
+- 每个阶段任务开始时，默认先做 parallel eligibility check；适合安全拆分时，主 Agent 创建或使用 `parallel_execution.trigger: "workflow_default"` 并调度 Codex native subagents。用户说“并行 / 多 agent / 多 worktree / parallel” → 使用 `trigger: "user_requested"` 强化该意图。
 - “准备 review / 帮我 review” → 进入只读 Review workflow。
 - “刷新文档总览 / 同步 overview” → 等价 `/overview`。
 - `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；用户可以手动组合，例如 `/plan /prd`、`/plan 完善产品方案`、`/goal /devloop` 或 `/goal 开始循环：写任务，执行任务`。
 
-Parallel Execution 是可选协作协议，不是默认模式，也不是 CLI 自动启动 Agent 的承诺。只有用户明确要求多 agent、并行或多 worktree，且当前阶段适合拆分时，Agent 才能在 `plan.yaml` 增加 `parallel_execution`。`parallel_execution` 不保存 `phase` 或 `linked_task_id`；当前阶段读取 `lifecycle.yaml#current_phase`，当前任务读取 `plan.yaml#current_task_id`。如果当前 runtime 支持 subagent，由主 Agent 使用 `runtime_managed` 模式编排；否则使用 `user_orchestrated` 模式，主 Agent 生成每个 worker 的可复制 prompt，用户手动打开对话或 worktree 后粘贴执行。worker 之间不要求通信，最终事实源更新、review、merge/cherry-pick 和总 gate 由主 Agent 负责。
+Parallel Execution 是默认评估、按需启用的协作协议。`parallel_execution` 只在实际并行时写入 `plan.yaml`，不保存 `phase` 或 `linked_task_id`；当前阶段读取 `lifecycle.yaml#current_phase`，当前任务读取 `plan.yaml#current_task_id`。默认模式是 `runtime_managed` + `runtime.provider: "codex_native_subagents"`，由主 Agent 明确调度 Codex native subagents；如果 runtime 不可用则降级为 `user_orchestrated`，需要强隔离时可使用 `codex_exec_worktree` fallback。worker 之间不要求通信，最终事实源更新、review、merge/cherry-pick、总 gate、SPRINTING 两段提交和发布动作都由主 Agent 负责。
 
 如果自然语言意图会改变阶段、创建或删除 task、提交、push 或发布，Agent 先用一句话说明将执行的动作和验证方式，再继续。
 

package/assets/docs/README.md

@@ -64,10 +64,11 @@ npx sdlc-harness init --adopt
 | 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
 | 阶段小任务管控 | `plan.yaml`、`make validate-plan` | 每个阶段的 Agent 主任务都应拆成足够小的 `TASK-*` open task，并用 `phase` 标明所属阶段 |
 | 自然语言控制 | `AGENTS.md` + workflow skills | 用户可说“继续”“开始开发”“跑测试”“需求变了”等，由 Agent 映射到 `/next`、`/dev`、`/test`、RFC 等动作 |
-| 可选并行执行合同 | `plan.yaml#parallel_execution` | 用户明确要求多 agent/并行/多 worktree 时启用；支持 runtime-managed subagents 或 user-orchestrated worker prompts |
+| 默认并行调度合同 | `plan.yaml#parallel_execution` | 阶段任务默认评估是否可安全并行；适合时优先使用 Codex native subagents，并保留 user-orchestrated / worktree fallback |
 | Workflow skills | `<harnessRoot>/skills/pjsdlc_*/SKILL.md` | 提供 PM、架构、开发、实现文档、Review、测试、发布、RFC 等阶段角色提示词 |
 | 阶段角色提示词本地追加 | `<harnessRoot>/pjsdlc_managed/override_skills/<skill_name>.md` + `sync` | 用户不改 managed Skill，通过本地 override 追加项目规则，下一次 sync/upgrade 会重新合成 |
 | 本地策略覆盖 | `<harnessRoot>/pjsdlc_managed/policies/*.local.yaml` | 保留项目自己的策略补充，不和包内默认策略混写 |
+| Harness Python tools | `tools/*.py` | package-managed 本地 workflow tools，包括 `transition.py`、validators 和 overview 生成器；`init/sync/upgrade` 会生成或更新这些脚本 |
 | Agent 可读用户指南 | `node_modules/agent-project-sdlc/assets/docs/README.md` | npm 包内附带本仓库根 README，方便用户 Agent 在安装包中读取完整工作流说明 |
 | 文档 overview | `make docs-overview`、`make validate-doc-overviews` | 从 `.docs/**` facts 生成各阶段 overview，避免手写派生视图 |
 | 包源码一致性检查 | `sdlc-harness package sync-source`、`sdlc-harness package check-source` | 供本仓库维护者同步和检查 package canonical assets，避免源码与发布内容漂移 |
@@ -101,7 +102,7 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc 和执行顺序；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
 
-在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流，完成 PRD task 和 `validate-pm` 后，再用 `python3 tools/transition.py --to ARCHITECTING` 回到设计阶段。进入 `SPRINTING` 后的需求变化仍走 RFC workflow。
+在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流，完成 PRD task 和 `validate-pm` 后，再用 `python3 tools/transition.py --to ARCHITECTING` 回到设计阶段。进入 `SPRINTING` 后的需求或设计变化走 RFC workflow；`SPRINTING`、`REVIEWING`、`TESTING` 和 `RELEASING` 都可以通过 `python3 tools/transition.py --to RFC_RECALIBRATION` 进入受控 RFC 中断，RFC 完成后回到 `SPRINTING` 重新完成开发自测和 handoff。
 
 `validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。可运行边界类 draft task 还必须带 `self_test_contract`，并在 tech plan 中有 `Development Self-Test Contract`；合同必须记录 `module_key_test_path`，说明从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。
 
@@ -156,16 +157,17 @@ override 文件支持两种写法：普通项目追加片段，或带 `name`/`de
 
 `sync` 会把通用 Skill 和本地 override 合成到最终 `SKILL.md`。v1 只支持追加覆盖，不替换 package base Skill；`<skill_name>` 必须匹配已有 workflow Skill，例如 `pjsdlc_pm_prd`、`pjsdlc_architect_design` 或 `pjsdlc_dev_sprint`。合并后应由用户或用户的 Agent 检查 base Skill 与 local override 是否存在语义冲突，尤其是阶段边界、`allowed_paths`、`required_gates`、提交/发布规则和完成检查。
 
-### 可选并行执行
+### 默认并行调度
 
-默认 workflow 是串行的。只有用户明确说“并行”“多 agent”或“多 worktree”时，Agent 才能在 `plan.yaml` 创建 `parallel_execution` 合同。
+默认 workflow 会先评估当前阶段 task 是否适合安全并行。适合拆分时，主 Agent 在 `plan.yaml` 创建 `parallel_execution.trigger: "workflow_default"` 合同，并优先使用 Codex native subagents；不适合拆分时继续串行并记录原因。用户明确说“并行”“多 agent”或“多 worktree”时，使用 `trigger: "user_requested"` 强化该意图。
 
-- `runtime_managed`：当前 Agent runtime 支持创建 subagent 时，由主 Agent 分配 worker、等待结果、review、merge/cherry-pick 并跑总 gate。
-- `user_orchestrated`：runtime 不能自动创建 subagent 时，主 Agent 生成每个 worker 的可复制 prompt；用户手动打开多个对话或 worktree 后粘贴执行。
+- `runtime_managed` + `runtime.provider: "codex_native_subagents"`：默认路径。主 Agent 分配 worker、等待结果、review、merge/cherry-pick 并跑总 gate。
+- `user_orchestrated`：runtime 不能创建 subagent 时，主 Agent 生成每个 worker 的可复制 prompt；用户手动打开多个对话或 worktree 后粘贴执行。
+- `codex_exec_worktree`：高风险写入或用户要求强隔离时的 fallback；第一版不新增 `sdlc-harness parallel run` CLI。
 
 `parallel_execution` 不保存当前阶段或当前任务副本；阶段只从 `lifecycle.yaml#current_phase` 读取，当前任务只从 `plan.yaml#current_task_id` 读取。
 
-Harness CLI v1 不承诺自动启动 Codex agent，也不要求 worker 之间通信。worker 只处理自己的 `owned_paths` 和 gate，最终 PRD、plan、implementation doc、test result、overview 等事实源由主 Agent 集成。
+SPRINTING 写入 worker 必须使用互不重叠的 `owned_paths`，且这些路径必须落在当前 task `allowed_paths` 内。worker 不直接拥有最终 PRD、plan、implementation doc、review/test/release report、overview 或发布动作；这些事实源和收尾动作仍由主 Agent 集成。
 
 常用快捷入口：
 

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -23,6 +23,8 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 
 如果在 `ARCHITECTING` 中发现 PRD 缺失、验收标准不清或产品边界需要调整，且项目尚未进入 `SPRINTING`，不要用架构文档替代产品事实。先收尾或移除当前 open design task，再请 Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改 `.docs/01_product/**`。进入 `SPRINTING` 后的需求变化走 RFC workflow。
 
+架构阶段默认先评估是否适合并行调研或方案拆解。适合时，主 Agent 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别做架构草稿、接口分析、风险清单或方案对比；用户明确要求并行时使用 `trigger: "user_requested"`。worker 不直接写最终 architecture、tech plan、ADR 或 `plan.draft.yaml`，最终事实源和任务草案由主 Agent 合成；不适合拆分时保持串行并记录原因。
+
 ## 输入
 
 - `.docs/INDEX.md`

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -25,7 +25,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。直接运行 `make validate-dev` 或 `npx sdlc-harness validate-dev` 是开发中 gate，允许当前 `SPRINTING` task 仍然 open，并校验 `current_task_id`、task 合同、dirty files、draft queue 和 implementation doc。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。`make validate-current` / `/advance` 是阶段出口 gate，必须在 open task 已移除后才通过。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
-如果用户明确要求并行、多 agent 或多 worktree，开发阶段可以启用可选 `parallel_execution`。主 Agent 先创建合同，声明每个 worker 的 `branch`、`worktree`、`owned_paths`、`forbidden_paths`、`expected_output` 和 `required_gates`。worker 可以在各自 owned paths 内实现，但不得直接修改 `plan.yaml`、`lifecycle.yaml`、`.docs/INDEX.md`、overview 或最终 implementation doc。主 Agent 负责 review、merge/cherry-pick、运行总 gate、更新事实源和完成两段提交。没有用户显式要求时，继续使用串行 `/dev` 或 `/devloop`。
+开发阶段默认先评估当前 task 是否能安全并行。适合时，主 Agent 创建 `parallel_execution.trigger: "workflow_default"` 合同，默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"` 调度 worker；用户明确要求并行、多 agent 或多 worktree 时使用 `trigger: "user_requested"`。主 Agent 声明每个 worker 的 `owned_paths`、`forbidden_paths`、`expected_output` 和 `required_gates`；非 native fallback 写仓库时还要声明 `branch` 和 `worktree`。worker 可以在各自非空、互不重叠且属于当前 task `allowed_paths` 的 owned paths 内实现，但不得直接修改 `plan.yaml`、`lifecycle.yaml`、`.docs/INDEX.md`、overview 或最终 implementation doc。主 Agent 负责 review、merge/cherry-pick、运行总 gate、更新事实源和完成两段提交。不适合拆分时继续串行 `/dev` 或 `/devloop` 并记录原因。
 
 ## 输入
 
@@ -63,7 +63,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
 - `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 `TASK-*` open task；如果从 `plan.draft.yaml.tasks[]` 采用 draft，必须同次从 draft 列表删除源项；已有 open task 时，直接执行该 task；完成后停止。
 - `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、`plan.yaml`、`plan.draft.yaml`、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有 open task 且没有未采用 draft，或出现 blocker 时停止并报告。
-- Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行从 lifecycle 的 `current_phase` 和 plan 的 `current_task_id` 推断上下文，不在 `parallel_execution` 内重复保存。
+- Parallel Execution 是当前 task 的默认评估协作方式，不替代 task completion protocol；`SPRINTING` 并行从 lifecycle 的 `current_phase` 和 plan 的 `current_task_id` 推断上下文，不在 `parallel_execution` 内重复保存。
 
 ## Plan Protocol
 
@@ -96,8 +96,8 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 13. 默认不追溯已完成 task 的执行流水；只有显式 forensic/audit/regression 任务才临时查询 git、PR 或 CI 记录。
 14. 两个 commit 后必须 `git push` 到当前 upstream branch；如果没有 remote/upstream、权限或凭证导致无法 push，停止推进并报告 blocker。
 15. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、draft、代码或远端状态未变化。
-16. 只有用户明确要求并行、多 agent 或多 worktree 时，才允许创建 `parallel_execution`；否则不得默认并行。
-17. `runtime_managed` 只在当前 runtime 支持 subagent 时使用；没有该能力时，输出 `user_orchestrated` worker prompt，由用户手动打开对话或 worktree 后粘贴。
+16. 每个开发 task 开始时默认评估是否适合并行；适合时使用 `parallel_execution.trigger: "workflow_default"`，用户明确要求并行、多 agent 或多 worktree 时使用 `trigger: "user_requested"`。
+17. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；没有 native subagent 能力时输出 `user_orchestrated` worker prompt，由用户手动打开对话或 worktree 后粘贴；高风险写入或用户要求强隔离时可使用 `codex_exec_worktree` fallback。
 18. worker 不更新主事实源；主 Agent 才能更新 `plan.yaml`、`.docs/INDEX.md`、overview、implementation doc 和最终 gate 证据。
 
 ## 完成检查

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -20,7 +20,7 @@ Skill、执行出口 gate，并记录 blocker。
 
 自然语言和宏指令必须进入同一组 workflow action；区别在于 `/xxx` 入口携带更稳定的细节约束，简单自然语言入口更低成本，但需要你根据当前阶段、plan 和文档上下文补足细节。
 
-Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多 agent”“多 worktree”或等价意图时，才允许创建或使用 `parallel_execution`。不要因为任务看起来可拆就默认启用。当前 runtime 有 subagent 能力时，主 Agent 可使用 `runtime_managed` 编排；没有该能力时，使用 `user_orchestrated`，输出 worker prompts 让用户手动多开对话或 worktree。无论哪种模式，主 Agent 都是 coordinator 和 integration owner。
+Parallel Execution 是默认评估、按需启用：每个阶段 task 开始时，主 Agent 先做 parallel eligibility check；任务能安全拆分时创建或使用 `parallel_execution.trigger: "workflow_default"`，默认通过 `runtime_managed` + `runtime.provider: "codex_native_subagents"` 调度 Codex native subagents；不适合拆分时保持串行并在 task notes 或输出中简短记录原因。用户明确提出“并行”“多 agent”“多 worktree”或等价意图时，使用 `trigger: "user_requested"`。native subagent 不可用时降级为 `user_orchestrated`；高风险写入或用户要求强隔离时可使用 `codex_exec_worktree` fallback。无论哪种模式，主 Agent 都是 coordinator 和 integration owner。
 
 ## 输入
 
@@ -50,8 +50,8 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；如果 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft；否则说明当前阶段冲突和推荐路径。
 18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
 19. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
-20. 用户明确要求并行、多 agent 或多 worktree 时，先判断当前阶段是否是 `REQUIREMENT_GATHERING`、`SPRINTING` 或 `TESTING`；如果是，生成或使用 `parallel_execution.trigger: "user_requested"` 合同；否则说明当前阶段不支持并行合同。
-21. `runtime_managed` 模式只在当前 Agent runtime 真实具备 subagent 能力时使用；否则使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt。
+20. 每个阶段 task 开始时先判断当前阶段和当前 task 是否适合并行；如果适合，生成或使用 `parallel_execution.trigger: "workflow_default"` 合同；如果用户明确要求并行、多 agent 或多 worktree，使用 `trigger: "user_requested"`。
+21. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；native subagent 不可用时使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt；高风险写入或用户要求强隔离时可选择 `codex_exec_worktree` fallback。
 22. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
 23. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
 24. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
@@ -63,7 +63,7 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 
 `/prd`、`/design`、`/dev`、`/review`、`/test`、`/release` 和 `/rfc` 都是单 task 推进：默认只完成一个 `TASK-*`。`validate-plan` 用于检查当前 open task 合同是否完整。direct `validate-dev` / `make validate-dev` 是 `SPRINTING` 开发中 gate，允许一个合法当前 open task 存在；`validate-current` / `/advance` 在 `SPRINTING` 下仍是阶段出口 gate，要求没有 open task 残留。其它阶段出口 gate `validate-pm`、`validate-design`、`validate-review`、`validate-test`、`validate-release` 和 `validate-rfc` 也要求没有 open task 残留。
 
-`parallel_execution` 是可选顶层合同，缺省表示串行。启用后必须声明 `enabled`、`trigger`、`mode`、`coordinator`、`workers` 和 `integration`；不要在合同内重复保存 `phase` 或 `linked_task_id`，当前阶段来自 lifecycle 的 `current_phase`，当前任务来自 plan 的 `current_task_id`。
+`parallel_execution` 是按需顶层合同，缺省表示当前 task 串行。启用后必须声明 `enabled`、`trigger`、`mode`、`coordinator`、`workers` 和 `integration`；默认并行还应声明 `runtime.provider: "codex_native_subagents"`。不要在合同内重复保存 `phase` 或 `linked_task_id`，当前阶段来自 lifecycle 的 `current_phase`，当前任务来自 plan 的 `current_task_id`。
 
 `lifecycle.yaml` 和 `plan.yaml` 只用于当前可执行状态。默认不要读取过去 phase/task/gate 执行流水；只有用户明确要求 forensic/audit/regression 追溯时，才临时查询 git、PR、CI 或 release 记录。
 

package/assets/skills/pjsdlc_pm_prd/SKILL.md

@@ -21,7 +21,7 @@ PRD 产出本身是 workflow task，而不是一次性长文档生成。无论
 
 如果项目已经进入 `ARCHITECTING` 但尚未进入 `SPRINTING`，用户发现 PRD 需要补充或调整时，Manager 可以先通过 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到本 Skill。此时按正常 PRD task protocol 修改 `.docs/01_product/**`，完成后再通过 `validate-pm` 回到 `ARCHITECTING`；进入 `SPRINTING` 后的需求变化仍走 RFC workflow。
 
-如果用户在需求阶段明确要求并行、多 agent 或多 worktree，Parallel Execution 只能用于调研、草稿、场景拆解、风险列表或 open questions 收集。worker 不直接写最终 PRD；主 Agent 必须合成最终 `.docs/01_product/**`，并把假设、分歧和未决项写入 PRD。没有用户显式要求时，不要启用 `parallel_execution`。
+需求阶段默认先评估是否适合并行调研。适合时，主 Agent 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 收集调研、草稿、场景拆解、风险列表或 open questions；用户明确要求并行时使用 `trigger: "user_requested"`。worker 不直接写最终 PRD；主 Agent 必须合成最终 `.docs/01_product/**`，并把假设、分歧和未决项写入 PRD。不适合拆分时保持串行并记录原因。
 
 ## 输入
 
@@ -68,7 +68,7 @@ PRD 产出本身是 workflow task，而不是一次性长文档生成。无论
 4. 如果需求与既有架构或已接受决策冲突，先写冲突说明，不要直接编写技术方案。
 5. 需求阶段一次只执行一个 `TASK-*` task；不要在单次回复里创建或改写大量 PRD slices。
 6. `make validate-pm` 是阶段出口 gate；如果还有 open `TASK-*` PRD task，不要请求进入 `ARCHITECTING`。
-7. 需求阶段并行必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+7. 需求阶段默认评估并行；workflow 默认触发使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"`，用户显式要求并行时使用 `trigger: "user_requested"`；native subagent 不可用时输出 `user_orchestrated` worker prompt。
 8. 本 Skill 不直接进入开发；PRD 完成后请求 `manager` 运行阶段出口 gate。
 
 ## 完成检查
@@ -81,7 +81,7 @@ PRD 产出本身是 workflow task，而不是一次性长文档生成。无论
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已判断是否需要新增、拆分、合并或废弃 PRD slice。
 - [ ] 如果用户要求把完整 PRD/产品方案切成 slices，已删除被替代的完整文件，并保留必要的 `.docs/00_raw/` 原始记录。
-- [ ] 如果用户要求并行，worker output 已由主 Agent 合成，最终 PRD 不由 worker 直接写入。
+- [ ] 如果启用了并行，worker output 已由主 Agent 合成，最终 PRD 不由 worker 直接写入。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] `make validate-pm` 准备通过。

package/assets/skills/pjsdlc_release_manager/SKILL.md

@@ -19,6 +19,8 @@ Current release status 面向当前发布决策，必须说明版本、变更价
 
 发布准备本身也是 workflow task。开始 release 工作前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RELEASING"`；当前轮只更新 `.docs/08_release/CURRENT_RELEASE.md` 中的当前发布状态、一次 smoke evidence 补充、一个部署检查或一个 rollback plan 单元。发布动作本身仍需用户明确授权。
 
+发布阶段默认先评估是否适合并行 read-only preflight。适合时，主 Release Manager 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别检查 release notes、build artifacts、smoke evidence、known limitations 或 rollback risk；用户明确要求并行时使用 `trigger: "user_requested"`。RELEASING worker 必须 `writes_repo: false`，不得执行 publish、tag、push、delete、deploy 或生产变更；最终 `CURRENT_RELEASE.md`、发布结论和任何真实发布动作由主 Release Manager 负责。
+
 ## 输入
 
 - `<harnessRoot>/state/plan.yaml`

package/assets/skills/pjsdlc_reviewer/SKILL.md

@@ -21,6 +21,8 @@ Review 必须把“当前模块没有可运行入口/出口”视为阻断项，
 
 Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REVIEWING"`；当前轮只产出一个 review batch、一个风险主题 slice 或一次 PR review 结论。不要在一个任务里覆盖多个互不相关的 review 主题。
 
+Review 阶段默认先评估是否适合并行只读审查。适合时，主 Reviewer 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别检查需求一致性、架构风险、测试缺口、runnable entry/exit 或安全风险；用户明确要求并行时使用 `trigger: "user_requested"`。worker 必须 `writes_repo: false`，只提交 findings 和证据；最终 `REVIEW_REPORT.md` 与 PASS/BLOCKED 结论由主 Reviewer 汇总。
+
 ## 输入
 
 - `<harnessRoot>/state/plan.yaml`

package/assets/skills/pjsdlc_rfc_recalibrate/SKILL.md

@@ -23,6 +23,8 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 
 RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RFC_RECALIBRATION"`；当前轮只处理一个 RFC 文件、一个 impact analysis 单元或一个局部补丁单元。
 
+RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Agent 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别检查 docs、state、skills、policies、templates、tools、package assets、tests、migrations 或 generated artifacts 影响；用户明确要求并行时使用 `trigger: "user_requested"`。worker 必须 `writes_repo: false`，只提交影响面、patch candidates 和风险清单；最终 RFC、事实源补丁和任务调整由主 Agent 汇总。
+
 ## 输入
 
 - `.docs/rfc/RFC_*.md`

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -21,7 +21,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 
 测试设计和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试策略 slice、测试用例 slice、回归批次、风险验证片区或一组 scoped test changes。`plan.yaml` 仍是唯一执行计划事实源，`.docs/07_test/**` 只记录当前方案的 test strategy、test cases、executed regression evidence、coverage gaps 和 final decision，不表达“下一步如何开发”，也不保留已被 RFC supersede 的旧测试结果。
 
-如果用户明确要求并行、多 agent 或多 worktree，测试阶段可以启用 `parallel_execution`，让 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。没有用户显式要求时，测试 workflow 保持串行。
+测试阶段默认先评估是否适合并行验证。适合时，主 Tester 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证；用户明确要求并行时使用 `trigger: "user_requested"`。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。不适合拆分时保持串行并记录原因。
 
 ## 输入
 
@@ -75,7 +75,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 6. 新测试策略使用 `.docs/07_test/TEST_STRATEGY.md`，新测试用例使用 `.docs/07_test/TEST_CASES.md`，执行报告使用 `.docs/07_test/TEST_REPORT.md`；不要新建或继续依赖 `.docs/07_test/TEST_PLAN.md`。
 7. `TEST_REPORT.md` 不得包含 `pending`、`TBD`、`待填`、`TODO` 或占位结论；未执行或不可执行时 Final decision 必须为 `BLOCKED` 并给出恢复条件。
 8. RFC 改变技术路线、entry/exit 或验收边界后，必须确认 `.docs/07_test/**` 中旧路线测试证据已删除或不再从 `.docs/INDEX.md` 暴露。
-9. 并行测试必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+9. 测试阶段默认评估并行；workflow 默认触发使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"`，用户显式要求并行时使用 `trigger: "user_requested"`；native subagent 不可用时输出 `user_orchestrated` worker prompt。
 10. 宣布阶段完成前运行 `make test-all`。
 11. 测试阶段一次只执行一个 `TASK-*` task。
 

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -1,17 +1,20 @@
 current_task_id: "TASK-001"
 next_task_sequence: 2
-# Optional. Omit this block for normal serial workflow. Only add it when the
-# user explicitly asks for parallel / multi-agent / multi-worktree execution.
+# Optional top-level execution contract. Omit this block when the current task
+# stays serial after the default parallel eligibility check. Use
+# trigger: "workflow_default" when the workflow safely splits the task by
+# default; use trigger: "user_requested" when the user explicitly asks for
+# parallel / multi-agent / multi-worktree execution.
 # parallel_execution:
 #   enabled: true
-#   trigger: "user_requested"
-#   mode: "user_orchestrated" # or "runtime_managed" when the current agent runtime can spawn subagents
+#   trigger: "workflow_default"
+#   mode: "runtime_managed"
+#   runtime:
+#     provider: "codex_native_subagents" # fallbacks: user_orchestrated, codex_exec_worktree
 #   coordinator: "main_agent"
 #   workers:
 #     - id: "worker-feature"
 #       writes_repo: true
-#       branch: "agent/feature"
-#       worktree: "../project-feature"
 #       owned_paths:
 #         - "src/feature/**"
 #         - "tests/feature/**"

package/assets/tools/build_doc_overviews.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+from harness_utils import ROOT, HarnessError, require, run_main
+
+
+DOCS_ROOT = ROOT / ".docs"
+OUTPUT_NAME = "overview.md"
+LEGACY_OUTPUT_NAME = "overview.html"
+
+
+def stage_dirs() -> list[Path]:
+    require(DOCS_ROOT.exists(), "Missing .docs directory")
+    return sorted(path for path in DOCS_ROOT.iterdir() if path.is_dir() and not path.name.startswith("."))
+
+
+def resolve_stage(value: str) -> Path:
+    raw = Path(value)
+    path = raw if raw.is_absolute() else ROOT / raw
+    if not path.exists() and not value.startswith(".docs/"):
+        path = DOCS_ROOT / value
+    require(path.exists() and path.is_dir(), f"Stage directory not found: {value}")
+    require(DOCS_ROOT in path.parents or path == DOCS_ROOT, f"Stage must be under .docs/: {value}")
+    return path
+
+
+def markdown_files(stage: Path) -> list[Path]:
+    files = []
+    for path in sorted(stage.rglob("*.md")):
+        if any(part.startswith(".") for part in path.relative_to(stage).parts):
+            continue
+        if path.name in {OUTPUT_NAME, LEGACY_OUTPUT_NAME}:
+            continue
+        files.append(path)
+    return files
+
+
+def source_hash(files: list[Path], stage: Path) -> str:
+    digest = hashlib.sha256()
+    for path in files:
+        relative = path.relative_to(stage).as_posix()
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(path.read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()[:16]
+
+
+def markdown_link(label: str, target: str) -> str:
+    escaped_label = label.replace("[", "\\[").replace("]", "\\]")
+    escaped_target = target.replace(" ", "%20")
+    return f"[{escaped_label}]({escaped_target})"
+
+
+def markdown_document(stage: Path, files: list[Path]) -> str:
+    stage_name = stage.relative_to(ROOT).as_posix()
+    digest = source_hash(files, stage)
+    parts = [
+        f"# {stage_name} overview",
+        "",
+        "<!-- generated-by: AI SDLC Harness build_doc_overviews.py -->",
+        f"<!-- source-hash: {digest} -->",
+        "",
+        "Generated artifact. Markdown slices remain the source of truth.",
+        "",
+        f"Source hash: `{digest}`",
+        "",
+        "## Source Slices",
+        "",
+    ]
+
+    if not files:
+        parts.extend(["当前阶段还没有 Markdown slice。", ""])
+    else:
+        for index, path in enumerate(files, start=1):
+            relative = path.relative_to(stage).as_posix()
+            parts.append(f"{index}. {markdown_link(relative, relative)}")
+        parts.append("")
+
+    for path in files:
+        relative = path.relative_to(stage).as_posix()
+        content = path.read_text(encoding="utf-8").strip()
+        parts.extend(
+            [
+                "---",
+                "",
+                f"## {relative}",
+                "",
+                f"Source: {markdown_link(relative, relative)}",
+                "",
+                content if content else "空文档。",
+                "",
+            ]
+        )
+
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def write_overview(stage: Path, check: bool) -> bool:
+    files = markdown_files(stage)
+    output = stage / OUTPUT_NAME
+    legacy_output = stage / LEGACY_OUTPUT_NAME
+    rendered = markdown_document(stage, files)
+    if check:
+        if legacy_output.exists():
+            print(f"Legacy {legacy_output.relative_to(ROOT)} remains")
+            return False
+        if not output.exists():
+            print(f"Missing {output.relative_to(ROOT)}")
+            return False
+        existing = output.read_text(encoding="utf-8")
+        if existing != rendered:
+            print(f"Outdated {output.relative_to(ROOT)}")
+            return False
+        print(f"OK {output.relative_to(ROOT)}")
+        return True
+    if legacy_output.exists():
+        legacy_output.unlink()
+    output.write_text(rendered, encoding="utf-8")
+    print(f"Wrote {output.relative_to(ROOT)}")
+    return True
+
+
+def selected_stages(args: argparse.Namespace) -> list[Path]:
+    if args.stage:
+        return [resolve_stage(value) for value in args.stage]
+    return stage_dirs()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build deterministic Markdown overviews for .docs stage slices")
+    parser.add_argument("--stage", action="append", help="Stage directory, e.g. .docs/01_product or 01_product")
+    parser.add_argument("--all", action="store_true", help="Build all .docs stage directories")
+    parser.add_argument("--check", action="store_true", help="Check whether overview.md files are up to date")
+    args = parser.parse_args()
+
+    stages = selected_stages(args)
+    require(stages, "No .docs stage directories found")
+    ok = True
+    for stage in stages:
+        ok = write_overview(stage, args.check) and ok
+    if not ok:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_main(main)