greprag 5.74.9 → 5.74.11

package/skill/templates/codex-chip-spawn.md

@@ -1,95 +1,102 @@
 # Codex Chip Spawn Method
 
-Use this for Codex visible child tasks. Claude-side `spawn_task` rules do not
-apply to Codex: Codex creates the task, selects its workspace, and provides the
-native parent-child reply channel.
-
-## Roles and models
-
-The exact first-line title selects the governance and model slot:
-
-| Title | Purpose | Model slot |
-| --- | --- | --- |
-| `Chip A/B/C: <Specific Purview>` | Independent implementation worker | `chip.worker` |
-| `LEAD: <Mission>` | Own and integrate a multi-chip mission | `chip.leader` |
-| `PLANNER: <Mission>` | Create and brief a separate LEAD | `chip.planner` |
-| `ADVISOR: <Purview>` | Read-only consultation to the LEAD | `chip.advisor` |
-| `FIX: [harness\|doctrine\|injection\|env\|code] <one friction unit>` | Root-cause repair | `chip.fix` |
-
-Check active slots with `greprag codex models show`. Pass the selected slot as
-top-level `model` and `thinking` in `codex_app__create_thread`; do not rely on
-Codex Desktop defaults for a visible chip.
-
-## Mode selection
-
-- 1-2 visible tasks: rename the current task `LEAD: <Mission>` and
-  spawn `Chip A` / `Chip B` directly.
-- More chips or shared seams: rename the current task `PLANNER: <Mission>`,
-  create a separate `LEAD: <Mission>` first, then that LEAD spawns children.
-- Bounded same-session work: use `greprag load codex-subagent-spawn` instead.
-
-A dedicated `LEAD: <Mission>` creates a native top-level goal with
-`create_goal`, verifies it with `get_goal`, then fans out children. PLANNER is
-a handoff role: after briefing the LEAD it goes quiet until completion,
-blocker, explicit decision request, or operator intervention.
-
-## Workspace selection and project preflight
-
-Standard writable chips use the current project with
-`environment: { "type": "worktree" }`. For a FIX chip, run
-`greprag fix spawn` in the source project and honor its top-level
-`workspaceMode` without a fail-then-fallback attempt:
-
-- `workspaceMode=worktree`: use the project worktree target. Before the call,
-  check the saved project/main repo for `.codex/environments/environment.toml`.
-  If missing, stop and set up the repo first with the `codex-environments`
-  skill.
-- `workspaceMode=local`: use the project local target. The source has no usable
-  Git HEAD, so do not initialize Git, invoke `codex-environments`, or request a
-  worktree. This is the project-local task path with serialized writes: the
-  caller yields file writes until the FIX chip reports back.
-- Non-FIX writable chips remain worktree-only.
-- Missing for `PLANNER` or `ADVISOR` consultation: local/projectless fallback
-  is allowed only when the prompt explicitly forbids writes and no child
-  worktree dispatch happens until the repo environment exists.
-
-## Dispatch
-
-Call `codex_app__create_thread` once as a standalone tool call:
+Codex has no Claude Code `pre-spawn-check` validator over `spawn_task`. The
+agent writes the exact first-line title + Block 1 + task body + Block 2 into
+the prompt itself, then dispatches exactly once with
+`codex_app__create_thread`. Codex task creation proves dispatch only; the
+child's native `IN-FLIGHT` reply proves launch/setup.
+
+> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a
+> single objective, you should already be inside a chip-leader plan — your
+> **base branch** and **merge target** (the integration branch, *never* master)
+> come from it. If you're not, stop and run `greprag load chip-leader` first.
+> A lone chip targeting its own objective proceeds here directly.
+
+## What the agent provides
+
+- `title: "Chip A: <verb-phrase>"` — exact first prompt line. Use the
+  leader-assigned label (`A`/`B`/`C`...) per workstream, for example
+  `"Chip B: Build freshness engine"`. The label is the shared handle the
+  leader and chip both use end-to-end (title -> report-back self-ID -> merge
+  references). Dedicated orchestration titles are exact too: `PLANNER:
+  <Mission>`, `LEAD: <Mission>`, `ADVISOR: <Purview>`, and `FIX:
+  [type] <one friction unit>`.
+- `prompt:` — exact title line + Block 1 + task body + Block 2 (templates
+  below).
+- The first-line title also selects the model slot:
+  `Chip A/B/C` -> `chip.worker`, `LEAD` -> `chip.leader`, `PLANNER` ->
+  `chip.planner`, `ADVISOR` -> `chip.advisor`, `FIX` -> `chip.fix`.
+- `target:` — Codex project target. Writable worktree chips must include the
+  prepared branch as `startingState`; this is the required Codex parameter
+  Claude does not have:
 
 ```json
 {
   "target": {
     "type": "project",
     "projectId": "<current-project-id>",
-    "environment": { "type": "<worktree|local>" }
+    "environment": {
+      "type": "worktree",
+      "startingState": { "type": "branch", "branchName": "<prepared chip branch>" }
+    }
   },
-  "prompt": "<Block 1 + Task + Block 2>",
+  "prompt": "<exact title + Block 1 + Task + Block 2>",
   "model": "<selected role model>",
   "thinking": "<selected role effort>"
 }
 ```
 
