@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/skills/land/SKILL.md

@@ -0,0 +1,77 @@
+# Land
+
+Use this skill when a CO worker is shepherding an attached PR from review-complete into merge and final Linear closeout.
+This skill covers the `Merging` phase; use `skills/linear/SKILL.md` for Linear workpad, review, and state-transition rules.
+
+## When To Use
+
+- The Linear issue is in `Merging`.
+- The PR is approved or near-approved and needs active watch/resolve/merge handling.
+- The worker needs to keep ownership through merge completion instead of stopping at review handoff.
+
+## Preconditions
+
+- The PR is attached to the Linear issue.
+- Required implementation work is already complete.
+- Required validation and PR checks are green, or you are actively resolving the blockers that prevent green.
+- Unresolved actionable review threads are zero before merge.
+- The issue does not move to `Done` until the PR merge is complete.
+
+## Preferred Command
+
+Use the shipped repo merge loop first:
+
+```bash
+codex-orchestrator pr resolve-merge \
+  --pr "$PR_NUMBER" \
+  --quiet-minutes 15
+```
+
+Add `--auto-merge` only when the PR is approved, mergeable, and ready to land without more author work.
+
+Repo-local fallback:
+
+```bash
+npm run pr:resolve-merge -- \
+  --pr "$PR_NUMBER" \
+  --quiet-minutes 15
+```
+
+## Merge Loop
+
+1. Confirm the PR is not draft and is not labeled `do not merge`.
+2. Confirm unresolved actionable review threads are zero.
+3. Confirm required checks are green or keep shepherding until they are.
+4. If merge conflicts, failing checks, or new review feedback appear, handle them immediately. If the PR needs more code changes, resume the issue through `Rework` rather than pretending merge is still blocked-only.
+5. Keep the same PR, branch, and workpad current while monitoring the merge loop.
+6. Once the PR merges, reconcile the shared local root checkout before `Done`.
+
+## Shared Root Reconciliation
+
+After the PR merges and before moving the issue to `Done`:
+
+1. Inspect the shared local root checkout, not the per-issue worktree. This is the repo checkout that owns `.workspaces/`.
+2. Record the before state in the same workpad closeout using `git -C "$SHARED_ROOT" status --short --branch`.
+3. Only when that checkout is on `main` and clean, run:
+
+```bash
+git -C "$SHARED_ROOT" fetch origin refs/heads/main:refs/remotes/origin/main
+git -C "$SHARED_ROOT" merge --ff-only origin/main
+```
+
+4. Record the after state with the same `git status --short --branch` command.
+5. If the checkout is dirty, detached, on another branch, or otherwise unsafe to mutate, do not force a sync. Leave it untouched and record the explicit skip reason in the same workpad closeout.
+6. Do not mutate the issue worktree or other active workspaces as part of this step.
+
+## Linear Closeout
+
+After the PR merges, move the issue to `Done` with the Linear helper:
+
+```bash
+codex-orchestrator linear transition \
+  --issue-id "$ISSUE_ID" \
+  --state "Done" \
+  --format json
+```
+
+Do not transition to `Done` before the merge has actually completed and the shared-root reconciliation result is recorded.

package/skills/linear/SKILL.md

