greprag 5.84.0 → 5.85.1

package/dist/skill-mirror-client.js

@@ -1,15 +1,8 @@
 "use strict";
-/** Skill-mirror client — the Tier-3 mirror's upload half
- *  (docs/load-system.md §Tier 3). Runs inside the Stop hook: a skill-load turn
- *  triggers `maybeMirrorSkill`, which content-hashes the skill's markdown and
- *  uploads ONLY on change. Follower semantics — files canonical, the mirror
- *  shadows "last used state." Best-effort end to end: a mirror failure never
- *  touches the turn.
- *
- *  Local freshness state (`~/.greprag/state/skill-mirror.json`) remembers the
- *  last-mirrored hash per skill so an unchanged skill costs one hash pass and
- *  ZERO network. Markdown only, v1 — SKILL.md + docs/**\/*.md; script-bearing
- *  assets stay file-bound (see the spec's named gaps). */
+/** Skill package reader: the markdown a mirrored skill carries (SKILL.md +
+ *  docs/**\/*.md) and its content hash. Used to verify an export and to send a
+ *  loadout. The mirror itself is written only by git ingestion
+ *  (skill-git-ingest.ts, adr/skill-ownership-git.md). */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -44,44 +37,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skillRevisionAuthor = skillRevisionAuthor;
 exports.collectSkillFiles = collectSkillFiles;
 exports.computeMirrorHash = computeMirrorHash;
-exports.dryRunNativeSkillAdoption = dryRunNativeSkillAdoption;
-exports.syncNativeSkillAdoptions = syncNativeSkillAdoptions;
-exports.readMirrorState = readMirrorState;
-exports.writeMirrorState = writeMirrorState;
-exports.maybeMirrorSkill = maybeMirrorSkill;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const skill_landing_1 = require("./skill-landing");
-const native_skill_adoption_1 = require("./native-skill-adoption");
-const native_skill_mirror_1 = require("./native-skill-mirror");
 const skill_mirror_files_1 = require("./skill-mirror-files");
-const proc_1 = require("./proc");
-/** Who is writing skill canon, for the revision row every write records:
- *  the writer (`via`), the harness session, and the chip branch when the
- *  write runs inside one. adr: adr/skill-revision-history.md */
-function skillRevisionAuthor(via, opts = {}) {
-    const env = process.env;
-    const harness = opts.harness
-        || (env.CLAUDE_CODE_SESSION_ID || env.CLAUDECODE ? 'claude-code'
-            : env.CODEX_THREAD_ID || env.CODEX_CI || env.CODEX_SHELL ? 'codex'
-                : env.OPENCODE_SESSION_ID ? 'opencode' : 'cli');
-    const sessionId = opts.sessionId || env.CLAUDE_CODE_SESSION_ID || env.CODEX_THREAD_ID
-        || env.OPENCODE_SESSION_ID || env.GREPRAG_SESSION_ID || '';
-    let chip = '';
-    try {
-        const branch = (0, proc_1.safeSpawnSync)('git', ['branch', '--show-current'], {
-            cwd: opts.cwd || process.cwd(), encoding: 'utf8', timeout: 3000,
-        });
-        const name = String(branch.stdout || '').trim();
-        if (branch.status === 0 && name.startsWith('chip/'))
-            chip = name;
-    }
-    catch { /* not a git checkout */ }
-    return { via, harness, ...(sessionId ? { sessionId } : {}), ...(chip ? { chip } : {}) };
-}
 /** Mirrors the server's caps (SKILL_MIRROR_* in @greprag/core — the CLI is
  *  core-free, so the numbers are restated; the server re-validates anyway). */
 const MAX_FILES = 20;