-Creation success proves dispatch, not successful startup. If the result is
-ambiguous, do not retry blindly: use `list_threads` for the expected title,
-inspect candidates with `read_thread`, and retry only after proving no matching
-task exists.
+- `model:` / `thinking:` — select with `greprag codex models show`; pass them
+  top-level in `codex_app__create_thread`, not by relying on Desktop defaults.
 
-## Block 1 - Setup and startup acknowledgement
+`workspaceMode=local` FIX tasks keep the same required Codex shape but use the
+project-local environment and omit `startingState`:
 
-Paste this at the top of the child prompt after the title.
+```json
+{
+  "target": {
+    "type": "project",
+    "projectId": "<current-project-id>",
+    "environment": { "type": "local" }
+  },
+  "prompt": "<exact title + Block 1 + Task + Block 2>",
+  "model": "<selected role model>",
+  "thinking": "<selected role effort>"
+}
+```
+
+Codex has no `mode: interactive` create-thread field. If the chip must pause
+for human input, put that requirement in the task body and make the child
+report `BLOCKED` with the decision needed.
+
+## Block 1 — Setup (verbatim, substitute `<exact-title>`, `<branch>` + mode)
+
+`<exact-title>` = the first prompt line. `<branch>` = the prepared chip branch
+used in `startingState.branchName`. `workspaceMode` comes from the dispatch
+path; standard chips and `workspaceMode=worktree` FIX chips are already in a
+Codex worktree environment.
+
+````
+**Setup — do this FIRST:**
 
 ```text
 ## Setup - do this FIRST
-Stay in the selected workspace and inspect the current repository state.
+Stay in the Codex-provided selected workspace and inspect the current
+repository state.
 Applicable AGENTS.md instructions and the session-start recap are already in
-context. Do not create another worktree; a `workspaceMode=local` FIX stays in
-the project directory and never initializes Git.
-Bootstrap this checkout before build/test: if `scripts/ensure-npm-deps.cjs`
-exists, run `node scripts/ensure-npm-deps.cjs`; if
-`scripts/worktree-bootstrap.cjs` exists, run
-`node scripts/worktree-bootstrap.cjs`. Never link or junction `node_modules` to
-another checkout.
+context.
+Do not create another worktree. Standard chips and `workspaceMode=worktree`
+FIX chips are already in the Codex worktree environment created from
+`startingState.branchName`. A `workspaceMode=local` FIX stays in the project
+directory, never initializes Git, never requests a worktree, and requires the
+caller to yield file writes until the FIX chip reports back.
+Bootstrap this checkout before build/test: if `scripts/worktree-bootstrap.cjs`
+exists, run `node scripts/worktree-bootstrap.cjs`; if only
+`scripts/ensure-npm-deps.cjs` exists, run `node scripts/ensure-npm-deps.cjs`.
+Never link or junction `node_modules` to another checkout.
+When running build/test or other env-driven commands, use
+`node scripts/codex-run.cjs -- <command ...>` if that wrapper exists. It loads
+ignored env files from the main checkout; never copy or print secrets.
 After setup and bootstrap succeed, reply to the LEAD in the native Codex task
 thread:
 `IN-FLIGHT: <exact title> — setup complete; work started`
@@ -111,25 +118,36 @@ the LEAD only: findings, questions, tradeoffs, and recommendations. Do not
 write operator-facing completion language or decide/spawn worker chips.
 ```
 
