greprag 5.83.1 → 5.84.0

package/skill/greprag/docs/inbox-watch.md

@@ -14,7 +14,7 @@ greprag inbox watch --since <id-or-iso>   # resume from a known cursor
 greprag inbox watch --json                # one JSON object per line (preferred under Monitor)
 ```
 
-`--project` and `--session` compose. `--session` is the strictest filter: only messages with matching `to_session_id` get through. The tenant catch-all (cold open / inbound email — `to_session_id IS NULL`) does NOT reach a session- or project-scoped watcher; only a `--receptionist` watcher wakes on it (Option C). adr: adr/address-grammar.md. This eliminates cross-session noise when several Claude sessions watch the same project's inbox at once.
+`--project` and `--session` compose. `--session` is the strictest filter: only messages with matching `to_session_id` get through. The tenant catch-all (cold open / inbound email — `to_session_id IS NULL`) does NOT reach a session- or project-scoped watcher; only a `--receptionist` watcher wakes on it (Option C). adr: repo:greprag/adr/address-grammar.md. This eliminates cross-session noise when several Claude sessions watch the same project's inbox at once.
 
 `--mechanic` is a role subscription: it keeps the normal session/project lane and adds only tenant `mechanic_friction` events. It does not wake on ordinary cold opens or inbound email.
 

package/skill/greprag/docs/inbox.md

@@ -77,9 +77,9 @@ First-contact handshake: a sender who doesn't know your session sends to bare `<
 - `1834729@greprag.com` — canonical numeric handle. Opaque, leaks nothing. Get yours from `greprag status --json | jq -r .identity.handle` or `greprag whoami`.
 - `alice@greprag.com` — opt-in vanity alias (claim with `greprag identity claim alice`).
 
-**Real emails are NEVER routing addresses.** `users.email` is auth credential only. If you don't know the recipient's numeric handle, ask the user — don't guess from their email. adr: adr/numeric-handles.md
+**Real emails are NEVER routing addresses.** `users.email` is auth credential only. If you don't know the recipient's numeric handle, ask the user — don't guess from their email. adr: repo:greprag/adr/numeric-handles.md
 
-Session targeting is the default and expected form; the bare handle is the cold-open front desk. Project broadcasts were removed (2026-06-07) — a project-name target errors out. adr: adr/address-grammar.md
+Session targeting is the default and expected form; the bare handle is the cold-open front desk. Project broadcasts were removed (2026-06-07) — a project-name target errors out. adr: repo:greprag/adr/address-grammar.md
 
 ## retract
 

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

@@ -53,6 +53,6 @@ Each: **signature** (how it shows up in the run) · **location** (where it lives
 
 - **One friction, one edit.** If a run surfaced two defects, make two separate edits, each shown for its own accept/revert. Never batch.
 - **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.)
-- **Edit the canonical source.** Managed skills: `greprag skill edit <name> --skill-id <id>`; greprag-bundled skills: `packages/cli/skill/<name>/`. Never edit a generated `~/.claude/skills/<name>/SKILL.md` adapter or install artifact.
+- **Edit the canonical source.** Managed skills: `greprag skill edit <name> --skill-id <id> --reason "<the friction this fixes>"`; greprag-bundled skills: `packages/cli/skill/<name>/`. Never edit a generated `~/.claude/skills/<name>/SKILL.md` adapter or install artifact.
 - **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 → spawn, don't improvise.** Anything not matching the six becomes one `greprag fix spawn --type doctrine "<unit>"` chip. `greprag fix log` is only for deliberate audit/design notes.

package/skill/templates/chip-spawn.md

