harnery 0.5.0 → 0.7.0

package/src/lib/http/request.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ */
+
+export interface RetryingResponse {
+  /** `status` in the 2xx range. */
+  ok: boolean;
+  status: number;
+  /** Response body as text; callers handle JSON parsing. */
+  text: string;
+  url: string;
+  headers: Headers;
+}
+
+export interface RequestWithRetriesOptions {
+  /** HTTP method. Default GET. */
+  method?: string;
+  /** Extra headers. Content-Type defaults to application/json when a non-string body is given. */
+  headers?: Record<string, string>;
+  /**
+   * Request body. Strings, Uint8Array, FormData, Blob, and ReadableStream pass
+   * through untouched; any other value is JSON.stringify'd (with a
+   * Content-Type: application/json default).
+   */
+  body?: unknown;
+  /** Per-attempt timeout (AbortController). Default 30s. */
+  timeoutMs?: number;
+  /** Retries after the first attempt. Default 3. */
+  maxRetries?: number;
+  /** Which statuses to retry. Default: 429 and 5xx. */
+  shouldRetry?: (status: number) => boolean;
+  /** Delay before retry `attempt` (0-based). Default `backoffDelayMs`. */
+  delayMs?: (attempt: number, retryAfterSeconds?: number | null) => number;
+  /** Observability hook — fires once per received response (every attempt). */
+  onResponse?: (info: { method: string; url: string; status: number; attempt: number }) => void;
+  /**
+   * Wrap a terminal network failure (fetch threw on the last attempt) in the
+   * caller's error class. Default: a plain Error with the message.
+   */
+  networkError?: (message: string, url: string, retries: number) => Error;
+}
+
+/**
+ * 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: number, retryAfterSeconds?: number | null): number {
+  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: number): Promise<void> {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+export async function requestWithRetries(
+  url: string,
+  opts: RequestWithRetriesOptions = {},
+): Promise<RetryingResponse> {
+  const method = opts.method ?? "GET";
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const maxRetries = opts.maxRetries ?? 3;
+  const shouldRetry = opts.shouldRetry ?? ((status: number) => 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: Record<string, string> = { ...(opts.headers ?? {}) };
+    const init: RequestInit = { 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 as BodyInit;
+      } else {
+        if (!Object.keys(headers).some((k) => k.toLowerCase() === "content-type")) {
+          headers["Content-Type"] = "application/json";
+        }
+        init.body = JSON.stringify(opts.body);
+      }
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(url, init);
+    } catch (err: unknown) {
+      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/src/lib/instructions/apply.ts

@@ -0,0 +1,318 @@
+/**
+ * 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.ts";
+import {
+  checkOwnedSkill,
+  checkRegion,
+  isOwnedFile,
+  type ManagedStatus,
+  removeRegion,
+  spliceRegion,
+} from "./splice.ts";
+import {
+  type BlockSkills,
+  IMPORT_REGION,
+  INSTRUCTIONS_REGION,
+  renderInstructionsBlock,
+  SKILLS,
+} from "./templates.ts";
+
+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(): string {
+  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: (bin: string) => string, binName: string): string {
+  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: string): Set<string> {
+  const p = join(projectRoot, ".harnery", "config.jsonc");
+  try {
+    const cfg = JSON.parse(stripJsonComments(readFileSync(p, "utf8"))) as {
+      skills?: { exclude?: unknown };
+    } | null;
+    const ex = cfg?.skills?.exclude;
+    if (Array.isArray(ex)) return new Set(ex.filter((x): x is string => 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: string, harness: string): BlockSkills {
+  const claudeCode = harness === "claude-code";
+  const exclude = readSkillsExclude(projectRoot);
+  return {
+    decide: claudeCode && !exclude.has("harn-decide"),
+    council: claudeCode && !exclude.has("harn-council"),
+  };
+}
+
+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 function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyResult {
+  const actions: string[] = [];
+  const warnings: string[] = [];
+  const claudeCode = opts.harness === "claude-code";
+  // dry-run narrates the future ("would create"); a real run narrates the past.
+  const verbed = (base: string, past: string) => (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 };
+}
+
+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 function removeInstructions(projectRoot: string, opts: RemoveOpts): ApplyResult {
+  const actions: string[] = [];
+  const warnings: string[] = [];
+  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 };
+}
+
+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 function checkInstructions(
+  projectRoot: string,
+  opts: { binName: string; harness: string },
+): CheckResult {
+  const issues: string[] = [];
+  let errored = false;
+
+  const note = (label: string, status: ManagedStatus) => {
+    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 as Error).message}`);
+  }
+
+  if (errored) return { status: "error", issues };
+  return { status: issues.length === 0 ? "fresh" : "drift", issues };
+}

package/src/lib/instructions/splice.ts

@@ -0,0 +1,148 @@
+/**
+ * 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: string): string {
+  return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Capture regex for a named managed region: begin-marker, body, end-marker. */
+function regionRe(region: string): RegExp {
+  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: string, body: string): string {
+  return `<!-- harnery:begin ${region} v=${shortHash(body)} -->\n${body}\n<!-- harnery:end ${region} -->`;
+}
+
+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 function spliceRegion(content: string, region: string, body: string): SpliceResult {
+  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: string, region: string): { text: string; removed: boolean } {
+  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: string, region: string, body: string): ManagedStatus {
+  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: string): boolean {
+  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: {
+  name: string;
+  description: string;
+  argumentHint?: string;
+  binName: string;
+  body: string;
+}): string {
+  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: string, freshBody: string): ManagedStatus {
+  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";
+}