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

package/toolkit/skills/project-engineering-workflow/references/active-long-task-short-contract.md

@@ -0,0 +1,53 @@
+# Shared Active Long Task Contract
+
+Use this contract for `AGENTS.md`, `$flow-continue`, shared workflow, native review tasks, and replay checkers that govern long-running tasks. Callers should reference it instead of restating the same ownership / stop / polling rules.
+
+## 1. Active Long Task Definition
+
+- An `active long task` is any still-running exec session, browser automation run, test/build job, remote job, tracker, advisory review, or equivalent live operation whose next meaningful step is to keep polling / relaying / waiting / same-path retrying.
+- Dedicated contracts may add stricter semantics for specific subclasses:
+  - Code-hosting-visible `外部门禁等待态` keeps its own shared wait budget and cadence.
+  - a Tracker Agent or advisory reviewer may keep its own runtime handle and terminal-state rules.
+- These dedicated contracts do not weaken the generic ownership guard in this file.
+- CI, release, deployment, PR-status, and recovery tracking MUST NOT create, update, or reuse heartbeat, cron, or app automation. Wait on the dedicated tracker's runtime handle in the current chat; if it is unavailable, retain its identity/history anchor for owner-issued `$flow-continue`. Resource-lease renewal and explicitly authorized non-tracking handoffs retain their separate contracts.
+
+## 2. Ownership Promise
+
+- An `ownership promise` exists once the assistant says it will keep watching or continue the same live task, for example:
+  - `我继续盯着`
+  - `正在跑`
+  - `我等它收口`
+  - `我继续 relay/poll`
+  - `我不切走`
+- Equivalent wording counts even if phrased differently. The key meaning is: the assistant has accepted responsibility for continuing the same live task without needing new owner input.
+
+## 3. Stop Prohibition
+
+- If an active long task exists, and the only next step is still to poll / relay / wait / same-path retry that same task, the assistant must keep going in the same turn.
+- It is not a valid stop point to say “still running”, “I’ll keep watching”, or any equivalent status-only summary while the same live task remains the only next action.
+- The owner must not be forced to send no-op nudges such as `继续 / 盯着 / 别停 / 你自己处理` just to resume a task the assistant already promised to continue.
+
+## 4. Legal Stop Reasons
+
+- A non-terminal stop is allowed only when at least one of the following is true:
+  - the task reached a terminal result (`completed`, `hard_dead`, explicit failure, timeout, or equivalent);
+  - new blocker evidence changed the next action from pure waiting/polling to diagnosis or repair;
+  - the next action requires fresh owner decision, authorization, or scope confirmation;
+  - the applicable contract's wait budget is truly exhausted;
+  - the current flow already reached its explicit user-approved stop condition.
+- When stopping because wait budget is exhausted, the conclusion must explicitly say `等待预算耗尽`.
+- For a live Tracker Agent, `等待预算耗尽` never becomes success; report its incomplete/unavailable terminal state and recovery anchor.
+
+## 5. Polling Cadence Defaults
+
+- Short 1-3 second polling is only for the first few observation cycles right after launch or right after a state-changing action.
+- Once a local exec/browser/test/build task becomes a stable long task, callers should stretch cadence (for example `5s -> 10s -> 15s`) instead of indefinite `1s` busy polling.
+- Dedicated contracts override cadence where they already define stricter budgets or polling intervals.
+- Local commands have a default 1800-second hard budget. Only a repository-declared known-long command may override it.
+- Identical effective inputs permit one transient retry only after observable state change. Output truncation, missing scrollback, or context compaction is not such a change.
+- Nested skills inherit elapsed time and retry counters from the outer flow; they must not reset either budget.
+
+## 6. Generic Continuation And Resume
+
+- If a previous turn leaked an ownership promise anyway, the next generic continuation must resume the same live task first.
+- Generic `继续 / 盯着 / 你自己处理` does not authorize a new route, a new launch, or a no-op pause; it only resumes the leaked task unless fresher direct evidence overrides it.

package/toolkit/skills/project-engineering-workflow/references/advisory-review-short-contract.md

@@ -0,0 +1,19 @@
+# Advisory Review Contract
+
+Use this contract for optional independent review during a delivery flow. An advisory review improves the candidate; it is not a merge gate and does not decide whether the candidate is merge-ready. It cannot replace the mandatory `review-proof-short-contract.md` evidence when a Tier 3/4 direct delivery flow requires it.
+
+## Applicability
+
+- An advisory reviewer starts only when explicitly requested by the owner or main Agent, and only after all formal lanes reach terminal state.
+- It never occupies a formal review slot while a required lane is live or pending. The caller supplies an explicit supported model and effort; its profile is a quality/cost recommendation, not task identity or delivery proof.
+
+## Runtime boundary
+
+- The reviewer may be launched through direct Agent calls or Programmatic Tool Calling (PTC). The runtime owns child identity and waiting; callers must not reconstruct either from transcript files.
+- A reviewer is read-only and returns findings with concrete file/behavior evidence. The main Agent applies the canonical disposition and the shared priority-aware `repair_resolution`: an `In-Scope Review Finding` joins the normal Repair Batch only when the current Formal Review Wave and CI state satisfy that threshold, a `Design-Returning Review Finding` stops ordinary convergence, and a `Review Observation` remains report-only. Advisory output alone never creates a Repair Batch or turns a later-wave P2 into an authorized repair.
+- Missing, failed, or malformed reviewer output is reported as advisory review unavailable. That advisory result remains non-blocking, but it must not be misreported as successful required Tier 3/4 evidence.
+
+## Delivery boundary
+
+- No ledger receipt, review wave, repair permit, profile attestation, or transcript digest is required for advisory review.
+- Step 5C uses the current PR head, required checks, validation receipts, and other applicable external facts. Advisory findings are context for the main Agent, not a substitute for those facts.

package/toolkit/skills/project-engineering-workflow/references/ci-tracking-short-contract.md

