Bump Codex package to 0.4.7

Author: Cipher-85

.agents/skills/resume-from-handoff/SKILL.md

@@ -63,7 +63,7 @@ Read these in order. The handoff is the source of truth.
 
 If the user passed a focus area, bias the worklist toward it, but still surface
 the handoff's own recommended Next Action and the vertical-slice forcing
-function.
+function. A focus argument biases ranking; it does not select a lane.
 
 ## Step 2: Apply The Vertical-Slice Forcing Function
 
@@ -162,6 +162,11 @@ Reporting integrity: this skill runs no measurements by default, so it has no
 verified numbers of its own unless you actually produced them in this turn.
 Report handoff figures as claims, not as facts you observed.
 
+FIRST verification cannot be waived by choosing another lane. Run any required
+read-only FIRST check before selection when project instructions authorize it.
+Otherwise put that check at the front of every affected lane and do not enter
+the selected workflow until the check clears or is reported blocked.
+
 ## Step 6: Write The Session Cache
 
 Write `production/session-state/active.md` with the current session routing
@@ -245,11 +250,27 @@ Before you start - check / honor first:
 - <owed verification or gate>
 ```
 
-If one lane is clearly valid, state it as the recommended next action and give
-the exact starting command. If multiple lanes are genuinely viable, use a
-compact numbered prompt with exactly one `(Recommended)` item, or
-`request_user_input` when available. Do not end with an unstructured "what do you
-want to do?" line.
+The briefing ends at a selection boundary. Never start an unselected lane.
+
+- If multiple lanes are genuinely viable, use `request_user_input` when
+  available, with the recommendation as the first option. Keep the choices
+  compact, preserve exactly one recommendation, and wait for the user's
+  selection. If structured input is unavailable, use the same ordered lanes in
+  a numbered prompt and wait for the numeric reply.
+- If exactly one lane is valid, present the numeric fallback:
+  `Next action:` then `1. (Recommended) [action label] - [reason / command]`.
+  Even for this single option, wait for the user to reply `1`; do not start it
+  automatically.
+
+Resume selection authorizes entering only the selected workflow. It does not
+authorize that workflow's writes, builds, boot smoke, mutating `gh`, commits,
+pushes, branch changes, design decisions, game-feel decisions, balance
+decisions, or any other mutation beyond approvals already declared by that
+workflow. A Follow-up fork inside the selected workflow is a new decision:
+use `request_user_input` when available, otherwise use a compact numbered or
+lettered prompt, and wait again.
+
+Do not end with an unstructured "what do you want to do?" line.
 
 Do not point the user back to `$resume-from-handoff` after work completes. Later
 closeouts should read or refresh the saved `## Session Worklist` in `active.md`.
@@ -263,8 +284,11 @@ closeouts should read or refresh the saved `## Session Worklist` in `active.md`.
   invoked `$resume-from-handoff`.
 - Use `request_user_input`, not a free-text prompt, for true multi-lane choices
   when the tool is available.
-- Never jump to work the user did not select unless there is one obvious next
-  step and the invoked workflow already authorizes it.
+- Never start an unselected lane. A single obvious lane still waits for the
+  user's numeric `1` selection.
+- Treat later workflow forks as new structured decisions; the resume choice
+  does not pre-answer them.
+- FIRST verification remains mandatory regardless of lane choice.
 - Make one primary recommendation. The user should leave knowing the top thing
   to do, with the rest as a ranked menu.
 - The vertical-slice forcing function overrides doc-track drift.
@@ -273,6 +297,7 @@ closeouts should read or refresh the saved `## Session Worklist` in `active.md`.
 ## What This Skill Does Not Do
 
 - Does not write anything except `production/session-state/active.md`.
+- Does not start follow-on work before the user selects a lane.
 - Does not commit or push; that is `$handoff`.
 - Does not perform a full artifact gap audit; that is `$project-stage-detect`.
 - Does not replace reading the handoff; it operationalizes the canonical handoff

.codex/README.md

@@ -12,7 +12,14 @@ Current package version:
   explicit publish operations.
 
 Current status:
-- The package version is `v0.3.0`.
+- The package version is `v0.4.7`.
+- `v0.4.7` hardens resume lane selection, validates Codex-native optional
+  `gen-asset` cores and ACTIVE/STUB profiles, and keeps that project-local skill
+  trackable without adding it to package ownership.
+- Release validation rejects stale package-version summaries in the root and
+  runtime README files.
+- `v0.4.6` restored the in-session two-round `$handoff` review gate without
+  nested CLI, subagent-review, companion, or external-model fallbacks.
 - `v0.2.0` added release versioning, release validation, schema-2 install
   state, and default patch-aware installs.
 - `v0.3.0` documents the latest root workflow alignment and the hook parser fix
@@ -25,6 +32,9 @@ Coexistence rules:
 - Do not write to `.claude/`.
 - Do not require or modify `CLAUDE.md`.
 - Keep neutral game project state such as `production/`, `design/`, `docs/architecture/`, `docs/engine-reference/`, `src/`, `tests/`, and `prototypes/` shared.
