@davidvornholt/standards 0.17.3 → 0.19.0

package/README.md

@@ -25,7 +25,7 @@ standards poller --config <path>
 standards poller --print-units --config <path>
 ```
 
-`dependabot --write` regenerates the composed `.github/dependabot.yml` from the canonical `.github/dependabot.base.yml` and the optional repo-owned `.github/dependabot.local.yml`; `init` and `sync` do the same automatically. `dependabot --check` verifies the generated file still matches its sources, and `doctor`/`check` include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and `ignore` or `registries` entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy.
+`dependabot --write` regenerates the composed `.github/dependabot.yml` from the canonical `.github/dependabot.base.yml` and the optional repo-owned `.github/dependabot.local.yml`; `init` and `sync` do the same automatically. `dependabot --check` verifies the generated file still matches its sources, and `doctor`/`check` include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and `ignore` or `registries` entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy. Update blocks for the same ecosystem and target branch must not select intersecting directories after Dependabot's path normalization. A plural `directories` target is expanded as a glob when it contains `*`, `?`, or both `[` and `]`: `*` and bare `**` stay within one path segment, `**/` matches zero or more directory segments, `?` matches one non-separator character, and bracket expressions match character sets or ranges. Singular `directory` values are always literal.
 
 `dev-env` decrypts the SOPS-encrypted `secrets/dev.yaml` — keyed by workspace group and a one-segment kebab-case workspace name (`apps.<name>`, `packages.<name>`), each mapping portable environment variable names to string values — and transactionally writes every declared workspace's `.env.local` with owner-only permissions and a do-not-edit header. Its Bun-specific dotenv codec exactly round-trips every value it accepts without adding helper environment variables; a value the codec cannot encode exactly is gathered as a validation problem instead of being changed silently. Validation gathers all document, containment, destination-type, workspace, and gitignore problems before writing anything. Generation then stages every output in its destination directory and rolls the whole set back if staging or commit fails, preserving prior contents, modes, and absent files; symlink destinations, duplicate resolved destinations, changed parent-directory identities, and symlinked workspace paths are rejected without following the link. Cleanup trouble after a completed commit is reported loudly as a warning rather than falsely reporting generation failure. Parent identities are checked immediately before each path operation; an unavoidable swap in the syscall-sized interval after a check remains outside the non-hostile maintainer threat model. The canonical `justfile` exposes the command as `just dev-env-generate`, and `just dev-refresh` chains a `just secrets edit dev` session into regeneration.
 
@@ -48,6 +48,6 @@ standards poller --print-units --config <path>
 - **`.github/settings.local.json` `"rulesetEnforcement": "unavailable-on-plan"`** (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). `github --check` and `--apply` then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Plan-gated repository settings that only function alongside branch protection (`allow_auto_merge`) are skipped for the same reason — GitHub accepts a PATCH for them with HTTP 200 and silently keeps the old value. The remaining repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is `"unavailable-on-plan"` (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run `bun standards github --apply` to restore enforcement.
 - **Poller config file** (required for `poller`, passed via `--config`) — host-level JSON, deliberately not repository state. Required: `"repos"` (1–12 unique `owner/repo` strings), `"model"` and `"reasoningEffort"` (passed to `codex exec`; the model choice is deliberate and has no default). The 12-repository maximum and five-minute acknowledgement cooldown keep supported mixed fix/review queues and persisted review-plan recovery below the 5,000-request/hour GitHub API budget with at least 1,400 requests/hour reserved for pagination, active jobs, writes, and other token users; the compound regression bound covers four acknowledged fixes plus four acknowledged reviews with persisted plans in every repository at no more than 3,312 requests/hour. Existing configs above the repository limit must be reduced or split across pollers with independent GitHub API budgets before upgrading. Optional: `"maxJobsPerTick"` (default 1 — the maximum number of new Codex runs the sequential worker may start in one tick), `"staleClaimHours"` (default 6; must exceed `runTimeoutMinutes` so a sweep can never release the claim of a job that is still running), `"runTimeoutMinutes"` (default 240 — the timeout catches wedged agents, not honest multi-hour review runs), `"cacheDir"` (default `~/.cache/standards-poller`; holds bare mirrors and job worktrees; relative paths resolve against the config file), `"extraCodexArgs"` (extra `codex exec` arguments, e.g. enabling the collaboration feature for subagent fan-out). Unknown keys are rejected. The poller needs `git`, `gh`, `codex` (authenticated — its rotating auth state must live in a writable location), and a GitHub token per the bullet below; the token needs issues, pull-requests, and contents write on the watched repos, and nothing else.
 - **Broker store** (created by `creds login`) — machine-global root credentials at `$XDG_CONFIG_HOME/standards/broker.yaml` (default `~/.config/standards/broker.yaml`; override with `STANDARDS_BROKER_FILE`), holding the GitHub App identity (id, slug, client id, private key) and one bootstrap token per Cloudflare account. The file is plaintext with `0600` permissions — deliberately the same local-account trust boundary as the plaintext personal age identity at `~/.config/sops/age/keys.txt`, which unlocks the same secrets; SOPS-encrypting the store to that adjacent identity would not improve custody. Writes use an owner-only temporary file and atomic replacement, and simultaneous provider logins merge rather than overwrite each other; `creds status` warns when the final mode is broader. The store lives outside every repository, is never synced or backed up, and losing it is cheap: re-run the two login commands and revoke the old App key and bootstrap token. On an additional machine, do not create a second App: generate an additional private key from the existing App's settings page (GitHub Apps support several active keys; key generation has no API) and add it to that machine's store, so retiring a machine revokes one key, not the setup.
-- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional generally; poller automation requires this or a logged-in `gh`) — GitHub API token for the `github` command and the GitHub portion of `check`; poller runs pass environment tokens through to Codex, while a local poller can share the service identity's authenticated `gh` state. When neither is available, other commands can still read public repositories anonymously, but poller writes and `github --apply` fail. GitHub's REST API reveals repo merge settings only to write-capable viewers — `check` retries REST-hidden keys over GraphQL, which serves them to read-only tokens — ruleset `bypass_actors` requires repository Administration read, and private-repository labels require Issues read (or Pull requests read); a token that still cannot see declared state fails the check rather than passing unverified. In CI, the canonical workflow decrypts `ci.github_settings_read_token` from the SOPS-encrypted `secrets/ci.yaml`: a repository-scoped fine-grained PAT with read-only "Administration" and "Issues" access.
+- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional generally; poller automation requires this or a logged-in `gh`) — GitHub API token for the `github` command and the GitHub portion of `check`; poller runs pass environment tokens through to Codex, while a local poller can share the service identity's authenticated `gh` state. When neither is available, other commands can still read public repositories anonymously, but poller writes and `github --apply` fail. GitHub's REST API reveals repo merge settings only to write-capable viewers, and `check` retries REST-hidden keys over GraphQL, which serves them to read-only tokens. REST serves ruleset `bypass_actors` only to a user-scoped token holding repository Administration read (a fine-grained PAT with that permission, such as CI's settings token, or the local `gh` CLI), and never to a GitHub App installation token at any permission level, so `check` retries the hidden lists over GraphQL, which withholds the actor identities but answers an exact bypass-actor count (established for a GitHub App installation token and for a non-admin classic-scope viewer, not for every identity class): a declared-empty list verifies exactly, a count that disagrees with the declared length is drift, and a matching non-zero count leaves *which* actors bypass unconfirmed, so the gate fails closed on that ruleset. An installation-token run therefore leaves a declared non-empty list failing until the check is re-run locally with admin `gh` auth; broadening the settings PAT beyond read-only Administration is not the fix. Private-repository labels require Issues read (or Pull requests read); a token that still cannot see declared state fails the check rather than passing unverified. In CI, the canonical workflow decrypts `ci.github_settings_read_token` from the SOPS-encrypted `secrets/ci.yaml`: a repository-scoped fine-grained PAT with read-only "Administration" and "Issues" access.
 
 See the standards repository README for the ownership model and adoption workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.17.3",
+  "version": "0.19.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,9 @@
     "src/creds-store-lock.ts",
     "src/dependabot-compose-input.ts",
     "src/dependabot-compose.ts",
+    "src/dependabot-directory-character-class.ts",
+    "src/dependabot-directory-normalize.ts",
+    "src/dependabot-directory-overlap.ts",
     "src/dependabot-inspect.ts",
     "src/dependabot-update.ts",
     "src/dev-env-document.ts",
@@ -66,17 +69,23 @@
     "src/dev-env.ts",
     "src/github-api.ts",
     "src/github-apply.ts",
+    "src/github-bypass-actors.ts",
     "src/github-command-shared.ts",
     "src/github-commands.ts",
     "src/github-diff.ts",
+    "src/github-graphql.ts",
     "src/github-labels.ts",
     "src/github-label-identity.ts",
     "src/github-live-drift.ts",
     "src/github-paginate.ts",
+    "src/github-ruleset-api.ts",
+    "src/github-ruleset-diff.ts",
+    "src/github-ruleset-visibility.ts",
     "src/github-settings-merge.ts",
     "src/github-settings-parse.ts",
     "src/github-settings.ts",
     "src/managed-files.ts",
+    "src/managed-path-ownership.ts",
     "src/poller-approval.ts",
     "src/poller-acknowledgements.ts",
     "src/poller-claim.ts",

package/src/cli.ts

@@ -13,7 +13,7 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
-import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
 import process from 'node:process';
@@ -32,8 +32,16 @@ import { loadGithubSettings } from './github-settings';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
 import {
   findManagedFilesContainingBiomeDirectiveToken,
+  inspectManagedPath,
   listManagedFiles,
+  type ManagedEntry,
+  managedEntryDigestInput,
+  writeManagedEntry,
 } from './managed-files';
+import {
+  interposedAncestor,
+  unlockedPathsUnder,
+} from './managed-path-ownership';
 import { runPollerCommand } from './poller-commands';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
@@ -44,6 +52,10 @@ const DEFAULT_UPSTREAM = 'github:davidvornholt/standards';
 // Characters of a sha256 hex digest shown in drift reports; enough to identify.
 const HASH_PREVIEW_LENGTH = 12;
 
+// Unmanaged paths named as examples in a collision refusal, which also reports
+// the full count.
+const COLLISION_SAMPLE = 3;
+
 const GITHUB_PREFIX = 'github:';
 const SKIP_GITHUB_CHECK_ENV = 'STANDARDS_SKIP_GITHUB_CHECK';
 
@@ -112,6 +124,38 @@ const assertSafeRelativePath = (path: string, label: string): void => {
   }
 };
 
+// `C:/Windows` is absolute on Windows and relative to POSIX `isAbsolute`, so a
+// drive-qualified target written with forward slashes would escape a consumer
+// synced on Linux. Managed targets are POSIX-relative on every platform.
+const DRIVE_QUALIFIED = /^[A-Za-z]:/u;
+
+// A managed symlink is mirrored verbatim into every consumer, so its target
+// must resolve inside the consumer repository rather than at the host
+// filesystem around it. Returns the problem instead of throwing, so a command
+// can report every offending link before it writes anything.
+const symlinkTargetProblem = (rel: string, target: string): string | null => {
+  const resolved = posix.normalize(posix.join(posix.dirname(rel), target));
+  if (
+    target.length === 0 ||
+    posix.isAbsolute(target) ||
+    DRIVE_QUALIFIED.test(target) ||
+    target.includes('\\') ||
+    resolved.split('/').includes('..')
+  ) {
+    return `canonical symlink ${rel} must point inside the repository: ${target}`;
+  }
+  return null;
+};
+
+const symlinkTargetProblems = (
+  entries: ReadonlyMap<string, ManagedEntry>,
+): ReadonlyArray<string> =>
+  [...entries]
+    .map(([rel, entry]) =>
+      entry.kind === 'symlink' ? symlinkTargetProblem(rel, entry.target) : null,
+    )
+    .filter((problem): problem is string => problem !== null);
+
 const parseManifest = (raw: unknown): Manifest => {
   if (typeof raw !== 'object' || raw === null) {
     throw new Error('sync-standards.json must be a JSON object');
@@ -249,22 +293,147 @@ type MirrorResult = {
   readonly updated: ReadonlyArray<string>;
   readonly deleted: ReadonlyArray<string>;
   readonly tampered: ReadonlyArray<string>;
+  // Locked paths the prune pass deliberately left on disk, each with the reason
+  // the operator needs in order to finish the job by hand.
+  readonly retained: ReadonlyArray<string>;
+  // Locked paths that sit below a managed symlink once this run has finished.
+  // Nothing is left on disk for the operator to act on: the lock entry is
+  // dropped, and the name now resolves through the link into content this run
+  // must not delete. Reported so the drop is not silent, never as an instruction.
+  readonly stale: ReadonlyArray<string>;
 };
 
 type MirrorOptions = {
-  readonly manifest: Manifest;
-  readonly srcDir: string;
+  readonly upstream: ReadonlyMap<string, ManagedEntry>;
   readonly consumer: string;
   readonly previous: Record<string, string>;
   readonly dryRun: boolean;
 };
 
+// Two things init/sync must settle before their first write: an escaping
+// canonical link target, and a managed destination that is a directory holding
+// paths the lock does not record. The lock is the only record of what this
+// engine put in a consumer, so whether the destination itself is locked decides
+// nothing — a consumer can replace a locked link with a directory of its own
+// skills, and that directory is still consumer work. Both problems are decided
+// from data already in hand, and both are reported together so one run surfaces
+// every offending managed path.
+const mirrorPreconditionProblems = async (
+  consumer: string,
+  upstream: ReadonlyMap<string, ManagedEntry>,
+  previous: Record<string, string>,
+): Promise<ReadonlyArray<string>> => {
+  const locked = new Set(Object.keys(previous));
+  const collisions = await Promise.all(
+    [...upstream.keys()].map(async (rel) => {
+      const current = await inspectManagedPath(join(consumer, rel));
+      if (current?.kind !== 'directory') {
+        return null;
+      }
+      const unlocked = await unlockedPathsUnder(consumer, rel, locked);
+      return unlocked.length === 0
+        ? null
+        : `${rel} is a directory holding ${unlocked.length} path(s) this repository does not manage (${unlocked.slice(0, COLLISION_SAMPLE).join(', ')}); move or delete them, then re-run`;
+    }),
+  );
+  return [
+    ...symlinkTargetProblems(upstream),
+    ...collisions.filter((problem): problem is string => problem !== null),
+  ];
+};
+
+const assertNoProblems = (
+  problems: ReadonlyArray<string>,
+  headline: string,
+): void => {
+  if (problems.length > 0) {
+    throw new Error(
+      [`${headline}:`, ...problems.map((problem) => `  - ${problem}`)].join(
+        '\n',
+      ),
+    );
+  }
+};
+
+type PruneOutcome =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'delete'; readonly rel: string }
+  | { readonly kind: 'retain'; readonly note: string }
+  | { readonly kind: 'stale'; readonly note: string };
+
+// Two things the prune pass must never do: resolve through a symlink it (or an
+// older CLI's lock) put in the parent chain, and recursively delete a
+// destination the consumer turned into a directory. Every answer is decided
+// against the shape the mirror leaves behind, not the shape on disk right now,
+// so `--dry-run` predicts what the matching real run does.
+const pruneOutcome = async (
+  consumer: string,
+  rel: string,
+  planned: ReadonlyMap<string, ManagedEntry>,
+): Promise<PruneOutcome> => {
+  const ancestor = await interposedAncestor(consumer, rel, planned);
+  if (ancestor?.kind === 'symlink') {
+    return {
+      kind: 'stale',
+      note: `${rel} (below the symlink ${ancestor.rel}; nothing was deleted through it)`,
+    };
+  }
+  // Below a managed file the name resolves to nothing once the mirror has run,
+  // whether or not a directory still stands there while a dry run looks.
+  const current =
+    ancestor === null ? await inspectManagedPath(join(consumer, rel)) : null;
+  if (current === null) {
+    return { kind: 'absent' };
+  }
+  if (current.kind === 'directory') {
+    return {
+      kind: 'retain',
+      note: `${rel}: removed upstream but now a directory this repository does not manage; delete it yourself if you no longer want it`,
+    };
+  }
+  return { kind: 'delete', rel };
+};
+
+// Remove the locked paths that vanished upstream. Retained paths are reported
+// and left alone; the lock drops every removable key either way, so the next
+// run is clean.
+const prune = async (
+  consumer: string,
+  removable: ReadonlyArray<string>,
+  planned: ReadonlyMap<string, ManagedEntry>,
+  dryRun: boolean,
+): Promise<{
+  readonly deleted: ReadonlyArray<string>;
+  readonly retained: ReadonlyArray<string>;
+  readonly stale: ReadonlyArray<string>;
+}> => {
+  const outcomes = await Promise.all(
+    removable.map((rel) => pruneOutcome(consumer, rel, planned)),
+  );
+  const deleted = outcomes.flatMap((outcome) =>
+    outcome.kind === 'delete' ? [outcome.rel] : [],
+  );
+  const retained = outcomes.flatMap((outcome) =>
+    outcome.kind === 'retain' ? [outcome.note] : [],
+  );
+  const stale = outcomes.flatMap((outcome) =>
+    outcome.kind === 'stale' ? [outcome.note] : [],
+  );
+  if (!dryRun) {
+    // `pruneOutcome` decides what may be deleted; a directory takes the retain
+    // branch there and never reaches this call.
+    await Promise.all(
+      deleted.map((rel) => rm(join(consumer, rel), { force: true })),
+    );
+  }
+  return { deleted, retained, stale };
+};
+
 // Mirror managed files into the consumer, deleting any previously-locked file
 // that no longer exists upstream (three-way reconcile against the lock). When
 // `dryRun` is set nothing is written or deleted; the returned plan is reported.
 const mirror = async ({
-  manifest,
-  srcDir,
+  upstream,
   consumer,
   previous,
   dryRun,
@@ -272,19 +441,23 @@ const mirror = async ({
   for (const rel of Object.keys(previous)) {
     assertSafeRelativePath(rel, 'sync-standards.lock file');
   }
-  const upstream = await listManagedFiles(srcDir, manifest.paths);
+  assertNoProblems(
+    await mirrorPreconditionProblems(consumer, upstream, previous),
+    'cannot mirror canonical files',
+  );
   const next: Record<string, string> = {};
   const created: Array<string> = [];
   const updated: Array<string> = [];
   const tampered: Array<string> = [];
   await Promise.all(
-    [...upstream].map(async ([rel, abs]) => {
+    [...upstream].map(async ([rel, entry]) => {
       const dest = join(consumer, rel);
-      const buf = await readFile(abs);
-      const hash = sha256(buf);
-      const currentHash = existsSync(dest)
-        ? sha256(await readFile(dest))
-        : null;
+      const hash = sha256(await managedEntryDigestInput(entry));
+      const current = await inspectManagedPath(dest);
+      const currentHash =
+        current === null
+          ? null
+          : sha256(await managedEntryDigestInput(current));
       const prev = previous[rel];
       if (prev !== undefined && currentHash !== null && currentHash !== prev) {
         tampered.push(rel);
@@ -296,61 +469,95 @@ const mirror = async ({
       }
       if (!dryRun) {
         await mkdir(dirname(dest), { recursive: true });
-        await writeFile(dest, buf);
+        // The precondition above proved every path inside this directory is one
+        // the lock already records, so replacing it restores the managed shape
+        // rather than destroying consumer work.
+        if (current?.kind === 'directory') {
+          await rm(dest, { recursive: true, force: true });
+        }
+        await writeManagedEntry(dest, entry);
       }
       next[rel] = hash;
     }),
   );
-  const deleted = Object.keys(previous).filter(
-    (rel) => !(rel in next) && existsSync(join(consumer, rel)),
+  // `existsSync` would miss a broken link, so the prune pass lstats instead.
+  const { deleted, retained, stale } = await prune(
+    consumer,
+    Object.keys(previous).filter((rel) => !(rel in next)),
+    upstream,
+    dryRun,
   );
-  if (!dryRun) {
-    await Promise.all(deleted.map((rel) => rm(join(consumer, rel))));
-  }
-  return { files: next, created, updated, deleted, tampered };
+  return { files: next, created, updated, deleted, tampered, retained, stale };
+};
+
+// What a mirror reports, in the tense the run calls for: a dry run also
+// announces the writes ahead of it, while a real sync stays quiet about them and
+// speaks only of removals, lock entries it drops, and clobbered local edits. One
+// list in both tenses so a dry run cannot describe an outcome differently from
+// the real run it predicts.
+const mirrorLines = (
+  result: MirrorResult,
+  dryRun: boolean,
+): ReadonlyArray<string> => {
+  const tense = (would: string, did: string): string => (dryRun ? would : did);
+  const writes = dryRun
+    ? [
+        ...result.created.map((rel) => `would create ${rel}`),
+        ...result.updated.map((rel) => `would update ${rel}`),
+      ]
+    : [];
+  const tampered =
+    result.tampered.length === 0
+      ? []
+      : [
+          `${tense('would overwrite', 'overwrote')} ${result.tampered.length} locally-modified canonical path(s): ${result.tampered.join(', ')}`,
+        ];
+  return [
+    ...writes,
+    ...result.deleted.map(
+      (rel) => `${tense('would delete', 'deleted')} ${rel} (removed upstream)`,
+    ),
+    ...result.retained.map(
+      (note) => `${tense('would leave in place', 'left in place')} ${note}`,
+    ),
+    ...result.stale.map(
+      (note) =>
+        `${tense('would drop', 'dropped')} the stale lock entry ${note}`,
+    ),
+    ...tampered,
+  ];
 };
 
-// Print what a mirror did (or, for a dry run, would do). Real syncs stay quiet
-// about unchanged files and only announce deletions and clobbered local edits.
 const reportMirror = (result: MirrorResult, dryRun: boolean): void => {
-  if (dryRun) {
-    for (const rel of result.created) {
-      console.log(`  would create ${rel}`);
-    }
-    for (const rel of result.updated) {
-      console.log(`  would update ${rel}`);
-    }
-    for (const rel of result.deleted) {
-      console.log(`  would delete ${rel} (removed upstream)`);
-    }
-    if (result.tampered.length > 0) {
-      console.log(
-        `  would overwrite ${result.tampered.length} locally-modified canonical file(s): ${result.tampered.join(', ')}`,
-      );
-    }
-    const changes =
-      result.created.length + result.updated.length + result.deleted.length;
-    console.log(
-      changes === 0
-        ? 'dry run: already in sync; no changes'
-        : `dry run: ${result.created.length} to create, ${result.updated.length} to update, ${result.deleted.length} to delete`,
-    );
-    return;
-  }
-  for (const rel of result.deleted) {
-    console.log(`  deleted ${rel} (removed upstream)`);
-  }
-  if (result.tampered.length > 0) {
-    console.log(
-      `  overwrote ${result.tampered.length} locally-modified canonical file(s): ${result.tampered.join(', ')}`,
-    );
+  for (const line of mirrorLines(result, dryRun)) {
+    console.log(`  ${line}`);
   }
 };
 
+// A retained or stale key leaves the lock, so the run rewrites `sync-standards.lock`
+// even when it touches nothing on disk; neither may be summed into "no changes".
+const reportDryRunSummary = (
+  result: MirrorResult,
+  generated: boolean,
+): void => {
+  const unlocked = result.retained.length + result.stale.length;
+  const changes =
+    result.created.length +
+    result.updated.length +
+    result.deleted.length +
+    unlocked +
+    Number(generated);
+  console.log(
+    changes === 0
+      ? 'dry run: already in sync; no changes'
+      : `dry run: ${result.created.length} to create, ${result.updated.length} to update, ${result.deleted.length} to delete, ${Number(generated)} to generate, ${unlocked} to drop from the lock without deleting`,
+  );
+};
+
 const seedTargets = (
   srcDir: string,
   seedDir: string,
-): Promise<ReadonlyMap<string, string>> => {
+): Promise<ReadonlyMap<string, ManagedEntry>> => {
   const root = join(srcDir, seedDir);
   return listManagedFiles(root, ['.']);
 };
@@ -362,27 +569,39 @@ const runInit = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const upstream = await listManagedFiles(src.dir, manifest.paths);
+  // Seeds are written before the mirror, so both halves of the payload must
+  // clear their preconditions here for `init` to refuse before writing anything.
+  assertNoProblems(
+    [
+      ...symlinkTargetProblems(seeds),
+      ...(await mirrorPreconditionProblems(consumer, upstream, {})),
+    ],
+    'cannot initialize from this source',
+  );
   const prospectiveDependabot = await prepareProspectiveDependabot(
-    manifest,
-    src.dir,
+    upstream,
     consumer,
     seeds.get(DEPENDABOT_LOCAL_FILE) ?? null,
   );
   await Promise.all(
-    [...seeds].map(async ([rel, abs]) => {
+    [...seeds].map(async ([rel, entry]) => {
       const dest = join(consumer, rel);
-      if (existsSync(dest)) {
+      // A seed destination is kept whenever anything at all occupies it.
+      // `existsSync` reports a broken link as absent, so it would call this
+      // destination free and let the seed replace a link the consumer put
+      // there; `lstat` sees the link and keeps it.
+      if ((await inspectManagedPath(dest)) !== null) {
         console.log(`  kept ${rel} (already present)`);
         return;
       }
       await mkdir(dirname(dest), { recursive: true });
-      await cp(abs, dest);
+      await writeManagedEntry(dest, entry);
       console.log(`  seeded ${rel}`);
     }),
   );
   const result = await mirror({
-    manifest,
-    srcDir: src.dir,
+    upstream,
     consumer,
     previous: {},
     dryRun: false,
@@ -395,7 +614,7 @@ const runInit = async (
     files: result.files,
   });
   console.log(
-    `init complete: ${Object.keys(result.files).length} managed file(s) at ${src.sha}`,
+    `init complete: ${Object.keys(result.files).length} managed path(s) at ${src.sha}`,
   );
 };
 
@@ -407,23 +626,27 @@ const runSync = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const upstream = await listManagedFiles(src.dir, manifest.paths);
   const prospectiveDependabot = await prepareProspectiveDependabot(
-    manifest,
-    src.dir,
+    upstream,
     consumer,
     null,
   );
   const lock = await readLock(consumer);
   const result = await mirror({
-    manifest,
-    srcDir: src.dir,
+    upstream,
     consumer,
     previous: lock?.files ?? {},
     dryRun,
   });
   reportMirror(result, dryRun);
-  await applyProspectiveDependabot(consumer, prospectiveDependabot, dryRun);
+  const generated = await applyProspectiveDependabot(
+    consumer,
+    prospectiveDependabot,
+    dryRun,
+  );
   if (dryRun) {
+    reportDryRunSummary(result, generated);
     return;
   }
   await writeLock(consumer, {
@@ -432,7 +655,7 @@ const runSync = async (
     files: result.files,
   });
   console.log(
-    `sync complete: ${Object.keys(result.files).length} managed file(s) at ${src.sha}`,
+    `sync complete: ${Object.keys(result.files).length} managed path(s) at ${src.sha}`,
   );
 };
 
@@ -454,10 +677,11 @@ const runCheck = async (consumer: string): Promise<boolean> => {
   const results = await Promise.all(
     Object.entries(lock.files).map(async ([rel, hash]) => {
       const dest = join(consumer, rel);
-      if (!existsSync(dest)) {
+      const entry = await inspectManagedPath(dest);
+      if (entry === null) {
         return `  missing:  ${rel}`;
       }
-      const current = sha256(await readFile(dest));
+      const current = sha256(await managedEntryDigestInput(entry));
       if (current !== hash) {
         return `  modified: ${rel} (expected ${hash.slice(0, HASH_PREVIEW_LENGTH)}, found ${current.slice(0, HASH_PREVIEW_LENGTH)})`;
       }
@@ -469,7 +693,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
     await findManagedFilesContainingBiomeDirectiveToken(lockedFiles);
   if (problems.length > 0) {
     console.error(
-      `standards: ${problems.length} canonical file(s) drifted from the last synced state:`,
+      `standards: ${problems.length} canonical path(s) drifted from the last synced state:`,
     );
     console.error(problems.join('\n'));
     console.error(
@@ -487,7 +711,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
   }
   if (problems.length === 0) {
     console.log(
-      `standards: ${Object.keys(lock.files).length} canonical file(s) match the last synced state`,
+      `standards: ${Object.keys(lock.files).length} canonical path(s) match the last synced state`,
     );
   }
   return problems.length === 0 && directiveFiles.length === 0;
@@ -577,14 +801,12 @@ type ProspectiveDependabot = {
 // file. For init, an existing overlay wins; otherwise the overlay seed is what
 // the command is about to install.
 const prepareProspectiveDependabot = async (
-  manifest: Manifest,
-  srcDir: string,
+  incoming: ReadonlyMap<string, ManagedEntry>,
   consumer: string,
-  localSeed: string | null,
+  localSeed: ManagedEntry | null,
 ): Promise<ProspectiveDependabot> => {
-  const incoming = await listManagedFiles(srcDir, manifest.paths);
-  const basePath = incoming.get(DEPENDABOT_BASE_FILE);
-  if (basePath === undefined) {
+  const base = incoming.get(DEPENDABOT_BASE_FILE);
+  if (base === undefined || base.kind !== 'file') {
     throw new Error(
       `source content must manage ${DEPENDABOT_BASE_FILE}; @davidvornholt/standards 0.10.1 requires a 0.10.1-compatible content ref`,
     );
@@ -594,10 +816,12 @@ const prepareProspectiveDependabot = async (
   );
   const local =
     existingLocal ??
-    (localSeed === null ? null : await readFile(localSeed, 'utf8'));
+    (localSeed === null || localSeed.kind !== 'file'
+      ? null
+      : await readFile(localSeed.absolutePath, 'utf8'));
   const current = await readTextIfPresent(join(consumer, DEPENDABOT_FILE));
   const sources = {
-    base: await readFile(basePath, 'utf8'),
+    base: await readFile(base.absolutePath, 'utf8'),
     local,
     current,
   };
@@ -612,16 +836,17 @@ const applyProspectiveDependabot = async (
   consumer: string,
   prospective: ProspectiveDependabot,
   dryRun: boolean,
-): Promise<void> => {
+): Promise<boolean> => {
   if (prospective.current === prospective.composed) {
-    return;
+    return false;
   }
   if (dryRun) {
     console.log(`  would generate ${DEPENDABOT_FILE}`);
-    return;
+    return true;
   }
   await writeComposedDependabot(consumer, prospective.composed);
   console.log(`  generated ${DEPENDABOT_FILE}`);
+  return true;
 };
 
 const runDependabotCheck = async (consumer: string): Promise<boolean> => {