harnery 0.5.0 → 0.7.0

package/dist/lib/http/request.js

@@ -0,0 +1,105 @@
+/**
+ * Retrying JSON-API request — the toolkit-tier HTTP primitive for host CLIs'
+ * vendor clients.
+ *
+ * Extracted from the first embedding host, where ten vendor clients carried
+ * byte-similar copies of the same loop: abort-controller timeout, retry on
+ * 429/5xx with exponential backoff + jitter, `Retry-After` honored when sane,
+ * vendor-specific error taxonomy applied by the caller. This module owns the
+ * loop; callers keep their auth headers and error classes:
+ *
+ *   const r = await requestWithRetries(url, {
+ *     method, body,
+ *     headers: { Authorization: `ApiKey ${key}`, Accept: "application/json" },
+ *     timeoutMs: this.timeoutMs,
+ *     maxRetries: this.maxRetries,
+ *     onResponse: ({ status }) => log(`${method} ${url} → ${status}`),
+ *     networkError: (msg) => new VendorError("network_error", msg),
+ *   });
+ *   if (!r.ok) throw makeHttpError(r.status, url, r.text, r.headers);
+ *
+ * Design choices, so they survive review:
+ *   - Terminal non-2xx responses RETURN (`ok: false`) rather than throw — the
+ *     vendor error taxonomy belongs to the caller, not this module.
+ *   - Only terminal NETWORK failures throw (after retries), because there is
+ *     no response to hand back; `networkError` lets the caller keep its class.
+ *   - The response body is always read (even on retried statuses) so keep-alive
+ *     sockets are released.
+ */
+/**
+ * Exponential backoff with jitter: 500ms · 2^attempt, capped at 30s, plus up
+ * to 250ms of jitter. A sane `Retry-After` (0 < s < 60) short-circuits the
+ * curve — the server knows better than the guess.
+ */
+export function backoffDelayMs(attempt, retryAfterSeconds) {
+    if (retryAfterSeconds && retryAfterSeconds > 0 && retryAfterSeconds < 60) {
+        return retryAfterSeconds * 1000 + Math.floor(Math.random() * 250);
+    }
+    const base = Math.min(30_000, 500 * 2 ** attempt);
+    return base + Math.floor(Math.random() * 250);
+}
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+export async function requestWithRetries(url, opts = {}) {
+    const method = opts.method ?? "GET";
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const maxRetries = opts.maxRetries ?? 3;
+    const shouldRetry = opts.shouldRetry ?? ((status) => status === 429 || status >= 500);
+    const delayMs = opts.delayMs ?? backoffDelayMs;
+    let attempt = 0;
+    for (;;) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const headers = { ...(opts.headers ?? {}) };
+        const init = { method, headers, signal: controller.signal };
+        if (opts.body !== undefined && opts.body !== null) {
+            const passthrough = typeof opts.body === "string" ||
+                opts.body instanceof Uint8Array ||
+                opts.body instanceof FormData ||
+                opts.body instanceof Blob ||
+                opts.body instanceof ReadableStream;
+            if (passthrough) {
+                init.body = opts.body;
+            }
+            else {
+                if (!Object.keys(headers).some((k) => k.toLowerCase() === "content-type")) {
+                    headers["Content-Type"] = "application/json";
+                }
+                init.body = JSON.stringify(opts.body);
+            }
+        }
+        let res;
+        try {
+            res = await fetch(url, init);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (attempt < maxRetries) {
+                await sleep(delayMs(attempt));
+                attempt++;
+                continue;
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            const message = `request failed after ${maxRetries} retries: ${msg} (URL: ${url})`;
+            throw opts.networkError ? opts.networkError(msg, url, maxRetries) : new Error(message);
+        }
+        clearTimeout(timer);
+        opts.onResponse?.({ method, url, status: res.status, attempt });
+        if (shouldRetry(res.status) && attempt < maxRetries) {
+            const retryAfter = Number(res.headers.get("retry-after"));
+            // Drain the body so the socket is reusable before we sleep.
+            await res.text().catch(() => undefined);
+            await sleep(delayMs(attempt, Number.isFinite(retryAfter) ? retryAfter : null));
+            attempt++;
+            continue;
+        }
+        return {
+            ok: res.ok,
+            status: res.status,
+            text: await res.text(),
+            url,
+            headers: res.headers,
+        };
+    }
+}