@@ -0,0 +1,255 @@
+# Linear
+
+Use this skill when a CO worker or operator needs to read or mutate Linear through the repo's worker-owned helper surface.
+Pair it with `skills/land/SKILL.md` once an attached PR enters the merge shepherding phase.
+
+## Commands
+
+Use the packaged CLI when available:
+
+```bash
+codex-orchestrator linear <subcommand> --format json ...
+```
+
+Inside provider-worker runs, the exact helper command is usually:
+
+```bash
+node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/bin/codex-orchestrator.js" linear <subcommand> --format json ...
+```
+
+## Issue Context
+
+Read the current issue state, team states, comments, attachments, and active workpad comment:
+
+```bash
+codex-orchestrator linear issue-context \
+  --issue-id "$ISSUE_ID" \
+  --format json
+```
+
+## Workpad
+
+Maintain exactly one persistent `## Codex Workpad` comment. Reuse the existing comment when present; do not create duplicate progress comments.
+
+```bash
+codex-orchestrator linear upsert-workpad \
+  --issue-id "$ISSUE_ID" \
+  --body-file /tmp/workpad.md \
+  --format json
+```
+
+The body must contain the `## Codex Workpad` marker.
+
+When a lane needs a fresh screenshot on macOS, capture it through the repo-owned helper first:
+
+```bash
+codex-orchestrator linear screenshot-proof \
+  --issue-id "$ISSUE_ID" \
+  --output /absolute/path/to/proof.png \
+  --format json
+```
+
+Use `capture.embed_markdown` from that JSON directly in the workpad body. The helper keeps local capture outcomes separate from later Linear upload/embed outcomes.
+
+When a screenshot already exists locally, embed it in the workpad body as markdown image syntax that points at that file (prefer `file:///absolute/path/to/proof.png`; use `<file:///absolute/path/to/proof (1).png>` when the path contains spaces or parentheses). The helper uploads local PNG/JPG/JPEG/WEBP/GIF image references to Linear and rewrites them to Linear-hosted asset URLs before the workpad comment mutation lands. Use runtime-proof or external URLs only when reviewer-visible external proof is acceptable.
+
+Keep the workpad body in this exact top-level order, with every section non-empty:
+
+```md
+## Codex Workpad
+
+### Environment / Workspace Stamp
+### Plan
+### Acceptance Criteria
+### Validation
+### Notes
+```
+
+`Acceptance Criteria` and `Validation` must contain non-empty checkbox list items (`- [ ] task` / `- [x] task`).
+`Environment / Workspace Stamp`, `Plan`, and `Notes` may stay free-form as long as they remain non-empty.
+
+If the ticket includes `Validation`, `Test Plan`, or `Testing` requirements, mirror them in the workpad `Acceptance Criteria` and `Validation` sections.
+
+Delete the current unresolved workpad comment when a Symphony-style `Rework` reset requires a fresh attempt:
+
+```bash
+codex-orchestrator linear delete-workpad \
+  --issue-id "$ISSUE_ID" \
+  --format json
+```
+
+## State Transition
+
+Move the issue by state name. The helper resolves the target `stateId` from the issue's team workflow states.
+Use `Human Review` when the team exposes that exact state and `In Review` when the live team uses that review-handoff alias.
+
+```bash
+codex-orchestrator linear transition \
+  --issue-id "$ISSUE_ID" \
+  --state "Human Review" \
+  --format json
+```
+
+## PR Attachment
+
+Attach a GitHub PR to the issue. The helper prefers the GitHub-specific attachment mutation and falls back to a plain URL attachment when needed.
+
+```bash
+codex-orchestrator linear attach-pr \
+  --issue-id "$ISSUE_ID" \
+  --url "$PR_URL" \
+  --title "$PR_TITLE" \
+  --format json
+```
+
+## Parallelization Decision
+
+Ordinary active provider-worker turns are parallel-first where safe. Before recording `linear parallelization`, write a pre-turn decomposition matrix in the workpad or notes. The matrix must include candidate child lanes, file/phase scope, dependencies, overlap risk, expected validation artifact, child-lane owner, and cap-slot use.
+
+```bash
+codex-orchestrator linear parallelization \
+  --issue-id "$ISSUE_ID" \
+  --decision parallelize_now \
+  --reason independent_scope_available \
+  --summary "matrix found a safe docs/test child lane; cap 0/2 -> 1/2" \
+  --format json
+```
+
+Use `parallelize_now` when the matrix contains at least one safe independent child-lane candidate. Do not use `stay_serial` while a safe independent candidate remains unless the cap is exhausted. When `single_bounded_change` is the reason, the summary must include labeled per-slice evidence: `docs: ...; test: ...; research: ...; review: ...`.
+
+The same-issue child-lane cap is `2`. It counts active, pending, and unaccepted child lanes and does not bypass provider admission constraints from CO-125. If the cap is exhausted, do not launch another lane; record `stay_serial` with reason `existing_child_lane_active` and include labeled `cap_exhausted:` evidence in the summary. Stale in-flight accept claims older than 30 minutes, and legacy in-flight claims without timestamps, are recoverable and do not consume cap slots.
+
+Parent ownership remains strict. While a child lane is active, the parent avoids delegated files/phases. If parent edits collide with delegated scope, invalidate or reject the child lane, or record explicit rebase/collision reasoning before accepting the child patch.
+
+## Runtime Proof
+
+For app-touching lanes, use the runtime-proof helper to turn permit policy into an explicit screenshot / external-link / video posture and, when allowed, generate reviewer-usable workpad and PR markdown. This is the reviewer-URL path, not the local macOS capture path.
+
+Inspect the current permit posture first:
+
+```bash
+codex-orchestrator linear runtime-proof \
+  --issue-id "$ISSUE_ID" \
+  --origin "https://app.example.com" \
+  --format json
+```
+
+Generate handoff content once you have a reviewer-visible proof URL:
+
+```bash
+codex-orchestrator linear runtime-proof \
+  --issue-id "$ISSUE_ID" \
+  --origin "https://app.example.com" \
+  --kind screenshot \
+  --proof-url "https://review-assets.example.com/co-8-dashboard.png" \
+  --title "Dashboard after launch-app validation" \
+  --summary "Signed-in dashboard state used for review handoff." \
+  --format json
+```
+
+Paste `handoff.workpad_markdown` into the workpad and `handoff.pr_markdown` into the PR description or a review-ready PR comment.
+The helper fails closed when:
+- the permit file is unreadable
+- the origin is not approved
+- the requested proof kind is blocked
+- the proof URL is loopback or otherwise local-only
+- only a local file path exists instead of a reviewer-visible proof URL
+
+## Pre-Review Drain
+
+After opening or updating a PR, run the shipped bounded automated-feedback drain before moving the issue to `Human Review` or `In Review`.
+
+```bash
+codex-orchestrator pr ready-review \
+  --pr "$PR_NUMBER" \
+  --quiet-minutes 15
+```
+
+`ready-review` waits for green gating signals plus a bounded quiet window, treats `REVIEW_REQUIRED` as informational for review handoff, and exits non-zero when the author still needs to address actionable blockers.
+
+## Follow-Up Issues
+
+When you discover a meaningful out-of-scope improvement, create a separate same-project follow-up issue in `Backlog` instead of expanding the current issue.
+The helper always adds a `related` relation to the source issue and can also add blocker linkage when the follow-up depends on the source issue landing first.
+The stronger contract also preserves:
+- `Intent Checksum`: exact wording, protected terms, and nearby wrong interpretations to reject
+- `Non-Goals`
+- `Not Done If`
+- required `Parity / Alignment Matrix` when `--parity-lane` marks a parity/alignment follow-up
+- deterministic `Immediate Traceability` back to the repo packet expected before the follow-up leaves `Backlog`
+
+```bash
+codex-orchestrator linear create-follow-up \
+  --issue-id "$ISSUE_ID" \
+  --title "Follow-up title" \
+  --description-file /tmp/follow-up-description.md \
+  --intent-checksum-file /tmp/follow-up-intent-checksum.md \
+  --non-goals-file /tmp/follow-up-non-goals.md \
+  --not-done-if-file /tmp/follow-up-not-done-if.md \
+  --acceptance-criteria-file /tmp/follow-up-acceptance.md \
+  --parity-lane \
+  --parity-matrix-file /tmp/follow-up-parity-matrix.md \
+  --blocked-by-source \
+  --format json
+```
+
+For recurring baseline debt, prefer canonical-owner reuse/update over a fresh issue. Inspect the `candidate_cohorts` emitted by machine output such as `docs:freshness:maintain`, choose the intended cohort, and pass that cohort's exact `canonical_owner_key`; the helper reuses only open same-team same-project issues stamped with the exact marker and treats `Done`, `Duplicate`, and `Cancelled`/`Canceled` issues as evidence only.
+
+```bash
+jq '.candidate_cohorts[] | {id, status, canonical_owner_key, sample_paths}' out/<task-id>/docs-freshness-maintenance.json
+# After selecting the intended cohort, replace <cohort-id> with its id.
+canonical_owner_key="$(jq -er '.candidate_cohorts[] | select(.id == "<cohort-id>") | .canonical_owner_key // empty' out/<task-id>/docs-freshness-maintenance.json)"
+codex-orchestrator linear create-follow-up \
+  --issue-id "$ISSUE_ID" \
+  --title "Recurring baseline owner" \
+  --description-file /tmp/follow-up-description.md \
+  --intent-checksum-file /tmp/follow-up-intent-checksum.md \
+  --non-goals-file /tmp/follow-up-non-goals.md \
+  --not-done-if-file /tmp/follow-up-not-done-if.md \
+  --acceptance-criteria-file /tmp/follow-up-acceptance.md \
+  --canonical-owner-key "$canonical_owner_key" \
+  --format json
+```
+
+## Workflow Notes
+
+- Move `Todo` or the live team's equivalent queued state (for CO, `Ready`) to the actual started state before active coding when the issue is unblocked.
+- Use the Linear issue id, not the human identifier, for helper commands.
+- When you discover a meaningful out-of-scope improvement, use `create-follow-up` so the issue stays in the same project, starts in `Backlog` when newly created, records intent checksum/non-goals/not-done-if, requires a parity matrix for parity/alignment lanes, and returns the reused or created follow-up identifier/URL for workpad references.
+- For recurring baseline debt, pass the deterministic `--canonical-owner-key` from machine output before creating follow-ups. Do not file a fresh issue when an open same-team same-project owner is already stamped with that exact marker.
+- Treat `CODEX_ORCHESTRATOR_REPO_CONFIG_PATH` and `CODEX_ORCHESTRATOR_PACKAGE_ROOT` as provider-lane-only overrides. Child streams and repo-local validation/test subprocesses should strip them unless the subprocess explicitly needs provider snapshot/package-root behavior.
+- Prefer an installed global `linear` skill when available, and fall back to this bundled `skills/linear/SKILL.md` copy only when no global skill is installed.
+- Keep exactly one active `## Codex Workpad` comment current. Refresh it after each meaningful milestone, immediately before review or merge handoffs, after rework, and after merge completion. Final closeout stays in the same workpad comment. Do not create duplicate progress or terminal summary comments.
+- Always read `issue-context` before any transition so you use the team's actual workflow state names.
+- Attach the PR before handing off to `Human Review` or the live-team alias `In Review`.
+- In provider-worker issue workspaces, audited `linear child-stream` and `linear child-lane` runs record manifests under the workspace-scoped artifact root for that issue workspace, for example `.runs/linear-<uuid>/cli/<runId>/manifest.json`.
+- Treat those workspace-scoped manifests as the intended delegation evidence path.
+- Do not reach for blanket `DELEGATION_GUARD_OVERRIDE_REASON` text when valid child evidence already exists in the workspace artifact tree.
+- If a PR is already attached, run a full PR feedback sweep before any new implementation work:
+  - check top-level PR comments
+  - check inline review comments and unresolved review threads
+  - check review summaries / decisions
+  - resolve each actionable item or post explicit, justified pushback
+- For app-touching lanes, use `runtime-proof` before review handoff so the workpad and PR carry reviewer-usable proof links instead of local-only artifact paths. Add `--reachability-mode dns-public` only when worker-local DNS public-resolution evidence is worth the extra environment-dependent check.
+- Use `screenshot-proof` when you still need to create a local screenshot artifact on macOS. For an existing screenshot, direct local-file workpad embedding is the right path. `runtime-proof` is for cases where reviewers need an external proof URL rather than a workpad-embedded local capture.
+- After opening or updating a PR, run `codex-orchestrator pr ready-review --pr "$PR_NUMBER" --quiet-minutes <window>` and keep the issue out of review until that bounded automated-feedback drain exits cleanly or reveals a blocker you handle explicitly.
+- Treat standalone review plus elegance review as a required pre-review-handoff gate for any non-trivial diff before opening a new PR for review handoff, before updating an already attached PR for handoff, and before transitioning the issue to `Human Review` or `In Review`.
+- Use the repo heuristic for non-trivial work: about 2+ changed files or about 40+ changed lines, unless you record an explicit skip justification in the workpad.
+- Run the standalone review first. When manifest-backed evidence matters, use the wrapper-led review path by default; if review tooling is unavailable or stalls without a concrete verdict, do a manual correctness/regressions/missing-tests review plus a manual elegance checklist and record that fallback instead of stalling.
+- After standalone-review findings are addressed, run an explicit elegance/minimality pass before handoff and record any kept complexity or fallback.
+- When `review/telemetry.json` reports `status: succeeded` with `review_outcome: bounded-success` (or an older succeeded payload with a preserved `termination_boundary`), record it in the workpad and validation notes as successful bounded review completion, not as a blocker or generic quiet-tail failure.
+- Treat `review_outcome: failed-boundary` (or older failed telemetry with a non-null `termination_boundary`) as an explicit review-wrapper boundary failure. Treat `failed-other` as a failed review command without a classified boundary, not as proof of wrapper breakage, and keep unrelated validation, CI, or merge blockers labeled separately instead of blaming the review wrapper.
+- Before handing off to `Human Review` or `In Review`, the completion bar is:
+  - required validation is green
+  - `docs-review` and `implementation-gate` freshness status comes from the machine-readable `docs:freshness:maintain` decision; cite `pass_with_owned_rolling_debt` only when current diff/task-packet paths are clean and the owner issue/cap/window evidence is present
+  - actionable PR feedback is handled or explicitly pushed back
+  - the latest `origin/main` is merged into the branch
+  - PR checks are green
+  - the `pr ready-review` drain is clean
+  - the workpad is refreshed to match the current implementation and remaining risks
+  - the workpad records the review goal, findings or fallback, and final clean or justified status for the standalone/elegance gate
+- `Human Review` and `In Review` are review handoff states. Do not keep coding there; refresh the workpad if needed, record the handoff clearly, and end the turn instead of polling inside the same run.
+- `Rework` means a full reset on the same issue. Close the previous PR, delete the old workpad, create a fresh branch from `origin/main`, create a new bootstrap workpad, then execute end to end again before handing the issue back to `Human Review` or `In Review`.
+- `Merging` means the issue is still active. Follow `skills/land/SKILL.md` to shepherd the PR through checks, conflicts, approvals, and merge completion.
+- In `Merging`, final closeout must also inspect the shared local root checkout, record before/after `git status --short --branch` output in the same workpad comment, refresh the local `origin/main` tracking ref from remote `main`, and only then fast-forward that checkout to `origin/main` when it is on clean `main`; otherwise, record an explicit skip reason and leave the checkout untouched before `Done`.
+- Only move the issue to `Done` after the PR is actually merged and the shared-root closeout result is recorded. `Merging` and `Rework` are active workflow states only when the team exposes them.