+- Keep optional `.agents/skills/gen-asset/**` content project-owned; the
+  installer only makes that subtree trackable and never adds it to the package
+  manifest.
 
 Install and release notes:
 - Fresh targets and old install-state schemas receive a full install.

.codex/VERSION

@@ -1 +1 @@
-0.4.6
+0.4.7

.codex/docs/COEXISTENCE.md

@@ -11,6 +11,10 @@ Rules:
 - Workflow-created shared folders such as `assets/`, `tests/`, `tools/`, and
   `prototypes/` are created lazily when needed.
 - Package ownership is tracked in `.codex/manifest/installed-files.json`.
+- The optional `.agents/skills/gen-asset/**` subtree is project-owned. The
+  installer allowlists it so its core and profiles are trackable, but it is
+  deliberately absent from `installed-files.json`; install and uninstall never
+  copy, replace, own, or delete it.
 - Each target install writes `.codex/manifest/install-state.json` with schema
   version, installed CCGS version, package commit, timestamp, patch mode, file
   hashes, marker-block hashes, detected coexistence mode, Claude guardrail
@@ -35,6 +39,12 @@ Rules:
 - Uninstall removes only package-owned files, CCGS marker blocks, and CCGS
   migration blocks.
 
+For a project that already has Claude-side `gen-asset` profiles, migrate only
+after reviewing the target inventory: create the Codex-native core under
+`.agents/skills/gen-asset/SKILL.md`, copy project-owned profiles byte-for-byte
+from `.claude/skills/gen-asset/profiles/`, and keep the Codex runtime independent
+of `.claude/**`. CCGS does not perform this project-specific migration itself.
+
 Install detects three modes:
 
 - `codex_only`: no Claude guardrail runtime is detected. Install writes the full

.codex/docs/MIGRATION.md

@@ -11,9 +11,21 @@ This port maps upstream workflows to Codex-native surfaces:
 - Hooks live under `.codex/hooks/*.sh` and are wired by `.codex/hooks.json`.
 - Command policy lives in `.codex/rules/settings.rules`.
 
+Optional project-local skills are migrated separately from the CCGS package.
+For `gen-asset`, place the Codex-native direct-image-generation core at
+`.agents/skills/gen-asset/SKILL.md` and copy the project's profile files
+byte-for-byte from `.claude/skills/gen-asset/profiles/` only when the project
+owner approves that migration. The installed runtime must not read or modify
+the Claude-side copy. The `.agents/skills/gen-asset/**` subtree remains outside
+`.codex/manifest/installed-files.json`, so CCGS install and uninstall do not own
+it.
+
 Partial parity gaps are intentional:
 
 - Built-in footer items are represented by `[tui].status_line`; the upstream scripted Stage/session footer is blocked until Codex exposes a documented project custom footer item, with `studio-status-on-start.sh` and `$studio-status` as startup/on-demand fallbacks.
 - Structured choice prompts are written as numbered natural-language choices.
 - Role delegation is written as Codex subagent delegation by upstream role name.
 - Per-agent tool fences, max-turns, and worktree isolation are preserved as explicit instructions and policy checks rather than unsupported TOML fields.
+- Image generation extensions invoke Codex's built-in `image_gen` capability
+  directly. Nested `codex exec`, session-ID parsing, CLI/API fallbacks, and
+  legacy `.Codex/` skill paths are not part of the Codex-native contract.

.codex/docs/VALIDATION.md

@@ -33,6 +33,17 @@ Validator policy:
   commits against the actual previous release tag ref, not mutable GitHub
   Release branch metadata.
 - Runtime files must not depend on Claude-owned paths.
+- `$resume-from-handoff` validation enforces the lane-selection pause, FIRST
+  verification, structured follow-up forks, dynamic slice pointer, stage/catalog
+  guards, and one-file session-cache boundary.
+- If an optional project-local `$gen-asset` skill exists, validation rejects
+  nested Codex CLI generation, legacy runtime paths, API/CLI fallbacks, and
+  unbounded newest-image discovery. ACTIVE profiles require the full semantic
+  schema; minimal STUB profiles remain valid refusal markers.
+- Coexistence validation requires `.agents/skills/gen-asset/**` to stay
+  trackable while remaining absent from package ownership.
+- Release validation requires the root and `.codex` README version summaries
+  to match `.codex/VERSION`.
 - Generated skills must not retain raw structured-choice tool names, raw Claude task-delegation syntax, unsupported frontmatter, or bare custom slash commands.
 - Generated agents must not use unsupported top-level fields such as `tools`, `disallowedTools`, `maxTurns`, `memory`, `skills`, or `isolation`.
 - Hooks must not include a `Notification` event.

.codex/docs/session-continuity.md

@@ -82,6 +82,23 @@ On resume:
 4. Verify drift-prone claims cheaply before acting on them.
 5. Continue from the saved `## Session Worklist` unless there is a real
    inconsistency.
