@blxzer/pactile 0.5.0 → 0.6.0-beta.2

package/dist/templates/markdown/framework/middleware-protocol.md.txt

@@ -1,238 +1,139 @@
-# Middleware Protocol v1
-
-> 一种中间件。官方与用户同一契约，只靠 `source` 区分。字段名英文；正文跟 `artifact_locale`（当前 zh）。
->
-> Overlay（已拍）：项目 **`.pactile/middleware/`**。默认可进 git。`pactile init` / `pactile update` **永不写入、不删除、不纳入 `.template-hashes.json`**。历史残渣清理走独立 allow-list，不得误删本目录。
-
-Capability router 只声明 `exact` / `semantic` / `structural` / `external`，不绑 Agent 工具名。Manifest 的 `capability` 可以更细（例如 `browser-session`）；路由仍只按四意图，不绑工具名。
-
-## 双轨
-
-| 轨 | PACTILE 管什么 |
-| --- | --- |
-| 集成 | 本协议：Manifest + Profile + 健康。下表 **shipped** 各路属于此轨（含 MCP 传输）。 |
-| Extra | **未**出现在 shipped 表、也 **未**放入 overlay 的宿主 MCP / Agent 配置 → PACTILE 不管、不进健康表 |
-
-`pactile init` **不**写入 `.cursor/mcp.json`，也 **不**强制安装 Playwright / GitHub / codegraph / fast-context / chrome-cdp。默认 Profile 只把 **smart-search** 标为 required；其余 shipped 为 optional，有探测、缺了不挡无关任务。
-
-## 义务
-
-1. **一种 ABI。** `source: shipped | user` 不是两套协议。
-2. **Update 不顶掉。** 用户 overlay 不进模板 hash / 官方 refresh 写集。同 id：用户赢，并报告。
-3. **Secret。** Manifest 只许引用（环境变量名 / 平台 Secret），不许写密钥原文。日志与 Artifact 同样禁止。
-4. **权限。** 新权限首次启用走一次 Resolution Approval。后续 `update` 不得扩大已批权限；要扩大再批一次。
-5. **校验。** 缺必填字段则拒绝接入并说明，不得半接入。
-6. **Hook。** 只订 Event Bridge 已有事件。未订阅模块不得让 hook 失败。
-7. **协议版本。** Manifest 可带 `protocol: 1`。不兼容升级必须在应用前被发现。
-
-本条不实现安装器、不做商店、不改全局 MCP。可选日后加 `pactile middleware add`，非发布阻塞。
-
-## 生命周期
-
-添加（放入 overlay 的 Manifest）→ 启用/停用（Profile `required` / `optional` / `unset`）→ 移除（用户删 overlay，PACTILE 忘记）。
-
-停用 ≠ 删除文件。官方 shipped 可被用户停用，不得被 `update` 强行再打开。`update` 可刷新 shipped 声明，但不得删用户 overlay，也不得在用户停用后自动重装实现。
-
-同一 capability 多个 Provider：Profile 选一个 active；其余 standby。不得静默抢当前 active。
-
-## 传输类
-
-`transport` 取其一：`skill+cli` | `mcp` | `skill` | `hook`。未登记且未写入 overlay 的宿主配置，PACTILE 不管。
-
-## 发现与健康
-
-发现方式：在 `.pactile/middleware/` 放 Manifest。缺必填字段则拒绝接入。shipped 声明由产品登记；用户 overlay 同 id 时用户赢。
-
-Status / Continue 在任务需要该 capability 时展示 `ready` / `missing` / `failed` / `degraded`。未登记且未 overlay 的 Extra MCP 不进健康表。
-
-## 第一波 shipped（不挡用户自添）
-
-默认 Profile：仅 **smart-search** = `required`。其余 = `optional`（探测缺失则 missing/degraded，不挡不需要该能力的任务）。**pactile-byok** 仍只占位，本批无实现。
-
-| Provider | Profile | capability | transport | 说明 |
-| --- | --- | --- | --- | --- |
-| smart-search | required `external-knowledge` | external-knowledge | skill+cli | 独立包；缺失则 degrade |
-| codegraph | optional | structural | mcp | 默认不装；不进 always-on |
-| fast-context | optional | semantic | mcp | 默认不装；Native `@codebase` 不是这一路 |
-| chrome-cdp | optional | browser-session | skill+cli | 源仓 **blaze-skills/chrome-cdp**；贴已开调试的本机 Chrome。PACTILE 不以「自带 skill」为唯一叙事 |
-| playwright | optional | browser-automation | mcp | `@playwright/mcp`；可复现自动化。与 chrome-cdp 不合并 |
-| github | optional | vcs-host | mcp | 官方 GitHub MCP；密钥只引用 |
-| cursor-ide-browser | optional | ide-browser | mcp | Cursor **宿主**注入；无独立 npm。非 Cursor 会话 = missing。不得用平台 WebSearch 冒充 |
-| pactile-byok | optional 占位 | — | — | **实现与发版延后**；不带 BYOK 安装 |
-
-## Manifest 样例
-
-### smart-search
-
-```yaml
-id: smart-search
-protocol: 1
-capability: external-knowledge
-source: shipped
-ownership:
-  kind: external-package
-  name: smart-search
-transport: skill+cli
-profile: required
-readiness:
-  probe: cli
-  command_hint: smart-search doctor
-on_missing: degrade
-permissions:
-  network: true
-  shell: true
-  secrets: true
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-### codegraph
-
-```yaml
-id: codegraph
-protocol: 1
-capability: structural
-source: shipped
-ownership:
-  kind: external-package
-  name: "@colbymchenry/codegraph"
-transport: mcp
-profile: optional
-readiness:
-  probe: mcp
-  command_hint: npx @colbymchenry/codegraph serve --mcp
-on_missing: degrade
-permissions:
-  network: false
-  shell: true
-  secrets: false
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-### fast-context
-
-```yaml
-id: fast-context
-protocol: 1
-capability: semantic
-source: shipped
-ownership:
-  kind: external-package
-  name: fast-context-mcp
-transport: mcp
-profile: optional
-readiness:
-  probe: mcp
-  command_hint: npx -y fast-context-mcp
-on_missing: degrade
-permissions:
-  network: false
-  shell: true
-  secrets: false
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-### chrome-cdp
-
-```yaml
-id: chrome-cdp
-protocol: 1
-capability: browser-session
-source: shipped
-ownership:
-  kind: external-package
-  name: blaze-skills/chrome-cdp
-transport: skill+cli
-profile: optional
-readiness:
-  probe: cli
-  command_hint: node scripts/cdp.mjs list
-on_missing: degrade
-permissions:
-  network: false
-  shell: true
-  secrets: false
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-### playwright
-
-```yaml
-id: playwright
-protocol: 1
-capability: browser-automation
-source: shipped
-ownership:
-  kind: external-package
-  name: "@playwright/mcp"
-transport: mcp
-profile: optional
-readiness:
-  probe: mcp
-  command_hint: npx -y @playwright/mcp@latest
-on_missing: degrade
-permissions:
-  network: true
-  shell: true
-  secrets: false
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-### github
-
-```yaml
-id: github
-protocol: 1
-capability: vcs-host
-source: shipped
-ownership:
-  kind: external-package
-  name: "@modelcontextprotocol/server-github"
-transport: mcp
-profile: optional
-readiness:
-  probe: mcp
-  command_hint: npx -y @modelcontextprotocol/server-github
-on_missing: degrade
-permissions:
-  network: true
-  shell: true
-  secrets: true
-secret_refs:
-  - GITHUB_TOKEN
-update_policy: preserve-user-overlay
-```
-
-### cursor-ide-browser
-
-```yaml
-id: cursor-ide-browser
-protocol: 1
-capability: ide-browser
-source: shipped
-ownership:
-  kind: host-platform
-  name: cursor-ide-browser
-transport: mcp
-profile: optional
-readiness:
-  probe: host
-  command_hint: Cursor Agent MCP namespace cursor-ide-browser
-on_missing: degrade
-permissions:
-  network: true
-  shell: false
-  secrets: false
-secret_refs: []
-update_policy: preserve-user-overlay
-```
-
-## 相关
-
-- [upgrade.md](./upgrade.md) — 终端用户升级半页
-- [release-boundary.md](./release-boundary.md) — PACTILE 本批 vs pactile-byok
-- `.pactile/workflow.md` — 并行第一原则（约定，不是 CLI gate）
+# Middleware Protocol v1
+
+> 一种中间件。官方与用户同一契约，只靠 `source` 区分。字段名英文；正文跟 `artifact_locale`（当前 zh）。
+>
+> Overlay（已拍）：项目 **`.pactile/middleware/`**。默认可进 git。`pactile init` / `pactile update` **永不写入、不删除、不纳入 `.template-hashes.json`**。历史残渣清理走独立 allow-list，不得误删本目录。
+
+Capability router 只声明 `exact` / `semantic` / `structural` / `external`，不绑 Agent 工具名。Manifest 的 `capability` 可以更细（例如 `browser-session`）；路由仍只按四意图，不绑工具名。
+
+## 双轨
+
+| 轨 | PACTILE 管什么 |
+| --- | --- |
+| 集成 | 本协议：Manifest + Profile + 健康。下表 **shipped** 各路属于此轨（含 MCP 传输）。 |
+| Extra | **未**出现在 shipped 表、也 **未**放入 overlay 的宿主 MCP / Agent 配置 → PACTILE 不管、不进健康表 |
+
+`pactile init` 不写入宿主 MCP 配置，也不强制安装 codegraph / fast-context。默认 Profile 只把 **smart-search** 标为 required；其余 shipped 为 optional，有探测、缺了不挡无关任务。
+
+shipped 表只登记**产品侧有承载**的 Provider。Playwright / GitHub 等已退役集成的宿主 MCP 属 Extra：PACTILE 不管、不进健康表（见上「双轨」）。用户要接入就放进 overlay，否则与本协议无关。
+
+## 义务
+
+1. **一种 ABI。** `source: shipped | user` 不是两套协议。
+2. **Update 不顶掉。** 用户 overlay 不进模板 hash / 官方 refresh 写集。同 id：用户赢，并报告。
+3. **Secret。** Manifest 只许引用（环境变量名 / 平台 Secret），不许写密钥原文。日志与 Artifact 同样禁止。
+4. **权限。** 新权限首次启用走一次 Resolution Approval。后续 `update` 不得扩大已批权限；要扩大再批一次。
+5. **校验。** 缺必填字段则拒绝接入并说明，不得半接入。
+6. **Hook。** 只订 Event Bridge 已有事件。未订阅模块不得让 hook 失败。
+7. **协议版本。** Manifest 可带 `protocol: 1`。不兼容升级必须在应用前被发现。
+
+本条不实现安装器、不做商店、不改全局 MCP。可选日后加 `pactile middleware add`，非发布阻塞。
+
+## 生命周期
+
+添加（放入 overlay 的 Manifest）→ 启用/停用（Profile `required` / `optional` / `unset`）→ 移除（用户删 overlay，PACTILE 忘记）。
+
+停用 ≠ 删除文件。官方 shipped 可被用户停用，不得被 `update` 强行再打开。`update` 可刷新 shipped 声明，但不得删用户 overlay，也不得在用户停用后自动重装实现。
+
+同一 capability 多个 Provider：Profile 选一个 active；其余 standby。不得静默抢当前 active。
+
+## 传输类
+
+`transport` 取其一：`skill+cli` | `mcp` | `skill` | `hook`。未登记且未写入 overlay 的宿主配置，PACTILE 不管。
+
+## 发现与健康
+
+发现方式：在 `.pactile/middleware/` 放 Manifest。缺必填字段则拒绝接入。shipped 声明由产品登记；用户 overlay 同 id 时用户赢。
+
+Status / Continue 在任务需要该 capability 时展示 `ready` / `missing` / `failed` / `degraded`。未登记且未 overlay 的 Extra MCP 不进健康表。
+
+## 第一波 shipped（不挡用户自添）
+
+默认 Profile：仅 **smart-search** = `required`。其余 = `optional`（探测缺失则 missing/degraded，不挡不需要该能力的任务）。**pactile-byok** 仍只占位，本批无实现。
+
+| Provider | Profile | capability | transport | 说明 |
+| --- | --- | --- | --- | --- |
+| smart-search | required `external-knowledge` | external-knowledge | skill+cli | 独立包；缺失则 degrade |
+| codegraph | optional | structural | mcp | 默认不装；不进 always-on |
+| fast-context | optional | semantic | mcp | 默认不装；Native `@codebase` 不是这一路 |
+| pactile-byok | optional 占位 | — | — | **实现与发版延后**；不带 BYOK 安装 |
+
+## Manifest 样例
+
+### smart-search
+
+```yaml
+id: smart-search
+protocol: 1
+capability: external-knowledge
+source: shipped
+ownership:
+  kind: external-package
+  name: smart-search
+transport: skill+cli
+profile: required
+readiness:
+  probe: cli
+  command_hint: smart-search doctor
+on_missing: degrade
+permissions:
+  network: true
+  shell: true
+  secrets: true
+secret_refs: []
+update_policy: preserve-user-overlay
+```
+
+### codegraph
+
+```yaml
+id: codegraph
+protocol: 1
+capability: structural
+source: shipped
+ownership:
+  kind: external-package
+  name: "@colbymchenry/codegraph"
+transport: mcp
+profile: optional
+readiness:
+  probe: mcp
+  command_hint: npx @colbymchenry/codegraph serve --mcp
+on_missing: degrade
+permissions:
+  network: false
+  shell: true
+  secrets: false
+secret_refs: []
+update_policy: preserve-user-overlay
+```
+
+### fast-context
+
+```yaml
+id: fast-context
+protocol: 1
+capability: semantic
+source: shipped
+ownership:
+  kind: external-package
+  name: fast-context-mcp
+transport: mcp
+profile: optional
+readiness:
+  probe: mcp
+  command_hint: npx -y fast-context-mcp
+on_missing: degrade
+permissions:
+  network: false
+  shell: true
+  secrets: false
+secret_refs: []
+update_policy: preserve-user-overlay
+```
+
+## 相关
+
+- [upgrade.md](./upgrade.md) — 终端用户升级半页
+- [release-boundary.md](./release-boundary.md) — PACTILE 本批 vs pactile-byok
+- `.pactile/workflow.md` — 并行第一原则（约定，不是 CLI gate）

package/dist/templates/markdown/framework/parallel-first-execution.md.txt

@@ -1,116 +1,116 @@
-# Parallel-first execution contract
-
-> **Purpose**: Make “parallel by default, serial by written reason” a **product** principle and an executable planning contract. After a Task is Open, first judge isolatable units; if they exist, prefer **host-native** parallel. Pactile owns declaration + integration only.
->
-> **Not a scheduler.** No queue, no new CLI, no host-parallel replacement, no cross-platform dispatch.
->
-> **Scope:** review-pool accepted items, development-plan batches, Parent/Full fan-out, and independent middleware / protocol / release tracks. **Not:** Lite / single-file (spawn not required); unisolatable write-sets; HITL / `start-execution --approved` / reviewer / `integrate-child`.
->
-> **Strength:** convention + Independent Check / planning review. Missing declaration on Full/Parent is **Check FAIL**. Not a `start-execution --check` hard gate. Attention order (`priority`) is not a serial lock.
-
-Full Prefer/Adapt/Own and serial-exception list: `.pactile/workflow.md` (Parallel-first). Host binding lives in the Adapter guide, not this contract. Who/where dispatch: `.pactile/framework/execution-strategy.md` (orthogonal).
-
----
-
-## Open, then judge isolation
-
-1. After Open, name isolatable **write-sets / deliverables** (different `touches`, different Child, independent slices). Role chains stay serial: implement → Check. Independent research slices in Define may run in parallel; research must not share an Execute write-set.
-2. Point to **≥2** isolatable units → default parallel. Cannot point to more than one (true single write-set) → main session inline and write `serial_reason` (or one equivalent line). Full / Parent should normally be able to name units. Lite does not forbid fan-out; it usually has one write-set.
-3. The main session is dispatcher + HITL + integration, not the default sole implementer.
-4. Prefer a **host-visible parallel surface** when the Adapter can open one. If it cannot bind, record assurance and degrade to inline / sequential — do not claim work already ran in parallel. Same-session silent workers are a degrade and need one plain sentence.
-
----
-
-## Declaration XOR (task-map / implement.md)
-
-Planning must pick **exactly one side** (aliases allowed):
-
-- `parallel_groups` (or existing alias `stages`) lists isolatable units, and unit `touches` do not overlap (or isolation such as `git-worktree` is declared); **or**
-- `serial_reason` is one of: shared write-set / HITL or reviewer gate / `depends_on` unmet / user asked serial / conflict surface cannot isolate.
-
-Declare these in Parent `task-map.md` (frontmatter and/or Orchestration notes). For a Full task with explicit worker fan-out and no Parent, put the same block in `implement.md`.
-
-| Need | Field | Where it already lives | Notes |
-| --- | --- | --- | --- |
-| Topology | `execution_topology` | task-map frontmatter | `parallel` (default when ≥2 independent units) or `serial` (requires `serial_reason`) |
-| 可并行组 | `parallel_groups` *or* `stages[].units` | `stages:` already groups units | List child / slice ids that may run concurrently (empty `depends_on`) |
-| 合并点 | `merge_points` *or* `merge_limit` | `merge_limit: 1` + `integrate-child` | HITL, `start-execution --approved`, reviewer gates, and Parent integrate stay **serial** |
-| 冲突面 | `conflict_surface` *or* `children[].touches` | per-child `touches` | Write-sets that can collide; isolate with worktrees or serialize |
-| 串行理由 | `serial_reason` | required when there are no isolatable groups | Exactly one of the exception list above |
-
-`serial_reason` (one of):
-
-- shared write-set
-- HITL or reviewer gate
-- `depends_on` unmet
-- user asked serial
-- conflict surface cannot isolate
-
-Lite true single write-set: one line is enough (`serial_reason: single write-set`, or omit the parallel block and state inline in `implement.md`).
-
-Optional YAML (Parent frontmatter or Full `implement.md`):
-
-```yaml
-execution_topology: parallel
-parallel_groups: [child-a, child-b]
-merge_points: [integrate-child, reviewer-gates]
-conflict_surface: [path/that/collides]
-# serial_reason:  # omit when parallel groups are declared
-```
-
-These fields are **planning declarations**. CLI may round-trip them on `task-map.md` writes; nothing in Pactile auto-dispatches workers from them.
-
----
-
-## Check FAIL (Full / Parent)
-
-Independent Check / typed Check worker (helper: `common.parallel_declaration.evaluate_parallel_declaration`) is **unqualified** when any of:
-
-1. Neither `parallel_groups` / `stages` nor `serial_reason` is declared.
-2. Isolatable groups are declared, all write-set work stayed inline, and there is no `serial_reason`.
-3. Two workers share a write-set and isolation was not declared (fake parallel).
-
-Lite missing the block is not FAIL. Archives are not backfilled.
-
-This is **not** a `task.py start-execution --check` hard fail.
-
----
-
-## Worker binding window
-
-Activate `worker-orchestration` when — and only when — isolatable groups are already declared **and** a dispatch window is open (Execute-approved implement workers; independent research slices under Define). Parent may not silently finish children in sequence without a written `serial_reason`.
-
-HITL, `start-execution --approved`, reviewer, and `integrate-child` (`merge_limit: 1`) stay serial. Human attention: batch questions on one frontier; do not multiply confirms by N.
-
----
-
-## Archived Parent 对照 (do not edit the archive)
-
-Source (read-only): `.pactile/tasks/archive/2026-08/08-05-pactile-optimization/task-map.md`
-
-That campaign already behaved parallel-first; this table shows which **named** fields the contract would ask for vs what the archive already has. The archive body is **not** rewritten.
-
-| Contract field | Archive evidence | Gap |
-| --- | --- | --- |
-| Default parallel (≥2 children, `depends_on: []`) | Five children, all `depends_on: []`; notes say 可并行尽量并行 | Met |
-| `execution_topology` | `parallel_work_serial_merge` | Met in spirit (parallel work, serial merge). Today’s spelling is `parallel` + serial merge_points — do not rename the archive |
-| 可并行组 | `stages:` `stage-p0` / `stage-p1` / `stage-p1-lsp` with “可并行” titles | Met via `stages:` (alias of `parallel_groups`) |
-| 合并点 | `merge_limit: 1`; Event Log integrates one Child at a time; Suggested integration order: 合入仍串行 | Met via `merge_limit` + notes. Missing the literal key `merge_points:` |
-| 冲突面 | Per-child `touches` (hooks/rules/templates overlap called out) | Met via `touches`. Missing top-level `conflict_surface:` |
-| `serial_reason` | Topology is not `serial`, so none required. HITL/gates stayed serial through `merge_limit` | No gap for this map. A **serial** topology would need one exception line |
-| Prefer host-native | Parent routed workers to the host parallel surface / worktrees; Pactile did not schedule | Met (capability). Contract now makes that the **default**, not “when useful” |
-| Worker prompt path | Child prompts under `child-prompts/` with explicit task dirs | Met |
-
-**Would-write `serial_reason` only if** this Parent had set `execution_topology: serial` despite empty `depends_on` — e.g. shared write-set on `pactile/packages/cli/src/templates/`. It did not; it kept topology parallel and serialized **merge** only.
-
-Contrast (not edited): `.pactile/tasks/archive/2026-08/08-20-08-20-byok-headless-backend/task-map.md` has `execution_topology: serial` with every `depends_on: []` and **no** `serial_reason`. Under this contract that map would add one line (likely shared write-set / same branch `feat/byok-headless`).
-
----
-
-## Non-goals
-
-- Auto parallel dispatch, queues, or new CLI
-- Forcing Lite tasks into parallel agents
-- Replacing the host-native parallel surface
-- Relaxing HITL / `start-execution --approved` / reviewer-gate serial semantics
-- Cross-platform parallel (P16)
+# Parallel-first execution contract
+
+> **Purpose**: Make “parallel by default, serial by written reason” a **product** principle and an executable planning contract. After a Task is Open, first judge isolatable units; if they exist, prefer **host-native** parallel. Pactile owns declaration + integration only.
+>
+> **Bounded batch, not a generic scheduler.** `pactile parallel run` dispatches approved Pi Child tasks from a Parent manifest. Codex desktop Execute tasks continue to use native App tools plus Pactile requests and receipts.
+>
+> **Scope:** Parent/Full fan-out, independent isolatable Tasks, and independent middleware / protocol / release tracks. **Not:** Lite / single-file (spawn not required); unisolatable write-sets; HITL / `start-execution --approved` / reviewer / `integrate-child`.
+>
+> **Strength:** convention + Independent Check / planning review. Missing declaration on Full/Parent is **Check FAIL**. Not a `start-execution --check` hard gate. Attention order (`priority`) is not a serial lock.
+
+Full Prefer/Adapt/Own and serial-exception list: `.pactile/workflow.md` (Parallel-first). Host binding lives in the Adapter guide, not this contract. Who/where dispatch: `.pactile/framework/execution-strategy.md` (orthogonal).
+
+---
+
+## Open, then judge isolation
+
+1. After Open, name isolatable **write-sets / deliverables** (different `touches`, different Child, independent slices). Role chains stay serial: implement → Check. Independent research slices in Define may run in parallel; research must not share an Execute write-set.
+2. Point to **≥2** isolatable units → default parallel. Cannot point to more than one (true single write-set) → main session inline and write `serial_reason` (or one equivalent line). Full / Parent should normally be able to name units. Lite does not forbid fan-out; it usually has one write-set.
+3. The main session is dispatcher + HITL + integration, not the default sole implementer.
+4. Prefer a **host-visible parallel surface** when the Adapter can open one. If it cannot bind, record assurance and degrade to inline / sequential — do not claim work already ran in parallel. Same-session silent workers are a degrade and need one plain sentence.
+
+---
+
+## Declaration XOR (task-map / implement.md)
+
+Planning must pick **exactly one side** (aliases allowed):
+
+- `parallel_groups` (or existing alias `stages`) lists isolatable units, and unit `touches` do not overlap (or isolation such as `git-worktree` is declared); **or**
+- `serial_reason` is one of: shared write-set / HITL or reviewer gate / `depends_on` unmet / user asked serial / conflict surface cannot isolate.
+
+Declare these in Parent `task-map.md` (frontmatter and/or Orchestration notes). For a Full task with explicit worker fan-out and no Parent, put the same block in `implement.md`.
+
+| Need | Field | Where it already lives | Notes |
+| --- | --- | --- | --- |
+| Topology | `execution_topology` | task-map frontmatter | `parallel` (default when ≥2 independent units) or `serial` (requires `serial_reason`) |
+| 可并行组 | `parallel_groups` *or* `stages[].units` | `stages:` already groups units | List child / slice ids that may run concurrently (empty `depends_on`) |
+| 合并点 | `merge_points` *or* `merge_limit` | `merge_limit: 1` + `integrate-child` | HITL, `start-execution --approved`, reviewer gates, and Parent integrate stay **serial** |
+| 冲突面 | `conflict_surface` *or* `children[].touches` | per-child `touches` | Write-sets that can collide; isolate with worktrees or serialize |
+| 串行理由 | `serial_reason` | required when there are no isolatable groups | Exactly one of the exception list above |
+
+`serial_reason` (one of):
+
+- shared write-set
+- HITL or reviewer gate
+- `depends_on` unmet
+- user asked serial
+- conflict surface cannot isolate
+
+Lite true single write-set: one line is enough (`serial_reason: single write-set`, or omit the parallel block and state inline in `implement.md`).
+
+Optional YAML (Parent frontmatter or Full `implement.md`):
+
+```yaml
+execution_topology: parallel
+parallel_groups: [child-a, child-b]
+merge_points: [integrate-child, reviewer-gates]
+conflict_surface: [path/that/collides]
+# serial_reason:  # omit when parallel groups are declared
+```
+
+These fields remain planning declarations. A Parent can opt into an actual bounded batch with `pactile parallel run`; dispatch checks current approval, dependencies, declared write sets, review cost and the Parent cap before launch.
+
+---
+
+## Check FAIL (Full / Parent)
+
+Independent Check / typed Check worker (helper: `common.parallel_declaration.evaluate_parallel_declaration`) is **unqualified** when any of:
+
+1. Neither `parallel_groups` / `stages` nor `serial_reason` is declared.
+2. Isolatable groups are declared, all write-set work stayed inline, and there is no `serial_reason`.
+3. Two workers share a write-set and isolation was not declared (fake parallel).
+
+Lite missing the block is not FAIL. Archives are not backfilled.
+
+This is **not** a `pactile task start-execution --check` hard fail.
+
+---
+
+## Worker binding window
+
+Activate `worker-orchestration` when — and only when — isolatable groups are already declared **and** a dispatch window is open (Execute-approved implement workers; independent research slices under Define). Parent may not silently finish children in sequence without a written `serial_reason`.
+
+HITL, `start-execution --approved`, reviewer, and `integrate-child` (`merge_limit: 1`) stay serial. Human attention: batch questions on one frontier; do not multiply confirms by N. Run `pactile parallel status <parent>` to read wall time, queue wait, recorded rework events, Child outcomes, and current integration states.
+
+---
+
+## Archived Parent 对照 (do not edit the archive)
+
+Source (read-only): `.pactile/tasks/archive/2026-08/08-05-pactile-optimization/task-map.md`
+
+That campaign already behaved parallel-first; this table shows which **named** fields the contract would ask for vs what the archive already has. The archive body is **not** rewritten.
+
+| Contract field | Archive evidence | Gap |
+| --- | --- | --- |
+| Default parallel (≥2 children, `depends_on: []`) | Five children, all `depends_on: []`; notes say 可并行尽量并行 | Met |
+| `execution_topology` | `parallel_work_serial_merge` | Met in spirit (parallel work, serial merge). Today’s spelling is `parallel` + serial merge_points — do not rename the archive |
+| 可并行组 | `stages:` `stage-p0` / `stage-p1` / `stage-p1-lsp` with “可并行” titles | Met via `stages:` (alias of `parallel_groups`) |
+| 合并点 | `merge_limit: 1`; Event Log integrates one Child at a time; Suggested integration order: 合入仍串行 | Met via `merge_limit` + notes. Missing the literal key `merge_points:` |
+| 冲突面 | Per-child `touches` (hooks/rules/templates overlap called out) | Met via `touches`. Missing top-level `conflict_surface:` |
+| `serial_reason` | Topology is not `serial`, so none required. HITL/gates stayed serial through `merge_limit` | No gap for this map. A **serial** topology would need one exception line |
+| Prefer host-native | Parent routed workers to the host parallel surface / worktrees; Pactile did not schedule | Met (capability). Contract now makes that the **default**, not “when useful” |
+| Worker prompt path | Child prompts under `child-prompts/` with explicit task dirs | Met |
+
+**Would-write `serial_reason` only if** this Parent had set `execution_topology: serial` despite empty `depends_on` — e.g. shared write-set on `pactile/packages/cli/src/templates/`. It did not; it kept topology parallel and serialized **merge** only.
+
+Contrast (not edited): `.pactile/tasks/archive/2026-08/08-20-08-20-byok-headless-backend/task-map.md` has `execution_topology: serial` with every `depends_on: []` and **no** `serial_reason`. Under this contract that map would add one line (likely shared write-set / same branch `feat/byok-headless`).
+
+---
+
+## Non-goals
+
+- Unapproved automatic dispatch or a persistent general-purpose queue
+- Forcing Lite tasks into parallel agents
+- Replacing the host-native parallel surface
+- Relaxing HITL / `start-execution --approved` / reviewer-gate serial semantics
+- Cross-platform parallel (P16)