package/dist/lib/instructions/apply.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The fs side of ADR 0008: apply / remove / check harnery's machine-owned
+ * agent-facing content in a consumer repo. `init` calls `applyInstructions`,
+ * `deinit` calls `removeInstructions`, and `init --check` calls
+ * `checkInstructions`. The pure splice mechanics live in `splice.ts` and the
+ * rendered content in `templates.ts`; this module only sequences the reads,
+ * writes, and deletes so init/deinit stay thin and this stays integration-
+ * testable against a temp dir.
+ *
+ * Two files, one dir:
+ *   - `AGENTS.md` — the always-on orientation block (a managed region; the
+ *     consumer owns the rest of the file).
+ *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
+ *     so a fresh consumer gets a CLAUDE.md whose managed region imports
+ *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
+ *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.claude/skills/<skill>/SKILL.md` — claude-code only; fully-owned files,
+ *     honoring `skills.exclude` in `.harnery/config.jsonc`.
+ */
+/** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
+export declare function readSkillsExclude(projectRoot: string): Set<string>;
+interface ApplyOpts {
+    binName: string;
+    harness: string;
+    dryRun: boolean;
+}
+export interface ApplyResult {
+    actions: string[];
+    warnings: string[];
+}
+/**
+ * Inject / refresh the instructions block, the CLAUDE.md import shim (claude-code),
+ * and the shipped skills (claude-code). Idempotent: a re-run on current content
+ * writes nothing. `dryRun` reports without touching the fs.
+ */
+export declare function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyResult;
+interface RemoveOpts {
+    harness: string;
+    dryRun: boolean;
+}
+/**
+ * Reverse {@link applyInstructions}: strip the AGENTS.md block, the CLAUDE.md
+ * import shim, and delete the shipped skill files (only ones harnery generated).
+ * A file that becomes empty once our region is gone is deleted (init created it);
+ * a hand-edited skill (no ownership marker) is left with a warning.
+ */
+export declare function removeInstructions(projectRoot: string, opts: RemoveOpts): ApplyResult;
+export interface CheckResult {
+    status: "fresh" | "drift" | "error";
+    issues: string[];
+}
+/**
+ * Read-only drift report for `init --check`: the AGENTS.md block and each
+ * shipped skill (claude-code). Fresh → exit 0; any stale / missing / hand-edit
+ * → drift (exit 2); an unreadable file → error (exit 1). Mirrors the wiki-theme
+ * `--check-only` contract the first host wires into pre-commit.
+ */
+export declare function checkInstructions(projectRoot: string, opts: {
+    binName: string;
+    harness: string;
+}): CheckResult;
+export {};
+//# sourceMappingURL=apply.d.ts.map

package/dist/lib/instructions/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4CH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAiBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA4EnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAmErF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAqCb"}

package/dist/lib/instructions/apply.js

@@ -0,0 +1,255 @@
+/**
+ * The fs side of ADR 0008: apply / remove / check harnery's machine-owned
+ * agent-facing content in a consumer repo. `init` calls `applyInstructions`,
+ * `deinit` calls `removeInstructions`, and `init --check` calls
+ * `checkInstructions`. The pure splice mechanics live in `splice.ts` and the
+ * rendered content in `templates.ts`; this module only sequences the reads,
+ * writes, and deletes so init/deinit stay thin and this stays integration-
+ * testable against a temp dir.
+ *
+ * Two files, one dir:
+ *   - `AGENTS.md` — the always-on orientation block (a managed region; the
+ *     consumer owns the rest of the file).
+ *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
+ *     so a fresh consumer gets a CLAUDE.md whose managed region imports
+ *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
+ *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.claude/skills/<skill>/SKILL.md` — claude-code only; fully-owned files,
+ *     honoring `skills.exclude` in `.harnery/config.jsonc`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { stripJsonComments } from "../../core/config.js";
+import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, spliceRegion, } from "./splice.js";
+import { IMPORT_REGION, INSTRUCTIONS_REGION, renderInstructionsBlock, SKILLS, } from "./templates.js";
+const AGENTS_FILE = "AGENTS.md";
+const CLAUDE_FILE = "CLAUDE.md";
+const CLAUDE_SKILLS_DIR = join(".claude", "skills");
+/** CLAUDE.md import-shim body: points Claude Code (which reads CLAUDE.md, not AGENTS.md) at AGENTS.md. */
+function importBody() {
+    return "This project's agent instructions live in AGENTS.md.\n@AGENTS.md";
+}
+/** The body harnery expects for a skill's file (everything after the ownership marker). */
+function skillBody(render, binName) {
+    const content = render(binName);
+    return content.slice(content.indexOf("-->") + 3).trim();
+}
+/** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
+export function readSkillsExclude(projectRoot) {
+    const p = join(projectRoot, ".harnery", "config.jsonc");
+    try {
+        const cfg = JSON.parse(stripJsonComments(readFileSync(p, "utf8")));
+        const ex = cfg?.skills?.exclude;
+        if (Array.isArray(ex))
+            return new Set(ex.filter((x) => typeof x === "string"));
+    }
+    catch {
+        /* absent / unparseable → no exclusions */
+    }
+    return new Set();
+}
+/**
+ * Which shipped skills exist for this project, so the block references only the
+ * ones actually present: claude-code writes skills (unless excluded); cursor and
+ * codex get the block but no skill files, so both read false there. Kept in one
+ * place so `applyInstructions` and `checkInstructions` render byte-identical blocks.
+ */
+function blockSkills(projectRoot, harness) {
+    const claudeCode = harness === "claude-code";
+    const exclude = readSkillsExclude(projectRoot);
+    return {
+        decide: claudeCode && !exclude.has("harn-decide"),
+        council: claudeCode && !exclude.has("harn-council"),
+    };
+}
+/**
+ * Inject / refresh the instructions block, the CLAUDE.md import shim (claude-code),
+ * and the shipped skills (claude-code). Idempotent: a re-run on current content
+ * writes nothing. `dryRun` reports without touching the fs.
+ */
+export function applyInstructions(projectRoot, opts) {
+    const actions = [];
+    const warnings = [];
+    const claudeCode = opts.harness === "claude-code";
+    // dry-run narrates the future ("would create"); a real run narrates the past.
+    const verbed = (base, past) => (opts.dryRun ? `would ${base}` : past);
+    // ── AGENTS.md orientation block ─────────────────────────────────────────
+    const agentsPath = join(projectRoot, AGENTS_FILE);
+    const agentsExisted = existsSync(agentsPath);
+    const agentsBefore = agentsExisted ? readFileSync(agentsPath, "utf8") : "";
+    const body = renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.harness));
+    const spliced = spliceRegion(agentsBefore, INSTRUCTIONS_REGION, body);
+    if (!spliced.changed) {
+        actions.push(`· ${AGENTS_FILE} instructions block already current`);
+    }
+    else {
+        if (!opts.dryRun)
+            writeFileSync(agentsPath, spliced.text);
+        if (!agentsExisted)
+            actions.push(`+ ${verbed("create", "created")} ${AGENTS_FILE} with the instructions block`);
+        else if (!spliced.had)
+            actions.push(`+ ${verbed("inject", "injected")} the instructions block into ${AGENTS_FILE}`);
+        else
+            actions.push(`~ ${verbed("update", "updated")} the instructions block in ${AGENTS_FILE}`);
+    }
+    // ── CLAUDE.md import shim (claude-code only) ────────────────────────────
+    if (claudeCode) {
+        const claudePath = join(projectRoot, CLAUDE_FILE);
+        if (!existsSync(claudePath)) {
+            const shim = spliceRegion("", IMPORT_REGION, importBody());
+            if (!opts.dryRun)
+                writeFileSync(claudePath, shim.text);
+            actions.push(`+ ${verbed("create", "created")} ${CLAUDE_FILE} importing @AGENTS.md`);
+        }
+        else {
+            const claude = readFileSync(claudePath, "utf8");
+            const sees = claude.includes("@AGENTS.md") ||
+                claude.includes(`harnery:begin ${IMPORT_REGION}`) ||
+                claude.includes(`harnery:begin ${INSTRUCTIONS_REGION}`);
+            if (sees) {
+                actions.push(`· ${CLAUDE_FILE} already reaches AGENTS.md (left untouched)`);
+            }
+            else {
+                warnings.push(`${CLAUDE_FILE} exists but neither imports @AGENTS.md nor carries the block; left ` +
+                    `untouched. For Claude Code to see the orientation, add \`@AGENTS.md\` to ${CLAUDE_FILE} ` +
+                    `(or generate ${CLAUDE_FILE} from ${AGENTS_FILE}).`);
+            }
+        }
+    }
+    // ── shipped skills (claude-code only) ───────────────────────────────────
+    if (claudeCode) {
+        const exclude = readSkillsExclude(projectRoot);
+        for (const skill of SKILLS) {
+            if (exclude.has(skill.id)) {
+                actions.push(`· skipped skill ${skill.id} (skills.exclude)`);
+                continue;
+            }
+            const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+            const content = skill.render(opts.binName);
+            const before = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : null;
+            if (before === content) {
+                actions.push(`· skill ${skill.id} already current`);
+                continue;
+            }
+            if (!opts.dryRun) {
+                mkdirSync(dirname(skillPath), { recursive: true });
+                writeFileSync(skillPath, content);
+            }
+            const fresh = before === null;
+            actions.push(`${fresh ? "+" : "~"} ${verbed(fresh ? "write" : "update", fresh ? "wrote" : "updated")} skill ${skill.id}`);
+        }
+    }
+    return { actions, warnings };
+}
+/**
+ * Reverse {@link applyInstructions}: strip the AGENTS.md block, the CLAUDE.md
+ * import shim, and delete the shipped skill files (only ones harnery generated).
+ * A file that becomes empty once our region is gone is deleted (init created it);
+ * a hand-edited skill (no ownership marker) is left with a warning.
+ */
+export function removeInstructions(projectRoot, opts) {
+    const actions = [];
+    const warnings = [];
+    const claudeCode = opts.harness === "claude-code";
+    // ── AGENTS.md block ─────────────────────────────────────────────────────
+    const agentsPath = join(projectRoot, AGENTS_FILE);
+    if (existsSync(agentsPath)) {
+        const { text, removed } = removeRegion(readFileSync(agentsPath, "utf8"), INSTRUCTIONS_REGION);
+        if (!removed) {
+            actions.push(`· no instructions block in ${AGENTS_FILE}`);
+        }
+        else if (text === "") {
+            if (!opts.dryRun)
+                rmSync(agentsPath);
+            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} ${AGENTS_FILE} (was block-only)`);
+        }
+        else {
+            if (!opts.dryRun)
+                writeFileSync(agentsPath, text);
+            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} the instructions block from ${AGENTS_FILE}`);
+        }
+    }
+    // ── CLAUDE.md import shim (claude-code) ─────────────────────────────────
+    if (claudeCode) {
+        const claudePath = join(projectRoot, CLAUDE_FILE);
+        if (existsSync(claudePath)) {
+            const { text, removed } = removeRegion(readFileSync(claudePath, "utf8"), IMPORT_REGION);
+            if (removed) {
+                if (text === "") {
+                    if (!opts.dryRun)
+                        rmSync(claudePath);
+                    actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} ${CLAUDE_FILE} (was shim-only)`);
+                }
+                else {
+                    if (!opts.dryRun)
+                        writeFileSync(claudePath, text);
+                    actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} the import shim from ${CLAUDE_FILE}`);
+                }
+            }
+        }
+    }
+    // ── shipped skills (claude-code) ────────────────────────────────────────
+    if (claudeCode) {
+        for (const skill of SKILLS) {
+            const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+            if (!existsSync(skillPath))
+                continue;
+            if (!isOwnedFile(readFileSync(skillPath, "utf8"))) {
+                warnings.push(`left ${skill.relPath} (hand-edited; no harnery ownership marker)`);
+                continue;
+            }
+            if (!opts.dryRun) {
+                rmSync(skillPath);
+                // drop the now-empty skill dir (harn-decide/), leaving .claude/skills/ intact
+                const dir = dirname(skillPath);
+                try {
+                    if (readdirSync(dir).length === 0)
+                        rmdirSync(dir);
+                }
+                catch {
+                    /* dir not empty or gone → leave it */
+                }
+            }
+            actions.push(`+ ${opts.dryRun ? "would delete" : "deleted"} skill ${skill.id}`);
+        }
+    }
+    return { actions, warnings };
+}
+/**
+ * Read-only drift report for `init --check`: the AGENTS.md block and each
+ * shipped skill (claude-code). Fresh → exit 0; any stale / missing / hand-edit
+ * → drift (exit 2); an unreadable file → error (exit 1). Mirrors the wiki-theme
+ * `--check-only` contract the first host wires into pre-commit.
+ */
+export function checkInstructions(projectRoot, opts) {
+    const issues = [];
+    let errored = false;
+    const note = (label, status) => {
+        if (status === "missing")
+            issues.push(`${label}: missing`);
+        else if (status === "stale")
+            issues.push(`${label}: stale (re-run init)`);
+    };
+    try {
+        const agentsPath = join(projectRoot, AGENTS_FILE);
+        const content = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+        note(`${AGENTS_FILE} block`, checkRegion(content, INSTRUCTIONS_REGION, renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.harness))));
+        if (opts.harness === "claude-code") {
+            const exclude = readSkillsExclude(projectRoot);
+            for (const skill of SKILLS) {
+                if (exclude.has(skill.id))
+                    continue;
+                const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+                const c = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : "";
+                note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
+            }
+        }
+    }
+    catch (err) {
+        errored = true;
+        issues.push(`error reading instructions state: ${err.message}`);
+    }
+    if (errored)
+        return { status: "error", issues };
+    return { status: issues.length === 0 ? "fresh" : "drift", issues };
+}

