greprag 5.63.0 → 5.64.1

package/skill/mechanic/SKILL.md

@@ -2,10 +2,10 @@
 name: mechanic
 description: |
   The Mechanic — keep the harness healthy. The loop is friction → fix → repair:
-  detect friction, log fixes, repair so it can't recur. Digest the fix queue (raw
-  signal → repair the broken mechanism or surface the durable gotcha), audit fixes
-  for drift, mine episodic memory, promote project-agnostic repairs to global.
-  One-at-a-time conversational review — never bulk.
+  spawn one fix chip per live friction unit, then repair so it can't recur.
+  Digest the existing fix queue and audit/design notes, audit fixes for drift,
+  mine episodic memory, promote project-agnostic repairs to global. One-at-a-time
+  conversational review — never bulk.
 
   Trigger phrases: "/mechanic", "digest
   fixes", "digest smells", "drain the queue", "any friction", "any fixes", "what
@@ -34,14 +34,14 @@ license: MIT
 
 The Mechanic keeps the harness healthy. The loop is **friction → fix → repair**:
 
-- **friction** — a rough spot the agent or operator hit: a gotcha, a rediscovery, a repeated correction, churn, rework. The hourly detector auto-logs 5 types (`friction-extractor.ts`); the operator drops them by hand too.
-- **fix** — the logged item. *"This needs a fix."* Sits in the fix queue, open until resolved.
+- **friction** — a rough spot the agent or operator hit: a gotcha, a rediscovery, a repeated correction, churn, rework. Live friction becomes one `greprag fix spawn "<unit>"` chip at the moment it happens.
+- **fix** — the repair mission or audit note. Live fixes are owned by spawned FIX chips; the queue remains for existing backlog and deliberate design-input notes.
 - **repair** — the fix wired in so it can't recur: a hook, a code change, or *surfacing it* (a doc line / a fact-seed / an injection). A repaired fix is done.
 
 **The one gate: is this worth repairing?** If yes → repair it on the lowest rung that holds. If there's no repair worth doing — not even a line in a doc — drop it. (Can't fix it and won't surface it → you don't care.)
 
 **Autonomy = blast radius** (not repair-vs-not). Don't route every repair through the operator — gate by what can be affected:
-- **Tier 0 — inert / instantly-reversible, zero reach → just do it, report.** Author schemas **born-shadow** (logs only, injects nothing until armed), record/close/delete fixes, fix skill/doc text you own, ADR entries, log friction. Born-shadow makes authoring free — nothing fires until graduation.
+- **Tier 0 — inert / instantly-reversible, zero reach → just do it, report.** Author schemas **born-shadow** (logs only, injects nothing until armed), record/close/delete existing fixes, fix skill/doc text you own, ADR entries, record audit/design notes. Born-shadow makes authoring free — nothing fires until graduation.
 - **Tier 1 — local code, test-covered, reversible → do it, commit, report.** Contained to the repo, green on its own tests, no prod/fleet/external reach.
 - **Tier 2 — real reach or hard to undo → confirm first.** ARM a schema (shadow→active = fleet-wide inject), any deny/transform, prod/deploy/secrets/money/external, untested load-bearing code, deleting what you didn't author, editing a file a peer is live in.
 
@@ -116,7 +116,11 @@ do not retry blindly, and never treat two visible copies as two requests.
 
 ## Phase 0 — Fix digestion
 
-A fix is a raw, undigested signal. Auto-detected friction fixes carry a type; hand-dropped ones are freeform. Digestion does two jobs per fix — **repair** the mechanism and/or **record** the durable gotcha — and runs FIRST.
+A fix note is a raw, undigested signal. Historical auto-detected friction rows
+may carry a type; deliberate audit/design notes are freeform. New live friction
+does not enter this queue: it becomes one `greprag fix spawn "<unit>"` chip at
+the moment it happens. Digestion does two jobs per queued note — **repair** the
+mechanism and/or **record** the durable gotcha — and runs FIRST.
 
 1. **Tenant-wide census (FIRST — queues silo per project).** A run that only drains the current project leaves fixes from other roots piling up unseen (the failure that stranded 15 greprag fixes while another queue showed 1). Get the whole picture:
    ```bash
@@ -254,13 +258,12 @@ Append `(phase <X> skipped)` per skipped phase.
 Repairs (D3 rows attached to fixes) are managed with `greprag mechanic`, not by editing hooks:
 
 ```
-greprag mechanic set                  mark THIS project/session as the live Mechanic role;
-                                      fan out `mechanic_live` to open sessions;
-                                      arm with --mechanic to receive live friction
+greprag mechanic set                  legacy role marker for mechanic follow-up rails;
+                                      fan out `mechanic_live` to open sessions
 greprag mechanic role                 show whether this project is the live Mechanic
 greprag mechanic friction "obs"       RETIRED as the reflex (2026-07-12): spawn a fix chip