-## Task body
+The `IN-FLIGHT` reply is non-negotiable — without it the parent assumes the
+Codex task exists but was not successfully launched.
 
-Keep the actual work dominant:
+---
+````
+
+**Multi-chip mission (`greprag load chip-leader`)?** The first-line title alone
+is not enough because Codex can auto-title before the child is renamed. The
+parent or LEAD must set the exact registry/task title immediately after the
+task appears, then read it back twice before treating the title as durable:
 
 ```text
-## Task
-Outcome: <observable result>
-Problem and evidence: <failure, request, or proof motivating the work>
-Relevant files/contracts: <starting points; child still owns discovery>
-Constraints and prior decisions: <invariants that must survive>
-Seams and integration order: <shared contracts/order, or none>
-Acceptance: <checks/evidence that mean done>
-Own repository discovery, design, implementation, tests, and commit; do not
-wait for a parent-authored implementation plan.
+set_thread_title "<exact-title>"
+read_thread -> exact title
+read_thread -> exact title again after the retry delay
 ```
 
-## Block 2 - Report back
+The leader dictates the exact string (for example `Chip A: Converter format
+coverage`). Single chips still use the exact title, but skip leader-assigned
+registry retitle planning.
+
+## Block 2 — Report back (verbatim, substitute `<branch>` + LEAD task)
 
-Paste this at the end of the child prompt.
+Use the native Codex parent-child task-message channel for Codex-to-Codex
+completion. Do not substitute `greprag send` for normal Codex child reports.
+
+````
+---
+
+**Block 2 — Report back via native Codex task reply:**
 
 ```text
 ## Report when done
@@ -161,45 +179,72 @@ worktree pruning. If review is needed, the parent creates a fresh review
 chip/session.
 ```
 
