dorfl 0.1.1 → 0.2.0

package/src/install-ci-core.ts

@@ -1,5 +1,5 @@
 /**
- * The provider-agnostic CORE of the `install-ci` scaffolder (prd `runner-in-ci`,
+ * The provider-agnostic CORE of the `install-ci` scaffolder (spec `runner-in-ci`,
  * task `install-ci-core-and-github-adapter`; US #7/#10). `install-ci` is a
  * human-run, one-time SCAFFOLDER (mirrors whitesmith's `src/providers/github-ci.ts`):
  * it writes `.github/**` + a composite setup action + secrets so autonomous work
@@ -106,7 +106,7 @@ export interface CIConfigFile {
 	/** API key values keyed by env var name. Only present with `--include-secrets`. */
 	secrets?: Record<string, string>;
 	/**
-	 * The project-setup escape hatch (prd `install-ci-project-provisioning`,
+	 * The project-setup escape hatch (spec `install-ci-project-provisioning`,
 	 * task `install-ci-project-setup-hook`): a PROVIDER-NAMESPACED, OPAQUE,
 	 * NATIVE-SYNTAX pass-through map. The key is a provider id (today only
 	 * `github`); the value is the user's own project-toolchain snippet in that
@@ -152,7 +152,7 @@ export const DEFAULT_HARNESS: HarnessAdapter = 'pi';
  * draining steadily rather than stampeding the model-provider rate limit + the
  * arbiter CAS. Tunable via `install-ci --max-parallel <n>` / the config file.
  */
-export const DEFAULT_MAX_PARALLEL = 4;
+export const DEFAULT_MAX_PARALLEL = 2;
 
 /** The default install source: the published CLI via `npm install -g`. */
 export const DEFAULT_INSTALL_SOURCE: InstallSource = 'registry';
