greprag 5.82.1 → 5.83.0

package/dist/claude-lifecycle-cutover.js

@@ -42,20 +42,6 @@ const path = __importStar(require("path"));
 const native_skill_mirror_1 = require("./native-skill-mirror");
 const skill_mirror_files_1 = require("./skill-mirror-files");
 exports.CLAUDE_LIFECYCLE_SKILLS = ['commit', 'deploy', 'release'];
-const STATE_FILE = '.greprag-mirror.json';
-function readState(root) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(root, STATE_FILE), 'utf8'));
-        if (parsed?.version === 1 && parsed.skills && typeof parsed.skills === 'object')
-            return parsed;
-    }
-    catch { /* first targeted cutover */ }
-    return { version: 1, skills: {} };
-}
-function writeState(root, state) {
-    fs.mkdirSync(root, { recursive: true });
-    fs.writeFileSync(path.join(root, STATE_FILE), JSON.stringify(state, null, 2) + '\n', 'utf8');
-}
 function adapterFor(skill) {
     const files = (0, native_skill_mirror_1.buildNativeSkillAdapter)('claude-code', skill, { allowClaudeCode: true });
     if (!files || files.length !== 1 || files[0].path !== 'SKILL.md') {
@@ -88,10 +74,13 @@ function requiredSkills(skills, names) {
 function applyClaudeLifecycleCutover(params) {
     const homeDir = params.homeDir || os.homedir();
     const root = (0, native_skill_mirror_1.nativeSkillRoot)('claude-code', homeDir);
-    const state = readState(root);
+    const state = (0, native_skill_mirror_1.readState)(root);
     const names = params.names?.length ? params.names : exports.CLAUDE_LIFECYCLE_SKILLS;
     const prepared = requiredSkills(params.skills, names).map(skill => {
         const target = path.join(root, skill.skillName);
+        if ((0, skill_mirror_files_1.isSkillFolderOwnedElsewhere)(target)) {
+            throw new Error(`Claude skill folder is owned elsewhere (a link or another installer's package): ${skill.skillName}; not written.`);
+        }
         const skillMd = path.join(target, 'SKILL.md');
         const adapterFiles = adapterFor(skill);
         const nextHash = (0, skill_mirror_files_1.computeSkillFileHash)(adapterFiles);
@@ -138,7 +127,7 @@ function applyClaudeLifecycleCutover(params) {
         else
             result.installed++;
     }
-    writeState(root, state);
+    (0, native_skill_mirror_1.writeState)(root, state);
     return result;
 }
 async function syncClaudeLifecycleCutover(params) {

package/dist/commands/codex.js

@@ -472,6 +472,10 @@ function printCodexWatcherRetired() {
 async function runCodex(args) {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        if (args[1] === 'chip')
+            return (0, command_1.runCodexChip)(['--help', ...args.slice(2)]);
+        if (args[1] === 'app-server')
+            return (0, codex_app_server_1.runCodexAppServer)(['--help', ...args.slice(2)]);
         console.log(HELP);
         return;
     }

package/dist/commands/corpus/client.js

@@ -47,6 +47,8 @@ exports.abortNotConfigured = abortNotConfigured;
 exports.apiCall = apiCall;
 exports.apiGet = apiGet;
 exports.apiDelete = apiDelete;
+exports.formatPassage = formatPassage;
+exports.getMaxChars = getMaxChars;
 exports.getFlag = getFlag;
 exports.getFlags = getFlags;
 exports.extractPositionals = extractPositionals;
@@ -143,6 +145,20 @@ async function apiDelete(url, apiKey, body) {
  *  Listing and search now answer from the same classification.
  *  adr: adr/searchable-store-kinds.md, adr: adr/corpus-tags.md */
 exports.INTERNAL_KINDS = ['inbox', 'fix', 'docptr', 'skillgain', 'parity', 'doctrine'];
+/** Body of one node for `walk` / `section`, indented under its header line.
+ *  Full text by default — these commands exist to read the whole passage around
+ *  a hit (search snippets stay short). `maxChars` is the explicit opt-in cut. */
+function formatPassage(content, maxChars) {
+    const text = maxChars && maxChars > 0 && content.length > maxChars
+        ? content.slice(0, maxChars) + `... [+${content.length - maxChars} chars]`
+        : content;
+    return text.split('\n').map((line) => `    ${line}`).join('\n');
+}
+/** `--max-chars N` → N, or undefined (full text). */
+function getMaxChars(args) {
+    const raw = getFlag(args, '--max-chars');
+    return raw ? parseInt(raw, 10) : undefined;
+}
 // -- Arg helpers -----------------------------------------------------------
 function getFlag(args, flag) {
     const idx = args.indexOf(flag);

package/dist/commands/corpus/index.js

@@ -57,10 +57,13 @@ Subcommands:
                                             --all = every store under the tenant;
                                             --store repeatable; --kind filters to
                                             one kind. Hits are labeled by store.
-  section <store> "<heading>"               Every node under a heading (forgiving
+  section <store> "<heading>" [--max-chars N]
+                                            Every node under a heading (forgiving
                                             match: any depth, dash/case-insensitive).
-  walk   <store> <nodeId> [--before 2 --after 2]
+  walk   <store> <nodeId> [--before 2 --after 2] [--max-chars N]
                                             Show a node and its neighbors.
+                                            section/walk print full node text;
+                                            --max-chars N cuts each node.
   status <store>                            Show write-side enrichment progress
                                             (per-node vocabulary bridge).
   refresh <store>                           Manually re-check a tracked source —

package/dist/commands/corpus/section.js

@@ -13,9 +13,10 @@ async function sectionCmd(args) {
     const storeRef = args[0];
     const headingPath = args[1];
     if (!storeRef || !headingPath) {
-        console.error('Usage: greprag corpus section <storeIdOrName> "<heading>"\n  e.g. greprag corpus section "Scientific Advertising" "Chapter 7"\n  Forgiving match: any depth, case-/dash-insensitive, leaf prefix.');
+        console.error('Usage: greprag corpus section <storeIdOrName> "<heading>" [--max-chars N]\n  e.g. greprag corpus section "Scientific Advertising" "Chapter 7"\n  Forgiving match: any depth, case-/dash-insensitive, leaf prefix.');
         process.exit(1);
     }
+    const maxChars = (0, client_1.getMaxChars)(args);
     const store = await (0, client_1.resolveStore)(storeRef, cfg.apiUrl, cfg.apiKey);
     const url = `${cfg.apiUrl}/v1/stores/${store.id}/section?path=${encodeURIComponent(headingPath)}`;
     const res = await (0, client_1.apiGet)(url, cfg.apiKey);
@@ -24,9 +25,8 @@ async function sectionCmd(args) {
     console.log(`\n${store.name} · section "${headingPath}" — ${res.nodes.length} node${res.nodes.length === 1 ? '' : 's'}\n`);
     for (const n of res.nodes) {
         const heading = n.headingPath?.length ? ` · ${n.headingPath.join(' / ')}` : '';
-        const snippet = n.content.length > 200 ? n.content.slice(0, 197) + '...' : n.content;
         console.log(`  [${n.nodeId}] pos=${n.position}${heading}`);
-        console.log(`    ${snippet.replace(/\n/g, ' ')}\n`);
+        console.log(`${(0, client_1.formatPassage)(n.content, maxChars)}\n`);
     }
     if (res.nodes.length === 0) {
         console.log('No nodes under that heading. Check a hit\'s headingPath from `corpus search`, or broaden the heading.');

package/dist/commands/corpus/walk.js

@@ -13,11 +13,12 @@ async function walkCmd(args) {
     const storeRef = args[0];
     const nodeId = args[1];
     if (!storeRef || !nodeId) {
-        console.error('Usage: greprag corpus walk <storeIdOrName> <nodeId> [--before 2 --after 2]');
+        console.error('Usage: greprag corpus walk <storeIdOrName> <nodeId> [--before 2 --after 2] [--max-chars N]');
         process.exit(1);
     }
     const before = parseInt((0, client_1.getFlag)(args, '--before') || '2', 10);
     const after = parseInt((0, client_1.getFlag)(args, '--after') || '2', 10);
+    const maxChars = (0, client_1.getMaxChars)(args);
     const store = await (0, client_1.resolveStore)(storeRef, cfg.apiUrl, cfg.apiKey);
     // Step 1: fetch the anchor node to learn its position.
     const anchorRes = await (0, client_1.apiGet)(`${cfg.apiUrl}/v1/stores/${store.id}/by-node-id/${nodeId}`, cfg.apiKey);
@@ -33,8 +34,7 @@ async function walkCmd(args) {
         const isAnchor = n.nodeId === nodeId;
         const marker = isAnchor ? '★' : ' ';
         const heading = n.headingPath?.length ? ` · ${n.headingPath.join(' / ')}` : '';
-        const snippet = n.content.length > 320 ? n.content.slice(0, 317) + '...' : n.content;
         console.log(`  ${marker} [${n.nodeId}] pos=${n.position}${heading}`);
-        console.log(`    ${snippet.replace(/\n/g, ' ')}\n`);
+        console.log(`${(0, client_1.formatPassage)(n.content, maxChars)}\n`);
     }
 }

package/dist/commands/delivery.js

@@ -1,12 +1,49 @@
 "use strict";
+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.runDelivery = runDelivery;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const delivery_config_1 = require("../delivery-config");
 const HELP = `greprag delivery — resolve the current repo's delivery authority
 
 Usage:
   greprag delivery resolve [--json]
   greprag delivery status [--json]
+  greprag delivery init [--write]   draft this repo's profile (report only unless --write;
+                                    never overwrites an existing profile)
 
 Reads .greprag/delivery.json when present. During migration only, falls back to
 docs/deploy.md, docs/releases.md, then CLAUDE.md. Provider commands remain in
@@ -17,6 +54,8 @@ function runDelivery(args) {
         return;
     }
     const sub = args[0] || 'resolve';
+    if (sub === 'init')
+        return runInit(args.includes('--write'));
     if (sub !== 'resolve' && sub !== 'status') {
         console.error(`Unknown delivery command: ${sub}\n\n${HELP}`);
         process.exitCode = 1;
@@ -56,3 +95,28 @@ function runDelivery(args) {
     if (result.mode === 'missing' || result.mode === 'invalid')
         process.exitCode = 1;
 }
+function runInit(write) {
+    const draft = (0, delivery_config_1.draftDeliveryProfile)(process.cwd());
+    if (!draft) {
+        console.error('Not inside a Git repository.');
+        process.exitCode = 1;
+        return;
+    }
+    const target = (0, delivery_config_1.deliveryProfilePath)(draft.root);
+    if (fs.existsSync(target)) {
+        console.log(`Profile already exists: ${target}\nEdit it by hand; init never overwrites.`);
+        return;
+    }
+    const body = JSON.stringify(draft.profile, null, 2) + '\n';
+    console.log(`Draft profile for ${draft.root}:\n${body}`);
+    console.log(`Deploy signals: ${draft.providerSignals.join(', ') || 'none (commit-and-merge only)'}`);
+    for (const item of draft.todo)
+        console.log(`  todo: ${item}`);
+    if (!write) {
+        console.log('\nReport only. Rerun with --write to save it.');
+        return;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, body);
+    console.log(`\nWrote ${target}. Commit it.`);
+}

package/dist/commands/docptr.js

@@ -51,9 +51,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDocPtr = runDocPtr;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const proc_1 = require("../proc");
 const project_anchor_1 = require("../project-anchor");
 const docptr_refs_1 = require("../docptr-refs");
+const doc_mirror_client_1 = require("../doc-mirror-client");
 function getConfig() {
     return {
         apiUrl: process.env.GREPRAG_API_URL || 'https://api.greprag.com',
@@ -67,25 +69,6 @@ USAGE
         Judge every tracked, eligible .md and register the core ones — the
         one-time catch-up for docs that predate the system or are never edited.
         Idempotent. --missing-only skips already-registered docs.`;
-/** Mirror of hook.ts isDocPathEligible — the deterministic pre-filter (non-.md,
- *  dot-dirs, build trees, harness-owned CLAUDE.md/MEMORY.md). Duplicated because
- *  the CLI command files are self-contained (zero cross-file coupling). */
-function isDocPathEligible(relPath) {
-    const p = relPath.replace(/\\/g, '/');
-    if (!p.toLowerCase().endsWith('.md'))
-        return false;
-    const segments = p.split('/');
-    const base = segments[segments.length - 1];
-    if (base === 'CLAUDE.md' || base === 'MEMORY.md')
-        return false;
-    for (const seg of segments.slice(0, -1)) {
-        if (seg.startsWith('.'))
-            return false;
-        if (seg === 'node_modules' || seg === 'dist' || seg === 'build' || seg === 'vendor')
-            return false;
-    }
-    return true;
-}
 const SNIPPET_CHARS = 2_000;
 const EVENTS_PER_POST = 8;
 /** Judging runs server-side in waitUntil (async, after the POST returns), so a
@@ -109,13 +92,16 @@ async function runDocPtr(args) {
     const missingOnly = args.includes('--missing-only');
     const cwd = process.cwd();
     const anchor = (0, project_anchor_1.readAnchor)(cwd);
+    // Paths are relative to the checkout root, so a backfill run from a subfolder
+    // registers the same paths the hook and the doc mirror use.
+    const root = (0, doc_mirror_client_1.docPathRoot)(cwd);
     // Enumerate tracked, eligible docs.
     let tracked;
     try {
         const out = (0, proc_1.safeExecFileSync)('git', ['ls-files', '--', '*.md'], {
-            cwd, encoding: 'utf-8',
+            cwd: root, encoding: 'utf-8',
         });
-        tracked = out.split('\n').map(s => s.trim()).filter(s => s && isDocPathEligible(s));
+        tracked = out.split('\n').map(s => s.trim()).filter(s => s && (0, doc_mirror_client_1.isDocMirrorEligible)(s));
     }
     catch {
         console.error('Not a git repo (or git unavailable) — backfill needs `git ls-files`.');
@@ -158,7 +144,7 @@ async function runDocPtr(args) {
     // manifest. Best-effort: an empty set yields empty manifests (docs read fresh).
     let present = new Set();
     try {
-        const all = (0, proc_1.safeExecFileSync)('git', ['ls-files'], { cwd, encoding: 'utf-8' });
+        const all = (0, proc_1.safeExecFileSync)('git', ['ls-files'], { cwd: root, encoding: 'utf-8' });
         present = new Set(all.split('\n').map(s => s.trim().replace(/\\/g, '/')).filter(Boolean));
     }
     catch { /* not a git repo — manifests stay empty */ }
@@ -166,11 +152,11 @@ async function runDocPtr(args) {
     const events = [];
     for (const rel of targets) {
         try {
-            const snippet = fs.readFileSync(rel, 'utf-8').slice(0, SNIPPET_CHARS);
+            const snippet = fs.readFileSync(path.join(root, rel), 'utf-8').slice(0, SNIPPET_CHARS);
             if (!snippet.trim())
                 continue;
             const p = rel.replace(/\\/g, '/');
-            events.push({ path: p, snippet, refs: present.size ? (0, docptr_refs_1.extractDocRefs)(snippet, p, cwd, present) : [] });
+            events.push({ path: p, snippet, refs: present.size ? (0, docptr_refs_1.extractDocRefs)(snippet, p, root, present) : [] });
         }
         catch { /* skip */ }
     }

package/dist/commands/init.js

@@ -1629,11 +1629,10 @@ function applySettings(settings, apiKey) {
         }
     }
     // PreToolUse (pre-spawn-check) — fires BEFORE every `mcp__ccd_session__spawn_task`
-    // call. Validates the call against three machine-checkable rules from the inline
-    // chip-spawning convention in ~/.claude/CLAUDE.md § Chip Spawning: title prefix
-    // `Chip: `, Block 1 (`git worktree add` in prompt), Block 2 (`greprag send` in
-    // prompt). Returns permissionDecision: "deny" with remediation when any rule
-    // fails; the agent re-composes the call.
+    // call. Validates the call against two machine-checkable rules from
+    // `greprag load chip-spawn`: title prefix `Chip: ` and Block 1 (`git branch -m`
+    // and `git worktree add` in prompt). Returns permissionDecision: "deny" with remediation when
+    // either rule fails; the agent re-composes the call.
     const preSpawnCheckHook = {
         matcher: 'mcp__ccd_session__spawn_task',
         hooks: [{ type: 'command', command: 'greprag-hook pre-spawn-check', timeout: 3000 }],

package/dist/commands/load-primer-reminder.js

@@ -29,10 +29,10 @@ exports.LOAD_PRIMER = [
     '• Pointers (below) name a trigger + the entry to load at that moment. Or browse the catalog yourself any time you suspect a method exists.',
 ].join('\n');
 /** POINTER — the one standing chip pointer. Thin: trigger + load command. The
- *  method (Block 1/Block 2) and the multi-chip upgrade both live in the payload. */
+ *  method (Block 1 + report-back) and the multi-chip upgrade both live in the payload. */
 exports.CHIP_SPAWN_POINTER = [
     '[greprag chips — agent coordination is built in (messaging plumbing in the inbox primer).]',
-    '• About to spawn a chip (`spawn_task`)? → run `greprag load chip-spawn` FIRST for the method (Block 1 worktree + Block 2 report-back); it carries the multi-chip upgrade path inline. Non-negotiable — the spawn validator rejects an unstructured chip.',
+    '• About to spawn a chip (`spawn_task`)? → run `greprag load chip-spawn` FIRST for the method (Block 1 worktree + report-back); it carries the multi-chip upgrade path inline. Non-negotiable — the spawn validator rejects an unstructured chip.',
 ].join('\n');
 /** POINTER — OpenCode's native chip path (the fix-chip era vehicle: `greprag
  *  opencode chip` HTTP spawn, goals, native child sessions). Supersedes the

package/dist/commands/load.js

@@ -51,6 +51,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundleOwnsSkill = bundleOwnsSkill;
 exports.runLoad = runLoad;
 exports.normalizeLoadName = normalizeLoadName;
 const fs = __importStar(require("fs"));
@@ -72,7 +73,7 @@ const LIBRARY = {
     },
     'chip-spawn': {
         files: ['skill/templates/chip-spawn.md'],
-        purpose: 'How to spawn one chip correctly (Block 1 worktree + Block 2 report-back). Carries the multi-chip upgrade path inline.',
+        purpose: 'How to spawn one chip correctly (Block 1 worktree + report-back). Carries the multi-chip upgrade path inline.',
     },
     'codex-chip-spawn': {
         files: ['skill/templates/codex-chip-spawn.md'],
@@ -118,6 +119,13 @@ const LIBRARY = {
 function payloadPath(file) {
     return path.join(__dirname, '..', '..', file);
 }
+/** True when the CLI ships `name` as its own skill bundle (`skill/<name>/`) and
+ *  serves it from this library. The bundle is that skill's canon, so its global
+ *  id means the bundle; a mirror row under the same name can only be a copy of
+ *  an installed bundle, frozen when it was captured. adr: adr/skill-adapter-never-canon.md */
+function bundleOwnsSkill(name) {
+    return LIBRARY[name]?.files[0] === `skill/${name}/SKILL.md`;
+}
 // ---------- Tier 3 — the skill mirror (docs/load-system.md) -------------------
 const API_URL_DEFAULT = 'https://api.greprag.com';
 const MIRROR_TIMEOUT_MS = 4_000;
@@ -185,25 +193,28 @@ async function printCatalog() {
     console.log(`  ${'agents'.padEnd(width)}  Deprecated alias for instructions.`);
     // Tier-3 section: the operator's own skills, auto-mirrored from use.
     const data = await mirrorGet('/v1/skillmirror');
-    const skills = data?.skills || [];
+    // A mirror row under a bundled skill's name is a stale copy; the bundled
+    // entry above is that skill.
+    const skills = (data?.skills || [])
+        .filter((s) => !bundleOwnsSkill(s.skillName || ''));
     if (skills.length > 0) {
         // A mirrored skill with no native adapter on this harness never reaches the
         // harness's own skill list — the agent can only reach it through this
         // catalog. Mark the gap here and name the command that closes it.
+        // A hand-kept copy does reach that list, but the harness runs the copy and
+        // never sees canon move on, so it is marked too (with `~`).
         const platform = (0, harness_1.inferCurrentHarness)() || '';
-        const installed = platform
+        const native = platform
             ? (0, skill_activation_manifest_1.readNativeSkillNames)({ platform, cwd: process.cwd(), homeDir: os.homedir() })
-            : new Set();
-        const missing = platform
-            ? skills.map((s) => s.skillName || '').filter((n) => n && !installed.has(n.toLowerCase()))
-            : [];
+            : new Map();
+        const { missing, localCopies } = (0, skill_activation_manifest_1.nativeAdapterGap)(platform, skills, native);
         const w = Math.max(...skills.map((s) => (s.skillName || '').length), 8);
         console.log('\nYour mirrored skills (auto-fresh from use — work on any machine/harness):\n');
         for (const s of skills) {
             if (!s.skillName)
                 continue;
             const scope = s.scope === 'project' && s.projectId ? ` [project:${s.projectId.slice(0, 8)}]` : '';
-            const gap = missing.includes(s.skillName) ? ' *' : '';
+            const gap = missing.includes(s.skillName) ? ' *' : localCopies.includes(s.skillName) ? ' ~' : '';
             console.log(`  ${(s.skillName + scope + gap).padEnd(w + 20)}  ${(s.description || '').slice(0, 110)}`);
         }
         const installCommand = (0, skill_activation_manifest_1.nativeAdapterInstallCommand)(platform, missing);
@@ -212,6 +223,13 @@ async function printCatalog() {
             console.log('    in this harness\'s own skill list. Install the adapters with:\n');
             console.log(`      ${installCommand}\n`);
         }
+        const cutoverCommand = (0, skill_activation_manifest_1.localCopyCutoverCommand)(platform, localCopies);
+        if (cutoverCommand) {
+            console.log(`\n  ~ ${localCopies.length} skill(s) run from a hand-kept copy in ${platform}, not an adapter — the harness`);
+            console.log('    keeps running that copy when the mirrored skill changes. Replacing a copy is a per-skill');
+            console.log('    call; its SKILL.md is backed up first:\n');
+            console.log(`      ${cutoverCommand}\n`);
+        }
     }
     console.log('\n  greprag load <name>            print the full entry / mirrored skill');
     console.log('  greprag load /<name>           print a user-named slash skill');
@@ -375,8 +393,13 @@ async function printStateDocHints(name, skillBody) {
     const data = await mirrorPost(`/v1/doc/${projectId}/search`, { query, limit: 5 });
     if (!data)
         return;
+    // This block calls what it lists authoritative, so it lists only what the
+    // mirror would accept today. Skill files mirrored before skill trees were
+    // excluded, or by an older CLI, stay until a full `greprag doc update` prunes
+    // them.
+    // adr: adr/doc-mirror-state-only.md
     const docs = (data.docs || [])
-        .filter((d) => typeof d.path === 'string' && d.path.trim().length > 0)
+        .filter((d) => typeof d.path === 'string' && (0, doc_mirror_client_1.isDocMirrorEligible)(d.path))
         .slice(0, 5);
     if (docs.length > 0) {
         process.stdout.write('\n[STATE DOCS — relevant project state from the current repo mirror]\n');
@@ -484,12 +507,22 @@ async function runLoad(args) {
         console.error('No canonical GrepRAG Instructions found. Seed them with `greprag instructions adopt <CLAUDE.md|AGENTS.md>`.');
         process.exit(1);
     }
-    const entry = LIBRARY[name];
+    // An explicit --skill-id names one mirrored skill, so it outranks a bundled
+    // entry that merely shares the name, and a miss is an error rather than a
+    // quiet fallback to the bundled payload. A skill the CLI ships as its own
+    // bundle is the exception: its global id is the bundle, so every harness's
+    // launcher reaches the same canon. adr: adr/skill-adapter-never-canon.md
+    const mirroredArgs = parseMirroredLoadArgs(args.slice(1));
+    const bundleCanon = mirroredArgs.skillId === `global:${name}` && bundleOwnsSkill(name);
+    const entry = mirroredArgs.skillId && !bundleCanon ? undefined : LIBRARY[name];
     if (!entry) {
-        // Not bundled → try the Tier-3 skill mirror before giving up.
-        const mirroredArgs = parseMirroredLoadArgs(args.slice(1));
         if (await printMirroredSkill(name, mirroredArgs))
             return;
+        if (mirroredArgs.skillId) {
+            console.error(`No mirrored skill "${name}" with id ${mirroredArgs.skillId}.`);
+            process.exitCode = 1;
+            return;
+        }
         console.error(`Unknown load entry: ${name}\n`);
         await printCatalog();
         process.exitCode = 1;

package/dist/commands/merge-guard.js

@@ -22,7 +22,7 @@
  *      plumbing that happens to share a prefix, and `merge-base` is used BY the
  *      provenance check — blocking it would break the gate with the guard.
  *    · only a merge nothing already serialises. A command that takes the lock
- *      itself, ahead of the merge and `&&`-joined to it, is already serialised.
+ *      itself and stops on acquisition failure is already serialised.
  *
  *  Holding the lock yourself is a pass. A peer holding it is the refusal that
  *  matters: it is the exact collision, caught before the merge instead of after.
@@ -51,6 +51,12 @@
  *     trips. Only `&&` earns this: after `;` or `||` the merge still runs when the
  *     acquire failed, so those are refused, and the refusal now says so.
  *
+ *  A THIRD, 2026-10-06 in C:/sift: an acquire run from a linked worktree wrote the
+ *  lock into that worktree's private git dir, so this guard, reading the canonical
+ *  checkout, refused the holder's own merge whatever its shape. Locks now live in the
+ *  repository's shared `.git`, and a chained acquire counts when it writes the same
+ *  lock file this guard reads.
+ *
  *  # adr: adr/deploy-gate-cli.md
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -126,11 +132,11 @@ function shellSegments(command) {
     let start = 0;
     let afterAnd = true;
     for (let match = separator.exec(masked); match; match = separator.exec(masked)) {
-        segments.push({ text: source.slice(start, match.index), afterAnd });
+        segments.push({ text: source.slice(start, match.index), start, afterAnd });
         afterAnd = match[0] === '&&';
         start = match.index + match[0].length;
     }
-    segments.push({ text: source.slice(start), afterAnd });
+    segments.push({ text: source.slice(start), start, afterAnd });
     return segments;
 }
 /** Quote-aware tokens. A quoted run is one token with its quotes removed, so
@@ -297,9 +303,10 @@ function buildMergeGuardReason(held, ownership) {
         '  greprag merge-lock acquire --label "<what you are merging>"',
         '  git merge --ff-only <rebased branch>',
         '  greprag merge-lock release --landed <the merge sha> --label "<what it was>"',
-        'One call works too, as long as the acquire comes first and every step is joined by',
-        '`&&` — that is what stops the merge when someone else holds the lock. A `;` or `||`',
-        'between them runs the merge anyway, so those are refused.',
+        'One call works too when the acquire comes first and failure stops the merge:',
+        'use an `&&` chain, or in PowerShell a try/finally block with an immediate',
+        '`if ($LASTEXITCODE -ne 0) { throw ... }` after acquire. Bare `;` and `||`',
+        'let the merge run after a failed acquire, so those are refused.',
         '`--landed` is what lets the deploy prove YOUR work is in what ships, rather than only',
         'that production serves HEAD. Merging in a worktree instead? That is never blocked.',
     ].join(' ');
@@ -357,7 +364,8 @@ function guardMergeAt(input, segments, mergeAt) {
     // truncating it locally to 8 was a second copy of identity logic waiting to disagree
     // with the one in session-id.ts.
     const ownership = (0, deploy_locks_1.lockOwnership)(held, input.session_id);
-    const chainedLock = takesLockForTarget(segments, mergeAt, cwd, target);
+    const chainedLock = takesLockForTarget(segments, mergeAt, cwd, target)
+        || powerShellTryTakesLock(input.tool_input?.command ?? input.tool_input?.cmd ?? '', segments[mergeAt].start, cwd, target);
     if (ownership !== 'mine' && !chainedLock)
         return denyMerge(input, buildMergeGuardReason(held, ownership));
     // Git owns the final freshness check AT mutation time. Even if master changes
@@ -403,11 +411,88 @@ function takesLockForTarget(segments, mergeAt, cwd, target) {
             return false;
         if (!isMergeLockAcquire(segments[i - 1].text))
             continue;
-        const lockDir = mergeCwd(segments, i - 1, cwd);
-        return (0, deploy_gate_1.normalizePath)(mergeWorktreeRoot([], lockDir) ?? lockDir) === (0, deploy_gate_1.normalizePath)(target);
+        return acquiresTargetLock(mergeCwd(segments, i - 1, cwd), target);
+    }
+    return false;
+}
+/** An acquire run in `dir` serialises a merge into `target` exactly when it writes the
+ *  lock the guard reads for `target`. The lock is repository-wide, so an acquire from a
+ *  linked worktree counts; comparing worktree roots refused that holder on 2026-10-06. */
+function acquiresTargetLock(dir, target) {
+    try {
+        return (0, deploy_gate_1.normalizePath)((0, deploy_locks_1.mergeLockPath)(dir)) === (0, deploy_gate_1.normalizePath)((0, deploy_locks_1.mergeLockPath)(target));
+    }
+    catch {
+        return false;
+    }
+}
+/** PowerShell's `try { acquire; if ($LASTEXITCODE -ne 0) { throw ... }; merge }
+ * finally { release }` is a fail-closed lock sequence too. Inspect only direct
+ * statements in the try body; a bare semicolon or an acquire nested in a branch
+ * must not excuse a merge. */
+function powerShellTryTakesLock(command, mergeStart, cwd, target) {
+    const masked = maskQuoted(command);
+    const tryStart = /(?:^|[;\n])\s*try\s*\{/gi;
+    for (let match = tryStart.exec(masked); match; match = tryStart.exec(masked)) {
+        const open = masked.indexOf('{', match.index);
+        const close = matchingBrace(masked, open);
+        if (close < 0 || mergeStart <= open || mergeStart >= close)
+            continue;
+        const suffix = masked.slice(close + 1);
+        const finallyMatch = /^\s*finally\s*\{/.exec(suffix);
+        if (!finallyMatch || matchingBrace(masked, close + 1 + finallyMatch[0].lastIndexOf('{')) < 0)
+            continue;
+        const statements = powerShellStatements(command, masked, open + 1, close);
+        const mergeIndex = statements.findIndex(s => mergeStart >= s.start && mergeStart < s.end);
+        if (mergeIndex < 2 || mergeGlobalOpts(statements[mergeIndex].text)?.length !== 0)
+            continue;
+        // A location change would make the lock's target ambiguous. The regular
+        // chained-command path already resolves simple cd/Set-Location sequences.
+        if (/(?:^|[;\n])\s*(?:cd|chdir|sl|Set-Location|Push-Location|Pop-Location|pushd|popd)\b/i.test(masked.slice(0, mergeStart)))
+            continue;
+        if (!acquiresTargetLock(cwd, target))
+            continue;
+        for (let i = mergeIndex - 2; i >= 0; i--) {
+            if (!isMergeLockAcquire(statements[i].text))
+                continue;
+            if (/[|&]/.test(maskQuoted(statements[i].text)))
+                continue;
+            if (!/^if\s*\(\s*\$LASTEXITCODE\s*-ne\s*0\s*\)\s*\{\s*throw\b[^{}]*\}\s*$/i.test(statements[i + 1].text.trim()))
+                continue;
+            if (statements.slice(i + 2, mergeIndex).some(s => /\bmerge-lock\s+release\b/i.test(s.text)))
+                continue;
+            return true;
+        }
     }
     return false;
 }
+function matchingBrace(masked, open) {
+    let depth = 0;
+    for (let i = open; i < masked.length; i++) {
+        if (masked[i] === '{')
+            depth++;
+        else if (masked[i] === '}' && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+function powerShellStatements(command, masked, start, end) {
+    const statements = [];
+    let depth = 0;
+    let from = start;
+    for (let i = start; i < end; i++) {
+        if (masked[i] === '{')
+            depth++;
+        else if (masked[i] === '}')
+            depth--;
+        else if (depth === 0 && (masked[i] === ';' || masked[i] === '\n')) {
+            statements.push({ text: command.slice(from, i).trim(), start: from, end: i });
+            from = i + 1;
+        }
+    }
+    statements.push({ text: command.slice(from, end).trim(), start: from, end });
+    return statements.filter(s => s.text);
+}
 function denyMerge(input, reason) {
     return {
         hookSpecificOutput: {

package/dist/commands/parity.js

@@ -80,10 +80,8 @@ const SEED_UNITS = [
     {
         name: 'chip-spawn',
         followers: [
-            { harness: 'claude-code', candidate: '~/.claude/docs/chip-spawn.md' },
             { harness: 'claude-code', candidate: 'packages/cli/skill/templates/chip-spawn.md' },
             { harness: 'codex', candidate: 'packages/cli/skill/templates/codex-chip-spawn.md' },
-            { harness: 'codex', candidate: 'docs/codex-chip-spawn.md' },
             { harness: 'opencode', candidate: null, note: 'no dedicated opencode chip-spawn doc found — chips ride greprag opencode chip + templates/chip-leader-opencode.md covers the leader shape only' },
         ],
     },