@sabaiway/agent-workflow-kit 1.15.2 → 1.17.0

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -10,13 +10,22 @@ judgment.
 
 1. Decide the mode: `codex-exec` to *do* (edit the repo under the sandbox), `codex-review` to *judge*
    (advisory findings, no edits).
-2. Run the wrapper from the **target project root** so codex auto-reads its `AGENTS.md` (the wrappers
-   also preflight that a root `AGENTS.md` and a git work tree exist).
+2. Run the wrapper from the **target project root** so codex auto-merges its `AGENTS.md` (the wrappers
+   also preflight that a root `AGENTS.md` and a git work tree exist, and fail fast before spending a run).
 3. For an ad-hoc instruction, make it self-contained: codex cannot see your conversation — embed the
-   goal, the relevant paths, the non-goals, and the expected result. The project's rules come from
-   `AGENTS.md`.
+   goal, the relevant paths, the non-goals, and the expected result. The project's rules come from the
+   already-merged `AGENTS.md`.
 4. Let codex run; then **review its diff yourself** and re-run the project's gates.
-5. **Commit yourself** — codex never commits.
+5. **Commit yourself** — codex never commits (a git-write shim enforces it; see below).
+
+## Quality-first: model & effort are pinned
+
+Delegated codex work ALWAYS runs on the frontier model at max effort: `gpt-5.5` / `xhigh` are **pinned**
+and a non-default `CODEX_MODEL`/`CODEX_EFFORT` is **refused** (exit 2). Do not try to "tune down" the
+model or effort for a real run — the wrapper will stop you. Quota is metered in **messages** (rolling
+5h + weekly), so economy comes from removing waste (clean capture, the precomputed review diff, resume),
+never from a downgrade. The only opt-out is a throwaway, effort-independent probe: `CODEX_PROBE=1`
+(loud) — never use its output as real work.
 
 ## Exec vs review
 
@@ -27,34 +36,74 @@ can review the resulting diff.
 Use **`codex-review plan`** for a cold second opinion on a plan before executing it (risks, missing or
 mis-ordered steps, scope creep, missing gates).
 
-Use **`codex-review code`** for advisory, severity-tagged findings on uncommitted changes — including
-when **untracked** files matter: the wrapper prompt tells codex to run `git status --short` and read
-the contents of `??` files, because plain `git diff` omits them.
+Use **`codex-review code`** for advisory, severity-tagged findings on uncommitted changes. The wrapper
+**precomputes the whole change set** — repo map, `git status`, staged + unstaged diff, and the
+**contents of untracked files** (binaries noted but skipped, symlinks shown as targets, other
+non-regular paths skipped) — and feeds it in, so codex does not burn a run roaming the filesystem to
+rediscover it. A clean tree exits 0 *before* a run is spent. An oversized payload (over
+`CODEX_REVIEW_MAX_TOTAL_BYTES`, default 1.5 MB) is written to a git-dir temp file and referenced by
+path — never silently truncated. Set `CODEX_REVIEW_SCHEMA=1` to get findings back as a validated JSON
+object (raw-text fallback on failure).
 
 ## Usage
 
 ```bash
 codex-exec docs/plans/<slug>.md                  # drive a plan file
 echo "apply review fix: tighten the guard in X, keep tests green" | codex-exec -
-CODEX_MODEL=<slug> CODEX_EFFORT=high codex-exec <file>     # tune model/effort
-codex-exec <file|-> -- --add-dir ../shared        # passthrough codex flags after `--`
+codex-exec <file|-> -- <unguarded codex flags>   # passthrough AFTER `--` (policy/model/capture flags are rejected)
+
+codex-exec --resume-last docs/plans/<slug>.md    # continue the last session, no re-send
+echo "now do step 2" | codex-exec --resume <id> -
 
 codex-review plan docs/plans/<slug>.md            # critique a plan before executing it
-codex-review code                                 # review the current working-tree diff
+codex-review code                                 # review the current working-tree diff (precomputed)
 codex-review code "focus on the reducer and its tests"
 ```
 
 `codex-exec` prepends an **orchestrator execution contract**: work in the current tree, never
-git-write, obey the target `AGENTS.md`, self-review the diff (incl. untracked files), run the
-project's declared gates (STOP if none are declared), don't commit, report blockers.
+git-write, *obey* the already-merged `AGENTS.md` (Hard Constraints + declared gates), self-review the
+diff (incl. untracked files), run the project's declared gates (STOP if none are declared), don't
+commit, report blockers. It captures only codex's **final message** (`-o`; the JSON event stream +
+reasoning are discarded to a trace) and, on a **non-resume** run, records the session id to
+`${CODEX_SESSION_FILE:-./.codex-last-session}`.
 
