Fix permission and handoff push parity

Author: Cipher-85

.agents/skills/handoff/SKILL.md

@@ -31,6 +31,29 @@ pair for `$resume-from-handoff`.
   claim.
 - If a command fails, halt the current phase and report the exact failure.
 
+## Git Metadata Capability Gate
+
+Before Phase 0, resolve the repository's actual Git metadata directory:
+
+```bash
+git rev-parse --absolute-git-dir
+```
+
+Run `test -w '<absolute-git-dir>'` against the exact returned path, shell-quoted.
+Do not request escalation for this check. The `game_studios` permission profile
+must make Git metadata writable. The same profile preserves normal workspace
+writes to `.agents/` and `.codex/` so CCGS's own maintenance workflows remain
+usable; only the declared secret paths stay denied.
+
+If the lookup fails or the check reports the Git directory is not writable,
+halt before Phase 0. Report the exact path and result as a permission-profile
+configuration mismatch. Direct the user to install the current CCGS permission
+profile and start a new session so that profile becomes active. Do not begin the
+review gate, rotate continuity files, run `chmod`, delete lock files, or try an
+indirect command workaround. Do not tell the user to switch `/permissions`
+modes: approval routing cannot repair a filesystem rule already resolved for the
+session.
+
 ## Phase 0: Review Gate
 
 Before rotating continuity files or committing, run this mandatory two-round
@@ -215,14 +238,21 @@ If there are no relevant uncommitted changes, skip the commit and say why.
 
 Otherwise stage only the relevant paths by name. Avoid broad staging unless the
 user explicitly asked for it. `$handoff` invocation is commit authorization for
-the relevant handoff work. Before committing, verify:
+the relevant handoff work. Run staging without requesting escalation; the
+active `game_studios` profile grants Git metadata writes. If staging cannot
+write the Git index, halt Phase 3 and report the exact failure without retrying
+through a different command shape.
+
+Before committing, verify:
 
 ```bash
 git diff --cached --name-status
 ```
 
-Commit with the standard handoff subject. Include a Codex co-author trailer only
-if that is normal for this repo.
+Commit with the standard handoff subject without requesting escalation. Include
+a Codex co-author trailer only if that is normal for this repo. If the commit
+cannot write Git metadata, halt Phase 3 and report the exact failure without
+retrying through a different command shape.
 
 Never use `--no-verify`. Never amend as a workaround for a failed hook.
 
@@ -249,21 +279,17 @@ git remote get-url --push origin
 Run only the command that matches the detected upstream state. Halt if the
 required push remote is missing.
 
-When the push remote is on `github.com`, establish destination evidence in this
-same handoff turn immediately before the push:
-
-```bash
-gh auth status -h github.com
-gh api user --jq .login
-gh repo view <owner>/<repo> --json viewerPermission --jq .viewerPermission
-```
+Treat the resolved push URL, current branch/upstream, and explicit `$handoff`
+invocation as the destination and user-authorization evidence. Show the push URL
+and branch in commentary immediately before requesting the push. Do not require
+`gh auth status`, `gh api user`, or `gh repo view` as push preconditions. Git and
+GitHub CLI may use different credentials. A `gh auth status` failure under
+network restriction is not evidence that the Git credential is invalid.
 
-Derive `<owner>/<repo>` from the verified remote URL. Run these read-only GitHub
-checks with the network access they require; a failure from a network-restricted
-sandbox is not evidence that the stored credential is invalid. Never request or
-display a token. Continue only when the authenticated account and a `WRITE`,
-`MAINTAIN`, or `ADMIN` permission establish that the destination is authorized.
-Otherwise halt and report the exact failed check.
+Optional GitHub CLI checks must be read-only, run with the network access they
+require, and remain advisory. Never request or display a token. Do not halt
+before the authorized push solely because a GitHub CLI check is unavailable,
+network-blocked, unauthenticated, or inconclusive.
 
 Push only if the handoff trigger or user instruction authorizes it. Use exactly
 one of these command shapes:
@@ -273,10 +299,14 @@ one of these command shapes:
 
 Request the required escalation with the scoped approval prefix
 `["git", "push"]`. The justification must state that this is the explicitly
-authorized, non-force handoff push; name the verified remote, authenticated
-account and permission; and identify the current branch/upstream. Explicit
-`$handoff` invocation is normal push authorization for the standard handoff
-commit. Never force-push.
+authorized, non-force handoff push; name the verified push URL; and identify the
+current branch/upstream. Do not claim an authenticated account or repository
+permission unless it was actually verified. Explicit `$handoff` invocation is
+normal push authorization for the standard handoff commit. Never force-push.
+
+The actual `git push` is the authoritative network and Git-authentication check.
+If it fails, report Git's exact error and do not reinterpret a preceding GitHub
+CLI result as proof of the cause.
 
 If policy or automatic approval review rejects the push, halt Phase 4. Report
 the exact rejection and do not retry with another command shape, indirect

.codex/config.toml

@@ -4,6 +4,9 @@ default_permissions = "game_studios"
 extends = ":workspace"
 
 [permissions.game_studios.filesystem.":workspace_roots"]
+".git" = "write"
+".agents" = "write"
+".codex" = "write"
 ".env*" = "deny"
 "**/.env*" = "deny"
 

.codex/lib/validate_rules.py

@@ -17,9 +17,12 @@
     "git_branch": "git-branch",
 }
 
-REQUIRED_ENV_DENY_PATTERNS = {
-    ".env*",
-    "**/.env*",
+REQUIRED_WORKSPACE_RULES = {
+    ".git": "write",
+    ".agents": "write",
+    ".codex": "write",
+    ".env*": "deny",
+    "**/.env*": "deny",
 }
 
 REQUIRED_FORBIDDEN_COMMAND_EXAMPLES = (
@@ -84,15 +87,15 @@ def main() -> int:
                 '.codex/config.toml: missing [permissions.game_studios.filesystem.":workspace_roots"]'
             )
         else:
-            missing_env_denies = sorted(
-                pattern
-                for pattern in REQUIRED_ENV_DENY_PATTERNS
-                if workspace_rules.get(pattern) != "deny"
+            incorrect_workspace_rules = sorted(
+                f"{path}={workspace_rules.get(path)!r} (expected {access!r})"
+                for path, access in REQUIRED_WORKSPACE_RULES.items()
+                if workspace_rules.get(path) != access
             )
-            if missing_env_denies:
+            if incorrect_workspace_rules:
                 errors.append(
-                    ".codex/config.toml: missing strict workspace .env deny pattern(s): "
-                    + ", ".join(missing_env_denies)
+                    ".codex/config.toml: incorrect game_studios workspace rule(s): "
+                    + ", ".join(incorrect_workspace_rules)
                 )
         tui = data.get("tui")
         if isinstance(tui, dict) and "status_line" in tui:

.codex/lib/validate_runtime.py

@@ -344,6 +344,49 @@
     ),
 }
 
