dorfl 0.14.2 → 0.15.0

package/dist/ci-phase-tasking.d.ts

@@ -0,0 +1,205 @@
+/**
+ * **The tasking path split into the three CI phases** (spec
+ * `ci-agent-job-without-write-token` §3 tasking row, ADR
+ * `ci-agent-job-holds-no-write-token`, task `ci-split-tasking`).
+ *
+ * `do spec:<slug>` / `advance spec:<slug>` with `--phase` run ONE of three
+ * halves of the one tasking pipeline (`tasking.ts`: {@link runTaskingAgentHalf}
+ * is the agent half, {@link integrateTaskingCandidates} /
+ * {@link surfaceTaskingBlock} / {@link persistTaskingCandidates} the write half),
+ * never a second implementation:
+ *
+ *  - **lock** ({@link performTaskingLockPhase}): fetch `<arbiter>/main` (its tip
+ *    is `baseSha`); in a throwaway worktree of it, check the spec rests in
+ *    `work/specs/ready/` and passes the agent tasking gate (and, for `advance`,
+ *    classifies on the `task-spec` rung); take the tasking lock
+ *    (`acquireTaskingLock`, the unified `spec:<slug>` lock, `action: task`);
+ *    publish `acquired`, `needsAgent`, `rung`, `baseSha`, `lockSha`,
+ *    `handoffName` and `agentTimeoutMinutes`. No agent, no repository code.
+ *  - **agent** ({@link performTaskingAgentPhase}): check, read-only, that the
+ *    lock ref still equals `lockSha`; on a `work/spec-<slug>` branch cut from
+ *    `baseSha`, run the tasker, its review rounds, and the one-round task-set
+ *    review (which the laptop path runs inside `performIntegration`; it is an
+ *    agent, so it runs HERE), then hand over `tasking-land` (the candidates, the
+ *    PR body, the review verdict and prose, the trimmed spec body) or
+ *    `tasking-surface` (the candidates to save, the reason). Writes nothing to
+ *    the arbiter: every write seam records into a recorder that knows no write.
+ *    A tasker failure writes no handoff and fails the job.
+ *  - **apply** ({@link performTaskingApplyPhase}): refuse to write unless the
+ *    lock ref still equals `lockSha`; act on the agent job's result first
+ *    (`failure` / timeout surfaces the spec, a real cancel only releases the
+ *    lock); read the handoff as hostile and never take a bundle: it re-commits
+ *    only VALIDATED candidate files ({@link checkTaskingCandidate}) and the
+ *    validated trimmed spec body ({@link checkTrimmedSpecBody}) on a fresh
+ *    `work/spec-<slug>` branch cut from `baseSha`, then integrates with the spec
+ *    move and the review OFF (it already ran), or saves the candidates on the
+ *    work branch, closes a stale PR in propose mode and surfaces. Every lock
+ *    release is leased on `lockSha`.
+ */
+import { type HandoffRecord } from './ci-handoff-format.js';
+import type { LockOutputs } from './ci-lock-outputs.js';
+import type { AgentJobResult, GithubApiGet } from './ci-agent-result.js';
+import type { DoOptions } from './do.js';
+import { type Frontmatter } from './frontmatter.js';
+import type { Phase } from './phase.js';
+/** The verb a tasking phase runs under (they classify the argument differently). */
+export type TaskingPhaseVerb = 'do' | 'advance';
+/** Options of a tasking phase run: the `do` pipeline's options plus the phase inputs. */
+export interface TaskingPhaseOptions extends DoOptions {
+    /** Which of the three jobs this process is. */
+    phase: Phase;
+    /** `do spec:<slug>` or `advance spec:<slug>`. */
+    verb: TaskingPhaseVerb;
+    /** agent: write the handoff here (empty or absent); apply: read it (under {@link runnerTemp}). */
+    handoffDir?: string;
+    /** `$RUNNER_TEMP` (the apply phase); defaults to the env's. */
+    runnerTemp?: string;
+    /** The lock job's outputs (agent / apply); defaults to `DORFL_LOCK_OUTPUTS`. */
+    lockOutputs?: LockOutputs;
+    /** `github.run_attempt` (the lock phase names the artifact with it); default the env's, else 1. */
+    runAttempt?: string;
+    /** The `$GITHUB_OUTPUT` file the lock phase appends to; default the env's. */
+    githubOutput?: string;
+    /** The merge-mode CAS-loop jitter (tests pass 0). */
+    mergeJitterMs?: number;
+    /** apply: `needs.agent.result` (`--agent-result`), REQUIRED. Only `success` reads the handoff. */
+    agentResult?: AgentJobResult;
+    /** apply: the agent job's timeout (`--agent-timeout-minutes`); default the lock outputs'. */
+    agentTimeoutMinutes?: number;
+    /** apply: the Actions API reader (tests stub it); default `fetch` with `GITHUB_TOKEN`. */
+    actionsApi?: GithubApiGet;
+}
+/** How a tasking phase run ended. */
+export type TaskingPhaseOutcome = 
+/** lock: the spec is locked; the agent phase runs next. */
+'locked'
+/** lock: nothing to task at the arbiter's `main`. */
+ | 'no-op'
+/** lock: the agent tasking gate refused the spec (nothing was written). */
+ | 'gate-refused'
+/** lock: another run holds the spec's lock. */
+ | 'lost'
+/** agent / apply: the lock ref no longer equals `lockSha`; nothing was done. */
+ | 'stale-lock'
+/** agent: the handoff was written (see `intent`). */
+ | 'handed-over'
+/** agent: the tasker (or the phase) failed; no handoff (the job fails). */
+ | 'agent-failed'
+/** apply: the tasks and the spec move landed on `main`; the lock was released. */
+ | 'landed'
+/** apply: the work branch was pushed (and a PR requested); the lock stays held. */
+ | 'proposed'
+/** apply: the spec was surfaced to needs-attention and its lock released. */
+ | 'surfaced'
+/** apply: surfacing the spec did not land on the arbiter. */
+ | 'surface-unmoved'
+/** apply: the spec on `main` changed since the lock job; nothing was written. */
+ | 'stale'
+/** apply: the agent job was cancelled (not timed out); the lock was only released. */
+ | 'released'
+/** apply: the cancelled agent job's leased lock release was refused. */
+ | 'release-refused'
+/** apply: the handoff broke a rule; the spec was surfaced, nothing from it landed. */
+ | 'rejected'
+/** A usage or environment problem. */
+ | 'usage-error';
+/** The result of one tasking phase run. */
+export interface TaskingPhaseResult {
+    /** See "A handled outcome is green" in `ci-phase-driver.ts`. */
+    exitCode: 0 | 1 | 2 | 3 | 4;
+    outcome: TaskingPhaseOutcome;
+    /**
+     * The result line: the CLI prints it (`>> ` or `error: `), so the phase does
+     * NOT also `note` it (each line appears once in the job log).
+     */
+    message: string;
+    slug?: string;
+    /** lock: the facts published. */
+    lockOutputs?: LockOutputs;
+    /** agent: the handed-over intent kind. */
+    intent?: HandoffRecord['intent']['kind'];
+    /** apply: the repository paths of the tasks the runner committed. */
+    emitted?: string[];
+}
+/**
+ * Run one phase of the tasking path. The CLI calls this for `do spec:<slug>
+ * --phase` and `advance spec:<slug> --phase`.
+ */
+export declare function performTaskingPhase(options: TaskingPhaseOptions): Promise<TaskingPhaseResult>;
+/**
+ * The lock phase: check the spec at the arbiter's `main`, take the tasking lock
+ * and publish the trusted facts. Runs no agent and no repository code. A spec
+ * that is not taskable at `baseSha` is refused BEFORE any write.
+ */
+export declare function performTaskingLockPhase(options: TaskingPhaseOptions): Promise<TaskingPhaseResult>;
+/**
+ * The agent phase: after a read-only lock-ownership check, run the tasker, its
+ * review rounds and the task-set review on a `work/spec-<slug>` branch cut from
+ * `baseSha`, and write the handoff. Holds a read-only token: every write seam
+ * records into a recorder that knows no write, so a write attempt fails the
+ * job. Any failure writes no handoff and fails the job (the apply job then
+ * surfaces the spec).
+ */
+export declare function performTaskingAgentPhase(options: TaskingPhaseOptions): Promise<TaskingPhaseResult>;
+/** The spec's origin stamp at `baseSha`: the one every candidate carries. */
+export type OriginStamp = Pick<Frontmatter, 'origin' | 'originTrust'>;
+/**
+ * Check ONE candidate task file of a hostile handoff and return the content the
+ * apply job commits (spec §3 "Structured products", task `ci-split-tasking`).
+ *
+ * - The path is derived, never taken: `work/tasks/backlog/<slug>.md`, and the
+ *   slug must be safe (`slug-safety.ts`; the record validation already refused
+ *   any other key, so `..` or a folder can never reach here).
+ * - It must be NEW relative to `baseSha`: a candidate that names a staged task
+ *   already on the base is an edit to a task this run did not produce.
+ * - Its frontmatter must parse (an opening AND a closing `---`): an unclosed
+ *   fence reads as no frontmatter, which would silently drop the stamp.
+ * - `humanOnly` / `needsAnswers` must each appear at most once and read as a
+ *   boolean. Their VALUES are not judged: the review loop that sets them ran in
+ *   the hostile job, and every candidate lands staged for a human to promote.
+ * - `origin` / `originTrust` are OVERWRITTEN with the spec's stamp at `baseSha`:
+ *   every such line is dropped (with its continuation lines) and exactly one of
+ *   each is written, so a candidate that repeats `originTrust: trusted` cannot
+ *   keep one past the stamp (observation
+ *   `tasker-drafted-duplicate-origintrust-launders-propagated-stamp`); then the
+ *   result is re-parsed with `assertFrontmatterFields`, and any duplicate or
+ *   mismatch rejects it.
+ *
+ * Throws {@link HandoffRejected} on any breach.
+ */
+export declare function checkTaskingCandidate(params: {
+    slug: string;
+    content: string;
+    stamp: OriginStamp;
+    existsAtBase: boolean;
+}): string;
+/**
+ * The spec frontmatter keys a trimmed body must keep EXACTLY as they are at
+ * `baseSha`: the gate keys (`humanOnly`, `needsAnswers`, `taskedAfter`), the
+ * issue link and the origin stamp, plus `slug` (the tasked-spec identity
+ * `taskedAfter` of other specs resolves against).
+ */
+export declare const SPEC_PINNED_KEYS: readonly ["humanOnly", "needsAnswers", "taskedAfter", "issue", "origin", "originTrust", "slug"];
+/** The headings a trimmed spec keeps (its durable framing, TASKING-PROTOCOL §6). */
+export declare const SPEC_REQUIRED_HEADINGS: readonly ["Problem Statement", "Solution", "User Stories"];
+/**
+ * Check the trimmed spec body of a hostile `tasking-land` against the spec at
+ * `baseSha`, and return the body the apply job commits as the tasked spec. Its
+ * frontmatter must parse; every {@link SPEC_PINNED_KEYS} key must read EXACTLY
+ * as at `baseSha` (the same top-level lines, in the same order, with the same
+ * continuation lines, so neither a first-wins nor a last-wins reader can see
+ * another value); and every {@link SPEC_REQUIRED_HEADINGS} heading the base
+ * spec has must still be there. Throws {@link HandoffRejected} otherwise.
+ */
+export declare function checkTrimmedSpecBody(params: {
+    slug: string;
+    body: string;
+    baseSpec: string;
+}): string;
+/**
+ * The apply phase: check the lock is still this run's, act on the agent job's
+ * result, validate the handoff as hostile, then resume at the tasking write
+ * half. Runs no agent and no repository code.
+ */
+export declare function performTaskingApplyPhase(options: TaskingPhaseOptions): Promise<TaskingPhaseResult>;
+//# sourceMappingURL=ci-phase-tasking.d.ts.map

package/dist/ci-phase-tasking.d.ts.map

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