-## FIX contract
-
-For `FIX:` tasks, the mission printed by `greprag fix spawn` is the source of
-truth. The FIX chip keeps the existing route and carries its type in the title,
-for example `FIX: [doctrine] stale skill text sent Codex to Claude rules`.
-Type means durable repair surface: `harness` hooks/watchers/task dispatch,
-`doctrine` load entries/skills/rendered instructions, `injection`
-recap/Capture/doc-pointer/stateful injection, `env` bootstrap/deps/scripts, and
-`code` product/source behavior. It identifies the exact friction, makes the
-smallest durable root-cause fix, explains why it works, verifies and commits
-it, then hands it to the parent delivery owner.
-
-Removal comes first: remove offending doctrine, gates, controls, duplication,
-or wrong boundaries before adding guidance. Add prose or controls only when
-removal cannot solve the friction. Data-only repair rows and diagnosis do not
-require a writable task.
-
-## After spawning
-
-- Wait for the child-confirmed native `IN-FLIGHT` reply; task creation alone
-  does not prove setup/bootstrap succeeded.
-- In `workspaceMode=local`, yield parent file writes until the FIX chip reports
-  back; both tasks share the same project directory.
-- Use native Codex parent-child task replies for Codex-to-Codex reporting.
-- Use `greprag send` only for explicit cross-harness or fallback coordination.
-- Contact same-project Codex peers through `codex_app.list_threads` scoped by
-  `cwd`, then `codex_app.send_message_to_thread`. Coordination asks only about
-  blockers, owned dirt, or sequencing constraints; peer review is a separate
-  child task.
-
-## Parent cleanup
-
-After integration, the parent may clear remaining GrepRAG manifest/branch
-bookkeeping with:
+**Cleanup discipline (HARD RULE):** chip prompts forbid `git clean`,
+`git reset --hard`, `git checkout <other>`, raw recursive delete outside the
+selected workspace, manual worktree deletion, or manual Codex managed-checkout
+pruning.
+````
+
+## After spawning — wait for native IN-FLIGHT (HARD RULE)
+
+The chip reports back to the LEAD through native Codex task replies. Nothing
+else proves it launched correctly: `create_thread` success proves only that
+Codex accepted the dispatch. So immediately after `codex_app__create_thread`
+returns, resolve the visible task, set the exact title, read it back twice, and
+wait for:
+
+```text
+IN-FLIGHT: <exact-title> — setup complete; work started
+```
+
+If `create_thread` returns a generic/transport failure, treat it as ambiguous
+success. Do not call `create_thread` again until recovery checks prove no
+existing task exists: use `list_threads` for the expected title or manifest id,
+inspect candidates with `read_thread`, and recover a matching visible task
+before retrying.
+
+Use native Codex task replies for Codex-to-Codex reporting. Use `greprag send`
+only for explicit cross-harness or fallback coordination; a stored GrepRAG row
+is not proof that an idle Codex task woke or acted.
+
+**Launch state:** the Block 1 `IN-FLIGHT` reply is your only signal the child
+actually entered its selected workspace and completed setup. No `IN-FLIGHT` =
+assume the task is not launched, blocked, or not yet set up — don't wait on
+results from a chip that never started.
+
+## Before composing
+
+`greprag fix list --repaired --scope chip-startup --limit 20 --project <chip-project> --format markdown` — already scoped, no slicing. If non-empty, paste at top of body as `**Project Fixes (do not re-discover):**`. Do not use `fix search` for this pull.
+
+## Merge before testing globally (HARD RULE)
+
+Chips never `npm link` from the worktree — dangling symlinks silently break the
+CLI everywhere. To test a built CLI globally: merge through the repo delivery
+path first, then install from the main checkout.
+
+## Parent merge discipline — cleanup after integration (HARD RULE)
+
+When you (the parent) integrate a Codex chip branch — through the canonical
+commit path or a profile-declared merge — clear the Codex chip bookkeeping in
+the same breath after the child's `Archive: yes` report and merge:
 
 ```bash
 greprag codex chip cleanup <id> --native-archived
 ```
 
 The child archives its own task after sending `Archive: yes`; the parent does
-not perform routine child-task archival. Codex owns managed-worktree pruning.
-Local-mode FIX tasks have no worktree or branch to prune.
+not perform routine child-task archival. The parent may delete the branch after
+merge. Codex owns managed-worktree pruning, and the cleanup command records the
+archive-safe attestation before removing managed checkout state. Local-mode FIX
+tasks have no worktree or branch to prune.
+
+**FIX chips use the same delivery owner.** A `greprag fix spawn` mission is the
+source of truth for FIX behavior. `fix spawn` detects usable Git history and
+emits `workspaceMode`: Git uses an isolated worktree; non-Git, unavailable
+Git, or no commit uses the project-local task with serialized writes. Dispatch
+honors that mode without trying a worktree first. The FIX chip identifies the
+exact friction, makes the smallest durable root-cause fix, verifies and
+checkpoints it, then reports the commit/result and cleanup parameters to the
+parent delivery owner. It creates no human landing gate. If no live parent
+exists and the chip carries the full-goal mission, it becomes delivery owner
+and follows the repo profile.

package/skill/templates/os.md

@@ -52,11 +52,14 @@ project, repo, customer, handle, or unexplained proper noun, search memory for
 that entity before responding when prior context could affect the answer. Do
 not do this for generic nouns or for entities fully defined in the current turn.
 
-## Law 4 — Friction ⇒ fix spawn, at the moment
+For any env, toolchain, worktree, secret, tool, hook, command, correction, or
+repetition friction, search Memory for the exact error/friction plus repo/tool.
+If Memory has a clear overcome, apply it and continue.
 
