claude-dev-env 1.93.1 → 1.95.0

package/skills/closeout/reference/issue-body-templates.md

@@ -0,0 +1,108 @@
+# Issue body templates
+
+Body shapes for the parent tracking issue and its child issues, plus a worked example. Every body is self-contained: a reader with zero session context understands it. Every body carries a quoted line of evidence captured this session. Write each body to a temp file and pass it with `gh issue create --body-file <path>`.
+
+## Contents
+
+- [Child issue body](#child-issue-body)
+- [Parent tracking issue body](#parent-tracking-issue-body)
+- [Worked example — child](#worked-example--child)
+- [Worked example — parent](#worked-example--parent)
+- [Body rules](#body-rules)
+
+## Child issue body
+
+One obstacle per child. Fill every section:
+
+```markdown
+## What happened
+
+<One sentence: the failure mode, in plain terms.>
+
+## Evidence
+
+<The verbatim line captured this session — error text, command, or log line — in a fenced block.>
+
+```
+<exact quoted text>
+```
+
+## Where
+
+<The file, hook, gate, or tool the evidence names. Path relative to the repo root.>
+
+## Impact
+
+<What the obstacle cost: work blocked, count of times hit, workaround forced.>
+
+## Proposed fix
+
+<The specific change. Name the failure mode and the condition, not "improve error handling".>
+```
+
+## Parent tracking issue body
+
+The parent gathers the children. Its body is a checklist, one line per child created:
+
+```markdown
+## Session closeout — <short session label>
+
+Obstacles this session, filed as child issues:
+
+- [ ] owner/repo#<N> — <child title>
+- [ ] owner/repo#<N> — <child title>
+- [ ] owner/repo#<N> — <child title>
+
+## Handoff
+
+A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
+```
+
+## Worked example — child
+
+```markdown
+## What happened
+
+The code_rules_enforcer hook blocked a valid list literal in a test file, where test files are exempt from the magic-value gate.
+
+## Evidence
+
+```
+BLOCKED: [MAGIC_VALUE] Inline list literal [200, 404, 500] in a function body -- extract to a named constant in config/.
+```
+
+## Where
+
+packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py — the inline-collection check.
+
+## Impact
+
+Hit 3 times in one session on three test files. Forced a workaround: moving each literal to a module constant the test did not need.
+
+## Proposed fix
+
+Extend the test-file exemption that already covers the magic-value gate to also cover the inline-collection check, so list and set literals in test bodies pass.
+```
+
+## Worked example — parent
+
+```markdown
+## Session closeout — hook exemptions for test files
+
+Obstacles this session, filed as child issues:
+
+- [ ] jl-cmd/claude-dev-env#101 — inline-collection gate fires in exempt test files
+- [ ] jl-cmd/claude-dev-env#102 — boolean-naming gate flags a fixture variable
+
+## Handoff
+
+A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
+```
+
+## Body rules
+
+- **Quoted evidence is required.** No child ships without a fenced block holding a line captured this session.
+- **No volatile paths.** No temp dirs, worktrees, `$CLAUDE_JOB_DIR`, `.claude-editor/jobs`, or `.claude/worktrees` paths in any body. Paste text inline; for a binary artifact, upload it to a durable release and link that URL.
+- **No chat references.** Drop "as discussed" and "the choice we picked". State each fact on its own.
+- **Specific over vague.** "The gate fires on `[200, 404, 500]` in a test body" beats "the gate is too strict".
+- **PII stripped.** Run the PII pass (see the PII redaction checklist) over every body before it reaches the confirmation gate.

package/skills/closeout/reference/pii-redaction-checklist.md

@@ -0,0 +1,36 @@
+# PII redaction checklist
+
+The PII pass runs on every closeout run, over every issue body and over the handoff prompt, before the confirmation gate. Repository visibility changes how aggressive the redaction is — public repos get the strictest pass — never whether the pass runs.
+
+## The pass
+
+Read each drafted body and the handoff prompt line by line. For every match below, swap the real value for the placeholder. When a value is load-bearing for the fix (a hook needs the exact path shape), keep the shape and drop the private part — `~/.claude/hooks/<hook>.py`, not the full home path.
+
+| Category | What to catch | Swap |
+|---|---|---|
+| Email | Any address | `<email>` |
+| Real name | A person's name in a path, log line, or account | `<name>` |
+| Home path | A user home directory | `~/` or `<home>/` |
+| Private host / IP | A LAN host, NAS name, private IP | `<host>` |
+| SSH user / port | A login user or non-standard port | `<user>`, `<port>` |
+| Account id | A store, cloud, app, or master-user id | `<account-id>` |
+| Token / secret | An API key, token, or credential | `<redacted>` |
+| Private repo name | An unpublished owner/repo | `<owner>/<repo>` |
+| Sheet / DB / script id | A Neon, Sheet, or Apps Script id | `<id>` |
+
+## Public versus private aggression
+
+| Target repo | Aggression |
+|---|---|
+| Public (ships to a public host, open source) | Strictest: redact every category above, and any value a stranger could tie to a person or a private system. When in doubt, redact. |
+| Private (internal, team-only) | Redact tokens, secrets, credentials, and emails without exception. Keep internal host and path shapes only when the fix needs them. |
+
+## After the pass
+
+- List every redaction made, so the confirmation gate shows the user what changed.
+- When a redaction removes a value the fix needs, note it as an open question for the user in the gate — do not guess a replacement.
+- A body that still holds a match after the pass does not reach the gate. Re-run the pass until every match is swapped.
+
+## Why the pass is unconditional
+
+An issue is a durable post on a shared server. A private value in an issue body outlives the session and the person who typed it. Running the pass on every body, public or private, keeps a leak from landing where it cannot be pulled back.

package/skills/copilot-finding-triage/SKILL.md

@@ -1,19 +1,25 @@
 ---
 name: copilot-finding-triage
 description: >-
-  Sorts each Copilot gate finding from a converge run into one of two tiers and
-  routes it: a self-healing finding is auto-fixed, pushed, and counted toward
-  convergence with no user page, while a code concern pages the user over ntfy
-  and holds the run behind a 45-minute gate. Triggers: 'copilot finding triage',
-  'user review gate', 'tier copilot findings', 'triage the copilot gate'.
+  Sorts each Copilot gate finding from a converge run into one of two tiers, then
+  verifies each code concern with an executed check before routing it: a
+  self-healing finding is auto-fixed, pushed, and counted toward convergence with
+  no user page; a confirmed or refuted code concern is handled by the run with its
+  check evidence; only a code concern the check leaves inconclusive pages the user
+  over ntfy and holds the run behind a 45-minute gate. Triggers: 'copilot finding
+  triage', 'user review gate', 'tier copilot findings', 'triage the copilot gate'.
 ---
 
 # Copilot Finding Triage
 
-After a converge run's Copilot gate returns its findings, this skill sorts each
-one into a tier and acts on it. Findings scoped to style, type hints, or tests
-heal themselves inside the run. A logic, security, or behavior finding pages the user
-and holds the run until they answer or a 45-minute deadline passes.
+After a converge run's Copilot gate returns its findings, this skill tiers each
+one, verifies every code concern with an executed check, then acts on it.
+Findings scoped to style, type hints, or tests heal themselves inside the run. A
+logic, security, or behavior finding goes to a verifier that runs a check against
+HEAD: a confirmed defect joins the fix round carrying its repro, a refuted claim
+is answered on the thread with the check evidence, and only a finding the check
+leaves inconclusive pages the user and holds the run until they answer or a
+45-minute deadline passes.
 
 ## When this applies
 
@@ -22,7 +28,6 @@ inside one of these callers:
 
 - `autoconverge` — the single-run converge workflow, at its Copilot wait-gate.
 - `pr-converge` — the looping converge workflow, at each Copilot tick.
-- `copilot-review` — the standalone Copilot babysitter.
 
 Each caller already fetches the review and carries a fix-and-push flow. This
 skill decides, per finding, whether that flow runs on its own or waits behind
@@ -40,12 +45,48 @@ Read the complete rubric in `reference/tier-rubric.md`. The short form:
   product decision. Logic or correctness defects, security, data handling,
   error-handling semantics, and concurrency.
 
-A finding that straddles both tiers sorts to CODE CONCERN. Any doubt routes to
-the user gate.
+A finding that straddles both tiers sorts to CODE CONCERN. Any doubt about the
+tier sorts the finding to CODE CONCERN.
+
+## The verification stage
+
+Tiering names who might act; the verification stage between tiering and the user
+gate settles it for every code concern. Each code-concern finding goes to its own
+verifier agent, all in parallel, inside the run. The verifier runs a check
+against the flagged HEAD and returns one of three verdicts.
+
+**The governing rule: a verdict is conclusive only if an actual check was
+executed.** Reading the source and reasoning about it, however sound, never
+produces a conclusive verdict. A check is a concrete command the verifier runs
+against the flagged HEAD — executing the code path with crafted inputs, forcing
+the claimed error condition, or running a purpose-built test — whose captured
+output demonstrates the behavior in question. Each verdict carries
+`{verdict, checkCommand, checkOutput, evidence}`; a conclusive verdict whose
+`checkCommand` or `checkOutput` is empty carries no executed check, so the run
+downgrades it to inconclusive.
+
+- **CONFIRMED** — the check reproduces the defect. The finding becomes
+  self-healing: it joins the fix round carrying its repro. The fix re-runs the
+  same repro check and shows it passes, adds the repro to the test suite as a
+  regression test where the suite covers that surface, lands in one commit and
+  pushes, replies to the thread with the fix SHA plus the before/after check
+  output, and resolves the thread. No page.
+- **REFUTED** — the check shows the code already behaves correctly in the exact
+  scenario the finding claims is broken. The run replies to the thread with the
+  command(s) and captured output, resolves the thread, and counts the finding
+  clean. No page.
+- **INCONCLUSIVE** — everything else: no runnable check exists, the check is
+  infeasible in this environment, the results are ambiguous, or the fix needs a
+  product decision between defensible behaviors. The verifier defaults to
+  inconclusive, and any doubt sorts here. These findings, and only these, flow
+  into the user gate.
+
+A run with zero inconclusive findings never reaches the user gate.
 
 ## Self-healing flow
 
-A self-healing finding never pages the user.
+A self-healing finding never pages the user. This covers a finding tiered
+self-healing and a code concern the verifier confirmed.
 
 1. Fix the finding through the caller's existing fix flow.
 2. Verify the fix.
@@ -54,16 +95,18 @@ A self-healing finding never pages the user.
 
 ## User gate protocol
 
-Run this protocol when one or more CODE CONCERN findings sit on the round's HEAD.
+Run this protocol when one or more code-concern findings stayed inconclusive
+after verification on the round's HEAD.
 
 ### Step 1 — Page the user
 
 Run `scripts/notify_ntfy.py` with:
 
 - `--title` naming the PR.
-- `--message` summarizing each code-concern finding, one line each, as
-  `file:line — severity — one sentence`. Build the body from
-  `templates/notification.md`.
+- `--message` summarizing each inconclusive finding, one line each, as
+  `file:line — severity — one sentence`, followed by the verifier's one-line
+  evidence note stating what check was attempted and why it was not decisive.
+  Build the body from `templates/notification.md`.
 - `--click-url` set to the Copilot review URL, so tapping the page opens the
   review.
 
@@ -82,17 +125,22 @@ moment the script exits zero.
 - If the deadline passes with no answer, run the caller's normal teardown and
   report the un-reviewed findings in the final report.
 
-### Step 3 — Self-healing findings run in parallel
+### Step 3 — Self-healing and confirmed findings run in parallel
 
-Self-healing findings on the same HEAD do not wait for the gate. Fix, verify,
-commit, and push them through the caller's fix flow, and count the round toward
-convergence.
+Self-healing findings and confirmed code concerns on the same HEAD do not wait
+for the gate. Fix, verify, commit, and push them through the caller's fix flow,
+and count the round toward convergence. A confirmed finding carries its repro, so
+its fix re-runs that same check and posts the before/after output on the thread.
 
 ## Gate checklist
 
 - [ ] Every finding on HEAD carries a tier.
 - [ ] Each self-healing finding is fixed, verified, and pushed.
-- [ ] Each code-concern finding appears as one line in the ntfy body.
+- [ ] Each code-concern finding carries a verifier verdict from an executed check.
+- [ ] Each confirmed finding is fixed with its repro re-run and pushed.
+- [ ] Each refuted finding's thread carries the check evidence and is resolved.
+- [ ] Each inconclusive finding appears as one line in the ntfy body with its
+      evidence note.
 - [ ] The page carries the PR name, the per-finding summary, and the review URL.
 - [ ] `scripts/notify_ntfy.py` exited zero before the 45-minute clock started.
 - [ ] The wakeup is armed for 45 minutes from a delivered page.
@@ -102,9 +150,9 @@ convergence.
 
 | Path | Role |
 |------|------|
-| `SKILL.md` | This hub: when it applies, the tier split, the gate protocol. |
-| `reference/tier-rubric.md` | The complete tier rubric and the behavior-safe test. |
-| `templates/notification.md` | The ntfy message body for a code-concern page. |
+| `SKILL.md` | This hub: when it applies, the tier split, the verification stage, the gate protocol. |
+| `reference/tier-rubric.md` | The complete tier rubric, the three verdicts, and the executed-check standard. |
+| `templates/notification.md` | The ntfy message body for an inconclusive-finding page. |
 | `scripts/notify_ntfy.py` | The ntfy publish CLI. |
 | `scripts/test_notify_ntfy.py` | Tests for the publish CLI. |
 
@@ -116,9 +164,13 @@ convergence.
 - **A failed page is not consent.** A failed ntfy POST holds the gate open. It
   does not auto-approve the round. Read the script's non-zero exit as a page that
   never reached the user, and keep the run held.
-- **Doubt sorts to CODE CONCERN.** When a finding could sit in either tier,
-  classify it as a code concern and page the user. The safe default never
-  auto-fixes a finding that might change runtime behavior.
+- **A conclusive verdict needs an executed check.** Source reading, however
+  sound, never confirms or refutes a finding. A confirmed or refuted verdict
+  whose `checkCommand` or `checkOutput` is empty downgrades to inconclusive and
+  pages the user.
+- **Doubt sorts to INCONCLUSIVE.** When an executed check does not pin down the
+  behavior, the verifier defaults to inconclusive and the finding pages the user.
+  The safe default never auto-fixes a finding whose behavior a check did not show.
 - **The 45-minute clock starts at page success.** The timer starts when the page
   reaches the user, which is the moment `scripts/notify_ntfy.py` exits zero, not
   the moment the finding is classified.

package/skills/copilot-finding-triage/reference/tier-rubric.md

@@ -1,17 +1,19 @@
 # Tier Rubric
 
-Every Copilot finding on the round's HEAD sorts into one of two tiers. The tier
-decides who acts: the run fixes a self-healing finding on its own, and the run
-pages the user for a code concern.
+Every Copilot finding on the round's HEAD passes through two stages: tiering,
+then — for a code concern — an executed-check verification stage that decides who
+acts. Tiering sorts a finding into one of two tiers. The run fixes a self-healing
+finding on its own; a code concern goes to a verifier agent, and only a finding
+the verifier leaves inconclusive pages the user.
 
 ## The two tiers
 
-| Tier | Who acts | Page the user | Counts toward convergence |
-|------|----------|---------------|---------------------------|
+| Tier | Next step | Page the user | Counts toward convergence |
+|------|-----------|---------------|---------------------------|
 | SELF-HEALING | The run auto-fixes | No | Yes |
-| CODE CONCERN | The user decides | Yes | Held until the user answers or the deadline passes |
+| CODE CONCERN | An executed-check verifier decides | Only when the verifier's verdict is inconclusive | Confirmed and refuted count; inconclusive holds until the user answers or the deadline passes |
 
-## The test that splits them
+## The test that splits the tiers
 
 A finding is SELF-HEALING when its fix cannot change what a production caller
 observes at runtime. A finding is a CODE CONCERN when its fix changes runtime
@@ -42,8 +44,65 @@ weigh a tradeoff.
 - Concurrency.
 - Anything whose fix changes observable production behavior.
 
-## When a finding sits on the line
+A finding that touches both tiers sorts to CODE CONCERN. Any doubt about the tier
+sorts the finding to CODE CONCERN.
 
-A finding that touches both tiers sorts to CODE CONCERN. Any doubt about whether
-a fix stays behavior-safe routes the finding to the user gate. The safe default
-pages a person; it never auto-fixes a finding that might change runtime behavior.
+## The verification stage
+
+Every code-concern finding goes to its own verifier agent, all in parallel,
+inside the run. The verifier decides one of three verdicts by executing a check
+against the flagged HEAD.
+
+**The governing rule: a verdict is conclusive only if an actual check was
+executed.** Reading the source and reasoning about it, however sound, never
+produces a conclusive verdict. A check is a concrete command the verifier runs
+against the flagged HEAD — executing the flagged code path with crafted inputs,
+forcing the claimed error condition, or running a purpose-built test — whose
+captured output demonstrates the behavior in question. Source inspection points
+the check at the right place; it is never itself grounds for a conclusive verdict.
+
+Each verdict carries `{verdict, checkCommand, checkOutput, evidence}`. A
+conclusive verdict whose `checkCommand` or `checkOutput` is empty carries no
+executed check, so the run downgrades it to inconclusive.
+
+| Verdict | What the executed check shows | Who acts | Page the user |
+|---------|-------------------------------|----------|---------------|
+| CONFIRMED | The check tangibly reproduces the defect | The run auto-fixes | No |
+| REFUTED | The check tangibly shows the code already behaves correctly in the exact scenario the finding claims is broken | The run replies and resolves | No |
+| INCONCLUSIVE | Everything else | The user decides | Yes |
+
+### CONFIRMED
+
+The executed check reproduces the defect; the evidence carries the exact
+command(s) and the captured output. Only a confirmed verdict makes a
+code-concern finding self-healing. The finding joins the round's fix list
+carrying its repro, and the fix:
+
+1. Re-runs the same repro check and shows it passes.
+2. Adds the repro to the repo's test suite as a regression test where the suite
+   covers that surface.
+3. Lands in one commit and pushes.
+4. Replies to the thread with the fix SHA plus the before/after check output,
+   then resolves the thread.
+
+The loop resumes on its own. No page.
+
+### REFUTED
+
+The executed check demonstrates the code already behaves correctly in the exact
+scenario the finding claims is broken. The run replies to the thread with the
+command(s) and captured output, resolves the thread, and counts the finding
+clean. No page.
+
+### INCONCLUSIVE
+
+Everything else: no runnable check exists, the check is infeasible in this
+environment, the results are ambiguous, or the fix needs a product decision
+between defensible behaviors. A finding that is not tangibly reproducible is not
+self-healing. These findings, and only these, flow into the user gate.
+
+## The default is inconclusive
+
+The verifier defaults to inconclusive. Any doubt sorts to inconclusive, and an
+inconclusive finding pages the user. The safe default pages a person; it never
+auto-fixes a finding whose behavior an executed check did not pin down.

package/skills/copilot-finding-triage/templates/notification.md

@@ -13,10 +13,12 @@ Copilot code concern on PR {pr_number}: {short_pr_title}
 ## Body
 
 ```
-{finding_count} code concern(s) need your call on PR {pr_number} ({head_sha}):
+{finding_count} code concern(s) survived verification as inconclusive and need your call on PR {pr_number} ({head_sha}):
 
 - {file_1}:{line_1} — {severity_1} — {one_sentence_concern_1}
+  Check: {evidence_note_1}
 - {file_2}:{line_2} — {severity_2} — {one_sentence_concern_2}
+  Check: {evidence_note_2}
 
 Review: {review_url}
 Reply within 45 minutes or the run tears down and reports these findings unreviewed.
@@ -24,10 +26,13 @@ Reply within 45 minutes or the run tears down and reports these findings unrevie
 
 ## Field notes
 
-- `{finding_count}` counts the CODE CONCERN findings on this HEAD, not the
-  self-healing ones.
+- `{finding_count}` counts the inconclusive findings on this HEAD — the code
+  concerns an executed check left undecided — not the self-healing, confirmed, or
+  refuted ones.
 - Each bullet holds one finding: its `file:line`, its severity, and one sentence
   naming the concern.
+- `{evidence_note_N}` is the verifier's one-line note stating what check was
+  attempted and why it was not decisive.
 - `{review_url}` is the same URL passed as `--click-url`, so the reader sees it
   in the body and reaches it by tapping the message.
 - The 45-minute clock starts when the page reaches the user, which is the moment

package/skills/everything-search/SKILL.md

@@ -13,8 +13,7 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 ## Hard limits
 
-- **Scope every search.** Pass a project path, an `ext:`/`dm:`/`size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds.
-- **Fall back on failure.** When `es.exe` fails or returns nothing, try to start it. if that doesn't work, prompt the user to decide next steps: grep, debug further, etc.
+Scope and fallback policy: `packages/claude-dev-env/rules/es-exe-file-search.md`.
 
 ## Instructions
 

package/skills/grokify/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: grokify
+description: >-
+  Grok Build execution handoff prompt, embed Claude advisor.
+---
+
+# Grokify
+
+## Principle
+
+One paste-ready handoff turns this session's work into a plan a Grok Build session can execute alone. Grok gets no access to this conversation, so the handoff carries everything: repos, findings, constraints, the phased plan, and a Claude advisor Grok reaches through the `claude` CLI.
+
+## Gotchas
+
+- Grok Build cannot spawn Claude subagents. The advisor is an out-of-process `claude -p` session — never write Agent-tool, `session-advisor`, or SendMessage instructions into the handoff.
+- A `--resume` after a usage-limit failover to another binary fails, because a session store belongs to the binary that minted it. The handoff must tell Grok to treat that failure as starting over: re-send the charter plus a compact recap, capture the new `session_id`.
+- Conversation-relative phrases ("as discussed", "the plan above", "the earlier choice") are dead text to Grok — every statement stands on its own.
+- Copy findings' measured numbers and `file:line` citations into the handoff exactly, and label each figure measured, bounded, or unverified.
+- The advisor session starts empty. The bind step must pipe the findings, constraints, and plan into the charter, or every later consult is answered from nothing.
+- `claude` sessions are project-scoped by working directory. The handoff must tell Grok to run every bind and every `--resume` with the cwd set to the repo root it names — a bind launched from the Grok sandbox cwd files the session under that other project, and a later resume from the real worktree reports `No conversation found with session ID`. Treat a session-not-found error as a wrong-cwd or expired-session signal, not a model failure.
+- `--output-format json` returns a JSON array of events, not one object. `session_id` comes from any event; the reply text is the `type == "result"` event's `.result` field. A parser expecting one top-level object reports a missing session id on a working bind.
+- The charter travels as a file piped to stdin, or as one clean argv string. Half-escaped multiline shell expansion mangles the prompt in transit and the advisor sees a fragment.
+
+## When this applies
+
+The user types `/grokify`, alone or with guidance.
+
+- Bare `/grokify`: build the handoff from the current session's context — the task in flight, its findings, plan, and constraints.
+- `/grokify <guidance>`: the guidance names or scopes the task — a plan written earlier in the session, a file to read, or a fresh instruction. Build the handoff for that.
+
+**Refusal:** no session context and no guidance — reply `What should Grok execute? One sentence.` and stop.
+
+## Process
+
+1. Collect the substance: repos and branch, established findings with `file:line` and measured numbers, hard constraints, and the phased plan with acceptance criteria. Pull from session context first, then from the guidance; read any files the guidance names.
+2. Fill `templates/handoff-template.md`. Adapt every bracketed section to the task; keep the advisor CLI commands, signal rules, and consult cadence exactly as the template writes them.
+3. Mark any decision that belongs to the user as an explicit ask-the-user fork inside the plan. The handoff never lets Grok pick silently.
+4. Deliver one fenced markdown block (four-backtick fence, so inner fences survive), then one or two sentences naming the choices you baked in.
+
+## Fixed advisor structure (never vary these parts)
+
+- **Bind once, first:** charter + findings + constraints + plan piped from a temp file into `claude -p --model fable --effort high --output-format json`; parse and save `session_id` from the JSON reply.
+- **Consult:** brief piped into `claude -p --resume <session_id> --model fable --effort high --output-format json`.
+- **ConsultB** If fable is unavailable, use opus with max effort: `claude -p --resume <session_id> --model opus --effort max --output-format json`.
+- **Signals:** every advisor reply opens with exactly one of ENDORSE, CORRECTION, PLAN, or STOP. CORRECTION and PLAN are actions to take, with a report-back in the next consult on that topic. STOP halts that line of work and surfaces it to the user. When the CLI is unreachable, Grok stops and says so — it never self-endorses in the advisor's place.
+- **Cadence, mandatory:** after planning and before any edit; per phase before implementation (TDD red + approach) and after (diff, tests, acceptance evidence); before every `git commit` and `git push`; on every user-facing fork before asking; on any twice-repeated failure or stall.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Trigger, process, fixed advisor structure. |
+| `templates/handoff-template.md` | Section-by-section skeleton of the handoff prompt. |
+
+## Folder map
+
+- `SKILL.md` — the whole workflow.
+- `templates/` — the handoff skeleton.

package/skills/grokify/templates/handoff-template.md

@@ -0,0 +1,92 @@
+# Handoff template
+
+Fill every `[bracketed]` part from the session. Keep the advisor sections word-for-word except the charter's mission sentences.
+
+````markdown
+# Execution Handoff (Grok Build): [task title]
+
+You are Grok, executing this plan yourself on Grok Build. You write the code, run the
+tests, and run the checks. You do NOT decide alone: a standing Claude advisor (Fable High
+tier, or Opus MAX if Fable is unavailable, reached via CLI) reviews every significant step at the cadence below.
+
+## Repos and branch
+
+- [repo, working-tree path, and the branch to develop on; push and PR rules]
+- [any read-only sibling repos and what they are for]
+
+## Established findings (treat as settled)
+
+[Each finding on its own bullet with file:line citations and measured numbers, each
+labeled measured, bounded, or unverified. Include refuted hypotheses so Grok does not
+re-fix them.]
+
+## Hard constraints
+
+[Non-negotiables: values that stay fixed, behavior that stays, repo conventions
+(commit style, test-first rules, where constants live), anything out of scope.
+CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
+
+## The advisor: Claude Fable High / Opus MAX via CLI (bind FIRST, before any change)
+
+**Bind (once, at run start):**
+0. `cd` to the repo root named under Repos and branch — and do the same before every
+   later consult. `claude` sessions are project-scoped by working directory; a bind
+   or resume run from any other cwd (your sandbox, a temp dir) files the session
+   under a different project and later resumes report "No conversation found".
+1. Write the charter to a temp file. Charter text: "You are the standing advisor for a
+   Grok executor working on [one-sentence mission]. You never edit files or run
+   commands; you only answer. Open every reply with exactly one signal word: ENDORSE,
+   CORRECTION, PLAN, or STOP. Each consult brings the delta since the last consult
+   (real output, never a full recap), the live decision or blocker, and load-bearing
+   paths or excerpts. If a consult re-raises something you already answered with
+   nothing new attached, restate the prior answer and name it a restatement." Then
+   append the full Established findings, Hard constraints, and Plan sections of this
+   document to the same file.
+2. Bind: `claude -p --model fable --effort high --output-format json < <charter-file>`
+2a. If 2 fails, replace fable with opus, effort high to max.
+3. The JSON output is an array of events, not one object. Take `session_id` from any
+   event; the reply text is the `type == "result"` event's `.result` field. Persist
+   `session_id`, the repo root, and the cwd to a state file at once.
+4. If the primary `claude` binary is usage-limited, fall back through
+   `python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model fable --effort high --output-format json`.
+   A failover does NOT carry the session_id. On ANY resume failure — failover,
+   session-not-found, expiry — first confirm the cwd is the repo root, then re-bind
+   once from there with the charter plus a three-line recap of consults so far, and
+   persist the new session_id. A session-not-found error is a wrong-cwd or expired
+   session, not a model failure.
+
+**Consult (every time):** write the brief to a temp file, then
+`claude -p --resume <session_id> --model fable (or opus) --effort high (max for opus) --output-format json < <brief-file>`.
+Act on the reply's opening signal: ENDORSE — proceed. CORRECTION — apply it first;
+your next consult on that topic opens with what happened. PLAN — adopt it; same
+report-back rule. STOP — halt that line of work and surface it to the user. Never
+proceed past a mandatory checkpoint on an unread or unanswered consult; if the CLI
+and its fallback both fail, stop and tell the user rather than self-endorsing.
+
+**Mandatory consult cadence:**
+1. After binding, before touching any file: your concrete per-phase execution plan.
+2. Per phase, BEFORE implementation: the failing tests you wrote and your approach.
+3. Per phase, AFTER implementation: diff summary, test results, acceptance evidence.
+4. Before EVERY `git commit` and EVERY `git push`.
+5. On any user-facing fork: your proposed framing, before asking the user.
+6. Any time the same failure repeats twice, progress stalls, or you reconsider an
+   approach.
+
+## Plan
+
+[Numbered phases. Each phase: what to change (with paths), how to prove it worked
+(acceptance criteria with commands or counts), and its blast radius. A decision that
+belongs to the user is its own phase, marked USER DECISION — never pick silently. End
+with a verify-and-land phase: re-run the baseline check, gates green, advisor ENDORSE,
+then commit and push.]
+
+## Execution discipline
+
+- Track each phase as an explicit task; mark it complete only when its acceptance
+  evidence exists and the advisor has seen it.
+- Every progress claim rests on command output from this run; label anything
+  unverified as unverified.
+- Keep a consult log (checkpoint, signal received) and include it in the final report.
+- Final message: outcome first (evidence, phases landed, commits pushed), then the
+  decisions taken, then honest gaps.
+````