@@ -0,0 +1,73 @@
+# Shared CI Tracking Contract
+
+本合同是 shared Step 5 / Step 6、`$fast-flow`、`$flow-continue` 以及 PR publication/merge procedure 的唯一 CI 判定来源。入口 Skill 只提供阶段、仓库、分支和 SHA，不复制下面的状态矩阵。
+
+## 1. 输入与事实边界
+
+- 输入是 `phase + repo + branch + bound_sha`：`pr_head_ci` 绑定当前 `PR.head.sha`，`post_merge_target_ci` 绑定 `merge_sha` 与目标仓库/分支。
+- 一个 tracker 只观察一个阶段和一个绑定 SHA 的适用 CI。只计入由该 SHA 触发的自动 `push` / PR 相关检查；`schedule`、`workflow_dispatch`、release、 publish、deploy、deployment 以及无关分支或 SHA 的运行一律排除。
+- PR freshness/conflict 优先级使用 `pr-diagnosis-short-contract.md`：先确认 live PR 的状态、base/head 和 mergeability，再解释 CI 缺席。
+- 适用 CI、required check 和 provider 策略是三类不同事实。workflow 文件存在、手动运行成功或 `gh pr checks` 显示 `no checks reported`，单独都不能证明 required check 存在或不存在。
+
+## 2. 四字段状态模型
+
+CI facts adapter 必须同时返回以下字段；它们不能互相替代：
+
+| 字段 | 允许值 | 含义 |
+| - | - | - |
+| `policy_state` | `required` / `none` / `unknown` / `unavailable` | provider 是否读取到可用的 required-check 策略 |
+| `checks_expected` | `yes` / `no` / `unknown` | 是否有权威事实表明当前阶段期待 required checks |
+| `ci_evidence` | `passed` / `failed` / `pending` / `absent` / `unavailable` / `not_applicable` | 绑定 SHA 的适用 CI 证据现状 |
+| `gate_effect` | `blocking` / `non_blocking` / `not_applicable` | 当前 CI facts 对 PR reducer 的门禁效果，不是 provider 错误等级 |
+
+判定规则：
+
+- `policy_state=required` 只在 provider 明确返回非空 required contexts 时成立；各 required context 全部有成功的 exact-SHA status/check/run 证据时为 `ci_evidence=passed`，否则按失败、运行中、缺席或不可用分别分类。
+- `policy_state=none` 只在 provider 明确返回没有 required contexts、确认无保护策略，或通过同一分支的 `protected=false` fallback 时成立。此时无自动 CI 证据是 `ci_evidence=not_applicable`、`gate_effect=non_blocking`，可由 tracker 映射为 `CI_NOT_EXPECTED`。
+- `policy_state=unknown|unavailable` 时，`checks_expected` 必须是 `unknown`， `ci_evidence` 必须是 `unavailable`，`gate_effect` 必须是 `not_applicable`。这只是 provider observation evidence，不能被 adapter 单独映射成 `CI_NOT_EXPECTED`、required-check 失败或项目 blocker；是否阻塞由 live PR mergeability、可见 required contexts 和其他门禁共同决定。
+- 因此，Step 5C / merge procedure 不把 typed policy observation 单独当成 blocker；只有 live PR 的 freshness/conflict、可见 required contexts、缺席的已确认 gate 或其他独立门禁事实形成阻塞时，才返回相应 blocker。若这些事实没有形成阻塞，保留 observation error 并继续当前流程，但不能把 `unknown|unavailable` 改写成 `CI_NOT_EXPECTED`。
+- `gate_effect=blocking` 只表示已经确认存在 required gate 且当前证据未通过、仍在运行、缺席或无法观察。`gate_effect=not_applicable` 表示 adapter 没有足够事实决定门禁效果，不表示“没有门禁”。
+
+## 3. 策略来源与错误语义
+
+- GitHub required-check protection `200` 是可读策略；`contexts` 必须是字符串数组。非空数组为 `required`，空数组为 `none`；`404` 是确认无该 protection policy。
+- GitHub 私有仓库 plan-limit 的精确 `403` 只有在同一分支 metadata 返回请求分支名且 `protected=false` 时，才允许确认 `none`。fallback 失败、分支名不符或仍受保护时为 `unknown`，不得降级成 `checks_expected=no`。
+- 其他 `401/403/429`、`5xx`、`invalid_endpoint`、command/provider failure 或超时为 `unavailable`；`200` malformed policy、未知 HTTP 状态或结构不完整为 `unknown`。
+- policy 读取错误必须保留 typed `policy_observation.error`，并继续读取可独立读取的 commit status、check runs 和 workflow runs。错误不得掩盖已经获得的 exact-SHA 事实，也不得为了“补齐证据”触发 `workflow_dispatch` 或创建 replacement run。
+- status/check response 缺少或格式错误的 SHA、行结构或语义字段时，必须保留 typed `ci_surface_unavailable`；声明了合法但错误 SHA 时必须拒绝该证据。workflow run 只保留绑定 SHA，并排除手动、schedule、release、publish、deploy/deployment 事件。workflow run 缺失或不认识的 event 也必须排除；不能把未知 event 猜成 `push`。status/check surface 通常没有 workflow event provenance，因此只能凭 exact SHA 和 required context 参与判断，不能反向证明某个 workflow run 的触发事件。
+- 同一 required context 有多条 exact-SHA 观测时，若两条都有 timestamp，优先使用较新的 provider timestamp；若部分观测缺少 timestamp 且双方都有 `run_attempt`/attempt，优先使用较高 attempt，再使用 run id。旧失败不能覆盖更新的成功 rerun；无法比较新旧时按 `failed > pending > passed` 保守处理。rerun verify 与 mutation 必须通过 `include=true` 保留 provider HTTP status，并且只有真实 `2xx` 才能报告 `rerun_requested`。
+
+## 4. Tracker 生命周期与公共结果
+
+- `agent_type = "ci-tracker"`
+- 每个 bound SHA 使用一个只读 `ci-tracker`，profile 为 `gpt-6-luna + low`；tracker 直接读取和轮询 provider，不创建 automation，不启动第二个 tracker，不写代码、不创建 PR、不改 labels/state、不写入已合并主干。
+- tracker 从启动起拥有 `600 seconds`（10 分钟）bounded wait/polling budget，只轮询同一 SHA。head 变化会使旧 tracker stale，必须以新 SHA 建立新的 tracker。
+- tracker 终态保持 `passed|failed|incomplete|unavailable`，与任务状态分离。PR 侧公共结果枚举保持不变：`CI_GREEN | CI_NOT_EXPECTED | NEED_CODE_FIX | INFRA_BLOCKED`。
+- 终态映射必须经过 live PR reducer：
+  - `required + passed` -> `CI_GREEN`；
+  - 已证实 `none + not_applicable` -> `CI_NOT_EXPECTED`；
+  - `required + failed` -> `NEED_CODE_FIX`；
+  - 期待证据仍缺席、tracker 不可用或策略/证据无法在当前 live 门禁中完成分类 -> `INFRA_BLOCKED`，并附恢复锚点；但 policy observation error 本身不能单独制造这个结果。
+- `workflow_dispatch`、replacement run、手动 Actions 成功结果和历史 assistant transcript 都不是缺失证据的恢复手段。只有已有 run 被 live facts 证明是同一 SHA 的瞬态基础设施故障时，才允许对该已有 run 做一次 rerun。
+- rerun 的一次性预算由 bound tracker 持有；adapter 在同一进程内为同一 `provider/repository/run_id/SHA` 共享一个 claim。mutation 进行中到达的调用必须等待同一 in-flight promise；mutation 已发出后的后续调用必须拒绝再次尝试。确定的 `command_unavailable`、endpoint validation 等 pre-send failure 不消耗 allowance，timeout 或结果不明则保守保留 claim。独立 tracker 不得绕过这个预算创建第二次请求。
+- rerun 验证请求与 mutation 请求均只有严格 `2xx` 才算成功；`3xx`、`4xx`、`5xx`、 timeout 和 unsupported response 必须保留 typed failure/unsupported observation。
+
+## 5. Live reducer 顺序
+
+这里的 live PR reducer 是 shared workflow 的判定边界，不是 provider CI facts adapter 的第二套 tracker。adapter 只返回四字段 envelope 和 typed observations；入口 Skill、publication procedure 和 merge procedure 只能引用本合同完成公共结果映射。
+
+1. 刷新 live PR 的 `state/merged/draft/mergeable/merge_state/base_sha/head_sha`。
+2. `DIRTY` / `CONFLICTING` 先进入 freshness/conflict path；冲突导致的 workflow 缺席不能被改写成 `CI_NOT_EXPECTED`。
+3. 在干净且 head/base 仍绑定时，读取本合同的 CI facts，区分策略状态、证据状态和门禁效果。
+4. 只有 live PR surfaces 明确显示 required contexts 或权威无门禁事实时，才把 CI 结果映射为 `CI_GREEN` / `CI_NOT_EXPECTED`；provider API 错误不替代 PR reducer。
+5. 合并前只消费绑定 Candidate/PR head 的 `pre_merge` 证据；合并后必须绑定真实 Merge Receipt 的 `merge_sha`。
+
+## 6. 恢复卡
+
+tracker 必须返回 `phase`、`bound_sha`、`terminal_state`、`tracking_target`、 `external_locator`、`rerun_count=<0|1>`、匹配的 runs/checks、四字段 CI facts 与 `evidence`。等待预算耗尽、provider 不可用、策略不可读或证据缺席时，恢复卡必须说明：
+
+- 哪个事实已确认，哪个事实仍是 `unknown|unavailable`；
+- 是否存在 live required gate；
+- 下一步是刷新 live PR、处理 freshness/conflict、继续等待同一 SHA，还是由主人处理 provider 权限/策略问题。
+
+不能用“没有 checks”直接替代这些区分，也不能用普通等待或手动 dispatch 掩盖 unavailable。