@@ -78,7 +78,7 @@ Your parent session is named `<parent-name>`. When you finish, report to it with
 greprag session retitle <your-own-8hex> "Chip <Label> — <workstream>"
 ```
 
-The leader dictates the exact string (e.g. `Chip A — Converter format coverage`); substitute your own 8-hex from SessionStart. This force-sets the registry title so the watcher list + Discord `/switch` line up with the leader's labels. Single chips skip this.
+The leader dictates the exact string (e.g. `Chip A — Converter format coverage`); substitute your own 8-hex from SessionStart. This force-sets the registry title so the watcher list lines up with the leader's labels. Single chips skip this.
 
 ## Report back — native `SendMessage`
 
@@ -87,7 +87,9 @@ Close the task body with this (substitute `<slug>` + `<parent-name>`):
 ````
 ---
 
-**Report back:** when the work is committed, send your result to the parent with native `SendMessage`, then end your turn:
+**Rebase before you report:** when the work is committed, rebase this branch onto the current tip of your merge target (the default branch, or the integration branch on a multi-chip mission), resolve any conflicts here, and rerun the affected checks. Only you can edit this worktree, so the parent lands your branch by fast-forward alone and sends it back if the tip has moved again.
+
+**Report back:** then send your result to the parent with native `SendMessage`, then end your turn:
 
 - `to`: `"<parent-name>"`
 - `message`: status, commit hash, branch `chip/<slug>`, and a one-line summary.
@@ -116,6 +118,8 @@ Chips never `npm run deploy` (or Wrangler / another provider deploy) from the wo
 
 ## Parent merge discipline — prune at the merge (HARD RULE)
 
+Land a chip branch with `git merge --ff-only chip/<slug>` under the merge lock, nothing more: the chip rebased and retested it before reporting. Never rebase inside the chip's worktree; you cannot edit there, so a conflict strands a half-finished rebase. A refused fast-forward goes back to the chip over `SendMessage` (free the lock first).
+
 When you (the parent) merge a chip branch — through the canonical commit path or a profile-declared merge — prune in the same breath: find the worktree holding `chip/<slug>` in `git worktree list` (the app's own worktree when the chip reused it, `.claude/worktrees/<slug>` on a local start), junction guard it (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove <worktree>`, and `git branch -d chip/<slug>` once merged. A chip that closed itself has already removed its own worktree, so no worktree holds the branch — delete the branch and move on, don't go hunting for it. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the integration-branch merge; the branch lives until the configured default-branch merge (chip-leader Phase 4).
 
 **FIX chips report to the mission owner.** A `greprag fix spawn` mission is the source of truth for FIX behavior. `fix spawn` detects usable Git history and emits `workspaceMode`: Git uses an isolated worktree; non-Git, unavailable Git, or no commit uses the project-local task with serialized writes. Dispatch honors that mode without trying a worktree first. The FIX chip identifies the exact friction, makes the smallest durable root-cause fix, verifies and commits useful work, then reports the commit/result and cleanup parameters to the parent mission owner. It creates no human landing gate. If no live parent exists and the chip carries the full-goal mission, it follows the repo profile as mission owner.

package/skill/templates/delivery.md

@@ -88,13 +88,30 @@ checkout:
    tip.
 4. Land with `git merge --ff-only <branch>`. A fast-forward cannot produce a
    surprise merge commit or silently resolve someone else's conflict.
-5. Record the landed sha with `merge-lock release --landed`.
+5. Record it with `merge-lock release --landed <branch>` — the branch, never
+   HEAD. Release exits 1 if that branch did not land.
 
 If the tip moved while you were preparing, free the lock, rebase, and test
 again. Never rebase a shared default branch. A busy merge lock means retry
 after its holder finishes — never bypass it, and never take over someone
 else's in-progress merge.
 
+### Another session's branch is rebased by that session
+
+Step 2 happens in the checkout of whoever owns the branch, because only that
+session can edit there and so only it can resolve a conflict. A chip rebases
+onto its merge target's tip and retests before it reports, so its parent lands
+it with steps 3 to 5 alone. Never run `git -C <their worktree> rebase`: the
+write guard refuses your edits there, so the first conflict leaves you
+aborting, or leaves a half-finished rebase in someone else's checkout. If the
+fast-forward is refused because the tip moved, free the lock and send the
+branch back to its owner to rebase and retest. A chip that already closed left
+no worktree behind, so rebase its branch in a checkout you can edit.
+
+Field trigger (2026-10-06): a parent landing chip branches with
+`git -C <chip-worktree> rebase main` hit the same ADR conflict twice and could
+not resolve it either time.
+
 This lock is a short Git critical section. It is not a delivery lease, and it
 is not peer-acknowledgement polling.
 

package/skill/templates/skill-change.md

