forge-orkes 0.37.0 → 0.41.0

package/bin/create-forge.js

@@ -68,7 +68,7 @@ function compareVersions(a, b) {
 }
 
 // Template-only: reference templates Forge controls
-const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations'];
+const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations', '.forge/adapters'];
 
 // Settings file gets smart-merge (overwrite forge.* keys, preserve user hooks)
 const SETTINGS_FILE = '.claude/settings.json';
@@ -357,6 +357,9 @@ async function install() {
   }
 
   console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
+
+  // Presence-gated: if a Codex adapter is present, note it may need regeneration.
+  noticeCodexAdapter();
 }
 
 /**
@@ -652,6 +655,68 @@ async function upgrade() {
   // Pass the version captured BEFORE upgradeSettings() stamped the new one, so the
   // migration range is (installed, source] against the freshly-synced guides.
   runPostUpgradeMigrationChecks(installedVersion);
+
+  // Presence-gated advisories (no generation, no rebase — notices only).
+  noticeCodexAdapter();
+  noticeWorktreeLag();
+}
+
+/**
+ * Presence-gated Codex-adapter staleness notice. The bin has no LLM, so it can
+ * only NOTICE that a Codex adapter (.agents/ / .codex/) may be stale after a
+ * .claude/ sync and point to the regeneration route (/upgrading Step 4b). It
+ * never generates, never writes .agents/, never adds .agents to
+ * FRAMEWORK_OWNED_DIRS. Silent when no Codex adapter is present.
+ */
+function noticeCodexAdapter() {
+  const hasCodex =
+    fs.existsSync(path.join(targetDir, '.agents')) ||
+    fs.existsSync(path.join(targetDir, '.codex'));
+  if (!hasCodex) return;
+  console.log('  Codex adapter detected (.agents/ / .codex/).');
+  console.log('    It may now be stale relative to the .claude/ source just synced.');
+  console.log('    This installer does not regenerate it (no LLM). To refresh it,');
+  console.log('    run the `/upgrading` skill — its Codex step offers regeneration');
+  console.log('    from .forge/adapters/codex-generation.md.\n');
+}
+
+/**
+ * Presence-gated worktree-lag notice (paired with /upgrading Step 8). An upgrade
+ * run touches only this checkout; live forge/m-* worktrees keep their
+ * branch-point framework files until rebased. The bin only NOTICES — it never
+ * rebases (a rebase can conflict). Silent when there are no live forge worktrees
+ * or this is not a git repo.
+ */
+function noticeWorktreeLag() {
+  let out;
+  try {
+    out = execSync('git worktree list --porcelain', {
+      cwd: targetDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    return; // not a git repo / git unavailable
+  }
+  const lagging = [];
+  let curPath = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) curPath = line.slice('worktree '.length).trim();
+    else if (line.startsWith('branch ')) {
+      const br = line.slice('branch '.length).trim();
+      if (/^refs\/heads\/forge\/m-/.test(br) && curPath) {
+        lagging.push({ path: curPath, branch: br.replace('refs/heads/', '') });
+      }
+    }
+  }
+  if (!lagging.length) return;
+  console.log(`  ${lagging.length} live Forge worktree(s) lag this upgrade:`);
+  for (const w of lagging) {
+    console.log(`    ${w.path} (${w.branch})`);
+  }
+  console.log('    They keep their branch-point framework files until rebased.');
+  console.log('    Pick up this upgrade in each:  git -C <path> rebase main');
+  console.log('    (Gitignored carve-outs like .mcp.json / experimental hooks do not');
+  console.log('     rebase — re-run the experimental installer if the upgrade changed them.)\n');
 }
 
 // --- Entry point ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.37.0",
+  "version": "0.41.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -160,6 +160,14 @@ existing M10 state.
      `{orchestration.worktree_root or ../<repo>-worktrees}/{anchor}` — rather
      than assuming the experimental `orchestrating` skill's internal default.
      Confirm the resolved path with `git worktree list` before recording it.
+     **If a path *is* recorded, validate it before honoring it** (don't trust it
+     blind — that is the gap a recorded-but-wrong path slips through): compare its
+     parent dir to the resolved convention root (`orchestration.worktree_root`,
+     else `{repo-basename}-worktrees`). Mismatch → advisory warn *"recorded
+     worktree path `{path}` is not under the convention root `{root}` — a manual or
+     pre-convention `git worktree add`; `git worktree move` it and update the
+     record."* Adopt the recorded path as-is regardless (advisory, never a block;
+     honors `orchestration.worktree_root`).
    - `runtime.worker_sessions` with the M10 session / claim ids
    - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
      as empty lists if unknown