package/toolkit/skills/project-engineering-workflow/references/empirical-acceptance-short-contract.md

@@ -0,0 +1,48 @@
+# Empirical Acceptance Short Contract
+
+Use this contract whenever the current direct plan declares `empirical_acceptance=required`. It supplements, and never replaces, ordinary validation, CI, visual evidence, or direct review proof.
+
+## Evidence card
+
+The main Agent keeps one current Candidate card under the shared workflow's evidence-placement rule. The legacy single-card shape remains readable, but it is always mapped to `pre_merge`; it can never satisfy a post-merge or post-deploy obligation. New phase-aware records retain the same digests and locator and add `acceptance_id`, `phase`, and the identity required by that phase.
+
+```text
+empirical_acceptance=required|not_required
+empirical_acceptance_rationale=<non-empty proofability rationale>
+empirical_evidence_status=passed|failed|unavailable|not_required
+empirical_candidate_sha=<current Candidate SHA>|none
+acceptance_contract_digest=<accepted behavior/acceptance digest>|none
+scenario_set_digest=<required observable scenario-set digest>|none
+evidence_locator=<inspectable run/log/artifact locator>|none
+```
+
+Phase-aware evidence uses this identity contract:
+
+```text
+acceptance_id=<manifest acceptance ID>
+phase=pre_merge|post_merge|post_deploy
+candidate_sha=<Candidate SHA>                     # pre_merge only
+merge_sha=<actual Merge Receipt SHA>               # post_merge/post_deploy
+deployment_identity=<structured deployment identity object> # post_deploy only
+```
+
+`deployment_identity` is not a free-form label. It is a structured deployment identity containing `deployment_id`, `source_sha`, `bound_sha`, `relationship`, `provenance_boundary`, `evidence_source`, `operation_id`, `observed_state`, and `external_locator`. The receipt must use `relationship=deployed-from`, `provenance_boundary=deployment-provider`, `evidence_source=deployment-receipt`, and `observed_state=verified`. Both SHA fields must equal the actual Merge Receipt `merge_sha`. Both SHA fields must equal the actual Merge Receipt `merge_sha`. The structured identity is checked for its required deployment fields and lineage; an absent or mismatched identity cannot produce post-deploy evidence.
+
+`not_required` uses `empirical_evidence_status=not_required` and `none` for the remaining evidence identity fields. `required` uses a non-empty value for every remaining field and requires `empirical_candidate_sha` to equal the current Candidate for `pre_merge`. Post-merge evidence is admitted only after a real Merge Receipt exists and its `merge_sha` matches. Post-deploy evidence additionally requires the structured deployment identity above, bound to that same merge SHA. These later records do not block Review Readiness or the pre-merge Step 5C gate; they remain pending until their lifecycle phase. PR-bound Flow Complete still requires the canonical acceptance manifest to exist; an absent manifest is an owner-action blocker and is not equivalent to having no post-merge obligations.
+
+## Admission
+
+- `passed` is valid only when the Candidate SHA, acceptance-contract digest, scenario-set digest, and evidence locator are current and inspectable.
+- A Candidate SHA, accepted behavior/acceptance contract, or required scenario set change makes the prior card stale. A stale card is blocked, not reused.
+- `unavailable` blocks the gate but is not an empirical regression. It records an inability to observe the required evidence, not a guessed product cause.
+- A missing, malformed, or mismatched `pre_merge` card blocks Review Readiness, Step 5C, and Step 5L. A missing post-merge or post-deploy record blocks only its applicable post-merge closeout and remains an explicit owner-action blocker. It does not create a Repair Batch.
+
+## Review and regression disposition
+
+- A proposed repair that changes external-response assumptions, timing, timeout, retry, permission/state transition, or acceptance semantics is `Design-Returning` unless the settled contract already specifies the exact correction and current evidence demonstrates a violation.
+- A `failed` card for a Candidate after a comparable Candidate passed the same contract is an `Empirical Regression`. The flow records both Candidate SHAs, compares their relevant Git delta once, and enters diagnosis-only handling.
+- Diagnosis-only handling does not launch a new ordinary Repair Batch, formal review wave, or acceptance relaxation. It also does not attribute the failure to a reviewer or repair without evidence.
+
+## Continuation anchor
+
+An anchor for an applicable obligation carries the complete phase-aware card fields plus `repair_batches_used`. Generic continuation must match the current Candidate for `pre_merge`, and the recorded `merge_sha` and structured `deployment_identity` for later phases, before it may wait, relay, or continue. Missing or mismatched fields block recovery; they never infer `not_required`, turn `merge-ready` into Flow Complete, or reset the repair count.

package/toolkit/skills/project-engineering-workflow/references/execution-receipt-short-contract.md