@@ -197,7 +197,7 @@ export interface CIProviderContext {
 	/**
 	 * OPTIONALLY report whether the configured credential has REPO-ADMIN scope
 	 * on the provider (→ can set branch protection / rulesets). Used by the
-	 * Tier-1 branch-protection step (prd `land-time-reverify-and-parallel-
+	 * Tier-1 branch-protection step (spec `land-time-reverify-and-parallel-
 	 * merge-ceiling`, Story 11) to pick `auto-configure` vs `print fallback`.
 	 * `true` ⇒ admin, `false` ⇒ explicitly NOT admin, `undefined` ⇒ unknown
 	 * (treated as non-admin: never silently attempt a call that would 403).
@@ -212,6 +212,26 @@ export interface CIProviderContext {
 	 * Throws on failure (caller catches + logs).
 	 */
 	setBranchProtection?(branch: string, spec: unknown): Promise<void>;
+	/**
+	 * OPTIONALLY report the repo's DEFAULT BRANCH name (GitHub:
+	 * `gh repo view --json defaultBranchRef`). Used by the Tier-1 branch-
+	 * protection step so the PUT and the printed `gh api` fallback both target
+	 * the repo's real default branch (a `master`-defaulted repo would 404 a
+	 * hardcoded `main`). Returns `undefined` when the lookup fails / is empty
+	 * (caller falls back to `main` and logs it). Absent on a provider that has
+	 * no default-branch concept.
+	 */
+	getDefaultBranch?(): Promise<string | undefined>;
+	/**
+	 * OPTIONALLY create/replace a branch RULESET (GitHub:
+	 * `POST /repos/{owner}/{repo}/rulesets`) carrying the deadlock-guard
+	 * `required_status_checks` rule with `do_not_enforce_on_create: true`. The
+	 * `ruleset` body (`BranchProtectionRuleset` in
+	 * `install-ci-branch-protection.ts`) is typed as `unknown` here to keep this
+	 * core seam free of the branch-protection module's import. Absent on a non-
+	 * GitHub provider. Throws on failure (caller catches + logs).
+	 */
+	setBranchRuleset?(ruleset: unknown): Promise<void>;
 	/**
 	 * OPTIONALLY render the user's project-setup payload (the value of
 	 * {@link CIConfigFile.projectSetup}[providerId]) to the NATIVE-SYNTAX
@@ -787,7 +807,7 @@ ${indent(modelsJsonStr, 8)}
 	if (config.installSource === 'workspace') {
 		installSteps = `\
     - name: Setup pnpm
-      uses: pnpm/action-setup@v4
+      uses: pnpm/action-setup@v5
 
     - name: Add pnpm global bin to PATH
       shell: bash
@@ -809,7 +829,7 @@ ${indent(modelsJsonStr, 8)}
 	}
 
 	// PREFER-LOCAL RESOLVER (task install-ci-prefer-project-local-dorfl,
-	// PRD install-ci-project-provisioning axis C1+C3): emit a `dorfl` SHIM
+	// SPEC install-ci-project-provisioning axis C1+C3): emit a `dorfl` SHIM
 	// that resolves a project-local `node_modules/.bin/dorfl` FIRST (the repo's
 	// devDep pin, populated by the project-setup hook's `pnpm install` — C3),
 	// and falls back to the global bootstrap dorfl this composite action just
@@ -903,9 +923,16 @@ runs:
   using: composite
   steps:
 ${projectSetupBlock}    - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v5
       with:
         node-version: '22'
+        # setup-node@v5 auto-enables package-manager caching, which probes the
+        # project package manager DURING its own run when a lockfile is present,
+        # before that manager is on PATH, so the probe crashes ("Unable to
+        # locate executable file"). dorfl provisions ONLY its own runtime and
+        # leaves the project package-manager cache to the project (toolchain
+        # boundary), so disable it explicitly.
+        package-manager-cache: false
 
     - name: Configure git identity
       shell: bash

package/src/install-ci-github.ts

@@ -1,5 +1,5 @@
 /**
- * The thin GitHub adapter for `install-ci` (prd `runner-in-ci`, task
+ * The thin GitHub adapter for `install-ci` (spec `runner-in-ci`, task
  * `install-ci-core-and-github-adapter`). It plugs into the provider-agnostic
  * {@link CIProviderContext} seam from `install-ci-core.ts`: the core owns the
  * wizard / config / `models.json` / `--export-config` / `--fake` / secret
@@ -239,6 +239,66 @@ export class GitHubCIContext implements CIProviderContext {
 		return undefined;
 	}
 
+	/**
+	 * Detect the repo's DEFAULT BRANCH via
+	 * `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. Returns
+	 * `undefined` when `gh` is unavailable / the repo is unknown / the call fails
+	 * / the name is empty — the caller falls back to `main` (and logs it) so a
+	 * `master`-defaulted repo is never silently protected on a hardcoded `main`.
+	 */
+	async getDefaultBranch(): Promise<string | undefined> {
+		if (!this.repo) {
+			return undefined;
+		}
+		const result = this.runGh([
+			'repo',
+			'view',
+			'--json',
+			'defaultBranchRef',
+			'--jq',
+			'.defaultBranchRef.name',
+		]);
+		if (result === undefined || result.status !== 0) {
+			return undefined;
+		}
+		const name = result.stdout.trim();
+		return name === '' ? undefined : name;
+	}
+
+	/**
+	 * Create the deadlock-guard RULESET via
+	 * `POST /repos/{owner}/{repo}/rulesets`. The `ruleset` body is JSON-piped on
+	 * stdin (`gh api --input -`) so the nested rule shape carries cleanly. Throws
+	 * on a non-zero exit; caller logs + falls back. See the module header of
+	 * `install-ci-branch-protection.ts` for why the required-check guard uses a
+	 * ruleset while base protection stays a classic PUT.
+	 */
+	async setBranchRuleset(ruleset: unknown): Promise<void> {
+		if (!this.repo) {
+			throw new Error('cannot create branch ruleset: repo unknown');
+		}
+		const args = [
+			'api',
+			'-X',
+			'POST',
+			'-H',
+			'Accept: application/vnd.github+json',
+			`repos/${this.repo}/rulesets`,
+			'--input',
+			'-',
+		];
+		const result = this.runGhWithInput(args, JSON.stringify(ruleset));
+		if (result === undefined) {
+			throw new Error('gh not available; cannot create branch ruleset');
+		}
+		if (result.status !== 0) {
+			throw new Error(
+				`gh api POST repos/${this.repo}/rulesets failed: ` +
+					(result.stderr.trim() || 'unknown error'),
+			);
+		}
+	}
+
 	/**
 	 * Configure Tier-1 branch protection via
 	 * `PUT /repos/{owner}/{repo}/branches/{branch}/protection`. The `spec` body
@@ -322,10 +382,16 @@ export class MemoryCIProviderContext implements CIProviderContext {
 	readonly repoSettings = new Map<string, boolean>();
 	/** Branch-protection spec recorded in memory (branch → spec). */
 	readonly branchProtections = new Map<string, unknown>();
+	/** Deadlock-guard rulesets recorded in memory (append-only). */
+	readonly rulesets: unknown[] = [];
 	/** What `getRepoAdminScope()` should return (tests configure). */
 	private readonly adminScope: boolean | undefined;
+	/** What `getDefaultBranch()` should return (tests configure). */
+	private readonly defaultBranch: string | undefined;
 	/** Whether `setBranchProtection` should throw (tests configure). */
 	private readonly branchProtectionError: string | undefined;
+	/** Whether `setBranchRuleset` should throw (tests configure). */
+	private readonly branchRulesetError: string | undefined;
 
 	constructor(options: {
 		workDir: string;
@@ -333,8 +399,15 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		ghAvailable?: boolean;
 		/** Fixture admin-scope verdict; `undefined` ⇒ unknown. */
 		adminScope?: boolean;
+		/**
+		 * Fixture default-branch name; `undefined` ⇒ lookup "fails" so the caller
+		 * exercises its `main` fallback (models a `gh` that could not resolve it).
+		 */
+		defaultBranch?: string;
 		/** When set, `setBranchProtection` throws with this message (failure path). */
 		branchProtectionError?: string;
+		/** When set, `setBranchRuleset` throws with this message (failure path). */
+		branchRulesetError?: string;
 		/**
 		 * The provider id this stub claims (default `github`). Tests of the
 		 * project-setup seam may override to assert the orchestrator's
@@ -347,7 +420,9 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		this.repo = options.repo;
 		this.ghAvailable = options.ghAvailable ?? false;
 		this.adminScope = options.adminScope;
+		this.defaultBranch = options.defaultBranch;
 		this.branchProtectionError = options.branchProtectionError;
+		this.branchRulesetError = options.branchRulesetError;
 		this.providerId = options.providerId ?? GITHUB_PROVIDER_ID;
 	}
 
@@ -367,10 +442,21 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		return this.adminScope;
 	}
 
+	async getDefaultBranch(): Promise<string | undefined> {
+		return this.defaultBranch;
+	}
+
 	async setBranchProtection(branch: string, spec: unknown): Promise<void> {
 		if (this.branchProtectionError !== undefined) {
 			throw new Error(this.branchProtectionError);
 		}
 		this.branchProtections.set(branch, spec);
 	}
+
+	async setBranchRuleset(ruleset: unknown): Promise<void> {
+		if (this.branchRulesetError !== undefined) {
+			throw new Error(this.branchRulesetError);
+		}
+		this.rulesets.push(ruleset);
+	}
 }

package/src/install-ci.ts

@@ -1,5 +1,5 @@
 /**
- * The `install-ci` orchestrator (prd `runner-in-ci`, task
+ * The `install-ci` orchestrator (spec `runner-in-ci`, task
  * `install-ci-core-and-github-adapter`): ties the provider-agnostic core
  * (`install-ci-core.ts`) to a CI-provider adapter (the first being GitHub,
  * `install-ci-github.ts`) through the {@link CIProviderContext} seam. It drives
@@ -252,7 +252,7 @@ export async function installCI(
 	}
 
 	// 5. Assemble + write the artifacts (composite setup action + auth). The
-	// project-setup escape hatch (prd `install-ci-project-provisioning`) lives
+	// project-setup escape hatch (spec `install-ci-project-provisioning`) lives
 	// on `config.projectSetup` as a PROVIDER-NAMESPACED, OPAQUE map; we look up
 	// THIS provider's payload via the seam (`ctx.providerId`) and ask the
 	// adapter to render it to the FIRST-steps fragment (`ctx.renderProjectSetup`).
@@ -275,7 +275,7 @@ export async function installCI(
 		log(`  wrote ${path}`);
 	}
 
-	// 5b. Tier-1 GitHub branch protection (prd land-time-reverify-and-parallel-
+	// 5b. Tier-1 GitHub branch protection (spec land-time-reverify-and-parallel-
 	// merge-ceiling, Story 11). Auto-configures when the credential is admin-
 	// scoped (one `gh api` PUT on the protection endpoint, required check
 	// `verify` + strict: true); prints the exact ready-to-run `gh api` command
@@ -313,7 +313,7 @@ export async function installCI(
 			"      DORFL_AUTO_TASK: 'true'",
 	);
 	// Project-toolchain boundary (task install-ci-document-toolchain-boundary,
-	// PRD install-ci-project-provisioning axis (A)). dorfl declares
+	// SPEC install-ci-project-provisioning axis (A)). dorfl declares
 	// engines.node '>=18' and the generated composite action pins Node 22 only
 	// for dorfl's own runtime — it does NOT provision the project's toolchain.
 	// State that boundary explicitly so a maintainer whose project pins a

package/src/install-skills.ts

@@ -0,0 +1,166 @@
+/**
+ * The dorfl-side wrapper around the VENDORED `incur/agents.ts` (MIT — see
+ * `./vendor/incur/`, and the ADR `docs/adr/skill-install-vendors-incur-agents-map.md`).
+ * The vendored file provides the ~22-harness destination map, `detect()`, and
+ * `install(sourceDir, options)` that copies each skill into the canonical
+ * `~/.agents/skills/` and symlinks non-universal harnesses. This module is the
+ * dorfl-authored code AROUND it: it resolves the packaged-skills SOURCE dir
+ * and drives the vendored `install()` — nothing more. Keep the vendored file
+ * untouched (byte-close to upstream) so future incur updates stay a mechanical
+ * re-copy.
+ *
+ * ## Decisions (in-scope, non-obvious)
+ *
+ * - **Sibling script over merged.** The build-time packaging lives in
+ *   `scripts/vendor-skills.mjs`, a SIBLING of the existing `vendor-protocol.mjs`
+ *   rather than an appended block on it. The two scripts copy DIFFERENT concept
+ *   sets (contract docs vs. hand-authored skills) into different dest subtrees;
+ *   each has its own set that evolves independently. See the header of
+ *   `vendor-skills.mjs` for the rationale (mirrors the wording here).
+ * - **Vendored file location.** `src/vendor/incur/agents.ts` (co-located with
+ *   its MIT `LICENSE` + a `README.md` provenance note). Under `src/` so `tsc`
+ *   compiles it into `dist/vendor/incur/agents.js`; under `vendor/incur/` so
+ *   the upstream origin is CLEAR from the path, and a future re-copy is a
+ *   drop-in overwrite. All dorfl wrapper code lives OUTSIDE that directory.
+ * - **Resolver home.** {@link resolveSkillsSourceDir} lives IN this module
+ *   (not in `prompt.ts` next to `resolveProtocolDoc`) because "the packaged
+ *   skills source" is a concept OWNED by skill-install; `resolveProtocolDoc`
+ *   is owned by the runner's prompt-assembly. Same SHAPE, different concept —
+ *   duplicating the small resolver body keeps the ownership boundary clean.
+ */
+
+import {existsSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {install, type Agent} from './vendor/incur/agents.js';
+
+/**
+ * Locate the SOURCE directory of the vendored skills the installer copies
+ * from. Resolution order, highest authority first:
+ *
+ *   1. `override` — explicit, for tests / unusual layouts (short-circuits).
+ *   2. `dist/skills/` — a copy VENDORED inside this package (by the
+ *      `vendor-skills` build step). The published-CLI primary: an installed
+ *      CLI has no sibling monorepo-root `skills/` tree.
+ *   3. the legacy monorepo-relative `skills/` walk — DEV-only, kept LAST (it
+ *      only resolves inside this dev monorepo; an installed CLI's walks escape
+ *      into the consumer's filesystem \u2192 nothing there, which is why it cannot
+ *      be the primary source).
+ *
+ * Mirrors the shape of {@link import('./prompt.js').resolveProtocolDoc} — the
+ * prefer-`dist/`-then-dev-walk order. Returns the first existing candidate;
+ * when nothing exists, returns the first candidate (the caller then hits a
+ * clean ENOENT rather than a silent no-op).
+ */
+export function resolveSkillsSourceDir(override?: string): string {
+	if (override) {
+		return override;
+	}
+	const here = dirname(fileURLToPath(import.meta.url));
+	// here = .../packages/dorfl/{src,dist}.
+	const candidates: string[] = [
+		// 2. Package-vendored copy (published-CLI primary). From `src/` (tsx)
+		//    `dist/` is a sibling; from `dist/` it is the dir itself.
+		resolve(here, '..', 'dist', 'skills'),
+		resolve(here, 'skills'),
+		// 3. Legacy monorepo-root walk \u2014 DEV-only, LAST.
+		resolve(here, '..', '..', '..', 'skills'),
+		resolve(here, '..', '..', '..', '..', 'skills'),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return candidates[0];
+}
+
+/**
+ * Options threaded through {@link installSkills} to the vendored `install()`.
+ * The shape mirrors incur's `install.Options` verbatim, plus a `sourceDir`
+ * override for the resolver seam. Everything is optional; a bare call
+ * `installSkills()` performs the "install every packaged skill, globally,
+ * into every detected harness" default.
+ */
+export interface InstallSkillsOptions {
+	/**
+	 * Override the resolved packaged-skills source dir. Tests pin this to a
+	 * scratch dir with fake skill folders; production callers omit it and take
+	 * whatever {@link resolveSkillsSourceDir} returns.
+	 */
+	sourceDir?: string;
+	/**
+	 * `false` \u21d2 project-local placement (canonical base is `<cwd>/.agents/skills/`,
+	 * and non-universal harnesses use their PROJECT-relative dirs). Default
+	 * `true` (or omitted) \u21d2 global placement under `~/.agents/skills/`.
+	 */
+	global?: boolean;
+	/**
+	 * Working directory for project-local installs. Ignored when `global` is not
+	 * `false`. Defaults (in the vendored file) to `process.cwd()`.
+	 */
+	cwd?: string;
+	/**
+	 * Override the detected harnesses. Tests use this to force a deterministic
+	 * set; production callers omit it and let the vendored `detect()` pick.
+	 */
+	agents?: Agent[];
+}
+
+/**
+ * The per-harness install detail returned by the vendored `install()` (for
+ * NON-UNIVERSAL harnesses only \u2014 universal harnesses read from the canonical
+ * `.agents/skills/` directly and need no per-harness entry).
+ */
+export interface InstalledAgent {
+	/** Harness display name (e.g. `'Claude Code'`, `'Windsurf'`). */
+	agent: string;
+	/** Absolute path the skill was placed at for this harness. */
+	path: string;
+	/** How the placement was materialised. Symlink is the norm; copy is the
+	 *  Windows/no-permission fallback. */
+	mode: 'symlink' | 'copy';
+}
+
+/** The report {@link installSkills} returns to its CLI caller. */
+export interface InstallSkillsResult {
+	/**
+	 * The SOURCE directory the vendored `install()` was driven from (the value
+	 * {@link resolveSkillsSourceDir} chose). Included so `dorfl skills add`
+	 * can print WHERE the skills were read from, and tests can assert the
+	 * resolver picked what they expected.
+	 */
+	sourceDir: string;
+	/** Canonical install paths (one per skill directory copied). */
+	paths: string[];
+	/** Per-harness placements for non-universal harnesses. */
+	agents: InstalledAgent[];
+}
+
+/**
+ * Resolve the packaged-skills source, drive the vendored `install()`, return
+ * the source + canonical paths + per-harness report. Global by default; pass
+ * `global: false` for project-local placement. Tests pin `sourceDir`/`agents`
+ * to keep the run hermetic; production callers pass nothing.
+ *
+ * The vendored `install()` reads `os.homedir()` (etc.) at MODULE LOAD, so
+ * shared-write isolation for `global: true` (the default) has to happen BEFORE
+ * this module is loaded (e.g. by pointing `HOME` at a scratch dir). Tests use
+ * `global: false` + a scratch `cwd` for the common path (no env dance needed);
+ * see `test/install-skills.test.ts`.
+ */
+export function installSkills(
+	options: InstallSkillsOptions = {},
+): InstallSkillsResult {
+	const sourceDir = resolveSkillsSourceDir(options.sourceDir);
+	const result = install(sourceDir, {
+		global: options.global,
+		cwd: options.cwd,
+		agents: options.agents,
+	});
+	return {
+		sourceDir,
+		paths: result.paths,
+		agents: result.agents,
+	};
+}

package/src/intake-event.ts

@@ -1,14 +1,14 @@
 /**
- * **`intake`'s PURE event-classification** (task `intake-event-classification`, prd
+ * **`intake`'s PURE event-classification** (task `intake-event-classification`, spec
  * `issue-intake` US #2 — the resume-on-thread-change behaviour).
  *
  * `intake` is a CONVERSATION on an issue thread: a run may ASK a clarifying question
- * and STOP, expecting a LATER run to resume from the updated thread (prd "Loop
+ * and STOP, expecting a LATER run to resume from the updated thread (spec "Loop
  * closure" / the decision table's ASK row). This module is the PURE CONTROL-PATH
  * classifier the re-run depends on: given an issue EVENT, it decides whether `intake`
  * should RE-EVALUATE the whole thread or IGNORE the event.
  *
- * THE CANONICAL RULE (from prd `issue-intake`, "The engine shape"): *"The loop
+ * THE CANONICAL RULE (from spec `issue-intake`, "The engine shape"): *"The loop
  * re-runs on a new comment OR an issue-body edit (re-evaluate the whole thread); a
  * buried prior-comment edit is IGNORED."*
  *
@@ -23,7 +23,7 @@
  * distinction the rule turns on is "a NEW turn vs an edit of a BURIED prior turn",
  * NOT "edit vs reply".
  *
- * SCOPE FENCE (prd "Scope: the engine only"): this is ONLY the pure classifier. It is
+ * SCOPE FENCE (spec "Scope: the engine only"): this is ONLY the pure classifier. It is
  * NOT CI's TRIGGER POLICY (command/every-issue, maintainer/anyone) — that is
  * `runner-in-ci`'s. CI's trigger LATER CONSULTS this classifier, but the policy of
  * WHO/WHAT may trigger lives in CI, not here. This module touches no seam, no git, no
@@ -69,10 +69,10 @@ export interface IntakeEvent {
 
 /**
  * Classify an issue EVENT into the CONTROL-PATH decision: RE-EVALUATE the whole
- * thread, or IGNORE the event. The PURE realisation of the prd's canonical rule
+ * thread, or IGNORE the event. The PURE realisation of the spec's canonical rule
  * (no seam, no git, no `gh`).
  *
- * The table (prd `issue-intake` US #2):
+ * The table (spec `issue-intake` US #2):
  *
  * | event kind              | decision      | why                                          |
  * | ----------------------- | ------------- | -------------------------------------------- |

package/src/intake-marker.ts

@@ -2,7 +2,7 @@ import {brand} from './brand.js';
 import type {IssueComment} from './issue-provider.js';
 
 /**
- * **The intake MARKER** (task `intake-self-awareness-resumption-tracking`, prd
+ * **The intake MARKER** (task `intake-self-awareness-resumption-tracking`, spec
  * `issue-intake` US #2/#10): the ONE primitive the deterministic pre-decision
  * TRIAGE GATE is built on. A machine-readable HIDDEN HTML comment intake stamps on
  * EVERY comment it posts, recording a neutral FACT about what intake did:
@@ -26,7 +26,7 @@ import type {IssueComment} from './issue-provider.js';
  *   TERMINAL is the TRIAGE's interpretation, NEVER data in the marker (no `terminal`
  *   field): if a kind's terminal-ness ever changes that is a triage change and old
  *   markers stay valid.
- * - **`slug`** \u2014 present only on `kind=created` (which task/prd intake produced).
+ * - **`slug`** \u2014 present only on `kind=created` (which task/spec intake produced).
  * - **`seen=<id>,\u2026`** \u2014 the per-run DELTA of HUMAN comment ids intake READ this run
  *   (EXCLUDING intake's own marker-comments AND any human id already in a prior
  *   marker's `seen=`). Ids, not a count, because a count cannot distinguish "a new
@@ -47,7 +47,7 @@ export interface IntakeMarker {
 	kind: IntakeMarkerKind;
 	/** The HUMAN comment ids intake READ this run (the per-run delta; may be empty). */
 	seen: string[];
-	/** The created task/prd slug \u2014 present only on `kind=created`. */
+	/** The created task/spec slug \u2014 present only on `kind=created`. */
 	slug?: string;
 }
 

package/src/intake-triage.ts

@@ -6,7 +6,7 @@ import {
 } from './intake-marker.js';
 
 /**
- * **The intake TRIAGE GATE** (task `intake-self-awareness-resumption-tracking`, prd
+ * **The intake TRIAGE GATE** (task `intake-self-awareness-resumption-tracking`, spec
  * `issue-intake` US #2/#10): a DETERMINISTIC pre-decision gate that runs UNDER the
  * processing lock, BEFORE the decision prompt, deciding whether intake should run
  * the prompt at all. Built ENTIRELY on the thread MARKER (no sidecar, no cursor, no
@@ -55,7 +55,7 @@ export type IntakeTriageDecision =
 
 /**
  * Run the TRIAGE over the issue's full comment thread (oldest-first, as
- * `listComments` returns it). The canonical branches (prd `issue-intake`):
+ * `listComments` returns it). The canonical branches (spec `issue-intake`):
  *
  * 1. **Last comment is INTAKE's** (carries a marker). Build `seenSet` = the UNION of
  *    every intake marker's `seen=` id-list, then:

package/src/intake-trigger-template.ts

@@ -1,7 +1,7 @@
 /**
- * The `install-ci` ISSUE-INTAKE capability (prd `runner-in-ci`, task
+ * The `install-ci` ISSUE-INTAKE capability (spec `runner-in-ci`, task
  * `install-ci-intake-trigger-and-review-surface`; capability D: consider incoming
- * issues → task/prd, AND insertion point E: surface the review verdict back into
+ * issues → task/spec, AND insertion point E: surface the review verdict back into
  * the issue thread). This module GENERATES the one fixed intake workflow file and
  * STRUCTURALLY VALIDATES it, mirroring the snapshot-assertion style of
  * `advance-lifecycle-template.ts` / `advance-ci-template.ts` (the package depends on
@@ -10,13 +10,13 @@
  * ({@link deriveIntakeFlags}) — CI's merge-vs-propose POLICY, the load-bearing
  * testable logic the workflow encodes at runtime.
  *
- * SCOPE FENCE (prd Out-of-Scope): the issue→artifact TRANSFORM engine is
+ * SCOPE FENCE (spec Out-of-Scope): the issue→artifact TRANSFORM engine is
  * `issue-intake`'s (`intake <N>` + its four-outcome dispatch + the per-outcome
  * KNOBS + the lone-task review that posts to the issue thread). CI only
  * WIRES/SCHEDULES/INVOKES it and owns the merge-vs-propose POLICY + the delivery
  * surface. This module emits NO transform; it emits the WORKFLOW that calls it.
  *
- * The discipline (prd capability-D row + the merge-vs-propose POLICY + the two
+ * The discipline (spec capability-D row + the merge-vs-propose POLICY + the two
  * RESOLVED design decisions in the task):
  *
  *   - TRIGGERS: `issues` opened, `issue_comment` created, and a label
@@ -36,7 +36,7 @@
  *     everywhere" path is a LOUD, NON-DEFAULT opt-in — the default is conservative
  *     (propose / human-in-the-loop).
  *   - INSERTION POINT E (the issue-thread review surface): the review verdict over
- *     intake's generated prds/tasks is surfaced into the ISSUE THREAD via the
+ *     intake's generated specs/tasks is surfaced into the ISSUE THREAD via the
  *     `IssueProvider.postIssueComment` seam (issue thread, by NUMBER — NOT the PR
  *     seam `postPRComment`, which is keyed by url). This is REUSED, not new:
  *     `intake <N>` already runs the lone-task review/edit loop and posts its
@@ -65,7 +65,7 @@ export const INTAKE_TRIGGER_CAPABILITY_ID = 'intake';
 
 /** The wizard-facing label for the issue-intake capability. */
 export const INTAKE_TRIGGER_CAPABILITY_LABEL =
-	'Consider incoming issues → task/prd + surface the review verdict into the issue thread (the intake trigger: issues / issue_comment / label)';
+	'Consider incoming issues → task/spec + surface the review verdict into the issue thread (the intake trigger: issues / issue_comment / label)';
 
 /** The repo-relative path (under the output base) of the emitted workflow. */
 export const INTAKE_TRIGGER_WORKFLOW_PATH = 'workflows/intake.yml';
@@ -106,7 +106,7 @@ export interface IntakeIntegrationFlags {
 	task: 'merge' | 'propose';
 	/**
 	 * The ORIGIN-TRUST verdict CI passes to `intake <N>` via `--origin-trust`
-	 * (task `untrusted-origin-forces-build-propose`) so the emitted prd/task is
+	 * (task `untrusted-origin-forces-build-propose`) so the emitted spec/task is
 	 * STAMPED with how it was born. Derived from the SAME `author_association` case
 	 * as the integration flags (it IS `authorTrusted` collapsed to the wire value),
 	 * so the stamp and the integration mode CANNOT desync. `intake.ts` writes it
@@ -134,7 +134,7 @@ export interface IntakeGateState {
 
 /**
  * DERIVE the per-outcome merge-vs-propose flags from the gate state COMPOSED with
- * author-trust — CI's merge-vs-propose POLICY (prd "merge-vs-propose POLICY" +
+ * author-trust — CI's merge-vs-propose POLICY (spec "merge-vs-propose POLICY" +
  * "Composed with AUTHOR-TRUST"; task Decision 1). This is the load-bearing pure
  * logic the workflow encodes at runtime (it reads `author_association` off the
  * event payload and sets the flags accordingly):
@@ -167,9 +167,9 @@ export function deriveIntakeFlags(options: {
 	// ORIGIN-TRUST stamp (task `untrusted-origin-forces-build-propose`): the SAME
 	// author-trust verdict, collapsed to the wire value `intake` stamps onto the
 	// emitted artifact. Derived HERE — next to the integration flags, off the SAME
-	// `authorTrusted` input — so the stamp and the task/prd modes cannot desync.
+	// `authorTrusted` input — so the stamp and the task/spec modes cannot desync.
 	// It is NOT a re-resolution of trust (CI already resolved it); it is the verdict
-	// being CARRIED so it survives the prd/task merge boundary (the becomes-code
+	// being CARRIED so it survives the spec/task merge boundary (the becomes-code
 	// checkpoint is not laundered when the file lands on main).
 	const originTrust: 'trusted' | 'untrusted' = authorTrusted
 		? 'trusted'
@@ -216,12 +216,12 @@ export function generateIntakeWorkflow(config: ResolvedCIConfig): string {
 	const setupWith = providerSecretsWithBlock(config);
 	return `\
 # dorfl — the ISSUE INTAKE trigger in CI (capability D: consider incoming
-# issues → task/prd, PLUS insertion point E: surface the review verdict into the
-# issue thread, prd runner-in-ci). EMITTED by \`dorfl install-ci\`; the human
+# issues → task/spec, PLUS insertion point E: surface the review verdict into the
+# issue thread, spec runner-in-ci). EMITTED by \`dorfl install-ci\`; the human
 # commits it. DO NOT hand-edit a copy — re-run install-ci to upgrade the shell.
 #
 # WHAT IT DOES — \`dorfl intake <N>\` reads issue #N + its comment thread,
-# runs a prompt→verdict decision (ask / task / PRD / bounce), and dispatches it.
+# runs a prompt→verdict decision (ask / task / SPEC / bounce), and dispatches it.
 # CI owns ONLY the trigger + the merge-vs-propose POLICY + the delivery surface;
 # the TRANSFORM is the engine's (the Out-of-Scope fence — CI re-implements none of
 # it). The lone-task review/edit loop \`intake\` already runs ALSO surfaces its
@@ -307,7 +307,7 @@ env:
   # permissive merge side; author-trust then forces propose for a task from an
   # untrusted author.
   DORFL_AUTO_BUILD: 'false' # gate: will an agent auto-build the emitted task next?
-  DORFL_AUTO_TASK: 'false' # gate: will an agent auto-task the emitted prd next?
+  DORFL_AUTO_TASK: 'false' # gate: will an agent auto-task the emitted spec next?
 
 jobs:
   intake:
@@ -317,7 +317,7 @@ jobs:
     if: \${{ github.event.issue.number && !github.event.issue.pull_request }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -365,8 +365,8 @@ jobs:
 
           # ORIGIN-TRUST stamp (task untrusted-origin-forces-build-propose):
           # derived from the SAME \${trusted} case above (one author-trust read,
-          # two consumers — the task/prd modes AND the stamp — so they cannot
-          # desync). \`intake\` STAMPS this onto the emitted prd/task frontmatter
+          # two consumers — the task/spec modes AND the stamp — so they cannot
+          # desync). \`intake\` STAMPS this onto the emitted spec/task frontmatter
           # (origin: issue + originTrust: <value>); it does NOT re-resolve trust
           # (that is CI's policy, passed IN). The stamp SURVIVES the merge boundary
           # so a later auto-task/auto-build of an untrusted-origin artifact still
@@ -519,7 +519,7 @@ export function validateIntakeWorkflow(text: string): IntakeTriggerValidation {
 	), 'the policy derivation must be able to emit `--propose-spec` (autoTask on).');
 	// ORIGIN-TRUST stamp (task untrusted-origin-forces-build-propose): the shell
 	// must derive `--origin-trust <trusted|untrusted>` from the SAME author-trust
-	// case it uses for the task/PRD modes, and pass it to `intake` so the emitted
+	// case it uses for the task/SPEC modes, and pass it to `intake` so the emitted
 	// artifact is stamped (the stamp + the modes cannot desync).
 	require('derives-origin-trust-untrusted', /--origin-trust=untrusted\b/.test(
 		operative,