package/template/.claude/skills/forge/SKILL.md

@@ -32,8 +32,10 @@ git worktree list --porcelain 2>/dev/null \
 - Surfacing continues to Rollup + selection — but it is **no longer purely informational**. Enforcement is deferred to **1.1a**, which fires only for the *selected* milestone (booting from main to work an unrelated milestone stays free). Record which worktrees were reported here so 1.1a can match the selection against them. (See FORGE.md State Ownership for the full taxonomy.)
 
 **If `in_main_checkout: false`** (this session is itself a worktree) AND `forge.worktree_rebase_check: true` in `.forge/project.yml` (default `false` — opt-in):
-- Diff `.forge/` between this worktree's `HEAD` and `origin/main` (or `main` if no remote), restricted to the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`).
-- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides.
+- Diff this worktree's `HEAD` against `origin/main` (or `main` if no remote) across **two** surfaces:
+  - **(a) shared `.forge/` state** — the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy: `context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`, `FORGE.md`.
+  - **(b) framework surface** — `.claude/skills/`, `.claude/agents/`, `.forge/FORGE.md` — the files a `/upgrading` run changes. This catches a **framework upgrade that landed on main after this worktree branched**: `upgrading` Step 8's producer-side offer is the primary path, but a worktree created (or forgotten) since the upgrade only finds out here. (Gitignored framework files — `.mcp.json`, experimental hooks — won't show in the diff; they propagate via the experimental installer, not git.)
+- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides. For a framework-surface (b) hit, lead with rebase (a partial restore of skills/agents is rarely what you want).
 - Setting absent or `false` → no-op.
 
 **Integration flag check (consumer — worktree only).** When `in_main_checkout: false`, check whether a checkpoint publish has landed work on main that this worktree should pull (FORGE.md → Stream Integration Checkpoints). Event-driven, not polled — read the flag first; act only if it is set:
@@ -45,6 +47,13 @@ git worktree list --porcelain 2>/dev/null \
 
 Cross-machine note: the flag file is machine-local, so a worktree on another laptop relies on the opt-in `forge.worktree_rebase_check` / a periodic fetch instead — eventual, not instant.
 
+**Worktree path convention check (advisory — main or worktree).** A recorded worktree path is trusted *verbatim* everywhere (FORGE.md → "Recorded path is authoritative"), so a path created **outside** the convention — a manual `git worktree add ../forge-worktrees/m115`, or pre-convention state — is honored unchallenged by the 1.1a gate and by `chief-of-staff` adoption. This check surfaces that drift. It never blocks and never moves anything.
+
+- Resolve the convention root: `orchestration.worktree_root` from `project.yml` (relative → against the **repo root**; absolute / leading-`~` honored verbatim); if unset, `{repo-parent}/{repo-basename}-worktrees`.
+- For each recorded worktree path in play this boot — `lifecycle.worktree_path` of any surfaced live milestone, plus any stream `runtime.worktree` — compare its **parent dir** to the resolved root.
+- Mismatch → one advisory line: *"recorded worktree path `{path}` for m{id} is not under the convention root `{root}` — likely a manual `git worktree add` or pre-convention state. Fix: `git worktree move {path} {root}/{anchor}` then update the recorded path. (Advisory; honors `orchestration.worktree_root`.)"*
+- Parent dir under the root, or no recorded path → silent. An explicit `orchestration.worktree_root` is honored by construction (the override **is** the root compared against), so a deliberately relocated root never false-warns.
+
 **Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
 
 **Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml`, scan for streams with `coordination: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Any present → one line: *"{N} stream(s) ready to merge — run `/chief-of-staff` (merge safe) to integrate."* Pointer only — the cadence logic lives in the Chief's Merge Cadence Check; `forge` never merges. Nothing pending → silent.
@@ -65,6 +74,8 @@ Rollup procedure (deterministic + idempotent):
 
 Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **Only the main/orchestrator session runs rollup; worktree agents never write `index.yml`** (they edit only their own `milestone-{id}.yml`).
 