+6. Stop at lane selection. A focus argument changes ranking but does not select
+   work. For multiple viable lanes, use `request_user_input` when available and
+   put the recommendation first. For one valid lane, show the numeric
+   `Next action:` fallback and wait for `1`. Never start an unselected lane.
+7. Treat FIRST verification as mandatory across every lane, and treat each
+   follow-up workflow fork as a new structured decision. Resume selection
+   authorizes entering the selected workflow only; it grants no additional
+   mutation authority.
+
+## Optional Asset-Generation Continuity
+
+When a project provides `$gen-asset`, explicit invocation authorizes built-in
+generation and scratch writes only under `tmp/gen-asset/**`. Preserve one
+contact-sheet gate containing candidate verdicts, exact final paths, overwrite
+warnings, and the adapter command. Approval authorizes only those listed final
+paths and that adapter command; dependency installation, unrelated writes, and
+placement before approval remain outside the invocation.
 
 ## Context Thresholds
 

.codex/docs/skills-reference.md

@@ -2,6 +2,9 @@
 
 77 core skills organized by phase. Invoke them from Codex with the `$skill-name` form when available.
 
+Projects may also provide optional local extensions. They are not part of the
+77 shipped skills and remain owned by the game project rather than CCGS.
+
 ## Onboarding & Navigation
 
 | Command | Purpose |
@@ -35,6 +38,17 @@
 | `$asset-spec` | Generate per-asset visual specifications and AI generation prompts from GDDs, level docs, or character profiles |
 | `$asset-audit` | Audit assets for naming conventions, file size budgets, and pipeline compliance |
 
+Optional project-local extension:
+
+| Command | Purpose |
+|---------|---------|
+| `$gen-asset` | Generate profiled raster candidates with built-in image generation, stage them under `tmp/gen-asset/**`, and wait for one contact-sheet approval before placement |
+
+CCGS validates a present `.agents/skills/gen-asset/` core and its profiles but
+does not ship, install, uninstall, or count it among the 77 core skills. ACTIVE
+profiles must define the full generation/placement schema; minimal STUB
+profiles are valid and refuse generation.
+
 ## UX & Interface Design
 
 | Command | Purpose |

.codex/lib/install.sh

@@ -340,8 +340,15 @@ ccgs_deploy_paths() {
   fi
 }
 
+ccgs_project_owned_allowlist_paths() {
+  # Sentinel only: this makes the optional project-local subtree trackable.
+  # It is deliberately absent from deploy paths and installed-files ownership.
+  printf '%s\n' ".agents/skills/gen-asset/SKILL.md"
+}
+
 ccgs_gitignore_allowlist_paths() {
   ccgs_deploy_paths
+  ccgs_project_owned_allowlist_paths
   printf '%s\n' "$ccgs_install_state_rel"
 }
 
@@ -369,6 +376,10 @@ shared_content_roots = {
     "tools",
 }
 
+project_owned_roots = {
+    ".agents/skills/gen-asset",
+}
+
 def is_shared_content_path(path: str) -> bool:
     return path.split("/", 1)[0] in shared_content_roots
 
@@ -389,7 +400,7 @@ for raw in Path(sys.argv[1]).read_text(encoding="utf-8").splitlines():
 
 def emit_dir(path: str) -> None:
     print("!" + escape(path) + "/")
-    if not is_shared_content_path(path):
+    if not is_shared_content_path(path) and path not in project_owned_roots:
         print(escape(path) + "/*")
     for child in sorted(children.get(path, ())):
         emit_dir(child)

.codex/lib/validate_install.py

@@ -57,6 +57,7 @@ def validate_gitignore_allowlist(root: Path, errors: list[str]) -> None:
     for required in (
         ".codex/*",
         ".agents/*",
+        "!.agents/skills/gen-asset/",
         "!design/registry/entities.yaml",
         "!docs/WORKFLOW-GUIDE.md",
         "!production/session-state/.gitkeep",
@@ -65,6 +66,9 @@ def validate_gitignore_allowlist(root: Path, errors: list[str]) -> None:
         if required not in lines:
             errors.append(f"gitignore allowlist missing expected pattern: {required}")
 
+    if ".agents/skills/gen-asset/*" in lines:
+        errors.append("gitignore allowlist must keep project-local gen-asset descendants trackable")
+
 
 def main() -> int:
     parser = argparse.ArgumentParser()
@@ -116,6 +120,8 @@ def main() -> int:
                 seen.add(path)
                 if path.startswith(".claude/") or path == "CLAUDE.md" or "/.claude/" in path or path.endswith("/CLAUDE.md"):
                     errors.append(f"installed-files must not own Claude path {path}")
+                if path == ".agents/skills/gen-asset" or path.startswith(".agents/skills/gen-asset/"):
+                    errors.append(f"installed-files must not own project-local gen-asset path {path}")
                 if not (root / path).exists():
                     errors.append(f"installed-files path missing on disk: {path}")
         validate_gitignore_allowlist(root, errors)