skillrepo 4.9.2 → 4.10.0

package/src/lib/foreign-content.mjs

@@ -0,0 +1,461 @@
+/**
+ * Foreign-content detection for managed vendor skill roots (#2361).
+ *
+ * Governance doctrine (design doc D7 amendment, 2026-08-07): a skill
+ * reaching an agent without going through the library — or, post-H6,
+ * the repo's skillset — is a compliance VIOLATION, not a workflow to
+ * accommodate. Vendors load skills from DISK, so gitignore posture is
+ * repo cosmetics; disk presence is the compliance fact. This module
+ * detects that fact at sync time and surfaces it. It never deletes,
+ * moves, or rewrites anything — compliance is enforced by surfacing,
+ * never by destroying a developer's work (#2108's invariant).
+ *
+ * WHAT COUNTS AS FOREIGN: a directory inside a managed placement root
+ * whose name has no entry in the `.last-sync` per-skill manifest — the
+ * CLI has no record of writing it. Classification is by NAME, matching
+ * #2108's manifest model:
+ *
+ *   - Manifest-listed dir with modified content is NOT foreign — that
+ *     is drift ("edited", `drift.mjs`), a different axis (#2111 cat 1
+ *     territory), and `list` already surfaces it.
+ *   - Loose FILES directly in a root are ignored: vendors load skills
+ *     as directories containing SKILL.md, so a stray file never
+ *     reaches an agent — it is clutter, not a violation.
+ *   - `.tmp` / `.old` orphan dirs are the CLI's own crashed-write
+ *     artifacts (`cleanupOrphans`), not foreign content.
+ *   - Symlinks are skipped, mirroring `placement-walk.mjs`.
+ *
+ * KNOWN LIMIT (documented for the H7 seam): `.last-sync` is
+ * machine-global (D12 gives per-repo state to H5), so a hand-authored
+ * dir whose name collides with a library skill synced in a DIFFERENT
+ * repo classifies as managed-not-foreign here. The content-hash axis
+ * (drift/edited) still flags it. Revisit when per-repo state lands.
+ *
+ * RECEIPTS SEAM (H7 #2364, aligned with #2111's violation categories):
+ * `receiptViolationSummary` is the ONLY shape intended to leave the
+ * machine — counts and category, NEVER foreign dir names. Out-of-band
+ * names are not the team's library content; exfiltrating them by
+ * telemetry is #2111's explicitly rejected posture (its "unmanaged
+ * skills" category is team-level opt-in precisely because of this).
+ * The developer-facing warnings (`formatForeignWarnings`) keep the
+ * names LOCAL — stdout/stderr transparency, mirroring #2111's
+ * developer-transparency rule.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import {
+  placementTargetsFor,
+  resolvePlacementRoot,
+  describePlacementTarget,
+  escapeControlChars,
+} from "./file-write.mjs";
+import { writeFileAtomic } from "./fs-utils.mjs";
+import { globalGovernanceSeenPath } from "./paths.mjs";
+import { SKILLSET_DECLARATION_FILE } from "./constants.mjs";
+
+/**
+ * Receipt category identifier for this violation class. H7's receipt
+ * schema consumes it alongside #2111's categories; the string is the
+ * cross-layer contract, so treat renames as a wire-format change.
+ *
+ * Vocabulary note: the design doc's D7 amendment calls the DETECTION
+ * "foreign content" (this module's internal naming), but the category
+ * string follows #2111's established violation vocabulary — its
+ * category 2 is "Unmanaged skills" — which is also what the
+ * user-facing warning copy says. One wire word, one user word.
+ */
+export const UNMANAGED_CONTENT_CATEGORY = "unmanaged";
+
+/**
+ * @typedef {Object} ForeignRootResult
+ * @property {string} target      - PlacementTarget scanned.
+ * @property {string} root        - Absolute root directory.
+ * @property {string} displayRoot - Human-readable root (e.g. ".claude/skills/").
+ * @property {string[]} foreignDirs - Foreign directory names (sorted).
+ *
+ * @typedef {Object} ForeignScanResult
+ * @property {ForeignRootResult[]} roots - One entry per scanned root
+ *           (unique targets only; roots that don't exist scan empty).
+ * @property {number} foreignCount - Total foreign dirs across roots.
+ */
+
+/**
+ * Scan the placement roots of the current sync's write set for
+ * directories the CLI did not write.
+ *
+ * Read-only and best-effort: an unreadable root or entry is skipped —
+ * detection must never break a sync. Scans exactly the targets the
+ * sync writes to (project or global per the caller's scope): those are
+ * the roots this sync manages. Personal-scope roots are therefore
+ * scanned only under `--global` — broader personal-scope disclosure
+ * belongs to D20's dedicated work (#2495), not here.
+ *
+ * @param {object} options
+ * @param {string[]} [options.vendors] - Vendor keys for the current sync.
+ * @param {boolean} [options.global]
+ * @param {Record<string, unknown> | null | undefined} options.managedSkills
+ *        The `.last-sync` `skills` map (post-sync state) — keys are
+ *        `"<owner>/<name>"`. Only the name half is used: placement
+ *        dirs are keyed by skill name alone.
+ * @returns {ForeignScanResult}
+ */
+export function scanForeignContent({ vendors, global, managedSkills }) {
+  /** @type {ForeignScanResult} */
+  const result = { roots: [], foreignCount: 0 };
+
+  let targets;
+  try {
+    targets = placementTargetsFor({ vendors, global: global === true });
+  } catch {
+    // Invalid vendor/scope combos are surfaced by the sync itself —
+    // detection just declines to scan.
+    return result;
+  }
+
+  const managedNames = new Set();
+  if (managedSkills && typeof managedSkills === "object") {
+    for (const key of Object.keys(managedSkills)) {
+      const slashAt = key.indexOf("/");
+      if (slashAt < 0) continue;
+      const name = key.slice(slashAt + 1);
+      if (name) managedNames.add(name);
+    }
+  }
+
+  for (const target of targets) {
+    let root;
+    try {
+      // Normalized (realpath + win32 case-fold) because `root` doubles
+      // as the seen-state key — see normalizeStateKey. The D12 sibling
+      // state store already uses realpath-keyed state; same reasoning.
+      root = normalizeStateKey(resolvePlacementRoot(target));
+    } catch {
+      continue;
+    }
+    const rootResult = {
+      target,
+      root,
+      displayRoot: describePlacementTarget(target),
+      foreignDirs: [],
+    };
+    result.roots.push(rootResult);
+
+    if (!existsSync(root)) continue;
+    let entries;
+    try {
+      entries = readdirSync(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith(".tmp") || entry.endsWith(".old")) continue;
+      if (managedNames.has(entry)) continue;
+      let stat;
+      try {
+        stat = lstatSync(join(root, entry));
+      } catch {
+        continue;
+      }
+      if (stat.isSymbolicLink() || !stat.isDirectory()) continue;
+      rootResult.foreignDirs.push(entry);
+    }
+    rootResult.foreignDirs.sort();
+    result.foreignCount += rootResult.foreignDirs.length;
+  }
+
+  return result;
+}
+
+/**
+ * One warning line per foreign dir. Copy standard (owner directive,
+ * 2026-08-07): every warning answers WHY you are seeing it and WHAT to
+ * do about it. Sentence case, no exclamation marks, per the copy
+ * rules. The names stay on this machine — see the module docstring's
+ * privacy contract.
+ *
+ * @param {ForeignScanResult} scan
+ * @returns {string[]}
+ */
+export function formatForeignWarnings(scan) {
+  const lines = [];
+  for (const rootResult of scan.roots) {
+    for (const dir of rootResult.foreignDirs) {
+      // Directory names come from readdirSync — filesystem-sourced and
+      // attacker-influenceable (a cloned repo can carry any byte except
+      // NUL and "/"). Escape control characters so a crafted name can
+      // never inject terminal escapes through the warning, matching the
+      // server-path treatment in file-write.mjs (#2402 class).
+      const safeDir = escapeControlChars(dir);
+      const displayPath = `${rootResult.displayRoot}${safeDir}`;
+      // The remediation must be a RUNNABLE command. A tilde-shortened
+      // display root ("~/.claude/skills/") breaks copy-paste — quotes
+      // suppress shell tilde expansion and Windows cmd never expands
+      // "~" — so global-scope findings print the absolute path.
+      const commandPath = rootResult.displayRoot.startsWith("~")
+        ? join(rootResult.root, safeDir)
+        : displayPath;
+      lines.push(
+        `  warning: ${displayPath}/ is not from your library, but agents still ` +
+          `load it from disk. Run 'skillrepo push ${commandPath}' to bring it ` +
+          `into your library, or remove the directory.`,
+      );
+    }
+  }
+  return lines;
+}
+
+// ── Warn-on-new state (#2361 owner directive: no repeat warnings) ──────
+//
+// A warning that repeats unchanged findings on every sync trains users
+// to ignore it (#2111's own anti-nag rule, applied locally). The CLI
+// persists what it has already warned about in a small machine-global
+// state file and warns only about NEW findings. The state lives at
+// `~/.claude/skillrepo/.governance-seen`, keyed by ABSOLUTE root path —
+// two repos with same-named unmanaged dirs warn independently. Dirs
+// that disappear are pruned from the state, so a dir that is removed
+// and later reappears warns again (a state CHANGE in both directions
+// re-arms the warning).
+//
+// Privacy: the file stores unmanaged dir names LOCALLY, exactly like
+// `.last-sync` stores library skill names. Nothing from it is ever
+// serialized upstream; the receipts seam remains counts/category only.
+//
+// All IO is best-effort: an unreadable/corrupt state file reads as
+// empty (warn about everything — the loud-but-safe direction), and a
+// failed write means the next sync warns again rather than crashing.
+
+/**
+ * @typedef {Object} GovernanceSeenState
+ * @property {number} schemaVersion
+ * @property {Record<string, string[]>} roots - abs root path → dir names
+ *           already warned about (sorted).
+ * @property {Record<string, boolean>} declarations - abs repo path →
+ *           true when the gitignored-declaration warning was already
+ *           shown and the declaration is still gitignored.
+ */
+
+/** @returns {GovernanceSeenState} */
+function emptySeenState() {
+  return { schemaVersion: 1, roots: {}, declarations: {} };
+}
+
+/** @returns {GovernanceSeenState} */
+export function readGovernanceSeen() {
+  try {
+    const raw = readFileSync(globalGovernanceSeenPath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    // MAINTAINER: unknown schemaVersion reads as empty (warn-everything,
+    // the loud-but-safe direction) and the next write replaces the file
+    // at the current schema. A future v2 that must PRESERVE v1 data
+    // needs an explicit accept-in-place branch here, the way
+    // sync.mjs's readLastSync accepts its immediately-prior schema.
+    if (!parsed || typeof parsed !== "object" || parsed.schemaVersion !== 1) {
+      return emptySeenState();
+    }
+    return {
+      schemaVersion: 1,
+      roots:
+        parsed.roots && typeof parsed.roots === "object" && !Array.isArray(parsed.roots)
+          ? parsed.roots
+          : {},
+      declarations:
+        parsed.declarations &&
+        typeof parsed.declarations === "object" &&
+        !Array.isArray(parsed.declarations)
+          ? parsed.declarations
+          : {},
+    };
+  } catch {
+    return emptySeenState();
+  }
+}
+
+/**
+ * Best-effort persist. A write failure is swallowed — the cost is one
+ * repeated warning on the next sync, never a sync failure.
+ *
+ * Callers MUST go through `commitGovernanceSeen` for sync-time updates
+ * — it re-reads the file and merges only the caller's own keys, so a
+ * concurrent sync in ANOTHER repo (distinct keys) can't have its state
+ * clobbered by a snapshot taken before it wrote (a full-object
+ * overwrite from a stale snapshot could silently RESTORE a pruned
+ * entry and suppress a documented re-warn — the prod-readiness
+ * architect traced this). writeFileAtomic rules out torn files.
+ *
+ * RESIDUAL (known, tracked): two interactive syncs racing on the SAME
+ * key — same repo twice, or two repos sharing a --global home root —
+ * still last-write-wins on that key, and the later writer's scan may
+ * be the staler one, which CAN revive a pruned entry and suppress a
+ * later re-warn for that key. Requires two concurrent NON-hook syncs
+ * of one root (hook syncs never write here); the numeric `unmanaged`
+ * count is never affected (it is computed from the live scan, before
+ * any seen-state filtering). See the follow-up issue on the epic.
+ *
+ * @param {GovernanceSeenState} state
+ */
+export function writeGovernanceSeen(state) {
+  try {
+    writeFileAtomic(
+      globalGovernanceSeenPath(),
+      JSON.stringify(state, null, 2) + "\n",
+    );
+  } catch {
+    // Best-effort by design.
+  }
+}
+
+/**
+ * Select the findings the user has NOT been warned about yet. Pure —
+ * no IO. Seen-state bookkeeping lives in `commitGovernanceSeen`.
+ *
+ * @param {ForeignScanResult} scan
+ * @param {GovernanceSeenState} seen
+ * @returns {ForeignScanResult} Mirrors the scan shape but carries only
+ *          unseen dirs; `foreignCount` counts only the new ones.
+ */
+export function selectNewFindings(scan, seen) {
+  /** @type {ForeignScanResult} */
+  const newScan = { roots: [], foreignCount: 0 };
+  for (const rootResult of scan?.roots ?? []) {
+    const prior = new Set(
+      Array.isArray(seen.roots[rootResult.root]) ? seen.roots[rootResult.root] : [],
+    );
+    const fresh = rootResult.foreignDirs.filter((d) => !prior.has(d));
+    newScan.roots.push({ ...rootResult, foreignDirs: fresh });
+    newScan.foreignCount += fresh.length;
+  }
+  return newScan;
+}
+
+/**
+ * Normalize a path for use as a seen-state key: resolve symlinks
+ * (realpath) so two spellings of one directory share a key, and
+ * case-fold on Windows where the filesystem is case-insensitive but
+ * `process.cwd()` preserves whatever casing the shell used. Falls back
+ * to the raw path when realpath fails (root doesn't exist yet).
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function normalizeStateKey(p) {
+  let resolved = p;
+  try {
+    resolved = realpathSync(p);
+  } catch {
+    // Root not created yet — the raw absolute path is still stable.
+  }
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+/**
+ * Commit this sync's observations into the seen-state file with a
+ * NARROW merge: re-read the file and rewrite only the keys this sync
+ * actually scanned (its roots) or owns (this repo's declaration flag).
+ * Keys belonging to other repos/scopes pass through from the FRESH
+ * read — never from a snapshot taken before the scan — so a concurrent
+ * sync elsewhere keeps its update even if this process writes last.
+ *
+ * Replace-not-merge per scanned root: dirs that disappeared are
+ * pruned, so a removed-then-reappearing dir is a state change that
+ * warns again. A clean root deletes its key.
+ *
+ * @param {object} options
+ * @param {ForeignScanResult} options.scan - The FULL scan (all dirs
+ *        currently on disk, not just the newly-warned ones).
+ * @param {string} options.repoKey - Normalized repo path (declaration
+ *        flag owner).
+ * @param {boolean} options.declarationIgnored - Whether the declaration
+ *        file currently exists AND is gitignored.
+ */
+export function commitGovernanceSeen({ scan, repoKey, declarationIgnored }) {
+  const fresh = readGovernanceSeen();
+  const roots = { ...fresh.roots };
+  for (const rootResult of scan?.roots ?? []) {
+    if (rootResult.foreignDirs.length > 0) {
+      roots[rootResult.root] = [...rootResult.foreignDirs];
+    } else {
+      delete roots[rootResult.root];
+    }
+  }
+  const declarations = { ...fresh.declarations };
+  if (declarationIgnored) {
+    declarations[repoKey] = true;
+  } else {
+    delete declarations[repoKey];
+  }
+  writeGovernanceSeen({ schemaVersion: 1, roots, declarations });
+}
+
+/**
+ * The upstream-safe projection of a scan (#2111 privacy posture):
+ * category and count only, NEVER names. H7 (#2364) consumes this when
+ * wiring the receipts violation section; nothing else about the scan
+ * result may be serialized off the machine.
+ *
+ * @param {ForeignScanResult} scan
+ * @returns {{ category: string, count: number }}
+ */
+export function receiptViolationSummary(scan) {
+  return {
+    category: UNMANAGED_CONTENT_CATEGORY,
+    count: scan?.foreignCount ?? 0,
+  };
+}
+
+/**
+ * Check whether the repo's skillset declaration file exists but is
+ * gitignored (#2361, D6). The declaration (`skillrepo.json`) is the
+ * committed, human-owned governance contract — a gitignored copy is
+ * out-of-band governance state: it steers this machine while never
+ * reaching the repository.
+ *
+ * Best-effort probe via `git check-ignore`. Silent no-signal when git
+ * is absent, the CLI is not inside a work tree, or the spawn fails —
+ * a missing git can never break or slow a sync (matches the
+ * warn-only, git-optional posture this issue inherited from D7).
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Test seam; defaults to process.cwd().
+ * @returns {{ present: boolean, ignored: boolean }}
+ */
+export function checkDeclarationGitignored({ cwd = process.cwd() } = {}) {
+  if (!existsSync(join(cwd, SKILLSET_DECLARATION_FILE))) {
+    return { present: false, ignored: false };
+  }
+  try {
+    const probe = spawnSync(
+      "git",
+      ["check-ignore", "-q", "--", SKILLSET_DECLARATION_FILE],
+      { cwd, stdio: "ignore", windowsHide: true },
+    );
+    // status 0 = ignored; 1 = not ignored; 128 = not a git work tree.
+    // `probe.error` (e.g. ENOENT, git not installed) → no signal.
+    return { present: true, ignored: !probe.error && probe.status === 0 };
+  } catch {
+    return { present: true, ignored: false };
+  }
+}
+
+/**
+ * The one-line warning for a gitignored declaration. Same copy
+ * standard: why you are seeing it, what to do about it.
+ *
+ * @returns {string}
+ */
+export function formatDeclarationIgnoredWarning() {
+  return (
+    `  warning: ${SKILLSET_DECLARATION_FILE} is gitignored, so this repo's ` +
+    `skillset declaration only affects your machine and never reaches the ` +
+    `repository. Remove it from .gitignore and commit it so it applies to ` +
+    `everyone who works here.`
+  );
+}

package/src/lib/gitignore-section.mjs

@@ -0,0 +1,223 @@
+/**
+ * Core writer for the CLI's marked .gitignore section (#2361).
+ *
+ * ONE section, one header (`GITIGNORE_SECTION_HEADER` from the artifact
+ * registry). Every line the CLI adds to a project's .gitignore lives
+ * inside it; the uninstall remover strips exactly that section. Shared
+ * by the init-time merger (`mergers/gitignore.mjs`) and the sync-time
+ * pre-flight in `file-write.mjs` — a lib-level module with no
+ * `file-write.mjs` dependency, so both can import it without a cycle.
+ *
+ * Managed skill roots are OWNED SPACE (design doc D7 amendment,
+ * 2026-08-07): the CLI keeps simple blanket ignores for them. Content
+ * in those roots that the CLI did not write is a governance violation
+ * surfaced by the sync-time foreign-content scan (`foreign-content.mjs`)
+ * — never something the ignore machinery accommodates.
+ *
+ * Idempotent: entries already present anywhere in the file are skipped;
+ * missing entries are inserted INTO the existing marked section when one
+ * exists (never a duplicate header), else appended as a new section.
+ * Every call also heals the retired pre-4.10.0 sync-time section shape
+ * (see `healLegacySection`).
+ */
+
+import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
+import { gitignorePath } from "./paths.mjs";
+import { diskError } from "./errors.mjs";
+import {
+  GITIGNORE_SECTION_HEADER,
+  LEGACY_GITIGNORE_SECTION_HEADER,
+} from "./artifact-registry.mjs";
+
+/**
+ * The manual-recovery hint attached to every gitignore disk error the
+ * section writer throws. One string so the read and write branches
+ * never drift.
+ */
+const GITIGNORE_HINT =
+  "The CLI needs to gitignore its managed skill directories " +
+  "(.claude/skills/, .agents/skills/) so library skills don't get committed. " +
+  "Update .gitignore manually and re-run, or remove the read-only/symlinked constraint.";
+
+/**
+ * Blanket ignore line for each project-scope managed skill root. Global
+ * targets have no entry — a personal-scope root is not repo content.
+ */
+export const MANAGED_ROOT_ENTRIES = Object.freeze({
+  claudeProject: ".claude/skills/",
+  agentsProject: ".agents/skills/",
+});
+
+/**
+ * Sync-time pre-flight (#2361): ensure the blanket ignore for every
+ * project-scope managed root the current write set touches, inside the
+ * CLI's marked section. Runs on every sync/write (heal): a repo that
+ * never ran `init` still gets its managed roots ignored on first sync,
+ * and the legacy sync-time section is migrated into the marked section.
+ *
+ * Global-only write sets are a no-op — personal-scope roots are not
+ * repo content, so there is nothing to ignore.
+ *
+ * @param {string[]} targets - PlacementTarget values for the current write.
+ * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
+ */
+export function ensureManagedRootIgnores(targets) {
+  const entries = [];
+  if (Array.isArray(targets)) {
+    for (const [target, entry] of Object.entries(MANAGED_ROOT_ENTRIES)) {
+      if (targets.includes(target)) entries.push(entry);
+    }
+  }
+  if (entries.length === 0) {
+    return { path: ".gitignore", action: "skipped", added: [] };
+  }
+  return ensureGitignoreEntries(entries);
+}
+
+/**
+ * Core ensure: required entries end up line-exact in the file, inside
+ * the CLI's marked section, with the legacy sync-time section healed
+ * away. Single writer for every gitignore mutation the CLI performs.
+ *
+ * Returns `"skipped"` if every required entry is already present and no
+ * legacy section needed healing, `"created"` if the file didn't exist,
+ * `"updated"` otherwise.
+ *
+ * @param {string[]} requiredEntries
+ * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
+ */
+export function ensureGitignoreEntries(requiredEntries) {
+  const filePath = gitignorePath();
+  let existing;
+  try {
+    existing = readFileSafe(filePath);
+  } catch (err) {
+    // readFileSafe returns null on ENOENT and re-throws everything
+    // else (EISDIR, EACCES, ...). Surface as a typed diskError with a
+    // "Cannot read" message so callers abort BEFORE any skill write.
+    throw diskError(`Cannot read ${filePath}: ${err.message}`, {
+      cause: err,
+      hint: GITIGNORE_HINT,
+    });
+  }
+
+  if (existing === null) {
+    // Fresh .gitignore — write all required entries as one section.
+    const content =
+      GITIGNORE_SECTION_HEADER + "\n" + requiredEntries.join("\n") + "\n";
+    writeSectionFile(filePath, content);
+    return {
+      path: ".gitignore",
+      action: "created",
+      added: [...requiredEntries],
+    };
+  }
+
+  // Preserve the original line-ending style throughout.
+  const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
+
+  const { lines, healed } = healLegacySection(existing.split(/\r?\n/));
+
+  // Line-exact match check. `.env.local` as a line is distinct from
+  // `.env.local.backup` or a comment `# .env.local` — compare trimmed
+  // lines so we match the entry literally.
+  const trimmed = lines.map((l) => l.trim());
+  const missing = requiredEntries.filter((entry) => !trimmed.includes(entry));
+
+  if (missing.length === 0 && !healed) {
+    return {
+      path: ".gitignore",
+      action: "skipped",
+      added: [],
+    };
+  }
+
+  let outLines = lines;
+  if (missing.length > 0) {
+    const headerIdx = lines.findIndex(
+      (l) => l.trim() === GITIGNORE_SECTION_HEADER,
+    );
+    if (headerIdx !== -1) {
+      // Insert missing entries at the end of the existing marked
+      // section (header + following non-blank lines) — never a second
+      // header. This is what keeps the uninstall remover's "strip the
+      // section" contract complete.
+      let end = headerIdx + 1;
+      while (end < lines.length && lines[end].trim() !== "") {
+        end += 1;
+      }
+      outLines = [...lines.slice(0, end), ...missing, ...lines.slice(end)];
+    } else {
+      // No marked section yet — append one, separated by a blank line.
+      // Drop trailing empty lines from the split so the separator is
+      // exactly one blank line regardless of the file's tail shape.
+      let tail = lines.length;
+      while (tail > 0 && lines[tail - 1] === "") tail -= 1;
+      outLines = [
+        ...lines.slice(0, tail),
+        "",
+        GITIGNORE_SECTION_HEADER,
+        ...missing,
+        "",
+      ];
+    }
+  }
+
+  writeSectionFile(filePath, outLines.join(lineEnding));
+
+  return {
+    path: ".gitignore",
+    action: "updated",
+    added: missing,
+  };
+}
+
+/**
+ * Write the file, converting a raw fs failure (read-only file,
+ * symlinked target, EACCES) into a typed diskError with the shared
+ * recovery hint.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeSectionFile(filePath, content) {
+  try {
+    writeFileSafe(filePath, content);
+  } catch (err) {
+    throw diskError(`Cannot update ${filePath}: ${err.message}`, {
+      cause: err,
+      hint: GITIGNORE_HINT,
+    });
+  }
+}
+
+/**
+ * Remove the legacy sync-time section shape from a line array. The
+ * pre-#2361 sync pre-flight wrote exactly:
+ *
+ *     # SkillRepo (CLI-managed library skills)
+ *     .agents/skills/
+ *
+ * Only that attributable shape is removed: the header line itself and
+ * a directly-following `.agents/skills/` line when present. Any other
+ * line — including user-authored lines that happen to sit under the
+ * legacy header — survives verbatim.
+ *
+ * @param {string[]} lines
+ * @returns {{ lines: string[]; healed: boolean }}
+ */
+function healLegacySection(lines) {
+  const headerIdx = lines.findIndex(
+    (l) => l.trim() === LEGACY_GITIGNORE_SECTION_HEADER,
+  );
+  if (headerIdx === -1) return { lines, healed: false };
+
+  let end = headerIdx + 1;
+  if (end < lines.length && lines[end].trim() === ".agents/skills/") {
+    end += 1;
+  }
+  return {
+    lines: [...lines.slice(0, headerIdx), ...lines.slice(end)],
+    healed: true,
+  };
+}