@@ -0,0 +1,31 @@
+# Shared Execution Receipt Contract
+
+`${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/bin/flow_receipt.ts --repo <candidate>` maintains non-tracked validation and lifecycle facts below `git rev-parse --git-path codex-flow`. Always pass `--repo <candidate>`; do not copy the helper into the candidate. Code-hosting PRs, required CI, repository validation, release artifacts, and direct review evidence remain authoritative for delivery. Review execution and review gates never depend on this ledger.
+
+## Identity and reuse
+
+- A validation proof key binds the exact command, toolchain fingerprint, declared input scope, normalized paths, acceptance evidence, and clean repository HEAD. A receipt records the run id, flow type, base/head SHAs, exit code, log path/digest, and evidence appropriate to that validation.
+- Exact effective-input matches reuse a passed validation receipt without rerunning. Docs-only deltas may use a scoped attestation after the helper verifies the actual Git delta and current base.
+- Code, tests, build inputs, workflow files, canonical Spec contracts, or an effective merge result invalidate affected receipts. Required CI and owner approval always bind the current SHA and are never rebound by a local receipt.
+- Historical review fields are audit data only. They do not affect current review evidence or direct delivery eligibility. `bind-pr`, post-merge recording, and `close` do not require a review assessment, review wave, or convergence state.
+- `bind-pr --pr-ref` may link a live PR to an audit run. Direct PR convergence refreshes normalized base/head facts and OPEN state with the selected platform adapter; it does not require this audit metadata. These lifecycle reads pass the adapter's lightweight related-facts option; complete review/comment collections remain available to callers that explicitly need review-policy facts.
+
+## Budgets and lifecycle
+
+- Validation `record` runs the command itself and enforces the 1800-second hard budget unless an exact tracked known-long command grants a longer budget.
+- Use the ledger only for validation audit, scoped attestations, and lifecycle notes. Do not start review waves, record review receipts, consume repair permits, or use `close` to decide a Tier 3/4 review outcome.
+- A successful clean pre-PR validation may advance the candidate `head_sha`. Failed, dirty, preflight, or PR-bound attempts may not. `close` accepts an explicit terminal state, archives the ledger atomically, and does not rebuild or verify an Agent transcript.
+- Command logs stay below the ledger's dedicated execution directory. Ledger writes use a shared lock, temporary file, and atomic replacement; archived run ids are immutable.
+
+## CLI
+
+- `init`: create or resume a validation-audit ledger with an acceptance manifest and existing PR binding.
+- `bind-pr --pr-ref`: bind a created/reused live PR to the current ledger.
+- `record --kind validation`: execute and record a validation fact.
+- `record --kind attestation`: add a scoped docs-only delta attestation.
+- `record --kind post-merge --post-merge-evidence-file`: record the live MERGED PR identity plus terminal target-CI and release facts. The evidence binds the live PR's original base/head and actual merge SHA; a stale local binding is recovered from those live facts without consulting a historical review assessment. Identical merge identities are reusable, while conflicting evidence is immutable. For `release.status=not-applicable`, provide `release_expected=false` and `policy_evidence` with `repository` (`provider`, `host`, `full_name`), `target_branch`, `merge_sha`, `policy_locator`, and `reason`. The helper compares the identity with the live merged PR and checks structural consistency; callers remain responsible for verifying the policy itself. Historical evidence remains readable but cannot seal a new completion without these fields.
+- `classify`: classify a path/effective-merge delta as reusable or invalidating.
+- `status`: report validation state and any `legacy_review_history` for audit.
+- `close`: archive the audit ledger after its own validation lifecycle; it is not a direct-review or merge gate.
+
+Lifecycle CLI failures preserve the compatibility `error` field and exit code. When an explicit cause chain contains a typed provider adapter failure, the same JSON error object also exposes its safe `error_code` and `operation`; raw provider output, stderr, and credentials are never emitted.

package/toolkit/skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md

