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

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-agent-model-selection/SPEC.md

@@ -0,0 +1,86 @@
+# Workflow Agent Model Selection
+
+## Related ADRs
+
+- [0003 External Fact Delivery Gates](../../adr/0003-external-fact-delivery-gates.md)
+- [0014 Direct Review Evidence](../../adr/0014-direct-review-evidence.md)
+- [0017 Review Readiness And Runtime Launch](../../adr/0017-review-readiness-and-runtime-launch.md)
+- [0034 Priority-Aware Review Repair Eligibility](../../adr/0034-priority-aware-review-repair-eligibility.md)
+- [0038 Direct Review Terra Profile](../../adr/0038-direct-review-terra-profile.md)
+
+## Context and Scope
+
+Workflow launch settings remain explicit while direct review evidence stays independent from task identity, child provenance, transcript shape, and receipt ledgers. Trackers retain their separate external-fact responsibility.
+
+Runtime formal review requires Review Readiness: approved behavior and acceptance, scope, and required contracts are stable; no design decision is unresolved; and the current Candidate has completed applicable validation and visual evidence. Plans recommend a tier-consistent strategy and supported profile set, while each formal reviewer identity is created fresh at runtime.
+
+The retired review-orchestration ladder in the flow receipt adapter is outside this active policy and remains unchanged; this Spec does not restore or reclassify it.
+
+## Requirements
+
+### REQ-DIRECT-REVIEW-MODEL
+
+- `code-review` MUST use exactly this ordered allowlist for autonomous selection:
+  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`
+- Ordinary review MAY use profiles 1-3 and MUST default to profile 1 when no stronger distinction is available. Complex or rigorous review SHOULD use profiles 3-4. Special or high-risk review SHOULD use profiles 5-6 and MUST record a natural-language lane-specific escalation reason; the contract does not require a fixed serialization such as `lane=...; reason=...`.
+- The actual supported model/effort pair is recorded in each review result. Autonomous selection uses `gpt-6.1-sol`, `gpt-6.1-terra`, `gpt-6-luna`, or `gpt-5.6-luna`. A current task's explicit `agent-model: <model>` directive remains a session-scoped model-family selection; it is not a complete direct-review owner override. A direct-review exception requires an explicit complete `model + effort` pair. Direct plan guidance names a supported pair without fixing reviewer identity; runtime launch resolves the actual pair on the current host. A higher model or effort records a lane-specific escalation reason.
+- The workflow does not impose a concurrency cap. Autonomous direct-review selection remains strictly limited to the six profiles above; only a complete owner `model + effort` override may bypass that flow allowlist. An unavailable reviewer is never treated as clear.
+- Autonomous delegated launches are limited to `gpt-6.1-sol`, `gpt-6.1-terra`, `gpt-6-luna`, and `gpt-5.6-luna`. A non-autonomous supported model requires the exact standalone first non-empty prompt line `agent-model: <model>`; `agent-model: auto` removes the override. The override is session-scoped until replaced or removed and is not inherited by a fresh task.
+
+- A live lane is waited on or relayed; a terminal agent is retired and is not reused for formal review. A changed candidate receives a fresh `fork_turns=none` reviewer. Elapsed time alone is not review failure, and an exhausted orchestration wait budget remains a non-terminal blocker until the owner continues or explicitly stops the lane. An owner-stopped lane is not retried by continuation without a new owner instruction or changed candidate; live-lane uniqueness is scoped to the current flow invocation/thread. A
+  <!-- review-anchor-contract:workflow-model-spec:start -->
+  non-terminal wait anchor carries `repo_root`, base SHA, head SHA, lane, scope, review profile, current locked flow, ownership promise, and cumulative Repair Batch count; missing context requires owner input rather than a guessed relaunch.
+  <!-- review-anchor-contract:workflow-model-spec:end -->
+- The main Agent classifies every demonstrated finding against the approved behavior, acceptance, and safety boundaries. An `In-Scope Review Finding` follows the shared review-proof contract's current-PR repair or authorized late follow-up resolution; a `Design-Returning Review Finding` stops ordinary repair and returns the task to design, and a `Review Observation` is reported without creating a repair obligation. Missing, stale, malformed, or unavailable review output remains `unchecked` evidence and is never treated as a finding or clear result.
+
+  Any disposition outside those three values is malformed and must fail closed before repair or clear classification. An In-Scope disposition also requires a demonstrated finding in the terminal structured result; missing readiness evidence blocks launch rather than implying approval.
+
+### REQ-FLOW-PROFILE-ALLOWLIST
+
+- The supported runtime capability table and flow profile allowlists MUST remain separate. Direct Review names its reasoning field `effort`; a historical coordinator task envelope names the native reasoning field `thinking`. In a compatibility input that uses generic `model + effort` wording for both flows, the historical coordinator's `effort` value maps to the single native `thinking` field and MUST NOT create a second persisted key or alias. Unless the owner directly specifies a complete pair using the current flow's field, autonomous selection MUST use only the allowlist of the current flow.
+- A runtime-supported model or flow-specific reasoning level MUST NOT become available to a flow automatically. A selected pair MUST NOT be silently replaced by another pair after a runtime failure; the runtime error is reported as-is.
+- A direct owner specification MAY bypass the current flow allowlist. The flow MUST pass the exact pair to the runtime without pre-checking whether it is executable; runtime support or rejection remains the runtime's decision. For Direct Review, model-only or effort-only is incomplete; for historical coordinator input, model-only or thinking-only is incomplete.
+- An invocation-wide owner override applies to all lanes or tasks in that invocation unless the owner names a narrower lane or task. A named override applies only to that target, does not change either allowlist, and is not inherited by another flow or task.
+- covers: VER-FLOW-PROFILE-POLICY
+
+### REQ-CODE-REVIEW-PROFILES
+
+- `code-review` MUST allow exactly these ordered profiles for autonomous selection:
+  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`
+- Ordinary review MAY use profiles 1-3 and MUST default to profile 1 when no stronger distinction is available. Complex or rigorous review SHOULD use profiles 3-4. Special or high-risk review SHOULD use profiles 5-6 and MUST record the escalation reason.
+- Every formal Code Review lane MUST select its profile independently. Each fixed or selected dynamic lane MAY use the complete six-profile allowlist, and a named owner override applies only to its named lane.
+- covers: VER-FLOW-PROFILE-POLICY
+
+### REQ-TRANSPORT-NEUTRAL-EVIDENCE
+
+- A Tier 3/4 lane is a completed read-only sub-agent result bound to its base, head, scope, profile, and complete clear structured findings. Missing or non-clear evidence remains `unchecked` and cannot satisfy the gate; unknown fields and scope mismatches are also invalid. A clear terminal result may contain a blocking finding; that finding is classified by disposition and does not make otherwise valid evidence unavailable.
+- Evidence must not require child IDs, PTC parsing, task metadata, transcript shape, or flow-receipt recording. Advisory review cannot replace a required lane.
+
+### REQ-TRACKER-PROFILE
+
+- A tracker binds one external CI or release target and returns its terminal external facts. Auth, quota, provider, timeout, or terminal failure remains explicit `unavailable` and does not cause a parent poller or model retry.
+- Release observation recovery follows [Release Tracking](../release-tracking/SPEC.md): same-chat scheduling preserves the explicit profile, original identity, retry record, and deadline rather than switching models.
+
+## Verification
+
+### VER-MODEL-SELECTION covers: REQ-DIRECT-REVIEW-MODEL, REQ-TRANSPORT-NEUTRAL-EVIDENCE, REQ-TRACKER-PROFILE
+
+- direct review output exposes its actual profile and any high-effort reason;
+- multiple lanes may run concurrently without a workflow-imposed ceiling;
+- required evidence is accepted from the current structured result without a receipt ledger or transcript-derived identity.
+- direct-flow profile tests cover recovery-anchor fields and continuation's no-relaunch behavior for owner-stopped or terminally unavailable review.
+- Subagent status output exposes base/head, lane, scope, profile, locked flow, and ownership promise for a non-terminal review anchor.
+
+### VER-FLOW-PROFILE-POLICY covers: REQ-FLOW-PROFILE-ALLOWLIST, REQ-CODE-REVIEW-PROFILES
+
+- Contract checks MUST verify the exact flow-specific profile lists, independent Code Review lane selection, task-locked historical coordinator profiles, invocation/target override scope, and the separation between flow allowlists and runtime support.

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/HISTORY.md

