agent-project-sdlc 0.1.7 → 0.1.8

package/README.md

@@ -28,6 +28,7 @@ npx sdlc-harness init --adopt
 | Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks phase deliverables, active plan shape, prompt language contract and generated overview freshness. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
 | 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. |
 | 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. |
@@ -56,7 +57,16 @@ Then run:
 npx sdlc-harness sync
 ```
 
-The sync output is the package base Skill plus one appended `Local Override` block. Unknown skill names block sync so misspellings do not silently fail.
+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
+
+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.
+
+- `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.
+- `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.
+
+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.
 
 ## Common Commands
 

package/assets/agents/AGENTS_CORE.md

@@ -162,10 +162,13 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 - “开始开发 / 做当前任务 / 做下一个任务” → 等价 `/dev`。
 - “开始循环：写任务，执行任务 / 把开发循环跑完” → 等价 `/devloop`。
 - “跑测试 / 验证一下” → 运行当前 task 或阶段对应 gate。
+- “并行 / 多 agent / 多 worktree / parallel” → 只有用户显式提出时，才创建或使用 `parallel_execution` 合同；默认 workflow 不启用并行。
 - “准备 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`。如果当前 runtime 支持 subagent，由主 Agent 使用 `runtime_managed` 模式编排；否则使用 `user_orchestrated` 模式，主 Agent 生成每个 worker 的可复制 prompt，用户手动打开对话或 worktree 后粘贴执行。worker 之间不要求通信，最终事实源更新、review、merge/cherry-pick 和总 gate 由主 Agent 负责。
+
 如果自然语言意图会改变阶段、创建或删除 task、提交、push 或发布，Agent 先用一句话说明将执行的动作和验证方式，再继续。
 
 - `/status`：报告当前阶段、角色、任务、阻塞项和下一步动作。

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -19,6 +19,8 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
+如果用户明确要求并行、多 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`。
+
 ## 输入
 
 - `<harnessRoot>/state/lifecycle.yaml`
@@ -51,6 +53,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
 - `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 open task；已有 open task 时，直接执行该 task；完成后停止。
 - `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、plan、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有明确任务或出现 blocker 时停止并报告。
+- Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行必须用 `parallel_execution.linked_task_id` 绑定当前 `current_task_id`。
 
 ## Plan Protocol
 
@@ -81,6 +84,9 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 12. 默认不追溯已完成 task 的执行流水；只有显式 forensic/audit/regression 任务才临时查询 git、PR 或 CI 记录。
 13. 两个 commit 后必须 `git push` 到当前 upstream branch；如果没有 remote/upstream、权限或凭证导致无法 push，停止推进并报告 blocker。
 14. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、代码或远端状态未变化。
+15. 只有用户明确要求并行、多 agent 或多 worktree 时，才允许创建 `parallel_execution`；否则不得默认并行。
+16. `runtime_managed` 只在当前 runtime 支持 subagent 时使用；没有该能力时，输出 `user_orchestrated` worker prompt，由用户手动打开对话或 worktree 后粘贴。
+17. worker 不更新主事实源；主 Agent 才能更新 `plan.yaml`、`.docs/INDEX.md`、overview、implementation doc 和最终 gate 证据。
 
 ## 完成检查
 
@@ -89,6 +95,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
 - [ ] 当前任务仍然是单一清晰的执行单元。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
+- [ ] 如果启用了 `parallel_execution`，worker owned paths、forbidden paths、required gates 和主 Agent 集成结果已记录。
 - [ ] gate 结果已写入 implementation doc `Verification`，必要时当前 task `working_notes` 也记录了恢复现场所需的 gate evidence。
 - [ ] task implementation commit 已在 task 移除前创建。
 - [ ] done task 已在 implementation commit 之后从当前 `plan.yaml` 移除。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -20,6 +20,8 @@ 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。
+
 ## 输入
 
 - `<harnessRoot>/state/lifecycle.yaml`
@@ -48,15 +50,19 @@ Skill、执行出口 gate，并记录 blocker。
 17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 DEV task 并执行一个 task 闭环；否则说明当前阶段冲突和推荐路径。
 18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
 19. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
-20. 用户自然语言要求 review 时，进入只读 Review workflow，不直接改源码。
-21. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
-22. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
-23. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
+20. 用户明确要求并行、多 agent 或多 worktree 时，先判断当前阶段是否是 `REQUIREMENT_GATHERING`、`SPRINTING` 或 `TESTING`；如果是，生成或使用 `parallel_execution.trigger: "user_requested"` 合同；否则说明当前阶段不支持并行合同。
+21. `runtime_managed` 模式只在当前 Agent runtime 真实具备 subagent 能力时使用；否则使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt。
+22. 用户自然语言要求 review 时，进入只读 Review workflow，不直接改源码。
+23. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
+24. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
+25. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
 
 ## Plan Protocol
 
 每个 open task 都必须在 `plan.yaml` 中包含 `docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以模块、子系统或核心数据流级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
 