@@ -0,0 +1,93 @@
+# Shared PR Diagnosis Short Contract
+
+Use this contract for shared Step 5, `$flow-continue`, and the workflow PR publication/merge procedures. Callers should reference it instead of restating the same PR heuristics. Generic active-long-task ownership, legal stop reasons, and default polling cadence follow `references/active-long-task-short-contract.md`; this file keeps only PR-specific promise-resume and external-wait heuristics.
+
+## 1. Platform Live Truth Source
+
+- Before saying why a PR currently cannot merge, refresh the live PR fact set through `skills/bin/code_hosting.ts`. Minimum surfaces:
+  - provider-normalized PR state, closed/merged status, draft, mergeability, head SHA, base SHA, and target/source refs
+  - provider-normalized commit status, check/workflow runs, and review-policy contexts bound to the current SHA
+  - add reviews / review comments / review threads only when the live status surfaces still leave review policy as a real candidate blocker
+- The current blocker must be inferred from that live platform fact set, not from prior assistant prose, old status summaries, or carried flow text.
+- Historical assistant text may still resume a promised next branch or stop condition, but it is never blocker evidence.
+- If live platform facts conflict with historical prose, trust the live facts.
+- `merge-ready` / `Step 5C Ready` / `latest PR 可立即合并` are live-PR state words, not local Step 4 words. Callers may use them only after current facts already prove `PR状态=存在`; before that, the correct wording is `PR状态=不存在` or `可开 PR（local）`.
+
+## 2. Live Reducer Priority
+
+- `state == MERGED` or `mergedAt != null` means the PR is already merged; do not diagnose a current merge blocker.
+- `closed == true && mergedAt == null` means the PR is closed without merge; do not invent a still-running merge blocker.
+- `isDraft == true` means draft gate comes before checks/review/proof.
+- `mergeable == CONFLICTING` or `merge_state == DIRTY` means the PR is at the conflict gate. Ordinary checks/review/spec gates pause until conflict handling finishes.
+- `merge_state == BEHIND` records target drift; apply §3 at the review-round boundary rather than restarting live work.
+- For an open PR, `mergeable == UNKNOWN` or `merge_state == UNKNOWN` is not, by itself, proof of review/check failure. Refresh and continue using current live status surfaces instead of backfilling a blocker from history.
+- `merge_state == BLOCKED` is only a top-level gate shape; keep reducing it through current live checks/review/rules facts instead of reporting raw `BLOCKED` as the final reason.
+- Reduce `BLOCKED` using current live surfaces in this order:
+  1. running/failed required checks or workflows
+  2. explicit negative review-policy evidence
+  3. directly visible unresolved review-thread / conversation blockers
+  4. required deployment / merge queue / repository ruleset blockers
+  5. only if none of the above are visible, report `platform live blocked; exact gate not yet surfaced` and ask for another live refresh rather than guessing `approval` or replaying assistant history
+
+## 3. Round Boundary And Integration
+
+- Before a new or restarted round of CI tracking or formal review, refresh live PR base/head and bind its candidate once. Handle `DIRTY` or `CONFLICTING` first. Required-CI suppression or demonstrated invalidation of an interface, dependency, or validation assumption requires prompt diagnosis; candidate writes still wait for owned review/CI tasks to terminate.
+- Ordinary target advancement or `BEHIND` alone does not cancel, rebind, or restart a running round. Record the latest target and finish the bound review and CI, including remaining lane launches. At the round boundary, inspect accumulated target changes once and combine necessary alignment with the next candidate update. Before another round, resolve required freshness, actual conflicts, or demonstrated integration incompatibility; divergence alone does not mandate rebase.
+- Align within existing flow authorization. When alignment is necessary, an explicitly fixed target or missing rewrite authorization is an immediate blocker; a recorded starting SHA alone does not fix the delivery target. Repeated target movement uses the existing wait budget and repository integration mechanism; budget exhaustion reports a blocker rather than an unlimited rebase/review loop.
+- Old checks, proof, and spec verdicts keep their original base/head identity. An actual candidate head or review-base change requires rebinding and applicable fresh evidence, never relabeling old results. A live head change invalidates the round; diagnose it and settle owned tasks before launching replacements. PR-body writes require the publication envelope's current identity; Step 5C and merge retain their final live-fact, evidence, freshness, and repository-rule gates. `BLOCKED` without conflict facts follows §2.
+
+## 4. Conflict-Suppressed CI
+
+- CI absence, tracker ownership, four-field facts, and rerun boundaries follow `ci-tracking-short-contract.md`; this section only adds PR freshness/conflict precedence.
+- Before classifying CI absence, retain the adapter's `policy_state` / `checks_expected` / `ci_evidence` / `gate_effect` values as separate facts. `policy_state=unknown|unavailable` is a typed provider observation, not evidence for either `CI_NOT_EXPECTED` or a required-check failure.
+- For pull-request workflows, conflict alone may suppress runs. If the refresh shows `merge_state == DIRTY` or `mergeable == CONFLICTING`, classify the situation as `conflict-suppressed CI`.
+- `conflict-suppressed CI` is never ordinary `外部门禁等待态`. Route straight back to freshness/conflict handling. In auto-convergence / merge-authorized runs, that means conflict auto-heal rather than a new owner question.
+
+## 5. Approval Evidence Priority
+
+- Before approval can affect routing, read the current status / Review Policy Gate surface when available.
+- Explicit positive review-policy evidence wins:
+  - `approval not required`
+  - `approval satisfied`
+- Empty reviews, missing review comments, or “no human review yet” are weak signals only. They must not override explicit positive evidence.
+- If the live status surfaces already say review policy is clear, an empty reviews list must not become the reported blocker just because historical assistant text mentioned approval.
+- Do not read empty reviews as the default explanation for `merge_state == BLOCKED`; review only becomes the blocker when current live surfaces expose direct negative review-policy evidence or unresolved review blockers.
+- Only report approval as a blocker when there is direct negative evidence, or when no stronger evidence exists and repository policy still clearly requires approval.
+
+## 6. Promise-Resume And Wait-State
+
+- If the previous assistant reply already offered explicit next actions, and the user then says generic `继续 / 推进流程 / 你直接做吧`, resume the highest-priority unfinished promised branch unless new direct evidence overrides it.
+- Shared wait budget covers platform-visible running gates such as checks/workflows, mergeability recompute, and branch-update visibility.
+- In authorized PR convergence, pure external wait is not a valid stop point until the shared wait budget is exhausted.
+- If wait budget is exhausted, the conclusion must say `等待预算耗尽`, and `流程锚点.下一门禁` must point back to `继续轮询当前外部门禁等待态`, not to the completion of the currently running gate.
+
+## 7. Intent-Sensitive Stop Condition
+
+- Stop-condition words and live-state words are separate contracts:
+  - `merge-ready` can be the intended PR-stage stop condition in a plan or route decision;
+  - but a current-state claim such as `merge-ready` / `Step 5C Ready` / `latest PR 可立即合并` still requires live `PR状态=存在`.
+- `merge-ready`: `准备好 PR / 预备合并 / 准备好合并 / 完成合并前准备`; may stop at `Step 5C Ready`.
+- `merge-only`: `合并 / 合并 PR / merge PR / merge / 只合并 / 不收尾 / merge only / no cleanup`; must continue into the workflow PR merge procedure, delete the remote PR head branch, then stop without local cleanup.
+- `merge+cleanup`: `合并并收尾 / 推进到合并并收尾 / merge and cleanup`; must merge, then cleanup. Cleanup includes deleting PR worktrees when safe.
+- Generic `继续 / 收尾` inherits the current stop condition; latest explicit plain `合并` resolves to `merge-only`.
+- Once the current stop condition is `merge-only` or `merge+cleanup` and the run has entered the shared Step 5 merge path, same-PR in-scope writable convergence is authorized by default:
+  - included: reviewer-feedback repair, CI/blocker repair, freshness `merge_state=BEHIND`, conflict `merge_state=DIRTY` / `mergeable=CONFLICTING`, missing required Tier 3/4 review proof, and compatibility repairs directly forced by those live facts;
+  - excluded: scope expansion, `same-PR reopen`, permissions/risk blockers, and `convergence drag blocker`;
+  - `merge-ready` does not carry this writable-convergence default by itself.
+
+## 8. Advisory Review Boundary
+
+- Advisory review is launched only when explicitly requested, and only after all required formal lanes reach terminal state; it may not consume a slot while a formal lane is live or pending. This is supplemental: Tier 3/4 readiness still requires the direct structured evidence in `references/review-proof-short-contract.md`.
+- A reviewer task is an execution aid, not a PR fact. Its presence, completion, transcript shape, and findings do not create or clear a Tier 3/4 proof gate. The PR diagnosis reducer uses live PR, CI, validation, rules, release, the recorded review tier, and current-head review evidence when required.
+
+## 9. Convergence Stop-Loss
+
+- Apply the diagnosis and disposition in `review-proof-short-contract.md`; carried `PR收敛修复轮次` is the same cumulative `repair_batches_used`. Batch count alone does not block authorized in-scope repair. Design-returning findings follow the review contract.
+
+## 10. Output Coherence
+
+- If current facts do not yet prove `PR状态=存在`, conclusions must not say `merge-ready`, `Step 5C Ready`, or `latest PR 可立即合并`; use `PR状态=不存在` or `可开 PR（local）` instead.
+- If current facts are `merge_state == DIRTY` or `mergeable == CONFLICTING`, `流程锚点.下一门禁` must point to conflict/freshness handling, never to “wait for checks/proof/mergeability to finish”.
+- If current facts remain `merge_state == BLOCKED`, and the current live checks / review-policy / review-thread / deployment-or-rules surfaces still do not expose the concrete blocker, the conclusion must say `代码托管平台当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出`, and `流程锚点.下一门禁` must point to `继续刷新当前 PR 的 live checks/review/rules surfaces` (or an equivalent live-refresh wording).
+- In that exact `blocked-but-unsurfaced` case, do not rewrite the conclusion as `缺 approval`, `缺 review`, `等 checks`, or any other guessed gate.
+- If stop reason is `convergence drag blocker`, the conclusion must say so explicitly and recommend a `follow-up PR` by default.

package/toolkit/skills/project-engineering-workflow/references/pr-merge-procedure.md

