dorfl 0.0.0 → 0.1.0

package/dist/tasking.js

@@ -0,0 +1,952 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parseFrontmatter } 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 { resolveTaskingEligibility, } from './tasking-eligibility.js';
+import { acquireTaskingLock, releaseTaskingLock, } from './tasking-lock.js';
+import { releaseItemLock } from './item-lock.js';
+import { NullHarness } from './harness.js';
+import { launchWithOptionalWatch } from './agent-launch.js';
+import { placementFolder, resolvePlacement } from './placement.js';
+import { setNeedsAnswersMarker, propagateOrigin } from './frontmatter.js';
+import { workBranchRef } from './slug-namespace.js';
+import { runTaskReviewLoop, } from './tasker-review-loop.js';
+const DEFAULT_LOCK_SEAM = {
+    acquire: acquireTaskingLock,
+    release: releaseTaskingLock,
+};
+const DEFAULT_ARBITER = 'origin';
+/**
+ * **The STAGED-TASKS dir** (prd `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
+ * 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
+ * it claimable. STEP A: ADDITIVE — no `work/tasks/ready/` reader changes here.
+ */
+export const STAGED_TASKS_DIR = workFolderRel('tasks-backlog');
+/**
+ * The POOL folder tasks land in when the runner-deterministic placement
+ * resolver chooses the pool side (`tasksLandIn: 'ready'` and a trusted
+ * 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
+ * pool. Task `runner-deterministic-slice-placement-policy-and-precedence`.
+ */
+const POOL_TASKS_DIR = workFolderRel('tasks-ready');
+/** The placement slots for the TASK lifecycle (folder names). */
+const TASK_PLACEMENT_SLOTS = {
+    staging: STAGED_TASKS_DIR,
+    pool: POOL_TASKS_DIR,
+};
+/**
+ * Map the `tasksLandIn` value spelling (`pre-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`).
+ */
+function landingToSide(landing) {
+    if (landing === 'pre-backlog')
+        return 'staging';
+    if (landing === 'ready')
+        return 'pool';
+    return undefined;
+}
+/** The repo-relative path of a staged task's `.md` (per {@link STAGED_TASKS_DIR}). */
+function stagedTaskPath(name) {
+    return `${STAGED_TASKS_DIR}/${name}`;
+}
+/**
+ * Run the `do prd:<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.
+ */
+export async function performTask(options) {
+    const note = options.note ?? (() => { });
+    const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+    const cwd = options.cwd;
+    // `env` is the runner's GIT/provider env (identity-scoped). `agentEnv` is the
+    // AMBIENT env for AGENT launches (tasker agent, review/improver agents) — an
+    // agent must not act as the bot. Falls back to `env` when no identity.
+    const env = options.env;
+    const agentEnv = options.agentEnv ?? options.env;
+    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
+    //    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.`;
+        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.
+    if (doer === 'agent') {
+        const eligibility = resolveAgentGate(cwd, slug, specFm, options.autoTask, options.explicit ?? false);
+        if (!eligibility.taskable) {
+            const message = gateRefusalReason(slug, specFm, eligibility, options);
+            note(message);
+            return { exitCode: 1, outcome: 'gate-refused', slug, message };
+        }
+    }
+    // 2. ACQUIRE THE LOCK (agent path; concurrency serialisation). The human path
+    //    with no contention may task on `main` directly WITHOUT the lock.
+    let lockedBlob;
+    const useLock = doer === 'agent';
+    if (useLock) {
+        const acquired = await lock.acquire({ slug, cwd, arbiter, env, note });
+        if (acquired.outcome === 'lost') {
+            return {
+                exitCode: 2,
+                outcome: 'lock-lost',
+                slug,
+                message: acquired.message,
+            };
+        }
+        if (acquired.outcome === 'contended') {
+            return {
+                exitCode: 3,
+                outcome: 'lock-lost',
+                slug,
+                message: acquired.message,
+            };
+        }
+        if (acquired.exitCode !== 0) {
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                slug,
+                message: acquired.message,
+            };
+        }
+        lockedBlob = acquired.lockedBlob;
+    }
+    // 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`
+    //     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
+    //     its own branch and commits its output itself (no integrate, no branch cut).
+    if (useLock) {
+        await switchToWorkBranch(cwd, arbiter, slug, env);
+    }
+    // 3. INVOKE THE AGENT with the to-task prd. 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, prd US #4) before `git add -A` would sweep them in.
+    const poolBefore = snapshotPool(cwd);
+    // MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
+    // read the parent-spec self-pointer off `prdFm.spec` (populated beside
+    // `prdFm.prd` by the expand task).
+    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}'.`;
+        const message = `Agent failed tasking '${slug}' (${detail}).`;
+        note(message);
+        // The lock stays held (the runner did not release it): a stuck tasking is
+        // recoverable / re-runnable. Surfacing it is the review/edit loop's job.
+        return { exitCode: 1, outcome: 'agent-failed', slug, message };
+    }
+    // 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
+    //     AGENT path runs the loop — the human tasking path is unaffected.
+    let loopDisposition;
+    if (options.reviewLoop && doer === 'agent') {
+        loopDisposition = await runTaskReviewLoop({
+            slug,
+            cwd,
+            gate: options.reviewLoop,
+            // SCOPING FENCE (the requeue fix): the loop reviews/edits/flags ONLY the
+            // tasks THIS run produced (new-or-changed vs `before`), never the
+            // pre-existing staged tasks that share `work/tasks/backlog/`.
+            before,
+            taskerLoopMax: options.taskerLoopMax ?? 3,
+            executions: options.reviewExecutions,
+            taskerLoopModel: options.taskerLoopModel,
+            sessionsDir: options.sessionsDir,
+            // The improver loop's review AGENT launches AMBIENT, never the identity.
+            env: agentEnv,
+            note,
+        });
+        // DECOMPOSITION UNCLEAR: emit NO guessed tasks — route the held prd 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/`).
+        if (loopDisposition.outcome === 'decomposition-unclear') {
+            const reason = decompositionUnclearReason(slug, loopDisposition.specQuestions);
+            if (useLock) {
+                const routed = await lock.release({
+                    slug,
+                    cwd,
+                    arbiter,
+                    lockedBlob,
+                    routeToNeedsAttention: { reason },
+                    env,
+                    note,
+                });
+                if (routed.outcome !== 'released') {
+                    return releaseFailureToResult(routed, slug);
+                }
+            }
+            note(loopDisposition.message);
+            return {
+                exitCode: 1,
+                outcome: 'needs-attention',
+                slug,
+                message: loopDisposition.message,
+            };
+        }
+        // UNCERTAIN TASKS: mark each named candidate `needsAnswers: true` + record
+        // its questions in the body, so it lands but is not agent-buildable. The
+        // runner writes the marker (the agent does no git/disk-escape).
+        if (loopDisposition.outcome === 'uncertain-tasks') {
+            for (const uncertain of loopDisposition.uncertainTasks) {
+                markTaskNeedsAnswers(cwd, uncertain.path, uncertain.questions, note);
+            }
+        }
+    }
+    // 4. The RUNNER commits the COMPLETING transition: drop the produced backlog
+    //    tasks IN + move the prd tasking/ -> prd-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`). 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
+    // 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.
+    const placementDecision = resolvePlacement({
+        explicit: landingToSide(options.explicitTasksLandIn),
+        originTrust: specFm.originTrust,
+        configuredDefault: landingToSide(options.tasksLandIn),
+    });
+    const placementDir = placementFolder(TASK_PLACEMENT_SLOTS, placementDecision.choice);
+    // 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 prd body CLEANLY
+        // into prd/ (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
+        // 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 prd 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. ` +
+                `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
+        // 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 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).
+            mode: options.integration ?? 'propose',
+            noPR: options.noPR,
+            providerInstance: options.providerInstance,
+            type: 'tasking',
+            lifecycle: {
+                // Read the PR title / commit summary from the held prd (before it moves).
+                titlePath: workItemPath(cwd, 'specs-ready', slug),
+                commitTag: 'tasked',
+                stage: () => stageTaskingLifecycle({
+                    cwd,
+                    slug,
+                    emitTasks,
+                    poolBefore,
+                    placementDir,
+                    placementReason: placementDecision.reason,
+                    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 `prd:<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
+        // needs-attention THROUGH the lock release — the set never lands.
+        if (core.outcome === 'review-blocked') {
+            const reason = taskGateBlockedReason(slug, core.reviewBlockReason);
+            const routed = await lock.release({
+                slug,
+                cwd,
+                arbiter,
+                lockedBlob,
+                routeToNeedsAttention: { reason },
+                env,
+                note,
+            });
+            if (routed.outcome !== 'released') {
+                return releaseFailureToResult(routed, slug);
+            }
+            note(reason);
+            return {
+                exitCode: 1,
+                outcome: 'needs-attention',
+                slug,
+                message: `The task acceptance gate blocked the set produced for '${slug}'; ` +
+                    `marked the per-item lock stuck (needs attention; no tasks landed).`,
+            };
+        }
+        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
+            // 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
+            // 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 ?? ''}`;
+            const routed = await lock.release({
+                slug,
+                cwd,
+                arbiter,
+                lockedBlob,
+                routeToNeedsAttention: { reason },
+                env,
+                note,
+            });
+            if (routed.outcome !== 'released') {
+                return releaseFailureToResult(routed, slug);
+            }
+            note(reason);
+            return {
+                exitCode: 1,
+                outcome: 'needs-attention',
+                slug,
+                message: `The task acceptance gate produced an unparseable verdict for '${slug}'; ` +
+                    `marked the per-item lock stuck (needs attention; no tasks landed; re-run).`,
+            };
+        }
+        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/`
+            // 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
+            // `propose` (`mode: 'propose'`) is ALSO `completed` (the PR opened, the lock's
+            // hold over the in-flight tasking is done); the eventual hold-across-the-PR
+            // crash-safe ordering is the capstone task #7's concern, not this interim
+            // half. Best-effort + idempotent (`not-held` is fine).
+            // MIGRATE step: release under the `spec:<slug>` identity (keyed to the
+            // `spec-<slug>` lock entry the acquire now takes). Idempotent.
+            if (useLock) {
+                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 prd into
+    // `work/prds/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.`;
+    note(message);
+    return {
+        exitCode: 0,
+        outcome: 'tasked',
+        slug,
+        emitted,
+        loop: loopTag,
+        message,
+    };
+}
+/**
+ * Map a non-`released` lock-release result onto the {@link TaskResult} contract
+ * (the decomposition-unclear routing reuses the SAME release seam, so it can also
+ * be `stale`/`lost`/`contended`/usage-error). Mirrors the step-4 release mapping.
+ */
+function releaseFailureToResult(released, slug) {
+    if (released.outcome === 'stale') {
+        return { exitCode: 4, outcome: 'stale', slug, message: released.message };
+    }
+    if (released.outcome === 'lost' || released.outcome === 'contended') {
+        const code = released.outcome === 'lost' ? 2 : 3;
+        return {
+            exitCode: code,
+            outcome: 'lock-lost',
+            slug,
+            message: released.message,
+        };
+    }
+    return { exitCode: 1, outcome: 'usage-error', slug, message: released.message };
+}
+/**
+ * Map the shared integrate band's {@link IntegrationCoreResult} onto the tasking
+ * {@link TaskResult} (task `slice-output-through-integration`). On `completed`
+ * (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
+ * 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
+ * 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.
+ */
+function integrationToTaskResult(core, ctx) {
+    const { slug, emitted, loop } = ctx;
+    if (core.outcome === 'completed') {
+        const landed = core.integration?.mode === 'merge'
+            ? 'landed them on the arbiter main'
+            : '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 ` +
+            `tasked resting state) and ${landed}.`;
+        return { exitCode: 0, outcome: 'tasked', slug, emitted, loop, message };
+    }
+    if (core.outcome === 'rebase-conflict') {
+        return {
+            exitCode: 4,
+            outcome: 'stale',
+            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.`,
+        };
+    }
+    return {
+        exitCode: 1,
+        outcome: 'usage-error',
+        slug,
+        message: core.reason ??
+            `Integrating the tasking of '${slug}' failed unexpectedly.`,
+    };
+}
+/**
+ * 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
+ * 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`):
+    // 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);
+    await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+    await gitHard(['switch', '--quiet', '-C', branch, `${arbiter}/main`], cwd, 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
+ * 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
+ * not-stale (the lock acquire always returns it).
+ */
+async function heldSpecIsStale(cwd, arbiter, slug, lockedBlob, env) {
+    if (lockedBlob === undefined) {
+        return false;
+    }
+    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 integrate's rebase/push surfaces that); only a CHANGED held blob is stale.
+    if (held.status !== 0) {
+        return false;
+    }
+    return held.stdout.trim() !== lockedBlob;
+}
+/**
+ * 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
+ * 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/`
+ * 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.
+ */
+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`/
+    // `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
+    // human/local-authored one ⇒ trusted) propagates nothing — the normal path is
+    // untouched.
+    const specAbs = join(cwd, spec);
+    const specProvenance = existsSync(specAbs)
+        ? parseFrontmatter(readFileSync(specAbs, 'utf8'))
+        : { origin: undefined, originTrust: undefined };
+    if (placementReason === 'untrusted-origin') {
+        note(`Untrusted-origin prd '${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`
+    // 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/`).
+    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
+    // `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
+    // into. Anything the agent dropped under the pool would otherwise be swept in
+    // by `performIntegration`'s subsequent `git add -A` — a self-placement into
+    // the pool. Scrub it FIRST (before the runner writes its resolved destination
+    // files below), so when the runner-deterministic placement resolves to the
+    // pool the runner's writes are the ONLY legitimate pool entries in the commit.
+    await scrubPoolDrift(cwd, poolBefore, env);
+    // Drop the produced backlog tasks IN at the RUNNER-RESOLVED destination
+    // (write + stage; the band's `git add -A` also catches them, but staging here
+    // keeps the transition explicit + atomic). The runner STAMPS the propagated
+    // provenance onto each task as it writes it (the agent does no git; the runner
+    // owns the file write here). When the resolved destination DIFFERS from where
+    // the agent wrote (the staging folder), remove the agent's source file too —
+    // otherwise `git add -A` would commit BOTH (staging twin + pool destination).
+    for (const [agentRel, content] of Object.entries(emitTasks)) {
+        const filename = basename(agentRel);
+        const destRel = `${placementDir}/${filename}`;
+        const destAbs = join(cwd, destRel);
+        mkdirSync(dirname(destAbs), { recursive: true });
+        writeFileSync(destAbs, propagateOrigin(specProvenance, content));
+        await gitHard(['add', '--', destRel], cwd, env);
+        if (destRel !== agentRel) {
+            const srcAbs = join(cwd, agentRel);
+            rmSync(srcAbs, { force: true });
+            // Also unstage if `git add --` from a previous run picked it up;
+            // untracked-and-now-gone is fine.
+            await gitSoft(['rm', '-f', '--quiet', '--', agentRel], cwd, env);
+        }
+    }
+}
+/**
+ * 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`
+ * 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.
+ */
+async function scrubPoolDrift(cwd, poolBefore, env) {
+    const dir = workFolderPath(cwd, 'tasks-ready');
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!isWorkItemFile(name)) {
+            continue;
+        }
+        const abs = join(dir, name);
+        const content = readFileSync(abs, 'utf8');
+        if (poolBefore.has(name)) {
+            if (poolBefore.get(name) === content) {
+                continue;
+            }
+            // The agent edited a pre-existing pool task — restore it from HEAD.
+            await gitSoft(['checkout', 'HEAD', '--', workItemRel('tasks-ready', name)], cwd, env);
+            continue;
+        }
+        // The agent introduced a NEW file in the pool: drop it.
+        rmSync(abs, { force: true });
+    }
+}
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(args, cwd, env) {
+    const result = await runAsync('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+/**
+ * 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
+ * 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 ` +
+        `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.
+ */
+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 ` +
+        `to needs-attention with no guessed tasks; a human must resolve:`;
+    const body = questions.length > 0
+        ? questions.map((q) => `- ${q}`).join('\n')
+        : '- (no specific questions surfaced; the decomposition is broadly unclear)';
+    return `${head}\n${body}`;
+}
+/**
+ * Mark a candidate task file `needsAnswers: true` and record its open questions in
+ * its body (the loop's uncertain-task routing outcome). The runner writes the
+ * file; the agent does no git/disk-escape. A path outside `work/tasks/backlog/`
+ * is skipped (defensive). A relative `work/tasks/backlog/<slug>.md` that does not
+ * exist is skipped with a note (never crash the transition).
+ */
+function markTaskNeedsAnswers(cwd, relPath, questions, note) {
+    const normalized = relPath.replace(/\\/g, '/');
+    if (!normalized.startsWith(`${STAGED_TASKS_DIR}/`) ||
+        normalized.includes('..')) {
+        note(`Skipped a needsAnswers mark outside ${STAGED_TASKS_DIR}/ (${relPath}).`);
+        return;
+    }
+    const abs = join(cwd, normalized);
+    if (!existsSync(abs)) {
+        note(`Skipped a needsAnswers mark for missing candidate task ${relPath}.`);
+        return;
+    }
+    const current = readFileSync(abs, 'utf8');
+    const marked = setNeedsAnswersMarker(current, true);
+    writeFileSync(abs, appendQuestionsBlock(marked, questions));
+}
+/** The heading that opens the open-questions block in an uncertain task body. */
+const OPEN_QUESTIONS_HEADING = '## Open questions';
+/**
+ * Append an `## Open questions` block (prose, never a frontmatter field —
+ * WORK-CONTRACT rule 3) listing the loop's surfaced questions to an uncertain
+ * task's body. A human answers these before the task becomes agent-buildable.
+ */
+function appendQuestionsBlock(content, questions) {
+    if (questions.length === 0) {
+        return content;
+    }
+    const base = content.replace(/\s*$/, '');
+    const items = questions.map((q) => `- ${q}`).join('\n');
+    return [base, '', OPEN_QUESTIONS_HEADING, '', items, ''].join('\n');
+}
+/**
+ * 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.
+ */
+function resolveAgentGate(cwd, slug, specFm, autoTask, explicit) {
+    return resolveTaskingEligibility({
+        humanOnly: specFm.humanOnly,
+        needsAnswers: specFm.needsAnswers,
+        taskedAfter: specFm.taskedAfter,
+        taskedSlugs: readTaskedSlugs(cwd),
+        autoTask: autoTask ?? false,
+        explicit,
+    });
+}
+/** Build an HONEST gate-refusal message naming WHY the agent skipped the prd. */
+function gateRefusalReason(slug, specFm, eligibility, options) {
+    const reasons = [];
+    if (specFm.humanOnly === true) {
+        reasons.push('the prd is humanOnly (a human must drive its tasking)');
+    }
+    if (specFm.needsAnswers === true) {
+        reasons.push('the prd 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
+    // build path's autoBuild precedent), so the policy is never the reason there.
+    if (options.explicit !== true &&
+        specFm.humanOnly !== true &&
+        specFm.needsAnswers !== true &&
+        (options.autoTask ?? false) !== true) {
+        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(', ')}`);
+    }
+    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
+ * 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
+ * (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.
+ */
+function readTaskedSlugs(cwd) {
+    const slugs = new Set();
+    const dir = workFolderPath(cwd, 'specs-tasked');
+    for (const file of listMarkdown(dir)) {
+        const content = readFileSync(join(dir, file), 'utf8');
+        const fm = parseFrontmatter(content);
+        slugs.add(fm.slug ?? file.replace(/\.md$/i, ''));
+    }
+    return slugs;
+}
+/**
+ * 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
+ * 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
+ * (task `slicing-protocol-doc-and-vocabulary-fix`). The shape's source of
+ * truth is the frontmatter parser + the task template (`work/protocol/
+ * 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
+ * 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) {
+    return [
+        `You are a FRESH-CONTEXT tasker for the prd \`work/prds/ready/${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:`,
+        `decompose it into independently-grabbable, tracer-bullet vertical tasks.`,
+        `Read the prd 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 emitted task shape — ALL live in that doc. Read them there.`,
+        ``,
+        `No human is present, so apply the CONFIDENCE CHECK (\`TASKING-PROTOCOL.md\``,
+        `step 4): only emit tasks you would have gotten a human to approve. If`,
+        `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.`,
+        ``,
+        `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`,
+        `the runner owns the runner/human-only promotion into it; the tasker's staging`,
+        `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.`,
+        ``,
+        `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/\`).`,
+    ].join('\n');
+}
+/** Run the task agent. Prefers the injected runner; else the harness seam. */
+async function runTaskAgent(options, cwd, prompt, slug) {
+    // The tasker AGENT launches with the AMBIENT env (`agentEnv`), never the
+    // identity-scoped `env` (an agent must not act as the bot). Falls back to `env`
+    // when no identity is configured.
+    const agentEnv = options.agentEnv ?? options.env;
+    if (options.dorfl) {
+        return options.dorfl({ cwd, prompt, slug, env: agentEnv });
+    }
+    const harness = options.harness ?? new NullHarness();
+    const launched = await launchWithOptionalWatch({
+        harness,
+        dir: cwd,
+        slug,
+        command: options.agentCmd ?? '',
+        prompt,
+        model: options.model,
+        sessionId: `task-${slug}`,
+        sessionsDir: options.sessionsDir,
+        env: agentEnv,
+    });
+    return { ok: launched.ok, detail: launched.detail };
+}
+/** A snapshot of {@link STAGED_TASKS_DIR}: filename → file content. */
+function snapshotStagedTasks(cwd) {
+    const dir = join(cwd, STAGED_TASKS_DIR);
+    const snap = new Map();
+    for (const file of listMarkdown(dir)) {
+        snap.set(file, readFileSync(join(dir, file), 'utf8'));
+    }
+    return snap;
+}
+/**
+ * Repo-relative paths of the {@link STAGED_TASKS_DIR}`/*.md` files the agent
+ * NEWLY created or CHANGED vs the pre-run snapshot — exactly what the runner
+ * captures + commits. (An untouched pre-existing staged task is NOT
+ * 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) {
+    const dir = join(cwd, STAGED_TASKS_DIR);
+    const changed = [];
+    for (const file of listMarkdown(dir)) {
+        const content = readFileSync(join(dir, file), 'utf8');
+        if (before.get(file) !== content) {
+            changed.push(stagedTaskPath(file));
+        }
+    }
+    return changed.sort();
+}
+/** Snapshot the POOL `work/tasks/ready/` (for the agent-write fence at stage time). */
+function snapshotPool(cwd) {
+    const dir = workFolderPath(cwd, 'tasks-ready');
+    const snap = new Map();
+    for (const file of listMarkdown(dir)) {
+        snap.set(file, readFileSync(join(dir, file), 'utf8'));
+    }
+    return snap;
+}
+/** Read the produced backlog tasks' content keyed by repo-relative path. */
+function collectEmittedTasks(cwd, relPaths) {
+    const out = {};
+    for (const rel of relPaths) {
+        out[rel] = readFileSync(join(cwd, rel), 'utf8');
+    }
+    return out;
+}
+/** List `*.md` files in `dir`, sorted; an absent dir reads as empty. */
+function listMarkdown(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((name) => isWorkItemFile(name)).sort();
+}
+//# sourceMappingURL=tasking.js.map