@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/docs/vendor/dot-codex/adr/0003-external-fact-delivery-gates.md

@@ -0,0 +1,20 @@
+---
+status: accepted
+---
+
+# 交付门禁以外部事实为准
+
+> Review conclusion superseded by [ADR 0013](0013-review-necessity-tiering.md); CI, release, tracker, and post-merge external facts below remain active.
+
+交付资格由当前候选的验证结果、PR/CI 实时状态以及实际发布产物决定；Agent 的调用传输、子任务身份、等待方式和内部 transcript 只服务于执行，不构成交付证明。独立 review 作为 advisory review 提供可定位的改进建议，高风险改动自动运行，但其缺失或失败不能替代或阻塞上述事实门禁。这样可以保留低成本子 Agent 的并行与等待收益，同时避免 harness 日志格式变化改变流程结果。
+
+## Considered Options
+
+- 将 native spawn、child session 和 transcript attestation 作为 review/merge proof：拒绝，因为它把执行器内部格式误当成业务事实，并已导致 PTC 调用被错误判定为无 Agent。
+- 为每一种 PTC/harness 变体增加日志解析器：拒绝，因为解析器与运行时实现强耦合，维护成本高且无法提升 PR、CI 或发布事实的可信度。
+
+## Consequences
+
+- tracker 仍由低成本子 Agent 执行轮询，主 Agent 等待运行时返回的任务句柄，并在终态后复核一次外部事实。
+- review 结果需要可定位证据才能帮助修复，但不再写入或满足 flow receipt 的 merge gate。
+- Direct receipt schema v1-v4 已退役并明确拒绝；仅 active v5 receipt 可迁移到 v6。

package/toolkit/skills/docs/vendor/dot-codex/adr/0003-task-scoped-pr-visual-evidence.md

@@ -0,0 +1,23 @@
+---
+status: accepted
+---
+
+# PR 视觉证据采用任务级选择
+
+长期 `SPEC.md` / `PLAN.md` 的 `## Visual Evidence` 是主人验收与主题历史的归档，不是当前 PR 的选图数据库。Phase A 必须接收当前 UI 任务显式声明的 repo-relative Task Evidence Set，或显式 `--no-evidence`；它据此生成 PR 正文可见的受管 `## Visual Evidence` section。Phase B 只读取这个 section 并把现有 URL 重绑到 merge SHA，绝不重新扫描关联 Spec、Plan 或历史图片。
+
+视觉比较也以任务路径为身份：候选图片只与锁定 base commit 中相同 repo-relative path 的 blob 比较。路径在 base 中不存在时结果是 current-only，不按 Spec 中的图片顺序、不按相似度，也不从其他历史图片寻找替代基线。
+
+已退役的 PR selector markup 只在当前任务已经修改关联文档时做安全迁移。PostToolUse hook 提供即时归一化和反馈，最终 PR 门禁复查相同规则；含有并存图片 section 等歧义时必须保留文件并要求人工决定，不能自动合并或删除证据。
+
+## Considered Options
+
+- 在每个 Spec 内引入永久 Evidence Surface 分组：会把一次任务的临时选择固化为文档结构，并增加分裂与重复归档风险。
+- 继续扫描 Spec 的 selector：历史归档会随时间扩大，无法证明被选图片属于当前 PR。
+- 在 PR 正文写隐藏元数据清单：会制造第二个不可见事实源，且不能让审阅者直接核对选择结果。
+
+## Consequences
+
+- PR 选图输入变成显式、可审计且与当前任务绑定；同一张历史图片只有在被当前任务明确传入时才会发布。
+- 可见受管 PR section 是 Phase B 的唯一持久选择记录，仍保留人工可读性。
+- 每轮迁移只触及已改文档，避免为了清理旧 markup 制造大规模文档 churn；歧义旧文档会暂时阻断相关 PR，直到有人作出合并决定。

package/toolkit/skills/docs/vendor/dot-codex/adr/0004-scope-authority-and-topic-spec-boundaries.md