@@ -0,0 +1,67 @@
+# PR Merge Procedure
+
+This procedure is the mechanical merge layer for workflow Step 6 and for eligible direct or coordinator-owned role envelopes. Historical role envelopes retain their own compatibility topology; the caller owns authorization, role-specific frontier checks, review/validation gates, release applicability, and the terminal flow decision.
+
+## Operation Envelope
+
+The caller supplies:
+
+- `mode=merge|post-merge`;
+- `PR_ROLE`, exact repository and PR number, expected base/head SHAs, candidate worktree and local ref;
+- the explicit owner or frozen-role merge authorization for the current PR;
+- the approved `merge_method=merge|squash|rebase` and `merge-only|merge+cleanup` stop condition;
+- the current Step 5C release decision card and explicit owner confirmation including the version expectation. A single clear natural-language owner message may combine this confirmation with the request to continue; the caller must not require a response template or a second action turn;
+- current live head/base, required checks, validation, review proof, visual evidence, and role-specific facts when the caller uses a historical role envelope.
+
+The procedure returns the preflight receipt, locked head, terminal PR state, merge SHA, remote-head disposition, base-alignment result, Phase B image result, and post-merge facts needed by the caller.
+
+## Preconditions
+
+For `mode=merge`, require an open PR whose role/base/head match the envelope, whose live base/head OIDs equal `expected_base_sha`/`expected_head_sha`, a clean candidate whose local OID exactly matches the live head, a current CI result classified by `ci-tracking-short-contract.md` (`CI_GREEN`, an authoritative `CI_NOT_EXPECTED`, or a live reducer receipt that keeps policy observation explicitly unresolved without treating that observation alone as a blocker), with provider observation errors kept explicit, complete applicable validation and review proof, and a non-conflicting, non-dirty, non-behind, non-blocked mergeability result. `merge-ready` or `Step 5C Ready` never grants merge authorization. The decision card is not a release receipt; missing or conflicting live required facts or other gates block merge continuation, while a typed policy observation alone does not. For `mode=post-merge`, require the same role/base/head identity on an already merged PR, the recorded pre-merge base/head OIDs equal to `expected_base_sha`/`expected_head_sha`, the exact recorded `merge_sha`, and the caller's post-merge recovery facts. The target base ref may have advanced to the merge commit or later commits; refresh that current ref for alignment instead of comparing it to the pre-merge base. The local candidate may be absent when the caller is only converging remote post-merge facts. If the caller's formal review proof reports a `Design-Returning Review Finding`, stop and return that blocker; do not merge or relaunch review until the caller resolves the design and binds fresh evidence to the changed candidate.
+
+## Merge operation
+
+For `mode=merge`:
+
+1. Reconfirm repository policy and the selected merge method.
+2. Run `skills/project-engineering-workflow/scripts/merge_preflight.ts` before final live checks and again after any same-PR in-scope fix. Require `outcome=eligible` and use only its `merge_guard.locked_head` as the command head. Stale input, candidate drift, dirty worktrees, closed PRs, or an unsupported guard stop the path.
+3. Validate the approved merge method against the explicit allowlist and execute exactly one guarded direct merge. Bind the command to the envelope's exact repository with `--repo "$REPO"`; a PR number without this binding is not sufficient. Do not accept a repository default or an interactive method prompt:
+
+   ```bash
+   bun skills/bin/code_hosting.ts \
+     --repo-root "$CANDIDATE_ROOT" --remote "$BASE_REMOTE" pr-merge \
+     --number "$PR" --method "$MERGE_METHOD" \
+     --expected-base "$LOCKED_BASE" --expected-head "$LOCKED_HEAD"
+   ```
+
+   Fail closed if the guard flag is unsupported. A merge-queue enqueue is not a merged terminal state; refresh live facts until the PR is actually merged or a concrete blocker is returned.
+
+4. Fetch the resulting PR state and actual merge commit SHA. If the command outcome is ambiguous, inspect live facts before retrying and never issue a blind duplicate merge. These live merged-PR facts and the actual merge SHA constitute the Merge Receipt for Step 6. Launch target CI tracking and authorized independent release preparation immediately; do not wait for the ledger's terminal post-merge receipt or subsequent merge-scope operations.
+5. For a merged UI PR, call `skills/ui-visual-evidence/scripts/pr_body_image_gate.ts` Phase B. It reads only the managed `## Visual Evidence` section, binds URLs to the merge SHA, verifies the selected platform's rendered Markdown HTML, and keeps the existing bounded retry semantics.
+6. Resolve the live normalized `head_repository`, `head_ref`, and `is_cross_repository` immediately before remote-head cleanup. Delete only when `head_repository == REPO` and `head_ref` is non-empty, using the exact API ref and repository binding:
+
+   ```bash
+   bun skills/bin/code_hosting.ts \
+     --repo-root "$CANDIDATE_ROOT" --remote "$BASE_REMOTE" branch-delete \
+     --branch "$HEAD_REF"
+   ```
+
+   Treat DELETE HTTP `200` or `204` as a successful deletion candidate. Treat DELETE HTTP `404` or `422` as an already-absent candidate because a previous attempt or repository auto-delete may have removed the ref; do not describe those responses as a successful DELETE. Any other DELETE response is a blocker. A delete `404` or delete `422` still requires the bound GET below to prove the final absence; the GET result is authoritative.
+
+   The adapter performs the bound GET and accepts only HTTP `404` after the delete request:
+
+   A verified `404` after DELETE `200/204` records `deleted`; a verified `404` after DELETE `404/422` records `already_absent`. A missing `404` result or any other response is a blocker. Fork, non-owner, protected, or unknown head states are explicit non-deleting terminal dispositions, never permission to guess a remote or ref.
+
+7. Run `skills/project-engineering-workflow/scripts/base_alignment_helper.ts` against the primary worktree and PR base. Apply only its safe tracking-ref or fast-forward plan; dirty, ahead, diverged, and linked-worktree states return an owner decision or blocker.
+8. Record the receipt against the actual merge SHA after terminal CI and release facts are available. The caller continues both tracks and selected-flow closeout.
+
+For `mode=post-merge`, do not run `merge_preflight.ts` or `code_hosting.ts pr-merge`; this branch can never issue a second merge. Refresh the already merged PR and recorded `merge_sha`, then perform only the unfinished merge-scope/post-merge operations from the envelope:
+
+1. Run Phase B image finalization when a merged UI PR still needs it.
+2. Re-resolve `head_repository`, `head_ref`, and `is_cross_repository`. Delete and verify the exact API ref in that repository through the adapter's bound DELETE plus GET that proves HTTP `404`. DELETE `200/204` records `deleted`; DELETE `404/422` followed by `404` records `already_absent`; any other DELETE response or a non-`404` GET is a blocker. Report a fork, non-owner, protected, or unknown head as an explicit non-deleting disposition. Do not treat deletion as a merge operation.
+3. Run `base_alignment_helper.ts` and apply only its safe plan, returning the existing owner-decision/blocker states for dirty, ahead, diverged, or linked worktrees.
+4. Record or refresh the receipt against the exact `merge_sha`, then return the target/integration CI and release facts still required by the caller.
+
+## Stop Conditions
+
+`merge-only` leaves local cleanup untouched after merge-scope facts are verified. `merge+cleanup` delegates local cleanup to `$git-cleanup` only after remote-head disposition, base alignment, target/integration CI, and release terminal facts are established. Child PRs return their merge facts to the owning coordinator; the parent PR continues the shared post-merge release contract and its final merge remains owner-controlled.

package/toolkit/skills/project-engineering-workflow/references/pr-publication-procedure.md

