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

package/toolkit/skills/docs/vendor/dot-codex/adr/0022-sandboxed-reg-cli-report-execution.md

@@ -0,0 +1,31 @@
+# ADR 0022: Sandboxed reg-cli Report Execution
+
+## Status
+
+Accepted
+
+## Context
+
+The owner comparison report invokes a pinned npm package against symlinks to existing chat snapshots. The report generator must create HTML, JSON, and diff files without being able to modify the source snapshots or write outside the report's managed staging directory. Runtime caches and logs must not accumulate beside durable report assets.
+
+`reg-cli` 0.18.16 and its npm dependency tree run against symlinks to existing chat snapshots. npm requires network access to install packages. The current macOS Seatbelt interface can express the required staging write scope, but `sandbox-exec` is deprecated and the profile language is not a documented third-party API. Runtime checks show that Node/Python abort when the profile grants only narrow read subpaths, so filesystem-wide read access must be paired with explicit denials for sensitive file contents and directory enumeration under user data and mutable external stores. Metadata remains available to resolve allowlisted runtime paths.
+
+## Decision
+
+- Keep input images as symlinks to immutable chat snapshots; do not copy them. Accept only independent regular files matching the snapshot generator's repo/date/timestamp path layout, and reject report-output path components case-insensitively. The default-deny profile also rejects hard-link aliases into staging.
+- Commit `package.json` and `package-lock.json` with integrity data for `reg-cli@0.18.16` and every transitive dependency. Install with `npm ci`, lifecycle scripts disabled, and the official npm registry in a temporary directory beneath report staging, with a private staging-local `HOME` and npm cache. The install phase may use outbound network access but cannot write outside staging or read staging inputs and source snapshots.
+- Run the installed `reg-cli` executable in a second sandbox with outbound network denied. Both phases use the canonical staging path as their only writable filesystem scope and may execute only the selected Node runtime. Permit renderer worker forks only within the same sandbox profile. Do not inherit custom CA path variables that would reopen arbitrary user-selected files during network-enabled installation.
+- Deny file-content reads and directory enumeration under user home directories, `/private/tmp`, `/private/var/tmp`, temporary stores, mounted volumes, keychains, and non-runtime third-party tool roots. Reopen reads only for the install runtime during npm installation; the offline comparison phase may also read staging and the exact source snapshots. Metadata remains available for path resolution. Other operating-system file reads remain available because the supported Seatbelt runtime aborts under a strict read-subpath-only profile.
+- Keep npm cache, temp files, and stdout/stderr logs in staging. Stop the process group and atomically rename staging before inspecting outputs. Clone report, JSON, and diff outputs with APFS copy-on-write into a fresh publication directory outside the sandbox write scope, recreate input image symlinks, and validate the clone set before publication. Reject generated report outputs as future snapshot inputs and recheck source hashes after rendering, immediately before publication, and immediately after the final rename. If the last check fails, remove only the just-published directory with the recorded inode identity. Require one hard link for each generated HTML, JSON, manifest, and diff artifact, and apply the canonical snapshot-scope syntax to report paths. Audit repeats source path and independent-file checks. Fail closed if the filesystem cannot clone outputs; never copy source snapshots. Remove the original sandbox staging after publication.
+- Use macOS `/usr/bin/sandbox-exec` for now. If the required sandbox is unavailable or the platform is unsupported, fail closed; do not run the comparison unsandboxed.
+
+## Consequences
+
+- Report generation creates no persistent npm cache and no extra image copies, at the cost of installing the pinned package for each report.
+- The implementation is currently macOS-only and depends on a deprecated, undocumented sandbox interface. Replacing it requires a separately validated sandbox backend; platform support must not be inferred from availability of a shell command alone.
+- The Seatbelt profile retains read access to operating-system files; user-home and other excluded roots deny file contents and directory enumeration while preserving metadata lookups. Exact exceptions reopen runtime and task input paths. npm lifecycle scripts are disabled, install-time package bytes are integrity-locked, and the report execution phase is offline.
+- The pinned renderer requires forked workers, so the sandbox allows process creation under the same narrow policy. A detached writer may still hold a descriptor to staging; copy-on-write output clones have independent inodes and live outside the runner's writable scope. Input images remain symlinks. Same-UID processes remain outside the sandbox boundary and can mutate a snapshot after the final publication check; audit detects later changes. Hash revalidation around publication prevents a detected in-flight mutation from being returned as a successful report but cannot make source snapshots immutable against a concurrent owner process. Concurrent path replacement during a file read or cleanup, and coordinated same-UID rewrites of a report and its manifest, remain outside the contract; audit checks consistency and accidental corruption, not cryptographic authenticity.
+
+## Related Specs
+
+- [Shared UI visual evidence gate](../specs/shared-ui-visual-evidence-gate/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0023-dev-plan-release-delivery-scope.md

@@ -0,0 +1,24 @@
+# ADR 0023: Dev-Plan Release Delivery Scope
+
+## Status
+
+Superseded by [ADR 0024](0024-stop-condition-driven-release-decision.md)
+
+## Context
+
+An explicit development plan can reach a PR-ready stop without saying whether version release work belongs to the plan. The runtime publication route and post-merge release evidence are deliberately derived from live repository facts, so adding a runtime-facing release decision to the plan would recreate the boundary rejected by [ADR 0021](0021-runtime-derived-pre-merge-release-route.md).
+
+## Decision (Historical)
+
+Explicit `$dev-plan` delivery plans declare a separate release arrangement in `Flow Decision`: `release_scope`, `release_reason`, `release_entrypoint`, and `release_followup`. The arrangement is required for `normal`, `fast-track`, `local-merge`, `parallel-pr`, and `initiative`, while `implement-only`, ordinary Plan Mode, and non-`$dev-plan` work remain outside the contract.
+
+The arrangement has three scopes. `included` carries affirmative, unconditional release work, release evidence, and a release-capable stop in the same plan. Modal or conditional release wording does not satisfy `included`. `deferred` names the post-stop repository-native entrypoint, prerequisites, and pending version or channel decision. `not-applicable` records the checked absence of a release mechanism or the reason release is not required and uses `none` as its entrypoint. `normal` and `local-merge` remain in the arrangement contract but cannot use `included`, because their legal stops do not authorize a release terminal state. The fields describe intended handoff only; they do not authorize publishing, merge, tagging, label mutation, deployment, or any other runtime operation.
+
+Historical JSONL without the new fields remains valid. A historical explicit `$dev-plan` plan that starts declaring one of the new fields is validated as a complete arrangement, preventing partial migrations without rewriting old sessions. `release_disposition` remains historical compatibility metadata and cannot satisfy this contract.
+
+## Consequences (Historical)
+
+- New plans make release scope visible before implementation starts.
+- The shared workflow can carry the plan arrangement through its legal stop without treating it as release proof.
+- Repositories without a release mechanism can state that fact explicitly, while repositories with a later release can hand off from a deferred stop.
+- ADR 0021 remains the authority for runtime pre-merge route derivation and actual post-merge release facts.

package/toolkit/skills/docs/vendor/dot-codex/adr/0024-stop-condition-driven-release-decision.md

@@ -0,0 +1,28 @@
+# ADR 0024: Stop-Condition-Driven Release Decision
+
+## Status
+
+Accepted
+
+## Context
+
+Release applicability has two different evidence boundaries. Before merge, the Agent can inspect target-repository policy and current PR facts and show the owner a default decision. After merge, only facts bound to the target repository, target branch, and actual merge SHA can establish the release expectation and artifact identity. Encoding the pre-merge decision as plan arrangement keys caused stale planning metadata to look like runtime release authority.
+
+## Decision
+
+New plans keep the existing `Flow Decision`, `收口条件`, `Assumptions/Defaults`, and `Acceptance & Validation` sections. They do not add release-arrangement fields, release stop-condition values, or a final version string. Historical JSONL and history documents remain readable as historical data.
+
+At Step 5C, the runtime reads target-repository policy and current PR facts and returns an Agent default decision card covering publish applicability, components, channel, bump rule, predicted version, target identity, policy source, and collision policy. Missing or conflicting inputs are unknown/blocked; absence of a pre-merge route is not a no-release decision. Merge continuation requires explicit owner confirmation of the card, including the version expectation. An objection returns to the release decision. One clear natural-language owner message may combine this confirmation with the request to continue or merge. The Agent must not require a prescribed reply string, field order, or separate action turn; it asks one concise clarification only when applicability or version expectation is genuinely ambiguous.
+
+For `merge-only` and `merge+cleanup`, existing plan prose locks the target repository/branch, base-tag source, bump rule, channel, components, collision policy, and merge-SHA binding. It locks the rule and inputs, never the final version string. After merge, the workflow verifies actual version, tag, artifact identity, and merge SHA from `target_repo + target_branch + merge_sha`; `release_expected` is a post-merge fact only. Conflicting or missing facts stay unknown/blocked and never silently mean no release.
+
+## Consequences
+
+- Plans remain stable behavior descriptions rather than a second release decision interface.
+- Step 5C has an explicit owner-visible decision and confirmation boundary.
+- Merge-only execution cannot silently re-decide locked release inputs after the merge; post-merge verification is bound to the actual merge SHA.
+- The prior plan-level arrangement decision is retained only for historical compatibility and audit.
+
+## Supersedes
+
+- [ADR 0023: Dev-Plan Release Delivery Scope](0023-dev-plan-release-delivery-scope.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0025-native-incus-agent-vm-lifecycle.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Native Incus Agent VM lifecycle
+
+Agent execution uses one Incus VM per Codex session inside CT109, with root SSH through native proxy NAT and explicit leases. The trusted computer uses its existing host SSH management access for both daily and operations commands; Skills and task authorization define their boundary, rather than claiming separate Agent credentials.
+
+Lifecycle enforcement uses one-shot control actions and persistent native systemd timers. Lease end closes NAT and exact conntrack flows before stopping the guest, then retains its disk as a disposable stopped cache. Age-based cleanup after 24 idle hours and capacity-triggered oldest-first cleanup can reclaim any eligible session cache. Sparse disk overselling uses actual allocation and measured headroom only within the authorized CT filesystem; PVE storage discovery and external capacity probes are outside the boundary. Effective leases are never evicted for capacity.
+
+This supersedes [ADR 0015](0015-agent-owned-shared-testbox-workspace.md). Guest isolation replaces shared host paths and caches. Persistent custom services, gateways and implicit keepalive are excluded; native components carry enforcement, while Python entrypoints execute bounded actions. A cached guest may be reused but carries no recovery guarantee.

package/toolkit/skills/docs/vendor/dot-codex/adr/0026-agent-vm-cpu-memory-overselling.md

@@ -0,0 +1,44 @@
+---
+status: accepted
+---
+
+# Agent VM CPU and memory overselling
+
+Agent VM must permit both CPU and memory overselling. The baseline control rejected creation or resize when summed guest allocations exceed its configured CPU or memory budget; the baseline topic Spec also excluded additional memory overselling. That restriction does not satisfy the owner's requirement to let multiple Agent workloads request larger guest configurations without reserving their simultaneous peaks.
+
+The required direction is to distinguish CT-local allocatable capacity, an oversold allocation budget and observed resource pressure. A guest's configured vCPU and memory sizes do not guarantee exclusive CPU capacity or sufficient physical memory for every guest to consume its maximum simultaneously. CPU contention and memory exhaustion have different consequences and require separate admission rules.
+
+The confirmed design replaces the topic's one-to-one CPU/memory admission rule. It supplements ADR 0025's native lifecycle architecture. Installation and observed coverage belong in the implementation companion; this decision does not establish deployment success.
+
+## Settled boundaries
+
+- Both CPU and memory overselling are required; retaining the current one-to-one allocation cap is not an acceptable result.
+- Keep configurable aggregate allocation ceilings, initially CPU four times and memory twice the base budgets. With the current 15 vCPU and 12 GiB base budgets, the ceilings are 60 vCPU and 24 GiB. These are configurable allocation ceilings, not simultaneous physical capacity promises.
+- Refuse new creation, stopped-cache restoration and growth when actual CT-local memory headroom is below `max(1 GiB, 10% of CT-visible memory capacity)`. Do not subtract the complete requested virtual memory allocation from that headroom. The pressure gate does not refuse existing-lease queries, renewal, retrieval or release. Later native OOM is possible and must be reported without proactively stopping an effective lease.
+- CPU and memory allocation accounting includes admitted non-cached objects and pending transitions. Stopped caches retain their disk but consume no CPU or memory allocation budget, preserving the current control's accounting semantics.
+- Add `acquire --cpu --memory --disk`. New guests use requested values and existing defaults for omitted fields. Stopped caches retain omitted fields and may change explicit fields before startup; disks only grow. For an effective lease, a differing explicit request reports the mismatch and points to `resize` without interrupting the guest. Repeated acquire never renews.
+- Capacity observations remain inside the authorized CT. PVE access, topology discovery and underlying-capacity probes remain excluded.
+- The native Incus and bounded one-shot control architecture remains in place. No custom persistent service, polling loop or implicit lease extension is introduced.
+- Existing effective leases are not proactively stopped to admit a different request. Native exhaustion is reported as a failure, without automatic victim selection or restart.
+
+## Enforcement and failure contract
+
+The base budgets must remain valid against authorized CT-local capacity. Their multiplied allocation ceilings may exceed that capacity. Admission must count current allocations and pending reservations atomically; a resize must not double-count its target's old and requested configurations. Native guest CPU and memory settings remain guest limits, not simultaneous host-capacity promises.
+
+Remove Incus project aggregate CPU and memory quotas that count stopped caches, rather than using them as an active-allocation limit. The one-shot control owns the active allocation ceiling; this does not claim a security boundary against trusted host-root access outside control. Other native limits and existing ownership checks remain applicable.
+
+Actual memory headroom must come only from a validated CT-local view bounded by the CT's effective memory limit. Missing or contradictory measurements fail the new admission explicitly. New admission checks do not reserve the entire requested virtual memory size, estimate future guest workloads, promise OOM prevention, or poll continuously.
+
+A denial must name its dimension and give the requested value, projected allocation, ceiling or measured headroom and threshold as applicable. Native startup or resize failure must preserve the existing lease and partial-failure contracts; it is not silently converted into a quota denial. A guest stopped unexpectedly under an effective lease must be reported on the next observation. Report OOM as the cause only when native evidence supports it; do not automatically restart or choose another live VM to terminate.
+
+The existing lease, disk-reclamation, transfer and host-authorization contracts remain applicable. CLI and control use protocol 2 so new configuration requests cannot be silently ignored by an older peer. Existing operation records and state are retained; uncertain requests are not converted or replayed across protocols.
+
+## Verified implementation constraints
+
+The baseline control validated that its CPU and memory allocation budgets did not exceed CT-visible capacity before checking the admitted total. Raising configuration values alone would therefore produce `resource_budget_invalid`; physical capacity and the oversold allocation ceiling must become separate concepts.
+
+Incus project CPU and memory quotas sum configured resources across all instances, including stopped caches, whereas control excludes stopped caches from its CPU and memory totals. A project quota equal to an active-allocation ceiling would let disposable caches consume that ceiling. The design must settle this difference instead of copying one number into both layers. See the [official project limits](https://linuxcontainers.org/incus/docs/main/reference/projects/#project-limits) and the [7.5.1 aggregate calculation](https://github.com/lxc/incus/blob/v7.5.1/internal/server/project/permissions.go#L1763).
+
+Numeric VM vCPU allocations share scheduling capacity. Incus memory ballooning can reduce a configured guest limit, but does not establish automatic balancing under CT memory pressure. Native memory exhaustion can trigger cgroup OOM and terminate a QEMU process. Admission observations cannot guarantee that already admitted guests will never exhaust memory later. See the [VM CPU and memory options](https://linuxcontainers.org/incus/docs/main/reference/instance_options/) and the [Linux cgroup memory interface](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files).
+
+These facts were checked against source and official documentation without CT/PVE access. Observed rollout and empirical coverage are recorded in the topic implementation companion.

package/toolkit/skills/docs/vendor/dot-codex/adr/0027-release-tracker-ownership.md

@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Distinct CI and Release Tracker Ownership
+
+Delivery uses a dedicated Release Tracker, separate from CI observation, because passed checks do not establish actual publication or production deployment. An authorized release may proceed during a tracker outage, while bounded handle waiting and owner-issued `$flow-continue` retain the unfinished verification obligation without creating a heartbeat, cron, or app automation. Publication identity may differ from the fixed release origin only through a proven repository-owned lineage, supporting release preparation PRs without accepting unrelated artifacts.
+
+Requirements belong to [Release Tracking](../specs/release-tracking/SPEC.md); execution rules belong to the [shared release contract](../../skills/project-engineering-workflow/references/release-tracking-short-contract.md).

package/toolkit/skills/docs/vendor/dot-codex/adr/0028-wave-thread-coordinator.md

@@ -0,0 +1,22 @@
+# ADR 0028: Wave Thread Coordinator
+
+- Status: Superseded by ADR 0029
+- Successor: `docs/adr/0029-wave-thread-delivery-batches.md`
+- Supersedes: `docs/adr/0011-parallel-direct-pr-flow.md` and the active coordination portions of `docs/specs/initiative-flow/`.
+- Date: 2026-10-11
+
+## Context
+
+The former coordination flows split ownership across Initiative tickets, aggregate PRs, and an independent Parallel PR coordinator. That topology added state surfaces and made recovery depend on multiple ledgers. The delivery model needs one owner-facing parent conversation that can plan continuous waves, dispatch fresh task conversations, receive task events, and integrate sibling PRs without GitHub Stacked PR.
+
+## Decision
+
+Adopt `wave-thread-flow` as the only active multi-task coordinator. The parent conversation owns a parent branch, a parent PR, and conversation-local wave state; no coordination manifest is committed to the project. Each task conversation receives an envelope, works in an isolated worktree, and creates a direct child PR targeting the current parent branch. Same-wave children are siblings; dependencies are deferred to later waves after prerequisite merges.
+
+Task progress is delivered by explicit structured messages. The parent does not poll, schedule a heartbeat, or infer completion from absence. A plan approval authorizes in-scope child dispatch, planned release checkpoints, and ready child merges. The final parent PR remains owner-controlled at Step 5C Ready.
+
+Release checkpoints prefer a parent-branch non-production preview and use trunk-only publication only when repository policy offers no non-trunk route. The flow keeps the shared direct PR gates and does not create a Tracking Issue, aggregate PR, child PR chain, or runtime database.
+
+## Consequences
+
+Recovery has one durable source in the parent PR plus live GitHub PR facts and received messages. Event delivery is explicit and idempotent. Parent-branch changes invalidate stale child base evidence and force revalidation. Historical materials remain auditable but cannot be selected by new plans.

package/toolkit/skills/docs/vendor/dot-codex/adr/0029-wave-thread-delivery-batches.md

@@ -0,0 +1,28 @@
+# ADR 0029: Wave Thread Four-Level Delivery Batches
+
+- Status: Accepted for historical compatibility; superseded for active routing
+- Superseded for active routing by: `docs/adr/0037-dev-plan-multi-task-flow-routing.md`
+- Supersedes: `docs/adr/0028-wave-thread-coordinator.md`
+- Date: 2026-10-24
+
+## Context
+
+This ADR applies only to the retired `wave-thread` coordinator and its read-only compatibility inputs. It does not govern the active `multi-task-flow` route, whose runtime ledger decision is recorded in ADR 0037.
+
+The original Wave Thread contract described parent and task conversations plus waves, but it did not name the unit that owns one final merge. That ambiguity made a single parent PR look like one PR per wave and did not define how several independent main-branch merges should be represented. Event and acceptance evidence also lacked an explicit batch scope and lifecycle phase.
+
+## Decision
+
+Adopt the stable hierarchy Plan -> Delivery Batch -> Development Wave -> Task. The Plan owns one coordination conversation. A Delivery Batch owns one final main-branch merge, its parent branch/PR when using parent-child topology, its SHA lineage, milestones, release facts, and resource closeout. A Development Wave is a consecutive scheduling round inside a batch. A Task owns one isolated worktree, one implementation branch, one declared surface, one native task identity, and one implementation PR.
+
+Use one parent-child batch with one parent PR by default, even when the batch needs multiple waves. Create multiple batches only when separate main-branch merges are required. The direct topology is reserved for one wave with one task; its implementation PR is the final PR to the target branch and there is no parent PR. Sibling PRs always target their owning batch parent branch; child PR chains, PR identity reuse, and stacked metadata are invalid.
+
+Represent the model in schema version 2. Task events use `wave-thread/v2` with stable `event_id`, `plan_id`, `batch_id`, and scope. Batch events carry release and milestone facts without a fabricated task. Same identity and payload is idempotent; conflicting payloads fail transactionally; missing prerequisites are deferred and replayable. v1 input is read-adapted into one `default` batch while preserving source facts and legacy closeout evidence.
+
+Bind dependencies to explicit task or batch milestones. There is no cross-batch global wave barrier. Conditions remain unknown until resolved; an approved false condition records a skip without creating resources. Acceptance evidence names task/batch scope and `pre_merge`, `post_merge`, or `post_deploy` phase. Each v2 batch declares an absolute `observation_window.deadline`; publication, deployment, and observation remain batch facts bound to the merged SHA or a verifiable shared lineage, and recovery cannot reset that deadline.
+
+Acceptance entries are owned by the matching task or batch. Task `pr_ready` consumes the task's pre-merge evidence; final readiness consumes the batch's pre-merge evidence; parent-child finalization additionally requires native child conversation archive receipts. Deadline evaluation records the expired phase, missing evidence, and original absolute deadline without treating timeout as success.
+
+## Consequences
+
+The parent conversation remains the coordination owner for the historical wave-thread route, and that route still contains no runtime coordination ledger. The active `multi-task-flow` route is governed by ADR 0037 and owns one authoritative runtime ledger. Existing v1 plans and manifests remain readable, while new multi-batch plans must use the explicit v2 syntax.

package/toolkit/skills/docs/vendor/dot-codex/adr/0030-dev-plan-single-source-wave-thread.md

@@ -0,0 +1,25 @@
+# ADR 0030: Single Source for Wave Thread v2 Plans
+
+- Status: Accepted
+- Date: 2026-10-25
+- Related: `docs/adr/0029-wave-thread-delivery-batches.md`
+
+## Context
+
+Wave Thread v2 raw-plans previously repeated batch and task fields in both `Task Orchestration` and `Wave Thread Contracts`. The duplicate view made human-readable plans longer and forced the checker to prove equality between two representations of the same contract. It also blurred the boundary between new plan generation and historical JSONL replay.
+
+## Decision
+
+Use `Task Orchestration` as the only canonical v2 plan contract. Batch lines carry the existing batch fields plus `parent_branch`, `child_pr`, `topology`, `event_protocol`, and `release_policy`; nested task lines remain the source of owned surfaces, dependencies, conditions, acceptance IDs, and `$skill`.
+
+New raw-plans reject `## Wave Thread Contracts` with the stable finding code `WAVE_THREAD_V2_DUPLICATE_CONTRACT`. Historical JSONL that already contains the duplicated section remains readable through an explicit read-only legacy adapter. The adapter is selected only by the session JSONL route and cannot validate or generate a new raw-plan.
+
+## Alternatives Considered
+
+- Keep both sections and improve their prose: rejected because duplication still creates two machine sources and requires cross-section equality checks.
+- Move the second section to a separate renderer or artifact: rejected because it would introduce another input that an Agent must read and maintain.
+- Drop historical compatibility: rejected because old session JSONL remains a supported read-only replay input.
+
+## Consequences
+
+New plans are shorter and have one authoritative manifest for parsing, while legacy replay retains a narrow compatibility branch. The parser and shell checker now have separate canonical and legacy entry points; tests must cover both paths. This decision changes Markdown plan parsing only and does not alter Wave Thread runtime events, Worktrees, PR lifecycle, SHA lineage, archive, or release semantics.

package/toolkit/skills/docs/vendor/dot-codex/adr/0031-dev-plan-owner-review-projection.md

@@ -0,0 +1,25 @@
+# ADR 0031: Transient Owner Review Projection for Dev Plans
+
+- Status: Accepted
+- Date: 2026-10-25
+- Related: `docs/adr/0030-dev-plan-single-source-wave-thread.md`
+
+## Context
+
+The canonical `$dev-plan` Markdown must remain strict enough for the checker and execution flow, but its task rows are not an efficient owner-facing review view. Maintaining a second task registry would reintroduce the duplication that ADR 0030 removed and would make the displayed plan another source of execution truth.
+
+## Decision
+
+Keep `Task Orchestration` as the only v2 execution contract and require new v2 tasks to carry `title`, `purpose`, and `outputs` as display metadata. After the canonical raw-plan passes validation, `bin/plan-cli.sh` derives a transient Markdown projection from the same parsed facts and writes it only to stdout or the current response.
+
+The projection has nine fixed sections: decision card, goals, non-goals, wave and dependency graph, execution rules, task cards, constraints, acceptance checklist, and review/runtime closeout. The Mermaid graph may show only canonical waves, tasks, same-wave parallelism, and explicit dependencies. The projection is not persisted, is not reparsed, and is not accepted as raw-plan input. Historical JSONL remains on the explicit read-only legacy route and cannot enter the new generation path. File-based projection input is restricted to paths that resolve inside the candidate Worktree, and owner-facing metadata is escaped before Markdown or Mermaid rendering. The file route opens the resolved relative path through no-follow directory handles so validation and reading share the same candidate boundary.
+
+## Alternatives Considered
+
+- Keep a second human-readable task contract: rejected because it duplicates execution facts and creates reconciliation work.
+- Ask the Agent to hand-write the review view: rejected because prose drift could hide missing tasks, dependencies, or acceptance bindings.
+- Persist a rendered Markdown artifact: rejected because it creates another plan object that later turns could mistake for an execution input.
+
+## Consequences
+
+Owners receive a stable, readable review view with a Mermaid wave/dependency graph while the execution parser continues to consume one canonical contract. The display metadata slightly expands new v2 task rows, but historical JSONL is not migrated and remains covered by compatibility replay. The change affects Markdown plan presentation and validation boundaries only; Wave Thread runtime events, Worktrees, PR lifecycle, SHA lineage, archive, and release semantics are unchanged.

package/toolkit/skills/docs/vendor/dot-codex/adr/0032-dev-plan-single-finalization-gate.md

@@ -0,0 +1,86 @@
+# ADR 0032: One Finalization Gate for Dev-Plan Owner Review
+
+- Status: Accepted
+- Date: 2026-10-26
+- Related: `docs/adr/0030-dev-plan-single-source-wave-thread.md`, `docs/adr/0031-dev-plan-owner-review-projection.md`
+
+## Context
+
+Explicit `$dev-plan` output has two necessary concerns.
+
+The canonical raw-plan must satisfy the machine contract, and the owner-facing response must be a complete readable projection.
+
+Treating those checks as separate public gates makes a raw-plan pass look like a successful plan response even when the projection is missing or inconsistent.
+
+The projection also needs task titles, purposes, and outputs.
+
+Reconstructing those fields from a second task list would reintroduce the duplication that ADR 0030 removed.
+
+## Decision
+
+Use `bin/plan-cli.sh` as the only finalization route for explicit `$dev-plan`.
+
+It runs the canonical raw-plan checker, parses the same canonical facts, and derives the transient owner-facing view.
+
+It validates the view and returns one result: `pass` with projection output or `reject` with stable findings and no output.
+
+`bun run bin/plan_contract_check.ts --plan` remains a lower-level raw-contract diagnostic and compatibility test entrypoint.
+
+Its success alone does not authorize an explicit plan response.
+
+Native Codex Plan Mode without `$dev-plan` remains outside this route.
+
+New v2 task lines carry non-empty `title`, `purpose`, and `outputs` fields alongside execution fields.
+
+The projection renders nine fixed sections and a Mermaid graph from those canonical facts.
+
+It is stdout-only, is never persisted, and is never reparsed as an execution contract.
+
+The projection's task-card section also renders every non-empty canonical batch lifecycle field.
+
+Finalizer rejection messages expose stable finding codes without echoing raw plan content.
+
+Historical compatibility requires one proposed-plan block, and section extraction ignores headings inside fenced examples.
+
+The finalizer also rejects NUL input before raw checking and preserves direct task profile syntax in the owner-facing task card.
+
+It rejects task and acceptance-card drift plus duplicate route-driving sections before adapting direct facts.
+
+It opens every absolute tool-root component without following symlinks. The tool root is the selected entrypoint’s installation or candidate root, independent of the business project and working directory. Ordinary projects invoke a trusted installed entrypoint with stdin; dot-codex development validates the current candidate entrypoint and its paired checker, not runtime or another checkout.
+
+It also ignores fenced proposed-plan markers in both Python and shell historical validation.
+
+The file input route is tool-root-bound (relative paths are relative to that root), traverses directories and the final file with no-follow descriptors, and rejects non-regular inputs before reading.
+
+Historical JSONL and proposed-plan wrappers are rejected by the projection route.
+
+Historical duplicated contracts remain readable only through the explicit legacy parser.
+
+Its wrapper extractor stops at the first valid closing marker and rejects extra markers.
+
+Accepted flow aliases are normalized before canonical route selection.
+
+Direct-task skill annotations are preserved in the owner-facing card wherever the accepted task syntax places them.
+
+Every direct task form accepted by the raw checker must either project successfully or produce a rejection rather than disappear.
+
+## Alternatives Considered
+
+- Keep raw validation and projection validation as separate user-facing gates: rejected because either failure must produce the same blocked plan result. Separate success states are misleading.
+- Make the projection a second machine-readable contract: rejected because it duplicates execution facts and creates drift risk.
+- Change native Plan Mode to use the projection route: rejected because the custom contract is authorized only by explicit `$dev-plan`.
+- Drop historical JSONL compatibility: rejected because replay and audit inputs still require read-only support.
+
+## Consequences
+
+Explicit `$dev-plan` has one clear success boundary and one clear failure shape.
+
+The raw checker remains reusable for focused diagnostics, while the finalizer owns the combined decision.
+
+New v2 fixtures must include display metadata.
+
+Projection tests must verify section order, graph presence, fact coverage, stdout-only behavior, and tool-root path isolation in both installed and candidate invocation scenarios.
+
+This decision changes Markdown plan finalization only.
+
+It does not change Wave Thread runtime events, Worktrees, PR lifecycle, SHA lineage, archive behavior, or release semantics.

package/toolkit/skills/docs/vendor/dot-codex/adr/0032-flow-scoped-model-profile-allowlists.md

@@ -0,0 +1,36 @@
+# ADR 0032: Flow-Scoped Model Profile Allowlists
+
+- Status: Accepted; Direct Review portion superseded by [0038 Direct Review Terra Profile](0038-direct-review-terra-profile.md)
+- Date: 2026-10-26
+- Related: `docs/specs/workflow-agent-model-selection/SPEC.md`
+
+## Context
+
+The runtime can support more model/effort pairs than a particular workflow should select autonomously. Treating the runtime capability table as the flow policy would make Code Review and Wave Thread drift together, while a strict pre-check would prevent the owner from deliberately requesting a different pair and let the flow hide the runtime's actual error.
+
+The retired review-orchestration ladder in `bin/flow_receipt.py` is outside this decision and remains unchanged; this policy does not restore or reclassify that historical boundary.
+
+## Decision
+
+Keep separate, exact profile allowlists for Code Review and Wave Thread. Code Review lanes choose independently from this ordered six-profile allowlist (the direct-review portion is superseded by ADR 0038):
+
+1. `gpt-6-luna + high`
+2. `gpt-6-luna + max`
+3. `gpt-5.6-luna + xhigh`
+4. `gpt-5.6-luna + max`
+5. `gpt-6.1-terra + xhigh`
+6. `gpt-6.1-sol + medium`
+
+### Wave Thread task profiles
+
+Wave Thread tasks choose and lock one of this ordered three-profile allowlist:
+
+1. `gpt-6-luna + max`
+2. `gpt-5.6-luna + xhigh`
+3. `gpt-5.6-luna + max`
+
+The native task pair is `model` + `thinking`, where `thinking` is the native reasoning-effort field. Without a direct owner instruction, autonomous selection is limited to the corresponding allowlist. A complete owner instruction containing both `model` and `thinking` may bypass that allowlist; the flow passes the exact pair to the runtime without a capability pre-check, and the runtime remains responsible for accepting or rejecting it. An invocation-wide override covers all tasks in that invocation unless the owner names a narrower task. Model-only or thinking-only instructions are not complete overrides. The flow does not silently replace a failed selection, and future runtime capabilities do not enter either allowlist automatically.
+
+## Consequences
+
+The same runtime may expose profiles that neither flow selects by default. Code Review evidence can use lane-specific profiles, while Wave Thread recovery preserves task identity and its selected profile. Allowlist changes are explicit policy changes rather than incidental runtime discovery.

package/toolkit/skills/docs/vendor/dot-codex/adr/0032-phase-aware-acceptance-gates.md

@@ -0,0 +1,41 @@
+# 0032 Phase-Aware Acceptance Gates
+
+## Status
+
+Accepted
+
+## Context
+
+Direct/v1 plans previously rendered acceptance as one undifferentiated list. That allowed a criterion whose truth depended on a merged commit, a release, or a deployment observation to be interpreted as a pre-merge readiness gate. It also made a Candidate-only evidence card appear sufficient for later closeout, even though the required merge or deployment identity did not exist.
+
+The project workflow is trunk-only: both formal and informal releases are based on a pull request that has actually merged. `Step 5C Ready` is therefore a pre-merge handoff, not a release or deployment result.
+
+## Decision
+
+Use one canonical acceptance manifest with explicit `scope` and `phase` on all new direct/v1 items:
+
+- `scope=plan` is the direct-plan scope.
+- `phase=pre_merge` binds evidence to `candidate_sha` and is the only phase consumed by Review Readiness, PR convergence, and Step 5C.
+- `phase=post_merge` binds evidence to the `merge_sha` in a real Merge Receipt.
+- `phase=post_deploy` binds evidence to that same `merge_sha` and a structured `deployment_identity`. The identity carries the deployment ID, operation ID, external locator, provider provenance, observed state, and source/bound SHA fields equal to the Merge Receipt SHA.
+
+Post-merge evidence is recorded through the existing flow receipt and ledger lifecycle. It does not create a second ledger, tracking issue, aggregate PR, or release entry point. A post-merge record is rejected until the matching Merge Receipt exists; a post-deploy record is rejected without deployment authority. Closeout remains blocked until all applicable later-phase items are proved. PR-bound Flow Complete also requires a registered canonical acceptance manifest; a missing manifest is an owner-action blocker rather than an empty acceptance set.
+
+The owner-facing plan projection is derived from the canonical manifest and shows two phase headings: `PR 合并前验收` and `PR 合并后验收`. Each acceptance item is rendered as a readable card with its ID, scope when present, proof target, pass conditions, and evidence. Post-merge and post-deploy cards also show their applicable trigger rather than adding another phase column. Cards keep long evidence and assertion text in semantic lines, so the owner-facing view does not depend on equal-width table columns. This is a display projection only and never becomes a second machine contract. Wave Thread v2 keeps its existing batch/task graph and Mermaid projection.
+
+Historical JSONL without phase is compatible only when its text has no merge, release, deployment, or observation ambiguity; it maps read-only to `plan/pre_merge`. Ambiguous history is rejected and is not auto-promoted to a later phase.
+
+## Consequences
+
+Review readiness can finish without waiting for facts that cannot exist before merge, while the flow cannot claim overall completion by silently dropping post-merge work. Missing deployment identity or mismatched SHA lineage is visible as an owner-action blocker. Deterministic tests can prove the identity transitions and rejection paths; this decision does not authorize real deployment or publication during plan validation.
+
+## Rejected Alternatives
+
+- Keep one implicit acceptance phase: rejected because it permits a later fact to block or falsely satisfy a pre-merge gate.
+- Duplicate the manifest into separate pre/post registries: rejected because the two copies would drift; the cards remain projections of one manifest.
+- Retain multi-column acceptance tables: rejected because long evidence and assertion text is difficult to scan when a renderer allocates narrow or equal-width columns; cards preserve the same facts with natural wrapping.
+- Treat `merge-ready` as complete when no deployment is requested: rejected because trunk-only publication still requires an actual merge fact, and deployment applicability must be determined by the relevant post-merge contract rather than inferred from the pre-merge card.
+
+## Verification
+
+The manifest parser, contract checker, flow receipt, plan projection, profile replay model, and replay fixtures cover explicit phases, legacy ambiguity, Candidate-only evidence, merge-SHA binding, structured deployment identities, and the `merge-ready` versus `Flow Complete` boundary.

package/toolkit/skills/docs/vendor/dot-codex/adr/0033-bun-typescript-script-runtime.md

@@ -0,0 +1,41 @@
+# ADR 0033: Bun + TypeScript Script Runtime
+
+- Status: Accepted
+- Date: 2026-10-27
+- Related: `docs/specs/bun-typescript-scripts/SPEC.md`, `docs/adr/0022-sandboxed-reg-cli-report-execution.md`, `docs/adr/0029-wave-thread-delivery-batches.md`
+
+## Context
+
+The repository maintains a large set of Python command-line helpers, tests, and shell wrappers. The scripts are mostly standard-library code but include shared state formats, POSIX locks, process supervision, secure path handling, image comparison, and macOS sandboxed report generation. A runtime replacement can improve consistency and startup behavior only when those contracts are preserved and measured.
+
+The migration also needs a test runner that supports focused domain execution without adding a second JavaScript test framework. Long files have made ownership and review harder, so the replacement needs a physical-line policy that forces responsibility-based module boundaries.
+
+## Decision
+
+- Use Bun 1.4.4 and TypeScript as the maintained script runtime, with strict compiler settings, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, and `noEmit`.
+- Use Bun's built-in `bun:test` runner. Expose `test:core`, `test:hosting`, `test:plan`, `test:flow`, `test:workspace`, `test:docs`, `test:visual`, `test:waves`, `test:checks`, `test:multi-task`, and `test:all`; platform-specific tests remain explicit and a skip is not a pass.
+- Keep existing CLI directories and basenames, replacing `.py` with `.ts`. Shell wrappers may remain only as thin Bun forwarders that preserve arguments, stdin, and exit codes.
+- Split shared behavior into typed modules and keep each handwritten TypeScript source file at or below 400 physical lines and each TypeScript test file at or below 600 physical lines, counting blank and comment lines. Formatting runs before the line counter, and no ignore or compression bypass is allowed.
+- Preserve CLI diagnostics, machine output, state schemas, canonical JSON hashes, lock paths, atomic write order, historical JSONL parsing, and replay behavior. Existing runtime state is read and written through compatible formats without an in-place migration.
+- Isolate `flock`, no-follow directory-descriptor reads, and macOS `clonefile` behind a small POSIX adapter. Use `bun:ffi` only at that boundary; missing capabilities fail explicitly and no unsafe realpath/open fallback is permitted. The experimental and platform-specific nature of this boundary is part of the contract.
+- Use `sharp@0.35.5` for image decoding and encoding while preserving comparison and trim semantics. Keep the existing pinned `reg-cli@0.18.16`, Node/npm lockfile, two-stage sandbox, and publication isolation unchanged.
+- Keep Python only as a read-only comparison implementation during the four-wave migration. Delete maintained Python sources and executable Python references only in the final cutover after compatibility evidence is complete.
+
+## Alternatives Considered
+
+- Keep Python and add Bun wrappers: rejected because it preserves the second runtime and does not make domain tests or module ownership consistent.
+- Add Jest or Vitest: rejected because Bun already supplies the required test runner and an extra framework would add dependency and configuration surface.
+- Replace native operations with portable but weaker filesystem fallbacks: rejected because path replacement, lock release, and sandbox boundaries are security and correctness contracts.
+- Promise a fixed speedup: rejected because startup and workload performance must be measured on the same isolated environment and reported with p50, p95, RSS, and causes.
+
+## Consequences
+
+- The project has one maintained scripting runtime and one test command family, but migration requires a large compatibility fixture and explicit native validation.
+- Bun FFI and sharp introduce platform/runtime boundaries that must be checked in the Agent VM and on macOS; unsupported capability is a visible failure.
+- The physical-line policy creates more modules and review surfaces, while keeping files bounded and responsibilities clear.
+- Node/npm remains a deliberate exception for the existing reg-cli sandbox, so “no project Python” does not mean “no other runtimes anywhere.”
+
+## Verification
+
+- `docs/specs/bun-typescript-scripts/SPEC.md` remains the normative behavior contract.
+- `bun run check:source`, `bun check`, `bun fmt --check`, the domain test commands, Linux VM native scenarios, macOS smoke tests, and the same-input Python/Bun performance report are required before the parent reaches Step 5C.

package/toolkit/skills/docs/vendor/dot-codex/adr/0033-empirical-acceptance-and-repair-autonomy.md

@@ -0,0 +1,31 @@
+---
+status: accepted
+---
+
+# ADR 0033: Empirical Acceptance and Repair Autonomy
+
+## Status
+
+Accepted. Supersedes [ADR 0020](0020-empirical-acceptance-review-gate.md).
+
+## Context
+
+Empirical acceptance establishes whether an accepted behavior can be proven by deterministic repository-local validation. A separate cumulative Repair Batch count provides useful continuity and a signal of repeated work. Making the fourth repair depend on a new owner approval does not establish correctness or diagnose an expanding design, and interrupts authorized work.
+
+## Decision
+
+- Retain ADR 0020 decisions 1–5: proofability determines whether an obligation applies; evidence binds the Candidate, acceptance contract, scenario set, outcome and locator; applicable passed evidence gates review and readiness; changes to accepted external behavior return to design; a failed empirical run after a comparable pass is diagnosis-only.
+- Continuation anchors retain the obligation, current evidence, Candidate and cumulative Repair Batch count. Missing or mismatched facts block recovery rather than being inferred or reset.
+- Within the selected flow and approved scope, the main Agent decides and executes eligible repairs without per-batch owner approval. Near three batches or when the same root cause recurs, it diagnoses the approved scope, baseline, implementation and tests before continuing. A new behavior, contract or wider scope follows the existing design and owner-decision boundary.
+
+## Consequences
+
+- Empirical evidence and safety gates remain independent of repair count.
+- A count supports diagnosis and continuation without imposing a repair authorization budget.
+- A failed empirical comparison remains diagnosis-only; it is not an automatic repair authorization.
+
+## 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)
+- [PR Convergence Batching](../specs/pr-convergence-batching/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/adr/0034-bun-cli-launch-boundary.md

@@ -0,0 +1,36 @@
+# ADR 0034: Trusted Bun CLI Launch Boundary
+
+- Status: Accepted
+- Date: 2026-10-27
+- Related: `docs/specs/bun-typescript-scripts/SPEC.md`, `docs/adr/0033-bun-typescript-script-runtime.md`, `docs/adr/0032-dev-plan-single-finalization-gate.md`
+
+## Context
+
+Bun evaluates configured preload hooks before a TypeScript entrypoint reaches its `main()` function. A candidate-root or input validation routine inside the TypeScript process therefore cannot establish a security boundary when a caller can set `BUN_OPTIONS` or `NODE_OPTIONS`. Direct source execution is useful during development, but it is not sufficient as the secure interface for commands that read or validate candidate plans.
+
+## Decision
+
+- Sensitive candidate-input CLIs MUST be entered through a repository-controlled launcher owned by the corresponding command surface.
+- The launcher MUST clear `BUN_OPTIONS` and `NODE_OPTIONS`, select a repository-controlled Bun configuration, and then `exec` the TypeScript entrypoint while forwarding arguments, stdin, and the child exit code.
+- The launcher is the trusted boundary. TypeScript validation remains responsible for candidate paths, files, and state after startup, but it is not responsible for preventing pre-main preload execution.
+- Direct `bun run <entrypoint>.ts` remains a development and debugging interface only. Documentation and tests MUST distinguish it from the secure launcher path.
+- The implementation MUST use a Bun configuration-control mechanism supported by the pinned Bun 1.4.4 runtime. It MUST NOT rely on an undocumented or unavailable `--no-config` flag.
+
+## Alternatives Considered
+
+- Validate `BUN_OPTIONS` and `NODE_OPTIONS` inside TypeScript: rejected because preload code executes before that validation.
+- Treat direct `bun run` as secure: rejected because callers can influence pre-main runtime behavior.
+- Remove all TypeScript entrypoints and expose only a compiled binary: deferred because it changes the repository's script interface and is outside this migration's compatibility scope.
+
+## Consequences
+
+- Sensitive command documentation gains an explicit launcher path and a development-only direct path.
+- A small shell boundary becomes part of the security contract and must remain covered by hostile-environment tests.
+- The launcher must track Bun 1.4.4 configuration semantics and fail closed if the controlled configuration cannot be selected.
+- This boundary does not change plan schemas, candidate validation rules, state formats, or exit-code compatibility after startup.
+
+## Verification
+
+- Run each sensitive command through its launcher with hostile `BUN_OPTIONS` and `NODE_OPTIONS` values and confirm no preload hook executes.
+- Confirm the launcher uses the repository-controlled Bun configuration and forwards stdin, arguments, diagnostics, and exit codes unchanged.
+- Keep direct TypeScript invocation tests explicitly labeled as development-only coverage.

package/toolkit/skills/docs/vendor/dot-codex/adr/0034-priority-aware-review-repair-eligibility.md

@@ -0,0 +1,16 @@
+---
+status: accepted
+---
+
+# ADR 0034: Priority-Aware Review Repair Eligibility
+
+Formal review must preserve genuine defects without turning every low-priority finding into another repair wave. The workflow therefore keeps the canonical finding classifications from [ADR 0016](0016-bind-review-repairs-to-approved-scope.md), but adds a main-Agent repair threshold: an initial Formal Review Wave may optionally repair an eligible P2-only finding; later P2 repair requires an eligible P0/P1 finding or a qualifying current-Candidate CI failure in the same root-cause batch. P2/P3-only results may clear with an explicit `repair_not_required_low_priority` resolution and are reported at the next owner-facing stop. P3 and lower findings are not independent repair targets.
+
+`Design-Returning Review Finding`, safety boundaries, required acceptance, and unavailable or failed evidence retain their existing gates regardless of priority. The retired standalone review-loop Skill is outside this workflow decision and is not a second convergence path.
+
+## Consequences
+
+- Low-priority findings remain visible without forcing a repair batch or a new review wave.
+- A first-wave P2 repair consumes the ordinary cumulative Repair Batch count; accepting the finding without a write consumes no batch.
+- A qualifying CI failure can justify a related P2 repair after the initial wave, while infrastructure or unavailable CI evidence cannot.
+- The canonical reviewer disposition schema remains unchanged; the threshold is recorded as main-Agent `repair_resolution` evidence.

package/toolkit/skills/docs/vendor/dot-codex/adr/0035-task-orchestration-ledger.md

@@ -0,0 +1,20 @@
+# ADR 0035: Task Orchestration Ledger
+
+- Status: Accepted
+- Related: `docs/adr/0029-wave-thread-delivery-batches.md`
+
+## Context
+
+An owner-approved task orchestration coordinates concurrent task conversations, PR integration and dynamic parent PR cuts. Agents need a recoverable shared record that remains available across conversation interruptions and independent Worktrees.
+
+## Decision
+
+Keep one authoritative JSON ledger per orchestration under the multi-task-flow Skill's own data directory. Serialize ledger updates with an operating-system process lock and atomic replacement, and record external operation claims before invoking the platform. The ledger retains unresolved claims until the external result can be verified. A read-only dashboard projects the ledger; it is not a second source of state.
+
+Dependencies are explicit task and milestone facts, not waves. The coordinator and task conversations remain separately owned. Native thread creation and platform operations use their respective existing boundaries.
+
+This decision applies only to the multi-task-flow Skill. Legacy conversation-local coordination contracts remain read-only compatibility surfaces and are not modified by this Skill.
+
+## Consequences
+
+The ledger survives individual task Worktrees and allows reliable concurrent bookkeeping on one machine. Its schema, locking, recovery, resource cleanup and local service require explicit validation. Ambiguous native operations remain blocked rather than being guessed or retried.