-## Prompt shapes (for ad-hoc `codex-exec -` instructions)
+## Resume — iterate without re-sending context
+
+```bash
+codex-exec --resume-last <plan-file|->     # session id read from the sidecar
+codex-exec --resume <session-id> <file|->  # explicit session id
+```
+
+Resume continues the SAME codex session, so you avoid re-sending the original context. It runs through
+the wrapper, which **re-establishes every invariant** (subscription-only `*_API_KEY` scrub,
+`--ignore-user-config`, the pinned `gpt-5.5`/`xhigh`) and **restates the full posture via `-c`** —
+because `codex exec resume` resets the sandbox/approval/network posture and rejects `-s`/`--add-dir`/`-C`,
+the wrapper passes `-c sandbox_mode=workspace-write -c approval_policy=never -c
+sandbox_workspace_write.network_access=false` explicitly. A resume takes no passthrough flags and an
+empty resumed instruction is rejected. Prefer resume over re-dispatching a fresh run when you are
+iterating on the same task; start a fresh `codex-exec` when the task changes.
+
+## The commit boundary & the git-write shim
+
+- **Repo edits** are codex's job *inside* `codex-exec`'s workspace-write sandbox — but you **review the
+  diff** before accepting/committing it. `codex-review` makes no edits at all (read-only sandbox).
+- **Git writes** (branch/add/commit/stash/reset/checkout/tag/rewrite) are never delegated. Beyond the
+  prompt contract, `codex-exec` prepends a physical **git-write shim** to the codex subprocess's
+  `PATH`: a `git` wrapper file that passes read-only verbs through to the real git and **blocks every
+  write/unknown verb** (codex spawns `git` via `execve`, which bypasses shell functions, so the
+  boundary must be a real executable; the real git path is baked into the shim, not exposed as an env
+  var). `git config` is read-only too (blocked on a write flag or a `<name> <value>` set form). The
+  orchestrator commits after review.
+- **New dependencies / network installs** are done by hand (exec has network OFF), then codex is
+  re-dispatched.
+- **A hung run** is killed at `CODEX_HARD_TIMEOUT` (exec 3600s / review 1800s) and reported (exit
+  124/137); raise it for a known-healthy slow run.
 
-Execution:
+## Prompt shapes (for ad-hoc `codex-exec -` instructions)
 
 ```text
 Implement the change below from the current project root.
-Respect root AGENTS.md, especially its Hard Constraints and declared gates.
+Obey root AGENTS.md (already in your context), especially its Hard Constraints and declared gates.
 Do not run git write commands. Do not commit.
 If a dependency install, network call, missing gate set, or out-of-repo write is needed, STOP and report.
 
@@ -62,30 +111,8 @@ If a dependency install, network call, missing gate set, or out-of-repo write is
 ```
 
 The review prompt shapes are built into `codex-review` itself — you only pass `plan <file>` or
-`code [focus]`; the wrapper supplies the severity-tagged-findings + verdict directive.
-
-## Re-dispatch vs. fresh run
-
-```bash
-codex exec resume --last      # run codex DIRECTLY — not through codex-exec
-```
-
-Resume is **not** reachable through `codex-exec`: the wrapper's shape (fixed flags + a trailing `-`
-that reads the prompt from stdin) can't host the `resume` subcommand, and the wrapper rejects
-policy-affecting passthrough flags anyway. Run `codex exec resume` directly when you want to continue
-a session without re-sending context — but note it runs **outside** the wrapper, so it does not
-inherit the enforced sandbox/network/approval policy and **may not re-accept those flags**. Restate
-the policy in the resumed instruction, or just start a fresh `codex-exec` run when the posture must be
-guaranteed (see `sandbox-and-flags.md`).
-
-## Escalation policy (edits, network, git)
-
-- **Repo edits** are codex's job *inside* `codex-exec`'s workspace-write sandbox — but you **review the
-  diff** before accepting/committing it. `codex-review` makes no edits at all.
-- **New dependencies / network installs** are done by hand (exec has network OFF), then codex is
-  re-dispatched.
-- **Git writes** (branch/add/commit/stash/reset/checkout/tag/rewrite) are never delegated — the
-  orchestrator commits after review. The execution contract forbids them.
+`code [focus]`; the wrapper supplies the assembled diff + the severity-tagged-findings + verdict
+directive (or the JSON-schema directive when `CODEX_REVIEW_SCHEMA=1`).
 
 ## Handling output
 