@@ -0,0 +1,39 @@
+# PR Publication Procedure
+
+This procedure is the mechanical publication layer for workflow Step 5. The caller owns flow authorization, role legality, applicable contracts, visual comparison, and the Step 5 stop condition. This procedure does not grant any of them.
+
+## Operation Envelope
+
+The caller supplies:
+
+- `mode=publish|draft-bootstrap`;
+- `PR_ROLE`, exact repository, target base ref and `expected_base_sha`, current topic head and `expected_head_sha`, and candidate worktree;
+- the already-approved publication authorization;
+- current validation, Spec/Solutions/Project Docs, the Step 4 readiness and Tier/rationale assessment, and Step 4B visual evidence facts; completed PR-stage formal findings are not required yet for a direct PR path and are created after exact live PR binding;
+- the current stop condition and, for a parallel direct task, its frozen cohort/task metadata.
+
+The procedure returns the live PR identity, base/head facts, draft state, managed-body result, image-gate result when applicable, bound candidate SHA, and the next workflow gate or concrete blocker. It does not decide or prove a post-merge release.
+
+## Preconditions
+
+Require a non-default topic head, a committed clean candidate whose OID equals `expected_head_sha`, an exact base whose OID equals `expected_base_sha`, unambiguous repository identity, and no suspicious credential-like content. Derive one current `pre_merge_release_route` immediately before the first remote mutation. An explicit valid target-repository contract or already-adopted project-local Policy Skill may return managed release-label groups. When no applicable route is exposed, return `no-managed-route` with an empty managed label set and continue; do not ask the owner for a route and do not block PR publication. This route result is not the release decision: before a merge continuation, Step 5C separately reads target policy and current PR facts and returns the decision card from `release-planning-short-contract.md`. Dot-codex never invents release labels and preserves post-merge release tracking as a separate contract. The resolver returns one structured route card bound to the current repository and current or pending PR identity: `pre_merge_release_route`, `route_source`, `target_repo`, `target_pr`, `current_repository_facts`, `current_pr_facts`, and `managed_release_labels`. Before an open PR exists, `target_pr` is explicitly `null` and `current_pr_facts` must state that no open PR exists for the exact head/base pair; the card must also carry `target_head` and `target_base` matching those facts. After PR creation or reuse, refresh the card with the positive PR number before any subsequent PR-scoped mutation. `route_source` is `repository-contract`, `project-policy`, or `none`; only the first two may return a non-empty managed-label set. Discovery checks the target checkout's explicit contract first, then a Policy Skill adopted by that target repository, and uses the approved code-hosting adapter for live identity facts. The global Skill catalog is not a target policy source. For a UI candidate, the caller must provide a completed current visual comparison and its explicit Task Evidence Set handoff. A draft bootstrap is feedback-only and may not bind receipt, CI, review, convergence, or merge readiness. CI facts are classified only through `ci-tracking-short-contract.md`. The publication path keeps provider policy observation separate from required-check evidence: `no checks reported` is not a blocker until live facts prove a required gate, while a policy `unknown|unavailable` observation is preserved and cannot be rewritten as either `checks_expected=no` or a failed required check.
+
+## Procedure
+
+1. Fetch live repository and PR facts with the approved code-hosting adapter. Never change remote URLs, upstreams, credentials, or required checks. For an existing PR, apply `pr-diagnosis-short-contract.md` §3 before proceeding.
+2. Resolve the current route silently and emit the structured route card. If the route is `no-managed-route`, keep the managed-label set empty. Reconcile labels only when the card has a valid target-owned source and group; preserve unrelated labels and report policy diagnostics without converting them into an owner-supplied route decision.
+3. Re-read the candidate and base OIDs immediately before pushing. If either differs from the envelope, return `input_stale` and require a fresh envelope.
+4. Push the exact current head using the caller-approved target. Do not create a new branch or alter the current head while publishing.
+5. Find an open PR for the exact head/base pair and require its managed delivery role metadata to equal `PR_ROLE`. Reuse one matching PR; create exactly one when none exists; stop if role metadata is absent/mismatched, the identity is ambiguous, or a duplicate would be created.
+6. Re-read the live PR head/base after push and before body mutation. Any head or base drift from the envelope is `input_stale`; do not rewrite the body. Reapply the §3 freshness gate before body mutation or convergence launch.
+7. Build the managed PR body from the current delivery role, Spec disposition, Solutions, Project Docs, validation, and custom notes. Preserve text between `<!-- CUSTOM_NOTES_START -->` and `<!-- CUSTOM_NOTES_END -->`.
+8. When visual evidence applies, call `skills/ui-visual-evidence/scripts/pr_body_image_gate.ts` Phase A with the explicit Task Evidence Set or exclusive `--no-evidence`. Bind URLs to the live head branch and verify the result through the selected platform's rendered Markdown HTML. A new commit on the same branch does not rebind unchanged image paths.
+9. Outside `draft-bootstrap`, bind validation and checks to the current PR head SHA, and carry the workflow-owned readiness assessment for the caller's Step 5B/5C gates. After exact live PR base/head binding, the direct PR path starts fresh PR-stage formal evidence in the same first round as required-CI tracking and waits for both to reach terminal state before convergence writes, finding disposition, or a Repair Batch. Apply the shared CI state matrix to the bound facts; exclude manual dispatch, schedule, release, deploy, and unrelated SHA runs, and refresh freshness/conflict before classifying absence. `flow_receipt.ts bind-pr` is only a validation-audit association and does not enforce that assessment or review convergence. This procedure does not invent a second review policy or a second merge review. A `Design-Returning Review Finding` from the caller's formal review lanes stops convergence until the caller resolves the design and refreshes the changed candidate's required lanes.
+
+## Draft Bootstrap
+
+For `mode=draft-bootstrap`, publish or reuse the feedback Draft, record its published SHA and approved-goals fingerprint, then return control to Step 3. Do not report `Step 5C Ready` and do not start required-CI tracking, formal review, receipt binding, or merge work.
+
+## Safety
+
+Every new candidate SHA restarts SHA-bound validation and check binding. A failure caused by unrelated architectural work belongs in a follow-up PR. This procedure never weakens tests, policy, or repository rules to obtain a green result.

package/toolkit/skills/project-engineering-workflow/references/release-planning-short-contract.md

@@ -0,0 +1,27 @@
+# Pre-Merge Release Decision Short Contract
+
+This reference defines the runtime decision at Step 5C. It is deliberately not a plan schema and does not add fields, stop-condition values, or a final version to a new `<proposed_plan>`. Existing `Flow Decision`, `Acceptance & Validation`, and `Assumptions/Defaults` sections describe the behavior and the applicable stop; historical sessions may retain retired arrangement metadata for audit only.
+
+## Decision card
+
+For `merge-ready`, `merge-only`, and `merge+cleanup`, read the target repository's native release policy and current PR facts at Step 5C. Return one Agent default decision card containing:
+
+- publish applicability (`yes`, `no`, or `unknown`/blocked);
+- release components, channel, bump rule, predicted version, target repository, target branch/PR, policy source, collision policy, required preparation and release trigger;
+- the current pre-merge route as routing input only, never as proof that no release applies.
+
+Structured cards use `contract_version=3`, with `required_preparation` and `release_trigger` as nonempty, resolved descriptions for `publish=yes`. Unversioned historical cards remain replayable; unsupported versioned cards are rejected and historical cards cannot infer these newly explicit inputs.
+
+The card is re-evaluated when the current PR or policy facts change. Missing or conflicting policy/facts return `unknown`/blocked. A missing `pre_merge_release_route` is `no-managed-route` for label routing only; it must not silently become a no-release decision.
+
+## Owner gate and locked inputs
+
+The owner must explicitly confirm the displayed card and its version expectation before merge continuation. One clear natural-language owner message is sufficient and may combine card confirmation, the version expectation, and the request to continue or merge. The Agent MUST NOT require a prescribed reply string, field order, or response format, and MUST NOT split a clear confirmation into a second confirmation/action turn. Ordinary prose such as "the card looks good; use version 1.2.4 and merge" is valid when it is unambiguous. A generic continuation without a recoverable version expectation is insufficient; ask one concise natural-language clarification only when the applicability or version expectation is genuinely missing or ambiguous. An objection returns to the release decision and does not authorize merge or publication.
+
+An unambiguous confirmation of a complete `publish=yes` card together with a merge request authorizes its stated preparation and release trigger. It does not authorize independent operations outside the card. Retain this decision across continuation; recheck policy, inputs, and merge identity after merge. If facts drift or authorization is unclear, block the affected action rather than silently treating the release as inapplicable.
+
+For `merge-only` and `merge+cleanup`, the existing plan prose must make the executable inputs/rule reviewable: target repository and branch, base-tag source, bump rule, channel, components, collision policy, and merge-SHA binding. The plan may record a rule and a predicted runtime result, but it must never prefill the final version string or final tag.
+
+## Post-merge boundary
+
+After merge, evaluate `release_expected` only from actual facts bound to `target_repo + target_branch + merge_sha`. Verify the actual version, tag, artifact identity, and merge SHA. Pre-merge cards, route cards, CI snapshots, and release intent do not prove a release. Unknown or conflicting post-merge facts remain unknown/blocked; the workflow never silently assumes no release.