@@ -0,0 +1,69 @@
+# Workflow execution receipts 演进历史
+
+> 这里记录会影响 Agent 理解长期合同的关键演进；规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- Late-initialized or pre-merge unbound ledgers may close from a post-merge receipt matching the repository-bound live `MERGED` PR and merge-SHA-bound finality. The current repository identity and a valid timezone-qualified RFC 3339 merge time are revalidated at record and close. `pr_bound_at` remains evidence of an actual OPEN binding and is not synthesized during recovery.
+- Regression coverage now passes through ledger initialization and public evidence loading and close/CLI entry points, and verifies failed close attempts leave the ledger active.
+
+- Active instructions use the runtime-home receipt helper with `--repo`; the architecture check rejects target-relative helper paths without maintaining command, decoder, or wrapper allowlists.
+
+- Review orchestration moved out of the receipt ledger. Receipts retain local validation and lifecycle audit value while direct review uses current structured evidence.
+- The review-orchestration retirement inventory separates code safe to retain for validation/lifecycle from review-only legacy groups, so later deletion is deliberate and complete rather than inferred from the helper name.
+
+- Direct delivery validation no longer uses synthetic Git repositories or temporary `CODEX_HOME` paths. Only current-candidate facts may create or consume flow proof; isolated state-machine exercises are outside the delivery gate.
+- Active manifests that retained synthetic flow-receipt validation are migrated at their next gate, preserving their original manifest as read-only history; archived receipt bytes remain unchanged.
+
+- Acceptance manifest 将 local `validation` 与远端 `delivery` 验收分门别类；旧清单默认 local gate，使 existing plans 无需迁移。candidate head 只在成功干净的 pre-PR validation receipt 落盘时推进，避免 init 与 PR bind 的身份错位重跑。
+
+- Legacy receipt schema v3 may contain non-current fallback records. Current flows separate preferred workflow model/effort suggestions from resolved runtime profiles and retry an unavailable explicit override only with a different explicit pair; v2 Terra authorization remains read-compatible but is not accepted for new flows.
+
+- Native v3 review receipts now require `resolved_model` and `resolved_effort` from the tool-observed task envelope, rejecting missing or mismatched runtime profile evidence before lane registration.
+
+- owner 的 `convergence-reopen` 授权覆盖当前 PR 的首个受限 repair round；该 round 提交并推送后，账本以一次性、PR 事实绑定的 head bridge 进入 initial review，而不重复索取同一意图授权。bridge 不重置 repair 或 validation 预算。
+
+- validation scope 改由单张 receipt 的 manifest/evidence 覆盖自动派生，移除调用方 CLI override；规范化 evidence 纳入 execution identity，允许多张 targeted receipt 组合验收，并禁止 cross-head attestation 复用不同 evidence；review wave 同时在写账本前拒绝固定 SHA base-ref、在最终 lock 内重验 moving ref，以避免终态不可收口。
+
+- shared review proof 改由 `record --kind agent-review` 登记原生只读任务结果；receipt 不再为 shared flow 启动第二层 `codex exec`，旧 `record --kind review` 仅保留独立手动兼容。
+- native review profile 由 v3 caller envelope 升级为 v4 transcript-derived attestation，禁止通过 preferred/resolved 差异推断 fallback。
+- 验收证据从计划严格映射为 manifest，并由 validation receipt、synthesis 和 merge proof 逐项闭合；历史归档保持不可变，活动 v2 ledger 在 merge proof 前补登记。
+- routine lane model/effort 改为严格相等；Terra 只能通过 Luna unavailable 与主人授权绑定的 epoch mutation 启用。
+- Luna unavailable 证据改为快照验证并在原子更新区复核哈希，避免授权等待锁期间的文件替换使账本哈希脱离已验证内容。
+- 将 proof reuse 从 raw chat/SHA 推导改为 explicit receipt + current-head delta attestation。
+- 将 review convergence 从嵌套轮次改为一个不可重置的外层预算。
+- 将 ledger 放入 `git rev-parse --git-path codex-flow`，不增加 repo-tracked runtime state。
+- attestation 不再信任调用方自报 paths/fingerprints，而是从 source receipt SHA 到 current HEAD 计算 Git delta 与 effective merge fingerprint。
+- validation `record` 使用 helper-owned command runner；1800 秒预算由进程组 timeout 执行，known-long 只接受 tracked exact-command declaration。review `record` 以固定 read-only/no-approval 参数直接启动 Codex review，并从 JSONL、exit、final message 与 clean HEAD 派生证据，拒绝调用方 shell command 和自报运行事实。
+- repository-bound proof 只接受 helper 在干净 current HEAD 上实际执行的结果，Git tree 进入 effective-input fingerprint；日志限制在 ledger 专用目录，terminal run 拒绝后续写入。
+- `SPEC.md` 的 `## Visual Evidence` 变化与契约正文分开分类，使视觉证据可 scoped rebind 而不放松 Spec contract 失效规则。
+- proof lookup 使用不含 Git tree 的 stable key 关联跨 head 候选证明，执行 identity 则包含 Git tree；因此代码输入变化会重跑，而纯文档变化仍可经 current-head attestation 复用。
+- 同一 execution identity 的 preflight、执行与落盘由跨进程锁覆盖，不同 identity 保持可并行。
+- receipt 同时记录受限 log path 与内容 SHA-256；根入口项目文档可以 scoped rebind，legacy `docs/plan/**/{PLAN,SPEC}.md` 的契约变化继续强制失效。
+- 所有 ledger mutation 统一持有跨进程写锁，command log 按 execution identity 隔离；transient retry 必须提交与失败尝试不同的状态指纹，`close` 只接受明确终态。
+- retry 日志进一步按 attempt 固化；receipt 显式记录 targeted/full validation scope，并在 run 级别限制最多两次 full validation。
+- validation scope 进入 stable proof key 与 execution lock identity，避免 targeted/full proof 相互串行或误复用；共享 workflow 与 review loop 同步落地实际 CLI 调用点。
+- terminal ledger 在 close 与后续 init 前按 run identity 归档；第三轮 repair 若仍有 blocker 会立即终止，清零则完成。
+- repair wave 消费的入站 permit 与该 wave 后续签发的 permit 具有连续但不同的职责；状态机会核对前后 SHA 与来源后允许下一轮授权，同时拒绝同一 wave 重复签发。
+- review proof 改为严格 output schema 与流式 JSONL/stderr 监督；长进程只持有 proof identity lock，全局 ledger lock 仅覆盖短 mutation。
+- convergence clear 不再提前关闭顶层 flow run；dirty validation 仍按失败尝试消费预算，run id archive 不可复用或覆盖，docs-only attestation 可复用同 profile/base 的 review evidence。
+- review timeout 只由有效 JSONL progress 推进，持续 stderr/非 JSON 噪声不能绕过 300/900 秒门禁；helper 在中断时终止独立进程组。
+- failed/timeout review attempts 进入 durable ledger：startup 前只允许一次 restart，观察到 `thread.started` 后失败则禁止自动重启；focused replay 只接受 canonical helper launch。
+- launcher exception 与 owner interrupt 同样持久化；owner stop 保持显式可重启。输出管道 EOF 不再绕过存活子进程 deadline，无效 review attempt 不可提升为 attestation。
+- process-group cleanup 不再依赖 leader 存活，继承管道的 descendant 会在 timeout 后终止；连续 docs-only attestation 扁平回指原始 passed proof，避免第二次文档 delta 重跑 proof。
+- review launcher 使用 helper-owned 固定 structured-review prompt 的通用 `codex exec`，因为 `review --base` 子命令不允许同时提供 prompt，且其 skill prose 终态无法满足严格 output schema；base SHA、read-only/no-approval、JSONL 与 structured result 门禁保持不变。
+- convergence 的 blocking fingerprint multiset 使用显式计数包含判定，保持 duplicate blocker 严格递减语义并兼容不支持 `Counter` 富比较的 Python 运行时。
+- close 会检查 held execution identity lock；retry 只接受 helper 分类的 transient exit；review stall 只由已知 Codex event 刷新，CLI runtime/subprocess/OS failure 使用 JSON error object。
+- validation attestation 以显式 input path patterns 检查 delta 相交，且每次 attestation 重新核对 current base；`init` 同时验证 current clean HEAD，避免 stale ledger 与过期 merge proof。
+- normalized input paths 纳入 validation proof identity，review 同步核对 ledger base；terminal convergence 与 proof execution 串行，argparse 失败保持 JSON contract，review replay 拒绝 helper 前后拼接任意 shell wrapper。
+- malformed ledger JSON 与其他可预期 CLI failure 一样返回 JSON error object，不暴露 traceback。
+
+## Key Reasons / Replacements
+
+- context compaction、输出截断和纯文档提交不应导致相同输入上的重复工作。
+- GitHub current-SHA 门禁继续保持严格；receipt 只复用本地等价输入证明。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/IMPLEMENTATION.md

