greprag 5.65.2 → 5.65.4

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

@@ -6,14 +6,15 @@ Use `greprag load codex-chip-spawn` for the three-primitives method:
   worktree, manifest, inbox, or goal);
 - quick mode: rename the current task `LEAD: <Mission>` and directly spawn
   1–2 visible `Chip A/B: <Specific Purview>` worktree tasks;
-- Leader mode: create a separate `LEAD: <Mission>` task before spawning
+- Leader mode: rename the current task `PLANNER: <Mission>`, then create a
+  separate `LEAD: <Mission>` task before that LEAD spawns
   `Chip A/B/C: <Specific Purview>` children for seams or larger orchestration.
 
 Normal chips are writable and own discovery, design, implementation, tests, and
 commit. Preserve the Codex-provided worktree, committed result artifact, and
 parent cleanup. The child opening prompt starts with the exact visible title
-alone (`Chip A: <Specific Purview>`, `LEAD: <Mission>`, `ADVISOR: <Purview>`, or
-`MECHANIC: <Mission>`) and then has exactly three sections:
+alone (`Chip A: <Specific Purview>`, `LEAD: <Mission>`, `PLANNER: <Mission>`,
+`ADVISOR: <Purview>`, or `FIX: <one friction unit>`) and then has exactly three sections:
 `Setup — do this FIRST`, `Task`, and `Report when done`. It has no lease,
 read-only, mandatory nested-goal, or nonce/ACK requirement. Completion is the
 native Codex parent-child task reply: commit the durable result, then reply to

package/skill/templates/chip-leader.md

@@ -1,4 +1,4 @@
-# Leader Mission
+# Planner + Leader Mission
 
 Load this method when the work needs a dedicated orchestrator: more than the
 quick 1–2 visible chips, shared files or contracts, ordering, integration, or
@@ -6,13 +6,23 @@ another coordination seam.
 
 ## Identity first
 
-Before any child is created, the orchestrating task becomes the dedicated
-leader by renaming itself exactly:
+This is the explicit Leader shape. Before any child is created, the initiating
+task becomes the planner by renaming itself exactly:
+
+```text
+PLANNER: <Mission>
+```
+
+The PLANNER then creates one separate task whose exact first-line title is:
 
 ```text
 LEAD: <Mission>
 ```
 
+Do not leave the initiator unnamed, and do not name it LEAD when it creates a
+separate LEAD. The title split makes planning authority and execution
+leadership visible before fanout.
+
 Children use the exact ordinal discoverability schema:
 
 ```text
@@ -24,13 +34,21 @@ Chip C: <Specific Purview>
 Naming identifies the workstream and makes the task legible. It does not grant
 execution authority; every child remains an ordinary writable chip.
 
+<!-- adr: adr/codex-lead-native-goal.md -->
+After the PLANNER creates it and before fanout, the dedicated LEAD creates a
+native top-level mission goal with `create_goal`, then runs `get_goal` and
+verifies the active goal names this mission before fanout. That native goal
+tracks the LEAD mission; it is not a GrepRAG lease, durable manifest, or child
+permission gate.
+
 ## Quick versus Leader
 
 - **Quick:** the current task renames itself `LEAD: <Mission>` and directly
   spawns 1–2 children. No separate leader task is created.
-- **Leader:** the initiator creates a separate `LEAD: <Mission>` task. That
-  dedicated task owns decomposition, child dispatch, seam reconciliation,
-  checks, integration, parent messaging, and cleanup.
+- **Leader:** the initiator first renames itself `PLANNER: <Mission>`, then
+  creates a separate `LEAD: <Mission>` task. That dedicated task owns
+  decomposition, child dispatch, seam reconciliation, checks, integration,
+  parent messaging, and cleanup.
 
 This template is for the second shape. If the mission fits the quick shape,
 load `greprag load codex-chip-spawn` and keep the initiator as the implicit
@@ -56,14 +74,18 @@ ordering in the brief rather than relying on hidden coordination metadata.
 
 ## Dispatch and closeout
 
-1. Rename the leader task before the first child spawn.
-2. Spawn each `Chip A/B/C: <Specific Purview>` with its own visible worktree
-   and the mission context it needs.
-   A child titled exactly `MECHANIC: <Mission>` must make `greprag load mechanic`
-   its first Setup action before diagnosis or edits.
-3. Keep children writable and let them investigate, edit, test, and commit
+1. Rename the initiating task `PLANNER: <Mission>` before any child creation.
+2. Create the separate `LEAD: <Mission>` task; do not dispatch worker chips
+   directly from the PLANNER.
+3. In the dedicated LEAD, create the native top-level mission goal with
+   `create_goal`, then verify it with `get_goal`.
+4. From the LEAD, spawn each `Chip A/B/C: <Specific Purview>` with its own
+   visible worktree and the mission context it needs.
+   A `FIX: <one friction unit>` child must make `greprag load mechanic` its
+   first Setup action before diagnosis or edits.
+5. Keep children writable and let them investigate, edit, test, and commit
    within their worktrees.
-4. Require each child to return `DONE` or `BLOCKED` through the native
+6. Require each child to return `DONE` or `BLOCKED` through the native
    parent-child task result, including the commit, checks, and caveats. Use
    `greprag send` only for explicit cross-harness or peer messaging:
 
@@ -73,9 +95,9 @@ ordering in the brief rather than relying on hidden coordination metadata.
      --from-session <child-session>
    ```
 