package/skills/release/SKILL.md

@@ -13,7 +13,23 @@ If a global `release` skill is installed, prefer that and fall back to this bund
 - Never publish from an unmerged branch: release tags must point at `main`.
 - Release tags must be **signed annotated tags** (`git tag -s vX.Y.Z -m "vX.Y.Z"`).
 - Confirm `gh auth status` is OK before any PR/release steps.
+- Release is blocked unless commit/tag signing is configured on the release machine.
 - Prefer non-interactive commands; avoid anything that can hang on prompts.
+- Run the full release validation floor before tagging:
+  - `node scripts/delegation-guard.mjs`
+  - `node scripts/spec-guard.mjs --dry-run`
+  - `npm run build`
+  - `npm run lint`
+  - `npm run test`
+  - `npm run docs:check`
+  - `npm run docs:freshness`
+  - `npm run repo:stewardship`
+  - `node scripts/diff-budget.mjs`
+  - `NOTES="Goal: ... | Summary: ... | Risks: ... | Questions (optional): ..." npm run review`
+  - `npm run pack:audit`
+  - `npm run pack:smoke`
+- Validate the package artifact from a clean `dist/` before tagging: `npm run clean:dist && npm run build`, then `npm run pack:audit` and `npm run pack:smoke`.
+- Release/RC lanes should also run the full matrix: `npm run build:all`, `npm run test:adapters`, `npm run test:evaluation`, and `npm run eval:test` when fixtures/optional deps exist.
 - If any check fails (Core Lane, Cloud Canary, CodeRabbit, release workflow), stop and fix before proceeding.
 
 ## Workflow