package/bridges/codex-cli-bridge/references/sandbox-and-flags.md

@@ -1,7 +1,7 @@
 # `codex` sandbox, flags & policy (reference)
 
 The source of truth is the live binary: `codex --version`, `codex --help`, `codex exec --help`. The
-tables below were captured from **codex-cli 0.140.0**; if the binary disagrees, the binary wins. The
+tables below were captured from **codex-cli 0.142.3**; if the binary disagrees, the binary wins. The
 wrapper commands are `codex-exec` and `codex-review`, backed by `bin/codex-exec.sh` /
 `bin/codex-review.sh`.
 
@@ -13,51 +13,140 @@ wrapper commands are `codex-exec` and `codex-review`, backed by `bin/codex-exec.
 | `workspace-write` | repo (cwd) only | OFF (we force it off) | `codex-exec` (codex edits the repo) |
 | `danger-full-access` | anywhere | yes | never used by this skill |
 
-`codex-exec` always passes:
+**A sandbox bounds WRITES, not READS.** Even `read-only` can read any file on disk (it is what kept a
+naive review roaming into `~/.claude/**` and producing multi-MB transcripts). Read-scoping is therefore
+a **prompt + env** concern, not a sandbox one — see the review read-fence below. Under `read-only` codex
+*structurally* cannot edit, create, delete, or git-write; it can only read and report.
 
-```bash
---sandbox workspace-write \
--c approval_policy="never" \
--c sandbox_workspace_write.network_access=false
-```
+## Flags the wrappers always pass
 
-`codex-review` always passes:
+`codex-exec`:
 
 ```bash
---sandbox read-only \
--c approval_policy="never"
+codex exec --ignore-user-config \
+  --sandbox workspace-write \
+  -c approval_policy=never \
+  -c sandbox_workspace_write.network_access=false \
+  -c model_reasoning_effort="$CODEX_EFFORT" \
+  -c hide_agent_reasoning=true -c model_reasoning_summary=none \
+  --color never -o "$out" --json -m "$CODEX_MODEL" -
 ```
 
-Under `read-only`, codex *structurally* cannot edit, create, delete, or git-write — it can only read
-and report. In v0.140.0 `read-only` also grants **no network**, so `codex-review` relies on that and
-passes no separate network flag — the `sandbox_workspace_write.*` config (including
+`codex-review` is the same minus the write/network posture, plus `--sandbox read-only` and (optionally)
+`--output-schema`. In v0.142.3 `read-only` also grants **no network**, so `codex-review` relies on that
+and passes no separate network flag — the `sandbox_workspace_write.*` config (including
 `network_access`) applies **only** to `workspace-write`.
 
-## Network-OFF invariant (exec)
+### Clean output capture
 
-`codex-exec` keeps network access OFF on purpose: **new dependencies and any network step are
-installed by a human**, not by codex. If a task needs a new package, codex must STOP and report it;
-the orchestrator installs it, then re-dispatches.
+`-o`/`--output-last-message` writes ONLY codex's final message; `--json` streams the structured event
+stream (incl. `thread.started`, which carries the session id) to a discarded trace; `--color never` +
+`-c hide_agent_reasoning=true` + `-c model_reasoning_summary=none` strip colour and chain-of-thought.
+Net effect: the wrapper prints just the final answer. **Reasoning still runs at `xhigh`** — quality is
+unchanged; only the *noise* is dropped. On success `codex-exec` extracts the session id from the trace
+and records it to `${CODEX_SESSION_FILE:-./.codex-last-session}` (so `--resume-last` can find it) and
+echoes `session: <id>` to stderr. On a missing/empty final-message file it falls back to the trace tail
+(loud, never silent).
 
-## Escalation & approvals
+## Quality-first guard (pinned model & effort)
 
-There is **no TTY** in `codex exec`, so `approval_policy=never`: codex never pauses for an interactive
-approval. Any action that would need escalation (network, writes outside the repo, an ambiguous
-decision) is **refused and reported**, and the orchestrator handles it by hand. Codex must never run a
-git write command — the orchestrator commits after reviewing the diff.
+The wrappers default `CODEX_MODEL=gpt-5.5` and `CODEX_EFFORT=xhigh` and **refuse** (exit 2, loud) any
+non-default — delegated work always uses the frontier model at max effort; quality is never traded for
+quota. `CODEX_PROBE=1` relaxes this for a throwaway, effort-independent probe only (echoed loudly), and
+a probe still runs on the subscription, in the sandbox, with clean capture.
+
+## Passthrough guard (two tiers, after a literal `--`)
+
+`codex-exec` owns the safety + quality policy, so it filters passthrough flags:
 
-## Commit prohibition
+- **Tier 1 — ALWAYS rejected, even under `CODEX_PROBE=1`:** anything that would defeat the policy or the
+  capture — `-c`/`--config`, `-s`/`--sandbox`, `--full-auto`, `--dangerously-bypass-*`, `--oss`,
+  `--local-provider`, `-p`/`--profile`, `-m`/`--model` (the model is pinned via `CODEX_MODEL`), and the
+  capture flags `-o`/`--output-last-message`/`--json`/`--color`/`--output-schema`/`--ephemeral`.
+- **Tier 2 — context/discovery knobs, rejected for a real run but allowed under `CODEX_PROBE=1`:**
+  `--add-dir`, `-C`/`--cd`, `--skip-git-repo-check`, `--ignore-rules`, `--enable`/`--disable`.
 
-Delegated codex runs do not own repository history. The wrappers' contract prohibits every git write:
-no branch, add, commit, stash, reset, checkout, tag, or history rewrite. The orchestrator reviews the
-diff, runs final verification, and commits only when that is the desired next step.
+Args passed WITHOUT the `--` separator are rejected (a likely mistake), never silently dropped. Need
+more than the wrapper allows? Invoke `codex` directly — outside the subscription/policy guarantees.
 
-## `resume` caveat
+Note that `--skip-git-repo-check` (tier 2) only relaxes **codex's own** git-repo check; the wrapper's
+preflight still **requires a git work tree and a root `AGENTS.md`** and STOPs first if either is
+missing — passing it does not let `codex-exec` run outside a repo.
+
+## Network-OFF invariant (exec)
 
-`codex exec resume` re-dispatches an existing session without re-sending context. **It may not
-re-accept `--sandbox` / `approval_policy` / network flags** — do not assume the original posture
-carries over. Restate the policy in the resumed instruction, or start a fresh `codex-exec` run when a
-guaranteed sandbox/network posture matters.
+`codex-exec` keeps network access OFF on purpose: **new dependencies and any network step are installed
+by a human**, not by codex. If a task needs a new package, codex must STOP and report it; the
+orchestrator installs it, then re-dispatches.
+
+## Escalation & approvals
+
+There is **no TTY** in `codex exec`, so `approval_policy=never`: codex never pauses for an interactive
+approval. Any action that would need escalation (network, writes outside the repo, an ambiguous
+decision) is **refused and reported**, and the orchestrator handles it by hand.
+
+## Commit prohibition — enforced by a git-write shim
+
+Delegated codex runs do not own repository history. Beyond the prompt contract (no branch/add/commit/
+stash/reset/checkout/tag/rewrite), `codex-exec` **physically enforces** the boundary: it writes a `git`
+shim into a temp dir and prepends that dir to the codex subprocess's `PATH`. codex spawns `git` via
+`execve`, which bypasses exported shell functions, so the boundary must be a real executable file. The
+shim:
+
+- passes a **read-only allowlist** through to the real git (`status`, `diff`, `show`, `log`, `ls-files`,
+  `rev-parse`, `cat-file`, `for-each-ref`, …);
+- treats `git config` as **read-only** — blocked on any write/action flag (`--add`/`--unset`/…) or a
+  `<name> <value>` set form (≥2 positionals);
+- **blocks every other / unknown verb** (`add`, `commit`, `reset`, `checkout`, `merge`, `push`, `tag`,
+  `update-ref`, `symbolic-ref`, `reflog`, …) with exit 13;
+- bakes the **real git path into the shim itself** (never exposed as an env var — that would be a
+  trivial bypass vector).
+
+This is defence-in-depth beside the prompt contract; the orchestrator still reviews the diff and commits.
+
+## Precomputed review diff (`codex-review code`)
+
+`code` mode does NOT make codex discover the diff. The wrapper assembles the full surface — repo file
+map (`git ls-files`), `git status`, staged + unstaged diff, and the **contents** of every untracked
+regular file (NUL-safe; binaries noted but skipped, symlinks shown as targets, other non-regular paths
+skipped) — into a git-dir-local temp file (600 perms), then feeds it in. A **clean tree exits 0** before
+a run is spent. If the assembled payload exceeds `CODEX_REVIEW_MAX_TOTAL_BYTES` (default `1500000`) it is
+passed **by path** (read-fence carve-out) instead of inline — **never truncated**. `-s read-only` is
+kept so codex may still read surrounding in-repo files for context.
+
+### Optional structured findings
+
+`CODEX_REVIEW_SCHEMA=1` adds `--output-schema` with a flexible schema (`findings[]` of
+`severity`/`location`/`issue`/`suggested_change`/optional `evidence`, plus `verdict` and free-text
+`notes`). `--output-schema` *constrains* the output (a probe confirmed it does not silently emit
+non-conforming text); a raw-text retry covers a rare validation/run failure. Default OFF.
+
+### Review read-fence (best-effort env hygiene)
+
+`codex-review` runs under a throwaway `HOME` + `XDG_CONFIG_HOME`/`XDG_CACHE_HOME`/`XDG_DATA_HOME` with an
+**absolute `CODEX_HOME`** so auth + history still resolve while codex's default config/cache/skill-scan
+roots point at an empty dir (trims the roaming + skill-scan noise). This is **env hygiene, NOT a security
+boundary** — absolute paths anywhere on disk remain readable under `read-only`; the real read-scoping is
+the prompt fence ("do not read outside the working tree, except the precomputed-diff temp file").
+
+## `resume` — resets posture, restated via `-c`
+
+`codex exec resume` re-dispatches an existing session without re-sending context. It **rejects the
+posture flags** `-s`/`--add-dir`/`-C` and **resets** the sandbox/approval/network posture (it DOES
+accept `-c`/`-m`/`--last`/`-o`/`--json` on 0.142.3 — the wrapper just doesn't need `-o`/`--json` here).
+The `codex-exec --resume`/`--resume-last` entrypoint handles the reset: it restates the entire policy
+via `-c` (`sandbox_mode=workspace-write`, `approval_policy=never`,
+`sandbox_workspace_write.network_access=false`) plus the pinned `-m`/effort and `--ignore-user-config`,
+reads the session id from the sidecar (or an argument), and captures codex's final message straight
+from stdout (no `-o` needed). Only a *raw* `codex exec resume` outside the wrapper loses the posture.
+
+## Hard timeout
+
+A backgrounded/hung run survives otherwise, so both wrappers wrap codex in `timeout`/`gtimeout`
+(`--kill-after=15s`): `CODEX_HARD_TIMEOUT` defaults to **3600s (exec)** / **1800s (review)**, sized for a
+slow `xhigh` run. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
+`timeout` nor `gtimeout` is on `PATH`, the wrapper **warns loudly and runs uncapped** — never a silent
+no-op.
 
 ## Subscription / config invariant
 
@@ -70,27 +159,41 @@ Both wrappers, before invoking codex:
 - preflight `codex login status` and refuse unless it contains `Logged in using ChatGPT`;
 - preflight a git work tree and a root `AGENTS.md`, failing fast (before a run is spent) if missing.
 
-## Verified commands & flags (v0.140.0)
+## Native `codex review` is out of scope (why)
+
+`codex review` is the CLI's built-in review subcommand, but this skill does **not** ship it. Its flag
+surface (0.142.3) is `-c`/`--strict-config`/`--enable`/`--disable`/`--uncommitted`/`--base`/`--commit`/
+`--title` — crucially it **rejects** `--ignore-user-config`, `-s`, `-m`, `-o`, `--json`,
+`--output-schema`. Without `--ignore-user-config` a
+personal `~/.codex/config.toml` loads (a live run forced `sandbox: workspace-write`), which breaks the
+subscription/config-isolation invariant, and it has no clean-capture flag. `codex-review` runs `codex
+exec` over the precomputed diff instead, keeping every invariant intact.
+
+## Verified commands & flags (v0.142.3)
 
 | Command / flag | Verified behaviour |
 |---|---|
 | `codex exec` | non-interactive run from stdin / a prompt arg (headless, no TTY) |
-| `codex exec resume` | resume an exec session (see the resume caveat) |
-| `codex exec review` | review path reachable under `exec` |
-| `codex review` | repository review path; supports reviewing uncommitted changes |
+| `codex exec resume --last` / `resume <id>` | resume a session; **resets posture & rejects the `-s`/`--add-dir`/`-C` posture flags** (accepts `-c`/`-m`/`--last`/`-o`/`--json`) — restate posture via `-c` |
+| `codex review` | built-in review subcommand — **NOT used** (rejects `--ignore-user-config`; see above) |
 | `codex login` / `codex login status` | subscription auth flow + status check |
-| `codex sandbox` / `codex apply` / `codex resume` | sandbox / apply / resume helper subcommands |
-| `-c key=value` | override a config value (dotted path, TOML-parsed) — how policy is set deterministically |
+| `-c key=value` | override a config value (dotted, TOML-parsed) — how policy is set deterministically |
 | `--sandbox <mode>` | `read-only` \| `workspace-write` \| `danger-full-access` (this skill uses the first two) |
 | `-c approval_policy=never` | never pause for interactive approval (required: exec has no TTY) |
 | `-c sandbox_workspace_write.network_access=false` | network OFF under workspace-write (the exec invariant) |
-| `-m <model>` | model to use (wrapper default `gpt-5.5` via `CODEX_MODEL`) |
-| `-c model_reasoning_effort=<effort>` | reasoning effort (wrapper default `xhigh` via `CODEX_EFFORT`) |
+| `-c hide_agent_reasoning=true` / `-c model_reasoning_summary=none` | drop chain-of-thought from output (reasoning still runs) |
+| `-o, --output-last-message <f>` | write ONLY the final message (clean capture) |
+| `--json` | structured event stream (`thread.started` ⇒ session id) |
+| `--output-schema <f>` | constrain output to a JSON schema (`CODEX_REVIEW_SCHEMA=1`) |
+| `-m <model>` | model (wrapper default `gpt-5.5`, pinned via `CODEX_MODEL`) |
+| `-c model_reasoning_effort=<effort>` | reasoning effort (wrapper default `xhigh`, pinned via `CODEX_EFFORT`) |
 | `--ignore-user-config` | do NOT load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME` |
-| `--add-dir <dir>` | extra writable dir alongside the workspace |
-| `-C, --cd <dir>` | use `<dir>` as the working root |
-| `--skip-git-repo-check` | allow running outside a git repo (exec normally requires one) |
-| `--ephemeral` | do not persist session files |
+| `--color never` | disable ANSI colour in output |
+
+## Environment variables
+
+`CODEX_MODEL`, `CODEX_EFFORT`, `CODEX_HARD_TIMEOUT`, `CODEX_SESSION_FILE`, `CODEX_REVIEW_MAX_TOTAL_BYTES`,
+`CODEX_REVIEW_SCHEMA`, `CODEX_PROBE` — see the knob table in [`../SKILL.md`](../SKILL.md#environment-knobs).
 
 ## Troubleshooting
 
@@ -101,5 +204,7 @@ Both wrappers, before invoking codex:
   `codex login status` → `Logged in using ChatGPT`.
 - **`must run inside a git working tree` / `no root AGENTS.md`** (wrapper preflight): run the wrapper
   from the target project root.
+- **`exceeded the hard cap`** (exit 124/137): the run hit `CODEX_HARD_TIMEOUT` — raise it for a
+  known-healthy slow run, or narrow the task, then re-dispatch.
 - **codex wants to install a dependency**: it can't (network OFF in exec) — install it by hand, then
   re-dispatch.

package/bridges/codex-cli-bridge/setup/README.md

@@ -11,7 +11,7 @@ confirm it is on `PATH`:
 
 ```bash
 npm install -g @openai/codex     # or: brew install codex  (use the current official channel)
-codex --version                  # this skill was verified with codex-cli 0.140.0 or newer
+codex --version                  # this skill was verified with codex-cli 0.142.3 or newer
 ```
 
 The binary is **`codex`**. If `codex --version` works but the wrappers can't find it, fix your
@@ -70,7 +70,11 @@ if it reports a missing git work tree or root `AGENTS.md`, run it from a project
 
 - The wrappers are **subscription-only** by design and will not use api-key billing.
 - `codex-exec` runs a **workspace-write** sandbox with **network OFF**; `codex-review` runs
-  **read-only**. See [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md).
+  **read-only**. They also pin the frontier model/effort (refusing a downgrade), enforce a hard
+  timeout, capture only codex's final message, and block codex from writing git via a shim — see
+  [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md) and the knob table in
+  [`../SKILL.md`](../SKILL.md#environment-knobs). No setup is needed to enable these — they are on by
+  default.
 - `codex exec` requires a git repository, and the wrappers also require a root `AGENTS.md`. The
   orchestrator commits, not codex. Re-run `codex login` only when the cached login expires or the
   account changes.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.15.2",
+  "version": "1.17.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.15.2",
+  "version": "1.17.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/commands.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// commands.mjs — the kit's canonical command catalog + the pure invocation router behind the
+// `/agent-workflow-kit help` index and the safe unknown-invocation routing rule.
+//
+// Until now the modes existed only as `### Mode:` headers in SKILL.md, never enumerated for the user:
+// there was no discoverable command surface and no executable answer to "what did the user actually
+// invoke?". This module is the SINGLE source of truth for both — one frozen catalog (one entry per
+// mode, grouped + tagged read-only/writer/guarded with a plain-language one-liner) that the `help`
+// mode renders and the report footers point at, plus `routeInvocation(token)` that maps a raw
+// subcommand token to its mode.
+//
+// Safety invariant (pinned by the tests): `bootstrap` is a writer and the BARE/EMPTY invocation maps
+// to it — that is the ONE acknowledged exception, itself guarded downstream by the existing
+// "docs/ai/ exists → ask upgrade-vs-bootstrap" check (SKILL.md Mode: bootstrap). The invariant is
+// therefore: NO unrecognized/garbage token ever maps to a writer/guarded mode — every such token
+// routes to `help`, which is read-only.
+//
+// Source of truth = the COMMANDS table below; a drift-guard test (commands.test.mjs) pins its keys to
+// the `### Mode:` headers in SKILL.md, so the catalog cannot silently drift from the documented modes.
+// Pure, dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { pathToFileURL } from 'node:url';
+
+const SKILL_NAME = 'agent-workflow-kit';
+const BARE_INVOCATION = `/${SKILL_NAME}`;
+const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
+
+// ── kinds ────────────────────────────────────────────────────────────────────────
+// read-only — never writes, never commits, never runs a subscription CLI.
+// writer    — writes files (a project deployment or a settings/skill placement).
+// guarded   — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// `writer` and `guarded` are the "acts on the system" kinds; only an explicit known token may reach
+// one (plus the bare bootstrap exception). Garbage routes to `help` (read-only) — see routeInvocation.
+export const READ_ONLY = 'read-only';
+export const WRITER = 'writer';
+export const GUARDED = 'guarded';
+const KINDS = new Set([READ_ONLY, WRITER, GUARDED]);
+
+// ── groups (fixed render order) ────────────────────────────────────────────────────
+export const GROUP_ORDER = Object.freeze(['Inspect', 'Configure', 'Orchestrate', 'Lifecycle']);
+
+// ── the canonical catalog ──────────────────────────────────────────────────────────
+// One entry per `### Mode:` in SKILL.md. `key` is the mode (and, for every non-bootstrap mode, the
+// routable subcommand token — bootstrap is the bare invocation, so it has no token). `oneLine` is
+// plain-language: NO internal terms (no reconcile/fence/stamp/manifest/anchor) a third-party user
+// hasn't read SKILL.md for. The drift-guard test pins these keys to the SKILL.md headers.
+const CATALOG = [
+  {
+    key: 'bootstrap',
+    invocation: BARE_INVOCATION,
+    group: 'Lifecycle',
+    kind: WRITER,
+    oneLine: 'Deploy the memory & workflow system into a new or empty project (asks visibility, language, and attribution first).',
+  },
+  {
+    key: 'upgrade',
+    invocation: invocationOf('upgrade'),
+    group: 'Lifecycle',
+    kind: WRITER,
+    oneLine: 'Bring an existing deployment up to the current version — your authored notes are preserved.',
+  },
+  {
+    key: 'uninstall',
+    invocation: invocationOf('uninstall'),
+    group: 'Lifecycle',
+    kind: GUARDED,
+    oneLine: 'Remove only what setup placed; it never deletes your notes and always previews before changing anything.',
+  },
+  {
+    key: 'status',
+    invocation: invocationOf('status'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Show what is installed and at what version, your settings and backends, and what is deployed in this project.',
+  },
+  {
+    key: 'backends',
+    invocation: invocationOf('backends'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Check which optional review/execute backends (codex, agy) are set up versus missing, and the next step.',
+  },
+  {
+    key: 'help',
+    invocation: invocationOf('help'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'List every command, grouped, marking each as read-only or as one that makes changes.',
+  },
+  {
+    key: 'setup',
+    invocation: invocationOf('setup'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Set up an optional backend — place its helper and link its commands onto your PATH (opt-in; preview first).',
+  },
+  {
+    key: 'velocity',
+    invocation: invocationOf('velocity'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Seed a read-only command allowlist so routine read-only commands stop prompting (Claude Code; opt-in; preview first).',
+  },
+  {
+    key: 'recipes',
+    invocation: invocationOf('recipes'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated) and which one fits this environment.',
+  },
+  {
+    key: 'procedures',
+    invocation: invocationOf('procedures'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Show a named activity’s steps and which recipe applies at each stage here.',
+  },
+];
+
+// Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime
+// (Object.freeze on the array alone leaves the entry objects writable).
+export const COMMANDS = Object.freeze(CATALOG.map((c) => Object.freeze(c)));
+
+// The mode every garbage/unrecognized token routes to. Read-only by contract (see routeInvocation).
+export const UNKNOWN_INVOCATION_MODE = 'help';
+// The mode the bare/empty invocation maps to — the one writer reachable without an explicit token,
+// guarded downstream by the docs/ai upgrade-vs-bootstrap check.
+export const BARE_INVOCATION_MODE = 'bootstrap';
+
+const byKey = new Map(COMMANDS.map((c) => [c.key, c]));
+// Routable subcommand tokens = every mode except bootstrap (whose invocation is the bare default).
+const ROUTABLE_TOKENS = new Set(COMMANDS.filter((c) => c.key !== BARE_INVOCATION_MODE).map((c) => c.key));
+
+export const commandFor = (key) => byKey.get(key) ?? null;
+export const kindOf = (key) => byKey.get(key)?.kind ?? null;
+
+// ── the pure router ────────────────────────────────────────────────────────────────
+// routeInvocation(token) → a mode key. `token` is the subcommand the user typed — either the raw word
+// (`upgrade`) OR the full slash form (`/agent-workflow-kit upgrade`); the first word is significant
+// and trailing args are ignored. Precise semantics:
+//   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
+//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/uninstall/help)
+//     → that mode
+//   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
+export const routeInvocation = (token) => {
+  if (token == null) return BARE_INVOCATION_MODE;
+  const trimmed = String(token).trim();
+  if (trimmed === '' || trimmed === BARE_INVOCATION) return BARE_INVOCATION_MODE;
+  // Accept either the raw subcommand token OR the full slash invocation the user types — strip a
+  // leading `/agent-workflow-kit ` prefix so `/agent-workflow-kit upgrade` routes like `upgrade`.
+  const rest = trimmed.startsWith(`${BARE_INVOCATION} `)
+    ? trimmed.slice(BARE_INVOCATION.length).trim()
+    : trimmed;
+  if (rest === '') return BARE_INVOCATION_MODE;
+  const first = rest.split(/\s+/)[0];
+  return ROUTABLE_TOKENS.has(first) ? first : UNKNOWN_INVOCATION_MODE;
+};
+
+// ── render ──────────────────────────────────────────────────────────────────────────
+
+const KIND_TAG = { [READ_ONLY]: '[read-only]', [WRITER]: '[writer]   ', [GUARDED]: '[guarded]  ' };
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+
+// formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
+// catalog order within each group. The header states the index itself is read-only.
+export const formatHelp = () => {
+  const invocWidth = Math.max(...COMMANDS.map((c) => c.invocation.length));
+  const lines = [
+    `${SKILL_NAME} — command index (this list is read-only)`,
+    '',
+    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first).',
+  ];
+  for (const group of GROUP_ORDER) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    lines.push('', group);
+    for (const c of inGroup) {
+      lines.push(`  ${pad(c.invocation, invocWidth)}  ${KIND_TAG[c.kind] ?? c.kind}  ${c.oneLine}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+// The machine form behind `--json`: the flat catalog (machines group by `group` themselves) plus the
+// two routing anchors, so a consumer can reproduce routeInvocation without re-deriving the rules.
+export const buildJson = () => ({
+  skill: SKILL_NAME,
+  groupOrder: [...GROUP_ORDER],
+  unknownInvocationMode: UNKNOWN_INVOCATION_MODE,
+  bareInvocationMode: BARE_INVOCATION_MODE,
+  commands: COMMANDS.map(({ key, invocation, group, kind, oneLine }) => ({ key, invocation, group, kind, oneLine })),
+});
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────
+const main = (argv) => {
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(buildJson(), null, 2));
+    return;
+  }
+  console.log(formatHelp());
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));
+
+export { KINDS, SKILL_NAME, BARE_INVOCATION };