@@ -141,239 +101,3 @@ function collectSkillFiles(skillDir) {
 function computeMirrorHash(files) {
     return (0, skill_mirror_files_1.computeSkillFileHash)(files);
 }
-function dryRunNativeSkillAdoption(params) {
-    return (0, native_skill_adoption_1.planNativeSkillAdoption)({ ...params, collectFiles: collectSkillFiles });
-}
-function adoptedSkillId(candidate) {
-    return candidate.scope === 'project'
-        ? `project:${candidate.projectId}:${candidate.skillName}`
-        : `global:${candidate.skillName}`;
-}
-async function responseJson(response) {
-    try {
-        return await response.json();
-    }
-    catch {
-        return {};
-    }
-}
-async function ensureNativeAdoptionOriginalSnapshot(params) {
-    const skillId = adoptedSkillId(params.candidate);
-    const snapshotPath = `/v1/skillmirror/${encodeURIComponent(params.candidate.skillName)}/snapshots/original`;
-    const body = {
-        scope: params.candidate.scope,
-        projectId: params.candidate.projectId,
-        skillId,
-        source: 'disk',
-        sourceRef: path.join(params.candidate.root, params.candidate.skillName),
-        reason: 'captured native skill package before GrepRAG adapter adoption',
-    };
-    const created = await fetch(`${params.apiUrl}${snapshotPath}`, {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${params.apiKey}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-    if (created.ok)
-        return true;
-    if (created.status !== 409)
-        return false;
-    const query = new URLSearchParams({
-        scope: params.candidate.scope,
-        skillId,
-        ...(params.candidate.projectId ? { projectId: params.candidate.projectId } : {}),
-    });
-    const existing = await fetch(`${params.apiUrl}${snapshotPath}?${query.toString()}`, {
-        method: 'GET',
-        headers: { 'Authorization': `Bearer ${params.apiKey}` },
-    });
-    if (!existing.ok)
-        return false;
-    const data = await responseJson(existing);
-    const snapshot = data.snapshot;
-    return snapshot?.contentHash === params.candidate.sourceHash;
-}
-async function syncNativeSkillAdoptions(params) {
-    const plan = dryRunNativeSkillAdoption(params);
-    const result = {
-        plan,
-        adopted: 0,
-        blocked: plan.blocked.length,
-        skipped: plan.skipped.length,
-    };
-    if (params.dryRun)
-        return result;
-    for (const candidate of plan.candidates) {
-        const body = {
-            files: candidate.files,
-            contentHash: candidate.sourceHash,
-            scope: candidate.scope,
-            projectId: candidate.projectId,
-            projectName: candidate.projectName,
-            reason: `adoption of native ${params.platform} skill from ${path.join(candidate.root, candidate.skillName)}`,
-            author: skillRevisionAuthor('adoption', { cwd: params.projectDir }),
-        };
-        const response = await fetch(`${params.apiUrl}/v1/skillmirror/${encodeURIComponent(candidate.skillName)}`, {
-            method: 'POST',
-            headers: { 'Authorization': `Bearer ${params.apiKey}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        if (!response.ok) {
-            result.blocked++;
-            continue;
-        }
-        const snapshotted = await ensureNativeAdoptionOriginalSnapshot({
-            apiUrl: params.apiUrl,
-            apiKey: params.apiKey,
-            candidate,
-        });
-        if (!snapshotted) {
-            result.blocked++;
-            continue;
-        }
-        const installed = (0, native_skill_adoption_1.installAdoptedNativeSkill)({
-            platform: params.platform,
-            root: candidate.root,
-            expectedSourceHash: candidate.sourceHash,
-            collectFiles: collectSkillFiles,
-            skill: {
-                skillName: candidate.skillName,
-                skillId: adoptedSkillId(candidate),
-                scope: candidate.scope,
-                projectId: candidate.projectId,
-                projectName: candidate.projectName,
-                files: candidate.files,
-            },
-        });
-        if (installed === 'installed')
-            result.adopted++;
-        else if (installed === 'blocked')
-            result.blocked++;
-        else
-            result.skipped++;
-    }
-    return result;
-}
-function materializeLocally(skillName, files, cwd) {
-    for (const platform of native_skill_mirror_1.NATIVE_SKILL_ADAPTER_PLATFORMS) {
-        try {
-            (0, native_skill_mirror_1.applyNativeSkillMirror)({
-                platform,
-                skills: [{
-                        skillName,
-                        skillId: `global:${skillName}`,
-                        scope: 'global',
-                        contentHash: computeMirrorHash(files),
-                        files,
-                    }],
-                projectDir: cwd,
-                prune: false,
-            });
-        }
-        catch { /* local adapter failure never breaks turn capture */ }
-    }
-}
-function statePath() {
-    const home = process.env.HOME || process.env.USERPROFILE || '';
-    return path.join(home, '.greprag', 'state', 'skill-mirror.json');
-}
-function readMirrorState() {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(statePath(), 'utf-8'));
-        if (parsed && typeof parsed.skills === 'object' && parsed.skills) {
-            return { skills: parsed.skills };
-        }
-    }
-    catch { /* missing/unreadable → empty */ }
-    return { skills: {} };
-}
-function writeMirrorState(state) {
-    try {
-        const file = statePath();
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
-    }
-    catch { /* best-effort — worst case is one redundant upload next use */ }
-}
-async function fetchRemoteSkillHash(params) {
-    try {
-        const res = await fetch(`${params.apiUrl}/v1/skillmirror/${encodeURIComponent(params.skill)}?scope=global`, {
-            headers: { 'Authorization': `Bearer ${params.apiKey}` },
-        });
-        if (res.status === 404)
-            return null;
-        if (!res.ok)
-            return null;
-        const data = await responseJson(res);
-        return typeof data.contentHash === 'string' ? data.contentHash : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Mirror one skill if its content changed since the last mirror. Never throws. */
-async function maybeMirrorSkill(params) {
-    try {
-        if (!/^[A-Za-z0-9._-]{1,64}$/.test(params.skill))
-            return 'skipped';
-        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-        const dir = (0, skill_landing_1.resolveSkillDir)(params.skill, params.cwd, homeDir);
-        if (!dir)
-            return 'skipped';
-        const files = collectSkillFiles(dir);
-        if (!files)
-            return 'skipped';
-        // The disk copy of an already-mirrored skill is the generated ADAPTER that
-        // `materializeLocally` wrote below — a launcher whose whole body says "run
-        // `greprag load <name>`". Uploading it makes it canon, and `greprag load`
-        // then serves the launcher back to the agent that was told to run it: the
-        // skill's real instructions are gone and nothing errors. That loop closed
-        // here, one turn after every first mirror, and had already eaten the
-        // canonical body of skills including anti-ai, chrome, gmail and root-cause.
-        //
-        // An adapter is never a mirror source. Canon changes through the guarded
-        // edit path (`greprag skill edit` / `skill mirror apply`), never by
-        // shadowing a file greprag itself generated. adr: adr/skill-adapter-never-canon.md
-        const main = files.find(file => file.path === 'SKILL.md');
-        if (main && (0, skill_mirror_files_1.isGeneratedSkillAdapter)(main.content))
-            return 'skipped';
-        const hash = computeMirrorHash(files);
-        const state = readMirrorState();
-        const localLease = state.skills[params.skill]?.hash;
-        if (localLease === hash) {
-            materializeLocally(params.skill, files, params.cwd);
-            return 'fresh';
-        }
-        if (!localLease) {
-            const remoteHash = await fetchRemoteSkillHash(params);
-            if (remoteHash === hash) {
-                state.skills[params.skill] = { hash, mirroredAt: new Date().toISOString() };
-                writeMirrorState(state);
-                materializeLocally(params.skill, files, params.cwd);
-                return 'fresh';
-            }
-            if (remoteHash)
-                return 'skipped';
-        }
-        const res = await fetch(`${params.apiUrl}/v1/skillmirror/${encodeURIComponent(params.skill)}`, {
-            method: 'POST',
-            headers: { 'Authorization': `Bearer ${params.apiKey}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                files,
-                contentHash: hash,
-                scope: 'global',
-                expectedHash: localLease,
-                reason: params.reason || `shadow upload of local edit from ${dir}`,
-                author: skillRevisionAuthor('shadow-upload', { cwd: params.cwd, sessionId: params.sessionId }),
-            }),
-        });
-        if (!res.ok)
-            return 'skipped';
-        state.skills[params.skill] = { hash, mirroredAt: new Date().toISOString() };
-        writeMirrorState(state);
-        materializeLocally(params.skill, files, params.cwd);
-        return 'mirrored';
-    }
-    catch {
-        return 'skipped';
-    }
-}

package/dist/skill-staleness.js

@@ -358,7 +358,7 @@ function formatSkillStaleness(report, options = {}) {
         lines.push('1. Pause trusting this skill; read the changed watched source files/diffs first.');
         lines.push('2. Classify relevance: low relevance or small delta -> use repo source as truth; no chip.');
         lines.push('3. If this task depends on the stale area and the delta is material, spawn a skill-refresh chip.');
-        lines.push('4. The refresh chip must run `greprag load skill-change`, edit canonical GrepRAG skill source, and never edit local generated adapters.');
+        lines.push('4. The refresh chip edits the skill\'s git folder (~/.claude/skills/<name>/ in dotclaude, or <repo>/.claude/skills/<name>/) and commits; the mirror follows.');
     }
     if (report.projects.some(p => p.dirtyPaths.length > 0)) {
         lines.push('Baseline rule: do not stamp a new baseline while watched local edits are dirty.');
@@ -372,11 +372,8 @@ function formatSkillNoSourceBinding(skillName) {
     return [
         '[greprag skill-staleness - no source binding]',
         `/${skillName} has no source bindings.`,
-        'Authority: canonical mirrored payload exists in GrepRAG; local Codex/Claude/OpenCode SKILL.md files are generated adapter-only mirrors.',
-        'Do not edit a local native adapter as skill content.',
-        `Agent-safe edit path: \`greprag skill mirror export ${skillName} --to <dir>\`, patch the exported Markdown files non-interactively, then \`greprag skill mirror apply <dir> --skill ${skillName} --expected-hash <exported-hash> --reason "<why>"\`.`,
-        `Human editor shortcut: \`greprag skill edit ${skillName} --reason "<why>"\`; Codex auto-skips the editor, and agents may pass \`--no-open\` explicitly.`,
-        `After binding a real source repo, stamp it with \`greprag skill source stamp ${skillName} --project <p> --path <rel>\`.`,
+        `Authority: git. Edit ~/.claude/skills/${skillName}/ (dotclaude) or <repo>/.claude/skills/${skillName}/ and commit; GrepRAG mirrors the committed files read only. Codex/OpenCode SKILL.md files are generated launchers, never content.`,
+        `To watch a source repo, stamp a binding into the git SKILL.md with \`greprag skill source stamp ${skillName} --project <p> --path <rel>\`, then commit.`,
     ].join('\n') + '\n';
 }
 function stampSourceBinding(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.84.0",
+  "version": "5.85.1",
   "description": "Private GrepRAG client for existing Claude Code, Codex, OpenCode, and Grok Build tenants.",
   "main": "dist/index.js",
   "bin": {

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> --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.
+- **Edit the git source and commit.** Global skills: `~/.claude/skills/<name>/` (dotclaude repo); project skills: `<repo>/.claude/skills/<name>/`; greprag-bundled skills: `packages/cli/skill/<name>/`. The commit message names the friction this fixes. Never edit a generated Codex/OpenCode launcher or the installed copy of a bundled skill.
 - **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/os.md

@@ -31,7 +31,7 @@ conversation. The registration is part of the work, not an extra:
 
 - **Docs** mirror through `greprag doc mirror sync` and can still auto-register
   pointers when edited in a live session. Search/read them through the CLI.
-- **Skills** auto-mirror on use (`greprag load` serves them cross-machine).
+- **Skills** live in git (`~/.claude/skills/<name>/` or `<repo>/.claude/skills/<name>/`); commit them and the mirror follows (`greprag load` serves them cross-machine).
 - **Decisions** get a dated entry in the owning ADR / decision log, in the
   same commit as the code.
 - **Everything else** (state files, artifacts, conventions) gets its path

package/skill/templates/prompt-audit.md

@@ -1,4 +1,4 @@
-# Prompt Audit — dated-model cruft in canonical instructions
+# Prompt Audit — dated-model cruft in agent instructions
 
 <!-- adr: adr/prompt-audit-canon.md -->
 
@@ -14,56 +14,35 @@ local skill adapters may not override it.
 
 ## The one invariant
 
-**AUDIT FINDINGS LAND IN CANON, NEVER IN A FOLLOWER.** Global and repo
-instructions are served by `greprag load instructions`; `~/.claude/CLAUDE.md`,
-`~/.codex/AGENTS.md`, `<repo>/CLAUDE.md`, `<repo>/AGENTS.md` are one-way
-rendered followers. Editing a follower directly produces drift: the next
-`greprag instructions push` blocks with `local-change`, and the parity guard
-routes the repair back to `instructions pull`. So an accepted audit edit is
-applied to a **proposed revision file** in scratch and promoted with
-`greprag instructions pull <file> --scope <scope> --harness <harness> --push`.
-That single command advances canon (optimistic concurrency, `expectedRevision`)
-and materializes every follower for the scope. Nothing else writes a follower.
+**AUDIT FINDINGS LAND IN THE GIT SOURCE, NEVER IN A RENDERED FILE.**
+`~/.claude/CLAUDE.md` in the dotclaude repo is the global source; a repo's
+`CLAUDE.md` and `AGENTS.md` are ordinary files in that repo.
+`~/.codex/AGENTS.md` and `~/.config/opencode/AGENTS.md` are rendered from
+`~/.claude/CLAUDE.md` plus `~/.claude/instructions/<codex|opencode>.md` by
+`greprag instructions render` (session start runs it), so an edit there is
+overwritten. GrepRAG's copy (`greprag load instructions`) is read only and
+follows the last commit.
 
 ## Procedure
 
-1. **Scope and target model.** `--scope global` audits the tenant-global
-   revision; `--scope repo` audits the current repo's root revision. Target
+1. **Scope and target model.** Global audits `~/.claude/CLAUDE.md`; repo
+   audits the current repo's `CLAUDE.md`/`AGENTS.md`. Target
    model is the one Claude Code sessions run today (Claude Fable 5.1 as of
    2026-09). State both at the top of the report; do not ask.
-2. **Render canon, not disk.**
-   `greprag load instructions --scope global --harness claude-code > <scratch>/canon-global.md`
-   (repo: `--scope repo`). Confirm followers are fresh first with
-   `greprag instructions status --scope <scope>`; if any follower is
-   `local-change`, stop and have the operator `instructions pull` it before
-   auditing, or the audit will grade a stale canon.
-   Overlays: `instructions` canon is `shared` + per-harness raw suffixes. When
-   a suffix is non-empty, audit each harness render separately and land
-   suffix edits with `instructions overlay set|derive`, never by pulling a
-   rendered file as `shared`. When all suffixes are empty (check the document
-   via the API or `overlay` history), the Claude render **is** `shared` and
-   `pull` of the revised Claude render is exact.
-3. **Provenance.** The Claude follower is usually Git-tracked
-   (`~/.claude` dotclaude repo; repo files in the repo). `git log`/`git blame`
+2. **Read the source.** Global: `~/.claude/CLAUDE.md` plus any
+   `~/.claude/instructions/<harness>.md` addition; audit each addition
+   separately. Repo: that repo's `CLAUDE.md` and `AGENTS.md`. Confirm the
+   rendered files are current with `greprag instructions status`.
+3. **Provenance.** Every source file is in git. `git log`/`git blame`
    each emphatic or prohibitive line: which failure, on which model, did it
    prevent, and does it still reproduce on the target model?
 4. **Classify every line** with the rubric below. Produce the report and the
    proposed diff, both, always.
-5. **Land.** Copy the canon render to `<scratch>/proposed-<scope>.md`, apply
-   ONLY high-confidence hunks, then:
-   ```text
-   greprag instructions snapshot create --name pre-prompt-audit-<YYYY-MM-DD> --scope <scope>
-   greprag instructions pull <scratch>/proposed-<scope>.md --scope <scope> --harness claude-code --push
-   greprag instructions status --scope <scope>      # every follower fresh
-   ```
-   Medium findings and flags stay in the report for the operator; they are
-   applied by a later `pull` of an operator-approved revision, the same way.
-   If the follower lives in a Git repo, the push dirties it; the operator
-   commits that repo (the audit never runs git there).
-6. **Write the report** to `tasks/prompt-audit-<scope>-<date>.md` in the
-   repo you are working in (or scratch if the repo has no `tasks/`), in the
-   shape under "Report shape". Persona (`greprag persona show`) is a separate
-   system: note Persona findings in the report; never edit it from here.
+5. **Land.** Apply ONLY high-confidence hunks to the source file, show the
+   diff, and leave the commit to the operator (the audit never runs git in
+   their repos). After the commit, `greprag instructions render` rewrites the
+   AGENTS.md files and refreshes GrepRAG's copy. Medium findings and flags
+   stay in the report for the operator.
 
 ## Rubric (shipped copy — Anthropic prompt-audit, condensed, binding)
 
@@ -166,12 +145,12 @@ returns 400; prefill is replaced by structured outputs.
 ## Report shape
 
 Top: Assumptions (scope, target model), Inventory (what was audited and its
-canon revision), Summary (counts per group; two or three highest-impact
+source commit), Summary (counts per group; two or three highest-impact
 findings in prose). Then one entry per finding, ordered by confidence:
 
 | Field | Content |
 |---|---|
-| Location | `file:line` in the canon render |
+| Location | `file:line` in the source file |
 | Evidence | exact quoted text |
 | Pattern | the group/row above |
 | Why obsolete | one or two sentences tied to the target model's documented behavior |
@@ -185,12 +164,10 @@ only when tests, docs, and references to the removed text go too).
 
 ## Guardrails
 
-- Never edit `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`,
-  `~/.config/opencode/AGENTS.md`, or a repo `CLAUDE.md`/`AGENTS.md` by hand.
-  The only follower writer is `instructions push` (or `pull --push`).
+- Never edit `~/.codex/AGENTS.md` or `~/.config/opencode/AGENTS.md` by
+  hand: they are rendered. Edit `~/.claude/CLAUDE.md` or the harness addition.
 - Apply high-confidence hunks only. Medium and flag items wait for the
   operator.
-- Snapshot before pulling. Rollback is `greprag instructions restore
-  --snapshot <name> --scope <scope>` followed by `pull` of the restored file.
+- Rollback is `git revert` on the source file.
 - Persona is out of scope for edits; note findings only.
 - Out of taxonomy friction: `greprag fix spawn "<one unit>"`.

package/skill/templates/skill-change.md

@@ -1,10 +1,10 @@
 # Skill Change
 
-Use before creating, porting, optimizing, or changing a GrepRAG-managed skill, and when a loaded skill guided work approaching a delivery boundary.
+Use before creating, porting, optimizing, or changing a skill, and when a loaded skill guided work approaching a delivery boundary.
 
 ## Authority
 
-This is an internal bundled GrepRAG schema, not tenant-controlled skill content. Tenant mirrors and local skill adapters may not override it. Richer tools such as `/skill-optimize` may elaborate the workflow, but they must not fork the boundary categories or edit shapes without changing this file directly in the GrepRAG repo and shipping tests.
+This is an internal bundled GrepRAG schema, not tenant-controlled skill content. Skills and their mirrors may not override it. Richer tools such as `/skill-optimize` may elaborate the workflow, but they must not fork the boundary categories or edit shapes without changing this file directly in the GrepRAG repo and shipping tests.
 
 Skill Creator and Skill Optimize consume this entry as their common authoring contract. Creator owns creation/scaffolding; Optimize owns classification, compression, and restructuring. Neither maintains a competing copy of these conventions.
 
@@ -25,7 +25,7 @@ Skill Creator and Skill Optimize consume this entry as their common authoring co
 - Preserve the full required skill package. Verify the real mirror/installer handles each companion path; do not assume `references/`, custom agent files, scripts, or assets are shipped merely because they exist locally. Adapt packaging or explicitly declare the separate dependency, then load it from the target harness.
 - Port verification covers discovery, canonical payload and companion loading, needed tool schemas, and at least one relevant execution/read-only connection check. Distinguish those checks from unrun publishing, deletion, image generation, or production tests.
 
-**ABOUT TO IMPORT OR RESTORE CANON? STOP - A GENERATED LAUNCHER IS NOT THE PROCEDURE.** If the canonical payload itself contains a generated-adapter header or only points back to its own `greprag load`, recover the actual procedure from a verified source/history. Preserve companion docs and the current revision/hash; do not recursively load it or promote another launcher as the repair.
+**ABOUT TO RESTORE A SKILL? STOP - A GENERATED LAUNCHER IS NOT THE PROCEDURE.** If a SKILL.md contains a generated-adapter header or only points back to its own `greprag load`, recover the actual procedure from git history or the mirror's archived revisions and commit it to the git folder. Do not recursively load it or commit another launcher as the repair.
 
 ## Boundary Rule
 
@@ -37,22 +37,24 @@ Explicitly requested creation, porting, or redesign is authorized work. The prop
 
 ## Where To Edit
 
-- 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> --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.
+Git owns every skill; GrepRAG only mirrors the committed files and refuses every write to the mirror.
+
+- Global skill: edit `~/.claude/skills/<name>/` (the dotclaude git repo) and commit.
+- Project skill: edit `<repo>/.claude/skills/<name>/` and commit in that repo.
+- Bundled GrepRAG skill: edit `packages/cli/skill/<name>/` in the greprag repo, never the installed artifact.
+- Codex/OpenCode `SKILL.md` files are generated launchers: never edit them. Edit the git folder they name.
+- Unknown source: stop and identify the git folder before editing.
+- **ABOUT TO CALL A SKILL CHANGE DONE? STOP - COMMIT IT.** Uncommitted edits are never mirrored; the commit message carries the learning the edit captures, not "update skill". The next session start (or `greprag skill mirror sync`) copies the commit into the mirror for every harness.
+- History and rollback: `git log`, `git diff` and `git revert` on the skill folder. `greprag skill history <skill>` and `greprag skill diff <skill> <revA> [<revB>]` still read the mirror's archived revisions.
 
 ## Skill-Refresh Chips
 
 A `skill-refresh` chip must:
 
-- load the canonical skill with `greprag load <skill>`
+- load the skill with `greprag load <skill>`
 - read the changed watched source files/diffs before trusting stale skill claims
-- decide whether the right result is a canonical skill edit or only a new source stamp
-- update the canonical skill through the GrepRAG skill system, never a local generated adapter
-- regenerate or mirror adapters only through GrepRAG commands when needed
+- decide whether the right result is a skill edit or only a new source stamp (`greprag skill source stamp`, which writes the git SKILL.md)
+- edit the skill's git folder and commit, never a generated launcher
 - report checks and whether release/deploy is needed
 
 ## Edit Shapes