@@ -0,0 +1,17 @@
+# Workflow Execution Receipts Implementation
+
+- `${CODEX_HOME:-$HOME/.codex}/bin/flow_receipt.py` stores validation and lifecycle facts below Git metadata; callers select the candidate with `--repo` and never copy the helper into the repository.
+- Shared delivery skills use live GitHub facts, CI, validation, and direct review evidence without calling the ledger for review control.
+- Receipt bind, target-ref, and post-merge lifecycle reads use lightweight provider PR facts; complete related review/comment facts remain available to callers that need them. Wrapped adapter failures preserve safe error code and operation metadata at the CLI boundary.
+- Review-wave and repair state remains legacy compatibility behavior rather than an active direct-flow contract.
+- Live merged PR facts are authoritative when a stored binding has drifted; historical review fields are not consulted to recover post-merge identity.
+- A post-merge receipt may establish association when a ledger lacks a pre-merge bind timestamp. Closing still requires matching live `MERGED` facts and merge-SHA-bound finality, including a matching canonical repository binding and valid timezone-qualified RFC 3339 merge time; no pre-merge timestamp is synthesized.
+- A new no-release receipt binds the policy evidence to the live repository, target branch, and merge SHA. Normalization verifies structure and explicit `release_expected=false`, not the truth of the cited policy. Old receipts remain readable but cannot newly seal complete without the evidence.
+- Regression tests exercise lightweight lifecycle reads, typed CLI error provenance, late initialization through `init`, evidence-file normalization through the public record path, CLI dispatch into public `close`, and close failures for PR, repository, live merge facts, finality, and timestamp mismatches.
+- `contracts/review-orchestration-retirement.md` maps the legacy review state machine, parser surfaces, source anchors, and test/replay assets that must be removed together when archive compatibility is retired.
+
+## Verification
+
+- `python3 -m py_compile bin/flow_receipt.py`
+- `python3 bin/instruction_architecture_check.py --repo-root <candidate>`
+- `git diff --check`

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/SPEC.md