@@ -25,8 +41,12 @@ gh auth status -h github.com
 git status -sb
 git checkout main
 git pull --ff-only
+git config commit.gpgsign
+git config tag.gpgSign
 ```
 
+If signing is not configured, stop and fix the release machine before continuing.
+
 ### 2) Version bump PR
 
 Pick a version (usually patch): `0.1.N+1`.
@@ -66,7 +86,21 @@ PR_NUMBER="$(gh pr view --json number --jq .number)"
 codex-orchestrator pr resolve-merge --pr "$PR_NUMBER" --auto-merge --delete-branch --quiet-minutes 1 --interval-seconds 20
 ```
 
-### 3) Create signed tag + push
+If bundled skills changed, update the release notes copy before tagging:
+- Keep the bundled-skill highlight under **Overview**. The workflow promotes generated **Overview** and **Bug Fixes** into top-level release-note sections and leaves **Documentation** under **Full Changelog**.
+- Include `codex-orchestrator skills install --force`.
+- Include the docs link `docs/skills-release.md`.
+- If you want a one-shot manual overview narrative, put it in the signed annotated tag body, for example `git tag -s "$TAG" -m "$TAG" -m "Release overview text..."`. Do not use a committed overview file for this path.
+
+### 3) Validate the package artifact
+
+```bash
+npm run clean:dist && npm run build
+npm run pack:audit
+npm run pack:smoke
+```
+
+### 4) Create signed tag + push
 
 ```bash
 git checkout main
@@ -78,7 +112,9 @@ git tag -v "$TAG"
 git push origin "$TAG"
 ```
 