@@ -40,7 +40,9 @@ Explicitly requested creation, porting, or redesign is authorized work. The prop
 - Bundled GrepRAG skill: edit `packages/cli/skill/<name>/`, never the installed artifact.
 - Mirrored/local skill: edit its canonical source, not the generated Codex/Claude/OpenCode adapter.
 - Unknown source: stop and identify the canonical source before editing.
-- Codex/non-interactive harness: do not launch an editor. Use `greprag skill mirror export <skill> --to <dir>`, patch the exported Markdown files with file edits, then `greprag skill mirror apply <dir> --skill <skill> --expected-hash <exported-hash>`. If using `greprag skill edit` as the export helper, pass `--no-open`.
+- Codex/non-interactive harness: do not launch an editor. Use `greprag skill mirror export <skill> --to <dir>`, patch the exported Markdown files with file edits, then `greprag skill mirror apply <dir> --skill <skill> --expected-hash <exported-hash> --reason "<why>"`. If using `greprag skill edit` as the export helper, pass `--no-open`.
+- **ABOUT TO WRITE A MIRRORED SKILL? STOP - PASS `--reason "<one line>"`.** `skill edit`, `skill mirror apply`, `snapshot promote` and `skill revert` refuse without it. GrepRAG keeps every revision's bytes with that reason, so write the learning the edit captures, not "update skill".
+- History: `greprag skill history <skill>` lists revisions (date, author, reason, changes); `greprag skill diff <skill> <revA> [<revB>]` shows a unified diff; `greprag skill revert <skill> --to <rev> --reason "<why>" --expected-hash <current-hash>` makes an old revision current as a new one. Add the adapter's `--skill-id` to each.
 
 ## Skill-Refresh Chips
 

package/dist/commands/sms.js