@@ -0,0 +1,28 @@
+---
+status: accepted
+---
+
+# 显式计划的范围权威与主题 Spec 边界
+
+## Context
+
+Grilling、显式 `$dev-plan` 和 canonical topic Spec 服务于不同生命周期。过去的计划可以把仓库证据或模型推断演绎成 Goal、验收或流程硬门禁，Topic Spec 也混入执行状态、PR 选项和任务清单，造成来源不可追溯与重复治理。
+
+## Decision
+
+- 显式 `$dev-plan` 在 `Flow Decision` 后生成临时 `Scope Basis`，为每个 `G*`、`N*`、`A*` claim 记录唯一来源。只有具体 owner 指令、存在 anchor 的 canonical Spec 或 ADR 才能授权 material claim；`derives` 只连接已授权 claim，`flow` 只记录流程技能。
+- 泛化的 owner 批准、仓库事实和模型推断不能单独授权范围；来源解析由 Agent 自动完成，不把查找来源的工作转嫁给主人。未调用 `$dev-plan` 时，原生 Plan Mode 不受此合同影响。
+- canonical `SPEC.md` 是可追溯、可验证的主题级需求合同，使用稳定 `REQ-*` 与 `VER-*`；实施覆盖、命令、当前状态、PR/commit 关联和生命周期历史分别归入 `IMPLEMENTATION.md` 与 `HISTORY.md`。工作流主题可以在规范性需求中描述 PR/Phase 行为，但不能把当前任务状态写入 Spec。
+- Task Evidence Set 是视觉交付阶段的临时输入；Spec 中的 `Visual Evidence` 只保留规范性 owner-facing 资产，PR 选图与 Phase A/B 记录由既有工作流负责。
+
+## Consequences
+
+- 计划 checker 可以拒绝无来源或来源过宽的 claim，并保持 legacy recovery 读取能力。
+- Spec checker 可以按结构拒绝执行编排和未决问题，而不会因为工作流需求中的 `PR` 或 `Phase` 词语误伤。
+- 已有未触及的历史或外部 Spec 保持可读，不进行批量重写。
+
+## Related Specs
+
+- [Dev plan goals first](../specs/dev-plan-goals-first/SPEC.md)
+- [Topic Spec model](../specs/topic-spec-model/SPEC.md)
+- [Shared UI visual evidence gate](../specs/shared-ui-visual-evidence-gate/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0005-topic-spec-skill-naming.md

@@ -0,0 +1,27 @@
+---
+status: accepted
+---
+
+# Topic Spec Skill 命名与兼容边界
+
+## Context
+
+`docs-plan` 最初承载过 work-item plan 语义，后来 canonical 文档模型已经改为长期主题级 `SPEC.md`。名称、legacy `PLAN.md` 模板和执行交接用语仍然会把主题规格误导成一次性实施计划。
+
+## Decision
+
+- repository-local 的 canonical Skill 名称为 `$topic-spec`，其唯一职责是创建或维护 `docs/specs/<topic>/` 下的 `SPEC.md`、`IMPLEMENTATION.md`、`HISTORY.md` 及必要的契约文件。
+- `$dev-plan` 继续负责临时实施计划；`$topic-spec` 不生成 `Summary`、`Flow Decision`、`Task Orchestration` 等执行计划输出。
+- `docs-plan` 不再是 repository-local Skill 或路由名称；新文档和新调用只使用 `$topic-spec`。
+- legacy `PLAN.md` 模板只放在 `skills/topic-spec/templates/legacy/`，不属于新 Spec 模板集合。
+
+## Consequences
+
+- 新入口、Skill 索引、计划 checker 和回放 fixture 使用 `$topic-spec`，降低主题 Spec 与实施计划之间的误路由概率。
+- 历史文档中的旧名称只保留为历史事实；它不再对应可调用 Skill，也不参与自动发现。
+- 需要创建长期主题规格时唯一使用 `$topic-spec`；需要当前任务执行编排时使用 `$dev-plan`，二者不能互相替代。
+
+## Related Specs
+
+- [Topic-level Spec model](../specs/topic-spec-model/SPEC.md)
+- [Dev plan goals first](../specs/dev-plan-goals-first/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0006-internal-plan-authorization-and-scope-constraints.md

@@ -0,0 +1,26 @@
+---
+status: accepted
+---
+
+# 计划授权留在内部，验证限制建模为范围约束
+
+## Context
+
+将对话来源逐条输出到 `Scope Basis` 的初衷，是阻止模型把仓库事实、推断或泛化批准演绎成计划范围。它无法从静态 Markdown 判断一句话是否真正蕴含后续机制，反而会把主人对旧方案的否定、纠正或安全限制逐字写入计划，并将验证条件伪装成新的 Goal。
+
+## Decision
+
+- Scope Authority 仍由 Agent 在输出前自动检查：只有具体主人请求或有效的当前 Spec/ADR 能授权 material Goal 或 Non-goal；不把来源查找或重述转嫁给主人。
+- 最终 `$dev-plan` 不输出 `Scope Basis`、主人消息引语或 `owner`、`contract`、`adr`、`derives`、`flow` 来源映射；不保留该格式的兼容输出路径。
+- 主人对方法的否定、受控验证、绝对时间和安全边界等限制使用语义化 `C*` Constraint 表达，并绑定已有 `A*` 验收项。Constraint 只限制已授权目标及其验收，不能独立授权新 workflow、脚本、Spec、远端写入或交付义务。
+- 当提出的具体机制没有独立授权时，Agent 必须提出一个明确决策，而不是把机制混入 Goal、Constraint 或 Task Orchestration。
+
+## Consequences
+
+- 主人审阅的是目标、边界、约束、编排和验收，而不是对话转录或伪精确的来源账本。
+- checker 可以可靠验证最终文档的结构边界和 Constraint 到验收的关联，但不声称能从静态文本证明对话语义蕴含。
+- 本 ADR 取代 [ADR 0004](0004-scope-authority-and-topic-spec-boundaries.md) 中关于最终计划输出 Scope Basis 的决定；ADR 0004 关于 Topic Spec 分层的决定继续有效。
+
+## Related Specs
+
+- [Dev plan goals first](../specs/dev-plan-goals-first/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0007-source-managed-component-evidence.md

@@ -0,0 +1,26 @@
+---
+status: accepted
+---
+
+# 组件证据采用源管理展示面
+
+## Context
+
+组件截图曾尝试从像素推断背景、裁掉多余边缘并补出外边距。这个过程无法判断留白是否属于组件主题，也无法区分自然画布与额外画框；实际结果会制造与组件无关的边框、重复留白或嵌套卡片观感。
+
+## Decision
+
+- 选作组件、片段或可复用状态证据的 Story/docs DOM 必须声明 `data-visual-evidence-surface` 和其内的 `data-visual-evidence-target`。
+- 展示面由源代码拥有：使用真实主题的自有不透明纯色背景，并保留目标的自然外边距；不得为证据添加边框、圆角、阴影、专用颜色或嵌套卡片。
+- 截图流程只做一次 DOM 预检，量化目标与展示面的四边间距。它可在展示面内按已知几何范围收紧超过上限的空白，但不得注入 DOM、改样式、补边、像素推断背景或存储测量回执。
+- 页面和完整页面 Storybook fallback 继续使用已有 `trim_only` 图像路径。`require_margin` 保留为 helper 兼容参数，但必须在像素分析前阻断并要求源管理展示面。
+
+## Consequences
+
+- Storybook stories 成为组件证据空间的唯一权威，截图 Agent 不再承担视觉设计决策。
+- 无法自然提供展示面的组件证据会阻断并返回 Story authoring，而不会生成带假边框的图片。
+- 该合同不新增业务仓库 CI、`play`、测试配置或 owner-facing 测量字段。
+
+## Related Specs
+
+- [Visual evidence whitespace trim](../specs/visual-evidence-whitespace-trim/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0008-direct-pr-merge-preflight.md

@@ -0,0 +1,25 @@
+---
+status: accepted
+---
+
+# Direct PR Merge Preflight
+
+## Context
+
+Direct PR merge authorization should identify the PR the owner approved, while the exact commit being merged is a live remote fact. Requiring the owner to copy or repeat a SHA adds friction without proving that the candidate worktree still represents that PR head. An unguarded merge also leaves a race between the final inspection and the GitHub merge action.
+
+## Decision
+
+- Add `skills/pr-merge/scripts/merge_preflight.py` as a narrow, read-only check of live PR head/base, candidate ref OID, and candidate worktree cleanliness. It reports machine-readable facts and locks the live head only when all required facts are eligible.
+- Bind direct merge intent to the explicit PR identity. The Agent passes the preflight receipt's locked head to `gh pr merge --match-head-commit`; stale snapshots, candidate drift, dirty/closed PRs, and unsupported guard capability fail closed.
+- Keep CI, review, Spec, visual evidence, release, and child/checkpoint/ aggregate role-specific approval outside this preflight contract.
+
+## Consequences
+
+- Owners authorize the PR without entering or repeating a SHA; the final machine receipt records the exact head used by the guarded merge.
+- Same-PR in-scope fixes can continue under the existing merge intent, but must produce a fresh eligible preflight before merge.
+- A changed candidate, remote head/base snapshot, closed PR, dirty worktree, or missing `--match-head-commit` support stops the path instead of silently falling back to an unguarded merge.
+
+## Related Specs
+
+- [Fast-track merge intent closeout](../specs/fast-track-merge-intent-closeout/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0009-initiative-child-integration-ci-boundary.md

@@ -0,0 +1,24 @@
+---
+status: accepted
+---
+
+# Initiative Child Integration Uses Branch-Push CI
+
+Child integration and final PR validation establish different facts. Child integration proves the exact merge on `prd/<topic>` and unlocks the next Initiative state; final PR validation proves the final promotion candidate.
+
+## Decision
+
+- Initiative uses one named `branch-push` check for Bootstrap activation and every child integration result.
+- Evidence binds the integration branch, exact SHA, named check, `push` event, and run ID.
+- Bootstrap activation uses `development_base` when the Spec is reused; when Bootstrap changes the Spec, it uses the committed Bootstrap SHA.
+- Final PR checks remain final-promotion evidence. They cannot activate an Initiative, close a Ticket, or unlock a dependency.
+
+## Consequences
+
+- A Bootstrap cannot publish external topology until the required check has passed and the integration branch still points to that SHA.
+- Repositories need one qualifying `prd/**` branch-push check. The flow does not manufacture an alternate CI path.
+- Runtime validation and replay reject CI evidence that does not carry the exact branch, SHA, check, event, and run identity.
+
+## Related Specs
+
+- [Initiative flow](../specs/initiative-flow/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0010-post-merge-flow-receipt-finality.md

@@ -0,0 +1,22 @@
+---
+status: accepted
+---
+
+# Post-Merge Flow Receipt Finality
+
+`flow_receipt.py` must treat pre-merge OPEN PR binding and post-merge finality as different facts. Direct and aggregate flows record an explicit merge receipt containing the original PR head/base and the actual GitHub merge SHA; only after applicable Step 6 CI, release, deployment, or publication facts are terminal may the run be sealed as `complete`. This preserves the existing fail-closed OPEN binding while preventing a successfully merged PR from leaving its receipt permanently active.
+
+A ledger may be initialized after merge or may lack a pre-merge binding record. In either case, a post-merge association is valid only when the repository-bound PR identity, live `MERGED` facts, merge receipt, and terminal finality agree. This association does not backfill or claim a historical OPEN binding.
+
+## Considered Options
+
+- Reuse the OPEN-only binding check after merge: rejected because GitHub changes the PR state to `MERGED`, making normal successful merges impossible to close.
+- Accept `MERGED` directly in `close`: rejected because it could mark a run complete before post-merge delivery facts have settled.
+- Leave the receipt active and rely on an external control-plane record: rejected because the run loses an auditable link to the actual merge SHA and can block later work in the same worktree.
+
+## Consequences
+
+- `gh_pr_binding_facts()` remains OPEN-only; a separate merged-facts path validates `MERGED`, the original head/base, `mergeCommit.oid`, and `mergedAt`.
+- The first implementation targets direct and aggregate PRs. Child and checkpoint completion remains owned by `$initiative-flow` for the legacy Initiative flow; Wave Thread batches use the milestone and closeout contract in ADR 0029 and `docs/specs/wave-thread-flow/SPEC.md`.
+- Existing active ledgers are recovered separately after their Step 6 facts are verified; this decision does not authorize remote or ledger mutation by itself.
+- `pr_bound_at` records an actual pre-merge binding and is not required to complete a ledger whose post-merge receipt and live merged facts validate.

package/toolkit/skills/docs/vendor/dot-codex/adr/0011-parallel-direct-pr-flow.md

@@ -0,0 +1,25 @@
+---
+status: accepted
+---
+
+# Parallel Direct PR Flow
+
+Purely independent repository slices may be delivered as a bounded cohort of 2..8 direct PR tasks. The cohort is coordinated by native Codex task Worktrees and milestone messages, while each task retains the existing `PR_ROLE=direct` and `$fast-flow` responsibilities.
+
+## Decision
+
+`parallel-pr` is a top-level coordinator flow when every task starts from one exact base, owns a disjoint surface, consumes named contracts without creating dependencies, and declares its merge mode. The parent creates tasks and receives milestones; it does not create Tickets, a tracking Issue, an integration branch, aggregate artifacts, or a persistent ledger.
+
+Shared integration, dependency, topology freezing, or aggregate acceptance remains owned by `$initiative-flow`. A task that discovers one of those facts pauses and is rerouted rather than widening its surface silently.
+
+## Merge boundary
+
+`ready-only` is the default and stops at `Step 5C Ready`. `merge-on-green` is allowed only for a frozen named task after current PR metadata and current-head preflight prove that the repository can safely serialize merge and release work. The workflow PR merge procedure may downgrade to ready-only when those facts are absent.
+
+## Consequences
+
+- Cohort recovery uses durable task titles and PR metadata rather than a new cross-cohort ledger.
+- One failed or blocked task does not cancel unrelated direct PRs.
+- The flow reduces parent token cost after implementation starts, at the cost of requiring explicit scope and metadata reporting.
+
+Related specification: [parallel-pr-flow](../specs/parallel-pr-flow/SPEC.md).

package/toolkit/skills/docs/vendor/dot-codex/adr/0012-mandatory-local-review-proof.md

@@ -0,0 +1,23 @@
+---
+status: superseded
+supersedes: 0003-external-fact-delivery-gates.md (review conclusion only)
+superseded_by: 0013-review-necessity-tiering.md
+---
+
+# Mandatory Local Review Proof
+
+ADR 0003 remains authoritative for CI, release, tracker, PR, and post-merge external facts. This successor changes only the review conclusion: direct delivery flows require a fresh, read-only-sub-agent local `ReviewReceipt` before the corresponding delivery gate can pass.
+
+## Decision
+
+- Direct PR creation, reuse, update, and receipt binding do not require review proof. Before Step 5C or PR merge, every direct PR must converge one fresh clear four-lane proof on its current live `base_sha` and `head_sha`. `local-merge` requires the same proof on its current local base/head before Step 5L or merge.
+- A review runner failure, timeout, unavailable runner, malformed structured result, dirty reviewer worktree, stale base/head, or unresolved blocking finding is a blocker. There is no advisory fallback.
+- Proof is transport-neutral. It is accepted only from a read-only sub-agent's structured terminal result, exact base/head binding, and clean candidate HEAD. The receipt helper does not execute a model. Child IDs, PTC wrappers, and transcript shape are not proof.
+- Direct lane profiles are contract/Luna medium, state-concurrency/Luna xhigh, failure-data-safety/Luna max, and test-platform/Terra xhigh. Luna startup unavailability may use Terra medium and then Terra xhigh. Terra unavailability remains a blocker and cannot be silently replaced by Luna-only coverage.
+- Review waves retain four to six lanes, explicit convergence reopen, and at most three repair permits. Any repair commit or PR base/head drift makes the prior proof stale. A clear wave is the only AI review proof: Step 5C then checks current PR facts, CI, validation, repository rules, and clean HEAD without running a second AI merge review.
+
+## Compatibility
+
+Schema v6 is the active receipt format. An active v5 ledger is migrated on its next relevant gate, with the prior review bytes retained as read-only `legacy_review` history. Migration never makes historical proof current.
+
+`initiative-flow` keeps its independent review-proof state machine for legacy Initiative delivery. Wave Thread uses the review and evidence bindings defined by ADR 0029. This ADR applies to `normal`, `fast-track`, `local-merge`, and direct parallel-PR task flows only.

package/toolkit/skills/docs/vendor/dot-codex/adr/0013-review-necessity-tiering.md

@@ -0,0 +1,21 @@
+---
+status: accepted
+supersedes: 0012-mandatory-local-review-proof.md (universal direct-flow requirement only)
+---
+
+# Review Necessity Tiering
+
+ADR 0012 restored a mandatory local `ReviewReceipt` for every direct delivery flow. That universal requirement protects correctness but imposes the same review latency on changes where an Agent concludes code review is not needed. ADR 0003 remains authoritative for CI, release, tracker, PR, and post-merge external facts.
+
+## Decision
+
+- Every new direct `normal`, `fast-track`, `local-merge`, and direct parallel-PR flow records an Agent-owned review necessity assessment before PR binding or terminal local-merge completion. Workflow evidence stores a tier and concise rationale. Before PR binding, a changed candidate may be reassessed with its prior assessment retained as history; receipt binding does not lock or gate that workflow evidence.
+- The Agent selects Tier 1 through Tier 4 from the actual work. There is no automatic classifier, task-category mapping, or prescribed rubric.
+- Tier 1 has no code-review delivery gate. Tier 2 permits optional advisory review, which remains informational. Tier 3 requires the existing fresh clear four-lane current-head `ReviewReceipt`. Tier 4 requires that proof plus one or two Agent-selected dynamic lanes.
+- Tier 3/4 preserve all required-proof properties from ADR 0012: clean exact base/head binding, read-only-sub-agent structured result, transport independence, sub-agent unavailability blocking, current-head invalidation, three repair permits, explicit convergence reopen, and no AI merge-review duplication after clear proof.
+- Existing active or already-bound direct workflow evidence that predates assessment remains subject to the caller's current workflow contract. The receipt ledger keeps historical assessment fields readable without using them as a lifecycle gate. Archived historical receipt bytes remain unchanged.
+- `initiative-flow` retains its independent review-proof state machine.
+
+## Consequences
+
+Direct delivery no longer waits for mandatory local review when the recorded Agent assessment is Tier 1 or Tier 2. The assessment remains visible and immutable, so the absence of proof is deliberate and auditable. Tier 3/4 do not gain an advisory compatibility bypass.

package/toolkit/skills/docs/vendor/dot-codex/adr/0014-direct-review-evidence.md

@@ -0,0 +1,20 @@
+---
+status: accepted
+supersedes: 0013-review-necessity-tiering.md (receipt orchestration only)
+---
+
+# Direct Review Evidence
+
+Tier 3/4 review should protect delivery without making a local ledger the review scheduler, repair controller, or merge authority.
+
+## Decision
+
+- Required review is direct structured evidence from read-only sub-agents bound to the current base/head and declared scope.
+- Tier 3 uses four fixed lanes; Tier 4 adds one or two relevant dynamic lanes.
+- Initial evidence covers all required lanes. Repairs rerun affected lanes; unknown, high-risk, or base-drift repairs rerun all required lanes.
+- Lane profiles are cost/quality guidance, not concurrency or model ceilings.
+- `flow_receipt.py` remains validation and lifecycle infrastructure. Its review orchestration is a retirement target: it does not create review waves, freeze a candidate, consume repair permits, or decide whether review evidence is sufficient. Its retained `bind-pr`, post-merge, and close paths require only live PR identity, merge SHA, finality, and validation lifecycle facts; old assessment, review-wave, and convergence fields remain audit history.
+
+## Consequences
+
+Review work is scheduled directly against the current diff. PR convergence uses current review evidence, validation, CI, and GitHub facts, avoiding ledger-specific retries and state transitions.

package/toolkit/skills/docs/vendor/dot-codex/adr/0015-agent-owned-shared-testbox-workspace.md

@@ -0,0 +1,12 @@
+---
+status: superseded
+superseded_by: 0025-native-incus-agent-vm-lifecycle.md
+---
+
+# Agent-owned Shared Testbox Workspace
+
+Historical decision, superseded by [ADR 0025](0025-native-incus-agent-vm-lifecycle.md). It supplies no current operating entrypoint; use the [Agent VM contract](../specs/agent-vm/SPEC.md).
+
+The shared testbox was a common Linux execution host, so the Agent owned its workload directory and invoke SSH, Docker, and Compose directly. The repository used `/srv/codex/agents/<CODEX_THREAD_ID>/` as the persistent Agent Directory, kept reusable cache paths under the documented runtime/tool/domain convention, and exposed only small helpers for directory creation, Git worktree synchronization, read-only status, and explicit cleanup.
+
+The former centralized dispatcher and automatic reclaimer are retired because their run/control lifecycle, command forwarding, cache policy, and container restrictions made the helper responsible for workload governance. The consequence is that Agents own container lifecycle, cache use, and ordinary file transfer; cleanup is explicit and scoped to the current Agent Directory.

package/toolkit/skills/docs/vendor/dot-codex/adr/0016-bind-review-repairs-to-approved-scope.md

@@ -0,0 +1,19 @@
+---
+status: superseded by ADR-0034
+---
+
+# Bind Review Repairs to Approved Scope
+
+Code review must discover defects without turning every useful suggestion into an unbounded implementation obligation. The prior review/fix loop could keep reopening because it did not distinguish a defect in the accepted work from a new design request.
+
+## Decision
+
+- An in-scope review finding is repaired only when it demonstrates a violation of the approved behavior, acceptance, or non-negotiable safety boundary, and the repair does not change the settled design or implementation scope.
+- A finding whose remedy needs a new behavior, contract, or wider scope is a Design-Returning Review Finding. Ordinary repair stops and the task returns to design for a new decision and later implementation approval.
+- A Review Observation is reported but does not block delivery, create a Repair Batch, or start another formal review wave.
+- Missing or stale evidence concerns whether the current Candidate has been reviewed; it is not a finding and cannot be repaired as one. Existing current-candidate review evidence rules continue to govern that case.
+- The rule applies to every current Candidate. It does not create old/new review modes or reinterpret history by version.
+
+## Consequences
+
+Formal review remains able to require genuine in-scope repairs, but it cannot expand the task autonomously. A Repair Batch stays bounded to defects in the approved work, and a design-level finding has one explicit destination instead of becoming another review/fix round.

package/toolkit/skills/docs/vendor/dot-codex/adr/0016-pr-lifecycle-workflow-ownership.md

@@ -0,0 +1,27 @@
+---
+status: accepted
+---
+
+# PR Lifecycle Workflow Ownership
+
+## Context
+
+This ADR remains scoped to direct delivery, Initiative promotion, and visual evidence. Wave Thread delivery batches are governed by ADR 0029 and the wave-thread-flow SPEC. These paths all need PR publication and merge operations, but their authorization and state machines are different. Separate PR Skills duplicated shared workflow gates and made the public Skill index expose multiple competing lifecycle entrypoints.
+
+## Decision
+
+- `$project-engineering-workflow` owns the direct PR lifecycle: Step 5 publication/convergence and Step 6 merge/post-merge progression.
+- Mechanical publication and guarded merge operations live in workflow references and workflow-owned scripts. They accept a standard operation envelope and return live facts; they do not grant authorization or decide Initiative role legality.
+- `$initiative-flow` owns child/checkpoint/aggregate topology for the legacy Initiative flow, role-specific preconditions, exact-SHA approvals, integration CI, promotion, and closeout.
+- `$ui-visual-evidence` owns the Phase A/B PR body image gate, because its inputs and validation are the Task Evidence Set and managed visual section.
+- The former `pr-create`, `pr-merge`, and `github-pr-body-images` public Skill entries are retired without compatibility shells. Historical Specs and replay fixtures remain readable; active instructions route to the canonical owners.
+
+## Consequences
+
+Workflow stages have one direct PR entrypoint while the legacy role-specific flows retain their own state machines. Phase A/B image publication remains available to the workflow and Initiative callers without exposing a second lifecycle. Static and replay checks must validate canonical owner routes and preserve legacy fixture parsing without allowing legacy routes in active instructions.
+
+## Related Specs
+
+- [Agent Instruction Architecture](../specs/agent-instruction-architecture/SPEC.md)
+- [Shared UI Visual Evidence Gate](../specs/shared-ui-visual-evidence-gate/SPEC.md)
+- [Initiative Delivery Flow](../specs/initiative-flow/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0017-review-readiness-and-runtime-launch.md

@@ -0,0 +1,39 @@
+# ADR 0017: Review Readiness And Runtime Launch
+
+- Status: accepted
+- Date: 2026-09-14
+
+## Context
+
+Direct Tier 3/4 plans had begun to describe formal review as a fixed set of named sub-agents and model profiles. That made a plan look like an execution schedule, encouraged reuse of terminal reviewers, and obscured the fact that a candidate may not be reviewable until its behavior, acceptance, scope, contracts, validation, and applicable visual evidence are settled.
+
+Repair batches also need a precise boundary. Re-running every conceptual lane after every small repair wastes review capacity, while retaining evidence after a shared-contract or high-risk change can miss a regression.
+
+## Decision
+
+1. Review Readiness is a hard gate for formal review. Approved behavior and acceptance, scope, and required contracts must be stable; no design decision may remain unresolved; and the current Candidate must have completed applicable validation and visual evidence. If the gate is not satisfied, the flow returns to the design or evidence gate and does not launch formal lanes.
+2. Direct Tier 3/4 plans and new Wave Thread v2 plans that reach Step 5C record only the Tier, rationale, runtime launch strategy, and a supported profile recommendation. Task Orchestration must not name formal reviewer agents, lanes, or actual reviewer profiles. Wave Thread v2 uses the same shared Review Readiness and fresh-lane launch boundary; its task dispatch profile lock remains independent from formal review lane selection. Non-formal read-only analysis sidecars remain allowed.
+3. Once readiness is true, the runtime creates fresh formal reviewers for the current Candidate. Tier 3 starts with its four conceptual required lanes; Tier 4 adds one or two selected dynamic lanes. These conceptual lanes do not define a fixed reviewer count for every later Repair Batch. Every changed Candidate uses a fresh `fork_turns=none` reviewer, and a terminal reviewer is retired.
+4. A Repair Batch refreshes only lanes proven affected by the current Git delta. Unknown scope, shared-contract changes, security/schema/transaction/ protocol/concurrency/persistence/migration changes, high-risk changes, or base drift refresh every required lane. Retained results are valid only in the same active convergence run while their source base/head, scope, and delta remain inspectable.
+5. A `Design-Returning Review Finding` returns to design and cannot enter the ordinary repair loop. `Review Observation` is report-only, and missing, stale, malformed, or unavailable evidence remains `unchecked`. A complete clear terminal result may contain a blocking finding; it remains review evidence and follows the disposition rules.
+6. The launch boundary is stage-aware. For a direct PR, `Step 4 Ready` records Review Readiness and applicable pre-PR proof without requiring completed PR-stage findings or dispositions; after exact live PR base/head binding, fresh PR-stage formal review starts in parallel with CI, and the main Agent waits for both terminal states before convergence. No disposition, write, or Repair Batch may occur while either track is live. Local-merge formal review remains complete before `Step 5L`.
+
+## Consequences
+
+- Runtime evidence reflects the actual host-supported model/effort pair without making a plan promise an unavailable model or effort.
+- Formal review launches happen only for a reviewable candidate, and each changed candidate has an unambiguous reviewer lifecycle.
+- Direct PR review evidence is created at the live PR binding boundary, so `Step 4 Ready` remains a readiness handoff while CI and PR-stage review can share the first live round.
+- Small, proven-local repairs avoid unnecessary lane work; broad or uncertain changes retain the complete required coverage.
+- The plan checker can reject formal predeclaration without rejecting ordinary read-only sidecars.
+
+## Alternatives Rejected
+
+- Predeclaring four named sub-agents in every plan: rejected because it couples planning to runtime capacity and prevents independent fresh launches.
+- Reusing terminal reviewers for later candidates: rejected because the result is bound to the prior candidate head.
+- Refreshing only one lane for unknown or shared-contract changes: rejected because affected scope cannot be demonstrated safely.
+
+## Related Specs
+
+- [Local Review Necessity And Evidence](../specs/mandatory-local-review-proof/SPEC.md)
+- [PR convergence batching](../specs/pr-convergence-batching/SPEC.md)
+- [Workflow Agent Model Selection](../specs/workflow-agent-model-selection/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0018-v5-bootstrap-integration-ci-activation.md

@@ -0,0 +1,14 @@
+---
+status: accepted
+---
+
+# V5 Bootstrap Integration CI Activation
+
+Initiative Contract v5 is patched directly and is the only supported contract; earlier formats have no compatibility, migration, or recovery path. A provisional ledger permits only Bootstrap work before the first Integration CI: `reuse` activates from a passed exact-SHA branch-push check at `development_base`, while `refresh`, `create`, and `supersede` activate from the same check at their committed Bootstrap SHA. This preserves one named branch-push CI for both activation and later child integration without requiring a workflow to have run before the Bootstrap that introduces it. Only `spec.status=ready` permits external Tracking Issue and topology effects.
+
+## Consequences
+
+- A provisional Initiative cannot publish topology, create Ticket tasks, or recover from a missing ledger. A readable damaged provisional ledger without external topology may only be cancelled before a fresh Bootstrap.
+- A failed activation may rerun only at the same initial integration SHA; changing Bootstrap content starts a fresh Bootstrap.
+- If the integration branch no longer points to the CI SHA, activation stops. The provisional ledger may be closed as `cancelled`, but adopting that drift as a new base or deleting and recreating the branch is an explicit owner decision; the flow performs neither action automatically.
+- The approved Bootstrap plan remains the authority for its one branch and commit. No CI provisioning mode, workflow digest, or additional plan field is introduced.

package/toolkit/skills/docs/vendor/dot-codex/adr/0019-plan-release-disposition-policy-boundary.md

@@ -0,0 +1,35 @@
+# ADR 0019: Plan Release Disposition Policy Boundary
+
+## Status
+
+Superseded by [ADR 0021](0021-runtime-derived-pre-merge-release-route.md)
+
+## Context
+
+Direct delivery plans previously reached PR publication without an owner-visible pre-merge release route. Post-merge release tracking already has a separate merge-SHA-bound contract, but nothing required the plan or publication procedure to surface the target repository's release decision before labels or PR state were changed.
+
+The target repository may have its own release contract or an already-adopted project-local Policy Skill. Those owners define their version, label, channel, tag, and workflow vocabulary. dot-codex must remain compatible with them without installing, copying, or interpreting the Policy implementation.
+
+## Decision
+
+Every direct `normal`, `fast-track`, and `local-merge` plan has exactly one non-empty `release_disposition` in `Flow Decision`. The value is preserved as opaque repository-native text. The literal `unknown` is permitted as a plan value but blocks the first remote PR/label mutation and `Step 5C Ready` until the owner supplies a route fact.
+
+Before PR publication, the workflow re-resolves the current route from the target repository's checked-in contract and any already-adopted project-local Policy Skill. A determined route may reconcile only release-label groups that the target repository declares as managed, preserving unrelated labels. dot- codex defines no release enum and does not copy Policy grammar or Policy-owned version-impact states.
+
+`release_disposition` is not a version decision, release authorization, release receipt, `release_expected`, or publication proof. After a remote merge, the existing Step 6 release contract remains authoritative and requires merge-SHA-bound actual artifact evidence.
+
+## Consequences
+
+- Plans expose the missing decision before remote delivery begins.
+- Repeated or recovered publication re-checks current repository facts instead of trusting a stale plan route.
+- Repositories without a Policy keep their native route; repositories with a Policy keep ownership of its durable evidence and grammar.
+- Unknown routes fail closed before remote mutation, while post-merge release tracking remains unchanged.
+
+## Supersession
+
+This decision made the plan carry a route that the generic workflow could not reliably derive. ADR 0021 removes that owner-facing field and makes the pre-merge route a runtime-derived publication fact.
+
+## Related Specs
+
+- [Dev plan goals-first](../specs/dev-plan-goals-first/SPEC.md)
+- [Fast-track merge intent closeout](../specs/fast-track-merge-intent-closeout/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0020-code-hosting-platform-boundary.md

@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Bind Delivery Workflows to a Code Hosting Platform
+
+Delivery workflows resolve one repository binding from the approved `BASE_REMOTE` and choose an allowlisted code-hosting platform from its host. They call platform capabilities that return normalized facts, require Exact-SHA CI Evidence, and fail closed when a capability is unsupported; GitHub `gh` evidence remains readable for history, while all new receipts are platform-neutral structured facts. This preserves GitHub support while making self-hosted Gitea a first-class target without allowing task text, arbitrary URLs, or missing provider data to redirect or weaken a delivery action.
+
+Initiative Contract v5 remains GitHub-only. A Gitea Repository Binding rejects Initiative entry before creating an Issue, PR, or other external record, because Gitea does not provide the hierarchy semantics its ledger currently requires. This is an explicit capability boundary, not a partial compatibility mode.

package/toolkit/skills/docs/vendor/dot-codex/adr/0020-empirical-acceptance-review-gate.md

@@ -0,0 +1,42 @@
+---
+status: superseded
+---
+
+# ADR 0020: Empirical Acceptance Review Gate
+
+## Status
+
+Superseded by [ADR 0033](0033-empirical-acceptance-and-repair-autonomy.md).
+
+## Context
+
+The direct-review contract requires applicable validation before formal review, and it limits ordinary review repair to three bounded Repair Batches. That contract does not identify when acceptance requires observation of external behavior, nor does it bind that observation to the exact Candidate and accepted behavior. An Agent can therefore start formal review after repository-local validation even when a later repair changes a physical, timing, or protocol assumption that only empirical validation can verify.
+
+The existing Review Readiness and finding-disposition rules must remain generic. HIL is an important instance of this problem, but the durable boundary is any acceptance criterion that deterministic repository-local validation cannot prove.
+
+## Decision
+
+1. A direct flow must declare an Empirical Acceptance Obligation when an acceptance criterion depends on external behavior that repository-local, deterministic validation cannot prove. The declaration is based on the criterion's proofability, not a task category, changed-file heuristic, or reviewer preference.
+2. An applicable obligation has current Empirical Acceptance Evidence bound to the exact Candidate SHA, acceptance-contract digest, required scenario set, outcome, and an inspectable evidence locator. The record belongs to current Candidate/flow evidence; it is not a tracked receipt ledger and does not become direct review proof.
+3. Formal review, PR convergence, and local-merge readiness require passed current evidence for every applicable obligation. A Candidate SHA change or acceptance-contract change makes affected evidence stale.
+4. A proposed repair is Design-Returning when it changes an external-behavior contract, including source-response assumptions, timeouts, retries, permission/state transitions, or the acceptance semantics themselves, unless the accepted contract already states the exact behavior and evidence proves the Candidate violates it.
+5. A failed empirical run after a comparable passed Candidate is an Empirical Regression. The flow becomes diagnosis-only: it compares the exact passing and failing Candidates and does not open another ordinary Repair Batch or formal review wave. The failure does not by itself attribute cause to a reviewer or a particular repair.
+6. Continuation anchors carry the Empirical Acceptance Obligation and current evidence state together with the Candidate and cumulative Repair Batch count. Generic continuation cannot infer, reset, or waive either state. A fourth Repair Batch still requires explicit owner authorization bound to the current Candidate anchor.
+
+## Consequences
+
+- Empirical validation becomes a first-class admission condition rather than a late confirmation after review repairs.
+- Reviewers may report a concern, but they cannot silently redefine an externally observable contract through an In-Scope repair.
+- A hardware or integration regression is diagnosed from evidence instead of being treated as automatic proof that review was wrong.
+- `flow_receipt.py` remains validation/lifecycle audit infrastructure and does not regain review orchestration or delivery-gate authority.
+
+## Alternatives Rejected
+
+- Limit the rule to firmware or HIL: rejected because the governing distinction is proofability of an acceptance criterion, not implementation technology.
+- Add a durable review/repair receipt ledger: rejected because direct review evidence intentionally remains independent of receipt orchestration.
+- Allow every empirical failure to enter the next Repair Batch: rejected because it recreates the review/HIL alternation this decision prevents.
+
+## Related Specs
+
+- [Empirical Acceptance Review Gate](../specs/empirical-acceptance-review-gate/SPEC.md)
+- [Local Review Necessity And Evidence](../specs/mandatory-local-review-proof/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0021-runtime-derived-pre-merge-release-route.md

@@ -0,0 +1,33 @@
+# ADR 0021: Runtime-Derived Pre-Merge Release Route
+
+## Status
+
+Accepted
+
+## Context
+
+The generic delivery flow introduced `release_disposition` as a required plan field so PR publication could avoid guessing release labels. In practice, the generic workflow did not own the target repository's release vocabulary, and repositories without a release surface had no value to provide. A plan could therefore carry `unknown` through implementation and validation, then stop at the first PR mutation even when the safe result was simply to leave release labels alone.
+
+The target repository or an adopted project-local policy may still define a managed release-label contract. That contract must remain authoritative, but its absence is a normal repository state rather than an owner decision.
+
+## Decision
+
+Remove `release_disposition` from the direct plan contract. PR publication derives an internal `pre_merge_release_route` immediately from current repository and PR facts:
+
+1. An explicit, valid repository contract or adopted project-local Policy Skill may return a managed route and its owned release-label groups.
+2. An absent, unsupported, or non-applicable contract returns `no-managed-route`, with an empty managed-label set. Publication continues without release-label mutation.
+3. The generic workflow never invents release labels and never asks the owner to classify an absent route. A conflicting or malformed explicit policy is reported as a policy diagnostic; it does not become an owner-supplied `unknown` value or a generic PR publication blocker.
+
+The route evidence is runtime state, not a plan decision. Post-merge release tracking remains independent and is still the only source of `release_expected`, version, tag, and actual publication evidence.
+
+## Consequences
+
+- Repositories with no release surface proceed through PR publication silently.
+- Release-label reconciliation remains possible only when the target repository explicitly owns and exposes the label group.
+- The plan no longer stores a stale or opaque copy of live repository policy.
+- Release policy parsing is localized to publication-time route resolution; historical plan text may retain the old field as compatibility metadata, but it has no gating authority.
+
+## Related Specs
+
+- [Dev plan goals-first](../specs/dev-plan-goals-first/SPEC.md)
+- [Fast-track merge intent closeout](../specs/fast-track-merge-intent-closeout/SPEC.md)