@@ -0,0 +1,56 @@
+# Workflow Execution Receipts
+
+## Related ADRs
+
+- [0003 External Fact Delivery Gates](../../adr/0003-external-fact-delivery-gates.md)
+- [0010 Post-Merge Flow Receipt Finality](../../adr/0010-post-merge-flow-receipt-finality.md)
+- [0014 Direct Review Evidence](../../adr/0014-direct-review-evidence.md)
+
+## Context and Scope
+
+Long delivery tasks need reusable local validation facts across context compaction and documentation-only changes. The receipt ledger is non-tracked audit infrastructure for validation and lifecycle facts. It does not schedule, retain, validate, or gate code review.
+
+## Requirements
+
+### REQ-RECEIPT-CORE
+
+- The receipt root resolves through `git rev-parse --git-path codex-flow`.
+- The helper resolves from `${CODEX_HOME:-$HOME/.codex}/bin/flow_receipt.py` and selects the candidate with `--repo`; active instructions must not invoke a target-relative `bin/flow_receipt.py` path. The architecture check performs lexical normalization for quoting, slash escapes, repeated separators, and dot components including parent traversal. The canonical helper must be an exact path token and must be followed immediately by `--repo`; it does not execute or emulate generated shell/Python programs.
+- `init`, validation `record`, `classify`, `status`, and `close` provide stable JSON output for audit use. Review commands are legacy compatibility surfaces, not direct-flow requirements.
+- A validation receipt binds command, toolchain, effective inputs, acceptance evidence, current head, exit code, and log digest. Equivalent inputs may reuse a passed validation fact; required CI, GitHub, owner approval, release, and review evidence remain independent delivery facts.
+- The ledger may record post-merge facts but cannot block merge cleanup or decide direct-flow completion.
+- `bind-pr`, post-merge recording, and `close` retain only live PR identity, current base/head, merge SHA, finality, and validation lifecycle checks. Historical review assessment, review-wave, and convergence fields remain readable audit data and are never a retained lifecycle gate.
+- Receipt lifecycle reads request only the PR facts needed for identity, refs, state, and merge finality; they use the adapter's explicit lightweight mode and do not request review/comment collections. Review-policy diagnosis remains on the complete PR-facts path.
+- When a provider adapter failure is wrapped by a receipt lifecycle operation, the CLI keeps the compatibility `error` field and exit code while exposing the safe adapter `error_code` and `operation` fields when an explicit cause is available. Raw provider output and credentials remain excluded.
+- `bind-pr` requires a live `OPEN` PR and `pr_bound_at` records that pre-merge binding when it occurs. `close --state complete` does not require that timestamp: a ledger initialized after merge, or initialized earlier without `bind-pr`, may complete only with one matching post-merge receipt, terminal finality bound to the merge SHA, and live `MERGED` PR facts for the same repository and PR. The ledger repository binding must match the current PR adapter's canonical provider, host, and repository identity. The merge time must be a valid timezone-qualified RFC 3339 timestamp. The receipt proves post-merge association; it does not claim a historical pre-merge binding.
+- New `not-applicable` release finality requires `release_expected=false` and structured policy evidence bound to the same provider/repository, target branch, and merge SHA, with a policy locator and nonempty rationale. Record and complete recheck that binding against live merged PR facts; conflicting or missing fields cannot seal a new complete ledger. Historical receipts remain readable, but missing evidence is not promoted to a new completion. Structural consistency does not independently establish external policy truth.
+- A `published` fact that supplies `release_expected` must use the boolean `true`; omission remains readable for older published receipt inputs.
+
+### REQ-REVIEW-ORCHESTRATION-RETIREMENT
+
+- `contracts/review-orchestration-retirement.md` is the authoritative inventory for review-only code that remains in `bin/flow_receipt.py` solely for legacy compatibility. Direct-flow cleanup must use it to distinguish retained validation/lifecycle behavior from direct-review retirement targets.
+- Direct-flow skills must not invoke an inventory retirement target. Cleanup removes an entire named group and its replay/tests together; it does not remove validation, attestation, PR-audit, or post-merge behavior by name similarity.
+- Archive-read compatibility is an explicit later decision. It must be removed or migrated together with the legacy schema fields it reads, never silently during direct-flow cleanup.
+
+### REQ-VALIDATION-IDENTITY
+
+- A stable validation key includes command, toolchain, declared input scope, normalized paths, and acceptance evidence. Execution identity additionally includes effective current inputs.
+- Documentation-only deltas may use a helper-derived scoped validation attestation when effective inputs are unchanged. Code, test, build, workflow, contract, or effective merge changes invalidate affected validation facts.
+- The helper never accepts caller-declared paths or SHAs as a substitute for Git-derived scope.
+
+### REQ-EXECUTION-SAFETY
+
+- Validation runs only in the current candidate worktree. The helper does not create synthetic repositories, worktrees, homes, review processes, network requests, or provider sessions.
+- Ledger mutation is atomically locked. Long validation holds only its own execution identity lock. Failed, dirty, stale, or timed-out validations remain explicit audit facts.
+
+## Verification
+
+### VER-EXECUTION-RECEIPTS covers: REQ-RECEIPT-CORE, REQ-REVIEW-ORCHESTRATION-RETIREMENT, REQ-VALIDATION-IDENTITY, REQ-EXECUTION-SAFETY
+
+- equivalent validation inputs reuse safely and effective changes invalidate affected validation facts;
+- a late-initialized ledger and an earlier unbound ledger can close from matching live merged facts and finality without setting `pr_bound_at`;
+- mismatched repository, PR, base/head, merge SHA, timestamp, finality, or unavailable/non-`MERGED` live facts keep an active ledger from completing;
+- missing or conflicting no-release policy evidence is rejected while valid no-release evidence remains usable and historical receipts stay readable;
+- ledger operations do not create or gate review waves, repair permits, or review evidence;
+- current direct delivery combines GitHub facts, CI, validation, and direct review evidence without a receipt-led dependency.
+- the retirement inventory names each live review-only CLI and source group; the architecture check fails if the inventory and helper drift apart.

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/contracts/review-orchestration-retirement.md