+HANDOFF_GIT_CAPABILITY_REQUIRED_PHRASES = (
+    "## Git Metadata Capability Gate",
+    "Before Phase 0",
+    "git rev-parse --absolute-git-dir",
+    "test -w '<absolute-git-dir>'",
+    "Do not request escalation for this check",
+    "permission-profile configuration mismatch",
+    "start a new session",
+    "Do not begin the review gate",
+    "normal workspace writes to `.agents/` and `.codex/`",
+    "Do not tell the user to switch `/permissions` modes",
+)
+
+HANDOFF_PHASE3_GIT_WRITE_REQUIRED_PHRASES = (
+    "stage only the relevant paths by name",
+    "Run staging without requesting escalation",
+    "active `game_studios` profile grants Git metadata writes",
+    "Commit with the standard handoff subject without requesting escalation",
+    "without retrying through a different command shape",
+)
+
+HANDOFF_PHASE4_PUSH_REQUIRED_PHRASES = (
+    "Treat the resolved push URL, current branch/upstream, and explicit `$handoff` invocation",
+    "Do not require `gh auth status`, `gh api user`, or `gh repo view` as push preconditions",
+    "Git and GitHub CLI may use different credentials",
+    "Do not halt before the authorized push solely because a GitHub CLI check",
+    "name the verified push URL",
+    "Do not claim an authenticated account or repository permission unless it was actually verified",
+    "The actual `git push` is the authoritative network and Git-authentication check",
+    "report Git's exact error",
+)
+
+HANDOFF_PHASE4_PUSH_FORBIDDEN_PHRASES = (
+    (
+        "Continue only when the authenticated account",
+        "mandatory GitHub CLI identity gate blocks the actual authorized Git push",
+    ),
+    (
+        "Otherwise halt and report the exact failed check",
+        "mandatory GitHub CLI precheck failure still halts before Git push",
+    ),
+)
+
 HANDOFF_REVIEW_FORBIDDEN_PATTERNS = (
     (
         re.compile(r"(?im)^\s*(?:\$\s*)?codex\s+(?:review|exec)\b"),
@@ -727,6 +770,58 @@ def validate_handoff_review_contract(root: Path) -> list[str]:
     skill_path = root / skill_rel
     if skill_path.exists():
         skill_text = skill_path.read_text(encoding="utf-8")
+        missing = [
+            phrase
+            for phrase in HANDOFF_GIT_CAPABILITY_REQUIRED_PHRASES
+            if not contains_phrase(skill_text, phrase)
+        ]
+        if missing:
+            errors.append(
+                f"{skill_rel}: missing handoff Git capability phrase(s): "
+                + ", ".join(missing)
+            )
+
+        phase3_match = re.search(
+            r"(?ms)^## Phase 3: Commit Handoff\s*$\n(.*?)(?=^## Phase 4: Push Handoff\s*$)",
+            skill_text,
+        )
+        if not phase3_match:
+            errors.append(f"{skill_rel}: missing bounded Phase 3 commit section")
+        else:
+            phase3_text = phase3_match.group(1)
+            missing = [
+                phrase
+                for phrase in HANDOFF_PHASE3_GIT_WRITE_REQUIRED_PHRASES
+                if not contains_phrase(phase3_text, phrase)
+            ]
+            if missing:
+                errors.append(
+                    f"{skill_rel}: Phase 3 missing direct Git-write phrase(s): "
+                    + ", ".join(missing)
+                )
+
+        phase4_match = re.search(
+            r"(?ms)^## Phase 4: Push Handoff\s*$\n(.*?)(?=^## Phase 5: Report And Stop\s*$)",
+            skill_text,
+        )
+        if not phase4_match:
+            errors.append(f"{skill_rel}: missing bounded Phase 4 push section")
+        else:
+            phase4_text = phase4_match.group(1)
+            missing = [
+                phrase
+                for phrase in HANDOFF_PHASE4_PUSH_REQUIRED_PHRASES
+                if not contains_phrase(phase4_text, phrase)
+            ]
+            if missing:
+                errors.append(
+                    f"{skill_rel}: Phase 4 missing direct push phrase(s): "
+                    + ", ".join(missing)
+                )
+            for phrase, message in HANDOFF_PHASE4_PUSH_FORBIDDEN_PHRASES:
+                if phrase in phase4_text:
+                    errors.append(f"{skill_rel}: Phase 4 {message}: {phrase!r}")
+
         for pattern, message in HANDOFF_REVIEW_FORBIDDEN_PATTERNS:
             match = pattern.search(skill_text)
             if match:

README.md

@@ -33,8 +33,10 @@ The current release line is `v0.6.1`. It includes:
 
 - Upstream-aware `$handoff` push routing: existing-upstream branches use plain
   `git push`, while only branches without an upstream set one through origin.
-- Same-turn GitHub authentication, destination, and repository-permission
-  verification before a handoff push is attempted.
+- Same-turn destination verification from the configured push URL and
+  branch/upstream. GitHub CLI identity checks are advisory because Git and `gh`
+  can use different credentials; the authorized `git push` is the definitive
+  network and Git-authentication check.
 - Scoped `git push` approval requests with fail-closed policy-denial handling
   and no alternate-command retries or workarounds.
 
@@ -231,6 +233,27 @@ well as through the existing command rules and hooks, but it can also prevent
 Codex from creating or editing files such as `.env.example`. Use an
 agent-editable name such as `config.example` for non-secret templates.
 
+The profile extends Codex's built-in `:workspace` profile but explicitly
+restores write access to `.git/`, `.agents/`, and `.codex/`. This preserves the
+upstream CCGS behavior required by Git handoff and skill/runtime maintenance
+while retaining the narrower `.env*` denials. Destructive command protections
+remain in `.codex/rules/settings.rules` and the validation hooks.
+
+The project-local `default_permissions` setting is why `/permissions` displays
+`game_studios`; it does not edit the user's global `~/.codex/config.toml`.
+Approval modes control escalation separately and are not a repair mechanism for
+filesystem rules. `$handoff` checks Git metadata access before its review gate,
+then stages and commits without escalation; a networked push follows the active
+session's approval policy. It does not block an authorized push on inconclusive
+GitHub CLI authentication checks. If the initial Git check fails, install the
+current CCGS profile and start a new session so Codex resolves it. Do not switch
+approval modes, run `chmod`, or delete lock files as a workaround.
+
+The distributable profile does not mix permission profiles with legacy
+`sandbox_mode`. After changing `.codex/config.toml`, start a new session before
+judging the resolved profile because active sessions retain their launch-time
+filesystem rules.
+
 Default install behavior is patch-aware: a fresh target receives a full install,
 while a target with valid schema-v2 install state receives an incremental patch
 based on recorded package file hashes. Invalid, unsafe, or stale state aborts

docs/codex-conversion/codex-mapping-matrix.md

@@ -64,7 +64,7 @@ Official docs used: `https://developers.openai.com/codex/guides/agents-md`, `htt
 | `design/CLAUDE.md` | Design-document scope guidance | Nested Claude instructions | Root-routed Codex path guidance | `.codex/instructions/path-rules/design-directory.md` | replaced | partial | Preserve design and registry guidance; keep `design/registry/entities.yaml` shared. | Router-chain validation; no runtime `.claude` refs. |
 | `docs/CLAUDE.md` | Documentation scope guidance | Nested Claude instructions | Root-routed Codex path guidance | `.codex/instructions/path-rules/docs-directory.md` | replaced | partial | Preserve docs standards without depending on Claude imports. | Router-chain validation; instruction-budget check. |
 | `CCGS Skill Testing Framework/CLAUDE.md` | Test-framework specific guidance | Nested Claude instructions | Testing-framework docs/instructions | `CCGS Skill Testing Framework/AGENTS.md` or README section | replaced | semantic equivalent | Preserve the upstream framework path; replace Claude-specific guidance with Codex guidance. | File existence; no runtime `.claude` dependency. |
-| `.claude/settings.json` permissions | Allow/deny command and path policy | Claude permissions in settings JSON | Codex permission profile plus command rules | `.codex/config.toml`, `.codex/rules/settings.rules` | replaced | semantic equivalent | Use `[permissions.game_studios] extends = ":workspace"`; deny sensitive env paths; command policies go in `.rules`, not config. | TOML parse; rules lint; forbidden command fixture. |
+| `.claude/settings.json` permissions | Allow/deny command and path policy | Claude permissions in settings JSON | Codex permission profile plus command rules | `.codex/config.toml`, `.codex/rules/settings.rules` | replaced | semantic equivalent | Use `[permissions.game_studios] extends = ":workspace"`, then explicitly restore workspace writes to `.git`, `.agents`, and `.codex`; the inherited read-only carve-outs are stricter than upstream and break Git and CCGS maintenance workflows. Deny sensitive env paths; command policies go in `.rules`, not config. | TOML parse; rules lint; forbidden command fixture; fresh trusted session resolves `.git`, `.agents`, and `.codex` as writable while `.env*` remains denied. |
 | `.claude/settings.json` hooks | Hook event wiring | Claude settings hook blocks | Codex hooks config | `.codex/hooks.json` | replaced | semantic equivalent | Map supported lifecycle events only. Do not include Claude's `Notification` event; map notification behavior separately through user-level Codex notification docs. | JSON parse; event allowlist; command-path existence. |
 | `.claude/statusline.sh` | Always-on context/model/stage/session breadcrumb | Claude scriptable status line command | Codex native footer config plus startup/on-demand studio status | `.codex/config.toml` `[tui].status_line`, `.codex/hooks/studio-status-on-start.sh`, `.agents/skills/studio-status/SKILL.md` | replaced | partial; `Stage:` footer blocked | Preserve context/model visibility with Codex built-in `status_line` items. Preserve stage/review/session breadcrumb through shared-state parsing in `studio-status-on-start.sh` and `studio-status`; actual footer `Stage:` parity is blocked until Codex exposes a documented project custom footer item. | Config parse; status_line item allowlist; hook fixture; `studio-status` smoke reads `production/session-state/active.md`; no fake custom footer key. |
 | `.claude/agent-memory/lead-programmer/MEMORY.md` | Lead-programmer project memory seed | Claude agent memory file plus `memory: project` metadata | Repo-local Codex memory contract read by custom agent instructions | `.codex/agent-memory/lead-programmer/MEMORY.md` plus `.codex/agents/lead-programmer.toml` binding | ported | semantic equivalent | Rewrite Claude skill paths to `.agents/skills/<name>/SKILL.md` and keep canonical paths. Agent TOML must instruct `lead-programmer` to read the memory file before skill authoring, path canonicalization, and convention work. Do not write `~/.codex/memories`. | File existence; TOML binding scan; static scan: no writes to `~/.codex/memories`; content rewrite scan. |

docs/codex-conversion/corrected-architecture.md

@@ -280,9 +280,14 @@ Permissions:
 - `.codex/config.toml` should define:
   - `default_permissions = "game_studios"` only when safe to set in an owned config.
   - `[permissions.game_studios] extends = ":workspace"`.
+  - Explicit write rules for `.git`, `.agents`, and `.codex`; upstream permits
+    ordinary Git and runtime-maintenance workflows, so inherited read-only
+    carve-outs are not parity.
   - Deny sensitive env paths.
   - Network disabled by default unless a user explicitly enables it.
-  - `approval_policy = "on-request"` or documented granular equivalent.
+- Do not force a project-local `approval_policy`. Approval routing is
+  user/session-owned; local staging and commits must work without escalation,
+  while networked pushes follow the active session policy.
 - Do not set `sandbox_mode` in the same distributable config when permission profiles are used.
 
 Command rules:

docs/codex-conversion/implementation-plan.md

@@ -267,6 +267,11 @@ Acceptance criteria:
 - Hooks JSON parses and contains no `Notification`.
 - All hook scripts exist, are executable, and pass payload fixtures.
 - Config parses and does not mix permission profiles with `sandbox_mode`.
+- The `game_studios` profile explicitly grants write access to `.git`,
+  `.agents`, and `.codex`, retains both `.env*` deny patterns, and does not set a
+  project-local approval policy.
+- A fresh trusted session resolves those three runtime paths as writable;
+  parser success alone is not permission-parity evidence.
 - If `[tui].status_line` is installed, all item IDs are Codex-supported built-ins and the project config parses under `--strict-config`.
 - Rules file passes positive/negative command examples.