dorfl 0.1.1 → 0.2.0

package/dist/tasking.js

@@ -19,14 +19,14 @@ const DEFAULT_LOCK_SEAM = {
 };
 const DEFAULT_ARBITER = 'origin';
 /**
- * **The STAGED-TASKS dir** (prd `staging-pool-position-gate-and-trust-model`,
+ * **The STAGED-TASKS dir** (spec `staging-pool-position-gate-and-trust-model`,
  * task `pre-backlog-staging-folder-and-promote-step-a`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). The runner
  * lands the tasker's emitted task files HERE, NOT in `work/tasks/ready/`: an item
- * born in `pre-backlog/` is durable + readable but NOT in the agent-eligible
+ * born in `tasks/backlog/` is durable + readable but NOT in the agent-eligible
  * pool (`work/tasks/ready/` STILL means the pool — every reader is byte-for-byte
  * unchanged). A runner/human-owned promotion (`promoteFromPreBacklog` in
- * `needs-attention.ts`) moves an approved item `pre-backlog/ → backlog/` to make
+ * `needs-attention.ts`) moves an approved item `tasks/backlog/ → tasks/ready/` to make
  * it claimable. STEP A: ADDITIVE — no `work/tasks/ready/` reader changes here.
  */
 export const STAGED_TASKS_DIR = workFolderRel('tasks-backlog');
@@ -36,7 +36,7 @@ export const STAGED_TASKS_DIR = workFolderRel('tasks-backlog');
  * origin, or an `--tasks-land-in ready` operator override). The agent NEVER
  * writes here — it always writes to {@link STAGED_TASKS_DIR}; the runner
  * redirects the emitted files to the resolved destination at integrate-stage
- * time. prd US #4 / the governing ADR: the agent cannot self-place into the
+ * time. spec US #4 / the governing ADR: the agent cannot self-place into the
  * pool. Task `runner-deterministic-slice-placement-policy-and-precedence`.
  */
 const POOL_TASKS_DIR = workFolderRel('tasks-ready');