package/toolkit/skills/project-engineering-workflow/references/release-tracking-short-contract.md

@@ -0,0 +1,49 @@
+# Release Tracking Short Contract
+
+Use this contract for shared Step 6B, `$fast-flow`, `$flow-continue`, and the workflow PR merge procedure. Requirements: [Release Tracking](../../../skills/docs/vendor/dot-codex/specs/release-tracking/SPEC.md). Pre-merge route absence and a release decision card do not establish actual post-merge publication.
+
+## Identity and publication proof
+
+- Determine `release_expected=true|false|unknown` from repository-owned policy and live facts. A green intent, snapshot, build, or workflow is insufficient.
+- Keep `target_repo + target_branch + target_sha` fixed as the Release Origin. `target_sha` is the originating merge SHA; `merge_sha` remains its legacy alias. Assign a stable `release_epoch` and record actual version/tag separately.
+- Record `publication_sha` separately. If it differs from the origin, obtain external repository evidence for every preparation/run/PR/tag transition. Never replace the origin silently or accept a tag match as lineage proof.
+- A normalized lineage card carries the same epoch and origin, `publication_sha`, an `origin_locator` for the full origin commit in the bound repository, and an ordered `release_lineage` list. Each edge has `source_sha`, `target_sha`, `relation`, and `evidence`: a repository-owned external fact containing those two SHAs, that relation, and an `external_locator`. Edges must be contiguous from the full origin SHA to the full publication SHA. The locator identifies the bound code-hosting repository's PR, commit, run, or repository artifact on the same code-hosting host as the origin locator; a bare `lineage_verified=true` or child assertion is insufficient.
+- Discover every declared Release, package, container, and pipeline-owned deployment, including each concrete surface identity. Each must have terminal success, actual artifact/deployment identifiers, version/tag, publication SHA, time, and external locators. Deployment dispatch is not deployment success. Unknown surfaces remain unverified rather than being silently dropped.
+
+## Role and ownership
+
+- Use the runtime agent-spawn entrypoint with `agent_type="release-tracker"`, explicit `model=gpt-5.6-luna` and `effort=low` (`[gpt-5.6-luna, low]`). Direct and PTC transports are equivalent. Supply this contract and the complete origin, surface, authorization, retry, and observation-window state.
+- A role is not a standalone tool: inspect the runtime role inventory and, if registered, attempt its spawn. Only an actual inventory or startup result establishes availability; report its factual reason without guessing auth, quota, or provider failures. Source configuration checks do not prove a running session has loaded that role.
+- The main Agent owns release authorization and triggering. Tracker availability does not block an otherwise authorized merge or dispatch. Once triggered, missing observation leaves publication unverified and closeout incomplete.
+- On a Merge Receipt, evaluate the confirmed release card against live policy and merge identity while target CI is tracked. Start authorized preparation that does not depend on CI immediately; dispatch only after repository-specific prerequisites pass. A manual workflow not yet triggered is not evidence of `release_expected=false`.
+- One tracker owns live observation of one release epoch. The main Agent waits on its runtime-returned handle. Reuse an active tracker; create a successor only after the prior one is confirmed stopped or terminal. Do not fall back to a parent poller, repository watcher, transcript parser, generic agent, or implicit model switch.
+
+## Recovery and shared deadline
+
+- On unavailable or interrupted tracking, save a recovery anchor: chat, epoch, fixed origin, trigger time/receipt, run and surface locators, known lineage, active child handle, actual startup reason, retry record, window start, and absolute deadline. Preserve this state across successor trackers.
+- Tracking MUST NOT create, update, or reuse an app automation, heartbeat, cron, or scheduler. The main Agent waits only on the runtime-returned tracker handle while it exists; a missing or interrupted handle returns `unavailable|incomplete` with its recovery anchor. The owner resumes with `$flow-continue`, which reuses the same identity, configured profile, and history rather than creating a scheduled poller or redispatching a release.
+- Keep unchanged/non-actionable state quiet. Notify on completion, terminal failure after any permitted retry, required owner action, or budget exhaustion. If the tracker handle is unavailable, retain the anchor and report that precise gap for manual continuation.
+- The initial wall-clock window starts at confirmed merge for an automatic release, or confirmed dispatch for a manual one. Without a release recovery operation, the absolute deadline is 30 minutes from that start.
+- A permitted rerun or another explicitly authorized release recovery operation extends that same window to at most one hour from its start. Startup outages, waits, read-only checks, tracker recreation, and manual `$flow-continue` continuation never reset or extend it. No scheduler may continue observation past the deadline.
+- At the deadline, stop observation and the child without cancelling the external release. Return incomplete with the recovery anchor. An explicit owner `$flow-continue` resumes the same bounded window when time remains, preserving the origin, deadline, lineage, and spent retry history; it never resets or extends the budget.
+
+## Terminal and retry rules
+
+- `发布状态=已发布` requires terminal success and matching actual identities for every declared surface, with verified lineage if the publication SHA differs. `release_expected=false` alone permits `发布状态=未触发`; unresolved applicability remains `unknown` or `未终态`.
+- The tracker may rerun the same existing failed run at most once for the tracked release, when its task authorization permits it and attributable evidence proves `idempotent=true` and `retry_safe=true` for that exact run. Save the retry intent before mutation and the returned run/attempt receipt afterwards. An ambiguous prior retry consumes the allowance pending owner resolution.
+- Require the run's own terminal failure, not a nested artifact failure. Provided safety locators and the actual rerun repository (including CLI flags and environment overrides) must match the bound run. Conflicting aggregate safety facts fail closed; delayed reads or older attempts cannot restore revoked failure or safety permissions. After retry, explicit attempt evidence must be bound to the retry receipt before it can prove publication. A newer successful observation of the same externally restored run clears only that run's unresolved failure; other failed surfaces remain unresolved.
+- Never dispatch a replacement release, change inputs/version/channel/target, or restore a spent retry allowance by changing tracker, scheduler, or window. Other recovery mutations require their own explicit authorization.
+- Observe every surface again after retry. Missing safety evidence, exhausted allowance, or continued failure requires owner action and unsuccessful closeout; a successful rerun workflow alone does not prove publication.
+
+## Return fields
+
+Return `phase=post_merge_release`, `bound_sha=<origin>`, `publication_sha`, `release_epoch`, `terminal_state=passed|failed|incomplete|unavailable`, the origin and per-surface facts/locators, retry record, window start/deadline, and any recovery anchor. `passed` requires complete external publication proof.
+
+Always return `release_expected=true|false|unknown` and owner-facing fields:
+
+- `发布状态=不适用|未触发|运行中|已发布|失败|未终态|未检查`
+- `发布版本`, `发布tag`, `发布channel`, `发布起始sha`, `发布绑定sha`
+- `发布workflow`, `发布URL`, `发布时间`, `发布产物`
+- `发布处置=report-only|rerun-once|owner-action-required|none|未检查`
+
+`发布起始sha` is the fixed origin; `发布绑定sha` is the actual publication SHA. For failures, include the failing surface and required owner action. For non-release merges, include one-line live evidence for `未触发`.