greprag 5.82.0 → 5.83.0

package/dist/hook.js

@@ -91,6 +91,7 @@ const persona_1 = require("./commands/persona");
 const app_settings_1 = require("./app-settings");
 const inbox_primer_reminder_1 = require("./commands/inbox-primer-reminder");
 const skill_activation_manifest_1 = require("./skill-activation-manifest");
+const native_adapter_refresh_1 = require("./native-adapter-refresh");
 const worktree_state_1 = require("./worktree-state");
 // Ingress-trigger bridge, Adapter A (LOCAL/state half) — the Stop hook computes
 // the deterministic state values (stress / turnCount / keyword-seen) from the
@@ -644,37 +645,18 @@ function capField(text) {
 //
 // The Document Pointer System's detect half. No new hook: the Stop hook already
 // sees every file the turn touched (filesTouched), so .md writes ride the same
-// event — a deterministic path filter here, the Flash-Lite worthiness judge
-// server-side. Best-effort end to end: a docptr failure never blocks a turn.
-/** Deterministic pre-filter — the cheap gate BEFORE the LLM judge. Rejects the
- *  obvious never-index classes so they don't even cost a judge call: non-.md,
- *  dot-directories (.tmp-*, .claude/, .github/ — harness/scratch, not project
- *  docs), dependency/build trees, and the harness-owned CLAUDE.md/MEMORY.md
- *  (always injected anyway — indexing them is circular noise). Judge-worthy
- *  ambiguity (drafts, beats, plans) is the JUDGE's call, not this filter's. */
-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;
-}
+// event — the doc mirror's eligibility rule here (isDocMirrorEligible: project
+// state only, never skill trees or harness followers), the Flash-Lite worthiness
+// judge server-side. Paths are relative to the checkout root (docPathRoot), the
+// same root the mirror uses. Best-effort end to end: a docptr failure never
+// blocks a turn.
 /** Head-snippet cap posted to the judge (server re-caps defensively). */
 const DOC_EVENT_SNIPPET_CHARS = 2_000;
 /** Max doc events per turn (mirrors the server's MAX_EVENTS_PER_POST). */
 const DOC_EVENTS_PER_TURN = 8;
 /** Turn's touched files → judge-ready doc events: project-relative eligible
  *  .md paths + head snippets + a CLIENT-CONFIRMED reference manifest. Files
- *  outside cwd (scratchpad, other repos) and unreadable files (deleted later in
+ *  outside the checkout (scratchpad, other repos) and unreadable files (deleted later in
  *  the turn) are skipped silently.
  *
  *  The manifest is built HERE, on the side that has the tree (docs/doc-pointer-
@@ -684,15 +666,16 @@ const DOC_EVENTS_PER_TURN = 8;
  *  LLM ref-extraction is retired to a back-compat fallback (old CLIs send no
  *  refs). Tree unavailable → empty manifests (docs read fresh — bias-to-keep). */
 function collectDocEvents(filesTouched, cwd) {
+    const root = (0, doc_mirror_client_1.docPathRoot)(cwd);
     const staged = [];
     const seen = new Set();
     for (const abs of filesTouched) {
         if (staged.length >= DOC_EVENTS_PER_TURN)
             break;
-        const rel = path.relative(cwd, abs).replace(/\\/g, '/');
+        const rel = path.relative(root, abs).replace(/\\/g, '/');
         if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
             continue;
-        if (!isDocPathEligible(rel) || seen.has(rel))
+        if (!(0, doc_mirror_client_1.isDocMirrorEligible)(rel) || seen.has(rel))
             continue;
         try {
             const snippet = fs.readFileSync(abs, 'utf-8').slice(0, DOC_EVENT_SNIPPET_CHARS);
@@ -709,14 +692,14 @@ function collectDocEvents(filesTouched, cwd) {
     let present = new Set();
     try {
         const all = (0, proc_1.safeExecSync)('git ls-files', {
-            cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+            cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
         });
         present = new Set(all.split('\n').map((s) => s.trim().replace(/\\/g, '/')).filter(Boolean));
     }
     catch { /* not a git repo — manifests stay empty */ }
     return staged.map((e) => ({
         ...e,
-        refs: present.size ? (0, docptr_refs_1.extractDocRefs)(e.snippet, e.path, cwd, present) : [],
+        refs: present.size ? (0, docptr_refs_1.extractDocRefs)(e.snippet, e.path, root, present) : [],
     }));
 }
 // ---------- Procedure span observer (docs/procedure-system.md) --------------
@@ -975,12 +958,13 @@ async function fetchDocPointers(apiUrl, apiKey, anchor, cwd) {
         let presentPaths; // eligible .md — the existence sweep
         let trackedAll; // ALL tracked files — the manifest oracle
         try {
+            const root = (0, doc_mirror_client_1.docPathRoot)(cwd);
             const md = (0, proc_1.safeExecSync)('git ls-files -- "*.md"', {
-                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+                cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
             });
-            presentPaths = md.split('\n').map(s => s.trim()).filter(s => isDocPathEligible(s));
+            presentPaths = md.split('\n').map(s => s.trim()).filter(s => (0, doc_mirror_client_1.isDocMirrorEligible)(s));
             const all = (0, proc_1.safeExecSync)('git ls-files', {
-                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+                cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
             });
             trackedAll = new Set(all.split('\n').map(s => s.trim().replace(/\\/g, '/')).filter(Boolean));
         }
@@ -1624,7 +1608,9 @@ async function recap(input, mode = 'plain', opts = {}) {
     const skillGainsPromise = fetchAndLandSkillGains(cfg.apiUrl, cfg.apiKey, anchor, cwd);
     // Tier-3 skill activation manifest (docs/load-system.md): fetch canonical
     // full descriptions, then omit skills this harness already advertises
-    // natively. Best-effort; the renderer remains pure.
+    // natively. Best-effort; the renderer remains pure. The same roster is what
+    // installed adapters are checked against, so keeping them at canon costs no
+    // extra round trip unless one is stale. adr: adr/skill-bundle-shape.md
     const mirroredSkillsPromise = (async () => {
         try {
             const params = new URLSearchParams({ scope: 'effective', projectId: anchor.projectId });
@@ -1634,8 +1620,12 @@ async function recap(input, mode = 'plain', opts = {}) {
             if (!res.ok)
                 return undefined;
             const data = await res.json();
+            const rows = data.skills || [];
+            await (0, native_adapter_refresh_1.refreshNativeAdapters)({
+                platform, rows, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey, homeDir: os.homedir(), projectDir: cwd,
+            }).catch(() => undefined);
             return (0, skill_activation_manifest_1.activationFromApiRows)({
-                rows: data.skills || [],
+                rows,
                 platform,
                 cwd,
                 homeDir: process.env.HOME || process.env.USERPROFILE || '',
@@ -2203,10 +2193,16 @@ function validateChip(title, prompt) {
             `"Chip: Fix stale README badge" or "Chip B: Build freshness engine". ` +
             `The prefix distinguishes chip-spawned sessions from IDE/human sessions in FleetView.`);
     }
-    if (!/\bgit\s+worktree\s+add\b/.test(prompt)) {
-        violations.push(`prompt missing worktree setup. ` +
-            `Block 1 requires the chip to open with: \`git worktree add .claude/worktrees/<slug> -b chip/<slug>\` ` +
-            `then \`cd\` into it. Chips never edit the main checkout.`);
+    // Block 1 carries both steps: `git branch -m` keeps the fresh worktree the
+    // desktop app already gave the chip, `git worktree add` makes one on a local
+    // start. `git worktree add` alone is the old Block 1, which built a second
+    // worktree beside the app's — reject it so no stale copy brings that back.
+    if (!/\bgit\s+worktree\s+add\b/.test(prompt) || !/\bgit\s+branch\s+-m\b/.test(prompt)) {
+        violations.push(`prompt missing the current worktree setup. ` +
+            `Paste Block 1 verbatim from \`greprag load chip-spawn\`: it keeps the worktree the desktop app ` +
+            `already gave the chip (renaming its fresh branch to chip/<slug>) and runs ` +
+            `\`git worktree add .claude/worktrees/<slug> -b chip/<slug>\` only on a local start. ` +
+            `Chips never edit the main checkout.`);
     }
     // NO report-back check. Chips report to the parent with native
     // `SendMessage to: "<parent-name>"`, which needs no greprag address and no
@@ -2220,7 +2216,7 @@ function validateChip(title, prompt) {
  *  dropped by the CCD harness for MCP `spawn_task` calls (see
  *  adr/spawn-task-hook-mode.md 2026-05-27 entry — Tier 2 augmentation
  *  attempt). `permissionDecision: deny` IS honored, so the validator
- *  catches missing Block 1 / Block 2 markers; the agent re-composes the
+ *  catches a missing title prefix or Block 1 marker; the agent re-composes the
  *  call with the templates from `greprag load chip-spawn`. */
 function handlePreSpawnCheck(input) {
     if (input.tool_name !== 'mcp__ccd_session__spawn_task')

package/dist/index.js

@@ -325,16 +325,16 @@ async function runDesk(args) {
     process.exitCode = 1;
 }
 async function inbox(args) {
+    const sub = args[0];
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(args[1] === 'watch' ? INBOX_WATCH_HELP : INBOX_HELP);
+        return;
+    }
     const cfg = getConfig();
     if (!cfg.apiKey) {
         console.error('Not configured. Run: greprag init');
         process.exit(1);
     }
-    const sub = args[0];
-    if (sub === '--help' || sub === '-h' || sub === 'help') {
-        console.log(INBOX_HELP);
-        return;
-    }
     // A non-flag first arg that isn't a known subcommand is a typo — do NOT fall
     // through to list mode (which auto-marks every message read). The classic
     // slip is `inbox send` (the real reply command is top-level `greprag send`).
@@ -351,13 +351,6 @@ async function inbox(args) {
     }
     if (sub === 'watch') {
         const subArgs = args.slice(1);
-        // --help MUST be checked before launching the watch. Pre-fix, `inbox
-        // watch --help` started a live SSE watch instead of printing help (smell
-        // 3d908baa) — the help flag silently armed a watcher. Print and return.
-        if (subArgs.includes('--help') || subArgs.includes('-h')) {
-            console.log(INBOX_WATCH_HELP);
-            return;
-        }
         // The Assistant role was removed 2026-09-03 (adr/assistant-role.md). Fail
         // loudly rather than silently arming a stock watcher — 5.44.0 already
         // shipped a build where `--assistant` was dropped without error and the
@@ -1059,16 +1052,16 @@ async function send(args) {
 }
 /** greprag discord <pair|unpair|me> — Discord DM bridge to inbox. */
 async function discord(args) {
-    const cfg = getConfig();
-    if (!cfg.apiKey) {
-        console.error('Not configured. Run: greprag init');
-        process.exit(1);
-    }
     const sub = args[0];
     if (!sub || sub === 'help' || sub === '--help') {
         console.log(discord_1.DISCORD_HELP);
         return;
     }
+    const cfg = getConfig();
+    if (!cfg.apiKey) {
+        console.error('Not configured. Run: greprag init');
+        process.exit(1);
+    }
     if (sub === 'pair') {
         const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
         if (!anchor.projectId) {
@@ -1318,7 +1311,10 @@ Commands:
                                    parent of repo root). Each becomes inbox-addressable.
   status [--json] [--claude|--codex|--opencode|--grok]
                                   Installation, auth, platform hooks/plugins, and project state
-  codex doctor                    Diagnose Codex hooks, trust setup, and current thread
+  announce [--session <8hex>] [--path]
+                                  Print the full SessionStart announce (the harness
+                                  inlines only ~2KB; the rest is parked on disk)
+  codex doctor                   Diagnose Codex hooks, trust setup, and current thread
   project-id                       Print the current project_id
   session-id [--full]              Print this session's id (8-hex, 16-hex for UUIDv7, or full UUID with --full).
   discover [--json]                Tenant-wide structure: every project, per-shape row counts,
@@ -1526,11 +1522,12 @@ Corpus (upload + search arbitrary text — books, codebases, references):
                                 Single-store search. <store> is a UUID or name.
   corpus search "<intent>" --all|--store <ref>...  [--kind K] [--limit 8]
                                 Multistore search (RRF-fused). --all = every store.
-  corpus section <store> "<heading>"
+  corpus section <store> "<heading>" [--max-chars N]
                                 Every node under a heading (forgiving: any depth,
                                 dash/case-insensitive).
-  corpus walk <store> <nodeId> [--before 2 --after 2]
-                                Show a node and its surrounding context.
+  corpus walk <store> <nodeId> [--before 2 --after 2] [--max-chars N]
+                                Show a node and its surrounding context. Both
+                                print full node text; --max-chars N cuts each node.
   corpus status <store>         Write-side enrichment progress (per-node vocab bridge).
   corpus refresh <store>        Manually re-check a tracked source (re-ingest changed blocks).
   corpus sources <store>        Freshness state: source, policy, last change, next check.
@@ -1650,12 +1647,15 @@ Examples:
   greprag send "Bug in auth flow — repro at line 42" --to alice@greprag.com/abc12345 \
     --file src/auth.ts:42 --artifact commit:abc123
 `.trim();
-/** Groups that ship their own detailed `--help`. `help --all` invokes each one
+/** Groups that ship their own detailed `--help`. A help flag anywhere after one
+ *  of these prints it (printCommandHelp), and `help --all` invokes each one
  *  live and captures its output, so the assembled guide is rendered from the
  *  exact printers an agent gets via `greprag <group> --help` — it cannot drift
- *  from them. New group with its own --help? Add it here. (The help-coverage
- *  test flags any dispatched command that never appears in a help surface.) */
-const HELP_ALL_GROUPS = [
+ *  from them. Each is called as fn(['--help', ...words]) and must print and
+ *  return. New group with its own --help? Add it here, or its --help shows the
+ *  overview. (The help-coverage test flags any dispatched command that never
+ *  appears in a help surface.) */
+const HELP_GROUPS = [
     ['inbox', inbox],
     ['email', email_1.runEmail],
     ['memory', memory_1.runMemory],
@@ -1680,6 +1680,18 @@ const HELP_ALL_GROUPS = [
     ['opencode', opencode],
     ['crush', crush_1.runCrush],
     ['archive', archive_1.runArchive],
+    ['init', () => { console.log(INIT_HELP); }],
+    ['app', app_1.runApp],
+    ['announce', runAnnounce],
+    ['search', search_1.runSearch],
+    ['session', session_1.runSession],
+    ['context', context_governor_1.runContext],
+    ['repodoc', repodoc_1.runRepoDoc],
+    ['parity', parity_1.runParity],
+    ['grok', grok_spawn_1.runGrok],
+    ['docptr', docptr_1.runDocPtr],
+    ['loadout', loadout_1.runLoadout],
+    ['skillgain', skillgain_1.runSkillGain],
 ];
 const OPENCODE_HELP = `greprag opencode — bridge greprag inbox into a running opencode desktop
 session, plus a file-watching capture pipeline for episodic memory.
@@ -1805,6 +1817,8 @@ Run under a long-lived shell loop or as a Windows service:
 async function opencode(args) {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        if (args[1] === 'chip')
+            return (0, opencode_chip_1.runOpencodeChip)(['--help', ...args.slice(2)]);
         console.log(OPENCODE_HELP);
         return;
     }
@@ -1859,13 +1873,25 @@ async function captureOutput(fn) {
 async function printHelpAll() {
     const bar = '═'.repeat(72);
     const parts = [HELP];
-    for (const [name, fn] of HELP_ALL_GROUPS) {
+    for (const [name, fn] of HELP_GROUPS) {
         const body = (await captureOutput(() => fn(['--help']))).trim();
         if (body)
             parts.push(`${bar}\n  greprag ${name}\n${bar}\n${body}`);
     }
     console.log(parts.join('\n\n'));
 }
+/** Help for `greprag <command> ... --help`. The words before the first flag let
+ *  a group show the part of its help they name (`inbox watch --help` → the
+ *  watch guide); a command without help of its own gets the overview. */
+async function printCommandHelp(command, subArgs) {
+    const group = HELP_GROUPS.find(([name]) => name === command);
+    if (!group) {
+        console.log(HELP);
+        return;
+    }
+    const words = subArgs.slice(0, subArgs.findIndex(arg => arg.startsWith('-')));
+    await group[1](['--help', ...words]);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -1881,6 +1907,16 @@ async function main() {
         console.log(HELP);
         return;
     }
+    const subArgs = args.slice(1);
+    // A help flag anywhere after the command asks for help, so the command never
+    // runs. Each group parses its own argv and looks for help only in its first
+    // slot, so one further along fell through into a real run: `skill mirror
+    // sync --help` dropped the flag and synced every harness, `skill edit --help`
+    // sent "--help" to the API as a skill name. adr: adr/cli-help-dispatch.md
+    if (subArgs.some(arg => arg === '--help' || arg === '-h')) {
+        await printCommandHelp(command, subArgs);
+        return;
+    }
     // Load ~/.greprag/.env ONCE for every command. Commands that read
     // process.env.GREPRAG_API_KEY directly (load, loadout, …) used to work only
     // in shells with the var exported — a fresh terminal got "GREPRAG_API_KEY
@@ -1888,7 +1924,6 @@ async function main() {
     // config themselves) worked fine (field incident 2026-07-12, tenant tanya).
     // Dispatch-level ensureEnv kills the whole per-command-forgot-env class.
     ensureEnv();
-    const subArgs = args.slice(1);
     switch (command) {
         case 'app':
         case 'dashboard': return (0, app_1.runApp)(subArgs);

package/dist/native-adapter-refresh.js

@@ -0,0 +1,114 @@
+"use strict";
+/** Keep installed native skill adapters at canon.
+ *
+ *  Adapters were written only by explicit syncs (init, `skill mirror sync`,
+ *  `--only`), so a canon change made anywhere — `skill mirror apply`, another
+ *  session, another machine — left them behind until someone re-synced by hand.
+ *
+ *  SessionStart calls this with the mirror roster it already fetched. Detection
+ *  is local: each managed adapter's stamps against the roster. Only a stale
+ *  adapter costs a fetch, and every write goes through the writer the sync
+ *  commands use, so the ownership ledger and the divergence guard still decide
+ *  what may be replaced. Refresh-only: no adapter is created or removed here.
+ */
+// adr: adr/skill-bundle-shape.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAdapterStamps = readAdapterStamps;
+exports.staleNativeAdapters = staleNativeAdapters;
+exports.refreshNativeAdapters = refreshNativeAdapters;
+const claude_lifecycle_cutover_1 = require("./claude-lifecycle-cutover");
+const native_skill_mirror_1 = require("./native-skill-mirror");
+const skill_mirror_files_1 = require("./skill-mirror-files");
+/** The identity stamps a generated adapter carries in its frontmatter. */
+function readAdapterStamps(content) {
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(content.replace(/\r\n?/g, '\n'))?.[1] || '';
+    const field = (key) => new RegExp(`^${key}:[ \\t]*(\\S+)`, 'm').exec(frontmatter)?.[1];
+    const revision = field('greprag_revision');
+    return {
+        skillId: field('greprag_skill_id'),
+        contentHash: field('greprag_content_hash'),
+        revision: revision === undefined ? undefined : Number(revision),
+        format: field('greprag_adapter_format'),
+    };
+}
+/** Managed adapters whose canon or renderer has moved since they were written.
+ *  An adapter edited locally, so its bytes no longer match the ledger, stays
+ *  with the divergence guard and costs no fetch. A missing one stays missing. */
+function staleNativeAdapters(params) {
+    const globalRoot = (0, native_skill_mirror_1.nativeSkillRoot)(params.platform, params.homeDir);
+    const roots = [globalRoot];
+    // Claude adapters live only in the home root (claude-lifecycle-cutover.ts).
+    const projectRoot = params.projectDir && params.platform !== 'claude-code'
+        ? (0, native_skill_mirror_1.writerOwnedProjectSkillRoot)(params.platform, params.projectDir, params.homeDir)
+        : null;
+    if (projectRoot)
+        roots.push(projectRoot);
+    const byId = new Map();
+    for (const row of params.rows) {
+        if (typeof row.skillName === 'string' && typeof row.skillId === 'string') {
+            byId.set(row.skillId, row);
+        }
+    }
+    const format = (0, native_skill_mirror_1.nativeAdapterFormat)(params.platform);
+    const stale = [];
+    for (const root of roots) {
+        for (const [skillName, managed] of Object.entries((0, native_skill_mirror_1.readState)(root).skills)) {
+            let files;
+            try {
+                files = (0, native_skill_mirror_1.readManagedFiles)((0, native_skill_mirror_1.targetPath)(root, skillName), managed);
+            }
+            catch {
+                continue;
+            }
+            if (!files?.length || (0, skill_mirror_files_1.computeSkillFileHash)(files) !== managed.hash)
+                continue;
+            const stamps = readAdapterStamps(files.find(file => file.path === 'SKILL.md')?.content || '');
+            const row = byId.get(stamps.skillId || (root === globalRoot ? `global:${skillName}` : ''));
+            if (!row || row.skillName !== skillName)
+                continue;
+            // The content hash is canon's identity. Revision only decides for a row
+            // that predates content hashes; comparing it otherwise would fight writers
+            // that do not know the revision.
+            const canonMoved = row.contentHash
+                ? row.contentHash !== stamps.contentHash
+                : typeof row.revision === 'number' && row.revision !== stamps.revision;
+            if (canonMoved || stamps.format !== format)
+                stale.push({ root, row });
+        }
+    }
+    return stale;
+}
+/** Rewrite each stale managed adapter of this harness from canon, through the
+ *  writer the sync commands use. One adapter per write, so a diverged one holds
+ *  back no other. A harness without native adapters is a no-op. */
+async function refreshNativeAdapters(params) {
+    const platform = params.platform;
+    if (platform !== 'claude-code' && platform !== 'codex' && platform !== 'opencode') {
+        return { refreshed: 0, blocked: 0 };
+    }
+    const stale = staleNativeAdapters({ ...params, platform });
+    const skills = await Promise.all(stale.map(({ row }) => (0, native_skill_mirror_1.fetchNativeMirroredSkill)(params.apiUrl, params.apiKey, row).catch(() => null)));
+    let refreshed = 0;
+    let blocked = 0;
+    for (const skill of skills) {
+        if (!skill)
+            continue; // canon unreachable: the next session start retries
+        try {
+            const result = platform === 'claude-code'
+                ? (0, claude_lifecycle_cutover_1.applyClaudeLifecycleCutover)({ skills: [skill], names: [skill.skillName], homeDir: params.homeDir })
+                : (0, native_skill_mirror_1.applyNativeSkillMirror)({
+                    platform,
+                    skills: [skill],
+                    homeDir: params.homeDir,
+                    projectDir: params.projectDir,
+                    prune: false,
+                });
+            refreshed += result.updated;
+            blocked += result.blocked;
+        }
+        catch {
+            blocked++;
+        }
+    }
+    return { refreshed, blocked };
+}

package/dist/native-skill-adoption.js

@@ -41,49 +41,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const native_skill_mirror_1 = require("./native-skill-mirror");
 const skill_mirror_files_1 = require("./skill-mirror-files");
-const STATE_FILE = '.greprag-mirror.json';
 const NATIVE_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function emptyState() {
-    return { version: 1, skills: {} };
-}
-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 run or corrupt state: existing directories remain unmanaged */ }
-    return emptyState();
-}
-function writeState(root, state) {
-    fs.mkdirSync(root, { recursive: true });
-    fs.writeFileSync(path.join(root, STATE_FILE), JSON.stringify(state, null, 2) + '\n', 'utf8');
-}
-function targetPath(root, skillName) {
-    const target = path.resolve(root, skillName);
-    const prefix = path.resolve(root) + path.sep;
-    if (!target.startsWith(prefix))
-        throw new Error('skill target escapes native root');
-    return target;
-}
-function filePath(target, relative) {
-    const resolved = path.resolve(target, ...relative.split('/'));
-    const prefix = path.resolve(target) + path.sep;
-    if (!resolved.startsWith(prefix))
-        throw new Error('skill file escapes target directory');
-    return resolved;
-}
-function readManagedFiles(target, managed) {
-    try {
-        return managed.files.map(relative => ({
-            path: relative,
-            content: fs.readFileSync(filePath(target, relative), 'utf8'),
-        }));
-    }
-    catch {
-        return null;
-    }
-}
 function listSkillDirs(root) {
     try {
         return fs.readdirSync(root, { withFileTypes: true })
@@ -122,9 +80,12 @@ function countSkillFiles(root) {
 }
 function adoptionRoots(params) {
     const roots = [{ root: (0, native_skill_mirror_1.nativeSkillRoot)(params.platform, params.homeDir), scope: 'global' }];
-    if (params.projectDir && params.projectId) {
+    const projectRoot = params.projectDir && params.projectId
+        ? (0, native_skill_mirror_1.writerOwnedProjectSkillRoot)(params.platform, params.projectDir, params.homeDir)
+        : null;
+    if (projectRoot) {
         roots.push({
-            root: (0, native_skill_mirror_1.nativeProjectSkillRoot)(params.platform, params.projectDir),
+            root: projectRoot,
             scope: 'project',
             projectId: params.projectId,
             projectName: params.projectName,
@@ -169,12 +130,12 @@ function planNativeSkillAdoption(params) {
         projectId: params.projectId,
         projectName: params.projectName,
     })) {
-        const state = readState(root.root);
+        const state = (0, native_skill_mirror_1.readState)(root.root);
         for (const skillName of listSkillDirs(root.root)) {
-            const target = targetPath(root.root, skillName);
+            const target = (0, native_skill_mirror_1.targetPath)(root.root, skillName);
             const managed = state.skills[skillName];
             if (managed) {
-                const currentFiles = readManagedFiles(target, managed);
+                const currentFiles = (0, native_skill_mirror_1.readManagedFiles)(target, managed);
                 const currentHash = currentFiles ? (0, skill_mirror_files_1.computeSkillFileHash)(currentFiles) : '';
                 const entry = { ...root, skillName, reason: currentHash === managed.hash ? 'managed/current' : 'managed/diverged' };
                 if (currentHash === managed.hash)
@@ -224,8 +185,8 @@ function installAdoptedNativeSkill(params) {
         return 'skipped';
     if (!NATIVE_SKILL_NAME_RE.test(params.skill.skillName))
         return 'skipped';
-    const target = targetPath(params.root, params.skill.skillName);
-    const state = readState(params.root);
+    const target = (0, native_skill_mirror_1.targetPath)(params.root, params.skill.skillName);
+    const state = (0, native_skill_mirror_1.readState)(params.root);
     if (state.skills[params.skill.skillName])
         return 'blocked';
     const currentFiles = params.collectFiles(target);
@@ -234,17 +195,23 @@ function installAdoptedNativeSkill(params) {
     const adapterFiles = (0, native_skill_mirror_1.buildNativeSkillAdapter)(params.platform, params.skill);
     if (!adapterFiles)
         return 'skipped';
-    fs.rmSync(target, { recursive: true, force: true });
-    fs.mkdirSync(target, { recursive: true });
+    // Adoption replaces only the files it just moved into canon. The mirror
+    // carries SKILL.md and docs/**/*.md; everything else in the package
+    // (scripts/, references/, assets/, any non-markdown file) exists nowhere but
+    // this folder, and wiping the folder destroyed exactly those. Write the
+    // adapter, then remove the adopted files it did not overwrite, the same rule
+    // a managed adapter update follows. adr: adr/skill-bundle-shape.md
     for (const file of adapterFiles) {
-        const destination = filePath(target, file.path);
+        const destination = (0, native_skill_mirror_1.filePath)(target, file.path);
         fs.mkdirSync(path.dirname(destination), { recursive: true });
         fs.writeFileSync(destination, file.content, 'utf8');
     }
+    const adapterPaths = new Set(adapterFiles.map(file => file.path));
+    (0, native_skill_mirror_1.removeTrackedFiles)(target, currentFiles.map(file => file.path).filter(relative => !adapterPaths.has(relative)));
     state.skills[params.skill.skillName] = {
         hash: (0, skill_mirror_files_1.computeSkillFileHash)(adapterFiles),
         files: adapterFiles.map(file => file.path).sort(),
     };
-    writeState(params.root, state);
+    (0, native_skill_mirror_1.writeState)(params.root, state);
     return 'installed';
 }