dorfl 0.3.1 → 0.4.0

package/src/mirror-pool-scan.ts

@@ -47,7 +47,7 @@ import {heldTaskSlugs} from './item-lock.js';
  *     over the mirror's `work/specs/ready` + `work/specs/tasked` read via the mirror-ref
  *     {@link LedgerReadStrategy.resolveMirrorSpecPool}.
  *
- * Per-repo policy parity: a bare mirror has no checked-out `.dorfl.json`,
+ * Per-repo policy parity: a bare mirror has no checked-out `dorfl.json`,
  * but the COMMITTED one is reachable on `main` (the `do --remote` per-repo seam).
  * We layer it via {@link resolveRepoConfigFromMirror} so the same logical `work/`
  * state yields the SAME `autoBuild`/`autoTask` decision an in-place checkout
@@ -59,7 +59,7 @@ export interface ScanMirrorPoolOptions {
 	/** The bare hub mirror directory (`<workspacesDir>/repos/<key>.git`). */
 	mirrorPath: string;
 	/**
-	 * The global + default config layer. The repo's COMMITTED `.dorfl.json`
+	 * The global + default config layer. The repo's COMMITTED `dorfl.json`
 	 * (read from the mirror's `main`) is layered on top, so `autoBuild`/`autoTask`
 	 * resolve per-repo exactly as the in-place scan resolves them from the checkout.
 	 */
@@ -146,7 +146,7 @@ export async function scanMirrorPool(
 	const read = options.read ?? ledgerRead;
 	const warn = options.warn;
 
-	// Per-repo policy parity: layer the COMMITTED `.dorfl.json` from the
+	// Per-repo policy parity: layer the COMMITTED `dorfl.json` from the
 	// mirror's `main` (the `do --remote` per-repo seam) onto global. Never fatal —
 	// a config-less repo or a read fault falls back to global + default.
 	let repoConfig: Config;

package/src/prd-to-spec.ts

@@ -2,17 +2,27 @@ import {
 	existsSync,
 	readdirSync,
 	readFileSync,
-	statSync,
 	writeFileSync,
-	copyFileSync,
 	mkdirSync,
 	rmdirSync,
 } from 'node:fs';
-import {join, relative, dirname, basename} from 'node:path';
+import {join, basename} from 'node:path';
 import {run, git, gitMv} from './git.js';
-import {resolveProtocolDoc} from './prompt.js';
 import {WORK_ROOT} from './work-layout.js';
 import {repoConfigPath} from './repo-config.js';
+import {
+	resyncProtocol,
+	PROTOCOL_DOCS,
+	type ResyncedDoc,
+	type ResyncResult,
+} from './resync-protocol.js';
+
+// The protocol re-sync now lives in the shared `resync-protocol.ts` module (so
+// the standalone `dorfl sync` command and this migration engine share ONE
+// implementation). Re-exported here for backward compatibility with existing
+// importers/tests that reach for these symbols on `prd-to-spec.js`.
+export {resyncProtocol, PROTOCOL_DOCS};
+export type {ResyncedDoc, ResyncResult};
 
 /**
  * The **`dorfl prd-to-spec` migration ENGINE** (spec
@@ -41,7 +51,7 @@ import {repoConfigPath} from './repo-config.js';
  *      (a) FOLDERS `work/prds/{proposed,ready,tasked,dropped}/ → work/specs/…`
  *      via `git mv`; (b) FRONTMATTER/body `prd: → spec:` + inert path/token refs
  *      across ALL items INCLUDING `work/tasks/done/` and `work/specs/tasked/`;
- *      (c) CONFIG `.dorfl.json` (`prdsLandIn → specsLandIn`, keep-case);
+ *      (c) CONFIG `dorfl.json` (`prdsLandIn → specsLandIn`, keep-case);
  *      (d) LIVE GIT REFS (inert lock-refs `refs/dorfl/lock/prd-<slug>` and
  *      work-branches `work/prd-<slug>` — the quiescence gate guarantees none are
  *      held/in-flight, so this renames only INERT refs).
@@ -86,7 +96,7 @@ import {repoConfigPath} from './repo-config.js';
  * A single vocabulary cutover the engine enacts: the retired word `from` (all
  * three case variants) → the new word `to`. The `prd → spec` migration pins
  * {@link MIGRATION}; a future cutover supplies a different value and reuses the
- * same engine (user story 9). `configKeys` are the exact `.dorfl.json` keys that
+ * same engine (user story 9). `configKeys` are the exact `dorfl.json` keys that
  * carry the `from` word (their VALUES are preserved — only the key renames).
  */
 export interface VocabularyMigration {
@@ -111,25 +121,6 @@ export const MIGRATION: VocabularyMigration = {
 	configKeys: [{from: 'prdsLandIn', to: 'specsLandIn'}],
 };
 
-/**
- * The FULL set of protocol docs `setup` propagates into a repo's
- * `work/protocol/`. The re-sync copies EACH from the package's canonical source
- * (via {@link resolveProtocolDoc}) so the migrated repo carries the new `spec`
- * contract. Kept in lockstep with `skills/setup/protocol/` (the source of truth)
- * and the `vendor-protocol` build step (which vendors these into `dist/protocol/`
- * so the published CLI is self-contained).
- */
-export const PROTOCOL_DOCS: readonly string[] = [
-	'WORK-CONTRACT.md',
-	'CLAIM-PROTOCOL.md',
-	'REVIEW-PROTOCOL.md',
-	'SURFACE-PROTOCOL.md',
-	'TASKING-PROTOCOL.md',
-	'ADR-FORMAT.md',
-	'task-template.md',
-	'spec-template.md',
-];
-
 // ───────────────────────────────────────────────────────────────────────────
 // Layer: keep-case replace (the bespoke sweep — see the tooling JSDoc above).
 // ───────────────────────────────────────────────────────────────────────────
@@ -265,122 +256,6 @@ export function checkQuiescence(
 	return undefined;
 }
 
-// ───────────────────────────────────────────────────────────────────────────
-// Layer 2: the setup contract re-sync (the deterministic slice of `setup`).
-// ───────────────────────────────────────────────────────────────────────────
-
-/** One protocol doc the re-sync copied (or WOULD copy under `--dry-run`). */
-export interface ResyncedDoc {
-	/** The doc basename (e.g. `'WORK-CONTRACT.md'`). */
-	name: string;
-	/** Repo-relative destination (`work/protocol/<name>`). */
-	dest: string;
-	/** True when the target already had byte-identical content (a no-op copy). */
-	unchanged: boolean;
-	/**
-	 * True when the doc's SOURCE could not be resolved (the package/dev copy is
-	 * missing), so NOTHING was copied to `dest`. A skipped doc is NEVER counted as
-	 * a change (it must not bump `VERSION` — the latent bug this field guards) and
-	 * is surfaced LOUDLY by the caller. Distinct from `unchanged` (which means the
-	 * source WAS resolved and matched the dest byte-for-byte).
-	 */
-	skipped: boolean;
-}
-
-/** What the protocol re-sync did (or would do). */
-export interface ResyncResult {
-	docs: ResyncedDoc[];
-	/** Repo-relative `work/protocol/VERSION` path (written unless dry-run). */
-	versionPath: string;
-}
-
-/**
- * Re-sync the target repo's `work/protocol/*` from the package's canonical
- * source (the deterministic part of the `setup` skill — copy the docs verbatim +
- * bump `VERSION`). Resolves each doc's SOURCE via {@link resolveProtocolDoc} with
- * NO `cwd`, so it reads the package-vendored (`dist/protocol/`) or dev-source
- * (`skills/setup/protocol/`) copy — NEVER the target repo's own (old) copy. This
- * is how the migrated repo picks up the new `spec` contract before its data is
- * converted. Idempotent: a doc already byte-identical is reported `unchanged`.
- * A doc whose SOURCE cannot be resolved is reported `skipped` (NOT copied, NEVER
- * a VERSION-bump) rather than silently bumping VERSION with nothing copied.
- *
- * `dryRun` reports what WOULD be copied without writing. `resolveDoc` overrides
- * how a doc's source path is resolved (defaults to {@link resolveProtocolDoc});
- * it exists so a test can force a non-resolvable source (a path that does not
- * exist) to exercise the skip path.
- */
-export function resyncProtocol(
-	repoPath: string,
-	options: {
-		dryRun?: boolean;
-		resolveDoc?: (name: string) => string;
-	} = {},
-): ResyncResult {
-	const protocolDir = join(repoPath, WORK_ROOT, 'protocol');
-	const resolveDoc = options.resolveDoc ?? ((name) => resolveProtocolDoc(name));
-	const docs: ResyncedDoc[] = [];
-	for (const name of PROTOCOL_DOCS) {
-		// Resolve the SOURCE (package/dev), never the target's adopted copy.
-		const source = resolveDoc(name);
-		const destAbs = join(protocolDir, name);
-		const destRel = relative(repoPath, destAbs);
-		const sourceExists = existsSync(source);
-		if (!sourceExists) {
-			// The source doc could not be resolved: copy NOTHING and record the doc as
-			// SKIPPED (never a change). This is the latent-bug fix: a non-resolvable
-			// source must not count as `changed` and bump `VERSION` while copying no
-			// file. `unchanged: false` here is honest (the dest was not made to match a
-			// source), but `skipped: true` keeps it OUT of the VERSION-bump tally.
-			docs.push({name, dest: destRel, unchanged: false, skipped: true});
-			continue;
-		}
-		// Source resolved: a doc is CHANGED (VERSION-bump-worthy) only when the dest
-		// is absent OR its content differs from the source. An identical dest is a
-		// no-op copy (`unchanged`), so an already-synced re-run stays a true no-op.
-		const unchanged =
-			existsSync(destAbs) &&
-			readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
-		if (!options.dryRun) {
-			mkdirSync(dirname(destAbs), {recursive: true});
-			copyFileSync(source, destAbs);
-		}
-		docs.push({name, dest: destRel, unchanged, skipped: false});
-	}
-
-	const versionAbs = join(protocolDir, 'VERSION');
-	const versionRel = relative(repoPath, versionAbs);
-	// Bump VERSION only when a doc was ACTUALLY COPIED with new content, or when
-	// VERSION is absent AND at least one doc was genuinely synced (copied). A
-	// SKIPPED doc (unresolvable source, nothing copied) is NEVER a change —
-	// counting it would bump VERSION without copying a single doc (the latent bug),
-	// and the write-when-absent fallback must ALSO require a real copy so an
-	// all-skipped resync leaves no VERSION behind. A re-run on an already-synced
-	// repo must stay a true no-op — otherwise the (always-fresh) `synced-at`
-	// timestamp would dirty the tree on every idempotent re-run.
-	const anyDocChanged = docs.some((d) => !d.unchanged && !d.skipped);
-	const anyDocSynced = docs.some((d) => !d.skipped);
-	if (
-		!options.dryRun &&
-		(anyDocChanged || (anyDocSynced && !existsSync(versionAbs)))
-	) {
-		mkdirSync(dirname(versionAbs), {recursive: true});
-		const today = new Date().toISOString().slice(0, 10);
-		writeFileSync(
-			versionAbs,
-			[
-				`protocol-version: ${today}`,
-				'synced-from: skills/setup/protocol/',
-				`synced-at: ${new Date().toISOString()}`,
-				'source-commit: dorfl prd-to-spec',
-				'',
-			].join('\n'),
-		);
-	}
-
-	return {docs, versionPath: versionRel};
-}
-
 // ───────────────────────────────────────────────────────────────────────────
 // Layer 3a: the FOLDER move (in lockstep with work-layout.ts).
 // ───────────────────────────────────────────────────────────────────────────
@@ -653,7 +528,7 @@ export function migrateAllItemContent(
 }
 
 // ───────────────────────────────────────────────────────────────────────────
-// Layer 3c: the CONFIG key rewrite (.dorfl.json).
+// Layer 3c: the CONFIG key rewrite (dorfl.json).
 // ───────────────────────────────────────────────────────────────────────────
 
 /** One config key the rewrite renamed (or would rename). */
@@ -663,12 +538,12 @@ export interface ConfigRewrite {
 }
 
 /**
- * Rewrite the retired config KEYS in `.dorfl.json` (`prdsLandIn → specsLandIn`),
+ * Rewrite the retired config KEYS in `dorfl.json` (`prdsLandIn → specsLandIn`),
  * preserving each key's VALUE and the file's surrounding formatting — a TEXTUAL
  * key rename on the raw JSON, NOT a parse+reserialise (which would drop unknown
  * keys / reflow the file). Only renames a key that is actually present, so it is
  * idempotent (a config already on `specsLandIn` changes nothing) and safe on a
- * repo with no `.dorfl.json`. Returns the keys renamed. `dryRun` reports without
+ * repo with no `dorfl.json`. Returns the keys renamed. `dryRun` reports without
  * writing.
  */
 export function migrateConfig(
@@ -677,7 +552,7 @@ export function migrateConfig(
 	options: {dryRun?: boolean} = {},
 ): ConfigRewrite[] {
 	// Resolve the repo's actual config file (prefers `dorfl.json`, falls back to
-	// the legacy `.dorfl.json`), so the key rewrite finds it under either name.
+	// the legacy `dorfl.json`), so the key rewrite finds it under either name.
 	const configAbs = repoConfigPath(repoPath);
 	if (!existsSync(configAbs)) {
 		return [];
@@ -806,7 +681,7 @@ export interface DataLeak {
  * command's OUTPUT (ADR §7e: the leak scan is exhaustive-by-construction). This
  * is the DATA analogue of the source-part `prd-to-spec-leak-scan.test.ts`
  * (which scans `src/`/`skills/`/`docs/`): here it walks the CONVERTED `work/`
- * tree + `.dorfl.json` + the git refs.
+ * tree + `dorfl.json` + the git refs.
  *
  *   - **FORWARD:** fails on any surviving retired word (`prd`/`Prd`/`PRD`) in a
  *     data STRUCTURE position — a frontmatter `prd:` KEY, a `work/prds/…` folder
@@ -926,7 +801,7 @@ export function scanForLeaks(
 		}
 	}
 	// The config file (the key layer) — under either the preferred `dorfl.json`
-	// or the legacy `.dorfl.json`.
+	// or the legacy `dorfl.json`.
 	const configAbs = repoConfigPath(repoPath);
 	if (existsSync(configAbs)) {
 		scanText(
@@ -1040,7 +915,10 @@ export function runPrdToSpec(options: PrdToSpecOptions): PrdToSpecResult {
 	}
 
 	// 2. Setup contract re-sync FIRST (decision B).
-	const resync = resyncProtocol(repoPath, {dryRun});
+	const resync = resyncProtocol(repoPath, {
+		dryRun,
+		sourceCommit: 'dorfl prd-to-spec',
+	});
 	// 3a. Folders (git mv) — before content, so the content sweep also fixes the
 	//     moved items' own `work/prds/…` body refs in their NEW location.
 	const folderMoves = migrateFolders(repoPath, migration, {dryRun});

package/src/repo-config.ts

@@ -16,7 +16,7 @@ import {run} from './git.js';
 /**
  * The per-repo config layer.
  *
- * A repo may commit a `.dorfl.json` at its root. It travels WITH the repo
+ * A repo may commit a `dorfl.json` at its root. It travels WITH the repo
  * (it is committed) and overrides the global `~/.config/dorfl/config.json`
  * FOR THAT REPO ONLY — so repo-local properties (how this repo integrates, its
  * acceptance `verify` gate, which remote arbitrates its claims) are agreed by all
@@ -28,7 +28,7 @@ import {run} from './git.js';
  *   global > built-in default
  *
  * The mechanism is multi-repo aware: each repo resolves against its OWN
- * `.dorfl.json`, so repo A can be `merge` while repo B is `propose` in the
+ * `dorfl.json`, so repo A can be `merge` while repo B is `propose` in the
  * SAME run (see {@link resolveRepoConfig}).
  *
  * Only keys that are genuinely repo properties are honoured in the COMMITTED
@@ -44,7 +44,7 @@ import {run} from './git.js';
  * the global file / a flag) may set ANY key, host-only included (see
  * {@link envOverrides}).
  *
- * A repo with no `.dorfl.json` resolves to exactly the global config —
+ * A repo with no `dorfl.json` resolves to exactly the global config —
  * behaviour is unchanged from before this layer existed.
  */
 
@@ -57,7 +57,7 @@ export const REPO_CONFIG_FILENAME = brand.repoConfigFilename;
 
 /**
  * Config keys that are genuinely repo properties and so are honoured in a
- * per-repo `.dorfl.json`. Deliberately a subset of {@link Config};
+ * per-repo `dorfl.json`. Deliberately a subset of {@link Config};
  * extend this list as more keys become legitimately repo-scoped.
  */
 export const REPO_ALLOWED_KEYS = [
@@ -306,7 +306,7 @@ export function repoConfigPath(repoPath: string): string {
 	return resolveRepoConfigPath(repoPath);
 }
 
-/** The result of reading (and filtering) a repo's `.dorfl.json`. */
+/** The result of reading (and filtering) a repo's `dorfl.json`. */
 export interface LoadedRepoConfig {
 	/** Where we looked (whether or not the file exists). */
 	path: string;
@@ -328,7 +328,7 @@ export interface LoadedRepoConfig {
 }
 
 /**
- * Read a repo's `.dorfl.json` and split it into the honoured subset and
+ * Read a repo's `dorfl.json` and split it into the honoured subset and
  * the rejected runner/host-only keys. A missing file is not an error (the repo
  * simply resolves to the global config); invalid JSON is. Unknown keys are
  * silently dropped (neither honoured nor reported as rejected). Only keys in
@@ -352,8 +352,8 @@ export function loadRepoConfig(repoPath: string): LoadedRepoConfig {
 
 /**
  * The content-based half of {@link loadRepoConfig}: parse + apply the SAME
- * allow/reject split to ALREADY-READ `.dorfl.json` bytes, labelling the
- * source as `sourceLabel` (a path, or e.g. `<arbiter>/main:.dorfl.json`)
+ * allow/reject split to ALREADY-READ `dorfl.json` bytes, labelling the
+ * source as `sourceLabel` (a path, or e.g. `<arbiter>/main:dorfl.json`)
  * in the rejected-key message. Used wherever the committed repo file is sourced
  * from somewhere OTHER than a working-tree path — notably `do --remote`, which
  * reads it from the arbiter's `main` (`git show`) since there is no checkout.
@@ -413,7 +413,7 @@ function isRejectedKey(key: string): boolean {
 
 /** Inputs to {@link resolveRepoConfig}. */
 export interface ResolveRepoConfigOptions {
-	/** Absolute path to the repo root (where `.dorfl.json` would live). */
+	/** Absolute path to the repo root (where `dorfl.json` would live). */
 	repoPath: string;
 	/**
 	 * The fully-resolved GLOBAL config (already merged over built-in defaults,
@@ -491,7 +491,7 @@ export interface ResolvedRepoConfig {
 /**
  * Resolve the effective config for ONE repo by layering, per key:
  *
- *   flag > ENV (DORFL_*) > per-repo `.dorfl.json` > global >
+ *   flag > ENV (DORFL_*) > per-repo `dorfl.json` > global >
  *   built-in default
  *
  * The `global` argument already carries the global + default layers (it is the
@@ -502,7 +502,7 @@ export interface ResolvedRepoConfig {
  * in a multi-repo run yields INDEPENDENT results — repo A can be `merge` while
  * repo B is `propose` in the same run.
  *
- * A repo with no `.dorfl.json` (and no env) resolves to exactly `global`
+ * A repo with no `dorfl.json` (and no env) resolves to exactly `global`
  * (unchanged behaviour).
  */
 export function resolveRepoConfig(

package/src/repo-mirror.ts

@@ -151,7 +151,7 @@ export function ensureMirror(options: EnsureMirrorOptions): EnsureMirrorResult {
  * but on REUSE refreshes via {@link fetchMirrorMain} (main-only, no-prune).
  *
  * This is the MIRROR-ENSURE for the no-checkout CONFIG READ (`do --remote`/
- * `do --isolated` per-repo `.dorfl.json`): `git show main:.dorfl.json`
+ * `do --isolated` per-repo `dorfl.json`): `git show main:dorfl.json`
  * only needs `main`, and using the pruning all-heads fetch here would let a
  * `work/<slug>` branch CHECKED OUT in some other (stale) job worktree block the
  * fetch (`git refuses to fetch into branch … checked out`), throwing the config
@@ -226,12 +226,12 @@ export function fetchMirrorMain(
 }
 
 /**
- * Read the target repo's COMMITTED `.dorfl.json` from the bare hub
- * mirror's `main` (`git show main:.dorfl.json`) — the per-repo config
+ * Read the target repo's COMMITTED `dorfl.json` from the bare hub
+ * mirror's `main` (`git show main:dorfl.json`) — the per-repo config
  * layer for the NO-CHECKOUT paths (`do --remote`). The committed file is a
  * tracked file on `<arbiter>/main`, so it is reachable from the mirror without a
  * worktree. Returns the raw file CONTENT, or `undefined` when the repo has no
- * `.dorfl.json` on `main` (a config-less repo — the caller then resolves to
+ * `dorfl.json` on `main` (a config-less repo — the caller then resolves to
  * exactly global + default, byte-identical to before this layer existed).
  *
  * This is the task's ONE genuinely-new seam: sourcing the bytes from the arbiter
@@ -248,7 +248,7 @@ export function readRepoConfigFromMirrorMain(
 	mirrorDir: string,
 	env?: NodeJS.ProcessEnv,
 ): string | undefined {
-	// Prefer the plain `dorfl.json`; fall back to the legacy `.dorfl.json` when the
+	// Prefer the plain `dorfl.json`; fall back to the legacy `dorfl.json` when the
 	// preferred name is absent on `main` (a repo that committed the dotfile before
 	// dual-support). A genuine read fault on the FIRST attempt propagates; a
 	// path-missing on the first falls through to the legacy attempt.
@@ -293,7 +293,7 @@ function showConfigOnMain(
 
 /**
  * Resolve a repo's effective {@link Config} for a NO-CHECKOUT path by layering its
- * COMMITTED `.dorfl.json` (read from the bare hub mirror's `main` via
+ * COMMITTED `dorfl.json` (read from the bare hub mirror's `main` via
  * {@link readRepoConfigFromMirrorMain}) into the SAME
  * `flag > env > per-repo > global > default` chain a working checkout uses
  * ({@link resolveRepoConfigFromLoaded}). This is the reusable core of `do
@@ -308,7 +308,7 @@ function showConfigOnMain(
  * global + flags itself.
  */
 export function resolveRepoConfigFromMirror(options: {
-	/** The bare hub mirror directory whose `main:.dorfl.json` to read. */
+	/** The bare hub mirror directory whose `main:dorfl.json` to read. */
 	mirrorPath: string;
 	/** The global + default config layer (from `loadConfig`/`mergeConfig`). */
 	global: Config;

package/src/resync-protocol.ts

@@ -0,0 +1,162 @@
+import {
+	existsSync,
+	readFileSync,
+	writeFileSync,
+	copyFileSync,
+	mkdirSync,
+} from 'node:fs';
+import {join, relative, dirname} from 'node:path';
+import {resolveProtocolDoc} from './prompt.js';
+import {WORK_ROOT} from './work-layout.js';
+
+/**
+ * The **protocol re-sync** primitive: copy the package's canonical
+ * `work/protocol/*` docs into a target repo's `work/protocol/` and bump
+ * `work/protocol/VERSION`. This is the deterministic slice of what the `setup`
+ * skill does — the SINGLE source of truth for "make this repo carry the current
+ * protocol contract".
+ *
+ * Two verbs drive it:
+ *   - `dorfl sync` — the standalone "get the latest protocol" command (a repo
+ *     that adopted an OLD protocol picks up the new docs in one command);
+ *   - `dorfl prd-to-spec` — the vocabulary-migration engine, which re-syncs the
+ *     contract FIRST (before converting the repo's data) so the migrated repo
+ *     lands on the new `spec` contract.
+ *
+ * It was lifted out of `prd-to-spec.ts` (where it began life) into this shared
+ * module so both verbs import ONE implementation; `prd-to-spec.ts` re-exports
+ * the symbols for backward compatibility.
+ */
+
+/**
+ * The FULL set of protocol docs `setup` propagates into a repo's
+ * `work/protocol/`. The re-sync copies EACH from the package's canonical source
+ * (via {@link resolveProtocolDoc}) so a set-up repo carries the current
+ * contract. Kept in lockstep with `skills/setup/protocol/` (the source of truth)
+ * and the `vendor-protocol` build step (which vendors these into `dist/protocol/`
+ * so the published CLI is self-contained).
+ */
+export const PROTOCOL_DOCS: readonly string[] = [
+	'WORK-CONTRACT.md',
+	'CLAIM-PROTOCOL.md',
+	'REVIEW-PROTOCOL.md',
+	'SURFACE-PROTOCOL.md',
+	'TASKING-PROTOCOL.md',
+	'ADR-FORMAT.md',
+	'task-template.md',
+	'spec-template.md',
+];
+
+/** One protocol doc the re-sync copied (or WOULD copy under `--dry-run`). */
+export interface ResyncedDoc {
+	/** The doc basename (e.g. `'WORK-CONTRACT.md'`). */
+	name: string;
+	/** Repo-relative destination (`work/protocol/<name>`). */
+	dest: string;
+	/** True when the target already had byte-identical content (a no-op copy). */
+	unchanged: boolean;
+	/**
+	 * True when the doc's SOURCE could not be resolved (the package/dev copy is
+	 * missing), so NOTHING was copied to `dest`. A skipped doc is NEVER counted as
+	 * a change (it must not bump `VERSION` — the latent bug this field guards) and
+	 * is surfaced LOUDLY by the caller. Distinct from `unchanged` (which means the
+	 * source WAS resolved and matched the dest byte-for-byte).
+	 */
+	skipped: boolean;
+}
+
+/** What the protocol re-sync did (or would do). */
+export interface ResyncResult {
+	docs: ResyncedDoc[];
+	/** Repo-relative `work/protocol/VERSION` path (written unless dry-run). */
+	versionPath: string;
+}
+
+/**
+ * Re-sync the target repo's `work/protocol/*` from the package's canonical
+ * source (the deterministic part of the `setup` skill — copy the docs verbatim +
+ * bump `VERSION`). Resolves each doc's SOURCE via {@link resolveProtocolDoc} with
+ * NO `cwd`, so it reads the package-vendored (`dist/protocol/`) or dev-source
+ * (`skills/setup/protocol/`) copy — NEVER the target repo's own (old) copy. This
+ * is how a repo picks up the current contract. Idempotent: a doc already
+ * byte-identical is reported `unchanged`. A doc whose SOURCE cannot be resolved
+ * is reported `skipped` (NOT copied, NEVER a VERSION-bump) rather than silently
+ * bumping VERSION with nothing copied.
+ *
+ * `dryRun` reports what WOULD be copied without writing. `resolveDoc` overrides
+ * how a doc's source path is resolved (defaults to {@link resolveProtocolDoc});
+ * it exists so a test can force a non-resolvable source (a path that does not
+ * exist) to exercise the skip path. `sourceCommit` is stamped into the written
+ * `VERSION` provenance line so a reader can tell which verb wrote it.
+ */
+export function resyncProtocol(
+	repoPath: string,
+	options: {
+		dryRun?: boolean;
+		resolveDoc?: (name: string) => string;
+		sourceCommit?: string;
+	} = {},
+): ResyncResult {
+	const protocolDir = join(repoPath, WORK_ROOT, 'protocol');
+	const resolveDoc = options.resolveDoc ?? ((name) => resolveProtocolDoc(name));
+	const docs: ResyncedDoc[] = [];
+	for (const name of PROTOCOL_DOCS) {
+		// Resolve the SOURCE (package/dev), never the target's adopted copy.
+		const source = resolveDoc(name);
+		const destAbs = join(protocolDir, name);
+		const destRel = relative(repoPath, destAbs);
+		const sourceExists = existsSync(source);
+		if (!sourceExists) {
+			// The source doc could not be resolved: copy NOTHING and record the doc as
+			// SKIPPED (never a change). This is the latent-bug fix: a non-resolvable
+			// source must not count as `changed` and bump `VERSION` while copying no
+			// file. `unchanged: false` here is honest (the dest was not made to match a
+			// source), but `skipped: true` keeps it OUT of the VERSION-bump tally.
+			docs.push({name, dest: destRel, unchanged: false, skipped: true});
+			continue;
+		}
+		// Source resolved: a doc is CHANGED (VERSION-bump-worthy) only when the dest
+		// is absent OR its content differs from the source. An identical dest is a
+		// no-op copy (`unchanged`), so an already-synced re-run stays a true no-op.
+		const unchanged =
+			existsSync(destAbs) &&
+			readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
+		if (!options.dryRun) {
+			mkdirSync(dirname(destAbs), {recursive: true});
+			copyFileSync(source, destAbs);
+		}
+		docs.push({name, dest: destRel, unchanged, skipped: false});
+	}
+
+	const versionAbs = join(protocolDir, 'VERSION');
+	const versionRel = relative(repoPath, versionAbs);
+	// Bump VERSION only when a doc was ACTUALLY COPIED with new content, or when
+	// VERSION is absent AND at least one doc was genuinely synced (copied). A
+	// SKIPPED doc (unresolvable source, nothing copied) is NEVER a change —
+	// counting it would bump VERSION without copying a single doc (the latent bug),
+	// and the write-when-absent fallback must ALSO require a real copy so an
+	// all-skipped resync leaves no VERSION behind. A re-run on an already-synced
+	// repo must stay a true no-op — otherwise the (always-fresh) `synced-at`
+	// timestamp would dirty the tree on every idempotent re-run.
+	const anyDocChanged = docs.some((d) => !d.unchanged && !d.skipped);
+	const anyDocSynced = docs.some((d) => !d.skipped);
+	if (
+		!options.dryRun &&
+		(anyDocChanged || (anyDocSynced && !existsSync(versionAbs)))
+	) {
+		mkdirSync(dirname(versionAbs), {recursive: true});
+		const today = new Date().toISOString().slice(0, 10);
+		writeFileSync(
+			versionAbs,
+			[
+				`protocol-version: ${today}`,
+				'synced-from: skills/setup/protocol/',
+				`synced-at: ${new Date().toISOString()}`,
+				`source-commit: ${options.sourceCommit ?? 'dorfl sync'}`,
+				'',
+			].join('\n'),
+		);
+	}
+
+	return {docs, versionPath: versionRel};
+}

package/src/run.ts

@@ -294,7 +294,7 @@ export interface RunOnceOptions {
 	/** Override agent-id generation (tests). Retained for API compat; unused for branch naming. */
 	agentId?: () => string;
 	/**
-	 * Sink for non-fatal warnings (e.g. a repo's `.dorfl.json` naming
+	 * Sink for non-fatal warnings (e.g. a repo's `dorfl.json` naming
 	 * runner/host-only keys that were ignored). Defaults to a no-op so the core
 	 * stays pure; the CLI wires this to stderr.
 	 */
@@ -537,7 +537,7 @@ async function runOneItem(
 	const {slug, repoPath} = candidate;
 	const base: ItemResult = {repoPath, slug, status: 'lost-race'};
 
-	// Resolve THIS repo's effective config against its own `.dorfl.json`
+	// Resolve THIS repo's effective config against its own `dorfl.json`
 	// layered over the global config (flag > per-repo > global > default). Each
 	// repo gets its own integration mode / arbiter, so repo A can be `merge`
 	// while repo B is `propose` in one tick.

package/src/scan.ts

@@ -384,7 +384,7 @@ export function scoreItems(
  * primitive; the per-repo `work/` read goes through the seam's mirror-ref method.
  *
  * The autonomy gate's `autoBuild` policy is resolved PER REPO. NOTE: a bare
- * mirror has no checked-out `.dorfl.json`, so the per-repo file cannot be
+ * mirror has no checked-out `dorfl.json`, so the per-repo file cannot be
  * read from it — the global/env-resolved policy applies (the per-repo override is
  * a working-checkout concern, served by {@link scanRepoPaths}).
  */
@@ -450,7 +450,7 @@ export async function scan(
 		);
 		// Spec pool — the TASKABLE-SPEC companion of the task pool above
 		// (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`). Resolve
-		// `autoTask` PER REPO from the mirror's COMMITTED `.dorfl.json`
+		// `autoTask` PER REPO from the mirror's COMMITTED `dorfl.json`
 		// (exactly as the mirror-side pool scan does — NOT forked); a read fault is
 		// non-fatal (warn + global fall-back), since `scan` is read-only and must
 		// degrade gracefully (ADR §5/§6).
@@ -476,7 +476,7 @@ export async function scan(
 		const specs = scoreSpecs(mirror.path, specPool, repoAutoTask);
 		// The per-repo LIFECYCLE pool (`ci-propose-matrix-enumerates-lifecycle-items`),
 		// gated by this mirror's question-surfacing config (resolved from its committed
-		// `.dorfl.json`, with the same non-fatal global fall-back as `autoTask`
+		// `dorfl.json`, with the same non-fatal global fall-back as `autoTask`
 		// above) and computed by REUSING `gatherLifecycleMirror` → `buildLifecyclePools`
 		// (NOT a forked predicate), so it AGREES with the `run` selection.
 		let repoLifecycleConfig = {
@@ -536,7 +536,7 @@ export async function scan(
  * checkout IS the local state); the fetch-first contract (ADR §5/§6) applies to
  * the REGISTRY `scan` above, which refreshes each bare mirror before reading.
  * Reads each repo's `work/` via the read seam's local-tree method and honours its
- * per-repo `.dorfl.json` `autoBuild`. The registry `scan` above is the
+ * per-repo `dorfl.json` `autoBuild`. The registry `scan` above is the
  * mirror-ref counterpart; this is its working-tree sibling.
  */
 export function scanRepoPaths(
@@ -579,7 +579,7 @@ export function scanRepoPaths(
 			override,
 		}).config;
 		// Spec pool — the TASKABLE-SPEC companion of the task pool. Resolve
-		// `autoTask` PER REPO from the working-tree `.dorfl.json` (the same
+		// `autoTask` PER REPO from the working-tree `dorfl.json` (the same
 		// way `autoBuild` is resolved); `taskableSpecs` (the SAME `autoslice-gate`
 		// predicate the autopick paths run) decides what is taskable — no forked
 		// predicate. This is what makes the propose-mode CI matrix enumerate `spec:`

package/src/verify-workflow-template.ts

@@ -13,7 +13,7 @@
  *
  * The workflow is deliberately thin: it wires the same composite setup action
  * the other capabilities use, then runs `dorfl verify` — the deterministic shell
- * gate the repo declares in `.dorfl.json`. No agent, no provider secrets, no
+ * gate the repo declares in `dorfl.json`. No agent, no provider secrets, no
  * `gh` mutation; it is read-only with respect to `work/`.
  *
  * `merge_group` is present (with no extra wiring) so a follow-on Tier-2 task