greprag 5.57.0 → 5.59.0

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

@@ -0,0 +1,158 @@
+# Codex Chip Spawn
+
+This is the Codex Desktop chip method. It is separate from Claude Code
+`spawn_task`: never use or copy the Claude Block 1/Block 2 prompt here.
+
+## Gate: one chip or a mission?
+
+A single independent task proceeds directly. If two or more chips target one
+objective, or you are about to create a second chip, stop and run `greprag load
+chip-leader`. Plan the integration branch, ownership seams, dependency order,
+merge order, and whole-feature test gate before another spawn. Rename the
+orchestrating task so its title begins `LEAD: <Mission>`. Multi-chip workers are
+uniquely named `Chip A: <Specific Purview>`, `Chip B: ...`; a single worker is
+`Chip: <Purview>`. Labels are stable coordination handles, not execution order.
+
+## Prepare the isolated task
+
+Every mission starts with a durable parent-owned goal. Give it a concrete
+objective, final state, and stable acceptance criterion IDs. Every write chip
+declares non-overlapping ownership leases; research uses `--read-only`.
+
+```bash
+greprag codex chip goal create \
+  --objective "<concrete objective>" \
+  --final-state "<observable final state>" \
+  --criterion <id>:"<acceptance statement>"
+
+greprag codex chip spawn "<independent task>" \
+  --name <slug> \
+  --title "<Properly Capitalized Purview>" \
+  --goal-id <goal-id> --covers <criterion-id> \
+  --owns "<path/**>" \
+  --codex-project-id <desktop-project-id> \
+  --parent-session <parent-thread-id> \
+  --json
+```
+
+The parent/`LEAD:` selects each worker model before dispatch; the child never
+self-selects or changes it. Defaults are exact:
+
+- **Standard — `gpt-5.6-luna` / `xhigh`:** bounded single-owner execution with
+  clear acceptance criteria: scoped implementation, tests, docs, or focused
+  research/review.
+- **Complex — `gpt-5.6-sol` / `high`:** use when *any* hard signal applies:
+  orchestration/decomposition; multi-chip integration or merge arbitration;
+  architecture/API/schema decisions; cross-cutting ownership; ambiguous
+  requirements needing synthesis; high-risk migration/security/accounting
+  correctness; or novel diagnosis with multiple interacting hypotheses.
+
+In multi-chip missions the `LEAD:` itself is Sol/high, but it classifies every
+worker independently—workers do not inherit Sol. Complex selection requires a
+concise `--model-reason` plus one or more `--complexity-signal` values:
+`orchestration`, `multi-chip-integration`, `architecture-api-schema`,
+`cross-cutting-ownership`, `ambiguous-synthesis`, `high-risk-correctness`, or
+`novel-multi-hypothesis-diagnosis`. Explicit `--model`/`--effort` overrides are
+supported and require `--model-reason`; standard records its rubric reason by
+default. Native Desktop `thinking` uses the callable enum and is checked against
+the selected model's advertised effort matrix.
+An arbitrary custom native model also requires `--native-model-verified`, which
+means the parent verified it on the Desktop surface before dispatch. The
+manifest persists profile/model/effort, parent session in
+`selectedBy`, reason, and matched signals.
+
+Native Desktop is the default runtime.
+`--runtime cli` is opt-in and only valid when PATH Codex `model/list` actually
+exposes the requested model and effort; validation remains fail-loud.
+
+For a multi-chip mission every spawn also uses `--multi-chip --label A` (then B,
+C...) and a different `--title`. Duplicate active slugs, labels, or purview
+titles fail loudly.
+
+The spawn command creates a unique starting branch, records the manifest and
+lease, and returns a `greprag-codex-native-v4` handoff. Pass `createRequest`
+exactly to native `create_thread`: it already contains the full real mission,
+selected `model`, `thinking`, project target, and worktree starting branch.
+`expectedBaseSha` is the attach-time commit invariant behind that reserved branch.
+This is the only assignment turn. Never create a bootstrap task and never send
+the mission again after attach.
+
+Creation returns `clientThreadId` while Codex builds its own detached worktree.
+The initial `UserPromptSubmit` hook provisionally binds the manifest and native
+cwd before tool use. Resolve `threadId` + actual cwd immediately, then call
+`set_thread_title` with the exact handoff title and read it back twice. Retry at
+most three times if auto-title overwrites it; fail loudly if it will not remain
+exact. `create_thread` has no title field, so the mission's first line carries
+the correct identity immediately and task metadata is renamed as soon as the
+resolved task exists. Only then run
+`verifyTitleCommand`, rerun handoff, and run `attachCommand`. Attach validates
+project/base/sandbox attestation, writes the marker, sends parent `IN-FLIGHT`,
+and starts the monitor. The enforced order is create-real-mission → provisional
+bind → resolve → rename/verify → attach → IN-FLIGHT → monitor. A standalone CLI cannot
+invoke the Desktop-owned surface, so it prepares rather than pretending an old
+PATH app-server successfully ran a 5.6 turn.
+
+## Mandatory parent inbox lifecycle
+
+The child must address the recorded parent session, not a bare mailbox:
+
+- `IN-FLIGHT` immediately after it starts work.
+- `DONE` before ending, with commit + checks, by running the exact `codex chip
+  report` command in its opening prompt.
+- `BLOCKED` before ending when it cannot finish, by running the exact `codex
+  chip block` command.
+- If the work crosses the selected model boundary, send a breakthrough message
+  explaining the new signal. The parent decides whether to steer or relaunch;
+  the child never swaps models autonomously.
+
+The attached host monitor validates receipts from the recorded native cwd,
+exact base ancestry, clean state, and every changed path against the lease. A
+detached HEAD is valid; the host imports the reported exact commit into the
+reserved chip ref, then sends the terminal inbox event. The
+child never merges, pushes, cleans up, or edits the parent checkout. Reports map
+concrete evidence to every covered goal criterion. The parent reviews the diff,
+integrates it, and runs `greprag codex chip goal accept <goal-id> --summary
+"<review judgment>"` only when all criteria and chips are satisfied. For a
+verified squash/cherry-pick add `--integrated <chip-id>` to acceptance. Acceptance
+returns machine-readable closeout entries: apply each native `archiveRequest`
+first, then its exact `cleanupCommand`. Cleanup does not imply acceptance, is
+refused before it, and requires `--native-archived` for native tasks.
+
+Native chips have a receipt deadline (default 180 minutes; override with
+`--native-timeout-minutes`). This standalone CLI cannot query Desktop-private
+turn status, so it never guesses that a settled task succeeded: write *and read*
+chips must submit `report`/`block`, and timeout fails loudly. One live monitor
+per chip is enforced. `reconcile` expires unattached setup after 10 minutes,
+retires stale blocked chips after 24 hours, and surfaces terminal-delivery
+failure. Lifecycle inbox sends validate HTTP status, target session, sender
+session, and durable event receipts; a duplicate monitor cannot double-send.
+If initial `IN-FLIGHT` delivery fails, attach remains verified and retryable
+instead of terminally stranding the task. Server-side idempotency serializes
+the claim and preserves the originally resolved target across retries.
+
+The native worktree sandbox is the physical boundary. Verification accepts only
+the Codex-issued `client-new-thread:<uuid>` token (or its bare UUID form), a
+distinct resolved UUID task ID, the expected project/base proof,
+an attested `workspace-write` sandbox, and a Git root beneath Codex's own
+`worktrees` directory at the exact base commit. Hook guards require the exact
+bound task/cwd/sandbox and deny out-of-lease file tools, destructive
+Git/cleanup, and symlink/junction creation; link-based escape is never allowed.
+Generated verify/attach/report commands pin resolved stable Node and CLI paths,
+so restarting Codex does not invalidate an in-flight chip contract.
+
+Useful recovery commands:
+
+```bash
+greprag codex chip handoff <id> --json
+greprag codex chip status <id>
+greprag codex chip steer <id> "<follow-up>"
+greprag codex chip resume <id>
+greprag codex chip stop <id>
+```
+
+For a native chip, `steer` emits a `send_message_to_thread` handoff. Stop fails
+loud until the parent interrupts the Desktop task, then confirms that fact with
+`stop <id> --native-interrupted`; the CLI never records a false cancellation.
+After restart/usage interruption, use `resume`, deliver its handoff, and wait for
+the nonce-bound breakthrough acknowledgment. A delivered message without that
+ack is not recovery. Cleaned/cancelled/failed tasks cannot resume; relaunch them.