+`parallel_execution` 是可选顶层合同，缺省表示串行。启用后必须声明 `enabled`、`trigger`、`mode`、`phase`、`coordinator`、`workers` 和 `integration`；`SPRINTING` 并行还必须通过 `linked_task_id` 绑定当前 `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

@@ -17,6 +17,8 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 
 产出 PRD 时，优先让后续架构和测试能直接使用：每条需求应有清晰 requirement ID、验收条件、Out of Scope、风险或依赖。对话中出现新范围时，要判断是更新当前 slice、拆出新 slice，还是进入 RFC。
 
+如果用户在需求阶段明确要求并行、多 agent 或多 worktree，Parallel Execution 只能用于调研、草稿、场景拆解、风险列表或 open questions 收集。worker 不直接写最终 PRD；主 Agent 必须合成最终 `.docs/01_product/**`，并把假设、分歧和未决项写入 PRD。没有用户显式要求时，不要启用 `parallel_execution`。
+
 ## 输入
 
 - 用户需求或原始记录
@@ -45,7 +47,8 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 2. 每个 PRD 必须包含目标、用户场景、功能需求、验收标准、Out of Scope 和 Open Questions。
 3. 不确定内容必须写入 `Open Questions`，不要静默假设。
 4. 如果需求与既有架构或已接受决策冲突，先写冲突说明，不要直接编写技术方案。
-5. 本 Skill 不直接进入开发；PRD 完成后请求 `manager` 运行阶段出口 gate。
+5. 需求阶段并行必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+6. 本 Skill 不直接进入开发；PRD 完成后请求 `manager` 运行阶段出口 gate。
 
 ## 完成检查
 
@@ -54,6 +57,7 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 - [ ] Out of Scope 明确。
 - [ ] Open Questions 有 owner/status。
 - [ ] 已判断是否需要新增、拆分、合并或废弃 PRD slice。
+- [ ] 如果用户要求并行，worker output 已由主 Agent 合成，最终 PRD 不由 worker 直接写入。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] `make validate-pm` 准备通过。

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -17,6 +17,8 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过，应记录 blocker、已完成检查和恢复条件。
 
+如果用户明确要求并行、多 agent 或多 worktree，测试阶段可以启用 `parallel_execution`，让 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。没有用户显式要求时，测试 workflow 保持串行。
+
 ## 输入
 
 - `.docs/01_product/`
@@ -46,7 +48,8 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
-4. 宣布阶段完成前运行 `make test-all`。
+4. 并行测试必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+5. 宣布阶段完成前运行 `make test-all`。
 
 ## 完成检查
 
@@ -54,6 +57,7 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 - [ ] Regression checklist 已完成。
 - [ ] 已判断 test plan / test matrix 的语义切片边界。
 - [ ] Coverage gaps 已明确。
+- [ ] 如果启用了并行测试，worker evidence 已由主 Agent 汇总到测试产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] Final decision 是 `PASS` 或 `BLOCKED`。
 - [ ] `make validate-test` 准备通过。

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -1,6 +1,37 @@
 current_phase: "SPRINTING"
 current_task_id: "DEV-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.
+# parallel_execution:
+#   enabled: true
+#   trigger: "user_requested"
+#   mode: "user_orchestrated" # or "runtime_managed" when the current agent runtime can spawn subagents
+#   phase: "SPRINTING"
+#   coordinator: "main_agent"
+#   linked_task_id: "DEV-001"
+#   workers:
+#     - id: "worker-feature"
+#       writes_repo: true
+#       branch: "agent/feature"
+#       worktree: "../project-feature"
+#       owned_paths:
+#         - "src/feature/**"
+#         - "tests/feature/**"
+#       forbidden_paths:
+#         - "<harnessRoot>/state/**"
+#         - ".docs/INDEX.md"
+#       expected_output:
+#         - "implementation branch and focused gate evidence"
+#       required_gates:
+#         - "npm test -- tests/feature"
+#   integration:
+#     owner: "main_agent"
+#     merge_strategy: "main agent reviews worker output, merges or cherry-picks, then runs total gates"
+#     required_gates:
+#       - "make validate-current"
+#     fact_source_updates:
+#       - ".docs/04_implementation/"
 tasks:
   - id: "DEV-001"
     title: "实现示例任务"

package/dist/lib/init.js

@@ -51,7 +51,7 @@ async function createProjectState(projectRoot, root, report) {
     const files = [
         [
             harnessPath(root, "state", "lifecycle.yaml"),
-            `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "REQUIREMENT_GATHERING"\nactive_role: "pm"\nactive_skill: "pjsdlc_pm_prd"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "ARCHITECTING"\n`
+            `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n`
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],

package/dist/lib/sync-engine.js

@@ -4,6 +4,7 @@ import { harnessRoot } from "./harness-root.js";
 import { copyTree, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { AGENTS_BLOCK_MARKERS, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
 import { packageAssetPath } from "./paths.js";
+import { parseYaml, stringifyYaml } from "./yaml.js";
 export function emptySyncReport() {
     return {
         changed: [],
@@ -251,8 +252,23 @@ async function readSkillOverrides(projectRoot, root, knownSkills, report) {
         }
         const content = await readText(file);
         if (content.trim()) {
+            const fullSkill = parseFullSkillOverride(content);
+            if (fullSkill) {
+                if (fullSkill.name !== match[1]) {
+                    report.blocked.push(`skill override name mismatch: ${path.join(root, "pjsdlc_managed", "override_skills", relativePath)} declares name ${fullSkill.name}`);
+                    continue;
+                }
+                overrides.set(match[1], {
+                    relativePath: path.join(root, "pjsdlc_managed", "override_skills", relativePath),
+                    mode: "full-skill",
+                    content: fullSkill.body,
+                    description: fullSkill.description
+                });
+                continue;
+            }
             overrides.set(match[1], {
                 relativePath: path.join(root, "pjsdlc_managed", "override_skills", relativePath),
+                mode: "snippet",
                 content
             });
         }
@@ -271,6 +287,10 @@ function renderSkillWithOverride(baseContent, override) {
     if (!override) {
         return baseContent;
     }
+    const renderedBase = override.mode === "full-skill" ? mergeSkillDescription(baseContent, override.description) : baseContent;
+    const guidance = override.mode === "full-skill"
+        ? "The following project-local full Skill extension is appended by `sdlc-harness sync`. Its frontmatter has been merged into the generated Skill metadata; the body below remains the project-local extension."
+        : "The following project-local snippet is appended by `sdlc-harness sync`.";
     const header = [
         "",
         "",
@@ -278,10 +298,58 @@ function renderSkillWithOverride(baseContent, override) {
         "",
         `Source: \`${override.relativePath.split(path.sep).join("/")}\``,
         "",
-        "The following project-local instructions are appended by `sdlc-harness sync`. Keep package-managed Skill files unchanged; edit the override source instead.",
+        `${guidance} Keep package-managed Skill files unchanged; edit the override source instead.`,
+        "",
+        "After sync, review the merged Skill for semantic conflicts between the package base and local override, especially phase boundaries, `allowed_paths`, `required_gates`, commit/release rules and completion checks.",
         ""
     ].join("\n");
-    return `${baseContent.trimEnd()}${header}${override.content.trim()}\n`;
+    return `${renderedBase.trimEnd()}${header}\n${override.content.trim()}\n`;
+}
+function parseFullSkillOverride(content) {
+    const parsed = parseFrontmatter(content);
+    if (!parsed) {
+        return undefined;
+    }
+    const name = parsed.metadata.name;
+    const description = parsed.metadata.description;
+    if (typeof name !== "string" || typeof description !== "string") {
+        return undefined;
+    }
+    return { name, description, body: parsed.body };
+}
+function mergeSkillDescription(baseContent, overrideDescription) {
+    const parsed = parseFrontmatter(baseContent);
+    if (!parsed || typeof parsed.metadata.name !== "string" || typeof parsed.metadata.description !== "string") {
+        return baseContent;
+    }
+    const metadata = {
+        ...parsed.metadata,
+        name: parsed.metadata.name,
+        description: `${parsed.metadata.description} Project override: ${overrideDescription}`
+    };
+    return `---\n${stringifyYaml(metadata).trimEnd()}\n---\n${parsed.body.trimStart()}`;
+}
+function parseFrontmatter(content) {
+    if (!content.startsWith("---\n")) {
+        return undefined;
+    }
+    const endIndex = content.indexOf("\n---", 4);
+    if (endIndex < 0) {
+        return undefined;
+    }
+    let metadata;
+    try {
+        metadata = parseYaml(content.slice(4, endIndex));
+    }
+    catch {
+        return undefined;
+    }
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const bodyStart = content.indexOf("\n", endIndex + 4);
+    const body = bodyStart < 0 ? "" : content.slice(bodyStart + 1);
+    return { metadata: metadata, body };
 }
 async function syncFile(source, destination, report, missingMode) {
     if (!(await pathExists(source))) {

package/dist/lib/validators.js

@@ -5,6 +5,8 @@ import { harnessPath, harnessRoot } from "./harness-root.js";
 import { listFiles, pathExists, readText } from "./fs.js";
 import { parseYaml } from "./yaml.js";
 const execFileAsync = promisify(execFile);
+const PARALLEL_MODES = new Set(["runtime_managed", "user_orchestrated"]);
+const PARALLEL_PHASES = new Set(["REQUIREMENT_GATHERING", "SPRINTING", "TESTING"]);
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
@@ -88,6 +90,7 @@ async function validateDev(projectRoot) {
     const errors = [];
     const root = await harnessRoot(projectRoot);
     const tasksData = await readYamlObject(path.join(projectRoot, root, "state", "plan.yaml"));
+    validateParallelExecutionContract(tasksData, errors);
     const tasks = Array.isArray(tasksData.tasks) ? tasksData.tasks : [];
     const nextTaskSequence = tasksData.next_task_sequence;
     if (!Number.isInteger(nextTaskSequence) || Number(nextTaskSequence) <= 0) {
@@ -135,6 +138,98 @@ async function validateDev(projectRoot) {
     }
     return { info: [`validate-dev checked ${tasks.length} task(s)`], errors };
 }
+function validateParallelExecutionContract(plan, errors) {
+    const contract = plan.parallel_execution;
+    if (contract === undefined || contract === null)
+        return;
+    if (!isRecord(contract)) {
+        errors.push("parallel_execution must be a mapping");
+        return;
+    }
+    if (contract.enabled !== true)
+        errors.push("parallel_execution.enabled must be true when present");
+    if (contract.trigger !== "user_requested")
+        errors.push('parallel_execution.trigger must be "user_requested"');
+    if (!PARALLEL_MODES.has(String(contract.mode ?? ""))) {
+        errors.push("parallel_execution.mode must be runtime_managed or user_orchestrated");
+    }
+    if (!PARALLEL_PHASES.has(String(contract.phase ?? ""))) {
+        errors.push("parallel_execution.phase must be REQUIREMENT_GATHERING, SPRINTING, or TESTING");
+    }
+    if (contract.coordinator !== "main_agent")
+        errors.push('parallel_execution.coordinator must be "main_agent"');
+    if (contract.phase === "SPRINTING") {
+        if (!contract.linked_task_id)
+            errors.push("SPRINTING parallel_execution must define linked_task_id");
+        if (contract.linked_task_id !== plan.current_task_id) {
+            errors.push("SPRINTING parallel_execution.linked_task_id must match current_task_id");
+        }
+    }
+    const workers = contract.workers;
+    if (!Array.isArray(workers) || workers.length === 0) {
+        errors.push("parallel_execution.workers must be a non-empty list");
+    }
+    else {
+        const seen = new Set();
+        workers.forEach((worker, index) => {
+            const prefix = `parallel_execution.workers[${index}]`;
+            if (!isRecord(worker)) {
+                errors.push(`${prefix} must be a mapping`);
+                return;
+            }
+            const workerId = String(worker.id ?? "");
+            if (!workerId.trim()) {
+                errors.push(`${prefix}.id must be a non-empty string`);
+            }
+            else if (seen.has(workerId)) {
+                errors.push(`parallel_execution worker id must be unique: ${workerId}`);
+            }
+            seen.add(workerId);
+            if (typeof worker.writes_repo !== "boolean")
+                errors.push(`${prefix}.writes_repo must be a boolean`);
+            for (const field of ["owned_paths", "forbidden_paths", "expected_output", "required_gates"]) {
+                if (!Array.isArray(worker[field]))
+                    errors.push(`${prefix}.${field} must be a list`);
+            }
+            if (Array.isArray(worker.expected_output) && worker.expected_output.length === 0) {
+                errors.push(`${prefix}.expected_output must not be empty`);
+            }
+            if (Array.isArray(worker.required_gates) && worker.required_gates.length === 0) {
+                errors.push(`${prefix}.required_gates must not be empty`);
+            }
+            if (worker.writes_repo === true) {
+                if (typeof worker.branch !== "string" || !worker.branch.trim()) {
+                    errors.push(`${prefix}.branch is required when writes_repo is true`);
+                }
+                if (typeof worker.worktree !== "string" || !worker.worktree.trim()) {
+                    errors.push(`${prefix}.worktree is required when writes_repo is true`);
+                }
+                if (!Array.isArray(worker.owned_paths) || worker.owned_paths.length === 0) {
+                    errors.push(`${prefix}.owned_paths must not be empty when writes_repo is true`);
+                }
+            }
+        });
+    }
+    const integration = contract.integration;
+    if (!isRecord(integration)) {
+        errors.push("parallel_execution.integration must be a mapping");
+        return;
+    }
+    if (integration.owner !== "main_agent")
+        errors.push('parallel_execution.integration.owner must be "main_agent"');
+    if (typeof integration.merge_strategy !== "string" || !integration.merge_strategy.trim()) {
+        errors.push("parallel_execution.integration.merge_strategy must be a non-empty string");
+    }
+    if (!Array.isArray(integration.required_gates) || integration.required_gates.length === 0) {
+        errors.push("parallel_execution.integration.required_gates must be a non-empty list");
+    }
+    if (!Array.isArray(integration.fact_source_updates) || integration.fact_source_updates.length === 0) {
+        errors.push("parallel_execution.integration.fact_source_updates must be a non-empty list");
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function readYamlObject(filePath) {
     if (!(await pathExists(filePath)))
         return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {