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

package/toolkit/skills/docs/vendor/dot-codex/solutions/workflow-issues/forge-transport-decoupling.md

@@ -0,0 +1,116 @@
+---
+title: Decouple Code Hosting Transport from Delivery Workflows
+module: codex-global-workflow
+problem_type: integration
+component: code-hosting-transport
+tags:
+  - code-hosting
+  - github
+  - gitea
+  - cli
+  - workflow
+status: active
+related_specs:
+  - docs/specs/code-hosting-platform/SPEC.md
+resolution_type: architecture
+---
+
+# Decouple Code Hosting Transport from Delivery Workflows
+
+## Context
+
+dot-codex delivery rules currently name GitHub and `gh` directly in several workflow and tracker contracts. Those names leak a provider implementation into otherwise provider-neutral work: determine a repository, publish a change, inspect a PR, collect CI evidence, and perform a guarded merge.
+
+Git transport remains Git: `git fetch`, `push`, branch inspection, and worktrees do not need a code-hosting adapter. The adapter owns only the control plane that has platform-specific identifiers, URLs, credentials, APIs, and capability semantics.
+
+## Resolution
+
+Introduce one small code-hosting-platform boundary, selected before any platform API or CLI operation. Workflows call semantic operations rather than `gh` or `tea` commands:
+
+| Semantic operation | Required normalized result |
+| - | - |
+| `resolve_repository` | platform kind, `web_origin`, `api_origin`, `owner`, `repo`, selected remote, canonical repository URL |
+| `get_or_create_issue` | platform URL, numeric repository-local number, state, title/body |
+| `get_or_create_pr` | platform URL, numeric repository-local number, base/head refs and immutable head SHA |
+| `get_pr_facts` | open/merged state, base/head, head SHA, mergeability, reviews, comments, source URL |
+| `get_ci_facts` | exact SHA, named check/run identity, state, conclusion, evidence URL, observed time |
+| `submit_review` | review state, submitted SHA, comment/review URLs |
+| `merge_pr_at_head` | merged state, resulting merge SHA, used expected head SHA |
+| `render_asset_url` | platform-valid Markdown URL for a repository asset pinned to a ref |
+
+The shared workflow must make policy decisions only from normalized facts. A platform adapter must never silently map missing facts to passing facts. An unsupported capability is a typed `unsupported_capability` result, not a fallback to another host or an ad-hoc browser operation.
+
+### Repository and Platform Selection
+
+1. Resolve the delivery `BASE_REMOTE` under the existing workflow's explicit remote-selection rules. Do not presume `origin`; a fork/upstream checkout can have several remotes.
+2. Read its configured fetch/push URL with `git remote get-url`; parse standard SSH scp-like (`git@host:owner/repo.git`) and URI forms using a real Git URL parser, not prefix matching.
+3. Canonicalize `host`, strip a terminal `.git`, and extract exactly one `owner/repo`. Reject a URL which cannot be represented that way.
+4. Select a provider from a configuration-owned exact host allowlist, initially `github.com -> github` and `git.ivanli.cc -> gitea`. Do not infer provider from a repository name, organization, URL path, or a user-provided PR URL.
+5. Bind every platform request to this resolved repository identity. A supplied Issue/PR/evidence URL must have the same normalized host and repository; an adapter rejects cross-host or cross-repository identity rather than acting on it.
+6. Require an authenticated profile for that exact platform host before any external write. Auth setup, token creation, and login remain owner actions.
+
+The host map should be data, not conditionals scattered across skills. Unknown hosts are read-only Git remotes until an adapter is explicitly added and the owner authorizes its use. The source of each repository's required CI policy remains an explicit design decision; a Candidate-controlled repository file cannot set that policy.
+
+### Provider Implementations
+
+`github` may retain `gh` for its normal CLI path. `gh auth login` supports a specific hostname, and `gh pr create` supports a `[HOST/]OWNER/REPO` repository selector. It should be invoked only by the GitHub adapter, never by a generic flow directly.
+
+`gitea` may use the installed Tea CLI (`tea 0.16.0` observed locally) for ordinary operations. Tea has named logins stored in its own configuration; its entity commands accept `--login`, `--repo`, and `--remote`. The adapter should select an explicit named login from the resolved host, e.g. `--login ivan-gitea`, rather than depend on Tea's mutable default login or on ambient repository discovery. `tea logins add` also offers a Git credential helper; do not enable that implicitly because Git authentication is outside the platform adapter's authority.
+
+Use provider REST APIs behind the same adapter when the CLI cannot preserve a workflow invariant or provide structured facts. Tea's documented local help exposes issue and pull create/edit/list, approve/reject/review, comments, and Action run/workflow commands, but `tea pulls merge` has no expected-head-SHA option. It is therefore insufficient for guarded merge by itself.
+
+## Initiative Boundary
+
+Initiative Contract v5 is GitHub-only. A Gitea repository binding must reject Initiative entry before creating a tracking issue, child issue, PR, or release record. The adapter does not attempt to simulate GitHub issue hierarchy through Gitea dependencies, checklists, or links.
+
+## Capability Matrix
+
+| Capability | GitHub implementation | Gitea implementation | Adapter rule |
+| - | - | - | - |
+| Issue CRUD | `gh issue` / GitHub REST | `tea issues` / `/api/v1/repos/{owner}/{repo}/issues` | Return repository-local number and canonical URL. |
+| PR CRUD | `gh pr` / GitHub REST | `tea pulls` / `/api/v1/repos/{owner}/{repo}/pulls` | Read back base, head, and current head SHA after a write. |
+| Reviews | `gh pr review` / GitHub REST | Tea approve/reject/review or `POST .../pulls/{index}/reviews` | Bind review facts to the reviewed head SHA where the provider supplies it. |
+| Guarded merge | GitHub REST merge accepts `sha` | Gitea REST merge accepts `head_commit_id` | Refuse to merge unless live PR head equals the verified SHA; pass that same SHA to the merge request; re-read merged state and merge SHA. |
+| Commit status | GitHub combined commit status and Checks APIs | Gitea commit statuses and Action-task APIs | Normalize status and workflow evidence, but preserve provider-specific raw fields. |
+| CI runs | GitHub Actions check/run APIs and `gh pr checks` | `tea actions runs` and `/actions/tasks` | A named CI policy must declare its provider adapter and exact-SHA match. |
+| Repository image | GitHub raw/blob URL form | Gitea `/raw/{ref}/{path}` or `/src/{ref}/{path}?raw=1` | Generate only via `render_asset_url`; never reuse a GitHub URL formatter for Gitea. |
+
+### CI and Actions Are Not a Shared Contract
+
+Both platforms expose commit statuses, and Gitea's API exposes workflow tasks with `head_sha`, event, status, and workflow identity. This supports an exact-SHA evidence model, but it does not make GitHub Actions and Gitea Actions interchangeable. Gitea documents Actions as mostly GitHub-compatible while listing differences: `jobs.<id>.environment` is ignored, complex `runs-on` is not supported, only `always()` is supported among expressions, and several GitHub token scopes are absent. Gitea runners are independently deployed.
+
+Consequently, a workflow's generic rule can be “wait for declared CI evidence at the verified SHA”, while a provider/project-specific profile declares how a check is located, what success means, and whether Actions is even enabled. Do not hard-code a GitHub workflow event, check-run field, or Actions URL into the generic delivery contract.
+
+### Image URLs and Attachments
+
+GitHub CLI can upload PR attachments and rewrite local image references during `gh pr create`. That behavior is not a generic repository-image facility. Gitea resolves Markdown relative to its rendering context and supports raw repository content at `/owner/repo/raw/{ref}/{path}`; it also accepts the GitHub-like `?raw=1` redirect form from `/src/{ref}/{path}`. Gitea exposes Issue/PR attachments through its API, but Tea's PR creation help has no equivalent attachment flag.
+
+The adapter must choose one of two explicit strategies per provider: a repository asset pinned to an immutable commit SHA, or a provider attachment whose returned download URL is recorded. Existing GitHub-only PR-body image normalization needs a Gitea formatter and renderer verification; it cannot be renamed and treated as portable.
+
+## Unsupported or Separate Design Work
+
+- GitHub Issue parent/sub-issue semantics used by the current initiative tracker have no demonstrated Gitea equivalent in this research. Gitea initiative support requires a separate tracker model (for example, local ledger plus explicit issue links) and acceptance contract; do not claim parity merely because both hosts have Issues.
+- GitHub-specific surfaces such as GraphQL-only fields, rulesets, check-suite details, projects, and attachment behavior require explicit adapter methods or an `unsupported_capability` result.
+- Platform API versions must be observed per target Gitea server. This note uses the Gitea 1.27 API documentation, but the adapter should query its instance version/read capabilities before relying on optional endpoints.
+- A `tea` login is not a token authority delegation. The agent may inspect configured login status when authorized, but must not create tokens, log in, alter credential helpers, or print secrets.
+
+## Guardrails / Reuse Notes
+
+- Resolve platform identity once per operation and carry it as an opaque `RepositoryBinding` value. Do not reconstruct it from incidental URLs later.
+- Keep Git remote mutation, Git push target changes, and platform writes behind their existing owner-authorization gates.
+- Treat CLI output as an implementation detail. Adapters should request JSON when available and validate schema before normalizing facts.
+- Preserve original URLs, raw provider responses, and observation timestamps as evidence, alongside portable normalized fields.
+- Do not turn a generic delivery flow into a lowest-common-denominator flow: capability requirements belong to the operation contract and should fail clearly when a provider lacks them.
+
+## Primary References
+
+- GitHub CLI, [`gh auth login`](https://cli.github.com/manual/gh_auth_login): host-specific authentication and credential behavior.
+- GitHub CLI, [`gh pr create`](https://cli.github.com/manual/gh_pr_create): repository selector, PR fields, and GitHub attachment behavior.
+- GitHub REST, [merge a pull request](https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request): expected `sha` merge guard.
+- GitHub REST, [commit statuses](https://docs.github.com/en/rest/commits/statuses): combined commit status semantics and exact-ref lookup.
+- Tea source repository, [Gitea Tea](https://gitea.com/gitea/tea): primary project source. Local `tea 0.16.0 --help`, `tea logins --help`, `tea pulls --help`, and subcommand help were consulted for CLI flags and command availability.
+- Gitea 1.27 API, [API index](https://docs.gitea.com/api/): API surface and OpenAPI version.
+- Gitea API, [merge a pull request](https://docs.gitea.com/api/operations/repo-merge-pull-request/): `head_commit_id` merge guard.
+- Gitea API, [create a pull request](https://docs.gitea.com/api/operations/repo-create-pull-request/), [create a review](https://docs.gitea.com/api/operations/repo-create-pull-review/), [create a commit status](https://docs.gitea.com/api/operations/repo-create-status/), and [list action tasks](https://docs.gitea.com/api/operations/list-action-tasks/).
+- Gitea documentation, [Compared to GitHub Actions](https://docs.gitea.com/usage/actions/comparison/) and [Actions overview](https://docs.gitea.com/usage/actions/overview/).
+- Gitea documentation, [Markdown link-path resolving](https://docs.gitea.com/usage/repository/markdown/).

package/toolkit/skills/docs/vendor/dot-codex/solutions/workflow-issues/git-skill-convergence.md

@@ -0,0 +1,105 @@
+---
+title: Converge pure git operations into a local skill layer
+module: codex-global-workflow
+problem_type: workflow_issue
+component: git-skill-routing
+tags:
+  - git
+  - skills
+  - prompts
+  - workflow
+status: active
+related_specs:
+  - docs/specs/git-skill-convergence/SPEC.md
+  - docs/specs/initiative-flow/SPEC.md
+resolution_type: migration
+---
+
+# Converge Pure Git Operations Into A Local Skill Layer
+
+## Context
+
+Codex workflow repos can accumulate prompt shortcuts and flow-specific prose for the same local Git operations: branch creation, worktree lifecycle, base sync, and cleanup. When those contracts live in many places, prompt retirement becomes brittle and PR/flow skills keep repeating low-level Git rules.
+
+## Symptoms
+
+- Multiple prompts or skills recommend different branch/worktree cleanup paths.
+- PR merge skills own local branch/worktree cleanup details in addition to GitHub merge semantics.
+- Flow recovery references deleted prompts instead of stable skills.
+- Design prompts create branches or stash changes even though they should only shape a design.
+- A replacement sync skill stalls on ordinary "sync mainline" requests because it only accepts pre-resolved `BASE_REF` / `REMOTE`.
+- A planner says "default to mainline" but emits only an abstract phrase, while execution continues from a detached `HEAD` or a stale topic branch.
+- A moved helper script is documented with a global home path even though the new file only exists in the checked-out repository.
+- A flow resume route calls a generic cleanup skill without carrying the PR identity that the old prompt/skill path had in context.
+- A new closeout gate requires explicit absence evidence, but the orchestration handoff only passes existence paths.
+- A resumed cleanup flow reports a branch status without the branch identity needed to re-run the proof helper.
+- A handoff says a resource was required but omits the required resource identities needed to verify removal.
+- A cleanup flow accidentally treats a native Codex Ticket Worktree as a disposable manual Git Worktree.
+
+## Root cause
+
+Pure `git/local repo` operations and orchestration semantics were mixed together. The orchestration layer needs to decide when a branch, worktree, sync, or cleanup action is needed; the local Git layer should own how to do it safely.
+
+## Resolution
+
+- Create a small canonical local Git skill surface:
+  - `git-branch` for local branch create/switch/delete.
+  - `git-worktree` for worktree lifecycle and lease cleanup integration.
+  - `git-sync` for confirmed-base fetch / detached alignment / fast-forward / rebase sync.
+  - `git-cleanup` for local branch/worktree/lease cleanup and closeout proof.
+  - keep remote/auth/transport troubleshooting separate as `git-remote-troubleshoot`.
+- Delete retired prompts and old local Git skills instead of keeping stubs.
+- Update flow and PR skills to reference the canonical Git skills by name.
+- Keep historical specs and replay fixtures unchanged unless they are loaded as current runtime policy.
+- Preserve user-facing defaults when deleting a narrow skill: `git-sync` still resolves remote default branches for bare mainline-sync requests instead of forcing callers to provide parameters.
+- Treat a clean detached maintenance worktree as a separate `git-sync` path: after resolving and fetching a confirmed base, direct checkout to its exact commit without creating a branch, backup ref, or stash. First prove that the old commit remains reachable through target ancestry, an existing ref, or a HEAD reflog entry for that exact commit; otherwise stop because no backup ref was authorized. Bare owner mainline-sync requests select this path only while `HEAD` is detached; keep rebase for attached topic branches and reserve the shared `BASE_REF` + `REMOTE` contract for topic-branch rebase.
+- Separate "default baseline policy" from the final concrete value: owner-facing plans may explain that the default is the target repo mainline, but the final development baseline must still be emitted as a concrete branch/ref or commit.
+- Keep merge-scope primary-base alignment helpers with `pr-merge`, not `git-sync` or cleanup. That logic depends on merged PR base/head facts plus Git primary-worktree ownership, so a local helper should auto-apply only safe ff/tracking-ref updates and leave dirty/ahead/diverged primary-base states on the existing owner-decision path. Once the owner explicitly selects `安全对齐`, the same helper can own the backup-branch/stash/rebase/apply sequence and emit a structured recoverable-conflict state instead of falling back to ad-hoc shell composition.
+- Treat topic-branch freshness as a shared workflow concern, not just a git helper concern: if no topic branch exists, create one from the resolved baseline; if a topic branch already exists, sync it before implementation and re-check it again at closeout.
+- Invoke moved helper scripts relative to the loaded skill directory, not a hardcoded global installation path.
+- When an orchestration skill hands off to a generic local Git skill, include the mode and identity fields that used to be implicit in the old entrypoint.
+- Pass explicit "not required" facts into gates that distinguish unknown from absent state.
+- Status surfaces used for recovery must include object identity, not just three-state existence.
+- When passing a requirement flag into cleanup, pass the corresponding required object paths in the same handoff.
+- Keep native Codex Ticket Worktrees outside `$git-worktree` create/remove and `$git-cleanup` removal. Their archive lifecycle belongs to the native task; cleanup may record the path and release a task-owned service lease only when the task lifecycle resolves it.
+
+## Guardrails / Reuse notes
+
+- Do not let cleanup skills perform PR merge, remote protocol changes, or upstream/push target rewrites.
+- Do not move GitHub PR semantics into local Git skills.
+- Do not hardcode the default baseline to `origin/main` as a universal truth source. Use the target repo mainline as the default policy, but preserve stronger Git facts such as unique open PR base or explicit upstream integration branch.
+- Run an active-reference grep over `AGENTS.md`, current `skills/**`, retained `prompts/**`, README/index docs, and runtime helpers; exclude historical `docs/specs/**`, replay, and fixtures when the migration explicitly scopes them out.
+- Move executable closeout scripts and tests with the canonical skill that owns their proof contract.
+- When replacing a retired baseline-sync entry, include both explicit confirmed-base calls and bare owner requests in the new contract; otherwise routing becomes cleaner but day-to-day sync regressions appear.
+- Detached alignment must be a positive, narrowly named action. Do not silently use it to evade a blocked rebase or fast-forward request, and block on a dirty worktree before moving `HEAD`.
+- When tightening a plan contract around "baseline", update both the plan checker and the shared Step 1/Step 4 execution path. Otherwise the plan can look correct while the actual branch context stays stale.
+- Baseline text heuristics should prefer concrete git-ref validation before classifying a value as "abstract" or "placeholder". Otherwise legitimate refs like `feature/default-mainline-baseline-cleanup` or `todo-cleanup` get blocked by wording-only guards.
+- The inverse guard matters too: a value that merely _looks_ like a git ref to `git check-ref-format` is not automatically a valid development baseline. Remote symbolic aliases such as `origin/HEAD`, and combined abstract phrases like `目标仓库主干基线`, still need explicit rejection so the contract only accepts stable concrete refs or commits.
+- Owner-baseline extraction must treat replacement clauses such as `开发基线从 A 改为 B` as an override to `B`, not as evidence that `A` remains the active baseline.
+- Plain-text replacement-clause heuristics must not treat the `to` inside a concrete ref like `topic/foo` or `todo-cleanup` as the replacement keyword; otherwise valid explicit baselines are truncated and falsely rejected.
+- If a request clearly opens a fresh planning window (`重新规划这个任务`, `re-plan this task`), that reset must win over continuation words in the same sentence such as `改为 merge-ready`; otherwise prior owner baselines leak into a new plan session.
+- Treat short owner baseline spellings the same as the longer forms owners actually use. Chinese shorthand like `开发基线用 upstream/release-2026q3` should participate in the same explicit-baseline mismatch guard as `开发基线使用 ...`.
+- Do not require verbose branch names before owner-baseline extraction kicks in. Short plain-text refs like `qa` or `rc` can still be legitimate baselines and should be validated as refs instead of being dropped before comparison.
+- Preserve legal trailing git-ref characters during owner-baseline normalization. Plain-text baselines that end with `,` or `;` are ambiguous but valid refs, so only strip them when they clearly introduce a follow-up clause such as `, 并继续`.
+- Directional owner-baseline extraction needs a second guard beyond the leading verb. Phrases like `基于 new plan file upload API 规划这个任务` describe product scope, not a git baseline, so plain directional extraction should only survive when the value is explicitly labeled (`branch/ref/commit`) or already looks like a concrete ref/commit.
+- Treat backtick-wrapped spec/doc inputs as planning context by default, not as plain directional baselines. A phrase like ``基于 \``docs/specs/.../SPEC.md\` 规划这个任务``should stay a spec-input hint unless the owner also adds stronger Git semantics such as``开发基线``, ``BASE_REF``, or ``基于 ... 开发`.
+- If `flow_type` clarification is still pending, a natural-language reply such as `请按 normal 继续出计划` is still part of the same planning session and must preserve any earlier explicit baseline.
+- New-plan detection should not fire on any bare `计划` token. Product compounds like `计划页面上传 API` or `planning UI` need a request-shaped phrase (`给我计划`, `继续出计划`, `按 normal 流程计划`) before they can reset the planning session.
+- A plain-language request such as `请帮我规划这个任务：...` is a fresh planning window, not a continuation. Otherwise stale `flow_locked` / `owner_explicit_baseline` state leaks into unrelated plans.
+- Support the short explicit-baseline spellings owners actually use (`base=...`, `base:...`), not only verbose `baseline` / `base ref` / `BASE_REF` forms.
+- Continuation heuristics should not classify a new task request as follow-up only because the task name contains `merge`; explicit plan requests like `$dev-plan merge queue API` must still reset prior planning-session state.
+- Give fresh-request signals higher priority than continuation wording when the owner explicitly reopens `$dev-plan`. Phrases like `请用 $dev-plan 继续给我一份新的可执行计划` are new plan requests, not permission to leak the previous session's flow/baseline lock.
+- Path-like wording guards should only reject true filesystem-path baselines, not every legal git ref that happens to resemble a doc path. A branch like `feature/README.md` is still a valid explicit baseline; `./docs/specs/foo/SPEC.md` is not.
+- Placeholder-word heuristics must not block concrete refs like `todo`, `pending`, or `default`, but truly explicit placeholder tokens such as `TBD` should still be rejected even if `git check-ref-format` happens to accept them.
+- Reject common bare remote symbolic aliases like `origin/HEAD` / `upstream/HEAD`, plus any fully-qualified `refs/remotes/*/HEAD`, by stable syntax rather than by the current repository's configured remotes. At the same time, avoid broad `*/HEAD` rejection that would incorrectly block valid topic refs like `feature/HEAD`.
+- Check resumed-flow routes for lost implicit context. A generic skill name is not enough when the old path selected a specific operation mode.
+- After tightening a proof gate, add or retain at least one same-worktree/no-dedicated-resource test so absence evidence stays executable.
+- Recovery routes must preserve both requirement booleans and path lists; either one alone can still make a gate non-recoverable.
+
+## References
+
+- `docs/specs/git-skill-convergence/SPEC.md`
+- `skills/git-branch/SKILL.md`
+- `skills/git-worktree/SKILL.md`
+- `skills/git-sync/SKILL.md`
+- `skills/git-cleanup/SKILL.md`

package/toolkit/skills/docs/vendor/dot-codex/solutions/workflow-issues/gui-tool-escalation-gate.md

@@ -0,0 +1,55 @@
+---
+title: GUI tool escalation gate
+module: codex-global-config
+problem_type: workflow_issue
+component: agent-tool-routing
+tags:
+  - gui-automation
+  - bundled-plugins
+  - tool-routing
+status: active
+related_specs:
+  - docs/specs/gui-escalation-gate/SPEC.md
+---
+
+# GUI Tool Escalation Gate
+
+## Context
+
+Codex may expose multiple GUI-capable tools at the same time. Bundled plugin skills can have broad trigger descriptions, so leaving the plugins enabled may cause agents to use GUI automation earlier than intended.
+
+## Root Cause
+
+Bundled plugin cache files are not a stable policy layer. Editing those files can be overwritten by plugin updates or cache refreshes, while disabling the plugins removes legitimate fallback capability.
+
+Another recurring failure mode is fallback drift: an agent sees an `$ego-browser` setup or command failure and treats it as permission to switch to Chrome control, although the requested task has no Chrome-specific requirement.
+
+A second failure mode is `Synthetic DevTools Bootstrap`: the agent launches a fresh Chrome/Chromium/`9222` debugging instance and then treats that synthetic browser as if the repo-owned DevTools Surface had been available all along.
+
+## Resolution
+
+Keep GUI-capable plugins enabled, but enforce routing through repo-controlled policy:
+
+- Put the hard rule in `AGENTS.md`.
+- Add a repo-owned skill that governs browser exceptions and GUI escalation.
+- Preserve the lower-intrusion ladder: files/shell/project scripts/MCP/API/`ego-browser` before explicit Chrome / DevTools exceptions or `Computer Use`.
+- Require a short pre-use disclosure that names the tool, reason, target scope, and risk.
+- Require Chrome / DevTools exceptions to state their concrete task-specific reason; an `$ego-browser` failure alone is not enough.
+- Use one `$ego-browser` TaskSpace for each user goal.
+- Keep `$ego-browser` as the default browser route. Chrome control and `chrome-devtools` remain explicit exception paths, and `Synthetic DevTools Bootstrap` remains disallowed as a normal recovery path.
+- Keep the fix in the current repo-owned policy layer only; do not try to “solve” this by editing bundled plugin cache files.
+
+## Guardrails
+
+- Do not edit OpenAI bundled plugin cache files for long-term policy.
+- Do not disable GUI plugins solely to prevent accidental use.
+- Treat `Computer Use` as the highest escalation, not as a browser fallback.
+- Require explicit approval before state-changing or privacy-sensitive GUI actions.
+- For browser validation, prefer `$ego-browser`; use Chrome control only when the owner explicitly requests it or the existing Chrome session is required.
+- Do not treat `$ego-browser` unavailability as authorization to offer a Chrome or DevTools fallback.
+- Do not treat generic wording like “在浏览器打开” or “继续验证” as authorization to launch a fresh debugging browser instance; that authorization must be explicit and task-scoped in the same thread.
+
+## References
+
+- docs/specs/gui-escalation-gate/SPEC.md
+- skills/gui-escalation-gate/SKILL.md

package/toolkit/skills/docs/vendor/dot-codex/solutions/workflow-issues/stable-preview-handoff-runtime.md

@@ -0,0 +1,74 @@
+---
+title: Native background preview handoff guard
+module: codex-global-workflow
+problem_type: workflow_issue
+component: local-preview-handoff
+tags:
+  - preview
+  - localhost
+  - native-background
+  - port-registry
+status: active
+related_specs:
+  - docs/specs/stable-preview-runtime/SPEC.md
+  - docs/specs/retire-legacy-service-manager/SPEC.md
+  - docs/specs/global-port-preview-governance/SPEC.md
+symptoms:
+  - localhost preview URL worked during the current exec session but died before the user could revisit it
+  - port leases remained after the backing process had already disappeared
+root_cause: The workflow distinguished port ownership, but not strongly enough between a foreground live preview and a preview still owned by a Codex native background session.
+resolution_type: guardrail
+---
+
+# Native background preview handoff guard
+
+## Context
+
+- Scope: global Codex workflow for local preview URLs, Storybook review surfaces, and other owner-facing localhost handoffs.
+- Trigger: a session handed off `http://localhost:30060` while that preview still depended on a foreground exec session; later the exec was interrupted and the URL died.
+- Constraint: `global-port-manager` is still the source of truth for port ownership, but owner-facing handoff must continue to rely on Codex native background capability instead of reintroducing a repo-local service manager.
+- Responsibility boundary: the Agent/host creates and retains the native background session; repo Skills manage only their own service process and port lease. A Skill must not infer a hidden session from a PID or visible terminal.
+
+## Symptoms
+
+- A localhost preview is valid during the current browser validation, then disappears after the owning foreground exec exits.
+- The agent can prove the port lease exists, but cannot prove the preview is still held by a Codex native background session.
+- `leases.tsv` keeps recent rows whose `pid` is gone or whose port is no longer listening.
+
+## Root cause
+
+- After retiring the legacy `devctl/zellij` path, the workflow correctly moved back to Codex native background terminals, but the handoff rules did not draw a hard enough line between:
+  - `live exec preview`: tied to the current foreground exec and suitable only for same-turn validation.
+  - `native background handoff preview`: still owned by a Codex native background session and therefore eligible for owner-facing localhost handoff.
+- Port leasing without pid-backed cleanup also left stale rows behind, which blurred provenance further.
+
+## Resolution
+
+- Keep owner-facing localhost handoff on Codex native background capability; do not add a repo-local detached runtime.
+- Keep the existing dashboard wrapper responsible for its own PID, lease heartbeat and service-only release; this is service lifecycle bookkeeping, not a replacement for host-native session management.
+- Require owner-facing localhost handoff to prove both facts:
+  - the port belongs to the current scope/service lease;
+  - the service is still owned by the current workspace's Codex native background session, with `agent_session` recorded when available.
+- Treat any preview still dependent on a foreground live exec as non-handoffable, even if the lease is correct.
+- Keep `skills/global-port-manager/scripts/port_registry.ts` as the implementation that self-heals pid-backed leases immediately when:
+  - the stored `pid` is dead; or
+  - the leased port is no longer listening.
+- Require dashboard wrappers to atomically claim an empty-PID lease under the registry lock, bind the listener while that claim is held, and write their PID only after the listener is confirmed; an existing PID or already-listening port is a duplicate-startup blocker, not an invitation to transfer ownership.
+- Capture the listener cleanup handle before post-bind verification or lease persistence, and stop it on any startup failure so a rejected handoff cannot leave an unmanaged local service.
+- Keep the old `24h + port-not-listening` TTL only for historical pid-less rows.
+
+## Guardrails / Reuse notes
+
+- Always resolve a lease first via `$global-port-manager`; native background ownership does not replace lease ownership.
+- Use `live exec preview` only for current-turn browser validation. If the user may revisit the URL later, the service must be moved under a Codex native background session first.
+- If the runtime exposes an `agent_session`, write it into the lease so later turns have a concrete provenance breadcrumb.
+- Pass `agent_session` only when the Codex host supplied the real identifier. If no supported native background route exists, keep the URL live-preview-only and report the handoff blocker.
+- Do not hand off a localhost URL and then stop the owning background session in the same run.
+- Do not kill foreign port owners to “fix” handoff; allocate a new lease instead.
+
+## References
+
+- `docs/specs/stable-preview-runtime/SPEC.md`
+- `docs/specs/retire-legacy-service-manager/SPEC.md`
+- `docs/specs/global-port-preview-governance/SPEC.md`
+- `sessions/2026/04/12/rollout-2026-04-12T15-22-00-019d8091-9ee8-7882-b386-17304fca9830.jsonl`

package/toolkit/skills/docs/vendor/dot-codex/specs/2h289-local-merge-cleanup-closeout/HISTORY.md

@@ -0,0 +1,18 @@
+# Local merge cleanup closeout 演进历史（#2h289）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `8bcbcb9` fix(flow): smooth local merge cleanup closeout
+- `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: `#2h289`.

package/toolkit/skills/docs/vendor/dot-codex/specs/2h289-local-merge-cleanup-closeout/IMPLEMENTATION.md

@@ -0,0 +1,55 @@
+# Local merge cleanup closeout 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 收紧 local-merge cleanup 决策树与恢复语义
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-13
+- Legacy last-tracked: 2026-03-13
+- Current lifecycle: active
+- Catalog note: 收紧 local-merge cleanup 决策树与恢复语义
+
+## Delivery Milestones
+
+- [x] M1: 建立 local merge cleanup closeout 规格并登记索引
+- [x] M2: 收紧 local merge cleanup 契约与恢复语义
+- [x] M3: 新增 local closeout gate/context 与测试
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 登记本规格
+- `skills/local-merge-flow/SKILL.md`: cleanup 决策树与 closeout gate 规则
+- `skills/project-engineering-workflow/SKILL.md`: 共享 `Step 5L.3/5L.4` 语义
+- `skills/flow-continue/SKILL.md`: local cleanup 恢复规则
+- `prompts/advance-flow.md`: 顶部恢复提示
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `8bcbcb9` fix(flow): smooth local merge cleanup closeout
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/2h289-local-merge-cleanup-closeout/SPEC.md

@@ -0,0 +1,137 @@
+# Local merge cleanup closeout
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前 `$local-merge-flow` 对本地 cleanup 只有结果字段，没有稳定的决策树；一旦碰到“主人明确保留的无关脏文件 + 隔离 worktree 合主干 + 本地 topic 分支回收”这种组合场景，agent 就容易临场判断。
+- 这类临场判断会把本该自动完成的收尾拖成 `本地收尾=部分完成`，并把 `git branch -D` 一类已可安全自动执行的动作晚抛给主人，导致收尾体验发涩。
+- 不修这个问题，`local-merge` 路径仍会反复出现“代码其实已经合进主干，但最后一步 cleanup 解释不清、恢复不顺”的回归。
+
+## 目标 / 非目标
+
+### Goals
+
+- 为 `$local-merge-flow` 明确本地 cleanup 决策树，覆盖无关脏工作区保留、隔离 merge worktree 回收、切回基线分支与 topic 分支删除。
+- 让 `本地收尾=完成/部分完成/未执行` 由可核验的 closeout gate 决定，而不是由 agent 手写解释。
+- 让 `$flow-continue` 能把“已本地合入但 cleanup 未完成”恢复成明确的 `Step 5L.4` cleanup 门禁，而不是重新回到 merge 授权或笼统说明。
+
+### Non-goals
+
+- 不把 `$pr-post-merge-cleanup` 抽成新的共享 cleanup 框架。
+- 不改 PR merge / remote branch cleanup 语义。
+- 不要求 agent 处理主人明确保留的无关脏文件内容本身。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `docs/specs/README.md` 与本规格文档。
+- 更新 `$local-merge-flow` 与共享 `Step 5L.3/5L.4` cleanup 契约。
+- 更新 `$flow-continue` 与 `/prompts:advance-flow` 的 local cleanup 恢复语义。
+- 新增 `skills/local-merge-flow/scripts/` 下的 closeout context / gate / tests。
+
+### Out of scope
+
+- 变更 `$pr-post-merge-cleanup` 现有 closeout gate。
+- 引入新的测试框架或新的 GitHub 状态字段。
+
+## 需求（Requirements）
+
+### MUST
+
+- 若当前 main worktree 存在与本次 local merge 无关的脏改动，且可通过隔离 worktree 完成 merge / cleanup，则 `$local-merge-flow` 不得仅因 `git status` 非空就阻断。
+- `cleanup_proof` 除现有基础字段外，必须新增固定语义字段：
+  - `dirty_worktree_policy=clean/preserved_unrelated/skipped_conflict/user_decision_required`
+  - `topic_branch_action=not_needed/deleted_safe/deleted_forced/skipped`
+  - `merge_worktree_status=not_applicable/removed/still_present/skipped`
+  - `pending_cleanup_action=none/switch_to_base/delete_topic_branch/remove_merge_worktree/ask_user`
+- `本地收尾=完成` 必须允许 `worktree_clean=no`，但仅限 `dirty_worktree_policy=preserved_unrelated` 且当前已回到 `base_branch`、topic 分支已回收、merge worktree 已回收、`pending_cleanup_action=none` 的场景。
+- topic 分支删除必须固定为：先尝试 `git branch -d`；若已确认该分支已合入目标基线、未被任何 worktree checkout、且失败原因只是“not fully merged”，则自动升级到 `git branch -D`。
+- 若 `本地合入状态=已合入` 且 `本地收尾!=完成`，恢复层必须把下一个门禁解释成 `Step 5L.4 cleanup` 的第一个未完成动作，而不是重新进入 merge proof 或泛化解释。
+
+### SHOULD
+
+- local closeout gate 的字段与命名应尽量贴近现有 PR closeout gate，减少 agent 切换上下文时的心智负担。
+- 回归测试至少覆盖：无关脏文件保留但收尾完成、需要切回基线分支、merge worktree 未回收。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 当主人在 `Step 5L Ready` 后批准“合并/收尾”，若当前主工作区存在无关脏改动：
+  - 先分类为 `preserved_unrelated` 或 `skipped_conflict`
+  - `preserved_unrelated` 时允许在隔离 merge worktree 完成合主干
+  - merge 后若普通 `git switch <base_branch>` 可成功，则回到基线分支并继续 cleanup
+  - 若切回会覆盖无关脏改动，记为 `pending_cleanup_action=switch_to_base`，并降级为 `本地收尾=部分完成`
+- 当本地 topic 分支已并入目标基线，但 `git branch -d` 因 squash/rebase 语义报“not fully merged”：
+  - 若该分支未被任何 worktree checkout，且本地分支头与已合入目标一致，自动执行 `git branch -D`
+  - `cleanup_proof.topic_branch_action` 记录为 `deleted_forced`
+- 当 merge worktree 仍在 `git worktree list` 中：
+  - gate 必须禁止 `本地收尾=完成`
+  - `pending_cleanup_action=remove_merge_worktree`
+
+### Edge cases / errors
+
+- 若普通 `git switch <base_branch>` 已被 Git 拒绝，不得猜测“应该也许能安全切”；必须保留当前工作区并降级为 `部分完成`。
+- 若 topic 分支仍被任一 worktree checkout，禁止直接 `git branch -D`；必须先把未释放的 worktree 作为 cleanup 缺口报告。
+- 若 merge worktree 路径未知，则 `merge_worktree_status` 只能是 `not_applicable`；不得伪装成 `removed`。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| `$local-merge-flow.cleanup_proof` | skill contract | internal | Modify | None | main-agent | `$local-merge-flow`, `$flow-continue` | 新增 closeout 决策字段 |
+| `local closeout gate/context` | script | internal | New | None | main-agent | `$local-merge-flow` | 以 live git 事实判定 `本地收尾` |
+
+### 契约文档（按 Kind 拆分）
+
+None
+
+## 验收标准（Acceptance Criteria）
+
+- Given 主工作区保留无关脏文件，且 merge / cleanup 可在隔离 worktree 完成 When agent 执行 local merge cleanup Then 只要当前已回到基线分支、topic 分支已回收、merge worktree 已回收，允许给出 `本地收尾=完成`。
+
+- Given topic 分支已经合入目标基线，`git branch -d` 仅因“not fully merged”失败 When agent 评估本地 cleanup Then 它应自动转为安全校验后的 `git branch -D`，而不是把该动作晚抛给主人。
+
+- Given `本地合入状态=已合入` 且 `本地收尾=部分完成` When `$flow-continue` 恢复流程 Then 它必须把下一门禁恢复为 `Step 5L.4 cleanup` 的第一个未完成动作。
+
+- Given merge worktree 仍存在于 `git worktree list` When closeout gate 评估 `cleanup_proof` Then 不得返回 `本地收尾=完成`。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: 新增 local closeout context / gate 单测
+- Integration tests: 回归执行既有 `pr-post-merge-cleanup` closeout tests，确保未破坏 PR cleanup 语义
+- E2E tests (if applicable): N/A
+
+### Quality checks
+
+- `python3 skills/local-merge-flow/scripts/test_closeout_context.py`
+- `python3 skills/local-merge-flow/scripts/test_closeout_gate.py`
+- `python3 skills/pr-post-merge-cleanup/scripts/test_closeout_context.py`
+- `python3 skills/pr-post-merge-cleanup/scripts/test_closeout_gate.py`
+- `git diff --check`
+
+## Visual Evidence
+
+## 方案概述（Approach, high-level）
+
+- 复用现有 PR closeout 的思路，但只在 `local-merge` 路径补一套轻量、明确的 gate。
+- 把“脏工作区是否允许完成 cleanup”从二元 clean/dirty 改成带语义的 policy，再由 gate 决定是否可完成。
+- 让恢复层把 `部分完成` 视为真实的 cleanup 门禁，而不是一次失败解释。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若后续又新增新的 local-merge prompt 入口但没同步这套规则，仍可能出现入口不一致。
+- 需要决策的问题：None
+- 假设：主人明确保留的无关脏文件不应阻止其余 cleanup 对象被完整回收。
+
+## 参考（References）
+
+- `skills/pr-post-merge-cleanup/SKILL.md`
+- `skills/pr-post-merge-cleanup/scripts/closeout_context.py`
+- `skills/pr-post-merge-cleanup/scripts/closeout_gate.py`

package/toolkit/skills/docs/vendor/dot-codex/specs/4zciv-pr-skill-diagnosis-thinning/HISTORY.md

@@ -0,0 +1,20 @@
+# PR 续推 skill 瘦身与诊断优先级收敛 演进历史（#4zciv）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- Superseded by `docs/specs/agent-instruction-architecture/SPEC.md`; this ID-prefixed directory remains historical evidence only.
+
+- `97e541d` fix(skill): tighten pr diagnosis routing
+- `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: `#4zciv`.