-                                      instead — `greprag fix spawn "<unit>"`. Verb remains for
-                                      legacy stress-hook forwarding only
+                                      instead — `greprag fix spawn "<unit>"`. The CLI refuses
+                                      new working-session use.
 greprag mechanic reply --to <8hex>    typed follow-up from Mechanic to source session;
   "msg" [--friction-id <id>]          do not use generic send for mechanic workflow
 greprag mechanic status               inventory: live (shadow|active) repairs grouped by status,
@@ -273,18 +276,14 @@ greprag mechanic why <nodeId>         provenance: the friction → fix → repai
 greprag mechanic off / on             PANIC SWITCH — local file, no network; suspends ALL repairs
 ```
 
-**Live Mechanic role.** A `--mechanic` inbox watcher receives tenant
-`mechanic_friction` events in addition to its own session lane. Working sessions
-always assume they are not the Mechanic unless `greprag mechanic role` says the
-current session will arm with `--mechanic`. `greprag mechanic set` sends an
-immediate typed `mechanic_live` notice to currently open same-project sessions;
-SessionStart and the reminder hook cover sessions that launch or turn later.
-Working sessions emit friction automatically when the stress detector fires, and
-manually via `greprag mechanic friction "..." --tier sentence|mechanism|unsure
---signal <why> --platform <harness>`, then keep working unless blocked. The event
-is internal queue/work mail: it does not wake ordinary sessions or Assistant. The
-Mechanic replies with `greprag mechanic reply --to <source-session> "..."` for
-coordination and pings the operator for status/Tier-2 gates.
+**Legacy Mechanic role.** A `--mechanic` inbox watcher can still receive
+legacy `mechanic_friction` / `mechanic_reply` rows in addition to its own session
+lane, but live working sessions no longer route friction there. New friction is
+always Law 4: `greprag fix spawn "<one unit of friction>"`, one FIX chip per
+unit, at the moment it happens. `greprag mechanic set` only fans out a notice
+that teaches this fix-spawn reflex and preserves the reply rail for old mechanic
+threads. The Mechanic replies with `greprag mechanic reply --to <source-session>
+"..."` only for legacy follow-up coordination.
 
 **Born shadow → graduate.** Every repair is born `shadow`: it matches and logs would-have-fired
 evidence but injects nothing. Graduation is evidence-first — when `status` flags a row `⚑`, review

package/skill/mechanic/docs/skill-fix-conventions.md

@@ -6,7 +6,7 @@
 
 The skill-tuning reflex injects a directive when a skill under break-in loads. The old directive said "watch your execution, emit a SELF-TUNING block, propose a fix" — vague (it pointed at the *run*, not the *skill*) and propose-only (no edit ever landed). This doc replaces that with **six locatable skill defects**, each mapped to one concrete edit. The reflex's loop is: **detect a defined friction → locate it in the skill's SKILL.md → apply the fix per the matching recipe → show the diff for one accept/revert.**
 
-A friction that doesn't match one of the six below is **not auto-fixable** — log it (`greprag fix log "<obs>" --scope skill:<name>`) and keep working. Do not invent edits outside these recipes.
+A friction that doesn't match one of the six below is **not auto-fixable inline** — spawn a fix chip for the one unit (`greprag fix spawn "<skill friction unit>"`) and keep working. Use `greprag fix log` only for deliberate audit/design notes, not as the live-friction reflex. Do not invent edits outside these recipes.
 
 ## The two edit primitives (skill-optimize vocabulary)
 
@@ -55,4 +55,4 @@ Each: **signature** (how it shows up in the run) · **location** (where it lives
 - **Apply + show diff.** Make the edit, then show the unified diff and stop for one accept/revert. (This is the operator-chosen gate; the Mechanic "always confirm" rule still holds.)
 - **Bundled skills:** if the target is a greprag bundled skill, author the edit at `packages/cli/skill/<name>/` — never the `~/.claude/skills/<name>/` install artifact (it's overwritten on the next `init`). See greprag `CLAUDE.md`.
 - **Line budget:** a fix must not grow SKILL.md without adding a real proactive-fire rule or per-task step. Converting wallpaper → Convention B is net-neutral or smaller; mis-route adds at most one line.
-- **Out of taxonomy → log, don't improvise.** Anything not matching the six is `greprag fix log`-only.
+- **Out of taxonomy → spawn, don't improvise.** Anything not matching the six becomes one `greprag fix spawn "<unit>"` chip. `greprag fix log` is only for deliberate audit/design notes.