+**Enforced, not optional — a boot must not read a stale registry.** The rollup *is* the reconcile step; skipping it silently lets `index.yml` drift from the milestone files — e.g. a worktree sets `current.status: complete` and merges to main, but `index.yml` stays `active` until some later boot happens to regenerate by hand (observed twice for m-CLOUDS01). So every boot **runs** steps 1–4. Before rewriting, diff each milestone's *derived* status against its current `index.yml` entry; any mismatch → emit one loud line — *"index.yml was stale vs {N} milestone file(s) ({ids}) — regenerated."* — then write. Identical (the common case) → the rewrite is a no-op by bytes; stay silent. The rollup is idempotent, so running it on every boot is free.
+
 ### 1.1 Milestone Selection
 
 Check state files:
@@ -113,6 +124,12 @@ Single-owner-mutable state must be written by exactly one checkout. When this se
 
 Resolve the worktree path from the recorded `lifecycle.worktree_path` / `runtime.worktree`, or — if absent — from the base **Worktree Convention** (FORGE.md).
 
+**Completed milestone + live worktree → finalize, not gate (precedence).** The gate assumes the live worktree holds *in-progress, owned* work. A worktree whose milestone file is already `current.status: complete` — it set complete and merged to main, then a fresh main boot lands here — needs the **opposite** of a write-block: it needs wrapping up. So when the selected milestone is `complete` **and** still has a live worktree, do **not** raise the four-option ownership gate. Surface the finalize offer instead: *"m{id} is complete but its worktree `{path}` (`{branch}`) is still live — roll up `index.yml` and tear down the worktree + branch? [yes / keep]"*.
+- **yes** → confirm, then `git worktree remove {path}`, delete the branch, clear `lifecycle.worktree_*` on the milestone, and run **Rollup (1.0)**. (Never auto-remove without the explicit yes.)
+- **keep** → leave it; impose no write-block — a `complete` milestone has no live cursor left to fork.
+
+The gate (below) and this finalize path are mutually exclusive on `current.status`: `complete` → finalize; any other status with a live worktree → gate.
+
 **When it does NOT trigger** (no-op — continue to routing): no live worktree for the selected milestone; or this session **is** the owning worktree (`in_main_checkout: false` and the branch anchors to this milestone); or the milestone has a recorded, still-current `lifecycle.ownership_override` (see option 4).
 
 **When it triggers — STOP. Do not route** to `planning`, `executing`, `verifying`, `reviewing`, `quick-tasking` against this milestone, and do not write any of:

package/template/.claude/skills/upgrading/SKILL.md

@@ -81,12 +81,28 @@ For each skill dir present in the project's `.claude/skills/` but **absent from
 
 ## Step 4: Sync Template-Only Files
 
