greprag 5.58.0 → 5.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.58.0",
+  "version": "5.59.0",
   "description": "GrepRAG — agent memory for Claude Code, Codex, and OpenCode.",
   "main": "dist/index.js",
   "bin": {

package/skill/greprag/docs/codex-chip.md

@@ -4,9 +4,18 @@ Use a chip when parallel work needs an independent Codex task and repository
 isolation. A chip is a new app-server thread, not a native subagent.
 
 ```bash
-greprag codex chip spawn "<task>" --name <slug> --owns "src/area/**"
+greprag codex chip goal create --objective "<objective>" \
+  --final-state "<observable final state>" --criterion <id>:"<acceptance>"
+greprag codex chip spawn "<task>" --name <slug> --title "<Purview>" \
+  --goal-id <goal-id> --covers <id> --owns "src/area/**"
 ```
 
+Native-v4 sends the full mission, selected model/effort, and worktree in the
+initial `create_thread`. There is no bootstrap task and no second assignment.
+The initial hook binds the lease before tools; attach emits `IN-FLIGHT` and
+starts monitoring only. A single task is `Chip: <Purview>`. Multi-chip missions
+use `LEAD: <Mission>` and unique `Chip A/B/C: <Specific Purview>` identities.
+
 The standard/default profile is `gpt-5.6-luna` at `xhigh`. Use
 `--profile complex` (or `--complex`) for `gpt-5.6-sol` at `high` when the chip
 owns orchestration or unusually difficult work. Explicit `--model <model-id>`
@@ -25,13 +34,16 @@ greprag codex chip steer <id|name> "<correction>"
 greprag codex chip stop <id|name>
 ```
 
-The child commits inside its isolated checkout and runs `greprag codex chip report`.
+The child commits inside its isolated checkout and runs `greprag codex chip report`,
+mapping concrete `--evidence criterion-id:proof` to every covered criterion.
 The host validates the receipt and imports only that unique branch. The parent reviews
 the reported commit and integrates it. Never ask the child to merge, push, or
-delete its own checkout. After integration, the parent runs:
+delete its own checkout. After review and integration, the parent explicitly
+accepts the goal, then follows each returned closeout entry—archive the native
+Codex task first, then run its exact cleanup command:
 
 ```bash
-greprag codex chip cleanup <id|name>
+greprag codex chip goal accept <goal-id> --summary "<review judgment>"
 ```
 
 Messages between the parent and child use the normal GrepRAG session inbox, so

package/skill/templates/chip-leader.md

@@ -11,6 +11,31 @@ plans the whole mission *before* any worker deploys and reconciles them *after*.
 Topology is a planning decision, not an execution afterthought — draw the map
 before mobilizing the troops.
 
+## Codex Desktop standard
+
+For Codex, the leader first creates one durable mission goal with objective,
+observable final state, and criterion IDs. The leader task is named
+`LEAD: <Mission>`. Before dispatch it assigns each workstream a unique letter
+and human purview—`Chip A: <Specific Purview>`, `Chip B: ...`—plus disjoint
+leases and explicit `--covers` criteria. Every spawn uses `--multi-chip`, its
+`--label`, and its proper `--title`.
+
+Dispatch uses the native-v4 `createRequest` exactly once. It contains the real
+mission, the parent-selected model/effort, and native worktree setup; never send
+a bootstrap prompt or a second assignment. The initial hook binds before tool
+use, the leader applies the exact task title as soon as the resolved task ID is
+available, attach emits `IN-FLIGHT`, and the child reports evidence through the
+parent's breakthrough inbox.
+
+Closeout is parent-owned and immediate: review each report and commit, integrate
+it, verify the whole mission, explicitly accept the goal, then follow each
+returned closeout entry (archive the native task first; run its cleanup command).
+A report is not acceptance, cleanup never implies
+acceptance, and an accepted/integrated child should not remain in the active
+task list. These rules supersede any Claude `spawn_task`, Block 1/Block 2, or
+manual worktree instructions later in this shared template when operating in
+Codex.
+
 **Hard fire:** the moment you're about to spawn the **2nd chip**, stop and plan.
 Spawn-then-plan is the exact failure this prevents.
 

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

@@ -9,17 +9,26 @@ 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: `. Every spawned worker title
-begins `Chip: `; the native handoff supplies the exact title.
+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 write chip declares non-overlapping ownership leases; research uses
-`--read-only`. The parent session id is mandatory.
+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> \
@@ -56,27 +65,30 @@ 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-v3` handoff. Pass `createRequest`
-exactly to native `create_thread`: `target.type=project`, the supplied Codex
-`projectId` from `list_projects`, and `environment.type=worktree` with
-`startingState={type:"branch", branchName}`.
+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.
-Do not add `cwd`, `title`, `model`, or `effort`—they are not valid create fields.
+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.
-Wait for the bootstrap/auto-title turn to settle and verify the nonce-bearing
-`bootstrapAck`. Resolve `threadId` + actual cwd with `list_threads`/`read_thread`.
-Then call `set_thread_title` with the exact `Chip: ` name (`LEAD: ` for an
-orchestrator) and read it back twice. Retry the rename at most three times if
-auto-title overwrites it; fail loudly if it will not remain exact. Only then run
+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. Rerun handoff again and deliver `sendRequest` via
-`send_message_to_thread`. The enforced order is create → settle → rename →
-verify → attach → IN-FLIGHT → mission. This two-phase send applies
-`model` + `thinking` after creation because high/xhigh validation rejects a
-worktree `startingState` create request. A standalone CLI cannot
+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.
 
@@ -97,11 +109,14 @@ 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. The parent
-reviews/integrates and runs `greprag codex chip cleanup <id>` only afterward.
-After a verified squash/cherry-pick (where the exact report commit is not an
-ancestor), the parent acknowledges integration with `cleanup <id> --integrated`;
-ordinary merge ancestry remains automatic.
+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
@@ -117,7 +132,7 @@ 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/bootstrap proof,
+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
@@ -131,9 +146,13 @@ Useful recovery commands:
 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.