@@ -1,215 +0,0 @@
-"use strict";
-/** greprag sms <pair|unpair|me> — Front Desk SMS rail CLI.
- *
- *  pair    POSTs /v1/sms/pair with the current project anchor; prints the
- *          6-char code + the greprag number to text it to.
- *  unpair  DELETEs /v1/sms/pair (optionally for one --phone).
- *  me      GETs /v1/sms/me — the tenant's bound phones.
- *
- *  Self-contained HTTP client (does not import @greprag/core), mirroring
- *  commands/email.ts. See docs/receptionist-sms-mvp.md.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runSms = runSms;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const project_anchor_1 = require("../project-anchor");
-const API_URL_DEFAULT = 'https://api.greprag.com';
-function loadEnvFile(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        for (const line of content.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith('#'))
-                continue;
-            const eqIdx = trimmed.indexOf('=');
-            if (eqIdx < 1)
-                continue;
-            const key = trimmed.slice(0, eqIdx).trim();
-            let value = trimmed.slice(eqIdx + 1).trim();
-            if ((value.startsWith('"') && value.endsWith('"')) ||
-                (value.startsWith("'") && value.endsWith("'"))) {
-                value = value.slice(1, -1);
-            }
-            if (!process.env[key])
-                process.env[key] = value;
-        }
-    }
-    catch { /* file missing — fine */ }
-}
-function getConfig() {
-    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    if (homeDir)
-        loadEnvFile(path.join(homeDir, '.greprag', '.env'));
-    if (!process.env.GREPRAG_API_KEY)
-        loadEnvFile(path.join(process.cwd(), '.env'));
-    return {
-        apiUrl: process.env.GREPRAG_API_URL || API_URL_DEFAULT,
-        apiKey: process.env.GREPRAG_API_KEY || '',
-    };
-}
-function getFlag(args, flag) {
-    const idx = args.indexOf(flag);
-    if (idx === -1 || idx + 1 >= args.length)
-        return undefined;
-    return args[idx + 1];
-}
-async function callPair(cfg, phone, projectId) {
-    const payload = { phone };
-    if (projectId)
-        payload.project_id = projectId;
-    const res = await fetch(`${cfg.apiUrl}/v1/sms/pair`, {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
-    });
-    return res.json();
-}
-async function callUnpair(cfg, phone) {
-    const res = await fetch(`${cfg.apiUrl}/v1/sms/pair`, {
-        method: 'DELETE',
-        headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify(phone ? { phone } : {}),
-    });
-    return res.json();
-}
-async function callMe(cfg) {
-    const res = await fetch(`${cfg.apiUrl}/v1/sms/me`, {
-        method: 'GET',
-        headers: { 'Authorization': `Bearer ${cfg.apiKey}` },
-    });
-    return res.json();
-}
-const SMS_HELP = `
-greprag sms — Front Desk SMS rail. Reach a cheap receptionist by text to triage
-your inbox and route messages to your sessions from your phone.
-
-Subcommands:
-  greprag sms pair --phone <e164>       Generate a 15-min code BOUND to that
-                                        phone; text it (or "PAIR <code>") FROM
-                                        that exact number to the greprag number
-                                        to bind it. --phone is required and must
-                                        be full E.164 (e.g. +15551234567) — the
-                                        code only binds when claimed from it. The
-                                        current directory's project anchor becomes
-                                        your home project.
-  greprag sms unpair [--phone <e164>]   Unbind one phone (or all phones).
-  greprag sms me                        Show bound phones + the greprag number.
-
-Once paired, text the greprag number:
-  "what's waiting?"                     → the receptionist reads your inbox.
-  "tell session a1b2c3d4 to ship it"    → routes a message to that session.
-`.trim();
-async function runSms(args) {
-    const sub = args[0];
-    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
-        console.log(SMS_HELP);
-        return;
-    }
-    const cfg = getConfig();
-    if (!cfg.apiKey) {
-        console.error('Not configured. Run: greprag init');
-        process.exit(1);
-    }
-    if (sub === 'pair') {
-        // --phone is required: the code is bound to it, and only a claim texted from
-        // that exact number succeeds (the identity guard against brute-force binds).
-        const phone = getFlag(args, '--phone');
-        if (!phone) {
-            console.error('Error: --phone <e164> is required (the number you will text from, e.g. +15551234567).');
-            process.exit(1);
-        }
-        // The home/default project is the current directory's anchor. The API keys
-        // pairing by project_id; a `--project <name>` would need a server-side name
-        // lookup, so for the MVP the anchor is the source of truth (run pair from
-        // the project dir you want as home, or leave a message naming any project).
-        const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
-        const projectId = anchor.projectId || null;
-        const result = await callPair(cfg, phone, projectId);
-        if (!result.ok) {
-            console.error(`Error: ${result.error}`);
-            process.exit(1);
-        }
-        console.log(`Pairing code: ${result.code}`);
-        if (result.bound_phone) {
-            console.log(`Bound to ${result.bound_phone} — text the code FROM that number only.`);
-        }
-        if (result.sms_number) {
-            console.log(`Text it to the greprag number: ${result.sms_number}`);
-            console.log(`  (send "${result.code}" or "PAIR ${result.code}")`);
-        }
-        else {
-            console.log(`Text "${result.code}" (or "PAIR ${result.code}") to the greprag number.`);
-            console.log(`  (number not configured server-side yet — ask the operator)`);
-        }
-        console.log(`Code expires in ${result.expires_in_minutes} minutes.`);
-        if (result.project_name) {
-            console.log(`After pairing, your home project is "${result.project_name}".`);
-        }
-        else {
-            console.log(`No default project set — name one when you leave a message.`);
-        }
-        return;
-    }
-    if (sub === 'unpair') {
-        const phone = getFlag(args, '--phone');
-        const result = await callUnpair(cfg, phone);
-        if (!result.ok) {
-            console.error(`Error: ${result.error}`);
-            process.exit(1);
-        }
-        console.log(`Unpaired ${result.removed} phone(s).`);
-        return;
-    }
-    if (sub === 'me') {
-        const result = await callMe(cfg);
-        if (!result.ok) {
-            console.error(`Error: ${result.error}`);
-            process.exit(1);
-        }
-        console.log(`greprag number: ${result.sms_number ?? '(not configured)'}`);
-        if (!result.paired || !result.phones || result.phones.length === 0) {
-            console.log('No phones paired. Run: greprag sms pair');
-            return;
-        }
-        console.log(`Paired phones (${result.phones.length}):`);
-        for (const p of result.phones) {
-            console.log(`  ${p.phone}  paired ${p.paired_at}  last inbound ${p.last_seen_inbound_at ?? '(never)'}`);
-        }
-        return;
-    }
-    console.log(SMS_HELP);
-}