-Same process as Step 3 for `.forge/templates/**` and `.forge/migrations/**`. (Matches the npm bin's template-only dirs — keeps migration guides installed so the Step 7 pointers resolve via the in-Claude sync route, not just `npx forge-orkes upgrade`.)
+Same process as Step 3 for `.forge/templates/**`, `.forge/migrations/**`, and `.forge/adapters/**`. (Matches the npm bin's template-only dirs — keeps migration guides installed so the Step 7 pointers resolve via the in-Claude sync route, not just `npx forge-orkes upgrade`. `.forge/adapters/**` ships the platform-adapter generation protocols, e.g. `codex-generation.md`, so the Step 4b Codex step can hand it to `quick-tasking`.)
 
 **Also sync the forge gitignore:** the source ships it as `.forge/gitignore` (npm strips files literally named `.gitignore` from a published tarball). Copy/refresh the source's `.forge/gitignore` into the project as `.forge/.gitignore` (overwrite — it is framework-owned). Report added/updated/unchanged like any template-only file.
 
 **Sync the framework prose file `.forge/FORGE.md`** (framework-owned single file — it holds the `# Forge` prose, formerly embedded in CLAUDE.md). Copy/refresh `{source}/packages/create-forge/template/.forge/FORGE.md` → `.forge/FORGE.md` (overwrite when different; report added/updated/unchanged). **Run this BEFORE the Step 5 CLAUDE.md pass** so a migrated import line never points at a missing file.
 
+## Step 4b: Codex Adapter (presence-gated — detect + offer, never auto)
+
+Forge ships a **Codex/AGENTS adapter** (`.agents/skills/` + `.codex/` wiring) for projects run on Codex. It is a *derived translation* of the canonical `.claude/` skills (ADR-014) and drifts whenever core moves — but `upgrading` syncs only `.claude/`, so the Codex adapter would silently rot. This step makes that staleness visible and one-keystroke-fixable, **without** ever generating it here (only an agent-as-Codex can author it natively).
+
+1. **Presence gate.** Glob the project root for `.agents/` and `.codex/`. **Neither exists → skip silently** — no prose, no prompt (Claude-only / greenfield projects are unaffected).
+2. **Either exists → report + offer.** The Codex adapter is present and may be stale relative to the `.claude/` source just synced in Steps 3–4. Offer regeneration:
+   ```
+   Codex adapter detected (.agents/ / .codex/). It may be stale vs the .claude/
+   source just synced. Regenerate it now? (yes / no)
+   ```
+   - **yes** → invoke `quick-tasking`, handing it `.forge/adapters/codex-generation.md` as the task definition (the **same delegation pattern as Step 7 migrations**). The protocol instructs an agent-as-Codex to author `.agents/` + `.codex/` from source using native primitives; a human reviews the diff before commit. `upgrading` itself **never** writes `.agents/` and never performs the translation.
+   - **no** → record `Codex adapter: stale, declined` for the Step 6 report.
+3. **Report line.** Add a `Codex adapter:` line to the Step 6 report — one of `regenerated` / `stale, declined` / `not present`.
+
+Presence-gated, never auto-runs, regeneration is agent-run via `quick-tasking`. The protocol doc itself reaches the project via the Step 4 `.forge/adapters/**` sync.
+
 ## Step 5: Handle Import-Managed + Merge-Owned Files
 
 **`CLAUDE.md` (import-managed — one-pass auto-migration, no prompt):** mirror the npm bin's `ensureClaudeMdImport()` case-for-case. The framework prose lives in `.forge/FORGE.md` (synced in Step 4) — never write prose into CLAUDE.md, and never modify user content outside a legacy forge section.
@@ -125,6 +141,8 @@ Experimental skills: {N}
   - orchestrating (from experimental/m10) — updated  [or: unchanged / STALE, declined]
   - ...
 
+Codex adapter: regenerated   [or: stale, declined / not present]
+
 Removed from template: {N} files
   - .claude/agents/old-agent.md (still in your project)
   - ...
@@ -175,3 +193,21 @@ Migrate now? (yes/no/show guide)
 ### Why there is no bookkeeping
 
 Recording "crossed" guides is implicit in the range. Once Step 5 stamps `forge.version` to `source`, a later run's range `(new installed, source]` excludes every guide already crossed — so nothing re-detects, with **no ledger or marker file**. The range also closes the install-run blind spot: detection keys off the guides **freshly synced this run** (Step 4) plus the **pre-stamp installed version**, so the run that installs new detection behavior uses the new guides, not this skill's own pre-sync prose.
+
+## Step 8: Propagate to Live Worktrees (offer, never auto)
+
+The sync lands framework files (`.claude/skills/`, `.claude/agents/`, `.forge/FORGE.md`, templates) in **this checkout only**. A live Forge worktree keeps running its branch-point copies until it pulls main in — and nothing else surfaces this: the integration flag (`.git/forge/integration-pending`) fires only on a verified **work** checkpoint, never on an upgrade, and `forge.worktree_rebase_check` is opt-in. So close the loop here, where the upgrade actually happened.
+
+1. **Main checkout only.** `git rev-parse --git-dir` == `--git-common-dir` → main; differ → this session **is** a worktree, so skip (run `/upgrading` from main to propagate). No remote/not a git repo → skip.
+2. **Commit the sync first** — a worktree can only rebase onto committed history, so uncommitted synced files won't propagate. If the sync is unstaged, prompt: *"Commit this upgrade on main before propagating? (e.g. `chore(forge): upgrade to v{new}`)"* and wait.
+3. **Enumerate live worktrees:** `git worktree list --porcelain`, branches matching `refs/heads/forge/m-*` (same scan as the `forge` boot preflight). None → done, silent.
+4. **Offer — never auto** (a rebase can conflict and needs human judgment):
+   ```
+   {N} live worktree(s) lag this upgrade (v{old} → v{new}):
+     - {path} ({branch})
+   Pick up v{new} in each:  git -C {path} rebase main
+   Rebase now? (each / list-only / skip)
+   ```
+   - **each** → run `git -C {path} rebase main` per worktree; on conflict, **stop that one**, report it, and move on — never force, never auto-resolve.
+   - **list-only / skip** → print the commands; the operator runs them when each worktree is at a safe stopping point.
+5. **Gitignored carve-outs don't rebase.** `.mcp.json`, experimental hooks (e.g. M10 `forge-claim-check*.sh`), and anything else gitignored is **not** carried by a rebase. If the upgrade changed them (e.g. an experimental skill was re-synced in Step 3b), each worktree must re-run the experimental installer (`experimental/{pkg}/install.sh`) — a rebase alone leaves them stale. Surface this line whenever Step 3b reported an experimental re-sync.

package/template/.forge/FORGE.md

@@ -63,6 +63,8 @@ Worktrees are a **base concern** — Chief/Streams creates and references them w
 
 **Fallback when no path was recorded.** A worktree created outside `orchestrating` (a manual `git worktree add`, an adopted stream) may have no recorded path. Resolve it from this convention — `{worktree_root}/{anchor}` — rather than assuming the experimental skill's internal default. Chief/Streams uses this fallback; `orchestrating` (when installed) implements the same scheme for the worktrees it creates.
 
+**Validated against the convention (advisory).** "Authoritative" means *honored*, not *unchecked*: `forge` boot (Step 1 preflight) and `chief-of-staff` adoption compare a recorded path's parent dir to the resolved `worktree_root` and **warn** — never block, never move — when it sits outside. This catches a manual `git worktree add ../forge-worktrees/m115` or pre-convention state that the verbatim-trust rule would otherwise sail past (the convention was a *fallback resolver* only, never a *validator*). The warning honors an explicit `orchestration.worktree_root`. Fix with `git worktree move` + update the recorded path.
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
@@ -249,7 +251,7 @@ with the work it describes. Every artifact has a sharing class:
 | **Derived** | `state/index.yml`, `streams/active.yml` | Never hand-edited. Regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup). Only the main/orchestrator session (and `chief-of-staff` for `active.yml`) runs rollup. |
 | **Append-only shared** | `releases.yml` (version reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push before depending on the slot); desire-paths use distinct filenames so two writers never touch the same file. |
 | **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Write only to your milestone/stream block. Within a block, append-only; strike through instead of rewriting. |
-| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init. Canonical on main. Worktrees lag and pull on rebase. No special protocol — git handles it because the conflict surface is tiny. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading`. Canonical on main; worktrees lag until they rebase. An upgrade run touches **only the checkout it runs in**, so after upgrading in main, live worktrees keep their branch-point framework files — `upgrading` **Step 8** enumerates live `forge/m-*` worktrees and offers to rebase each (never auto), and the opt-in `forge.worktree_rebase_check` watches these files as a boot-time safety net. Gitignored carve-outs (`.mcp.json`, experimental hooks) don't rebase — re-run the experimental installer if the upgrade changed them. |
 
 Cross-tree edits land on the current branch and are invisible to other worktrees
 until they pull/rebase. `forge` surfaces live worktrees at boot **and enforces

package/template/.forge/adapters/codex-generation.md

@@ -0,0 +1,90 @@
+# Codex/AGENTS Adapter — Generation Protocol
+
+**You are an agent running AS the Codex runtime.** Your job: (re)generate Forge's
+Codex/AGENTS adapter from the canonical source skills, using **Codex's own native
+primitives**. This is a *native authoring* task, not a find-replace — a swapped-nouns
+copy of the Claude adapter is wrong (FORGE.md Principle 2: adapter-native). Output is a
+**derived product**; the source below is the spec.
+
+Run via `quick-tasking` (handed this file by `/upgrading` Step 4b). A human reviews your
+output before commit. Regenerating *this* Forge repo's own `.agents/` is **DEF-040** —
+not your job unless explicitly asked.
+
+## 1. Source spec → output
+
+| Source of truth (the spec) | You author (the derived adapter) |
+|---|---|
+| `.claude/skills/<name>/*.md` | `.agents/skills/<name>/*.md` |
+| `.claude/agents/<name>.md` (if present) | `.agents/agents/<name>.md` |
+| `.claude/hooks/*.sh` + settings hooks | `.codex/hooks/*.sh` + `.codex/hooks.json` |
+| `CLAUDE.md` | `AGENTS.md` (keep the `@.forge/FORGE.md` import) |
+
+Source = `.claude/` for now. The platform-neutral core (M16) is **DEF-041 deferred**; when
+it lands, only this "source" pointer changes. `.forge/` protocol state is shared, **not**
+translated — never fork it.
+
+## 2. Layout deltas — cosmetic, always-true (apply mechanically)
+
+- skill dir `.claude/skills/` → `.agents/skills/`
+- agent dir `.claude/agents/` → `.agents/agents/`
+- hook dir `.claude/hooks/` → `.codex/hooks/`
+- config file `CLAUDE.md` → `AGENTS.md`
+- settings `.claude/settings.json` → Codex's settings equivalent
+- `Reviewer: Claude` → `Reviewer: Codex`; `Claude Code <X>` → `Codex <X>`
+
+**WARN — do NOT produce `.Codex` (capital C).** The real directories are lowercase
+`.agents/` (skills/agents) and `.codex/` (hooks). A `.Codex` token is the exact bug this
+protocol exists to kill — it must appear **nowhere** in your output.
+
+**Do NOT rewrite Claude *model ids*** (`claude-opus-*`, `claude-sonnet-*`, `claude-haiku-*`,
+`claude-fable-*`) — those are literal API identifiers, not branding. Leave them verbatim.
+
+## 3. Coupled mechanisms — handle with JUDGMENT, not substitution
+
+These four skills (`executing`, `forge`, `orchestrating`, `planning`) reference Claude-only
+runtime mechanics. A noun-swap corrupts them. For each, translate to Codex's real surface or
+drop the moot part:
+
+- **`EnterPlanMode`** (forge, planning). A Claude-native tool. → Map to Codex's plan/approval
+  convention if it has one; else **DROP** the "never use EnterPlanMode" prohibition (moot on
+  Codex) and keep the positive rule: *planning = invoke the planning skill*.
+- **ADR-007 session-id / file-claim identity / `forge-session-id.sh` SessionStart hook**
+  (orchestrating). → Translate to Codex's actual session concept; if Codex has none, mark
+  **N/A** — the claim layer degrades to single-session, which `orchestrating` already
+  tolerates.
+- **Native Task tools** (`TaskCreate`/`TaskUpdate`/`TaskList`, executing in-session UI). →
+  Map to Codex's equivalent; if none, note they were a Claude-only UI nicety and the
+  `.forge/state/` files remain the cross-session source of truth.
+
+## 4. `.codex/` wiring
+
+Author the hook scripts + `.codex/hooks.json` for Codex's real hook surface (its
+PreToolUse/PostToolUse analogs), preserving the **active-skill gate** behavior the
+`.claude/hooks/` versions enforce. If Codex exposes no hook surface, say so explicitly and
+have the skills self-enforce in prose instead of silently dropping the gate. Pre-existing
+`.codex/hooks/README.md` cleanup (stale "Claude Code PreToolUse" wording) is **DEF-042** —
+separate.
+
+## 5. Invariants — PRESERVE verbatim across adapters
+
+Translate **mechanics** (tool names, hook surface, paths, config filenames), **never the
+protocol**. These must read identically in `.agents/` and `.claude/`, so a regeneration is
+diffable for fidelity:
+
+- skill routing tables + workflow tiers (Quick / Standard / Full)
+- gate semantics — verification gates, the **Human Verification Gate** (close precondition)
+- state-ownership rules (single-owner / derived / append-only / shared classes)
+- the **Version Reservation Protocol** and atomic-commit rules
+- desire-path capture, milestone lifecycle, context size gates
+
+If a translation forces a change to any of these, you have over-reached — stop and flag it;
+the protocol does not move to fit a platform.
+
+## 6. How this runs
+
+1. `/upgrading` Step 4b detects `.agents/` or `.codex/` and offers regeneration; on **yes**
+   it hands you this file via `quick-tasking`.
+2. You author the adapter per §1–5 using native primitives.
+3. A human reviews the diff for fidelity (invariants intact, no `.Codex`, coupled mechanisms
+   handled) **before** anything is committed. `/upgrading` never writes `.agents/` itself.
+4. Output is the derived adapter; the source skills are untouched.

package/template/.forge/migrations/0.41.0-generated-codex-adapter.md

@@ -0,0 +1,81 @@
+# Migration Guide: Agent-Regenerated Codex Adapter (Forge 0.41.0)
+
+Applies to projects that have a **Codex/AGENTS adapter** (`.agents/` and/or `.codex/`).
+Claude-only and greenfield projects are unaffected — this guide is silent for them.
+
+Forge 0.41.0 (ADR-014) stops treating `.agents/` as a hand-maintained or find-replaced
+second source. The Codex adapter is now a **derived translation** of the `.claude/` skills,
+**regenerated by an agent acting as the Codex runtime** from a shipped protocol
+(`.forge/adapters/codex-generation.md`), using Codex's native primitives. This kills the
+`.Codex`-token corruption an earlier naive find-replace produced and fixes the silent drift
+where `.agents/` rotted while `.claude/` advanced. Regeneration is **offered, never
+auto-applied** — `/upgrading` Step 4b hands the protocol to `quick-tasking`, and a human
+reviews the diff before commit.
+
+## Prerequisites
+
+1. On the 0.41.0 framework files — run `npx forge-orkes upgrade` (or the `/upgrading` skill)
+   first, so `.forge/adapters/codex-generation.md` is present.
+2. Working tree clean or changes committed — regeneration rewrites `.agents/` + `.codex/`.
+
+## Detection
+
+Prints `MIGRATE` when a Codex adapter exists but is missing the protocol, carries the broken
+`.Codex` token, or is older than the `.claude/` source. Silent + exit 0 otherwise (including
+Claude-only projects).
+
+```bash
+# Codex adapter present but stale/broken → regenerate via the protocol.
+{ [ -d .agents ] || [ -d .codex ]; } || exit 0          # Claude-only → nothing to do
+
+# (a) generation protocol not installed yet
+if [ ! -f .forge/adapters/codex-generation.md ]; then
+  echo "MIGRATE — Codex adapter present but the generation protocol is missing; sync framework files then regenerate"
+  exit 0
+fi
+
+# (b) broken: the .Codex corruption token anywhere in the adapter trees
+if grep -rqF '.Codex' .agents .codex 2>/dev/null; then
+  echo "MIGRATE — Codex adapter contains the broken .Codex token; regenerate from the protocol"
+  exit 0
+fi
+
+# (c) stale: newest source skill newer than newest adapter skill
+newest_src=$(ls -t .claude/skills/*/SKILL.md 2>/dev/null | head -1)
+newest_adapter=$(ls -t .agents/skills/*/SKILL.md 2>/dev/null | head -1)
+if [ -n "$newest_src" ] && [ -n "$newest_adapter" ] && [ "$newest_src" -nt "$newest_adapter" ]; then
+  echo "MIGRATE — Codex adapter is older than the .claude/ source; regenerate from the protocol"
+  exit 0
+fi
+exit 0
+```
+
+## Migration steps
+
+The migration is **never auto-applied**. In Claude Code it runs via the `quick-tasking`
+skill, which `/upgrading` Step 4b hands the protocol to on "yes".
+
+### 1. Ensure the protocol is present
+`.forge/adapters/codex-generation.md` ships with 0.41.0 — confirm `npx forge-orkes upgrade`
+(or `/upgrading`) has synced it.
+
+### 2. Regenerate (Codex-run, agent-authored)
+Run the regeneration **as the Codex runtime**, following `.forge/adapters/codex-generation.md`:
+author `.agents/skills/` + `.codex/` wiring from the `.claude/` source using native
+primitives. Do **not** find-replace; handle the coupled mechanisms (EnterPlanMode, ADR-007
+session-id/claim hook, native Task tools) with judgment per the protocol §3.
+
+### 3. Human review before commit
+Review the diff for fidelity: invariants intact (routing tables, tiers, gate semantics,
+state-ownership, version-reservation, atomic commits), **no `.Codex` token**, coupled
+mechanisms handled. Commit only after review. Lossy steps are confirmed first.
+
+## Validation
+
+```bash
+# No .Codex token survives anywhere in the regenerated adapter
+grep -rqF '.Codex' .agents .codex 2>/dev/null && echo "FAIL: .Codex token still present" || echo "OK: no .Codex token"
+# Every source skill has a corresponding adapter skill dir
+for d in .claude/skills/*/; do n=$(basename "$d"); [ -d ".agents/skills/$n" ] || echo "MISSING adapter skill: $n"; done
+echo "validation complete"
+```