@@ -46,15 +46,17 @@ const TASK_PLACEMENT_SLOTS = {
     pool: POOL_TASKS_DIR,
 };
 /**
- * Map the `tasksLandIn` value spelling (`pre-backlog` | `ready`) onto the
+ * Map the `tasksLandIn` value spelling (`backlog` | `ready`) onto the
  * resolver's lifecycle-generic side enum (`staging` | `pool`). Returns
  * `undefined` when no value is set, so the resolver's next precedence rung
- * applies (the built-in floor). The legacy `'backlog'`/`'todo'` pool spellings
- * are NOT accepted (clean break — the value was renamed `'backlog'` → `'todo'`
- * → `'ready'`, ADR `rename-task-pool-folder-todo-to-ready`).
+ * applies (the built-in floor). The legacy `'pre-backlog'`/`'todo'` spellings
+ * are NOT accepted (clean break — the staging value was renamed
+ * `'pre-backlog'` → `'backlog'`, and the pool value was renamed
+ * `'backlog'` → `'todo'` → `'ready'`, ADR
+ * `rename-task-pool-folder-todo-to-ready`).
  */
 function landingToSide(landing) {
-    if (landing === 'pre-backlog')
+    if (landing === 'backlog')
         return 'staging';
     if (landing === 'ready')
         return 'pool';
@@ -65,7 +67,7 @@ function stagedTaskPath(name) {
     return `${STAGED_TASKS_DIR}/${name}`;
 }
 /**
- * Run the `do prd:<slug>` tasking path end-to-end. Never throws for the expected
+ * Run the `do spec:<slug>` tasking path end-to-end. Never throws for the expected
  * gate-refused / lock-lost / agent-failed / stale cases — those are returned with
  * the appropriate exit code and outcome. The runner owns all git; the agent only
  * writes task files.
@@ -82,18 +84,18 @@ export async function performTask(options) {
     const slug = options.slug;
     const doer = options.doer ?? 'agent';
     const lock = options.lock ?? DEFAULT_LOCK_SEAM;
-    // 0. The prd must exist in the checkout (`work/prds/ready/<slug>.md`) — it is the
+    // 0. The spec must exist in the checkout (`work/specs/ready/<slug>.md`) — it is the
     //    source the agent tasks + the file the lock holds.
     const specPath = workItemPath(cwd, 'specs-ready', slug);
     if (!existsSync(specPath)) {
-        const message = `no prd '${slug}' found at ${workFolderRel('specs-ready')}/${slug}.md.`;
+        const message = `no spec '${slug}' found at ${workFolderRel('specs-ready')}/${slug}.md.`;
         note(message);
         return { exitCode: 1, outcome: 'usage-error', slug, message };
     }
     const specContent = readFileSync(specPath, 'utf8');
     const specFm = parseFrontmatter(specContent);
     // 1. RESOLVE THE GATE (agent path only). The human path is UNBOUND — a human
-    //    decides for themselves whether a prd is taskable.
+    //    decides for themselves whether a spec is taskable.
     if (doer === 'agent') {
         const eligibility = resolveAgentGate(cwd, slug, specFm, options.autoTask, options.explicit ?? false);
         if (!eligibility.taskable) {
@@ -136,9 +138,9 @@ export async function performTask(options) {
     }
     // 2b. ONBOARD the agent's tasking work onto a `work/<slug>` BRANCH cut from the
     //     freshly-fetched `<arbiter>/main` (task `slice-output-through-integration`).
-    //     The prd body rests in `work/prds/ready/<slug>.md` on `<arbiter>/main` (the lock no
-    //     longer moves it), so the branch's base HOLDS the held prd — the lifecycle
-    //     stage below moves it `prd/ → prd-tasked/` ON THIS BRANCH and the shared integrate core (`--propose`
+    //     The spec body rests in `work/specs/ready/<slug>.md` on `<arbiter>/main` (the lock no
+    //     longer moves it), so the branch's base HOLDS the held spec — the lifecycle
+    //     stage below moves it `specs/ready/ → specs/tasked/` ON THIS BRANCH and the shared integrate core (`--propose`
     //     PR / `--merge` main) lands the whole transition, WITHOUT the lock release
     //     committing tasks straight to `main`. The agent runs IN-PLACE on this branch
     //     (branch ≠ worktree; the isolation seam upgrades it). The HUMAN path stays on
@@ -146,7 +148,7 @@ export async function performTask(options) {
     if (useLock) {
         await switchToWorkBranch(cwd, arbiter, slug, env);
     }
-    // 3. INVOKE THE AGENT with the to-task prd. It WRITES
+    // 3. INVOKE THE AGENT with the to-task spec. It WRITES
     //    `work/tasks/backlog/*.md` task files (the STAGED area — NOT `work/tasks/ready/`,
     //    which is the agent-eligible pool the runner owns the promotion into; task
     //    `pre-backlog-staging-folder-and-promote-step-a`); it does NO git. We
@@ -155,10 +157,10 @@ export async function performTask(options) {
     const before = snapshotStagedTasks(cwd);
     // Also snapshot the POOL `work/tasks/ready/` BEFORE the agent runs: the runner's
     // final commit must scrub any agent writes there (an attempt to self-place into
-    // the pool, prd US #4) before `git add -A` would sweep them in.
+    // the pool, spec US #4) before `git add -A` would sweep them in.
     const poolBefore = snapshotPool(cwd);
     // Read the parent-spec self-pointer off `specFm.spec` (populated from the
-    // `spec:` key or the legacy `prd:` back-compat alias).
+    // `spec:` key).
     const prompt = buildTaskingSpec(slug, specFm.spec);
     let agent;
     try {
@@ -204,10 +206,10 @@ export async function performTask(options) {
             env: agentEnv,
             note,
         });
-        // DECOMPOSITION UNCLEAR: emit NO guessed tasks — route the held prd to
+        // DECOMPOSITION UNCLEAR: emit NO guessed tasks — route the held spec to
         // needs-attention with the questions as the reason. The lock release amends the
-        // `prd:<slug>` unified lock `active → stuck` (the tasking needs-attention surface
-        // is the stuck lock now — NO folder write; the prd body stays in `work/prds/ready/`).
+        // `spec:<slug>` unified lock `active → stuck` (the tasking needs-attention surface
+        // is the stuck lock now — NO folder write; the spec body stays in `work/specs/ready/`).
         if (loopDisposition.outcome === 'decomposition-unclear') {
             const reason = decompositionUnclearReason(slug, loopDisposition.specQuestions);
             if (useLock) {
@@ -242,7 +244,7 @@ export async function performTask(options) {
         }
     }
     // 4. The RUNNER commits the COMPLETING transition: drop the produced backlog
-    //    tasks IN + move the prd tasking/ -> prd-tasked/ (residence = tasked-ness) — now
+    //    tasks IN + move the spec specs/ready/ -> specs/tasked/ (residence = tasked-ness) — now
     //    through the SHARED integrate core (`--propose` PR / `--merge` main), NOT a
     //    direct commit to `main`. The agent never does git. (The backlog snapshot is
     //    taken AFTER any loop edits, so the runner integrates the IMPROVED tasks,
@@ -253,7 +255,7 @@ export async function performTask(options) {
     // `runner-deterministic-slice-placement-policy-and-precedence`). Resolve which
     // folder the runner lands the emitted tasks in BEFORE handing them to the
     // shared integrate band: precedence `explicit > untrusted-origin ⇒ staging >
-    // tasksLandIn > built-in (staging)`, all from unforgeable inputs (the prd's
+    // tasksLandIn > built-in (staging)`, all from unforgeable inputs (the spec's
     // stamped `originTrust:` + the resolved per-repo default + the operator's
     // explicit flag). The agent NEVER influences this; it always writes to
     // `work/tasks/backlog/`, and the runner redirects at `stage()` time.
@@ -274,11 +276,11 @@ export async function performTask(options) {
     if (useLock) {
         // READ-STABILITY BACKSTOP (the lock's content-identity check, now owned at the
         // integrate seam): the OUTPUT no longer rides the lock release, so the band
-        // below would otherwise rebase a concurrent edit of the held prd body CLEANLY
-        // into prd/ (a rename+edit merge) while the tasks were cut from the OLD body —
+        // below would otherwise rebase a concurrent edit of the held spec body CLEANLY
+        // into spec/ (a rename+edit merge) while the tasks were cut from the OLD body —
         // the exact silent stale-task drift the lock forbids
-        // (`work/notes/observations/tasking-lock-does-not-stabilise-prd-content.md`). So we
-        // compare the CURRENTLY held `work/prds/ready/<slug>.md` blob on the arbiter against
+        // (`work/notes/observations/tasking-lock-does-not-stabilise-spec-content.md`). So we
+        // compare the CURRENTLY held `work/specs/ready/<slug>.md` blob on the arbiter against
         // the snapshot the lock TOOK (`lockedBlob`); ANY change ⇒ STALE ⇒ fail loud,
         // touch NOTHING (the lock stays held; a human re-tasks or routes to
         // needs-attention). It is the SAME content-identity check `releaseTaskingLock`
@@ -287,16 +289,16 @@ export async function performTask(options) {
         const stale = await heldSpecIsStale(cwd, arbiter, slug, lockedBlob, env);
         if (stale) {
             const specRel = workItemRel('specs-ready', `${slug}.md`);
-            const message = `RELEASE CONFLICT for '${slug}': the prd was edited (${specRel} ` +
+            const message = `RELEASE CONFLICT for '${slug}': the spec was edited (${specRel} ` +
                 `changed on ${arbiter}/main) while the tasking lock was held. The tasking is ` +
-                `STALE — re-task from the edited prd or route it to needs-attention. ` +
+                `STALE — re-task from the edited spec or route it to needs-attention. ` +
                 `The arbiter was NOT modified (lock still held).`;
             note(message);
             return { exitCode: 4, outcome: 'stale', slug, message };
         }
         // Route the OUTPUT through the SHARED integrate back-half (task
-        // `slice-output-through-integration`): the produced backlog tasks + the prd
-        // lifecycle move (`work/prds/ready/ -> work/prds/tasked/`, residence = tasked-ness) integrate
+        // `slice-output-through-integration`): the produced backlog tasks + the spec
+        // lifecycle move (`work/specs/ready/ -> work/specs/tasked/`, residence = tasked-ness) integrate
         // via `performIntegration` honoring `--propose` (push the work branch + open a
         // PR, NO `main` touch) / `--merge` (land on `main`). Because the integrate-time
         // args resolve ONCE in the shared core, every `do task:` arg applies here by
@@ -331,18 +333,35 @@ export async function performTask(options) {
             reviewGate: options.reviewGate,
             reviewModel: options.acceptanceReviewModel,
             reviewMaxRounds: 1,
+            // The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
+            // threaded so a wide-matrix CI's raised cap reaches the tasking-
+            // transition's land tail too (task
+            // `thread-merge-retries-cross-task-and-ratify-default`). Unset ⇒ falls
+            // through to the engine default (byte-for-byte unchanged).
+            mergeRetries: options.mergeRetries,
             // The EXPLICITLY-chosen integrate mode proceeds AS-IS on an APPROVE — a
             // `--merge` tasking run lands on main, `--propose` opens a PR. The tasking
             // path's merge-vs-propose decision is the `integration` mode the user typed;
             // `merge` IS the auto-land mode, so a resolved `merge` is never downgraded.
             // The task gate family is `--review`/`--no-review`/`--review-model` only
-            // (prd US #6).
+            // (spec US #6).
             mode: options.integration ?? 'propose',
             noPR: options.noPR,
             providerInstance: options.providerInstance,
+            // PROPOSE-MODE PR BODY (task `slicing-pr-body-summary-threading`): mirror the
+            // BUILD path's body threading (`do.ts` — `body: agent.output`). The tasker
+            // agent produces no `LaunchResult.output` we can carry, but the slice-SET
+            // itself is a summary-worthy artifact: the emitted task slugs+titles, their
+            // coverage of the spec's user stories, the dependency graph (keystone +
+            // blockedBy edges), and any `needsAnswers` open questions the tasker review
+            // loop flagged. Compose it here and thread it into the shared core as `body`
+            // so the propose-mode PR carries the summary instead of degrading to
+            // `gh pr create --fill`. Empty-set (no emitted tasks) ⇒ undefined ⇒ the
+            // provider's `--fill` fallback (no regression on that edge).
+            body: composeTaskingProposeBody(slug, emitTasks),
             type: 'tasking',
             lifecycle: {
-                // Read the PR title / commit summary from the held prd (before it moves).
+                // Read the PR title / commit summary from the held spec (before it moves).
                 titlePath: workItemPath(cwd, 'specs-ready', slug),
                 commitTag: 'tasked',
                 stage: () => stageTaskingLifecycle({
@@ -367,9 +386,9 @@ export async function performTask(options) {
         // the review BEFORE the stage/integrate and did NOT integrate the tasks
         // (correct). The CORRECT task-path destination is the SAME needs-attention
         // route the lock release owns for the decomposition-unclear verdict: it amends
-        // the `prd:<slug>` unified lock `active -> stuck` with the block reason (the
+        // the `spec:<slug>` unified lock `active -> stuck` with the block reason (the
         // tasking needs-attention surface is the stuck lock now — NO folder write; the
-        // prd body stays in `work/prds/ready/`). So on a block we route the held prd to
+        // spec body stays in `work/specs/ready/`). So on a block we route the held spec to
         // needs-attention THROUGH the lock release — the set never lands.
         if (core.outcome === 'review-blocked') {
             const reason = taskGateBlockedReason(slug, core.reviewBlockReason);
@@ -396,9 +415,9 @@ export async function performTask(options) {
         }
         if (core.outcome === 'review-unparseable') {
             // The task-set acceptance gate RAN but its verdict was UNPARSEABLE (malformed
-            // JSON). Route the held prd to needs-attention through the SAME lock-release
+            // JSON). Route the held spec to needs-attention through the SAME lock-release
             // seam the block path uses (the tasking needs-attention surface is the stuck
-            // `prd:<slug>` lock; no folder write). It is NOT a block (the gate output was
+            // `spec:<slug>` lock; no folder write). It is NOT a block (the gate output was
             // unreadable) — record it as the transient-infra-class re-run signal so the
             // stuck reason reads correctly; nothing landed.
             const reason = `The task acceptance gate for '${slug}' produced an UNPARSEABLE verdict ` +
@@ -425,8 +444,8 @@ export async function performTask(options) {
             };
         }
         if (core.outcome === 'completed') {
-            // The durable `prd → prd-tasked` `main` move landed through the shared integrate
-            // core (the body moved straight from `work/prds/ready/` — no transient `tasking/`
+            // The durable `specs/ready → specs/tasked` `main` move landed through the shared integrate
+            // core (the body moved straight from `work/specs/ready/` — no transient `tasking/`
             // marker). The completing commit is owned by the integrate band, NOT
             // `releaseTaskingLock`, so the unified per-item lock that `acquireTaskingLock`
             // took is released HERE (delete the ref). A
@@ -443,12 +462,12 @@ export async function performTask(options) {
         return integrationToTaskResult(core, { slug, emitted, loop: loopTag });
     }
     // HUMAN, no-lock path: the human commits on `main` directly (the runner does
-    // not own the human's git). We report the produced tasks; moving the prd into
-    // `work/prds/tasked/` (residence = tasked-ness) and committing is the human's to
+    // not own the human's git). We report the produced tasks; moving the spec into
+    // `work/specs/tasked/` (residence = tasked-ness) and committing is the human's to
     // do, as with the human `complete`.
     const message = `Tasked '${slug}' -> ${emitted.length} backlog task` +
         `${emitted.length === 1 ? '' : 's'} (human path, no lock). Inspect + commit ` +
-        `the produced files (and move the prd into work/prds/tasked/) yourself.`;
+        `the produced files (and move the spec into work/specs/tasked/) yourself.`;
     note(message);
     return {
         exitCode: 0,
@@ -485,11 +504,11 @@ function releaseFailureToResult(released, slug) {
  * (propose pushed the work branch + opened a PR / merge landed on `main`) the
  * tasking is `tasked`. The band's FAILURE outcomes are reported on the tasking
  * contract: a `rebase-conflict` against a concurrently-advanced `main` maps to
- * `stale` (exit 4) — the tasking analogue of "the held prd moved under us"; a
+ * `stale` (exit 4) — the tasking analogue of "the held spec moved under us"; a
  * a `gate-failed` cannot occur (the tasking path passes `skipVerify`) but maps to
  * a usage error defensively. A `review-blocked` (the task-SET ACCEPTANCE GATE
  * blocked the set, task `slice-acceptance-gate`) is handled by `performTask`
- * BEFORE this mapper — it routes the held prd to needs-attention via
+ * BEFORE this mapper — it routes the held spec to needs-attention via
  * the lock release (the task-path needs-attention route) — so it never reaches
  * here; it is mapped defensively to a usage error if it ever does.
  */
@@ -501,7 +520,7 @@ function integrationToTaskResult(core, ctx) {
             : 'opened a PR carrying them (main untouched)';
         const message = `Tasked '${slug}' -> ${emitted.length} backlog task` +
             `${emitted.length === 1 ? '' : 's'}; the runner integrated the transition ` +
-            `through the shared core (moved work/prds/ready/ -> work/prds/tasked/, the ` +
+            `through the shared core (moved work/specs/ready/ -> work/specs/tasked/, the ` +
             `tasked resting state) and ${landed}.`;
         return { exitCode: 0, outcome: 'tasked', slug, emitted, loop, message };
     }
@@ -512,7 +531,7 @@ function integrationToTaskResult(core, ctx) {
             slug,
             message: core.reason ??
                 `Integrating the tasking of '${slug}' conflicted against the latest ` +
-                    `${slug} main — the tasking is stale; re-task from the current prd.`,
+                    `${slug} main — the tasking is stale; re-task from the current spec.`,
         };
     }
     return {
@@ -526,16 +545,16 @@ function integrationToTaskResult(core, ctx) {
 /**
  * ONBOARD the tasking work onto a `work/<slug>` branch cut from the freshly-
  * fetched `<arbiter>/main` (task `slice-output-through-integration`). Called
- * AFTER the tasking lock is held, so the branch's base HOLDS the prd in
- * `work/prds/ready/` (the lock no longer moves the body) — the lifecycle stage then moves
- * it `prd/ -> prd-tasked/` ON THIS BRANCH and the shared integrate core lands it. A
+ * AFTER the tasking lock is held, so the branch's base HOLDS the spec in
+ * `work/specs/ready/` (the lock no longer moves the body) — the lifecycle stage then moves
+ * it `specs/ready/ -> specs/tasked/` ON THIS BRANCH and the shared integrate core lands it. A
  * pre-existing local `work/<slug>` (a re-run) is force-recreated off fresh main.
  * The agent runs in-place on this branch (branch ≠ worktree).
  */
 async function switchToWorkBranch(cwd, arbiter, slug, env) {
     // The tasking path is the parent-spec namespace (`do spec:<slug>`): the branch
     // is `work/spec-<slug>`, distinct from a same-slug task-build's `work/task-<slug>`.
-    // MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
+    // MIGRATE step (spec `prd-to-spec-vocabulary-cutover-and-migration-command`):
     // MINT the work-branch under the `spec` namespace token (`workBranchRef` still
     // parses the legacy `work/prd-<slug>` form, so in-flight branches keep resolving).
     const branch = workBranchRef('spec', slug);
@@ -545,8 +564,8 @@ async function switchToWorkBranch(cwd, arbiter, slug, env) {
 /**
  * The READ-STABILITY content-identity STALE CHECK (the lock's backstop, owned at
  * the integrate seam now that the OUTPUT no longer rides the lock release): true
- * iff the CURRENTLY held `work/prds/ready/<slug>.md` blob on `<arbiter>/main` DIFFERS
- * from the snapshot the lock TOOK (`lockedBlob`, read from `work/prds/ready/<slug>.md` at
+ * iff the CURRENTLY held `work/specs/ready/<slug>.md` blob on `<arbiter>/main` DIFFERS
+ * from the snapshot the lock TOOK (`lockedBlob`, read from `work/specs/ready/<slug>.md` at
  * acquire). ANY change = a concurrent edit under the lock = the tasking is STALE.
  * Stronger than a textual rebase conflict (which a rename+edit merge can apply
  * CLEANLY). When `lockedBlob` is absent (never, in production) it reads as
@@ -558,7 +577,7 @@ async function heldSpecIsStale(cwd, arbiter, slug, lockedBlob, env) {
     }
     await gitHard(['fetch', '--quiet', arbiter], cwd, env);
     const held = await gitSoft(['rev-parse', `${arbiter}/main:${workFolderRel('specs-ready')}/${slug}.md`], cwd, env);
-    // The prd being absent (already tasked/moved) is NOT this check's concern
+    // The spec being absent (already tasked/moved) is NOT this check's concern
     // (the integrate's rebase/push surfaces that); only a CHANGED held blob is stale.
     if (held.status !== 0) {
         return false;
@@ -567,28 +586,28 @@ async function heldSpecIsStale(cwd, arbiter, slug, lockedBlob, env) {
 }
 /**
  * STAGE the tasking lifecycle into the index on the `work/<slug>` branch (the
- * {@link performIntegration} lifecycle seam): move the held prd
- * `git mv work/prds/ready/<slug>.md -> work/prds/tasked/<slug>.md` (the TASKED resting
+ * {@link performIntegration} lifecycle seam): move the held spec
+ * `git mv work/specs/ready/<slug>.md -> work/specs/tasked/<slug>.md` (the TASKED resting
  * state — the build-machine `done/` analogue, the SOURCE OF TRUTH for tasked-ness),
  * and write+`git add` the produced `work/tasks/backlog/*.md` files. The band's subsequent
  * `git add -A` + atomic commit folds this AND the agent's uncommitted backlog writes
  * into ONE runner-owned commit (the agent never does git).
  *
- * TASK `prd-sliced-folder-step-a` (prd `slicing-coherence` US #8): the lifecycle
- * destination is `work/prds/tasked/` (NOT back to `work/prds/ready/`) — `prd-tasked/`
+ * TASK `prd-sliced-folder-step-a` (spec `slicing-coherence` US #8): the lifecycle
+ * destination is `work/specs/tasked/` (NOT back to `work/specs/ready/`) — `specs/tasked/`
  * residence IS tasked-ness (like `done/` for tasks, with no `done:` marker). The
  * `tasked:` frontmatter marker was removed entirely in `remove-sliced-marker-step-b`
- * (sequenced last): residence in `work/prds/tasked/` is now the sole signal.
+ * (sequenced last): residence in `work/specs/tasked/` is now the sole signal.
  */
 async function stageTaskingLifecycle(params) {
     const { cwd, slug, emitTasks, poolBefore, placementDir, placementReason, note, env, } = params;
     const spec = workItemRel('specs-ready', `${slug}.md`);
     const specTasked = workItemRel('specs-tasked', `${slug}.md`);
     // PROPAGATE the origin-trust PROVENANCE (task
-    // `untrusted-origin-forces-build-propose`): read the held prd's `origin`/
+    // `untrusted-origin-forces-build-propose`): read the held spec's `origin`/
     // `originTrust` stamp BEFORE the move, so each emitted task can carry it. A
     // task's risk is its BUILD; the stamp must reach the task so the build
-    // transition can force `propose` for untrusted-origin work. An UNSTAMPED prd (a
+    // transition can force `propose` for untrusted-origin work. An UNSTAMPED spec (a
     // human/local-authored one ⇒ trusted) propagates nothing — the normal path is
     // untouched.
     const specAbs = join(cwd, spec);
@@ -596,18 +615,18 @@ async function stageTaskingLifecycle(params) {
         ? parseFrontmatter(readFileSync(specAbs, 'utf8'))
         : { origin: undefined, originTrust: undefined };
     if (placementReason === 'untrusted-origin') {
-        note(`Untrusted-origin prd '${slug}': forcing the emitted tasks STAGED ` +
+        note(`Untrusted-origin spec '${slug}': forcing the emitted tasks STAGED ` +
             `(${placementDir}/) regardless of tasksLandIn (a human promotes ` +
             'them into work/tasks/ready/). Pass --tasks-land-in <where> to override.');
     }
-    // Move the held prd prd/ -> prd-tasked/ (the TASKED resting state — folder =
-    // source of truth, like done/ for tasks). This is the DURABLE `prd → prd-tasked`
+    // Move the held spec specs/ready/ -> specs/tasked/ (the TASKED resting state — folder =
+    // source of truth, like done/ for tasks). This is the DURABLE `specs/ready → specs/tasked`
     // success move, owned by THIS transition's commit (the lock no longer moved the
-    // body, so the source is `work/prds/ready/`, never `work/tasking/`).
+    // body, so the source is `work/specs/ready/`, never `work/tasking/`).
     mkdirSync(dirname(join(cwd, specTasked)), { recursive: true });
     await gitHard(['mv', spec, specTasked], cwd, env);
     await gitHard(['add', '--', specTasked], cwd, env);
-    // **POOL-PLACEMENT FENCE (prd US #4 / governing ADR
+    // **POOL-PLACEMENT FENCE (spec US #4 / governing ADR
     // `placement-is-runner-deterministic-humanonly-is-agent-judgement`).** The
     // agent ALWAYS writes to the STAGING folder (`work/tasks/backlog/`); the POOL
     // (`work/tasks/ready/`) is the agent-eligible pool the runner owns the promotion
@@ -644,11 +663,11 @@ async function stageTaskingLifecycle(params) {
  * Revert any change/addition the agent made to the POOL `work/tasks/ready/` during a
  * tasking run. The agent's STAGING folder is `work/tasks/backlog/`; a write to the
  * pool is an attempt to self-place into the agent-eligible pool the runner owns
- * the promotion into (prd US #4 / governing ADR). Compared to the `poolBefore`
+ * the promotion into (spec US #4 / governing ADR). Compared to the `poolBefore`
  * snapshot (the branch-base state of `work/tasks/ready/`, taken BEFORE the agent
  * ran), any new file is removed from the worktree and any changed file is
  * checked back out to HEAD — so the subsequent `git add -A` cannot land it. The
- * runner's commit then carries ONLY the explicit `pre-backlog/` placement.
+ * runner's commit then carries ONLY the explicit `tasks/backlog/` placement.
  */
 async function scrubPoolDrift(cwd, poolBefore, env) {
     const dir = workFolderPath(cwd, 'tasks-ready');
@@ -692,26 +711,27 @@ async function gitHard(args, cwd, env) {
 /**
  * Build the needs-attention REASON for a task-SET ACCEPTANCE GATE block (task
  * `slice-acceptance-gate`): the fresh-context review of the produced set returned
- * `block`, so the prd is routed to `work/needs-attention/` with the review's
- * blocking findings as the body prose and NO tasks landed. Takes the core's
+ * `block`, so the spec is marked stuck on its per-item lock (post lock-cutover —
+ * `state: stuck` with this reason on the lock entry, no `work/needs-attention/`
+ * folder write) and NO tasks land. Takes the core's
  * structured `reviewBlockReason` (the gate's blocking findings); falls back to a
  * generic line when absent. DISTINCT from the improver loop's
  * {@link decompositionUnclearReason} (which carries the loop's open questions).
  */
 function taskGateBlockedReason(slug, findingsReason) {
     const head = `The task acceptance gate (fresh-context review of the produced SET) blocked ` +
-        `'${slug}'. The prd is routed to needs-attention with no tasks landed; a human ` +
+        `'${slug}'. The spec is routed to needs-attention with no tasks landed; a human ` +
         `must resolve the blocking findings, then re-task.`;
     return findingsReason ? `${head}\n\n${findingsReason}` : head;
 }
 /**
  * Build the needs-attention REASON for a decomposition-unclear loop verdict (the
- * prd is routed to `work/needs-attention/` with these open questions, no guessed
- * tasks). Prose only — recorded as the prd's needs-attention body block.
+ * spec is marked stuck on its per-item lock with these open questions, no guessed
+ * tasks). Prose only — recorded as the spec's stuck-lock reason.
  */
 function decompositionUnclearReason(slug, questions) {
     const head = `The tasker review→edit loop could not converge on a sound decomposition of ` +
-        `'${slug}' (--tasker-loop-max exhausted with unresolved blockers). The prd is routed ` +
+        `'${slug}' (--tasker-loop-max exhausted with unresolved blockers). The spec is routed ` +
         `to needs-attention with no guessed tasks; a human must resolve:`;
     const body = questions.length > 0
         ? questions.map((q) => `- ${q}`).join('\n')
@@ -759,8 +779,8 @@ function appendQuestionsBlock(content, questions) {
 /**
  * Resolve the AGENT tasking gate for `slug`: the pure predicate
  * (`needsAnswers !== true && humanOnly !== true && autoTask`) plus the
- * cross-prd `taskedAfter` ordering, resolved against `work/prds/tasked/` residence of
- * the prds present in the checkout.
+ * cross-spec `taskedAfter` ordering, resolved against `work/specs/tasked/` residence of
+ * the specs present in the checkout.
  */
 function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
     return resolveTaskingEligibility({
@@ -772,17 +792,17 @@ function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
         explicit,
     });
 }
-/** Build an HONEST gate-refusal message naming WHY the agent skipped the prd. */
+/** Build an HONEST gate-refusal message naming WHY the agent skipped the spec. */
 function gateRefusalReason(slug, specFm, eligibility, options) {
     const reasons = [];
     if (specFm.humanOnly === true) {
-        reasons.push('the prd is humanOnly (a human must drive its tasking)');
+        reasons.push('the spec is humanOnly (a human must drive its tasking)');
     }
     if (specFm.needsAnswers === true) {
-        reasons.push('the prd has needsAnswers (open questions block auto-tasking)');
+        reasons.push('the spec has needsAnswers (open questions block auto-tasking)');
     }
     // The autoTask POLICY only refuses on the NON-explicit (auto-pick pool) path:
-    // an explicitly-named `do prd:<slug>` is authorized by the naming itself (the
+    // an explicitly-named `do spec:<slug>` is authorized by the naming itself (the
     // build path's autoBuild precedent), so the policy is never the reason there.
     if (options.explicit !== true &&
         specFm.humanOnly !== true &&
@@ -791,18 +811,18 @@ function gateRefusalReason(slug, specFm, eligibility, options) {
         reasons.push("the repo's autoTask policy is off");
     }
     if (!eligibility.taskedAfter.satisfied) {
-        reasons.push(`taskedAfter prd(s) not yet tasked: ${eligibility.taskedAfter.missing.join(', ')}`);
+        reasons.push(`taskedAfter spec(s) not yet tasked: ${eligibility.taskedAfter.missing.join(', ')}`);
     }
     const why = reasons.length > 0 ? reasons.join('; ') : 'the tasking gate refused';
     return `Skipped tasking '${slug}': ${why}.`;
 }
 /**
- * Read the set of slugs whose prds are already TASKED in this checkout — RESIDENCE
- * in `work/prds/tasked/` (the tasked resting state, task `prd-sliced-folder-step-a`
- * / prd `slicing-coherence` US #9), the build-machine `done/` analogue. The FOLDER
+ * Read the set of slugs whose specs are already TASKED in this checkout — RESIDENCE
+ * in `work/specs/tasked/` (the tasked resting state, task `prd-sliced-folder-step-a`
+ * / spec `slicing-coherence` US #9), the build-machine `done/` analogue. The FOLDER
  * is the source of truth; the `tasked:` frontmatter marker was removed entirely in
  * `remove-sliced-marker-step-b` and is NOT consulted. So `taskedAfter` resolves
- * against `prd-tasked/` residence
+ * against `specs/tasked/` residence
  * (mirroring `blockedBy` -> `done/`). A missing folder reads as empty. The slug is
  * read from each file's frontmatter `slug:`, falling back to the filename — the same
  * shape the task readers use.
@@ -820,7 +840,7 @@ function readTaskedSlugs(cwd) {
 /**
  * Build the tasking PROMPT: instruct a fresh-context agent to apply the
  * **tasking discipline** (`work/protocol/TASKING-PROTOCOL.md`) to the held
- * prd at `work/prds/ready/<slug>.md` and to EMIT tracer-bullet vertical
+ * spec at `work/specs/ready/<slug>.md` and to EMIT tracer-bullet vertical
  * tasks under `work/tasks/backlog/`. The discipline body (the tracer-bullet
  * rules, the two-axis gate guidance, the confidence check, file-orthogonality,
  * the emitted task shape) lives in `TASKING-PROTOCOL.md` — NOT inlined here
@@ -829,24 +849,26 @@ function readTaskedSlugs(cwd) {
  * task-template.md`); the doc DESCRIBES it (D2).
  *
  * This builder owns ONLY the PER-BUILDER framing: who you are (a fresh-context
- * tasker for ONE prd), where the held prd is, where the emitted task files
+ * tasker for ONE spec), where the held spec is, where the emitted task files
  * MUST land (the staging folder, never the pool), and the runner-owns-git
  * boundary on the agent path. The shared discipline body is NOT duplicated
  * here.
  */
 function buildTaskingSpec(slug, _spec) {
+    const specReady = workFolderRel('specs-ready');
+    const specTasked = workFolderRel('specs-tasked');
     return [
-        `You are a FRESH-CONTEXT tasker for the prd \`work/prds/ready/${slug}.md\`.`,
+        `You are a FRESH-CONTEXT tasker for the spec \`${specReady}/${slug}.md\`.`,
         `Apply the tasking discipline defined in \`work/protocol/TASKING-PROTOCOL.md\``,
         `(the in-band, protocol-native tasking protocol every set-up repo carries; the`,
-        `human-facing pointer is \`skills/to-task/SKILL.md\`) to this ONE prd:`,
+        `human-facing pointer is \`skills/to-task/SKILL.md\`) to this ONE spec:`,
         `decompose it into independently-grabbable, tracer-bullet vertical tasks.`,
-        `Read the prd fully first.`,
+        `Read the spec fully first.`,
         ``,
         `The discipline rules — the tracer-bullet test, the two-axis gate guidance`,
         `(\`humanOnly\` is NARROW; \`needsAnswers\` flags genuine uncertainty), the`,
         `confidence check that REPLACES the human-quiz step when no human is present,`,
-        `the file-orthogonality preference, the prd-vs-task gate disjointness, and`,
+        `the file-orthogonality preference, the spec-vs-task gate disjointness, and`,
         `the emitted task shape — ALL live in that doc. Read them there.`,
         ``,
         `No human is present, so apply the CONFIDENCE CHECK (\`TASKING-PROTOCOL.md\``,
@@ -854,7 +876,7 @@ function buildTaskingSpec(slug, _spec) {
         `granularity, dependency order, a gate, or a seam is genuinely unresolved, set`,
         `\`needsAnswers: true\` on the specific uncertain task (questions in its body)`,
         `rather than guessing — or, if the whole decomposition is unclear, stop and`,
-        `route the prd to needs-attention with the questions.`,
+        `route the spec to needs-attention with the questions.`,
         ``,
         `WRITE EVERY emitted task file under \`${STAGED_TASKS_DIR}/\` (the STAGING folder)`,
         `— NEVER \`work/tasks/ready/\`. \`work/tasks/ready/\` is the agent-eligible POOL and`,
@@ -862,12 +884,12 @@ function buildTaskingSpec(slug, _spec) {
         `folder is \`work/tasks/backlog/\`. A write outside the staging folder is dropped`,
         `by the runner-deterministic placement resolver.`,
         ``,
-        `Set each task's \`prd:\` field to the source prd slug (\`${slug}\`) so the`,
-        `link back to the prd survives.`,
+        `Set each task's \`spec:\` field to the source spec slug (\`${slug}\`) so the`,
+        `link back to the spec survives.`,
         ``,
         `Do NOT perform any git operations — do not stage, commit, push, or move any`,
         `files. The RUNNER owns every git-state transition (it commits the produced`,
-        `tasks, releases the tasking lock, and moves the prd into \`work/prds/tasked/\`).`,
+        `tasks, releases the tasking lock, and moves the spec into \`${specTasked}/\`).`,
     ].join('\n');
 }
 /** Run the task agent. Prefers the injected runner; else the harness seam. */
@@ -937,6 +959,198 @@ function collectEmittedTasks(cwd, relPaths) {
     }
     return out;
 }
+/**
+ * Compose the propose-mode PR BODY for a slice-set (task
+ * `slicing-pr-body-summary-threading`): mirror the BUILD path's body threading
+ * (`do.ts` — `body: agent.output`) with a summary drawn from what the tasker
+ * ALREADY has in hand — the emitted task files. The shared
+ * {@link composeProposeBody} then wraps this prose with its runner-owned header.
+ *
+ * Sections (all suppressed when empty, so the body stays honest):
+ *   1. A lead line naming the source spec + emitted task count.
+ *   2. **Tasks** — one bullet per task: `slug — title`, plus `covers:` (which
+ *      spec user stories it maps to), `blockedBy:`, and `needsAnswers` if set.
+ *   3. **Dependency graph** — the KEYSTONE(S) (tasks whose `blockedBy` names no
+ *      other task in this set, so they land first) and the `blockedBy` edges.
+ *   4. **Needs answers** — any open questions the tasker review→edit loop
+ *      appended under `## Open questions` on `needsAnswers: true` tasks, so the
+ *      deferred seams are visible on the PR (not buried in task bodies).
+ *
+ * Returns `undefined` for the empty set (no emitted tasks) so the provider's
+ * `gh pr create --fill` fallback still applies on that edge (matches the build
+ * path's absent-body behaviour).
+ */
+export function composeTaskingProposeBody(specSlug, emitTasks) {
+    const entries = Object.entries(emitTasks);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    const tasks = entries
+        .map(([rel, content]) => parseTaskSummary(rel, content))
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+    const setSlugs = new Set(tasks.map((t) => t.slug));
+    const lines = [];
+    const n = tasks.length;
+    lines.push(`Auto-tasked \`${specSlug}\` into ${n} backlog task${n === 1 ? '' : 's'}.`);
+    lines.push('');
+    lines.push('## Tasks');
+    lines.push('');
+    for (const t of tasks) {
+        lines.push(`- **${t.slug}** — ${t.title}`);
+        if (t.covers.length > 0) {
+            lines.push(`  - covers: ${t.covers.map((c) => `US #${c}`).join(', ')}`);
+        }
+        if (t.blockedBy.length > 0) {
+            lines.push(`  - blockedBy: ${t.blockedBy.join(', ')}`);
+        }
+        if (t.needsAnswers) {
+            lines.push('  - needsAnswers: true');
+        }
+    }
+    // Dependency graph: keystone(s) are tasks whose blockedBy names no OTHER
+    // member of this set (an external blocker — e.g. a task already in `done/` —
+    // does not prevent this set-relative starting point); the edges list every
+    // set-internal `blockedBy` link so a reviewer can trace the ordering.
+    const keystones = tasks.filter((t) => t.blockedBy.every((b) => !setSlugs.has(b)));
+    const edges = tasks.flatMap((t) => t.blockedBy.filter((b) => setSlugs.has(b)).map((b) => `${t.slug} ← ${b}`));
+    if (keystones.length > 0 || edges.length > 0) {
+        lines.push('');
+        lines.push('## Dependency graph');
+        lines.push('');
+        if (keystones.length > 0) {
+            const word = keystones.length === 1 ? 'Keystone' : 'Keystones';
+            lines.push(`- ${word}: ${keystones.map((k) => k.slug).join(', ')}`);
+        }
+        for (const edge of edges) {
+            lines.push(`- ${edge}`);
+        }
+    }
+    const uncertain = tasks.filter((t) => t.needsAnswers);
+    if (uncertain.length > 0) {
+        lines.push('');
+        lines.push('## Needs answers');
+        lines.push('');
+        for (const t of uncertain) {
+            lines.push(`- **${t.slug}**:`);
+            if (t.openQuestions.length === 0) {
+                lines.push('  - (no specific questions surfaced)');
+                continue;
+            }
+            for (const q of t.openQuestions) {
+                lines.push(`  - ${q}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Parse one emitted task file into a {@link TaskSummary}. Uses
+ * {@link parseFrontmatter} for the shared fields; scans the raw frontmatter
+ * block for `covers:` (not currently modelled on the parser's typed shape) and
+ * the body for a trailing `## Open questions` bullet list (the loop's
+ * uncertain-task disposition sink, see {@link appendQuestionsBlock}).
+ */
+function parseTaskSummary(rel, content) {
+    const fm = parseFrontmatter(content);
+    const slug = fm.slug ?? basename(rel).replace(/\.md$/i, '');
+    const title = readTitleField(content) ?? slug;
+    return {
+        slug,
+        title,
+        covers: readCoversField(content),
+        blockedBy: fm.blockedBy,
+        needsAnswers: fm.needsAnswers === true,
+        openQuestions: readOpenQuestions(content),
+    };
+}
+/**
+ * Extract the `title:` scalar from the raw frontmatter block (not on
+ * {@link parseFrontmatter}'s typed shape). Missing / malformed ⇒ `undefined`.
+ * Comment-tolerant: a trailing `# ...` after an UNQUOTED value is stripped.
+ */
+function readTitleField(content) {
+    const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+    if (!normalized.startsWith('---\n')) {
+        return undefined;
+    }
+    const lines = normalized.split('\n');
+    const closing = lines.indexOf('---', 1);
+    if (closing === -1) {
+        return undefined;
+    }
+    for (let i = 1; i < closing; i++) {
+        const m = lines[i].match(/^title:\s*(.*)$/);
+        if (!m)
+            continue;
+        let value = m[1].trim();
+        if (value === '')
+            return undefined;
+        // Quoted ⇒ return inner text verbatim; unquoted ⇒ strip trailing `# ...`.
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            return value.slice(1, -1);
+        }
+        const hash = value.indexOf('#');
+        if (hash !== -1)
+            value = value.slice(0, hash).trimEnd();
+        return value === '' ? undefined : value;
+    }
+    return undefined;
+}
+/**
+ * Extract the `covers: [...]` inline-list values from the raw frontmatter block
+ * of a task (not on {@link parseFrontmatter}'s typed shape, so we scan the raw
+ * fence here). Missing / malformed / empty ⇒ `[]`. Comment-tolerant (a trailing
+ * `# ...` after the `]` is ignored, matching the house style on `blockedBy: []
+ * # startable now`).
+ */
+function readCoversField(content) {
+    const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+    if (!normalized.startsWith('---\n')) {
+        return [];
+    }
+    const lines = normalized.split('\n');
+    const closing = lines.indexOf('---', 1);
+    if (closing === -1) {
+        return [];
+    }
+    for (let i = 1; i < closing; i++) {
+        const line = lines[i];
+        const m = line.match(/^covers:\s*\[([^\]]*)\]/);
+        if (!m)
+            continue;
+        return m[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+            .filter((s) => s !== '');
+    }
+    return [];
+}
+/**
+ * Extract the bullets under a trailing `## Open questions` heading in a task
+ * body — the tasker review loop's uncertain-task sink (see
+ * {@link appendQuestionsBlock}). Returns `[]` when no such block exists.
+ */
+function readOpenQuestions(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const idx = normalized.lastIndexOf(`\n${OPEN_QUESTIONS_HEADING}`);
+    if (idx === -1) {
+        return [];
+    }
+    const tail = normalized.slice(idx + 1);
+    const lines = tail.split('\n').slice(1);
+    const questions = [];
+    for (const raw of lines) {
+        const line = raw.trimEnd();
+        if (line === '')
+            continue;
+        const m = line.match(/^- (.*)$/);
+        if (!m)
+            break;
+        questions.push(m[1]);
+    }
+    return questions;
+}
 /** List `*.md` files in `dir`, sorted; an absent dir reads as empty. */
 function listMarkdown(dir) {
     let entries;