@@ -0,0 +1,45 @@
+# Review Orchestration Retirement Inventory
+
+`bin/flow_receipt.py` is retained for validation and lifecycle facts. This inventory identifies the separate review-orchestration subsystem that direct delivery no longer uses and that a later cleanup must remove as named groups.
+
+## Retain
+
+- Validation/lifecycle CLI and implementation: `init`, `acceptance-register`, `record --kind validation`, `record --kind attestation`, `record --kind post-merge`, `classify`, `status`, `close`, validation execution, scoped attestation, atomic storage, and post-merge fact recording.
+- `bind-pr` may remain as validation-audit association only. Its current review-assessment, review-state, and convergence checks must be removed before treating that command as retained-only.
+
+## Retire With Direct Review
+
+### CLI and dispatch
+
+- `review-assess` and `FlowLedger.assess_review_necessity`.
+- `review-wave open`, `review-wave finalize`, and `review-wave authorize-repair`, plus `FlowLedger.open_review_wave`, `FlowLedger.finalize_review_wave`, and `FlowLedger.authorize_repair`.
+- `convergence-reopen` and `FlowLedger.reopen_convergence`.
+- `record --kind review`, `record --kind convergence`, `FlowLedger.record_subagent_review`, `FlowLedger.record_subagent_review_unavailable`, `FlowLedger.record_agent_review`, and `FlowLedger.record_convergence`.
+
+### Review-only policy and persistence
+
+- `REVIEW_MODEL_LADDER`, `DIRECT_REVIEW_LANE_PROFILES`, `review_model_fallbacks`, `direct_review_profile_resolution`, and `direct_wave_lane_profile_is_authorized`.
+- `default_review_state`, `pending_review_assessment`, `migrated_review_assessment`, `review_mode_for_tier`, `parse_lane_spec`, `review_model_matches_lane`, `review_convergence_started`, `is_current_clear_required_review_wave`, `_review_state`, `_review_wave`, `_validate_lane_specs`, `_requires_current_review_proof`, `_review_tier`, `_require_review_assessment`, `_rederive_current_review_receipt`, and `_revalidate_current_review_set`.
+- `structured_review_prompt`, structured review-result/task-receipt parsing, review artifacts, finding fingerprints, wave synthesis, and current-review revalidation.
+- Active ledger `review`, `review_assessment`, `review_mode`, convergence fields that exist only for review, and their normalizers. `legacy_review` and legacy migration readers remain until an explicit archive-read migration or support-end decision.
+
+### Source anchors
+
+- `REVIEW_MODEL_LADDER`, `DIRECT_REVIEW_LANE_PROFILES`, `def review_model_fallbacks`, `def is_direct_review_model`, `def is_allowed_direct_review_profile`, `def direct_review_profile_resolution`, and `def direct_wave_lane_profile_is_authorized`.
+- `def default_review_state`, `def pending_review_assessment`, `def migrated_review_assessment`, `def review_mode_for_tier`, `def parse_lane_spec`, `def review_model_matches_lane`, `def review_convergence_started`, `def is_current_clear_required_review_wave`, `def _review_state`, `def _review_wave`, `def _validate_lane_specs`, `def _requires_current_review_proof`, `def _review_tier`, `def _require_review_assessment`, `def _rederive_current_review_receipt`, and `def _revalidate_current_review_set`.
+- `review-assess`, `review-wave`, `convergence-reopen`, `def assess_review_necessity`, `def open_review_wave`, `def finalize_review_wave`, `def authorize_repair`, `def reopen_convergence`, and `def record_convergence`.
+- `def structured_review_prompt`, `def parse_review_result`, `def parse_agent_review_result`, `def parse_helper_task_receipt`, `def write_once_review_artifact`, `def review_artifact_path`, `def audit_review_artifacts`, `def remove_regular_review_artifact`, `def review_finding_fingerprint`, `def normalize_review_synthesis`, `def review_synthesis_input`, `def review_is_clear`, `def record_subagent_review`, `def record_subagent_review_unavailable`, and `def record_agent_review`.
+
+### Companion cleanup
+
+- When this subsystem is removed, delete or archive its review-only cases in `bin/test_flow_receipt.py`, `docs/specs/workflow-execution-receipts/replay/review-wave-cases.json`, `bin/review_proof_replay_check.py`, and any replay checker that accepts these commands.
+- In that removal, delete active-spec references to receipt-led review, waves, permits, or `ReviewReceipt`. Keep historical records readable rather than rewriting archived ledger bytes.
+
+## Removal Order
+
+1. Make the retained validation/lifecycle commands independent of review state.
+2. Remove each listed parser/dispatch surface and its complete implementation group.
+3. Remove its tests, replay assets, and active-contract references.
+4. Decide and execute archive-read migration separately, then remove legacy schema readers.
+
+Use this inventory when an intentional removal changes one of these groups.

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/replay/classification-cases.json

