dorfl 0.0.0 → 0.1.0

package/dist/tasking.d.ts

@@ -0,0 +1,275 @@
+import type { IntegrationMode } from './config.js';
+import type { ReviewProvider } from './integrator.js';
+import { type AcquireTaskingLockOptions, type AcquireTaskingLockResult, type ReleaseTaskingLockOptions, type ReleaseTaskingLockResult } from './tasking-lock.js';
+import { type Harness } from './harness.js';
+import { type TaskReviewGate } from './tasker-review-loop.js';
+import type { ReviewGate } from './review-gate.js';
+/**
+ * The **`do prd:<slug>` tasking path** (prd `auto-slice`, task
+ * `autoslice-command`) — the orchestration that ties the tasking GATE
+ * (`tasking-eligibility.ts`) and the tasking LOCK (`tasking-lock.ts`) together to
+ * task a prd into `work/tasks/backlog/` STAGED items (task
+ * `pre-backlog-staging-folder-and-promote-step-a` — the runner-owned promotion
+ * moves them `pre-backlog/ → backlog/` later), with the RUNNER owning every git-state
+ * transition. This is the prd branch of the `do` worker (ADR
+ * `command-surface-and-journeys.md` §3/§3a), NOT a standalone `task` command;
+ * `do.ts` dispatches `resolved.namespace === 'prd'` here.
+ *
+ * The end-to-end flow (mirroring the `do`/`run` runner-owns-git discipline — the
+ * agent only EDITS files, the runner does ALL git):
+ *
+ *   1. **Resolve the gate** (agent path): refuse to task a prd that is
+ *      `humanOnly`/`needsAnswers`, or whose `taskedAfter` prds are not yet tasked.
+ *      The repo's `autoTask` POLICY also refuses on the AUTO-PICK pool path, but
+ *      NOT when the prd was named EXPLICITLY (`do prd:<slug>`, `explicit: true`):
+ *      naming it IS the authorization, exactly as `do <task>` builds regardless of
+ *      `autoBuild` (the pool, not the explicit claim, gates the policy). The HUMAN
+ *      path is unbound by the gate entirely.
+ *   2. **Acquire the lock** (agent path) via the unified per-item lock CAS —
+ *      serialising concurrent taskers on the `prd:<slug>` ref (the body STAYS in
+ *      `work/prds/ready/`; the lock no longer moves it). The HUMAN path with no contention
+ *      may task on `main` directly WITHOUT the lock.
+ *   3. **Invoke the agent harness** with the `to-task` prd — the agent runs the
+ *      tasker methodology and produces `work/tasks/backlog/<slug>.md` FILES ONLY; it does
+ *      NOT commit/push/move (the same in-band boundary as the build agent).
+ *   4. **The runner integrates the COMPLETING transition through the SHARED core**
+ *      (`performIntegration`, task `slice-output-through-integration`): the agent's
+ *      tasking runs on a `work/<slug>` branch cut from `<arbiter>/main` (whose base
+ *      holds the prd in `work/prds/ready/`), and the produced backlog tasks + the durable
+ *      prd lifecycle move (`work/prds/ready/ → work/prds/tasked/`)
+ *      integrate via the band honoring `--propose` (push the 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:` integrate arg applies
+ *      to `do prd:` by construction. A content-identity STALE CHECK (the lock's
+ *      read-stability backstop) fires FIRST against the acquire-time `lockedBlob`,
+ *      so a concurrent edit of the held prd still fails loud (`stale`).
+ *
+ * The tasking LOCK (`tasking-lock.ts`, `acquireTaskingLock`/`releaseTaskingLock`)
+ * is the UNIFIED per-item lock (`refs/dorfl/lock/<entry>`, `action: task`)
+ * — the transient `tasking/` folder marker is RETIRED (task
+ * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`). The lock
+ * RELEASE owns the needs-attention redirect for the loop's decomposition-unclear
+ * verdict (it amends the lock `active → stuck` — no folder write); only the SUCCESS
+ * output integrates through the shared core. This path
+ * does NOT build the no-human confidence routing — that is the review/edit loop
+ * owned by `slicer-review-edit-loop`; this path produces + integrates the tasks.
+ */
+/** The terminal status of one `do prd:<slug>` tasking run. */
+export type TaskOutcome = 'tasked' | 'gate-refused' | 'lock-lost' | 'agent-failed' | 'stale' | 'needs-attention' | 'usage-error';
+export interface TaskResult {
+    exitCode: 0 | 1 | 2 | 3 | 4;
+    outcome: TaskOutcome;
+    /** The prd slug acted on. */
+    slug: string;
+    /** Repo-relative paths of the backlog tasks the runner committed. */
+    emitted?: string[];
+    /**
+     * The tasker review→edit LOOP's disposition (`slicer-review-edit-loop`), when
+     * the loop ran. `converged` = the improved tasks landed; `uncertain-tasks` =
+     * the cap was hit and specific tasks landed `needsAnswers: true`; absent when
+     * no loop ran or the prd was routed to needs-attention (`outcome:
+     * 'needs-attention'`).
+     */
+    loop?: 'converged' | 'uncertain-tasks';
+    /** Human-readable summary of the terminal condition. */
+    message: string;
+}
+/**
+ * The agent invocation: runs the `to-task` prd in `cwd`, WRITING
+ * `work/tasks/backlog/<slug>.md` task files (and trimming the prd). It does NO git —
+ * the runner captures the produced files and commits them.
+ */
+export type TaskDorfl = (input: {
+    cwd: string;
+    prompt: string;
+    slug: string;
+    env?: NodeJS.ProcessEnv;
+}) => {
+    ok: boolean;
+    detail?: string;
+};
+/** Injectable lock seams (production: the real CAS; tests: stubs). */
+export interface TaskingLockSeam {
+    acquire(options: AcquireTaskingLockOptions): Promise<AcquireTaskingLockResult>;
+    release(options: ReleaseTaskingLockOptions): Promise<ReleaseTaskingLockResult>;
+}
+export interface PerformTaskOptions {
+    /** The prd slug to task (`work/prds/ready/<slug>.md`). */
+    slug: string;
+    /** The working clone/checkout the tasking runs in. */
+    cwd: string;
+    /** Name of the arbiter git remote. Defaults to `origin`. */
+    arbiter?: string;
+    /**
+     * The DOER: `'agent'` (the default; bound by the gate, MUST take the lock) or
+     * `'human'` (unbound by the gate; with no contention tasks on `main` directly
+     * WITHOUT the lock). The human-vs-agent choice the command wires.
+     */
+    doer?: 'agent' | 'human';
+    /** Per-repo `autoTask` policy (resolved by `autoslice-gate`). Agent path only. */
+    autoTask?: boolean;
+    /**
+     * The prd was named EXPLICITLY by the operator (`do prd:<slug>`), so the
+     * `autoTask` POLICY is already satisfied — naming the prd IS the authorization,
+     * EXACTLY as `do <task>` builds a named task regardless of `autoBuild` (the
+     * build path's precedent: `autoBuild` gates the scan/selection POOL only, never
+     * `performDo`'s explicit claim). When `true`, the agent tasking gate drops the
+     * `autoTask` policy term and binds ONLY the prd's own readiness axes
+     * (`humanOnly`/`needsAnswers`) + `taskedAfter`. Defaults `false`. Both the
+     * explicit `do prd:` dispatch AND the auto-pick path pass `true` here: the
+     * auto-pick POOL (`do-autopick.ts`) is the single `autoTask`-enforcement point
+     * (a pool-ineligible prd is never selected), so once a prd is dispatched its
+     * policy is already settled. Agent path only.
+     */
+    explicit?: boolean;
+    /**
+     * The agent invocation. Tests inject this to write task files directly;
+     * production wires the harness seam. When omitted, {@link harness} is used.
+     */
+    dorfl?: TaskDorfl;
+    /** The harness seam used when `dorfl` is omitted; defaults to the null adapter. */
+    harness?: Harness;
+    /** The configured agent command the harness shells out to (null adapter). */
+    agentCmd?: string;
+    /** The model routing intent forwarded to the harness (ADR §13). */
+    model?: string;
+    /** The HOST-ONLY sessions root for the pi session file. */
+    sessionsDir?: string;
+    /**
+     * The integration mode the produced tasks integrate THROUGH the shared core
+     * with (task `slice-output-through-integration`): `propose` (default — push the
+     * `work/<slug>` branch + open a PR carrying the tasks, NO `main` touch) or
+     * `merge` (land them on `main`). Resolved ONCE in {@link performIntegration},
+     * so EVERY `do task:` integrate-time arg applies to `do prd:` by construction.
+     * The AGENT path only; the human path commits its own output. Defaults to the
+     * system default (`propose`).
+     */
+    integration?: IntegrationMode;
+    /**
+     * **The PR-INTENT axis** (config `noPR`, ADR §6): when `true`, propose pushes
+     * the produced task branch but skips the PR (the explicit suppress-PR intent).
+     * NOT a provider choice — the provider is purely arbiter-derived. Unset/false ⇒
+     * the PR opens normally.
+     */
+    noPR?: boolean;
+    /**
+     * Optional FULLY-FORMED review provider INSTANCE used VERBATIM (the SAME seam
+     * `run`/`do` expose; forwarded to `performIntegration` as `providerInstance`).
+     * Tests/embeddings inject a stubbed `GitHubProvider` (a custom `gh` path) to
+     * drive the propose pipeline OFFLINE. The resolved provider OBJECT, NOT a config
+     * override. Unset ⇒ the core selects from the arbiter URL.
+     */
+    providerInstance?: ReviewProvider;
+    /**
+     * **The task-SET ACCEPTANCE GATE** (task `slice-acceptance-gate`): the
+     * task-path mirror of the build Gate-2, riding {@link performIntegration}'s
+     * review-before-integrate block. When `review` resolves on, a FRESH-CONTEXT
+     * agent reviews the WHOLE produced task SET (coherence / dependency graph /
+     * gaps + overlap / prd-goal correct-if-implemented) BEFORE the tasks integrate;
+     * `approve` lands them, `block` routes the set to needs-attention. It is
+     * controlled by the BUILD `--review`/`--no-review`/`--review-model` family (ONE
+     * gate-configuration story shared with the build path) and is ONE-SHOT —
+     * terminal pass/fail, NO rounds (it does NOT inherit `--review-max-rounds`; the
+     * caller drives it with a single reviewer invocation). It is DISTINCT from and
+     * independently controllable from the tasker improver loop ({@link reviewLoop} /
+     * the `--tasker-loop*` family).
+     */
+    review?: boolean;
+    /** The task-SET acceptance-gate SEAM (injectable). Required when `review` is on. */
+    reviewGate?: ReviewGate;
+    /**
+     * The model the task-SET acceptance-gate reviewer runs on (the BUILD
+     * `--review-model`, de-correlated from the tasker). DISTINCT from the improver
+     * loop's {@link taskerLoopModel} — see the note there.
+     */
+    acceptanceReviewModel?: string;
+    /** Injectable lock seam (tests stub acquire/release). Defaults to the real CAS. */
+    lock?: TaskingLockSeam;
+    /**
+     * **The per-repo TASK-PLACEMENT default** (prd
+     * `staging-pool-position-gate-and-trust-model` US #5, task
+     * `runner-deterministic-slice-placement-policy-and-precedence`). The
+     * resolved per-repo default landing for the tasker's emitted tasks, fed as
+     * the CONFIGURED-DEFAULT rung into the runner-deterministic placement
+     * resolver (`src/placement.ts`). The resolver overlays an EXPLICIT operator
+     * flag ({@link explicitTasksLandIn}, top) and the UNTRUSTED-ORIGIN force
+     * (`originTrust: untrusted` ⇒ staging) on top. Unset ⇒ the resolver's
+     * built-in floor applies (`staging` = `pre-backlog/`, the conservative
+     * landing that preserves zero behaviour change for the normal path).
+     */
+    tasksLandIn?: 'pre-backlog' | 'ready';
+    /**
+     * **The OPERATOR's EXPLICIT task-placement override** (the TOP precedence
+     * rung). When set, the runner-deterministic resolver lands the tasks HERE
+     * regardless of `originTrust` or {@link tasksLandIn} — the positional
+     * analogue of `explicitMerge` overriding the untrusted-origin
+     * build-propose rule ("the operator is present; CLI always wins, no special
+     * force-key"). Set ONLY when the operator typed `--tasks-land-in <where>`;
+     * never when the value came from config.
+     */
+    explicitTasksLandIn?: 'pre-backlog' | 'ready';
+    /**
+     * **The tasker review→edit→converge LOOP** (`slicer-review-edit-loop`, GATES prd
+     * `work/prds/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A). When
+     * provided, AFTER the agent produces candidate tasks (step 3) and BEFORE the
+     * runner finalises them (step 4), run the `review` SKILL as a review→edit→
+     * re-review loop that IMPROVES the candidate tasks in place, then routes the
+     * verdict through the three outcomes (converge→land / uncertain-task→
+     * needsAnswers / decomposition-unclear→prd-to-needs-attention). The seam is the
+     * review+edit gate (tests inject a canned verdict+edits; production:
+     * {@link harnessTaskReviewGate}). Omitted ⇒ NO loop (the candidate tasks land
+     * as-is — the pre-loop behaviour). The HUMAN path is unaffected (the loop runs
+     * on the auto-tasker's output only — see the gating in {@link performTask}).
+     */
+    reviewLoop?: TaskReviewGate;
+    /**
+     * The HARD CAP on the tasker improver loop's in-context review passes (N) —
+     * resolved per-repo (flag `--tasker-loop-max` > env > per-repo > global > cheap
+     * default). Only consulted when {@link reviewLoop} is set. Defaults to 3 (the
+     * cheap default) when omitted.
+     */
+    taskerLoopMax?: number;
+    /**
+     * How many fresh-context EXECUTIONS (M) of the loop to run — each a NEW launch in
+     * a fresh context. Default 1 (the cheap degenerate case). Only consulted when
+     * {@link reviewLoop} is set.
+     */
+    reviewExecutions?: number;
+    /**
+     * The model the IMPROVER loop's review agent runs on (de-correlated from the
+     * tasker; the `--tasker-loop-model` family). Loop only. DISTINCT from the
+     * acceptance gate's {@link acceptanceReviewModel} (build `--review-model`).
+     */
+    taskerLoopModel?: string;
+    /** Environment for child GIT/provider processes (the identity-scoped env). */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Environment for the AGENT launches (the tasker agent + the review/improver
+     * loop's review agent). Distinct from {@link env}: an AGENT must NOT carry the
+     * runner identity (only the runner's git transitions do). Unset ⇒ falls back to
+     * {@link env} (byte-for-byte unchanged for non-identity callers).
+     */
+    agentEnv?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+/**
+ * **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 declare const STAGED_TASKS_DIR: string;
+/**
+ * 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 declare function performTask(options: PerformTaskOptions): Promise<TaskResult>;
+//# sourceMappingURL=tasking.d.ts.map

package/dist/tasking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasking.d.ts","sourceRoot":"","sources":["../src/tasking.ts"],"names":[],"mappings":"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"}