-Friction — you repeated yourself, fought a tool, got corrected twice on the
-same thing, rediscovered something already known, hit a setup failure that
-wasn't your edit — is fixed at the MOMENT it happens:
+## Law 4 — Unresolved friction ⇒ fix spawn
+
+Escalate only when Memory has no answer, the remembered overcome fails, or the
+same friction repeats:
 
     greprag fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"
 
@@ -66,9 +69,9 @@ wasn't your edit — is fixed at the MOMENT it happens:
   (Claude Code `spawn_task`, Codex `codex_app__create_thread`, opencode
   bootloader) and send the mission as its first message. Method:
   `greprag load chip-spawn`.
-- **One unit = one chip.** A fix chip exists for exactly one unit of
-  friction. Adjacent friction gets its own spawn — a chip that absorbs new
-  friction loses the context each unit needs.
+- **One unresolved unit = one chip.** A fix chip exists for exactly one unit of
+  unresolved friction. Adjacent friction gets its own spawn — a chip that
+  absorbs new friction loses the context each unit needs.
 - **Type = durable repair surface.** `harness` fixes hooks/watchers/task
   dispatch/harness behavior; `doctrine` fixes `greprag load`, bundled skills,
   and rendered AGENTS/CLAUDE instructions; `injection` fixes recap, Capture,
@@ -86,10 +89,10 @@ wasn't your edit — is fixed at the MOMENT it happens:
   the operator before touching code. Rarely can a chip design the durable
   repair alone; the gate is what keeps repairs durable instead of
   workarounds.
-- **Never queue friction for later.** The queue-first reflex (`fix log` →
-  periodic digestion) is retired; the moment that produced the friction
-  holds the context the fix needs. `greprag fix log` survives only for
-  audit trails and design-input notes that are deliberately not chips.
+- **Never queue unresolved friction for later.** The queue-first reflex
+  (`fix log` → periodic digestion) is retired; the live context belongs with
+  the fix chip. `greprag fix log` survives only for audit trails and
+  design-input notes that are deliberately not chips.
 - Every repair is ROOT-CAUSE: fix the pattern that makes the friction class
   possible, never a guard on today's trigger.
 
@@ -98,4 +101,4 @@ wasn't your edit — is fixed at the MOMENT it happens:
 If the operator explains the same thing twice, the explanation belongs in a
 durable surface — a skill, a load entry, a STATE block, an ADR — not in the
 conversation. Hand-taught doctrine that stays in chat dies with the session;
-that is itself friction (Law 4 applies).
+that is itself unresolved friction (Law 4 applies).

package/skill/templates/codex-subagent-spawn.md

@@ -1,34 +0,0 @@
-# Codex Internal Subagent
-
-Use an internal subagent for ephemeral, same-session work: a bounded research
-pass, comparison, review, edit, or test whose result can return directly to the
-current task.
-
-## Contract
-
-- Load this method with `greprag load codex-subagent-spawn` when the shape is
-  not already in context.
-- The subagent is ephemeral and same-session. It has no visible worktree task,
-  durable manifest, inbox identity, or goal.
-- Keep concurrency at `max_threads=6` and recursion at `max_depth=1`.
-- Give it one specific question or purview and ask for a compact result with
-  evidence. `fast_scan` is read-only; `routine_worker` and `deep_worker` may
-  perform bounded edits/tests in the parent workspace.
-- Use the configured model slots: `subagent.fast_scan`, `subagent.routine_worker`,
-  and `subagent.deep_worker`. Inspect them with `greprag codex models show`.
-- The parent prevents overlapping concurrent edits and owns the final judgment,
-  integration, and any commit that should outlive the session.
-- Do not use it for independent worktree isolation, parent-visible lifecycle
-  reporting, or work that must outlive the session; choose a quick chip instead.
-
-## Compact brief
-
-```text
-Subagent purview: <one bounded question>
-Context: <the files or facts it may inspect>
-Return: <decision / findings / recommended next step>
-```
-
-Internal subagents do not need `greprag send`; their result is returned to the
-initiating task. If you need a visible child identity, report, or cleanup
-boundary, stop using this primitive and load `codex-chip-spawn`.