dorfl 0.1.1 → 0.1.2

package/src/install-ci-capabilities/example-noop.ts

@@ -1,5 +1,5 @@
 /**
- * REFERENCE capability registration (PRD `runner-in-ci`, task
+ * REFERENCE capability registration (SPEC `runner-in-ci`, task
  * `install-ci-core-and-github-adapter`). This file proves the capability-emitter
  * REGISTRY seam works as a DIRECTORY of self-registering modules: a new capability
  * is a NEW file in `install-ci-capabilities/` that calls {@link registerCapability}

package/src/install-ci-capabilities/intake.ts

@@ -1,7 +1,7 @@
 /**
- * The ISSUE-INTAKE capability emitter (PRD `runner-in-ci`, task
+ * The ISSUE-INTAKE capability emitter (SPEC `runner-in-ci`, task
  * `install-ci-intake-trigger-and-review-surface`; capability D: consider incoming
- * issues → task/PRD, PLUS insertion point E: surface the review verdict into the
+ * issues → task/SPEC, PLUS insertion point E: surface the review verdict into the
  * issue thread). A SELF-REGISTERING module: it calls {@link registerCapability} at
  * import time, so {@link loadCapabilityRegistry} picks it up WITHOUT any edit to a
  * shared central list/switch (the file-orthogonality contract — this task and the

package/src/install-ci-capabilities/verify.ts

@@ -1,5 +1,5 @@
 /**
- * The VERIFY capability emitter (prd
+ * The VERIFY capability emitter (spec
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `install-ci-tier1-branch-protection`; Story 11 — Tier-1 GitHub ceiling).
  * A SELF-REGISTERING module: it calls {@link registerCapability} at import

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
@@ -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).
@@ -809,7 +809,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

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

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/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:
@@ -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,