-### 4) Watch the release workflow + confirm npm publish
+If the tag-triggered workflow needs a manual rerun, use `workflow_dispatch` with `inputs.tag="$TAG"`. Manual dispatch still requires an existing signed tag; it is not a substitute for creating the tag.
+
+### 5) Watch the release workflow + confirm npm publish
 
 ```bash
 TAG_SHA="$(git rev-list -n 1 "$TAG")"
@@ -108,7 +144,15 @@ npm view @kbediako/codex-orchestrator version
 gh release view "v${VERSION}" --json url,assets --jq '{url: .url, assets: (.assets|map(.name))}'
 ```
 
-### 5) Update global + downstream smoke
+Current workflow contract in `.github/workflows/release.yml`:
+- CI tag verification requires exactly one signer secret: `RELEASE_SIGNING_PUBLIC_KEYS` (GPG) or `RELEASE_SIGNING_ALLOWED_SIGNERS` (SSH).
+- The workflow rejects lightweight or unsigned tags and blocks tag/package version mismatches.
+- Stable tags publish to npm `latest`; prerelease tags publish with a dist-tag derived from the prerelease label and create a GitHub prerelease.
+- Generated release notes keep **Release Overview**, **Bug Fixes**, and **Full Changelog** sections; the signed annotated tag body overrides the Overview section when present.
+- Publish prefers npm trusted publishing (OIDC with `--provenance`) and only falls back to `NPM_TOKEN` when OIDC fails.
+- If `NPM_TOKEN` fallback is used, it must be an npm automation token, not an OTP-gated token.
+
+### 6) Update global + downstream smoke
 
 ```bash
 npm i -g @kbediako/codex-orchestrator@"${VERSION}"

package/skills/standalone-review/SKILL.md

@@ -27,6 +27,8 @@ If review execution is blocked, record why in task notes, then do manual diff re
 Compatibility guard (current Codex CLI behavior):
 - Do not combine `--uncommitted`, `--base`, or `--commit` with a custom prompt argument.
 - Use diff-scoped review without prompt, or prompt-only review without scope flags.
+- Wrapper note: `codex-orchestrator review` / `npm run review` still saves the full review prompt artifact for scoped runs, but explicit wrapper scope flags launch `codex review` without any prompt argument because current Codex CLI still treats stdin (`-`) as `[PROMPT]`; reviewer-visible scoped context first rides on bounded `--title` transport, and if Codex rejects a synthesized scoped title the wrapper retries the same explicit scope without `--title` and falls back to artifact-only context.
+- Scoped surface limit: explicit wrapper scope flags support only the default `diff` surface at the actual Codex layer; `--surface audit|architecture` requires an unscoped prompt-capable review.
 
 Uncommitted diff:
 ```
