dorfl 0.1.0 → 0.1.1

package/src/cli.ts

@@ -844,11 +844,21 @@ function printPrdToSpecReport(result: PrdToSpecResult): void {
 	);
 
 	if (result.resync) {
-		const changed = result.resync.docs.filter((d) => !d.unchanged).length;
+		const changed = result.resync.docs.filter(
+			(d) => !d.unchanged && !d.skipped,
+		).length;
 		console.log(
 			`Contract re-sync: ${verb} sync ${result.resync.docs.length} protocol ` +
 				`doc(s) (${changed} changed) + bump ${result.resync.versionPath}.`,
 		);
+		// Surface any doc whose SOURCE could not be resolved LOUDLY: it was NOT
+		// copied, so the contract in the target repo is incomplete for that doc.
+		for (const skipped of result.resync.docs.filter((d) => d.skipped)) {
+			console.warn(
+				`  !! ${skipped.name}: SOURCE could not be resolved — NOT copied ` +
+					`(the contract doc is missing/unchanged in the target repo).`,
+			);
+		}
 	}
 	console.log(`Folders: ${verb} move ${result.folderMoves.length} folder(s).`);
 	for (const m of result.folderMoves) {

package/src/do.ts

@@ -1054,7 +1054,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 			taskContent: readFileSync(task.path, 'utf8'),
 		});
-		prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+		prompt = buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 			cwd: tree.dir,
 			continueContext,
 			promptGuidance: itemGuidance,
@@ -2245,7 +2245,7 @@ async function runRemotePipeline(
 			repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 			taskContent: readFileSync(task.path, 'utf8'),
 		});
-		prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+		prompt = buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 			cwd,
 			continueContext,
 			promptGuidance: itemGuidance,

package/src/frontmatter.ts