@@ -0,0 +1,62 @@
+[
+  {
+    "name": "project-doc-delta-rebinds",
+    "paths": ["docs/guide.md"],
+    "spec_contract_changed": false,
+    "effective_merge_before": "merge",
+    "effective_merge_after": "merge",
+    "reusable": true,
+    "needs_attestation": true,
+    "reasons": ["scoped_non_effective_delta"]
+  },
+  {
+    "name": "spec-state-delta-rebinds",
+    "paths": ["docs/specs/topic/IMPLEMENTATION.md"],
+    "spec_contract_changed": false,
+    "effective_merge_before": "merge",
+    "effective_merge_after": "merge",
+    "reusable": true,
+    "needs_attestation": true,
+    "reasons": ["scoped_non_effective_delta"]
+  },
+  {
+    "name": "spec-contract-invalidates",
+    "paths": ["docs/specs/topic/SPEC.md"],
+    "spec_contract_changed": true,
+    "effective_merge_before": "merge",
+    "effective_merge_after": "merge",
+    "reusable": false,
+    "needs_attestation": false,
+    "reasons": ["spec_contract_changed"]
+  },
+  {
+    "name": "workflow-invalidates",
+    "paths": [".github/workflows/ci.yml"],
+    "spec_contract_changed": false,
+    "effective_merge_before": "merge",
+    "effective_merge_after": "merge",
+    "reusable": false,
+    "needs_attestation": false,
+    "reasons": ["effective_input_changed:.github/workflows/ci.yml"]
+  },
+  {
+    "name": "effective-merge-result-invalidates",
+    "paths": ["docs/guide.md"],
+    "spec_contract_changed": false,
+    "effective_merge_before": "old",
+    "effective_merge_after": "new",
+    "reusable": false,
+    "needs_attestation": false,
+    "reasons": ["effective_merge_result_changed"]
+  },
+  {
+    "name": "arbitrary-product-image-invalidates",
+    "paths": ["assets/product.png"],
+    "spec_contract_changed": false,
+    "effective_merge_before": "merge",
+    "effective_merge_after": "merge",
+    "reusable": false,
+    "needs_attestation": false,
+    "reasons": ["unclassified_effective_input_delta"]
+  }
+]

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/replay/convergence-cases.json