package/dist/lib/instructions/splice.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure splicer for harnery's machine-owned content in a consumer's repo.
+ *
+ * Two shapes of machine-owned content, both hash-versioned so drift is a
+ * byte-compare and a re-splice is idempotent (applying twice = identical bytes):
+ *
+ *   1. A **managed region** inside a larger file the consumer also edits
+ *      (`AGENTS.md`, `CLAUDE.md`), delimited by sentinel comments:
+ *        <!-- harnery:begin <region> v=<hash> -->
+ *        …rendered body…
+ *        <!-- harnery:end <region> -->
+ *      Everything outside the sentinels is never touched.
+ *
+ *   2. A **fully-owned file** harnery creates whole (a shipped skill's
+ *      `SKILL.md`), carrying an ownership header comment so `deinit` deletes
+ *      only files harnery generated and `--check` flags a hand-edit:
+ *        <!-- harnery:generated <name> v=<hash> — machine-owned … -->
+ *
+ * Modeled on the first host's HTML-theme splicer (regenerate + byte-compare,
+ * sha256-8 hash, content outside the region untouchable). Pure (no fs) so it's
+ * unit-testable like `wireHooks`/`unwireHooks`.
+ */
+/** 8-hex-char content hash stamped into every managed marker. */
+export declare function shortHash(s: string): string;
+/** Canonical region block: begin-marker, body flanked by newlines, end-marker. */
+export declare function regionBlock(region: string, body: string): string;
+export type ManagedStatus = "fresh" | "stale" | "missing";
+export interface SpliceResult {
+    text: string;
+    changed: boolean;
+    /** the region was already present before this splice */
+    had: boolean;
+    /** present-but-differs (hash or body); only meaningful when `had` is true */
+    stale: boolean;
+}
+/**
+ * Re-splice (or first-time append) a managed region into `content`. Idempotent:
+ * applying twice yields identical bytes. Content outside the markers is never
+ * touched; a re-splice replaces the region wherever the consumer moved it. When
+ * absent, the block is appended after existing content (blank-line separated);
+ * an empty/whitespace-only `content` becomes just the block.
+ */
+export declare function spliceRegion(content: string, region: string, body: string): SpliceResult;
+/**
+ * Remove a managed region, collapsing the blank lines it leaves behind. Returns
+ * `removed: false` (content unchanged) when the region is absent. When the region
+ * was the file's only content, the result is the empty string — the caller
+ * decides whether to delete the file.
+ */
+export declare function removeRegion(content: string, region: string): {
+    text: string;
+    removed: boolean;
+};
+/** Region freshness: missing, stale (hash or body drifted), or fresh. */
+export declare function checkRegion(content: string, region: string, body: string): ManagedStatus;
+/** True when a file carries harnery's ownership header (deinit may delete it). */
+export declare function isOwnedFile(content: string): boolean;
+/**
+ * Wrap a skill file: frontmatter, then a hash-stamped ownership header comment,
+ * then the body. The hash covers the trimmed body so `--check` catches a
+ * hand-edit even if the marker was left alone. `binName` renders the regenerate
+ * / remove hint in the host's own bin.
+ */
+export declare function buildOwnedSkill(opts: {
+    name: string;
+    description: string;
+    argumentHint?: string;
+    binName: string;
+    body: string;
+}): string;
+/** Owned-skill freshness against a freshly-rendered body (trimmed compare). */
+export declare function checkOwnedSkill(content: string, freshBody: string): ManagedStatus;
+//# sourceMappingURL=splice.d.ts.map