@@ -44,45 +44,38 @@ export interface Frontmatter {
 	/** Content-derived slug id (frontmatter `slug:`). */
 	slug: string | undefined;
 	/**
-	 * Source SPEC slug (frontmatter `spec:`); the spec lives at
-	 * `work/specs/ready/<spec>.md`. The `spec` vocabulary name for the parent-spec
-	 * pointer (prd `prd-to-spec-vocabulary-cutover-and-migration-command`). This is
-	 * the EXPAND-step ADDITION beside {@link prd}: `parseFrontmatter` populates BOTH
-	 * from EITHER the `spec:` OR the `prd:` key with the SAME value, so a caller
-	 * reading either sees the parent-spec slug. The migrate batches move `fm.prd`
-	 * reads onto `fm.spec` one at a time; the contract task removes `prd`.
+	 * Source SPEC slug: the parent-spec pointer this artifact derives from; the
+	 * spec lives at `work/specs/ready/<spec>.md`. The `spec` vocabulary name (spec
+	 * `prd-to-spec-vocabulary-cutover-and-migration-command`). `parseFrontmatter`
+	 * populates it from EITHER the canonical `spec:` key OR the LEGACY `prd:` key
+	 * (the latter kept as a read-only BACK-COMPAT alias for un-migrated downstream
+	 * repos, whose data still carries `prd:` until `dorfl prd-to-spec` converts it).
+	 * `spec:` wins when both are present. There is no longer a separate `fm.prd`
+	 * FIELD — both keys feed this one field.
 	 */
 	spec: string | undefined;
-	/**
-	 * Source spec slug (frontmatter `prd:`); the spec lives at
-	 * `work/specs/ready/<prd>.md`. The LEGACY vocabulary name for the parent-spec
-	 * pointer, kept BESIDE {@link spec} through the expand→migrate→contract cutover
-	 * (prd `prd-to-spec-vocabulary-cutover-and-migration-command`) so every existing
-	 * `fm.prd` reader keeps working; populated from EITHER the `spec:` or `prd:` key.
-	 */
-	prd: string | undefined;
 	/**
 	 * The GitHub issue number an `intake`-emitted artifact was transformed from
 	 * (frontmatter `issue:`). Parsed so the `issue: N` intake writes is
 	 * MACHINE-READABLE — the close JOB (`runner-in-ci`'s) reaches it to resolve the
 	 * issue from folder + field state. Carried on EITHER:
 	 *
-	 * - a **prd** (`intake`'s prd outcome) — a fanned task reaches it via
-	 *   `task.prd: → work/prds/ready/<prd>.md → prd issue:` (the number lives
-	 *   ONLY on the prd, never duplicated across the N fanned tasks); OR
-	 * - a **lone task** (`intake`'s TASK outcome, no `prd:`) — the provider-agnostic
+	 * - a **spec** (`intake`'s spec outcome) — a fanned task reaches it via
+	 *   `task.spec: → work/specs/ready/<spec>.md → spec issue:` (the number lives
+	 *   ONLY on the spec, never duplicated across the N fanned tasks); OR
+	 * - a **lone task** (`intake`'s TASK outcome, no `spec:`) — the provider-agnostic
 	 *   closure link for a task that closes its own issue directly (replaces the old
 	 *   GitHub-only `Fixes #N` body line, which is now a deferred optimisation).
 	 *
-	 * INVARIANT — one closure path per task: a task uses `issue:` XOR `prd:`, never
+	 * INVARIANT — one closure path per task: a task uses `issue:` XOR `spec:`, never
 	 * both. Either it closes its own issue directly (`issue:`) or it contributes to a
-	 * prd that closes the issue (`prd:` → prd `issue:`). This is NOT enforced by a
+	 * spec that closes the issue (`spec:` → spec `issue:`). This is NOT enforced by a
 	 * throwing validator (there is no frontmatter-validation layer): intake never
-	 * emits both — its task / prd dispatch branches are mutually exclusive — so only
-	 * a human hand-edit could produce both, and the precedence rule (`prd:` wins,
+	 * emits both — its task / spec dispatch branches are mutually exclusive — so only
+	 * a human hand-edit could produce both, and the precedence rule (`spec:` wins,
 	 * `issue:` ignored) is the future close-job's concern (see {@link
-	 * resolveClosingIssue}), degrading a typo to "use the prd's number" rather than
-	 * crashing. `undefined` when omitted (every non-intake prd and most tasks).
+	 * resolveClosingIssue}), degrading a typo to "use the spec's number" rather than
+	 * crashing. `undefined` when omitted (every non-intake spec and most tasks).
 	 */
 	issue: number | undefined;
 	/**
@@ -334,7 +327,6 @@ export function parseFrontmatter(content: string): Frontmatter {
 		originTrust: undefined,
 		slug: undefined,
 		spec: undefined,
-		prd: undefined,
 		issue: undefined,
 		humanOnly: undefined,
 		needsAnswers: undefined,
@@ -379,23 +371,23 @@ export function parseFrontmatter(content: string): Frontmatter {
 		} else if (key === 'slug') {
 			result.slug = rawValue === '' ? undefined : unquote(rawValue);
 		} else if (key === 'spec' || key === 'prd') {
-			// EXPAND step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-			// the parent-spec pointer is written under EITHER the new `spec:` key or the
-			// legacy `prd:` key. Populate BOTH `fm.spec` and `fm.prd` with the same value
-			// so a caller reading either field sees it. `spec:` wins if both are present
-			// (the canonical key takes precedence over the legacy alias); an empty value
-			// on one key does NOT clobber a non-empty value already read from the other.
+			// The parent-spec pointer, read from EITHER the canonical `spec:` key OR the
+			// LEGACY `prd:` key into the SINGLE `fm.spec` field (spec
+			// `prd-to-spec-vocabulary-cutover-and-migration-command`). The `prd:` key
+			// read is a permanent-for-now BACK-COMPAT alias so an un-migrated downstream
+			// repo (whose data still carries `prd:` until `dorfl prd-to-spec` converts
+			// it) keeps resolving its parent spec. `spec:` WINS when both are present
+			// (the canonical key over the legacy alias); an empty value on one key does
+			// NOT clobber a non-empty value already read from the other.
 			const value = rawValue === '' ? undefined : unquote(rawValue);
 			if (key === 'spec') {
 				// The canonical key wins: overwrite whatever `prd:` may have set.
 				if (value !== undefined) {
 					result.spec = value;
-					result.prd = value;
 				}
 			} else if (result.spec === undefined) {
-				// Legacy `prd:` only fills in when `spec:` has not already set the pair.
+				// Legacy `prd:` only fills in when `spec:` has not already set it.
 				result.spec = value;
-				result.prd = value;
 			}
 		} else if (key === 'issue') {
 			// Integer issue link (`intake`'s prd-emit OR a lone-task emit). A
@@ -456,15 +448,15 @@ export function parseFrontmatter(content: string): Frontmatter {
 
 /**
  * Resolve, from a parsed artifact's frontmatter, HOW it closes its source issue:
- * the `prd:` hop or the lone-task `issue:` field. A PURE helper for the FUTURE
+ * the `spec:` hop or the lone-task `issue:` field. A PURE helper for the FUTURE
  * CI close-job (`runner-in-ci`'s) — it is NOT wired into intake or any reader
  * today; it merely pins the one-closure-path PRECEDENCE in one place.
  *
- * Encodes the invariant: a task uses `issue:` XOR `prd:`. When (only a human
- * hand-edit could) BOTH are present, `prd:` WINS — the close-job hops to the prd's
- * `issue:` and IGNORES the task's own `issue:` (the fanned-prd path is the
- * authoritative one; a lone `issue:` on a `prd:`-bearing task is a contradiction
- * that degrades to "use the prd" rather than crashing).
+ * Encodes the invariant: a task uses `issue:` XOR `spec:`. When (only a human
+ * hand-edit could) BOTH are present, `spec:` WINS — the close-job hops to the
+ * spec's `issue:` and IGNORES the task's own `issue:` (the fanned-spec path is
+ * the authoritative one; a lone `issue:` on a `spec:`-bearing task is a
+ * contradiction that degrades to "use the spec" rather than crashing).
  *
  * Returns:
  * - `{via: 'spec', spec}` when a `spec:` is present (hop to the spec's `issue:`; the

package/src/prd-to-spec.ts

@@ -276,6 +276,14 @@ export interface ResyncedDoc {
 	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). */
@@ -293,40 +301,68 @@ export interface ResyncResult {
  * (`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.
+ * `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} = {},
+	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 = resolveProtocolDoc(name, undefined);
+		const source = resolveDoc(name);
 		const destAbs = join(protocolDir, name);
 		const destRel = relative(repoPath, destAbs);
-		let unchanged = false;
-		if (existsSync(source) && existsSync(destAbs)) {
-			unchanged =
-				readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
+		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;
 		}
-		if (!options.dryRun && existsSync(source)) {
+		// 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});
+		docs.push({name, dest: destRel, unchanged, skipped: false});
 	}
 
 	const versionAbs = join(protocolDir, 'VERSION');
 	const versionRel = relative(repoPath, versionAbs);
-	// Bump VERSION only when a doc actually CHANGED (or VERSION is absent). 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);
-	if (!options.dryRun && (anyDocChanged || !existsSync(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(

package/src/prompt.ts

@@ -7,7 +7,7 @@
  * The wrapper is NOT hardcoded here: it is read VERBATIM from the work-contract
  * (`skills/setup/protocol/CLAIM-PROTOCOL.md` → "The prompt handed to the work agent"),
  * so the emitted text can never silently diverge from the canonical contract.
- * We only substitute the per-task placeholders (`<slug>`, `<prd>`).
+ * We only substitute the per-task placeholders (`<slug>`, `<spec>`).
  *
  * The wrapper draws the git boundary IN-BAND — the spawned agent does NO git ops
  * on the repo (no commit/push, no moving `work/` files); the RUNNER owns every
@@ -137,7 +137,7 @@ export function resolveProtocolDoc(
 /**
  * Pull the canonical wrapper TEMPLATE out of CLAIM-PROTOCOL.md: the first fenced
  * code block following the "The prompt handed to the work agent" heading. The
- * returned text still contains the `<slug>` / `<prd>` placeholders verbatim — it
+ * returned text still contains the `<slug>` / `<spec>` placeholders verbatim — it
  * is the single source of truth for the wrapper.
  */
 export function extractCanonicalWrapperTemplate(protocol: string): string {
@@ -208,7 +208,7 @@ export function extractCanonicalWrapperTemplate(protocol: string): string {
  *
  * Pure string transform; runs AFTER `extractCanonicalWrapperTemplate` (a pure
  * verbatim extractor stays a pure verbatim extractor) and BEFORE the
- * `<slug>`/`<prd>` substitution.
+ * `<slug>`/`<spec>` substitution.
  */
 export function applyPromptGuidance(
 	template: string,
@@ -227,17 +227,17 @@ export function applyPromptGuidance(
 }
 
 /**
- * The constant wrapper, parameterised only by the task slug, its source prd
+ * The constant wrapper, parameterised only by the task slug, its source spec
  * slug, and (optionally) the resolved {@link PromptGuidance} nudges. Read
  * verbatim from the work-contract and substituted — never a divergent hardcoded
- * copy. `prd` may be `undefined` when the task has no `prd:` field. When
+ * copy. `spec` may be `undefined` when the task has no `spec:` field. When
  * `promptGuidance` is omitted (or every member resolves false) the output is
  * BYTE-IDENTICAL to today's wrapper (the ELSE-branch of every conditional is
  * the historic text).
  */
 export function wrapper(
 	slug: string,
-	prd: string | undefined,
+	spec: string | undefined,
 	options: {
 		protocolPath?: string;
 		cwd?: string;
@@ -252,7 +252,7 @@ export function wrapper(
 	const protocol = readFileSync(protocolPath, 'utf8');
 	const template = extractCanonicalWrapperTemplate(protocol);
 	const resolved = applyPromptGuidance(template, options.promptGuidance);
-	return resolved.replace(/<slug>/g, slug).replace(/<prd>/g, prd ?? '<prd>');
+	return resolved.replace(/<slug>/g, slug).replace(/<spec>/g, spec ?? '<spec>');
 }
 
 /**
@@ -427,7 +427,7 @@ export function buildContinueBlock(slug: string, ctx: ContinueContext): string {
  */
 export function buildAgentPrompt(
 	slug: string,
-	prd: string | undefined,
+	spec: string | undefined,
 	taskPrompt: string,
 	options: {
 		protocolPath?: string;
@@ -436,7 +436,7 @@ export function buildAgentPrompt(
 		promptGuidance?: {testFirst?: boolean};
 	} = {},
 ): string {
-	const head = wrapper(slug, prd, options);
+	const head = wrapper(slug, spec, options);
 	if (options.continueContext) {
 		const block = buildContinueBlock(slug, options.continueContext);
 		return `${head}\n\n${block}\n\n${taskPrompt}\n`;
@@ -459,8 +459,11 @@ export interface ResolvedTask {
 	path: string;
 	/** The folder the task was resolved from (in-progress wins over tasks-ready). */
 	folder: TaskFolder;
-	/** The task's source prd slug (frontmatter `prd:`), if any. */
-	prd: string | undefined;
+	/**
+	 * The task's source SPEC slug (frontmatter `spec:`, or the legacy `prd:` key
+	 * as read-only back-compat), if any.
+	 */
+	spec: string | undefined;
 	/** The extracted `## Prompt` body. */
 	taskPrompt: string;
 }
@@ -624,11 +627,11 @@ export function resolveTask(
 			);
 		}
 		const fm = parseFrontmatter(content);
-		// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-		// read the parent-spec pointer off the new `fm.spec` field (populated beside
-		// `fm.prd` by the expand task). The `ResolvedTask.prd` field name is left
-		// unchanged (a struct-field rename is out of this batch's scope).
-		return {slug, path, folder, prd: fm.spec, taskPrompt};
+		// Read the parent-spec pointer off `fm.spec` (populated from EITHER the
+		// canonical `spec:` key or the legacy `prd:` back-compat alias) into the
+		// `spec`-only `ResolvedTask` (spec
+		// `prd-to-spec-vocabulary-cutover-and-migration-command`).
+		return {slug, path, folder, spec: fm.spec, taskPrompt};
 	}
 	const searched = order.map((f) => `${workFolderRel(f)}/`).join(', ');
 	throw new PromptError(`no task '${slug}' found in ${searched}`);
@@ -722,8 +725,8 @@ export function resolvePromptGuidanceForItem(options: {
 }): PromptGuidance {
 	const taskFm = parseFrontmatter(options.taskContent);
 	let specFm: Frontmatter | undefined;
-	// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-	// read the parent-spec pointer off `fm.spec` (populated beside `fm.prd`).
+	// Read the parent-spec pointer off `fm.spec` (populated from the `spec:` key or
+	// the legacy `prd:` back-compat alias).
 	if (taskFm.spec !== undefined) {
 		const specPath = findSpecPath(options.cwd, taskFm.spec);
 		if (specPath !== undefined) {
@@ -752,7 +755,7 @@ export function renderPrompt(options: PromptOptions): string {
 		repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 		taskContent: readFileSync(task.path, 'utf8'),
 	});
-	return buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+	return buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 		protocolPath: options.protocolPath,
 		cwd: options.cwd,
 		promptGuidance: resolvedGuidance,

package/src/run.ts

@@ -808,7 +808,7 @@ async function runOneItem(
 				repoResolved: resolvePromptGuidance(config),
 				taskContent: readFileSync(task.path, 'utf8'),
 			});
-			prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+			prompt = buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 				cwd: tree.dir,
 				continueContext,
 				promptGuidance: itemGuidance,

package/src/tasking.ts

@@ -474,9 +474,8 @@ export async function performTask(
 	// final commit must scrub any agent writes there (an attempt to self-place into
 	// the pool, prd US #4) before `git add -A` would sweep them in.
 	const poolBefore = snapshotPool(cwd);
-	// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-	// read the parent-spec self-pointer off `prdFm.spec` (populated beside
-	// `prdFm.prd` by the expand task).
+	// Read the parent-spec self-pointer off `specFm.spec` (populated from the
+	// `spec:` key or the legacy `prd:` back-compat alias).
 	const prompt = buildTaskingSpec(slug, specFm.spec);
 	let agent: {ok: boolean; detail?: string};
 	try {