@@ -70,8 +72,11 @@ codex review "Focus on correctness, regressions, edge cases; list missing tests.
 - If you need manifest evidence, use the review wrapper command:
   `TASK=<task-id> NOTES="Goal: ... | Summary: ... | Risks: ... | Questions (optional): ..." codex-orchestrator review --manifest <path>`
 - Repo alias (same behavior in this repo): `npm run review -- --manifest <path>`
-- In non-interactive environments, add `FORCE_CODEX_REVIEW=1` as needed.
+- In non-interactive environments, direct/manual wrapper runs stay handoff-only unless you add `FORCE_CODEX_REVIEW=1`.
+- `docs-review` and `implementation-gate` already set `FORCE_CODEX_REVIEW=1`; `docs-relevance-advisory` intentionally keeps it cleared; the `provider-linear-worker` pipeline exports `CODEX_REVIEW_NON_INTERACTIVE=1` and `FORCE_CODEX_REVIEW=1`, so its closeout review executes before `Human Review` / `In Review`.
 - In non-interactive environments, prefer the wrapper over raw `codex review`; it preserves evidence paths, delegation toggles, and optional runtime guardrails (`CODEX_REVIEW_TIMEOUT_SECONDS`, `CODEX_REVIEW_STALL_TIMEOUT_SECONDS`).
+- For explicit wrapper scope flags (`--uncommitted`, `--base`, `--commit`), the saved prompt artifact remains available under `review/prompt.txt`, but the actual Codex launch still omits any prompt argument because current Codex CLI treats stdin (`-`) as `[PROMPT]`; reviewer-visible scoped context therefore rides on bounded `--title` transport.
+- For those explicit scoped runs, `--surface audit` and `--surface architecture` must fail fast and be rerun without explicit scope flags, because the requested full prompt context cannot reach Codex.
 
 ## Expected outputs
 - A prioritized list of findings.

package/templates/README.md

@@ -14,8 +14,10 @@ repository and will not overwrite files unless you pass --force.
 Current codex template payload includes:
 - `AGENTS.md`
 - `mcp-client.json`
