dorfl 0.1.0 → 0.1.2

package/dist/cli.js

@@ -218,10 +218,10 @@ function buildRegistrySetAdvanceTick(options) {
         lifecycleGates: {
             triage: config.observationTriage !== 'off',
             surface: config.surfaceBlockers,
-            // `surfaceStaging` widens the SURFACE candidate set into STAGING (prd
+            // `surfaceStaging` widens the SURFACE candidate set into STAGING (spec
             // `staging-surface-and-apply-promote-safety` F2). Default `true` — a
-            // tasked `needsAnswers` task in `tasks/backlog/` (or prd in
-            // `prds/proposed/`) surfaces its questions BEFORE promotion. BUILD/claim
+            // tasked `needsAnswers` task in `tasks/backlog/` (or spec in
+            // `specs/proposed/`) surfaces its questions BEFORE promotion. BUILD/claim
             // stays pool-only either way.
             surfaceStaging: config.surfaceStaging,
         },
@@ -249,10 +249,10 @@ function buildRegistrySetAdvanceTick(options) {
                 identity: config.identity,
                 autoTask: config.autoTask,
                 integration: config.integration,
-                // The per-TRANSITION TASKING override: the `do prd:` tasking path threads
+                // The per-TRANSITION TASKING override: the `do spec:` tasking path threads
                 // `taskingIntegration ?? integration`; the build path stays on `integration`.
                 taskingIntegration: config.taskingIntegration,
-                // The TASK-PLACEMENT configured default (`do prd:` tasking output:
+                // The TASK-PLACEMENT configured default (`do spec:` tasking output:
                 // `pre-backlog` staged vs `ready` pool). No operator flag on this
                 // registry-driven advance context, so only the configured default rung is
                 // threaded (the resolver still layers untrusted-origin force + built-in floor).
@@ -261,7 +261,7 @@ function buildRegistrySetAdvanceTick(options) {
                 verify: config.verify,
                 // Single-job build path: gate the REBASED tip (the default) unconditionally.
                 freshWorktreeGate: config.freshWorktreeGate,
-                // Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+                // Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
                 // parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — resolved per-repo
                 // and threaded so the registry-driven advance path's `do` inherits it.
                 mergeRetries: config.mergeRetries,
@@ -300,7 +300,7 @@ function buildRegistrySetAdvanceTick(options) {
                 triageGate: harnessTriageGate({ harness, agentCmd: config.agentCmd }),
                 triageModel: config.model,
                 // The ANSWERED-MERGE LAND DISPATCH context (task
-                // `apply-rung-merge-disposition`, prd `land-time-reverify-and-parallel-
+                // `apply-rung-merge-disposition`, spec `land-time-reverify-and-parallel-
                 // merge-ceiling`): the dispatcher cuts a per-job worktree via
                 // `workspace.ts` `createJob` off the hub mirror (so we thread the resolved
                 // `workspacesDir` + the real arbiter URL — the per-mirror tree-less
@@ -396,7 +396,7 @@ function runFlagOverrides(flags, command) {
     // fleet conditional lives in `runOnce`, not in this flag mapping).
     Object.assign(overrides, freshWorktreeGateFlagOverrides(flags));
     // `--merge-retries <n>` rides the SAME chain: the cross-job merge-serialiser
-    // CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 /
+    // CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 /
     // Applied Answer q1 (a)). The `run` fleet inherits the resolved cap through
     // the converged `performIntegration` core (config.mergeRetries threads into
     // the merge loop, replacing the bare `DEFAULT_MERGE_RETRIES` fallback).
@@ -409,7 +409,7 @@ function formatItemLine(item) {
 }
 /**
  * Resolve the EXPLICIT operator placement override from `--tasks-land-in <where>`
- * (the top of the `do prd:` tasking-placement precedence — task
+ * (the top of the `do spec:` tasking-placement precedence — task
  * `runner-deterministic-slice-placement-policy-and-precedence`). Mirrors the
  * `flagMode === 'merge'` ⇒ `explicitMerge: true` shape: it contributes
  * `explicitTasksLandIn` ONLY when the operator actually typed the flag, so an
@@ -469,9 +469,15 @@ function printPrdToSpecReport(result) {
         ? '=== prd-to-spec (DRY RUN — nothing written) ==='
         : '=== prd-to-spec ===');
     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) {
@@ -492,7 +498,7 @@ function printPrdToSpecReport(result) {
         return;
     }
     if (result.leaks.length === 0) {
-        console.log('Leak scan: GREEN (no surviving prd data ref).');
+        console.log('Leak scan: GREEN (no surviving spec data ref).');
     }
     else {
         console.error(`Leak scan: FAILED (${result.leaks.length} leak(s)):`);
@@ -507,11 +513,12 @@ function printLeak(leak) {
 /**
  * Resolve a task-only command's slug argument through the §3a namespace guard
  * (`resolveTaskOnlyArg`): accept bare (= task) + `task:` (explicit alias),
- * REJECT `spec:` with a clear "operates on tasks, not specs" error (and the
- * legacy `prd:` with "operates on tasks, not prds", still accepted through the
- * cutover). On rejection it prints the error to stderr and exits 1 (the task-only
- * commands never act on a spec). An OMITTED slug (`start`/`complete`/`prompt`
- * infer it from the branch) passes through untouched.
+ * REJECT `spec:` with a clear "operates on tasks, not specs" error. On rejection
+ * it prints the error to stderr and exits 1 (the task-only commands never act on
+ * a spec). An OMITTED slug (`start`/`complete`/`prompt` infer it from the branch)
+ * passes through untouched. (The legacy `prd:` prefix is a DEAD namespace token
+ * after the hard cutover — it is neither special-cased nor rejected here; a
+ * `prd:<slug>` arg resolves as a bare literal task slug.)
  *
  * `do` is the ONE command that spans both namespaces; it consumes the full
  * `resolveSlug` (with the cross-namespace collision check) in the `do-in-place`
@@ -589,10 +596,10 @@ function buildInteractiveLauncher(flags, configPath, repoPath) {
  * switching to its `work/<slug>` branch WITHOUT claiming). The runtime
  * difference is exactly the `resume` flag — `resume` forces it on (its only mode
  * is to re-engage), while `start` honours the (now hidden) `--resume` alias.
- * Both are task-only (§3a: accept bare + `task:`, reject `prd:`).
+ * Both are task-only (§3a: accept bare + `task:`, reject `spec:`).
  */
 async function runStartAction(rawSlug, flags, resume) {
-    // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+    // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
     const slug = resolveTaskOnlySlug(rawSlug);
     const cwd = process.cwd();
     // `resume --isolated <slug>`: re-engage the slug's RETAINED job worktree (the
@@ -908,7 +915,7 @@ export function buildProgram() {
         .option('--dry-run', 'show the intended push without mutating the arbiter')
         .option('--ignore-not-ready', 'override the readiness guard: claim despite an unmet blockedBy, and silence the needsAnswers warning (loud, never default)')
         .action(async (rawSlug, flags) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         // Wrap ONLY this CLI surface's `performClaim` call with the spinner
         // helper (task `claim-cas-spinner`): the push can take seconds, so the
@@ -1016,7 +1023,7 @@ export function buildProgram() {
         const remote = flags.remote !== undefined && flags.remote.trim() !== ''
             ? flags.remote
             : undefined;
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const theSlug = resolveTaskOnlySlug(rawSlug);
         const configPath = flags.config ?? defaultConfigPath();
         const { dir: configuredRoot, config } = loadHumanWorktreesDir(configPath);
@@ -1060,10 +1067,10 @@ export function buildProgram() {
     program
         .command('prompt')
         .helpGroup(ADVANCED_GROUP)
-        .description("Print to stdout the work-agent prompt for a task: the canonical CLAIM-PROTOCOL wrapper + the task's own ## Prompt (with <slug> and source prd substituted). Resolves work/in-progress/<slug>.md then work/backlog/<slug>.md; infers <slug> from a work/<slug> branch when omitted. Read-only, stdout only — the same assembly the autonomous runner feeds agentCmd.")
+        .description("Print to stdout the work-agent prompt for a task: the canonical CLAIM-PROTOCOL wrapper + the task's own ## Prompt (with <slug> and source spec substituted). Resolves work/in-progress/<slug>.md then work/backlog/<slug>.md; infers <slug> from a work/<slug> branch when omitted. Read-only, stdout only — the same assembly the autonomous runner feeds agentCmd.")
         .argument('[slug]', 'the slug to render (inferred from a work/<slug> branch if omitted)')
         .action((rawSlug) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         // Resolve the `promptGuidance` NUDGE namespace through the SAME chain the
         // gate family uses (env > per-repo > global > default), so e.g. a
@@ -1106,7 +1113,7 @@ export function buildProgram() {
         .option('--no-fresh-worktree-gate', 'run the acceptance gate in the current checkout (the pre-rebase tree) — the opt-out for when the per-gate install cost is too high')
         .option('--merge-retries <n>', 'cross-job merge-serialiser CAS-retry cap (see `run --help`); resolved flag > env > per-repo > global > default 1000.')
         .action(async (rawSlug, flags) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         const cwd = process.cwd();
         const { global, override } = loadGlobalAndOverride(flags.config);
@@ -1166,7 +1173,7 @@ export function buildProgram() {
                 // `--fresh-worktree-gate`/`--no-fresh-worktree-gate` rides the SAME chain.
                 ...freshWorktreeGateFlagOverrides(flags),
                 // `--merge-retries <n>` rides the SAME chain: the cross-job merge-serialiser
-                // CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5
+                // CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5
                 // / Applied Answer q1 (a)).
                 ...mergeRetriesFlagOverrides(flags),
                 // `--no-pr` (the PR-INTENT axis) rides the SAME chain.
@@ -1206,7 +1213,7 @@ export function buildProgram() {
             // a single-job path, so the resolved flag is passed UNCONDITIONALLY (no
             // fleet downgrade).
             freshWorktreeGate: config.freshWorktreeGate,
-            // Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+            // Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
             // parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — the resolved
             // per-repo value reaches the merge loop via `performComplete`→
             // `performIntegration`.
@@ -1237,13 +1244,13 @@ export function buildProgram() {
     program
         .command('do')
         .helpGroup(HEADLINE_GROUP)
-        .description('The per-repo WORKER (the CI command): claim + onboard onto work/<slug>, run the agent, gate, integrate, and exit. In the CURRENT checkout by default (refuses on a dirty tree, integrates in-place). With --remote <r>: against a REGISTERED repo with NO checkout — materialise a hub mirror + job worktree in the agents\u2019 area, run the same pipeline there, then reap. do <slug> | do task:<slug> | do spec:<slug> (the tasking path; the legacy prd:<slug> is still accepted) | do (auto-pick one) | do <a> <b> (those, in sequence) | do -n <x> (x eligible, in sequence). Auto-pick draws TASKS-FIRST then SPECS-to-task by default (per-repo selectionOrder reorders the pools). --propose (default) / --merge resolved at integrate-time. Supersedes ar-run.sh.')
+        .description('The per-repo WORKER (the CI command): claim + onboard onto work/<slug>, run the agent, gate, integrate, and exit. In the CURRENT checkout by default (refuses on a dirty tree, integrates in-place). With --remote <r>: against a REGISTERED repo with NO checkout — materialise a hub mirror + job worktree in the agents\u2019 area, run the same pipeline there, then reap. do <slug> | do task:<slug> | do spec:<slug> (the tasking path) | do (auto-pick one) | do <a> <b> (those, in sequence) | do -n <x> (x eligible, in sequence). Auto-pick draws TASKS-FIRST then SPECS-to-task by default (per-repo selectionOrder reorders the pools). --propose (default) / --merge resolved at integrate-time. Supersedes ar-run.sh.')
         // EXTENSIBLE argument grammar (the three do-* tasks grow this one block):
         // `do-autopick` widens the single optional positional into a VARIADIC one so
         // `do` (zero args = auto-pick), `do <a> <b> …` (named, in sequence), and
         // `do <slug>` (exactly one) all share the one command. `-n <x>` is the count
         // for the auto-pick form. `do` stays SEQUENTIAL (parallelism is `run`).
-        .argument('[slugs...]', 'the item(s) to do: bare (= the task), task:<slug>, or spec:<slug> (task the spec; the legacy prd:<slug> is still accepted). Zero args = auto-pick; multiple = do them in sequence.')
+        .argument('[slugs...]', 'the item(s) to do: bare (= the task), task:<slug>, or spec:<slug> (task the spec). Zero args = auto-pick; multiple = do them in sequence.')
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--arbiter <remote>', 'name of the arbiter git remote (default: per-repo/global defaultArbiter)')
         .option('-n, --number <x>', 'AUTO-PICK x eligible items and do them IN SEQUENCE (ordered by selectionOrder, default drain = tasks-first then prds-to-task). Sequential — never a parallelism knob (that is `run`). Mutually exclusive with naming items.')
@@ -1252,7 +1259,7 @@ export function buildProgram() {
         .option('--isolated', "build in an ISOLATED job worktree off THIS repo's arbiter (inferred from cwd) instead of taking over the current checkout, then integrate + reap \u2014 the in-place-but-isolated form. Shares the same grammar as the no-checkout forms: a single named item, multiple named items (in sequence), AND -n/auto-pick over the mirror-side eligible-pool scan. Always SEQUENTIAL (parallelism is `run` / the CI matrix). Orthogonal to --remote (a foreign repo); with --remote, remote wins (isolation is already implied).")
         .option('--merge', 'integrate in merge mode this invocation (mutually exclusive with --propose; overrides config)')
         .option('--propose', 'integrate in propose mode this invocation (default; mutually exclusive with --merge; overrides config)')
-        .option('--tasks-land-in <where>', 'where `do prd:<slug>` tasking output lands: `pre-backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > tasksLandIn default > built-in). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
+        .option('--tasks-land-in <where>', 'where `do spec:<slug>` tasking output lands: `pre-backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > tasksLandIn default > built-in). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
         .option('--no-pr', 'propose without opening a PR: push the branch but deliberately skip the review request, even on an authed GitHub arbiter (the explicit suppress-PR intent). Resolved flag > env > per-repo > global > default off.')
         .option('--ignore-diverged-main', 'override the in-place divergence guard: run even when local main is ahead of <arbiter>/main (unpushed). The work still lands on the arbiter; local main is left for you to `git rebase`. In-place only; loud, never default.')
         .option('--allow-backlog', 'do task:<slug> ONLY: also FIND, CLAIM, and COMPLETE a task that lives in tasks/backlog/ (staging), driving it in place WITHOUT promoting it to the pool (so no advance leg / run daemon can claim it out from under you). The done-move goes tasks/backlog/ -> tasks/done/ directly (your explicit drive IS the promotion). EXPLICIT-INVOCATION-ONLY: default off, never set by run/auto-pick/advance or config/env.')
@@ -1266,9 +1273,9 @@ export function buildProgram() {
         .option('--no-review', 'do NOT run Gate 2 this invocation (overrides config)')
         .option('--review-model <id>', 'model the Gate-2 review agent runs on (de-correlated from the builder; routing intent). Resolved flag > env > per-repo > global > default.')
         .option('--review-max-rounds <n>', 'bound the revise/review loop; on exhaustion force needs-attention (default 2)')
-        .option('--tasker-loop', 'run the tasker IMPROVER loop on `do prd:<slug>` (review→edit→converge over the produced task set). ON by default; --no-tasker-loop skips it. DISTINCT from the acceptance gate (--review).')
-        .option('--no-tasker-loop', 'skip the tasker improver loop on `do prd:<slug>`')
-        .option('--tasker-loop-max <n>', 'cap the tasker improver loop on `do prd:<slug>` (in-context review passes); on exhaustion with blockers, reject via needsAnswers / route the prd to needs-attention (default 3)')
+        .option('--tasker-loop', 'run the tasker IMPROVER loop on `do spec:<slug>` (review→edit→converge over the produced task set). ON by default; --no-tasker-loop skips it. DISTINCT from the acceptance gate (--review).')
+        .option('--no-tasker-loop', 'skip the tasker improver loop on `do spec:<slug>`')
+        .option('--tasker-loop-max <n>', 'cap the tasker improver loop on `do spec:<slug>` (in-context review passes); on exhaustion with blockers, reject via needsAnswers / route the spec to needs-attention (default 3)')
         .option('--tasker-loop-model <id>', 'model the tasker improver loop review agent runs on (de-correlated from the tasker; routing intent). Resolved flag > env > per-repo > global > default. DISTINCT from --review-model.')
         .option('--fresh-worktree-gate', 'run the acceptance gate (prepare then verify) against the REBASED tip in a CLEAN throwaway worktree (the tree that actually integrates), so a green gate provably describes the merged artifact. ON by default. Resolved flag > env > per-repo > global > default on.')
         .option('--no-fresh-worktree-gate', "run the acceptance gate in the agent's build worktree (the pre-rebase tree) as before — the opt-out for when the per-gate install cost is too high")
@@ -1405,7 +1412,7 @@ export function buildProgram() {
                 // Host-only runner IDENTITY — scopes git/provider ops only (not the
                 // agent launch); absent ⇒ ambient.
                 identity: remoteConfig.identity,
-                // `do --remote prd:<slug>` tasking-gate policy (task-build path ignores it).
+                // `do --remote spec:<slug>` tasking-gate policy (task-build path ignores it).
                 autoTask: remoteConfig.autoTask,
                 // The resolved `promptGuidance` nudge — threaded into the remote worker
                 // prompt (runRemotePipeline → buildAgentPrompt), mirroring in-place `do`.
@@ -1413,7 +1420,7 @@ export function buildProgram() {
                 integration: remoteConfig.integration,
                 // EXPLICIT `--merge` override for the untrusted-origin build-propose rule.
                 explicitMerge: flagMode === 'merge',
-                // Per-TRANSITION TASKING override (the `do --remote prd:` tasking path).
+                // Per-TRANSITION TASKING override (the `do --remote spec:` tasking path).
                 taskingIntegration: remoteConfig.taskingIntegration,
                 // TASK-PLACEMENT: the configured default + the EXPLICIT operator override
                 // (`--tasks-land-in`), the top of the placement precedence — mirrors
@@ -1425,7 +1432,7 @@ export function buildProgram() {
                 // Single-job build path: gate the REBASED tip (the default) unconditionally.
                 freshWorktreeGate: remoteConfig.freshWorktreeGate,
                 // Cross-job merge-serialiser CAS-retry cap (resolved through the per-repo
-                // chain on the arbiter-side `.dorfl.json` too) — prd
+                // chain on the arbiter-side `.dorfl.json` too) — spec
                 // `land-time-reverify-and-parallel-merge-ceiling` Story 5.
                 mergeRetries: remoteConfig.mergeRetries,
                 noPR: remoteConfig.noPR,
@@ -1442,7 +1449,7 @@ export function buildProgram() {
                         agentCmd: remoteConfig.agentCmd,
                     })
                     : undefined,
-                // The tasker IMPROVER loop on the `do --remote prd:` path is ON by default
+                // The tasker IMPROVER loop on the `do --remote spec:` path is ON by default
                 // (auto-tasking has no `verify` floor, so the loop is the task path's
                 // quality engine). `--tasker-loop`/`--no-tasker-loop` gates wiring the seam;
                 // `taskerLoopMax`/`taskerLoopModel` resolve per-repo (flag > env > per-repo
@@ -1455,7 +1462,7 @@ export function buildProgram() {
                     : undefined,
                 taskerLoopMax: remoteConfig.taskerLoopMax,
                 taskerLoopModel: remoteConfig.taskerLoopModel,
-                // The task-SET ACCEPTANCE GATE on the `do --remote prd:` path too.
+                // The task-SET ACCEPTANCE GATE on the `do --remote spec:` path too.
                 taskReviewGate: remoteConfig.review
                     ? harnessTaskAcceptanceGate({
                         harness: remoteHarness,
@@ -1559,7 +1566,7 @@ export function buildProgram() {
             // ops (claim, push, integrate, `gh`) — NEVER the agent launch. Absent ⇒
             // ambient (today's behaviour). Mapped Config → DoOptions like model/agentCmd.
             identity: config.identity,
-            // `do prd:<slug>` tasking-gate policy (the task-build path ignores it).
+            // `do spec:<slug>` tasking-gate policy (the task-build path ignores it).
             autoTask: config.autoTask,
             // The resolved `promptGuidance` NUDGE namespace (e.g. `testFirst`),
             // threaded into the worker prompt by performDo → buildAgentPrompt so a
@@ -1572,11 +1579,11 @@ export function buildProgram() {
             // typed `--merge` (`flagMode`), never when `merge` came from config — so an
             // untrusted-origin task still forces propose under a config `merge`.
             explicitMerge: flagMode === 'merge',
-            // Per-TRANSITION TASKING override: the `do prd:` tasking path threads
+            // Per-TRANSITION TASKING override: the `do spec:` tasking path threads
             // `taskingIntegration ?? integration`; the task-build path stays on
             // `integration`. Unset ⇒ tasking falls back to `integration` (today's behaviour).
             taskingIntegration: config.taskingIntegration,
-            // TASK-PLACEMENT (`do prd:` tasking output): the configured default rung +
+            // TASK-PLACEMENT (`do spec:` tasking output): the configured default rung +
             // the EXPLICIT operator override `--tasks-land-in` (top of the precedence).
             // `explicitTasksLandIn` is set ONLY when the flag was typed (mirrors
             // `explicitMerge`), so an untrusted-origin staging force still wins under a
@@ -1589,7 +1596,7 @@ export function buildProgram() {
             verify: config.verify,
             // Single-job build path: gate the REBASED tip (the default) unconditionally.
             freshWorktreeGate: config.freshWorktreeGate,
-            // Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+            // Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
             // parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — resolved per-repo
             // and threaded to `performComplete`→`performIntegration`.
             mergeRetries: config.mergeRetries,
@@ -1613,7 +1620,7 @@ export function buildProgram() {
             reviewGate: config.review
                 ? harnessReviewGate({ harness, agentCmd: config.agentCmd })
                 : undefined,
-            // The tasker IMPROVER loop on the `do prd:` tasking path is ON by default
+            // The tasker IMPROVER loop on the `do spec:` tasking path is ON by default
             // (auto-tasking has no `verify` floor — the loop is the task path's quality
             // engine). `--tasker-loop`/`--no-tasker-loop` gates wiring the seam;
             // `taskerLoopMax`/`taskerLoopModel` resolve per-repo (flag > env > per-repo
@@ -1640,7 +1647,7 @@ export function buildProgram() {
             note: (message) => console.error(`>> ${message}`),
             noteBlock: (message) => console.error(message),
         };
-        // `--allow-backlog` is EXPLICIT-SINGLE-TASK-ONLY (prd
+        // `--allow-backlog` is EXPLICIT-SINGLE-TASK-ONLY (spec
         // `do-allow-backlog-drive-staged-tasks-without-promotion`, decision 4): it
         // drives ONE named staged task in place. It must NOT combine with the
         // AUTO-PICK (zero-args / -n) or MULTI-ITEM forms — those select FROM the
@@ -1694,33 +1701,33 @@ export function buildProgram() {
         process.exit(result.exitCode);
     });
     // `advance` — the SIBLING top-level verb (NOT a `do` subcommand; `do`
-    // subcommands + a standalone `task` verb are REJECTED in prd `advance-loop`).
+    // subcommands + a standalone `task` verb are REJECTED in spec `advance-loop`).
     // It reuses the SAME shared `prefix:arg` resolver `do` uses, EXTENDED with the
     // `obs:` namespace, and wires the classify → lock → execute SKELETON: classify
     // the rung (read-only, no model, no lock), take the `advancing` CAS borrow, then
-    // dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do prd:` (never a
+    // dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:` (never a
     // duplicate), surface/apply/triage dispatch to a named executor seam later
     // tasks fill. The DRIVERS (one-shot/loop) + `-n` + per-action gates and the
     // rung BODIES are LATER tasks; the bare eligible-SET form errors clearly here.
     program
         .command('advance')
         .helpGroup(HEADLINE_GROUP)
-        .description('Advance work/ item(s) one lifecycle rung toward ready/built (PRD advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung; the legacy prd:<slug> is still accepted) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix).')
-        .argument('[slugs...]', 'the item(s) to advance: bare (= the task), task:<slug>, spec:<slug> (the legacy prd:<slug> is still accepted), or obs:<slug> (an observation). Zero args = auto-pick one eligible; multiple = advance them in sequence.')
+        .description('Advance work/ item(s) one lifecycle rung toward ready/built (SPEC advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix).')
+        .argument('[slugs...]', 'the item(s) to advance: bare (= the task), task:<slug>, spec:<slug>, or obs:<slug> (an observation). Zero args = auto-pick one eligible; multiple = advance them in sequence.')
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--arbiter <remote>', 'name of the arbiter git remote (default: per-repo/global defaultArbiter)')
         .option('-n, --number <x>', 'AUTO-PICK x eligible items and advance them IN SEQUENCE (ordered by selectionOrder, default drain = tasks-first then prds-to-task). Sequential — never a parallelism knob (that is `run` / the CI matrix). Mutually exclusive with naming items.')
         .option('--isolated', "advance in an ISOLATED worktree off THIS repo's arbiter (inferred from cwd) instead of taking over the current checkout, then integrate + reap — the in-place-but-isolated form. Shares the same grammar: a single named item, multiple named items (in sequence), AND -n/auto-pick over the mirror-side eligible-pool scan. Always SEQUENTIAL (parallelism is `run` / the CI matrix). Lets you advance from a busy/dirty checkout or anywhere with a participating arbiter.")
         .option('--selection-order <order>', 'order the auto-pick pools (build/task/surface/triage; apply is always first): a preset keyword (drain (default) | groom) or an explicit comma-separated pool list. Resolved flag > env > per-repo > global > default.')
         .option('--observation-triage <mode>', 'the observation-inbox gate (off|ask|auto): off (default) leaves observations untouched (the triage pool is dropped from auto-pick); ask surfaces a promote/keep/delete question for each untriaged observation; auto auto-disposes the no-question cases (duplicate/map) and asks about the rest. Resolved flag > env > per-repo > global > default. An explicit `advance obs:<slug>` bypasses the selection gate and runs in ask-mode (auto-disposes only under `auto`).')
-        .option('--surface-blockers', 'the declared-blocked-work gate (the orthogonal peer of --observation-triage): render a task/prd carrying needsAnswers:true into an answerable question sidecar (the needsAnswers-blocked pool is enumerated into auto-pick). Resolved flag > env > per-repo > global > default off. An explicit `advance <slug>`/`advance prd:<slug>` bypasses this selection gate and surfaces regardless. Does NOT gate apply (an answered sidecar still applies) or needs-attention (always on).')
-        .option('--no-surface-blockers', 'leave a needsAnswers:true task/prd silently blocked (default; the blocked pool is dropped from auto-pick)')
-        .option('--strict-merge-approval', 'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (prd `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when the merge-base CHANGED between the human’s merge-answer and the apply step, RE-SURFACE the merge-question (clear the answer back to no-answer; re-author the question on main/runner under the advancing lock) instead of auto-landing on a green re-verify. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.')
+        .option('--surface-blockers', 'the declared-blocked-work gate (the orthogonal peer of --observation-triage): render a task/spec carrying needsAnswers:true into an answerable question sidecar (the needsAnswers-blocked pool is enumerated into auto-pick). Resolved flag > env > per-repo > global > default off. An explicit `advance <slug>`/`advance spec:<slug>` bypasses this selection gate and surfaces regardless. Does NOT gate apply (an answered sidecar still applies) or needs-attention (always on).')
+        .option('--no-surface-blockers', 'leave a needsAnswers:true task/spec silently blocked (default; the blocked pool is dropped from auto-pick)')
+        .option('--strict-merge-approval', 'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (spec `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when the merge-base CHANGED between the human’s merge-answer and the apply step, RE-SURFACE the merge-question (clear the answer back to no-answer; re-author the question on main/runner under the advancing lock) instead of auto-landing on a green re-verify. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.')
         .option('--no-strict-merge-approval', 'honour the prior merge-answer and land when the rebased tip re-verifies GREEN even if the merge-base changed (default; the cheap green-re-verify-is-enough path)')
         .option('--merge-questions <mode>', 'the merge-question SURFACER gate (off|ask|auto): off drops the surfacer (only for a repo that lands by some other means); ask (default) enumerates unmerged `work/*` branches and surfaces a merge-question sidecar a human answers; auto self-supplies the `merge` answer and lands via the SAME deterministic apply-time re-verify (the merge-mode-like fast path). SEPARATE axis from --observation-triage with a HIGHER default (a dropped merge-question means pushed work never lands). Resolved flag > env > per-repo > global > default ask.')
         .option('--merge', 'integrate the advanced item(s) in merge mode this invocation (mutually exclusive with --propose; overrides config). The CI merge shape is a SINGLE SEQUENTIAL job, so this rides the `-n`/named-sequence path, never the matrix.')
         .option('--propose', 'integrate the advanced item(s) in propose mode this invocation (default; mutually exclusive with --merge; overrides config). The CI propose shape is the parallel matrix (one PR per item).')
-        .option('--tasks-land-in <where>', 'where `advance prd:<slug>` tasking output lands: `pre-backlog` (staged) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence. Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
+        .option('--tasks-land-in <where>', 'where `advance spec:<slug>` tasking output lands: `pre-backlog` (staged) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence. Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
         .option('--watch', "stream the build agent's high-signal events live by tailing the pi session log (requires harness: pi; READ-ONLY observer — does not change outcome/gate/git). The same view `do --watch` gives, threaded through the build rung; CI uses it so the job log shows the agent working instead of freezing.")
         .action(async (rawSlugs, flags) => {
         // Variadic grammar (mirrors `do`): zero args = AUTO-PICK; one = the single
@@ -1836,7 +1843,7 @@ export function buildProgram() {
                 integration: remoteConfig.integration,
                 // EXPLICIT `--merge` override for the untrusted-origin build-propose rule.
                 explicitMerge: flagMode === 'merge',
-                // Per-TRANSITION TASKING override (the isolated `do --remote prd:` path).
+                // Per-TRANSITION TASKING override (the isolated `do --remote spec:` path).
                 taskingIntegration: remoteConfig.taskingIntegration,
                 // TASK-PLACEMENT: configured default + EXPLICIT `--tasks-land-in` override
                 // (set only when typed, mirroring `explicitMerge`).
@@ -1846,7 +1853,7 @@ export function buildProgram() {
                 verify: remoteConfig.verify,
                 // Single-job build path: gate the REBASED tip (the default) unconditionally.
                 freshWorktreeGate: remoteConfig.freshWorktreeGate,
-                // Cross-job merge-serialiser CAS-retry cap — prd
+                // Cross-job merge-serialiser CAS-retry cap — spec
                 // `land-time-reverify-and-parallel-merge-ceiling` Story 5.
                 mergeRetries: remoteConfig.mergeRetries,
                 noPR: remoteConfig.noPR,
@@ -1974,7 +1981,7 @@ export function buildProgram() {
             // EXPLICIT `--merge` override for the untrusted-origin build-propose rule (a
             // bare `advance` auto-pick passes no flag ⇒ unset ⇒ untrusted forces propose).
             explicitMerge: flagMode === 'merge',
-            // Per-TRANSITION TASKING override (the `do prd:` tasking path threads
+            // Per-TRANSITION TASKING override (the `do spec:` tasking path threads
             // `taskingIntegration ?? integration`; the build path stays on `integration`).
             taskingIntegration: config.taskingIntegration,
             // TASK-PLACEMENT: configured default + EXPLICIT `--tasks-land-in` override
@@ -1985,7 +1992,7 @@ export function buildProgram() {
             verify: config.verify,
             // Single-job build path: gate the REBASED tip (the default) unconditionally.
             freshWorktreeGate: config.freshWorktreeGate,
-            // Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+            // Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
             // parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)).
             mergeRetries: config.mergeRetries,
             noPR: config.noPR,
@@ -2112,7 +2119,7 @@ export function buildProgram() {
         .action(async (flags) => {
         const config = resolveGlobalConfig(loadConfig(flags.config), {});
         const workspacesDir = flags.workspace ?? config.workspacesDir;
-        // The `gc`-STYLE ledger SWEEP (prd `ledger-integrity` story 3): a SEPARATE
+        // The `gc`-STYLE ledger SWEEP (spec `ledger-integrity` story 3): a SEPARATE
         // surface from the worktree reaper below — it REPORTS one-slug-one-folder
         // violations in a repo's `work/` lifecycle ledger and NEVER deletes (a human
         // resolves each). Distinct `work/`: the ledger, not the execution substrate.
@@ -2120,7 +2127,7 @@ export function buildProgram() {
             const repoPath = typeof flags.ledger === 'string' ? flags.ledger : process.cwd();
             const result = sweepLedgerDuplicates(repoPath);
             // The UNIFIED-LOCK stuck/orphaned-lock REPORT (task
-            // `release-lock-verb-and-gc-stuck-report`, prd
+            // `release-lock-verb-and-gc-stuck-report`, spec
             // `ledger-status-per-item-lock-refs` US #12/#13/#14): generalises the
             // advancing-marker report from advancing-only to the unified per-item
             // lock. The locks live on the ARBITER ref (`refs/dorfl/lock/*`),
@@ -2196,7 +2203,7 @@ export function buildProgram() {
             // ALL are REPORTED here (never auto-deleted — no automatic sweep exists; a
             // human clears a NAMED unified lock via `release-lock`).
             //
-            // SCOPED to the ATTENTION verdicts only (prd US#14/#21, ADR
+            // SCOPED to the ATTENTION verdicts only (spec US#14/#21, ADR
             // `ledger-status-on-per-item-lock-refs`: this surface is the STUCK /
             // crash-orphaned lock, NOT every held one): a `kept-stuck` (terminal +
             // stuck) or a `cleared-stale`-eligible (terminal + stale active = orphaned)
@@ -2223,7 +2230,7 @@ export function buildProgram() {
                 dryRun: flags.dryRun === true,
                 note: (message) => console.error(`>> ${message}`),
             });
-            // The ORPHAN-SIDECAR sweep (prd
+            // The ORPHAN-SIDECAR sweep (spec
             // `agentic-question-resolution-retire-disposition-vocabulary`, US #10) rides
             // the SAME `--remote-branches` invocation the SCHEDULED CI lifecycle workflow
             // runs (`dorfl gc --remote-branches --arbiter origin`) — so the reap of a
@@ -2421,7 +2428,7 @@ export function buildProgram() {
         .option('--reset', 'DISCARD the kept work: delete the remote work/<slug> branch FIRST, then move to backlog so the next claim starts FRESH (guarded; a deliberate departure from the never-delete-the-remote-branch invariant). Never the default.')
         .option('-m, --message <note>', 'append a dated handoff note to the item body for the next agent (append-only; applies to both default and --reset)')
         .action(async (rawSlug, flags) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         const cwd = flags.cwd ?? process.cwd();
         // Route the requeue (default keep+continue / --reset discard / -m handoff)
@@ -2457,12 +2464,12 @@ export function buildProgram() {
             : ' (kept the work branch; next claim continues from its tip)';
         console.log(`Requeued '${slug}' to backlog for re-claiming.${how}`);
     });
-    // `promote [item]` (prd `staging-pool-position-gate-and-trust-model`, tasks
+    // `promote [item]` (spec `staging-pool-position-gate-and-trust-model`, tasks
     // `pre-backlog-staging-folder-and-promote-step-a` /
     // `pre-prd-staging-pool-split-and-untrusted-prd-placement`): the HUMAN/runner-
     // owned verb that moves a STAGED item into its agent-eligible POOL — a task
-    // `work/pre-backlog/<slug>.md → work/backlog/<slug>.md`, a prd
-    // `work/prds/proposed/<slug>.md → work/prds/ready/<slug>.md` — as a tree-less CAS on the
+    // `work/pre-backlog/<slug>.md → work/backlog/<slug>.md`, a spec
+    // `work/specs/proposed/<slug>.md → work/specs/ready/<slug>.md` — as a tree-less CAS on the
     // arbiter, the SAME trust model + mechanism as `requeue`. The agent emits STAGED;
     // only this verb (a human, or the runner) admits it to the pool. With NO argument
     // it LISTS what is promotable (the "what is staged waiting for me?" discovery), so
@@ -2470,7 +2477,7 @@ export function buildProgram() {
     program
         .command('promote [item]')
         .helpGroup(HEADLINE_GROUP)
-        .description('Admit a STAGED item into its agent-eligible POOL (the runner/human side of the staging gate): a task `work/pre-backlog/<slug>.md → work/backlog/<slug>.md`, a prd `work/prds/proposed/<slug>.md → work/prds/ready/<slug>.md`, published as a TREE-LESS compare-and-swap to the arbiter ref (EXACTLY like requeue/claim — it never stages/commits in the cwd tree). The agent only ever CREATES staged; this verb is the gate a human (or the runner) opens. Accepts `task:<slug>` / `prd:<slug>` / a bare `<slug>` (= task). With NO argument, LISTS every promotable item (the tasks in pre-backlog/ + the prds in prds/proposed/ on the arbiter) so you can see what is staged waiting for promotion. Idempotent: promoting an already-pooled slug is a clean no-op success.')
+        .description(`Admit a STAGED item into its agent-eligible POOL (the runner/human side of the staging gate): a task \`work/pre-backlog/<slug>.md → work/backlog/<slug>.md\`, a spec \`${workFolderPrefix('specs-proposed')}<slug>.md → ${workFolderPrefix('specs-ready')}<slug>.md\`, published as a TREE-LESS compare-and-swap to the arbiter ref (EXACTLY like requeue/claim — it never stages/commits in the cwd tree). The agent only ever CREATES staged; this verb is the gate a human (or the runner) opens. Accepts \`task:<slug>\` / \`spec:<slug>\` / a bare \`<slug>\` (= task). With NO argument, LISTS every promotable item (the tasks in pre-backlog/ + the specs in specs/proposed/ on the arbiter) so you can see what is staged waiting for promotion. Idempotent: promoting an already-pooled slug is a clean no-op success.`)
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--cwd <dir>', 'the repo/working clone whose arbiter remote the tree-less move is resolved FROM (default: cwd) — an ORIGIN SOURCE only; the move is published to the arbiter, never to this tree')
         .option('--arbiter <remote>', 'the arbiter git remote the promotion is CAS-published to / the staging folders are listed from (default: origin)')
@@ -2489,7 +2496,7 @@ export function buildProgram() {
                 process.exit(1);
             }
             if (listed.items.length === 0) {
-                console.log(`Nothing staged to promote on ${arbiter}/main (work/pre-backlog/ and work/prds/proposed/ are empty).`);
+                console.log(`Nothing staged to promote on ${arbiter}/main (work/pre-backlog/ and ${workFolderPrefix('specs-proposed')} are empty).`);
                 return;
             }
             console.log('Staged, awaiting promotion (run `promote <item>`):');
@@ -2498,11 +2505,10 @@ export function buildProgram() {
             }
             return;
         }
-        // AN ITEM → promote it. `task:`/`spec:` are explicit (the legacy `prd:`
-        // prefix is still ACCEPTED as an input alias through the cutover — the
-        // contract task drops it); a bare slug defaults to a task (mirrors
-        // `requeue`). An `obs:`/`observation:` prefix is rejected (observations have
-        // no pool).
+        // AN ITEM → promote it. `task:`/`spec:` are explicit; a bare slug defaults to
+        // a task (mirrors `requeue`). An `obs:`/`observation:` prefix is rejected
+        // (observations have no pool). A legacy `prd:` prefix is a DEAD namespace token
+        // after the hard cutover — it resolves as a bare literal task slug, not a spec.
         const parsed = parseSlugArg(rawItem);
         if (parsed.explicit === 'observation') {
             console.error(`error: promote takes a task or spec, not an observation ('${rawItem}'). Observations have no agent pool.`);
@@ -2529,7 +2535,7 @@ export function buildProgram() {
     // the `work/advancing/<entry>.md` marker is gone and an advance hold is now just
     // `action: advance` on the UNIFIED per-item lock, so `release-lock <item>` (below)
     // is the SOLE named human release for ALL holds (implement/task/advance).
-    // `release-lock <item>` (task `release-lock-verb-and-gc-stuck-report`, prd
+    // `release-lock <item>` (task `release-lock-verb-and-gc-stuck-report`, spec
     // `ledger-status-per-item-lock-refs` US #14): the HUMAN-invoked named release of
     // a stuck/orphaned UNIFIED per-item lock (`refs/dorfl/lock/<entry>`) —
     // the GENERALISATION of `release-advancing` from the advancing-only marker to
@@ -2545,7 +2551,7 @@ export function buildProgram() {
     program
         .command('release-lock <item>')
         .helpGroup(HEADLINE_GROUP)
-        .description('Clear a NAMED stuck/orphaned UNIFIED per-item lock (refs/dorfl/lock/<entry>) by DELETING the ref on the arbiter — the recovery verb for a lock the system orphaned (a crashed build/task/advance that left the hold behind). The generalisation of `release-advancing` from the advancing marker to the ONE lock per item. Same trust model as `requeue`: a HUMAN asserts the lock is dead by NAMING it; the tool never guesses liveness (the lock has NO heartbeat, so there is NO automatic sweep / age-based reaper anywhere). Accepts the same item forms as the lock API: `task:<slug>` / `prd:<slug>` / `obs:<slug>` / a bare `<slug>` (= task). Idempotent — re-running on an already-cleared lock is a clean exit-0 no-op (deleting the lock ref is “all locks released”, recoverable). NEVER `--force`. Discoverable via `gc --ledger` (it REPORTS every lingering lock, never deletes).')
+        .description('Clear a NAMED stuck/orphaned UNIFIED per-item lock (refs/dorfl/lock/<entry>) by DELETING the ref on the arbiter — the recovery verb for a lock the system orphaned (a crashed build/task/advance that left the hold behind). The generalisation of `release-advancing` from the advancing marker to the ONE lock per item. Same trust model as `requeue`: a HUMAN asserts the lock is dead by NAMING it; the tool never guesses liveness (the lock has NO heartbeat, so there is NO automatic sweep / age-based reaper anywhere). Accepts the same item forms as the lock API: `task:<slug>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` (= task). Idempotent — re-running on an already-cleared lock is a clean exit-0 no-op (deleting the lock ref is “all locks released”, recoverable). NEVER `--force`. Discoverable via `gc --ledger` (it REPORTS every lingering lock, never deletes).')
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--cwd <dir>', 'the repo/working clone whose arbiter remote the lock ref is DELETED on (default: cwd)')
         .option('--arbiter <remote>', 'the arbiter git remote the lock ref is deleted on (default: origin)')
@@ -2574,7 +2580,7 @@ export function buildProgram() {
         console.error(`error: ${result.message}`);
         process.exit(1);
     });
-    // `drop <slug>` (prd `agentic-question-resolution-retire-disposition-vocabulary`,
+    // `drop <slug>` (spec `agentic-question-resolution-retire-disposition-vocabulary`,
     // US #5/#11; task `direct-delete-question-cli-helper`): the DIRECT "throw it
     // away" verb — `git rm` a source item AND its question sidecar (when present) in
     // ONE revertible commit, the reason in the commit MESSAGE (git history is the
@@ -2588,7 +2594,7 @@ export function buildProgram() {
     program
         .command('drop <slug>')
         .helpGroup(HEADLINE_GROUP)
-        .description('DIRECTLY delete a source item + its question sidecar (when present) in ONE revertible commit — the "I just want to throw this away" path that does NOT round-trip through the decision engine or any agent. Resolves the source by its namespaced identity (`task:<slug>` / `prd:<slug>` / `obs:<slug>` / a bare `<slug>` = task), `git rm`s the source AND its sidecar together, and records your --reason in the commit MESSAGE (git history is the archive). A single revertible commit, so a wrong delete is recoverable via `git revert`. DISTINCT from `remote rm` (the hub-mirror deleter). A LOCAL working-tree commit (like the apply rung); it does not touch the arbiter — push/integrate it as you normally would. If the named source is already gone it is a clean no-op (nothing to throw away).')
+        .description('DIRECTLY delete a source item + its question sidecar (when present) in ONE revertible commit — the "I just want to throw this away" path that does NOT round-trip through the decision engine or any agent. Resolves the source by its namespaced identity (`task:<slug>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` = task), `git rm`s the source AND its sidecar together, and records your --reason in the commit MESSAGE (git history is the archive). A single revertible commit, so a wrong delete is recoverable via `git revert`. DISTINCT from `remote rm` (the hub-mirror deleter). A LOCAL working-tree commit (like the apply rung); it does not touch the arbiter — push/integrate it as you normally would. If the named source is already gone it is a clean no-op (nothing to throw away).')
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--cwd <dir>', 'the working clone the revertible delete commit is made in (default: cwd)')
         .option('--reason <text>', 'why you are throwing this away — recorded in the commit MESSAGE (git history is the archive). Optional; recorded as "(no reason given)" when omitted.')
@@ -2658,7 +2664,7 @@ export function buildProgram() {
             console.error(`>> ${resolved.message}`);
         }
         const config = resolved.config;
-        // Resolve the PER-OUTCOME integration modes (prd US #9): `intake` decides
+        // Resolve the PER-OUTCOME integration modes (spec US #9): `intake` decides
         // the artifact TYPE at runtime, so a single --merge/--propose can't express
         // a type-conditional policy. The granular flags override the aggregate; an
         // UNSET type falls back to the per-repo/global `integration` (the SAME chain
@@ -2734,17 +2740,17 @@ export function buildProgram() {
         }
         process.exit(result.exitCode);
     });
-    // The CI CLOSE-JOB driver (prd `runner-in-ci`, capability E; task
+    // The CI CLOSE-JOB driver (spec `runner-in-ci`, capability E; task
     // `install-ci-close-job-workflow`). The thin JOB the emitted close-job workflow
     // invokes on a merge to main: resolve which source issue(s) the landed work
-    // closes (resolveClosingIssue), run the "prd complete?" query for the prd case
+    // closes (resolveClosingIssue), run the "spec complete?" query for the spec case
     // (prd-complete-query, done), and close via the IssueProvider seam — all
     // UNCHANGED engine pieces, CONSUMED not re-built (the Out-of-Scope fence). CI
     // owns ONLY the job + trigger. Local-runnable too (a manual catch-up close).
     program
         .command('close-merged-issues')
         .helpGroup(ADVANCED_GROUP)
-        .description('Close source issues whose work has landed on main (CI capability E, prd runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.prd: → prd issue:`), runs the existing "prd complete?" query for the prd case (closes ONLY when ALL its prd:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main; DEGRADES (never crashes) on a missing/unauthenticated gh.')
+        .description('Close source issues whose work has landed on main (CI capability E, spec runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.spec: → spec issue:`), runs the existing "spec complete?" query for the spec case (closes ONLY when ALL its spec:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main; DEGRADES (never crashes) on a missing/unauthenticated gh.')
         .option('--cwd <dir>', 'the repo working dir whose work/ tree to scan (default: cwd)')
         .option('--gh-bin <bin>', 'the gh CLI binary (default: gh on PATH)')
         .option('--json', 'output the raw result as JSON')