-5. Review reports, reconcile seams in the planned order, run the whole-mission
+7. Review reports, reconcile seams in the planned order, run the whole-mission
    checks, and send the parent a concise closeout.
-6. The parent owns integration and cleanup. Do not silently delete a child
+8. The parent owns integration and cleanup. Do not silently delete a child
    worktree or treat a report as acceptance.
 
 Do not introduce a separate read-only, lease, nested-goal, or delivery-proof

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

@@ -6,12 +6,13 @@ authority.
 
 ## Identity first
 
-For any coordinated multi-chip mission, rename the orchestrating task before
-spawning children:
+Choose the mission shape before naming the current task:
 
-```text
-LEAD: <Mission>
-```
+- **Quick mode:** rename the current task `LEAD: <Mission>` before spawning
+  1–2 children. No separate leader task exists.
+- **Leader mode:** rename the current initiating task `PLANNER: <Mission>`
+  before creating a separate `LEAD: <Mission>` task. Once a separate LEAD
+  exists, the PLANNER never presents itself as the LEAD.
 
 Then name children with the exact ordinal schema:
 
@@ -21,10 +22,15 @@ Chip B: <Specific Purview>
 Chip C: <Specific Purview>
 ```
 
-In quick mode, the current task renames itself `LEAD: <Mission>` and directly
-spawns 1–2 children. It is the **implicit LEAD**; no separate leader task is
-created. In Leader mode, the initiator creates a separate `LEAD: <Mission>`
-task, and that LEAD spawns and manages the children.
+The identity transition happens before the first child creation. In Leader
+mode the `PLANNER:` task creates only the dedicated `LEAD:` first; that LEAD
+then spawns and manages `Chip A/B/C`.
+
+<!-- adr: adr/codex-lead-native-goal.md -->
+A dedicated `LEAD: <Mission>` task must create a native top-level mission goal
+with `create_goal`, then run `get_goal` and verify the active goal names the
+mission before any child fanout. This is Codex-native mission tracking, not a
+GrepRAG durable manifest, lease, or permission gate.
 
 ## Three primitives
 
@@ -52,12 +58,12 @@ dispatch `Chip A` and `Chip B` directly.
 - Children are writable ordinary chips. Do not add a read-only role, lease,
   mandatory nested goal, or delivery-proof gate.
 - Role models come from the Codex model policy slots: `chip.worker`,
-  `chip.leader`, `chip.advisor`, and `chip.mechanic`. Inspect the active policy
-  with `greprag codex models show`; override a single child only with explicit
-  `--model` / `--effort` flags when needed.
+  `chip.leader`, `chip.planner`, `chip.advisor`, and `chip.fix`. Inspect the
+  active policy with `greprag codex models show`; override a single child only
+  with explicit `--model` / `--effort` flags when needed.
 - Select the role slot from the first-line title before dispatch:
-  `Chip A/B/C` -> `chip.worker`, `LEAD` -> `chip.leader`, `ADVISOR` ->
-  `chip.advisor`, and `MECHANIC` -> `chip.mechanic`. ABOUT TO call
+  `Chip A/B/C` -> `chip.worker`, `LEAD` -> `chip.leader`, `PLANNER` ->
+  `chip.planner`, `ADVISOR` -> `chip.advisor`, and `FIX` -> `chip.fix`. ABOUT TO call
   `codex_app__create_thread`? STOP - pass that slot as top-level `model` and
   `thinking`; never rely on Codex Desktop defaults for a visible chip.
 - An `ADVISOR: <Purview>` child is a lead-facing consultant. It reports
@@ -76,11 +82,16 @@ dispatch `Chip A` and `Chip B` directly.
 
 Use this when the work is more than the quick 1–2-chip shape, or when shared
 files, contracts, ordering, integration, or a seam require a dedicated
-orchestrator. The initiator creates the separate `LEAD: <Mission>` task first.
-That LEAD decomposes the mission, assigns exact `Chip A/B/C: <Specific Purview>`
+orchestrator. The initiator renames itself `PLANNER: <Mission>`, then creates
+the separate `LEAD: <Mission>` task first. That LEAD decomposes the mission,
+assigns exact `Chip A/B/C: <Specific Purview>`
 titles, dispatches ordinary writable chips, reconciles their reports, and owns
 integration checks and cleanup.
 
+Before dispatching any child, the LEAD creates and verifies its native
+top-level mission goal (`create_goal` -> `get_goal`). Child fanout starts only
+after that verified goal exists.
+
 Load `greprag load chip-leader` for the mission worksheet before dispatch.
 
 ## Codex Desktop dispatch route
@@ -146,10 +157,9 @@ dedicated `LEAD: <Mission>` task.
 ## FIX missions — the one landing exception
 
 Landing authority follows the MISSION SHAPE, not the harness
-(adr/codex-landing-doctrine.md). Every chip shape above (`Chip A/B/C`, `LEAD`,
-`ADVISOR`, `MECHANIC`) keeps the parent-owned landing: commit, native reply
-with archive clearance, and the parent reviews, integrates, archives, and
-cleans up.
+(adr/codex-landing-doctrine.md). Every non-FIX chip shape above (`Chip A/B/C`,
+`LEAD`, `PLANNER`, `ADVISOR`) keeps the parent-owned landing: commit, native reply with
+archive clearance, and the parent reviews, integrates, archives, and cleans up.
 
 A mission whose first line begins `FIX:` — emitted by `greprag fix spawn`
 (grepragOS law 4) — is the ONE exception: it carries its own Phase 3
@@ -189,9 +199,13 @@ Chip <Label>: <Specific Purview>
 ## Setup — do this FIRST
 Stay in the Codex-provided isolated worktree; do not create a second worktree.
 Read AGENTS.md and the session-start recap, then inspect the current repo state.
-No leases, read-only mode, or goals.
-If the exact first-line title is `MECHANIC: <Mission>`, make `greprag load
-mechanic` the first Setup action before diagnosis or edits.
+If the exact first-line title is `LEAD: <Mission>`, create a native top-level
+mission goal with `create_goal`, then run `get_goal` and verify the active goal
+names this mission before any child fanout.
+No leases, read-only mode, or GrepRAG goal gates.
+If the exact first-line title is `FIX: <one friction unit>`, make `greprag
+load mechanic` the first Setup action before diagnosis or edits; mechanic is
+the doctrine, not the visible task identity.
 If the exact first-line title is `ADVISOR: <Purview>`, report consultation to
 the LEAD only: strategic findings, questions, tradeoffs, and recommendations.
 Do not write operator-facing completion language or decide/spawn worker chips.
@@ -217,5 +231,6 @@ and cleans up.
 
 The first line is the exact visible title, alone. Substitute the appropriate
 discoverability label: `Chip A: <Specific Purview>`, `LEAD: <Mission>`,
-`ADVISOR: <Purview>`, or `MECHANIC: <Mission>`. These labels do not change
-execution authority.
+`PLANNER: <Mission>`, `ADVISOR: <Purview>`, or `FIX: <one friction unit>`. These labels do not change
+execution authority, except that FIX carries the one-friction Phase 3 contract
+printed by `greprag fix spawn`.