@@ -0,0 +1,22 @@
+[
+  {
+    "name": "third-repair-with-remaining-blockers-is-terminal",
+    "blocking_fingerprints": [["A", "B", "C", "D"], ["A", "B", "C"], ["A", "B"], ["A"]],
+    "states": ["initial", "progress", "progress", "NON_CONVERGENT"]
+  },
+  {
+    "name": "third-repair-may-clear-all-blockers",
+    "blocking_fingerprints": [["A", "B", "C"], ["A", "B"], ["A"], []],
+    "states": ["initial", "progress", "progress", "complete"]
+  },
+  {
+    "name": "initial-clear-review-is-complete",
+    "blocking_fingerprints": [[]],
+    "states": ["complete"]
+  },
+  {
+    "name": "no-progress-diagnoses-once-then-stops",
+    "blocking_fingerprints": [["A", "B"], ["A"], ["A"], ["A"]],
+    "states": ["initial", "progress", "diagnostic_required", "NON_CONVERGENT"]
+  }
+]

package/toolkit/skills/docs/vendor/dot-codex/specs/workflow-execution-receipts/replay/review-wave-cases.json

@@ -0,0 +1,9 @@
+[
+  {
+    "name": "twenty-review-attempts-stop-at-fourth-repair-permit",
+    "review_attempts": 20,
+    "writable_repair_permits": 3,
+    "terminal_attempt": 4,
+    "reopened_budget": 3
+  }
+]

package/toolkit/skills/docs/vendor/dot-codex/specs/xp-infra-public-hostname-convention/HISTORY.md