package/dist/lib/instructions/splice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAcD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAaxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAShG;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAIxF;AAMD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAcT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAKjF"}

package/dist/lib/instructions/splice.js

@@ -0,0 +1,118 @@
+/**
+ * Pure splicer for harnery's machine-owned content in a consumer's repo.
+ *
+ * Two shapes of machine-owned content, both hash-versioned so drift is a
+ * byte-compare and a re-splice is idempotent (applying twice = identical bytes):
+ *
+ *   1. A **managed region** inside a larger file the consumer also edits
+ *      (`AGENTS.md`, `CLAUDE.md`), delimited by sentinel comments:
+ *        <!-- harnery:begin <region> v=<hash> -->
+ *        …rendered body…
+ *        <!-- harnery:end <region> -->
+ *      Everything outside the sentinels is never touched.
+ *
+ *   2. A **fully-owned file** harnery creates whole (a shipped skill's
+ *      `SKILL.md`), carrying an ownership header comment so `deinit` deletes
+ *      only files harnery generated and `--check` flags a hand-edit:
+ *        <!-- harnery:generated <name> v=<hash> — machine-owned … -->
+ *
+ * Modeled on the first host's HTML-theme splicer (regenerate + byte-compare,
+ * sha256-8 hash, content outside the region untouchable). Pure (no fs) so it's
+ * unit-testable like `wireHooks`/`unwireHooks`.
+ */
+import { createHash } from "node:crypto";
+/** 8-hex-char content hash stamped into every managed marker. */
+export function shortHash(s) {
+    return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Capture regex for a named managed region: begin-marker, body, end-marker. */
+function regionRe(region) {
+    const r = escapeRe(region);
+    return new RegExp(`(<!--\\s*harnery:begin ${r}(?:\\s+v=([0-9a-f]*))?\\s*-->)([\\s\\S]*?)(<!--\\s*harnery:end ${r}\\s*-->)`);
+}
+/** Canonical region block: begin-marker, body flanked by newlines, end-marker. */
+export function regionBlock(region, body) {
+    return `<!-- harnery:begin ${region} v=${shortHash(body)} -->\n${body}\n<!-- harnery:end ${region} -->`;
+}
+/**
+ * Re-splice (or first-time append) a managed region into `content`. Idempotent:
+ * applying twice yields identical bytes. Content outside the markers is never
+ * touched; a re-splice replaces the region wherever the consumer moved it. When
+ * absent, the block is appended after existing content (blank-line separated);
+ * an empty/whitespace-only `content` becomes just the block.
+ */
+export function spliceRegion(content, region, body) {
+    const re = regionRe(region);
+    const m = content.match(re);
+    const fresh = regionBlock(region, body);
+    if (m) {
+        const stale = m[2] !== shortHash(body) || m[3] !== `\n${body}\n`;
+        // Replacer fn avoids `$`-in-body being read as a capture reference.
+        const text = content.replace(re, () => fresh);
+        return { text, changed: text !== content, had: true, stale };
+    }
+    const trimmed = content.replace(/\s+$/, "");
+    const text = trimmed ? `${trimmed}\n\n${fresh}\n` : `${fresh}\n`;
+    return { text, changed: true, had: false, stale: false };
+}
+/**
+ * Remove a managed region, collapsing the blank lines it leaves behind. Returns
+ * `removed: false` (content unchanged) when the region is absent. When the region
+ * was the file's only content, the result is the empty string — the caller
+ * decides whether to delete the file.
+ */
+export function removeRegion(content, region) {
+    const re = regionRe(region);
+    if (!re.test(content))
+        return { text: content, removed: false };
+    const stripped = content
+        .replace(re, "")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return { text: stripped ? `${stripped}\n` : "", removed: true };
+}
+/** Region freshness: missing, stale (hash or body drifted), or fresh. */
+export function checkRegion(content, region, body) {
+    const m = content.match(regionRe(region));
+    if (!m)
+        return "missing";
+    return m[2] === shortHash(body) && m[3] === `\n${body}\n` ? "fresh" : "stale";
+}
+// ── Fully-owned files (shipped skills) ──────────────────────────────────────
+const OWNED_RE = /<!--\s*harnery:generated\s+(\S+)\s+v=([0-9a-f]*)[\s\S]*?-->/;
+/** True when a file carries harnery's ownership header (deinit may delete it). */
+export function isOwnedFile(content) {
+    return OWNED_RE.test(content);
+}
+/**
+ * Wrap a skill file: frontmatter, then a hash-stamped ownership header comment,
+ * then the body. The hash covers the trimmed body so `--check` catches a
+ * hand-edit even if the marker was left alone. `binName` renders the regenerate
+ * / remove hint in the host's own bin.
+ */
+export function buildOwnedSkill(opts) {
+    const fm = [
+        "---",
+        `name: ${opts.name}`,
+        `description: ${opts.description}`,
+        ...(opts.argumentHint ? [`argument-hint: ${JSON.stringify(opts.argumentHint)}`] : []),
+        "---",
+    ].join("\n");
+    const body = opts.body.trim();
+    const marker = `<!-- harnery:generated ${opts.name} v=${shortHash(body)} — machine-owned; ` +
+        `regenerated by \`${opts.binName} init\`, removed by \`${opts.binName} deinit\`. ` +
+        `Edit the harnery template, not this file. -->`;
+    return `${fm}\n${marker}\n\n${body}\n`;
+}
+/** Owned-skill freshness against a freshly-rendered body (trimmed compare). */
+export function checkOwnedSkill(content, freshBody) {
+    const m = OWNED_RE.exec(content);
+    if (!m)
+        return "missing";
+    const body = content.slice(m.index + m[0].length).trim();
+    return m[2] === shortHash(freshBody.trim()) && body === freshBody.trim() ? "fresh" : "stale";
+}

package/dist/lib/instructions/templates.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The agent-facing content harnery ships into a consumer: one orientation block
+ * for `AGENTS.md` and the generic skills. Everything here is engine mechanics
+ * only — no triage rubric, no escalation targets, no host doc-layout policy
+ * (those stay host-authored, per ADR 0007's portability split). Every command
+ * string renders through `binName`; a template that only reads for `harn` is a
+ * bug the portability guard exists to catch.
+ *
+ * Content, not paths: templates are TS string builders (not shipped `.md`
+ * files), so they compile into `dist/` and resolve identically under Bun and
+ * Node — no `files`-field copy or package-path guesswork.
+ */
+/** Managed-region name for the AGENTS.md orientation block. */
+export declare const INSTRUCTIONS_REGION = "instructions";
+/** Managed-region name for the CLAUDE.md `@AGENTS.md` import shim. */
+export declare const IMPORT_REGION = "import";
+/** Which shipped skills exist in the project the block is rendered for. */
+export interface BlockSkills {
+    /** the `harn-decide` skill file is present (claude-code, not excluded) */
+    decide: boolean;
+    /** the `harn-council` skill file is present */
+    council: boolean;
+}
+/**
+ * The always-on orientation spliced into `AGENTS.md`. Target ≤ 80 rendered
+ * lines: it costs every agent context on every turn, so it states that each
+ * surface *exists* and gives one line of *when* — the *how* lives in the skills
+ * and each command's `--help`. Skill names are fixed (`harn-decide`,
+ * `harn-council`) even for a renamed bin; only command strings track `binName`.
+ *
+ * The block only points at a skill that actually exists here: a host that
+ * excludes one via `skills.exclude`, or a harness with no skill primitive
+ * (cursor/codex get the block but no skill files), gets a `--help` pointer
+ * instead of a dangling reference to a skill it doesn't have.
+ */
+export declare function renderInstructionsBlock(binName: string, skills?: BlockSkills): string;
+/** A shipped skill: its harness-relative file path + a bin-name-aware renderer. */
+export interface SkillTemplate {
+    id: string;
+    /** path under the harness skill dir, e.g. `harn-decide/SKILL.md` */
+    relPath: string;
+    render: (binName: string) => string;
+}
+export declare const SKILLS: SkillTemplate[];
+//# sourceMappingURL=templates.d.ts.map