-- `.codex/config.toml` plus `.codex/agents/*` role files
+- the consumer repo root .codex/config.toml plus .codex/agents/* role files (copied from `templates/codex/.codex/*`)
+- provider onboarding examples under `.codex/providers/`
 
 Next steps (recommended):
-  codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
+  codex-orchestrator delegation setup --yes --repo /path/to/repo
+  codex-orchestrator delegation cleanup-stale --yes   # when stale delegate-server processes build up
   codex-orchestrator codex setup   # optional: CO-managed Codex CLI (activate only when needed via CODEX_CLI_USE_MANAGED=1)

package/templates/codex/.codex/agents/awaiter-high.toml

@@ -1,7 +1,7 @@
 # Synced from codex-rs/core/src/agent/builtins/awaiter.toml (0.105.0)
-# with CO override to use gpt-5.3-codex at high reasoning.
+# with CO override to use gpt-5.4 at high reasoning.
 background_terminal_max_timeout = 3600000
-model = "gpt-5.3-codex"
+model = "gpt-5.4"
 model_reasoning_effort = "high"
 developer_instructions="""You are an awaiter.
 Your role is to await the completion of a specific command or task and report its status only when it is finished.

package/templates/codex/.codex/agents/worker-complex.toml

@@ -1,2 +1,2 @@
-model = "gpt-5.3-codex"
+model = "gpt-5.4"
 model_reasoning_effort = "xhigh"

package/templates/codex/.codex/config.toml

@@ -1,13 +1,12 @@
-model = "gpt-5.3-codex"
+model = "gpt-5.4"
+review_model = "gpt-5.4"
 model_reasoning_effort = "xhigh"
 
 [agents]
 max_threads = 12
-max_depth = 4
-max_spawn_depth = 4
 
 [agents.explorer_fast]
-description = "Fast explorer (spark text-only)."
+description = "Fast explorer (spark file/codebase search only)."
 config_file = "./agents/explorer-fast.toml"
 
 [agents.worker_complex]

package/templates/codex/.codex/providers/README.md

@@ -0,0 +1,13 @@
+# Provider Examples
+
+These files are seeded by `codex-orchestrator init codex`.
+
+- `provider.env.example` is the once-per-machine or secret-backed env contract.
+- `control.example.json` is the provider policy example for `dispatch_pilot` and `transport_mutating_controls`.
+
+Recommended flow:
+
+1. Copy values from `provider.env.example` into your real secret or env management system.
+2. Copy the `feature_toggles` blocks you need from `control.example.json` into your run-local control seed.
+3. Verify with `codex-orchestrator doctor --format json`.
+4. Start the host with `codex-orchestrator control-host --format json` and keep it running in a dedicated terminal during provider smoke.

package/templates/codex/.codex/providers/control.example.json

@@ -0,0 +1,18 @@
+{
+  "feature_toggles": {
+    "dispatch_pilot": {
+      "enabled": true,
+      "source": {
+        "provider": "linear",
+        "live": true,
+        "workspace_id": "workspace-id",
+        "team_id": "team-id",
+        "project_id": "project-id"
+      }
+    },
+    "transport_mutating_controls": {
+      "enabled": true,
+      "allowed_transports": ["telegram"]
+    }
+  }
+}

package/templates/codex/.codex/providers/provider.env.example

@@ -0,0 +1,15 @@
+# Linear
+CO_LINEAR_API_TOKEN=
+CO_LINEAR_WORKSPACE_ID=
+CO_LINEAR_TEAM_ID=
+CO_LINEAR_PROJECT_ID=
+CO_LINEAR_WEBHOOK_SECRET=
+
+# Telegram
+CO_TELEGRAM_POLLING_ENABLED=false
+CO_TELEGRAM_BOT_TOKEN=
+CO_TELEGRAM_ALLOWED_CHAT_IDS=
+CO_TELEGRAM_ENABLE_MUTATIONS=false
+CO_TELEGRAM_POLL_INTERVAL_MS=1000
+CO_TELEGRAM_PUSH_ENABLED=false
+CO_TELEGRAM_PUSH_INTERVAL_MS=30000

package/templates/codex/AGENTS.md

@@ -1,10 +1,11 @@
-<!-- codex:instruction-stamp 3599cb54f155d730dfc088b0ee6792ebe91e701cc288930064d73eae562b829a -->
+<!-- codex:instruction-stamp 347a0465abbf61f5c79a8012b466e908cd49d9a33a210cfaa4be693de106b6e0 -->
 # Agent Instructions (Template)
 
 ## Orchestrator-first workflow
 - Use `codex-orchestrator` pipelines for planning, implementation, validation, and review.
 - Default to `docs-review` before implementation and `implementation-gate` after code changes.
 - Use `docs-relevance-advisory` when you need semantic docs relevance signal without hard-gate behavior.
+- Local appserver remains the expected default runtime path.
 - Prefer cloud mode when runs are long-running/parallel and cloud prerequisites are ready.
 - Before cloud mode, verify branch availability, non-interactive setup commands, and required secrets/variables; if missing, run in local `mcp` mode and record why.
 - Before implementation, run a standalone review of the task/spec against the user’s intent and record the approval in the spec + checklist notes.
@@ -53,15 +54,21 @@
 - Built-in roles are `default`, `explorer`, `worker`, and `awaiter`; `researcher` is user-defined.
 - `spawn_agent` defaults to `default` when `agent_type` is omitted; always set `agent_type` explicitly.
 - For symbolic collab runs, prefix spawned prompts with `[agent_type:<role>]` on line one so role intent is auditable from JSONL/manifests.
-- Keep top-level defaults on latest codex by setting `model = "gpt-5.3-codex"` in `~/.codex/config.toml`.
+- CO-local ChatGPT-auth/appserver model posture is `gpt-5.5` / `xhigh` on Codex CLI `0.125.0` when live access smoke passes; release-facing cloud/downstream pins stay on the explicit promoted candidate recorded in `docs/guides/codex-version-policy.md`.
+- `0.124.0` CO posture evidence confirmed `codex exec` prompt-plus-stdin support, `codex login --device-auth`, `codex review --help` exposing `[PROMPT]` alongside scoped review flags, packaged `gpt-5.4` `xhigh` fallback defaults, and a post-build runtime-mode canary pass.
+- Current model posture is `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions; keep `explorer_fast` on `gpt-5.3-codex-spark` for file/codebase search only.
+- Portable generated defaults still keep `model = "gpt-5.4"` and `model_reasoning_effort = "xhigh"` as fallback values in `~/.codex/config.toml`; operators should use `gpt-5.5` locally when access smoke passes.
+- Use `gpt-5.5` for delegated/review surfaces after access smoke validates current ChatGPT-auth/appserver availability.
+- Caveat: local model availability can vary by account; keep `gpt-5.4` only as the fallback generated default because it remains the app-server `isDefault`.
+- CO-352 catalog caveat: local `0.125.0` live catalog lists `gpt-5.3-codex-spark`, but bundled `0.125.0` catalog does not, so downstream/no-network `explorer_fast` file/codebase-search-only posture remains unchanged.
 - Set `model_reasoning_effort` to at least `high` (CO default: `xhigh`) so spawned agents inherit high reasoning unless role overrides change it.
-- Built-in `explorer` inherits top-level model defaults unless you attach a `config_file`.
-- Spark caveat: `gpt-5.3-codex-spark` is text-only.
+- Built-in `explorer` inherits top-level model defaults unless you attach a `config_file`; keep `explorer_fast` as the only explicit `gpt-5.3-codex-spark` exception for file/codebase search only.
+- Spark caveat: `gpt-5.3-codex-spark` is file/codebase search only.
 - Keep RLM/collab built-ins-first by default; add custom specialist roles only when there is measured value, clear ownership, and validation evidence.
-- Use `[agents] max_threads = 12` with `max_depth = 4` and `max_spawn_depth = 4` as the default multi-agent baseline.
-- Keep fallback usage explicit and rare: `8/2/2` for constrained/high-risk lanes, `6/1/1` only as break-glass.
-- Add an explicit `worker_complex` role (`gpt-5.3-codex`, `xhigh`) for high-risk implementation streams.
-- Use `codex-orchestrator doctor` as an advisory drift check for Codex defaults; remediate additively via `codex-orchestrator codex defaults --yes`.
+- For normal `features.multi_agent=true` and older Codex behavior, use `[agents] max_threads = 12` as the seeded baseline. For Codex CLI `0.125+` with `features.multi_agent_v2=true`, do not write or recommend `agents.max_threads`; upstream rejects the key, so doctor/default setup must omit it. Keep explicit `max_depth = 4` only when your local Codex parser accepts it, and treat `max_spawn_depth` as a legacy local override rather than current baseline guidance; preserve any intentional constrained caps instead of resetting them.
+- Keep fallback usage explicit and rare, and only for v1/older configs that still accept thread/depth caps: `8/2` for constrained/high-risk lanes, legacy `6/1/1` only as break-glass when an older parser/runtime still consumes spawn-depth caps.
+- Add an explicit `worker_complex` role (`gpt-5.5`, `xhigh` for current CO-local ChatGPT-auth/appserver work; `gpt-5.4`, `xhigh` only for portable fallback surfaces) for high-risk implementation streams.
+- Use `codex-orchestrator doctor` as an advisory drift check for Codex defaults; remediate additively via `codex-orchestrator codex defaults --yes` for portable fallback defaults or `codex-orchestrator codex defaults --auth-scope chatgpt --yes` after live access smoke, with exact prior CO-managed role baselines auto-migrated to the access-verified current ChatGPT-auth posture while preserving unrelated local customization and the `multi_agent_v2` rule that omits `agents.max_threads`.
 
 ## Completion discipline (patience-first)
 - Wait/poll for terminal state on long-running operations (CI checks, reviews, cloud jobs, orchestrator runs) before reporting completion.

package/templates/codex/mcp-client.json

@@ -2,7 +2,11 @@
   "templateVersion": 1,
   "mcpServers": {
     "codex-orchestrator": {
-      "command": "codex-orchestrator mcp serve"
+      "command": "codex-orchestrator",
+      "args": [
+        "mcp",
+        "serve"
+      ]
     }
   }
 }