@@ -0,0 +1,15 @@
+# XP Infra 公网 hostname 规范主题历史
+
+## Lifecycle / Compatibility
+
+- 标准公网节点采用严格成对 hostname；private Docker exception 不在该公网合同内。
+
+## Replacements / Background
+
+- 此规范新增后，任意 legacy API hostname 都作为 drift 报告，而不通过自动兼容 alias 继续保留。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- `../../adr/0002-xp-infra-public-hostname-convention.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/xp-infra-public-hostname-convention/IMPLEMENTATION.md

@@ -0,0 +1,26 @@
+# XP Infra 公网 hostname 规范实现状态
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: policy 与只读审计已验证标准公网节点的两种 hostname。
+
+## Coverage / rollout summary
+
+- `xp-infra` policy 固定公共 Zone。
+- 审计比较节点名、API hostname 与 endpoint hostname。
+- fixture 覆盖 hostname mismatch、private Docker skip（包括无效节点名）、无效节点名和 60 字符边界。
+
+## Remaining Gaps
+
+- 存量节点的 DNS、Tunnel 与 Raft metadata 迁移需要单独授权。
+
+## Related Changes
+
+- None
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/xp-infra-public-hostname-convention/SPEC.md

@@ -0,0 +1,125 @@
+# XP Infra 公网 hostname 规范
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，主题局部演进见 `./HISTORY.md`，决策取舍见关联 ADR。
+
+## 背景 / 问题陈述
+
+公网节点的 API hostname 可能与同一节点的 endpoint hostname 使用不同的节点标识，造成控制面身份漂移。`xp-infra` 需要把标准公网节点的两个 hostname 作为可验证的持久合同，而不是把任意已配置 hostname 视为合规。
+
+## 目标 / 非目标
+
+### Goals
+
+- 为标准公网节点固定两种 hostname 形式。
+- 让只读审计以节点运行时的 `XP_NODE_NAME` 验证 API 与 endpoint hostname。
+- 让冲突和存量 drift 显式失败，而不是生成后缀或自动迁移。
+
+### Non-goals
+
+- 不修改线上节点、DNS、Cloudflare Tunnel 或 Raft 元数据。
+- 不为 owner-approved private Docker exception 强加公网 hostname。
+- 不改变 `xp` 应用的部署实现。
+
+## 范围（Scope）
+
+### In scope
+
+- `xp-infra` policy、runbook、审计脚本和 fixture 的公网 hostname 合同。
+- 标准公网节点 hostname drift 的只读检测。
+
+### Out of scope
+
+- 存量 drift 的实际迁移与别名清理。
+- 私有 Docker exception 的公网入口配置。
+
+## Related ADRs
+
+- [XP Infra 公网 hostname 采用成对严格命名](../../adr/0002-xp-infra-public-hostname-convention.md)
+
+## 需求（Requirements）
+
+### MUST
+
+- 标准公网节点的 API / Cloudflare Tunnel hostname 必须为 `<node>-xp.707979.xyz`。
+- 标准公网节点的 managed endpoint ingress hostname 必须为 `<node>-ep.707979.xyz`。
+- `<node>` 必须等于运行时 `XP_NODE_NAME`，且为未经改写、最多 60 个字符的小写 DNS label。
+- host-managed 审计必须从运行中 `xp` 进程的环境读取三项 hostname 输入，并在收集前后确认该进程 PID 与启动时间未变化。
+- DNS 或 Tunnel ownership 冲突必须交给操作员处理；不得生成后缀或覆写记录。
+- `xp-infra audit` 必须对非私有例外节点比较 `XP_NODE_NAME`、API host 和 access host，并在任一不匹配时失败。
+- owner-approved private Docker exception 必须跳过该公网 hostname 检查。
+- 审计不得自动修复任何 hostname drift。
+
+### SHOULD
+
+- inventory 应将已知公网 hostname drift 标明为待单独授权迁移的运维事实。
+
+### COULD
+
+- 后续可在已授权的迁移任务中加入 DNS/Tunnel inventory 级别的别名清理验证。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+1. `xp-infra policy check` 验证唯一公共 Zone。
+2. `xp-infra audit <alias>` 收集 `XP_NODE_NAME`、`XP_API_BASE_URL` 和 `XP_ACCESS_HOST`。
+3. 标准公网节点只有在两种 hostname 都由相同 `<node>` 推导时通过 `public_hostname_convention` 检查。
+
+### Edge cases / errors
+
+- 无效、非小写或超过 60 个字符的节点名，以及 API 或 access hostname 必须使审计失败。
+- 私有 Docker exception 输出明确的 skip，不能被误报为通过公网合同。
+- 配置冲突、缺失值或存量非 canonical hostname 必须失败并等待操作员处理。
+- host-managed 配置文件与运行中 `xp` 进程环境不一致时，审计必须以运行时环境为准；审计期间进程或三项 hostname 输入漂移必须失败。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口 | 类型 | 范围 | 变更 | 契约文档 | 负责人 | 使用方 | 备注 |
+| - | - | - | - | - | - | - | - |
+| `xp-infra audit` | CLI output | internal | Modify | None | xp-infra | operators | 新增 `public_hostname_convention` 结果 |
+| `public_hostname` policy | YAML | internal | New | None | xp-infra | audit | 固定公共 Zone |
+
+## 验收标准（Acceptance Criteria）
+
+- Given 标准公网节点的 API 与 access hostname 由相同节点名推导，When 运行 audit，Then 输出 `PASS public_hostname_convention`。
+- Given API 或 access hostname 含有额外后缀，When 运行 audit，Then 输出 `FAIL public_hostname_convention` 并返回失败。
+- Given owner-approved private Docker exception，When 运行 audit，Then 仅跳过公网 hostname 检查。
+
+## 验收清单
+
+- [x] 两种 hostname 的长期形式已定义。
+- [x] drift 和私有例外的边界已定义。
+- [x] CLI 与 policy 合同已列出。
+- [x] 验收条件可由 fixture 测试覆盖。
+
+## 非功能性验收 / 质量门槛
+
+### Testing
+
+- `bash skills/xp-infra/tests/test-xp-infra.sh`
+
+### Quality checks
+
+- `skills/xp-infra/scripts/xp-infra policy check`
+- `git diff --check`
+
+## Visual Evidence
+
+None
+
+## Related PRs
+
+- None
+
+## 风险 / 开放问题 / 假设
+
+- 假设：标准公网节点的 `XP_NODE_NAME` 是稳定、受管理的节点身份。
+- 风险：现网 legacy hostname 的实际迁移需要单独授权，不能由 audit 自动执行。
+
+## 参考
+
+- [agent-toolkit `xp-infra` Skill](https://github.com/IvanLi-CN/agent-toolkit/tree/main/skills/xp-infra)
+- [agent-toolkit deployment policy template](https://github.com/IvanLi-CN/agent-toolkit/blob/main/skills/xp-infra/references/deployment-policy.yaml.example)
+- [agent-toolkit `xp-infra` runbook](https://github.com/IvanLi-CN/agent-toolkit/blob/main/skills/xp-infra/references/runbook.md)

package/toolkit/skills/docs/vendor/dot-codex/specs/y9nrr-review-effort-by-pr-stage/HISTORY.md

@@ -0,0 +1,21 @@
+# Review model and effort defaults 演进历史（#y9nrr）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 主人决策：一般与轻量 review 默认使用 `gpt-5.6-luna` + `high`，关联 review 默认使用 `gpt-5.6-sol` + `low`，高要求或疑难 review 在启动前显式标记后使用 `gpt-5.6-sol` + `medium`。
+- 主人决策：默认 review 模型切回 `gpt-5.5`，所有 review 入口默认 `low`，并允许 invocation 启动前一次性自由改档。
+- 先前决策：所有 review 入口固定使用 `gpt-5.6-terra`，所有 profile 默认 `medium`，并允许 invocation 启动前一次性自由改档。
+- `54a9c9b` docs(workflow): align review effort defaults by pr stage
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#y9nrr`.