dorfl 0.14.2 → 0.15.0

package/dist/tasking.js

@@ -1,12 +1,14 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { parseFrontmatter } from './frontmatter.js';
+import { parseFrontmatter, unquoteYamlScalar } from './frontmatter.js';
 import { runAsync } from './git.js';
 import { workFolderRel, workFolderPath, workItemPath, workItemRel, isWorkItemFile, } from './work-layout.js';
-import { performIntegration, } from './integration-core.js';
+import { performIntegration, proposePointer, } from './integration-core.js';
+import { proposeRequestNotOpened } from './integrator.js';
 import { resolveTaskingEligibility, } from './tasking-eligibility.js';
 import { acquireTaskingLock, releaseTaskingLock, } from './tasking-lock.js';
 import { releaseItemLock } from './item-lock.js';
+import { refWrite } from './ref-write.js';
 import { NullHarness } from './harness.js';
 import { launchWithOptionalWatch } from './agent-launch.js';
 import { placementFolder, resolvePlacement } from './placement.js';
@@ -162,33 +164,19 @@ export async function performTask(options) {
     if (useLock) {
         await switchToWorkBranch(cwd, arbiter, slug, env);
     }
-    // 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
-    //    snapshot the staged-tasks folder before/after so the runner (not the
-    //    agent) captures + commits exactly what was produced.
-    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, 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).
-    const prompt = buildTaskingSpec(slug, specFm.spec);
-    let agent;
-    try {
-        agent = await runTaskAgent(options, cwd, prompt, slug);
-    }
-    catch (err) {
-        agent = {
-            ok: false,
-            detail: err instanceof Error ? err.message : String(err),
-        };
-    }
-    if (!agent.ok) {
-        const detail = agent.detail ?? `the agent failed to task '${slug}'.`;
-        let message = `Agent failed tasking '${slug}' (${detail}).`;
+    // 3. + 3.5 THE AGENT HALF (task `ci-split-tasking`): the tasker agent and the
+    //    tasker review→edit→converge loop. Shared, unchanged, with the CI agent
+    //    phase (`ci-phase-tasking.ts`), which runs this SAME half in the job that
+    //    holds no write token and hands the result over instead of integrating.
+    const half = await runTaskingAgentHalf(options, {
+        cwd,
+        slug,
+        specFm,
+        doer,
+        note,
+    });
+    if (half.kind === 'agent-failed') {
+        let message = `Agent failed tasking '${slug}' (${half.detail}).`;
         // RELEASE THE LOCK THE FAILED RUN TOOK (observation
         // `crashed-do-spec-strands-a-tasking-lock-no-verb-releases`).
         //
@@ -243,13 +231,164 @@ export async function performTask(options) {
         note(message);
         return { exitCode: 1, outcome: 'agent-failed', slug, message };
     }
+    if (half.kind === 'review-leg-failed') {
+        // REVIEW-LEG FAILURE handling (observation
+        // `tasker-review-edits-payload-caps-the-verdict-response`): PERSIST the
+        // candidate tasks, and BOUNCE through the SAME surface the
+        // decomposition-unclear path uses (release the lock + a question sidecar).
+        // NEVER a silent approve — a parse failure is always a needs-attention route.
+        const candidatePaths = await persistTaskingCandidates(cwd, slug, half.before, arbiter, env, note);
+        const reason = reviewFailureReason(slug, half.error, candidatePaths);
+        const message = reviewFailureMessage(slug, half.error);
+        if (useLock) {
+            return await surfaceTaskingBlock({
+                slug,
+                cwd,
+                arbiter,
+                reason,
+                message,
+                lockedBlob,
+                release: lock.release,
+                mode: resolvedMode,
+                provider: options.providerInstance,
+                env,
+                note,
+            });
+        }
+        note(reason);
+        // Human, no-lock path: a clean park-for-human is a success terminal (exit 0).
+        return { exitCode: 0, outcome: 'needs-attention', slug, message };
+    }
+    if (half.kind === 'decomposition-unclear') {
+        // DECOMPOSITION UNCLEAR: emit NO guessed tasks — route the held spec to
+        // needs-attention with the questions as the reason. The lock release surfaces
+        // the spec (a question sidecar + `needsAnswers: true` on main) and releases the
+        // `spec:<slug>` lock; the spec body stays in `work/specs/ready/`.
+        const reason = decompositionUnclearReason(slug, half.questions);
+        if (useLock) {
+            return await surfaceTaskingBlock({
+                slug,
+                cwd,
+                arbiter,
+                reason,
+                message: half.message,
+                lockedBlob,
+                release: lock.release,
+                mode: resolvedMode,
+                provider: options.providerInstance,
+                env,
+                note,
+            });
+        }
+        note(half.message);
+        // Human, no-lock path: nothing to release/surface via the seam; a clean
+        // park-for-human is still a success terminal (exit 0).
+        return {
+            exitCode: 0,
+            outcome: 'needs-attention',
+            slug,
+            message: half.message,
+        };
+    }
+    // 4. The RUNNER commits the COMPLETING transition: drop the produced backlog
+    //    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,
+    //    not the pre-loop candidates.)
+    const stagedEmitted = newOrChangedStagedTasks(cwd, half.before);
+    const emitTasks = collectEmittedTasks(cwd, stagedEmitted);
+    const placementDir = taskPlacementDir(options, specFm);
+    const loopTag = half.loopTag;
+    if (useLock) {
+        return await integrateTaskingCandidates({
+            slug,
+            cwd,
+            arbiter,
+            stagedEmitted,
+            emitTasks,
+            poolBefore: half.poolBefore,
+            placementDir,
+            loopTag,
+            lockedBlob,
+            release: lock.release,
+            mode: resolvedMode,
+            review: options.review,
+            reviewGate: options.reviewGate,
+            acceptanceReviewModel: options.acceptanceReviewModel,
+            mergeRetries: options.mergeRetries,
+            noPR: options.noPR,
+            providerInstance: options.providerInstance,
+            env,
+            agentEnv,
+            note,
+        });
+    }
+    // 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 spec into
+    // `work/specs/tasked/` (residence = tasked-ness) and committing is the human's to
+    // do, as with the human `complete`.
+    const emitted = stagedEmitted.map((rel) => `${placementDir}/${basename(rel)}`);
+    const message = `Tasked '${slug}' -> ${emitted.length} backlog task` +
+        `${emitted.length === 1 ? '' : 's'} (human path, no lock). Inspect + commit ` +
+        `the produced files (and move the spec into work/specs/tasked/) yourself.`;
+    note(message);
+    return {
+        exitCode: 0,
+        outcome: 'tasked',
+        slug,
+        emitted,
+        loop: loopTag,
+        message,
+    };
+}
+/**
+ * The AGENT half of the tasking path (steps 3 and 3.5): run the tasker agent in
+ * `cwd` (on the work branch), then, when a loop seam is wired and the doer is
+ * the agent, the tasker review→edit→converge loop, and report what is on disk.
+ * It performs NO write to the arbiter and no git transition: only the agents'
+ * file edits, the loop's local edits and markers, and the scratch cleanup.
+ */
+export async function runTaskingAgentHalf(options, params) {
+    const { cwd, slug, specFm, doer, note } = params;
+    const agentEnv = options.agentEnv ?? options.env;
+    // 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
+    //    snapshot the staged-tasks folder before/after so the runner (not the
+    //    agent) captures + commits exactly what was produced.
+    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, 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).
+    const prompt = buildTaskingSpec(slug, specFm.spec);
+    let agent;
+    try {
+        agent = await runTaskAgent(options, cwd, prompt, slug);
+    }
+    catch (err) {
+        agent = {
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (!agent.ok) {
+        return {
+            kind: 'agent-failed',
+            detail: agent.detail ?? `the agent failed to task '${slug}'.`,
+        };
+    }
     // 3.5 THE TASKER REVIEW→EDIT→CONVERGE LOOP (`slicer-review-edit-loop`, Shape 2 /
     //     insertion point A): when a loop seam is wired, run the `review` SKILL as a
     //     review→edit→re-review loop that IMPROVES the candidate tasks in place, then
     //     determines the disposition (the three outcomes). This plugs in AFTER the
     //     candidate tasks are produced and BEFORE they are finalised. The agent makes
     //     the review/edit JUDGEMENTS; the loop applies edits to the candidate files
-    //     and routes the verdict; the runner (below) owns the git transition. Only the
+    //     and routes the verdict; the runner owns the git transition. Only the
     //     AGENT path runs the loop — the human tasking path is unaffected.
     let loopDisposition;
     if (options.reviewLoop && doer === 'agent') {
@@ -259,10 +398,8 @@ export async function performTask(options) {
         // parseable verdict (a generic parse failure, or the NAMED cap-truncation
         // class). The pre-fix behaviour THREW here, crashing the run, LEAVING THE
         // LOCK HELD, writing NO question sidecar, and DISCARDING the tasker's
-        // candidate tasks. Now: catch it, PERSIST the candidate tasks, and BOUNCE
-        // through the SAME surface the decomposition-unclear path uses (release the
-        // lock + a question sidecar). NEVER a silent approve — a parse failure is
-        // always a needs-attention route. A non-review throw (genuine wiring error)
+        // candidate tasks. Now: catch it and report it, so the write half PERSISTS
+        // the candidate tasks and BOUNCES. A non-review throw (genuine wiring error)
         // is re-thrown.
         try {
             loopDisposition = await runTaskReviewLoop({
@@ -286,7 +423,6 @@ export async function performTask(options) {
             if (!(err instanceof ReviewParseError)) {
                 throw err;
             }
-            const reviewErr = err;
             // Reap any review-edits SCRATCH the failed pass left on disk so it is never
             // swept into a later run's integrate commit.
             try {
@@ -298,56 +434,12 @@ export async function performTask(options) {
             catch {
                 // Best-effort.
             }
-            const candidatePaths = await persistTaskingCandidates(cwd, slug, before, arbiter, env, note);
-            const reason = reviewFailureReason(slug, reviewErr, candidatePaths);
-            const message = reviewFailureMessage(slug, reviewErr);
-            if (useLock) {
-                return await surfaceTaskingBlock({
-                    slug,
-                    cwd,
-                    arbiter,
-                    reason,
-                    message,
-                    lockedBlob,
-                    release: lock.release,
-                    mode: resolvedMode,
-                    provider: options.providerInstance,
-                    env,
-                    note,
-                });
-            }
-            note(reason);
-            // Human, no-lock path: a clean park-for-human is a success terminal (exit 0).
-            return { exitCode: 0, outcome: 'needs-attention', slug, message };
+            return { kind: 'review-leg-failed', error: err, before };
         }
-        // DECOMPOSITION UNCLEAR: emit NO guessed tasks — route the held spec to
-        // needs-attention with the questions as the reason. The lock release amends the
-        // `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) {
-                return await surfaceTaskingBlock({
-                    slug,
-                    cwd,
-                    arbiter,
-                    reason,
-                    message: loopDisposition.message,
-                    lockedBlob,
-                    release: lock.release,
-                    mode: resolvedMode,
-                    provider: options.providerInstance,
-                    env,
-                    note,
-                });
-            }
-            note(loopDisposition.message);
-            // Human, no-lock path: nothing to release/surface via the seam; a clean
-            // park-for-human is still a success terminal (exit 0).
             return {
-                exitCode: 0,
-                outcome: 'needs-attention',
-                slug,
+                kind: 'decomposition-unclear',
+                questions: loopDisposition.specQuestions,
                 message: loopDisposition.message,
             };
         }
@@ -360,30 +452,34 @@ export async function performTask(options) {
             }
         }
     }
-    // 4. The RUNNER commits the COMPLETING transition: drop the produced backlog
-    //    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,
-    //    not the pre-loop candidates.)
-    const stagedEmitted = newOrChangedStagedTasks(cwd, before);
-    const emitTasks = collectEmittedTasks(cwd, stagedEmitted);
-    // RUNNER-DETERMINISTIC PLACEMENT (task
-    // `runner-deterministic-slice-placement-policy-and-precedence`; the
-    // untrusted-forces-staging rung was RETIRED by ADR
-    // `untrusted-origin-carries-via-stamp-not-forced-staging`). Resolve which
-    // folder the runner lands the emitted tasks in BEFORE handing them to the
-    // shared integrate band: precedence `explicit > configured default >
-    // built-in (staging)`. THIS caller selects the trusted-vs-untrusted
-    // configured default by reading the spec's propagated `originTrust:` stamp:
-    // an untrusted-origin spec selects `untrustedTasksLandIn` (default staging;
-    // `ready` when configured), a trusted/unset spec selects `tasksLandIn`. One
-    // knob (`untrustedTasksLandIn`) governs an untrusted task's destination
-    // whether born from an issue directly (intake) or from an untrusted spec
-    // here. The agent NEVER influences this; it always writes to
-    // `work/tasks/backlog/`, and the runner redirects at `stage()` time. Safety
-    // for an untrusted task landing in `ready` is the carried stamp (its BUILD is
-    // forced to a code PR), not the folder.
+    return {
+        kind: 'candidates',
+        before,
+        poolBefore,
+        loopTag: loopDisposition?.outcome === 'converged'
+            ? 'converged'
+            : loopDisposition?.outcome === 'uncertain-tasks'
+                ? 'uncertain-tasks'
+                : undefined,
+    };
+}
+/**
+ * The RUNNER-DETERMINISTIC PLACEMENT folder for a spec's emitted tasks (task
+ * `runner-deterministic-slice-placement-policy-and-precedence`; the
+ * untrusted-forces-staging rung was RETIRED by ADR
+ * `untrusted-origin-carries-via-stamp-not-forced-staging`): precedence
+ * `explicit > configured default > built-in (staging)`. This caller selects the
+ * trusted-vs-untrusted configured default by reading the spec's propagated
+ * `originTrust:` stamp: an untrusted-origin spec selects `untrustedTasksLandIn`
+ * (default staging; `ready` when configured), a trusted/unset spec selects
+ * `tasksLandIn`. One knob (`untrustedTasksLandIn`) governs an untrusted task's
+ * destination whether born from an issue directly (intake) or from an untrusted
+ * spec here. The agent NEVER influences this; it always writes to
+ * `work/tasks/backlog/`, and the runner redirects at `stage()` time. Safety for
+ * an untrusted task landing in `ready` is the carried stamp (its BUILD is forced
+ * to a code PR), not the folder.
+ */
+export function taskPlacementDir(options, specFm) {
     const configuredTasksLanding = specFm.originTrust === 'untrusted'
         ? options.untrustedTasksLandIn
         : options.tasksLandIn;
@@ -391,247 +487,215 @@ export async function performTask(options) {
         explicit: landingToSide(options.explicitTasksLandIn),
         configuredDefault: landingToSide(configuredTasksLanding),
     });
-    const placementDir = placementFolder(TASK_PLACEMENT_SLOTS, placementDecision.choice);
+    return placementFolder(TASK_PLACEMENT_SLOTS, placementDecision.choice);
+}
+/**
+ * The WRITE half of a tasking run that produced candidate tasks (step 4): the
+ * read-stability stale check, the integrate through the shared core (the tasks
+ * + the `specs/ready → specs/tasked` move, `--propose` PR / `--merge` main), the
+ * needs-attention routing of a not-landed transition, and the mode-dependent lock
+ * release. Shared by the laptop `performTask` (review ON inside the core) and the
+ * CI apply phase (`ci-phase-tasking.ts`, review OFF: it ran in the agent phase).
+ */
+export async function integrateTaskingCandidates(params) {
+    const { slug, cwd, arbiter, stagedEmitted, emitTasks, poolBefore, placementDir, loopTag, lockedBlob, mode: resolvedMode, env, agentEnv, note, } = params;
     // REWRITE the emitted list to the RUNNER-RESOLVED destination so callers see
     // where the runner actually placed the files (not where the agent wrote them).
     const emitted = stagedEmitted.map((rel) => `${placementDir}/${basename(rel)}`);
-    const loopTag = loopDisposition?.outcome === 'converged'
-        ? 'converged'
-        : loopDisposition?.outcome === 'uncertain-tasks'
-            ? 'uncertain-tasks'
-            : undefined;
-    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 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-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`
-        // runs — relocated here because this transition, not the release, owns the
-        // completing commit now.
-        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 spec was edited (${specRel} ` +
-                `changed on ${arbiter}/main) while the tasking lock was held. The tasking is ` +
-                `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 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
-        // construction. The agent did NO git; the runner (the band) owns the ONE commit.
-        const core = await performIntegration({
-            cwd,
-            arbiter,
-            slug,
-            // `source`/`recovering` are task-shaped and IGNORED when `lifecycle` is set
-            // (a tasking transition never recovers a surfaced needs-attention move).
-            source: 'in-progress',
-            recovering: false,
-            // Skip the build acceptance gate (Gate 1 / verify): a tasking transition has
-            // no `verify` floor (the tasker review loop above is its quality gate).
-            skipVerify: true,
-            // THE TASK-SET ACCEPTANCE GATE (task `slice-acceptance-gate`): the
-            // task-path mirror of the build Gate-2, riding THIS shared core's
-            // review-before-integrate block. When `review` resolves on, the wired
-            // `reviewGate` (production: `harnessTaskReviewGate` with the task-SET
-            // prompt) runs a FRESH-CONTEXT review of the produced task SET before it
-            // integrates: `approve` lands it, `block` routes the set to needs-attention
-            // via the SAME machinery the build block uses (mapped to the tasking
-            // `needs-attention` outcome below). It is ONE-SHOT: we pin
-            // `reviewMaxRounds: 1` so the gate is a SINGLE reviewer invocation → verdict
-            // (terminal pass/fail). The task path NEVER exposes/consults
-            // `--review-max-rounds` — a gate is terminal, the rounds bound is an orphan
-            // that belongs to a future revise↔review loop (see
-            // `work/notes/observations/reviewmaxrounds-on-wrong-concept.md`). This is
-            // independently controllable from the tasker improver loop (`reviewLoop` /
-            // the `--tasker-loop*` family); toggling one does not affect the other.
-            review: options.review,
-            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
-            // (spec US #6).
-            mode: resolvedMode,
-            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 spec (before it moves).
-                titlePath: workItemPath(cwd, 'specs-ready', slug),
-                commitTag: 'tasked',
-                stage: () => stageTaskingLifecycle({
-                    cwd,
-                    slug,
-                    emitTasks,
-                    poolBefore,
-                    placementDir,
-                    note,
-                    env,
-                }),
-            },
-            env,
-            // The task-SET acceptance review AGENT launches AMBIENT, never the
-            // identity-scoped `env` (an agent must not act as the bot).
-            agentEnv,
-            note,
-        });
-        // THE TASK-SET ACCEPTANCE GATE BLOCKED (task `slice-acceptance-gate`): the
-        // fresh-context review of the produced SET returned `block`, so the core ran
-        // 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 `spec:<slug>` unified lock `active -> stuck` with the block reason (the
-        // tasking needs-attention surface is the stuck lock now — NO folder write; the
-        // 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);
-            return await surfaceTaskingBlock({
-                slug,
+    // 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 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-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`
+    // runs — relocated here because this transition, not the release, owns the
+    // completing commit now.
+    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 spec was edited (${specRel} ` +
+            `changed on ${arbiter}/main) while the tasking lock was held. The tasking is ` +
+            `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 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
+    // construction. The agent did NO git; the runner (the band) owns the ONE commit.
+    const core = await performIntegration({
+        cwd,
+        arbiter,
+        slug,
+        // `source`/`recovering` are task-shaped and IGNORED when `lifecycle` is set
+        // (a tasking transition never recovers a surfaced needs-attention move).
+        source: 'in-progress',
+        recovering: false,
+        // Skip the build acceptance gate (Gate 1 / verify): a tasking transition has
+        // no `verify` floor (the tasker review loop above is its quality gate).
+        skipVerify: true,
+        // THE TASK-SET ACCEPTANCE GATE (task `slice-acceptance-gate`): the
+        // task-path mirror of the build Gate-2, riding THIS shared core's
+        // review-before-integrate block. When `review` resolves on, the wired
+        // `reviewGate` (production: `harnessTaskReviewGate` with the task-SET
+        // prompt) runs a FRESH-CONTEXT review of the produced task SET before it
+        // integrates: `approve` lands it, `block` routes the set to needs-attention
+        // via the SAME machinery the build block uses (mapped to the tasking
+        // `needs-attention` outcome below). It is ONE-SHOT: we pin
+        // `reviewMaxRounds: 1` so the gate is a SINGLE reviewer invocation → verdict
+        // (terminal pass/fail). The task path NEVER exposes/consults
+        // `--review-max-rounds` — a gate is terminal, the rounds bound is an orphan
+        // that belongs to a future revise↔review loop (see
+        // `work/notes/observations/reviewmaxrounds-on-wrong-concept.md`). This is
+        // independently controllable from the tasker improver loop (`reviewLoop` /
+        // the `--tasker-loop*` family); toggling one does not affect the other.
+        // The CI apply phase passes it OFF (it ran in the agent phase) and hands
+        // its approved prose in as `approvedReviewProse`.
+        review: params.review,
+        reviewGate: params.reviewGate,
+        reviewModel: params.acceptanceReviewModel,
+        reviewMaxRounds: 1,
+        approvedReviewProse: params.approvedReviewProse,
+        // 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: params.mergeRetries,
+        ...(params.mergeJitterMs === undefined
+            ? {}
+            : { mergeJitterMs: params.mergeJitterMs }),
+        // 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
+        // (spec US #6).
+        mode: resolvedMode,
+        noPR: params.noPR,
+        providerInstance: params.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 spec (before it moves).
+            titlePath: workItemPath(cwd, 'specs-ready', slug),
+            commitTag: 'tasked',
+            // The spec RESTS in `work/specs/tasked/` once this lands (never
+            // `work/tasks/done/`, the task-build default), so point the reviewer there.
+            proposeHeader: proposePointer('Spec', workItemRel('specs-tasked', `${slug}.md`)),
+            stage: () => stageTaskingLifecycle({
                 cwd,
-                arbiter,
-                reason,
-                message: `The task acceptance gate disapproved the set produced for '${slug}'; ` +
-                    `parked it for your attention (no tasks landed). ` +
-                    `Resolve the findings, then re-task.`,
-                lockedBlob,
-                release: lock.release,
-                mode: resolvedMode,
-                provider: options.providerInstance,
-                env,
-                note,
-            });
-        }
-        if (core.outcome === 'sidecar-violation') {
-            // A co-located `<slug>/` asset sidecar sits beside the FLOWING spec item
-            // (WORK-CONTRACT.md rule 8): the tasking transition would `git mv`
-            // `specs/ready → specs/tasked` and STRAND the sidecar. The core HARD-BLOCKED
-            // before the stage/integrate; route the held spec to needs-attention through
-            // the SAME `spec:<slug>` lock-release seam the block path uses (no tasks land),
-            // carrying the actionable relocate-to-`docs/spikes/<slug>/` reason.
-            const reason = `The spec '${slug}' carries a co-located asset sidecar: ` +
-                `${core.reviewBlockReason ?? core.reason ?? ''}`;
-            return await surfaceTaskingBlock({
                 slug,
-                cwd,
-                arbiter,
-                reason,
-                message: `The spec '${slug}' carries a co-located asset sidecar (WORK-CONTRACT ` +
-                    `rule 8); parked it for your attention (no tasks landed; relocate it ` +
-                    `to docs/spikes/${slug}/ and reference by path).`,
-                lockedBlob,
-                release: lock.release,
-                mode: resolvedMode,
-                provider: options.providerInstance,
-                env,
+                emitTasks,
+                poolBefore,
+                placementDir,
                 note,
-            });
-        }
-        if (core.outcome === 'review-unparseable') {
-            // The task-set acceptance gate RAN but its verdict was UNPARSEABLE (malformed
-            // 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
-            // `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 ` +
-                `(re-run — transient): ${core.reason ?? ''}`;
-            return await surfaceTaskingBlock({
-                slug,
-                cwd,
-                arbiter,
-                reason,
-                message: `The task acceptance gate produced an unparseable verdict for '${slug}'; ` +
-                    `parked it for your attention (no tasks landed; re-run).`,
-                lockedBlob,
-                release: lock.release,
-                mode: resolvedMode,
-                provider: options.providerInstance,
                 env,
-                note,
-            });
-        }
-        if (core.outcome === 'completed') {
-            // LOCK LIFETIME IS MODE-DEPENDENT (fix
-            // `propose-tasking-releases-lock-so-spec-is-retasked-and-pr-force-pushed-every-tick`;
-            // the "hold-across-the-PR" capstone the older interim half deferred).
-            //
-            // `merge`: the durable `specs/ready → specs/tasked` `main` move HAS landed, so
-            // residence-in-`specs/tasked/` on `main` now carries tasked-ness and the lock
-            // has done its job — RELEASE it (delete the ref). Best-effort + idempotent
-            // (`not-held` is fine).
-            //
-            // `propose`: the move lives ONLY on the pushed work branch / open PR — `main`
-            // still holds the spec in `work/specs/ready/`, so residence does NOT yet signal
-            // tasked-ness. If we released here, the next in-place scan would see the spec
-            // eligible again (ready + not-tasked + lock free) and re-task it EVERY tick,
-            // force-recreating the branch (`git switch -C`) and force-pushing the SAME PR —
-            // regenerating its review forever until a human merges/closes it. So we KEEP
-            // the `spec:<slug>` lock HELD across the open PR: the held lock IS the
-            // "in-flight tasking" marker, and `scoreSpecs`/`taskableSpecs` subtract held
-            // specs from the taskable pool (symmetric to the task-pool held-slug
-            // subtraction). The lock is reaped when the PR resolves: a MERGE lands the
-            // durable move (which now carries tasked-ness on its own) and the reap/gc path
-            // deletes the merged branch + its lock; a human CLOSING the PR unmerged is a
-            // recovery the human owns via `release-lock` (the same model as any other
-            // abandoned in-flight item — no liveness heartbeat/auto-steal).
-            //
-            // MIGRATE step: the ref is keyed under the `spec:<slug>` identity (the
-            // `spec-<slug>` lock entry the acquire took).
-            if (useLock && resolvedMode === 'merge') {
-                await releaseItemLock({ item: `spec:${slug}`, cwd, arbiter, env });
-            }
-        }
-        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 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 spec into work/specs/tasked/) yourself.`;
-    note(message);
-    return {
-        exitCode: 0,
-        outcome: 'tasked',
+            }),
+        },
+        env,
+        // The task-SET acceptance review AGENT launches AMBIENT, never the
+        // identity-scoped `env` (an agent must not act as the bot).
+        agentEnv,
+        note,
+    });
+    const surfaceBlock = (reason, message) => surfaceTaskingBlock({
         slug,
-        emitted,
-        loop: loopTag,
+        cwd,
+        arbiter,
+        reason,
         message,
-    };
+        lockedBlob,
+        release: params.release,
+        mode: resolvedMode,
+        provider: params.providerInstance,
+        env,
+        note,
+    });
+    // THE TASK-SET ACCEPTANCE GATE BLOCKED (task `slice-acceptance-gate`): the
+    // fresh-context review of the produced SET returned `block`, so the core ran
+    // 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 surfaces
+    // the spec and releases the `spec:<slug>` lock with the block reason. 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') {
+        return await surfaceBlock(taskGateBlockedReason(slug, core.reviewBlockReason), `The task acceptance gate disapproved the set produced for '${slug}'; ` +
+            `parked it for your attention (no tasks landed). ` +
+            `Resolve the findings, then re-task.`);
+    }
+    if (core.outcome === 'sidecar-violation') {
+        // A co-located `<slug>/` asset sidecar sits beside the FLOWING spec item
+        // (WORK-CONTRACT.md rule 8): the tasking transition would `git mv`
+        // `specs/ready → specs/tasked` and STRAND the sidecar. The core HARD-BLOCKED
+        // before the stage/integrate; route the held spec to needs-attention through
+        // the SAME `spec:<slug>` lock-release seam the block path uses (no tasks land),
+        // carrying the actionable relocate-to-`docs/spikes/<slug>/` reason.
+        return await surfaceBlock(`The spec '${slug}' carries a co-located asset sidecar: ` +
+            `${core.reviewBlockReason ?? core.reason ?? ''}`, `The spec '${slug}' carries a co-located asset sidecar (WORK-CONTRACT ` +
+            `rule 8); parked it for your attention (no tasks landed; relocate it ` +
+            `to docs/spikes/${slug}/ and reference by path).`);
+    }
+    if (core.outcome === 'review-unparseable') {
+        // The task-set acceptance gate RAN but its verdict was UNPARSEABLE (malformed
+        // JSON). Route the held spec to needs-attention through the SAME lock-release
+        // seam the block path uses. 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.
+        return await surfaceBlock(taskGateUnparseableReason(slug, core.reason), `The task acceptance gate produced an unparseable verdict for '${slug}'; ` +
+            `parked it for your attention (no tasks landed; re-run).`);
+    }
+    if (core.outcome === 'completed') {
+        // LOCK LIFETIME IS MODE-DEPENDENT (fix
+        // `propose-tasking-releases-lock-so-spec-is-retasked-and-pr-force-pushed-every-tick`;
+        // the "hold-across-the-PR" capstone the older interim half deferred).
+        //
+        // `merge`: the durable `specs/ready → specs/tasked` `main` move HAS landed, so
+        // residence-in-`specs/tasked/` on `main` now carries tasked-ness and the lock
+        // has done its job — RELEASE it (delete the ref). Best-effort + idempotent
+        // (`not-held` is fine).
+        //
+        // `propose`: the move lives ONLY on the pushed work branch / open PR — `main`
+        // still holds the spec in `work/specs/ready/`, so residence does NOT yet signal
+        // tasked-ness. If we released here, the next in-place scan would see the spec
+        // eligible again (ready + not-tasked + lock free) and re-task it EVERY tick,
+        // force-recreating the branch (`git switch -C`) and force-pushing the SAME PR —
+        // regenerating its review forever until a human merges/closes it. So we KEEP
+        // the `spec:<slug>` lock HELD across the open PR: the held lock IS the
+        // "in-flight tasking" marker, and `scoreSpecs`/`taskableSpecs` subtract held
+        // specs from the taskable pool (symmetric to the task-pool held-slug
+        // subtraction). The lock is reaped when the PR resolves: a MERGE lands the
+        // durable move (which now carries tasked-ness on its own) and the reap/gc path
+        // deletes the merged branch + its lock; a human CLOSING the PR unmerged is a
+        // recovery the human owns via `release-lock` (the same model as any other
+        // abandoned in-flight item — no liveness heartbeat/auto-steal).
+        //
+        // MIGRATE step: the ref is keyed under the `spec:<slug>` identity (the
+        // `spec-<slug>` lock entry the acquire took).
+        if (resolvedMode === 'merge') {
+            await releaseItemLock({ item: `spec:${slug}`, cwd, arbiter, env });
+        }
+    }
+    return integrationToTaskResult(core, { slug, emitted, loop: loopTag });
 }
 /**
  * Map a non-`released` lock-release result onto the {@link TaskResult} contract
@@ -670,9 +734,16 @@ function releaseFailureToResult(released, slug) {
 function integrationToTaskResult(core, ctx) {
     const { slug, emitted, loop } = ctx;
     if (core.outcome === 'completed') {
+        // Say "opened a PR" ONLY when the provider opened one (task
+        // `intake-reports-the-pr-it-actually-opened`); a degraded `gh pr create`
+        // pushed the branch but opened nothing, and the shared core printed why.
+        const notOpened = proposeRequestNotOpened(core.integration);
         const landed = core.integration?.mode === 'merge'
             ? 'landed them on the arbiter main'
-            : 'opened a PR carrying them (main untouched)';
+            : notOpened !== undefined
+                ? `pushed them on branch ${core.integration?.pushedRef ?? core.branch} ` +
+                    'but opened NO PR (main untouched; see the provider note above)'
+                : '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/specs/ready/ -> work/specs/tasked/, the ` +
@@ -706,7 +777,14 @@ function integrationToTaskResult(core, ctx) {
  * 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) {
+export async function switchToWorkBranch(cwd, arbiter, slug, env, 
+/**
+ * The commit to cut the branch from; default the freshly fetched
+ * `<arbiter>/main`. The CI phases pass the lock job's `baseSha` (task
+ * `ci-split-tasking`), so the agent and apply jobs work on the tree the lock
+ * job classified.
+ */
+base) {
     // 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 (spec `prd-to-spec-vocabulary-cutover-and-migration-command`):
@@ -714,7 +792,7 @@ async function switchToWorkBranch(cwd, arbiter, slug, env) {
     // parses the legacy `work/prd-<slug>` form, so in-flight branches keep resolving).
     const branch = workBranchRef('spec', slug);
     await gitHard(['fetch', '--quiet', arbiter], cwd, env);
-    await gitHard(['switch', '--quiet', '-C', branch, `${arbiter}/main`], cwd, env);
+    await gitHard(['switch', '--quiet', '-C', branch, base ?? `${arbiter}/main`], cwd, env);
 }
 /**
  * The READ-STABILITY content-identity STALE CHECK (the lock's backstop, owned at
@@ -876,12 +954,21 @@ async function gitHard(args, cwd, env) {
  * generic line when absent. DISTINCT from the improver loop's
  * {@link decompositionUnclearReason} (which carries the loop's open questions).
  */
-function taskGateBlockedReason(slug, findingsReason) {
+export function taskGateBlockedReason(slug, findingsReason) {
     const head = `The task acceptance gate (fresh-context review of the produced SET) blocked ` +
         `'${slug}'. The spec is parked for your attention with no tasks landed; ` +
         `resolve the blocking findings, then re-task.`;
     return findingsReason ? `${head}\n\n${findingsReason}` : head;
 }
+/**
+ * The needs-attention REASON for a task-SET ACCEPTANCE GATE whose verdict was
+ * UNPARSEABLE (the gate ran; its output could not be read): NOT a block, the
+ * transient-infra re-run signal. `detail` is the gate's parse-failure reason.
+ */
+export function taskGateUnparseableReason(slug, detail) {
+    return (`The task acceptance gate for '${slug}' produced an UNPARSEABLE verdict ` +
+        `(re-run — transient): ${detail ?? ''}`);
+}
 /**
  * Shared terminal for a tasking transition that DID NOT land — a disapproving
  * task-set review, a co-located sidecar violation, an unparseable verdict, or a
@@ -903,7 +990,7 @@ function taskGateBlockedReason(slug, findingsReason) {
  * is GREEN — a park-for-human is not a failure). Only a surface that FAILED to
  * publish maps to a non-zero {@link releaseFailureToResult}.
  */
-async function surfaceTaskingBlock(params) {
+export async function surfaceTaskingBlock(params) {
     const { slug, cwd, arbiter, reason, message, lockedBlob, release, mode, provider, env, note, } = params;
     // 1. Close a stale OPEN PR (propose only, only-if-exists) with the review as
     //    the closing comment; keep the branch for a later approving re-task to
@@ -940,7 +1027,7 @@ async function surfaceTaskingBlock(params) {
  * spec is parked for the human with these open questions + a question sidecar on
  * main, no guessed tasks). Prose only — recorded as the parked question's reason.
  */
-function decompositionUnclearReason(slug, questions) {
+export 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 spec is parked ` +
         `for your attention with no guessed tasks; resolve:`;
@@ -960,7 +1047,7 @@ function decompositionUnclearReason(slug, questions) {
  * The candidate tasks the tasker produced are PERSISTED on the work branch (see
  * {@link persistTaskingCandidates}) so a human can recover them.
  */
-function reviewFailureReason(slug, err, candidatePaths) {
+export function reviewFailureReason(slug, err, candidatePaths) {
     const named = err instanceof ReviewOutputCappedError
         ? `The tasker review leg failed on '${slug}': ${err.message}. This is a ` +
             "STRUCTURAL cap-truncation (the review edits payload shared the model's " +
@@ -979,7 +1066,7 @@ function reviewFailureReason(slug, err, candidatePaths) {
     return `${named}${tasks}`;
 }
 /** The human-readable terminal MESSAGE for a review-leg failure (the result's `message`). */
-function reviewFailureMessage(slug, err) {
+export function reviewFailureMessage(slug, err) {
     if (err instanceof ReviewOutputCappedError) {
         return (`Tasking '${slug}' parked: the review leg hit the model output cap ` +
             `(${err.outputTokens} tokens) and was truncated before emitting its ` +
@@ -1000,7 +1087,7 @@ function reviewFailureMessage(slug, err) {
  * candidate paths persisted (empty when there were none). Never throws — a git
  * failure is noted and the bounce proceeds (the lock is still released).
  */
-async function persistTaskingCandidates(cwd, slug, before, arbiter, env, note) {
+export async function persistTaskingCandidates(cwd, slug, before, arbiter, env, note) {
     const candidatePaths = newOrChangedStagedTasks(cwd, before);
     if (candidatePaths.length === 0) {
         return [];
@@ -1029,7 +1116,12 @@ async function persistTaskingCandidates(cwd, slug, before, arbiter, env, note) {
     // teardown on an isolated run (the branch ref survives locally too, but a push
     // makes them remote-recoverable). A push failure is noted, never fatal.
     try {
-        const pushed = await gitSoft(['push', arbiter, branch], cwd, env);
+        const pushed = await refWrite.pushTaskingCandidatesBranch({
+            arbiter,
+            branch,
+            cwd,
+            env,
+        });
         if (pushed.status !== 0) {
             note(`Could not push the candidate-tasks work branch '${branch}' to ${arbiter} ` +
                 `(best-effort; the local commit still persists for recovery).`);
@@ -1085,7 +1177,7 @@ function appendQuestionsBlock(content, questions) {
  * cross-spec `taskedAfter` ordering, resolved against `work/specs/tasked/` residence of
  * the specs present in the checkout.
  */
-function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
+export function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
     return resolveTaskingEligibility({
         humanOnly: specFm.humanOnly,
         needsAnswers: specFm.needsAnswers,
@@ -1096,7 +1188,7 @@ function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
     });
 }
 /** Build an HONEST gate-refusal message naming WHY the agent skipped the spec. */
-function gateRefusalReason(slug, specFm, eligibility, options) {
+export function gateRefusalReason(slug, specFm, eligibility, options) {
     const reasons = [];
     if (specFm.humanOnly === true) {
         reasons.push('the spec is humanOnly (a human must drive its tasking)');
@@ -1234,7 +1326,7 @@ async function runTaskAgent(options, cwd, prompt, slug) {
     return { ok: launched.ok, detail: launched.detail };
 }
 /** A snapshot of {@link STAGED_TASKS_DIR}: filename → file content. */
-function snapshotStagedTasks(cwd) {
+export function snapshotStagedTasks(cwd) {
     const dir = join(cwd, STAGED_TASKS_DIR);
     const snap = new Map();
     for (const file of listMarkdown(dir)) {
@@ -1249,7 +1341,7 @@ function snapshotStagedTasks(cwd) {
  * re-committed.) The agent's staging folder is `work/tasks/backlog/`; writes to
  * the pool `work/tasks/ready/` are scrubbed at stage time, never picked up here.
  */
-function newOrChangedStagedTasks(cwd, before) {
+export function newOrChangedStagedTasks(cwd, before) {
     const dir = join(cwd, STAGED_TASKS_DIR);
     const changed = [];
     for (const file of listMarkdown(dir)) {
@@ -1261,7 +1353,7 @@ function newOrChangedStagedTasks(cwd, before) {
     return changed.sort();
 }
 /** Snapshot the POOL `work/tasks/ready/` (for the agent-write fence at stage time). */
-function snapshotPool(cwd) {
+export function snapshotPool(cwd) {
     const dir = workFolderPath(cwd, 'tasks-ready');
     const snap = new Map();
     for (const file of listMarkdown(dir)) {
@@ -1270,7 +1362,7 @@ function snapshotPool(cwd) {
     return snap;
 }
 /** Read the produced backlog tasks' content keyed by repo-relative path. */
-function collectEmittedTasks(cwd, relPaths) {
+export function collectEmittedTasks(cwd, relPaths) {
     const out = {};
     for (const rel of relPaths) {
         out[rel] = readFileSync(join(cwd, rel), 'utf8');
@@ -1410,10 +1502,12 @@ function readTitleField(content) {
         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);
+        // Quoted ⇒ return the inner text (a single-quoted `''` decodes to `'`, the
+        // shape `quoteYamlScalar` writes); unquoted ⇒ strip trailing `# ...`.
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            return unquoteYamlScalar(value);
         }
         const hash = value.indexOf('#');
         if (hash !== -1)