dorfl 0.0.0 → 0.1.1

package/dist/intake.d.ts

@@ -0,0 +1,569 @@
+import type { IntegrateResult, ReviewProvider } from './integrator.js';
+import type { IntegrationMode, SpecsLandIn } from './config.js';
+import type { OriginTrust } from './frontmatter.js';
+import { type Identity } from './identity.js';
+import { type Harness } from './harness.js';
+import { type Issue, type IssueComment, type IssueProvider } from './issue-provider.js';
+import { parseReviewVerdict, type ReviewFinding, type ReviewVerdict } from './review-verdict.js';
+import { type IntakeTriageDecision } from './intake-triage.js';
+/**
+ * **`intake <N>`** (prd `issue-intake`, task `intake-tracer-slice-outcome`): the
+ * KEYSTONE of the issue front-door. A new, GATE-FREE command — explicit invocation
+ * IS the authorization (precedent: `explicit-do-prd-not-gated-by-autoslice`), so
+ * `autoTask`/`autoBuild` config does NOT apply — that reads a GitHub issue + its
+ * thread through the {@link IssueProvider} seam, runs the decision as a
+ * **prompt → VERDICT**, and DISPATCHES on the verdict.
+ *
+ * The engine shape MIRRORS the review gate (prompt → `approve|block` → dispatch):
+ * the decision prompt is an INLINE builder ({@link buildIntakeDecisionSpec}, like
+ * `buildTaskingPrd`); the **dispatcher is the testable seam** — a STUBBED verdict
+ * (injected, no model/network) drives it, exactly as `ReviewGate` is injected. The
+ * prompt's JUDGEMENT is NOT unit-tested (like the review prompt's is not); only the
+ * dispatch is.
+ *
+ * The dispatcher implements the FULL four-outcome decision table (prd
+ * `issue-intake` — the source of truth):
+ * - **ASK** (not clear enough to act on): `postIssueComment` the next clarifying
+ *   question; emit NOTHING; STOP.
+ * - **TASK** (clear AND fits ONE tracer-bullet task): write
+ *   `work/backlog/<slug>.md` (`covers: []`, NO `prd:`) carrying `issue: N` (the
+ *   lone-task closure link, NOT `Fixes #N`), integrate via {@link
+ *   performIntegration} (default `propose`).
+ * - **PRD** (clear AND coherent but >1 task — INCLUDING a coupled-but-SMALL pair,
+ *   which is NEVER bounced): write the prd file (`work/prds/ready/<slug>.md`) with `issue: N` (+ the gate
+ *   axes the verdict carried), integrate, STOP (tasking is the separate `do prd:`
+ *   step).
+ * - **BOUNCE** (genuinely UNRELATED concerns — no shared vision): the bounce is
+ *   TERMINAL (the asks are unrelated and must be re-filed), so intake CLOSES the
+ *   issue ATOMICALLY — the "file separate issues" text as the closing comment +
+ *   `reason: not planned` (the honest GitHub-native signal) in ONE `closeIssue`
+ *   call; emit NOTHING. Intake closes on BOUNCE (as not planned); NEVER on
+ *   task/prd (CI's close-job closes those via the `issue:` field) / ask.
+ *
+ * The per-outcome integration KNOBS, the processing LOCK, and event-classification
+ * are LATER tasks and are NOT built here (default `propose` is fine here).
+ *
+ * The AGENT only DRAFTS (returns the verdict object); the RUNNER (this dispatcher)
+ * owns every git/seam side-effect — the write + integrate (and, in later tasks,
+ * the comment + label ops). The agent is git-free AND seam-free: the in-band
+ * boundary (the SAME discipline the build/tasker agents follow).
+ */
+/**
+ * The four outcomes the decision prompt classifies an issue into (the decision
+ * table). EXPAND step (prd
+ * `prd-to-spec-vocabulary-cutover-and-migration-command`): the `spec` outcome
+ * names the "clear + coherent but >1 task" classification (a parent SPEC). HARD
+ * CUTOVER (contract step): the legacy `prd` outcome token is GONE — the prompt
+ * emits `spec` and the parser rejects any other token.
+ */
+export type IntakeOutcome = 'ask' | 'task' | 'spec' | 'bounce';
+/**
+ * The VERDICT the decision prompt returns — `{ask,task,spec,bounce}` + the drafted
+ * content for the chosen outcome. THIS code path consumes only the `task` branch's
+ * fields (`taskSlug` / `taskTitle` / `taskBody`); the `ask`/`spec`/`bounce`
+ * fields are carried on the shape (so the type is stable for the next task) but
+ * not dispatched here.
+ */
+export interface IntakeVerdict {
+    /** Which outcome the prompt chose for the issue. */
+    outcome: IntakeOutcome;
+    /**
+     * The drafted task's content-derived slug (`task` outcome). The dispatcher
+     * SANITISES it (a content-derived slug, never a counter) before writing
+     * `work/backlog/<slug>.md`. Falls back to a slug derived from {@link taskTitle}
+     * when absent/empty.
+     */
+    taskSlug?: string;
+    /** The drafted task's `title:` (`task` outcome). */
+    taskTitle?: string;
+    /**
+     * The drafted task BODY (`task` outcome) — the markdown AFTER the frontmatter
+     * (the `## What to build` / `## Acceptance criteria` / `## Prompt` sections). The
+     * dispatcher writes the frontmatter (slug/title/`covers: []`, NO `prd:`) carrying
+     * the lone-task `issue: N` closure link itself; the agent never writes
+     * git-visible files.
+     */
+    taskBody?: string;
+    /**
+     * The drafted clarifying question (`ask` outcome) — the dispatcher posts it via
+     * `postIssueComment`, emits nothing, and STOPS (a later run resumes from the
+     * updated thread).
+     */
+    question?: string;
+    /**
+     * The drafted spec's content-derived slug (`spec` outcome). The dispatcher
+     * SANITISES it through `paramCase` (never a counter) before writing the spec
+     * file (`work/specs/ready/<slug>.md`). Falls back to a slug derived from {@link specTitle} when
+     * absent/empty.
+     */
+    specSlug?: string;
+    /** The drafted spec's `title:` (`spec` outcome). */
+    specTitle?: string;
+    /**
+     * The drafted spec BODY (`spec` outcome) — the markdown AFTER the frontmatter
+     * (`## Problem Statement` / `## Solution` / `## User Stories` / …). The dispatcher
+     * writes the frontmatter (title/slug/`issue: N` + the gate axes) itself; the
+     * agent never writes git-visible files.
+     */
+    specBody?: string;
+    /**
+     * The spec's gate axes (`spec` outcome) AS THE PROMPT JUDGED THEM — surfaced onto
+     * the emitted spec frontmatter (prd `issue-intake` US #8: "the emitted artifact
+     * carries … its own gate axes"). Both omitted (undeclared) by default; the prompt
+     * sets `specHumanOnly: true` when a human should drive the TASKING and/or
+     * `specNeedsAnswers: true` when open questions remain.
+     */
+    specHumanOnly?: boolean;
+    specNeedsAnswers?: boolean;
+    /**
+     * The drafted bounce message (`bounce` outcome) — the dispatcher carries it as
+     * the CLOSING COMMENT on the atomic `closeIssue` ("please file separate issues")
+     * with `reason: not planned`, then emits nothing. A bounce is TERMINAL, so the
+     * issue is CLOSED (not left open).
+     */
+    bounceMessage?: string;
+}
+/** The terminal status of one `intake <N>` run. */
+export type IntakeRunOutcome = 'tasked' | 'asked' | 'spec-written' | 'bounced' | 'no-new-input' | 'already-terminal' | 'locked' | 'lock-failed' | 'agent-failed' | 'stale' | 'usage-error';
+export interface IntakeResult {
+    exitCode: 0 | 1 | 4;
+    outcome: IntakeRunOutcome;
+    /** The issue number acted on. */
+    issueNumber: number;
+    /** The slug of the emitted artifact (task OR prd outcome). */
+    emittedSlug?: string;
+    /** Repo-relative path of the emitted artifact (task OR prd outcome). */
+    emitted?: string;
+    /** True iff a comment was posted on the issue (ask / bounce outcomes). */
+    commented?: boolean;
+    /**
+     * True iff the ISSUE was closed (the BOUNCE outcome — a terminal bounce closes
+     * the issue atomically as `not planned`). Additive (mirrors {@link commented}),
+     * so CI / callers can observe the close. Never set on ask/task/prd.
+     */
+    closed?: boolean;
+    /** Human-readable summary of the terminal condition. */
+    message: string;
+}
+/**
+ * The DECISION step: given the issue + thread, return a VERDICT. Tests inject a
+ * canned verdict (the STUBBED seam that drives the dispatcher, no model/network).
+ * Production wires the harness through {@link harnessIntakeDecision}.
+ */
+export type IntakeDecider = (input: {
+    cwd: string;
+    issue: Issue;
+    comments: IssueComment[];
+    prompt: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<IntakeVerdict>;
+export interface PerformIntakeOptions {
+    /** The issue number to intake (`intake <N>`). */
+    issueNumber: number;
+    /** The working clone/checkout the intake runs in. */
+    cwd: string;
+    /** Name of the arbiter git remote. Defaults to `origin`. */
+    arbiter?: string;
+    /**
+     * The issue seam (read the issue + thread). Tests inject a STUB; production
+     * defaults to {@link GitHubIssueProvider} (the only place `gh` is shelled out).
+     */
+    issueProvider?: IssueProvider;
+    /**
+     * The DECISION seam (prompt → verdict). Tests inject a CANNED verdict (no
+     * model/network) — this is the unit-test target. Production wires the harness.
+     */
+    decide?: IntakeDecider;
+    /**
+     * The LONE-TASK bounded-review seam (prompt → review verdict). After a `task`
+     * verdict and BEFORE the write/integrate, {@link dispatchTask} runs a bounded
+     * (3-round, HARD-CAPPED) adversarial self-review on the SINGLE drafted task
+     * through this seam (observation
+     * `intake-lone-task-skips-adversarial-review-the-prd-path-gets`, rulings A/B/C).
+     * Tests inject a CANNED review verdict (no model/network) — the new testable
+     * seam; production wires the harness ({@link harnessLoneTaskReviewGate}). It
+     * mirrors {@link decide}'s injectable shape, NOT the tasker loop (which is a
+     * SET-level reviewer this never imports/calls).
+     */
+    reviewTask?: LoneTaskReviewGate;
+    /** The harness seam used when {@link decide} 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 PER-OUTCOME integration modes (prd `issue-intake` US #9) the emitted artifact integrates
+     * THROUGH the shared core with. Because `intake` decides the artifact TYPE at
+     * RUNTIME, the mode is keyed per type: an emitted task integrates with
+     * `integration.task`, an emitted prd with `integration.prd` (`propose` =
+     * push the `work/<slug>` branch + open a PR, NO `main` touch; `merge` = land on
+     * `main`). The CLI resolves this from the granular + aggregate flags via
+     * {@link resolveIntakeIntegrationModes}; ask/bounce emit nothing, so the modes
+     * are no-ops for them. Unset ⇒ propose for both.
+     */
+    integration?: IntakeIntegrationModes;
+    /**
+     * **The ORIGIN-TRUST verdict, passed IN** (task
+     * `untrusted-origin-forces-build-propose`; the `--origin-trust <trusted|untrusted>`
+     * CLI flag). `intake` STAMPS `origin: issue` + this `originTrust` onto every prd/
+     * task it emits, so the author-trust signal SURVIVES the prd/task merge
+     * boundary (a landed-on-main artifact otherwise erases how it was born, the
+     * laundering gap). `intake` does NOT resolve trust itself: the verdict is CI's
+     * POLICY, computed in the `intake.yml` shell from the SAME `author_association`
+     * case as the integration flags and threaded IN here (preserving the ~L296
+     * boundary). UNSET means the artifact is emitted UNSTAMPED, read as `human`/trusted:
+     * a LOCAL `dorfl intake <N>` (no CI shell, no `--origin-trust`) is the
+     * human-IS-the-checkpoint path, gate-free exactly as `do`.
+     */
+    originTrust?: OriginTrust;
+    /**
+     * **The PR-INTENT axis** (config `noPR`, ADR §6): when `true`, intake's propose
+     * emissions push the branch but skip 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;
+    /**
+     * **The per-repo PRD-PLACEMENT default, passed IN** (prd
+     * `staging-pool-position-gate-and-trust-model` US #2/#5, task
+     * `pre-prd-staging-pool-split-and-untrusted-prd-placement`). The resolved
+     * per-repo default landing for `intake`-authored prds (`pre-proposed` =
+     * staging; `ready` = the auto-tasking pool), fed as the CONFIGURED-DEFAULT rung
+     * into the shared placement resolver (`src/placement.ts`). The resolver
+     * overlays an EXPLICIT operator flag ({@link explicitSpecsLandIn}, top) and
+     * the UNTRUSTED-ORIGIN force (`originTrust: untrusted` ⇒ staging) on top.
+     * Unset ⇒ the resolver's built-in floor applies (`staging` = `prds/proposed/`,
+     * the conservative landing). The PRD TWIN of `tasksLandIn` on the tasker
+     * path — one resolver, two lifecycles.
+     */
+    specsLandIn?: SpecsLandIn;
+    /**
+     * **The OPERATOR's EXPLICIT spec-placement override** (the TOP precedence
+     * rung). When set, the runner-deterministic resolver lands the spec HERE
+     * regardless of `originTrust` or {@link specsLandIn} — 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
+     * `--specs-land-in <where>`; never when the value came from config.
+     */
+    explicitSpecsLandIn?: SpecsLandIn;
+    /**
+     * 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 intake's propose pipeline OFFLINE. The resolved provider OBJECT, NOT a
+     * config override. Unset ⇒ the core selects from the arbiter URL.
+     */
+    providerInstance?: ReviewProvider;
+    /**
+     * The optional runner IDENTITY (a bot), threaded from host-only
+     * `config.identity`. It scopes intake's GIT + provider operations — the `gh`
+     * issue ops (read/label/comment/close), the push, and the PR — via process-
+     * scoped env overrides. It is NEVER applied to the intake AGENT launches (the
+     * decision agent + the lone-task review agent), which stay ambient: an agent
+     * must not act as the bot. Absent ⇒ ambient (today's behaviour).
+     */
+    identity?: Identity;
+    /** Environment for child git/agent processes (the AGENT-launch ambient env). */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+/**
+ * **The STAGED-prds dir** (prd `staging-pool-position-gate-and-trust-model`,
+ * task `pre-prd-staging-pool-split-and-untrusted-prd-placement`, governing
+ * ADR `placement-is-runner-deterministic-humanonly-is-agent-judgement`). When
+ * the runner-deterministic placement resolver picks the staging side for an
+ * `intake`-authored prd, the runner writes the prd file HERE instead of in
+ * `work/prds/ready/`. An item born in `prds/proposed/` is durable + readable but NOT in
+ * the tasking candidate POOL (`work/prds/ready/` is the pool). A runner/human-owned promotion
+ * ({@link promoteFromPreSpec} in `needs-attention.ts`) moves an approved prd
+ * `prds/proposed/ → prds/ready/` to make it taskable.
+ */
+export declare const STAGED_SPECS_DIR: string;
+/**
+ * The emitted artifact TYPE `intake` decides at RUNTIME — a `task` verdict emits
+ * `work/backlog/<slug>.md`, a `prd` verdict emits the prd file (`work/prds/ready/<slug>.md`). The two
+ * granular flag axes (`--merge-task`/`--propose-task` vs `--merge-spec`/
+ * `--propose-spec`) are keyed on this. (ask/bounce emit NOTHING, so the modes are
+ * no-ops for them.)
+ */
+export type IntakeArtifactType = 'task' | 'spec';
+/**
+ * The PER-OUTCOME integration mode FLAG SET (prd `issue-intake` US #9). Because
+ * `intake` decides the artifact TYPE at runtime, a single `--merge`/`--propose`
+ * cannot express a type-conditional policy ("merge a prd but propose a task") —
+ * hence the four GRANULAR per-type flags layered over the two AGGREGATES:
+ *
+ * - **granular:** `--merge-spec`/`--propose-spec` apply iff the outcome is a spec;
+ *   `--merge-task`/`--propose-task` apply iff it is a task.
+ * - **aggregates:** `--merge` = merge BOTH types; `--propose` = propose BOTH.
+ *
+ * `intake` owns only these KNOBS; WHICH knobs CI sets (from gate state +
+ * author-trust) is CI's POLICY, authored in `runner-in-ci` — NOT here.
+ */
+export interface IntakeIntegrationFlags {
+    /** Aggregate: merge BOTH a task and a prd (the broad knob, overridden per type). */
+    merge?: boolean;
+    /** Aggregate: propose BOTH a task and a prd. */
+    propose?: boolean;
+    /** Granular: merge a spec (overrides the aggregate for the spec outcome). */
+    mergeSpec?: boolean;
+    /** Granular: propose a spec (overrides the aggregate for the spec outcome). */
+    proposeSpec?: boolean;
+    /** Granular: merge a task (overrides the aggregate for the task outcome). */
+    mergeTask?: boolean;
+    /** Granular: propose a task (overrides the aggregate for the task outcome). */
+    proposeTask?: boolean;
+}
+/** Both per-type integration modes, resolved from the flag set in ONE eager pass. */
+export interface IntakeIntegrationModes {
+    /** The mode an EMITTED task integrates with. */
+    task: IntegrationMode;
+    /**
+     * The mode an EMITTED spec integrates with. `spec` is the CANONICAL key (prd →
+     * spec cutover); the user-facing `--merge-spec`/`--propose-spec` flags that FEED
+     * it carry the same `spec` spelling (the cli-flag rename landed in batch 4f).
+     */
+    spec: IntegrationMode;
+}
+/**
+ * The PURE per-outcome integration mode resolution (prd `issue-intake` US #9 —
+ * the canonical table). Given ONLY the flag set, resolve BOTH per-type modes in
+ * one eager pass (so a usage error is caught before the runtime verdict is even
+ * known). The rules, all decided in the prd:
+ *
+ * - **unset ⇒ propose for BOTH** (conservative default; matches `do`).
+ * - **aggregates:** `--merge` ⇒ merge both; `--propose` ⇒ propose both (this axis
+ *   COMPOSES the existing {@link integrationFromFlags}, reusing its mutual
+ *   exclusion + error message).
+ * - **granular routes per type:** `--merge-spec` merges a spec (and leaves a task at
+ *   the aggregate/default), etc.
+ * - **GRANULAR OVERRIDES AGGREGATE:** `--merge --propose-task` ⇒ merge a spec,
+ *   propose a task.
+ * - **same type + both modes is a usage ERROR:** `--merge-spec --propose-spec` (and
+ *   `--merge-task --propose-task`), and the aggregate `--merge --propose`.
+ *
+ * Throws (a usage error) on any mutually-exclusive pair. The dispatcher picks the
+ * field matching the runtime verdict's type; ask/bounce never integrate, so the
+ * modes are no-ops for them.
+ *
+ * `defaultMode` is the FALLBACK when NEITHER a granular nor the aggregate flag
+ * selects a mode for a type — it defaults to `propose` (so the pure table reads
+ * "unset ⇒ propose for both"), but the CLI passes the per-repo/global
+ * config-resolved mode so the established precedence chain (flag > per-repo >
+ * global > default) is preserved, exactly as `do`/`complete` resolve it.
+ */
+export declare function resolveIntakeIntegrationModes(flags: IntakeIntegrationFlags, defaultMode?: IntegrationMode): IntakeIntegrationModes;
+/**
+ * Run `intake <N>` end-to-end (the LOCAL one-shot). Never throws for the expected
+ * agent-failed / stale / usage cases — those are returned with the corresponding
+ * exit code and outcome. The runner owns all git/seam side-effects; the agent only
+ * DRAFTS the verdict.
+ */
+export declare function performIntake(options: PerformIntakeOptions): Promise<IntakeResult>;
+/**
+ * Build the INFORMATIONAL completion-comment BODY (with its FULL `created` marker)
+ * for a SUCCESSFUL `task` / `spec` outcome — the PURE, seam-free core of
+ * {@link postCompletionComment}, exported so both link variants are unit-testable
+ * without a live seam. The comment:
+ *
+ * - reports `task created` / `spec created` framed as CREATED — NEVER "issue
+ *   resolved/closed" (intake never closes on the task/spec path).
+ * - LINKS the artifact by INTEGRATION MODE: the PR `url` in propose, the landed
+ *   `commit` (the additive {@link IntegrateResult.commit}) in merge. A degraded
+ *   propose (no `url`) or a failed merge-tip read (no `commit`) simply OMITS the
+ *   link — the comment still confirms what was created (the artifact is safe on the
+ *   branch/main regardless). No prd link beyond the slug.
+ * - carries the FULL intake MARKER via the SHARED {@link stampIntakeMarker} helper
+ *   (`kind=created slug=<slug> seen=<id>,…`) so the triage's `already-terminal`
+ *   branch consumes it — the comment cannot re-trigger intake.
+ */
+export declare function composeIntakeCompletionComment(params: {
+    kind: 'task' | 'spec';
+    slug: string;
+    integration: IntegrateResult | undefined;
+    seen: string[];
+}): string;
+/**
+ * Render the backlog task file: the frontmatter (`title`/`slug`/`covers: []`, NO
+ * `prd:` — its own source of truth, prd `issue-intake` decision table) carrying the lone-task
+ * `issue: N` closure link + the drafted body. The task closes its source issue
+ * via its `issue:` field (the provider-agnostic link a FUTURE CI close-job reads
+ * from folder + field state); it carries NO `Fixes #N` (a deferred GitHub-only
+ * optimisation, structurally unplaceable on the `--merge` path). The number is
+ * the task's own closure path — `issue:` XOR `prd:`; a lone task never carries a
+ * `prd:` (prd `issue-intake` decision table). When the agent drafted no body, a thin default
+ * scaffold keeps the file a valid task.
+ */
+export declare function renderBacklogTask(params: {
+    slug: string;
+    title: string;
+    body: string | undefined;
+    issueNumber: number;
+    /**
+     * The origin-trust STAMP (task `untrusted-origin-forces-build-propose`).
+     * Present ⇒ emit `origin: issue` + `originTrust: <value>` so the becomes-code
+     * checkpoint survives the merge boundary. UNSET (a local intake, no CI shell)
+     * ⇒ NO stamp (the human running intake IS the checkpoint ⇒ human/trusted).
+     */
+    originTrust?: OriginTrust;
+}): string;
+/**
+ * Render the emitted prd file: the frontmatter (`title`/`slug` + the loop-closure
+ * `issue: N` + the gate axes the prompt JUDGED) followed by the drafted prd body.
+ * For a FANNED prd the `issue: N` lives ONLY on the prd — never duplicated across
+ * the N fanned tasks, which reach it via `task.prd: → prd issue:` (a fanned
+ * task carries `prd:`, NOT its own `issue:`; the lone-task outcome is the only
+ * one that puts `issue:` on a task). The close JOB reaches the prd's number via
+ * `task.prd: → prd issue:`. The gate axes (`humanOnly`/`needsAnswers`) are emitted ONLY when the
+ * verdict declared them `true` — an omitted axis is `undefined` (undeclared), the
+ * same convention `frontmatter.ts` parses. When the agent drafted no body, a thin
+ * default scaffold keeps the file a valid prd that `do prd:` can later task.
+ */
+export declare function renderSpec(params: {
+    slug: string;
+    title: string;
+    body: string | undefined;
+    issueNumber: number;
+    humanOnly: boolean | undefined;
+    needsAnswers: boolean | undefined;
+    /**
+     * The origin-trust STAMP (task `untrusted-origin-forces-build-propose`).
+     * Present ⇒ emit `origin: issue` + `originTrust: <value>`, PROPAGATED onto every
+     * emitted task by the tasker so the build transition can read it. UNSET (a
+     * local intake) ⇒ NO stamp (human/trusted).
+     */
+    originTrust?: OriginTrust;
+}): string;
+/**
+ * Parse the decision agent's emitted VERDICT out of its (possibly prose-wrapped /
+ * fenced) textual output into an {@link IntakeVerdict} — the PRODUCTION wire
+ * between the launched agent and the already-built dispatcher, modeled 1:1 on the
+ * review gate's `parseReviewVerdict` twin (`review-gate.ts`). It pulls the first
+ * JSON object carrying an `"outcome"` field via the SHARED
+ * {@link extractJsonObjectSpan} (NOT a forked second "first JSON object in agent
+ * prose" extractor — the review gates anchor on `"verdict"`, intake on
+ * `"outcome"`; same need, one implementation — coherence), `JSON.parse`s it, and
+ * validates the shape: `outcome ∈ {ask,task,spec,bounce}`.
+ *
+ * The per-outcome fields map 1:1 onto {@link IntakeVerdict} (`task` →
+ * taskSlug?/taskTitle/taskBody, `spec` →
+ * specSlug?/specTitle/specBody/specHumanOnly?/specNeedsAnswers?, `ask` → question,
+ * `bounce` → bounceMessage). Missing OPTIONALS are tolerated — the dispatcher
+ * already has fallbacks (slug-from-title, the thin comment/scaffold defaults).
+ *
+ * THROWS a clear error on: no JSON object present, invalid JSON, or an `outcome`
+ * not in the set. The caller (`decideAndDispatch`) maps any throw onto the
+ * `agent-failed` outcome (exit 1) — a malformed verdict degrades honestly, never
+ * a crash and never a silent dispatch.
+ */
+export declare function parseIntakeVerdict(output: string): IntakeVerdict;
+/**
+ * Backwards-compatible alias for {@link ReviewFinding} (task
+ * `review-protocol-doc-and-shared-machinery`). Existing imports keep compiling;
+ * new code should reach for `ReviewFinding` from `review-verdict.ts`.
+ */
+export type LoneTaskReviewFinding = ReviewFinding;
+/**
+ * The lone-task review verdict shape is now the UNIFIED {@link ReviewVerdict}.
+ * The lone-task caller consumes the `edit` / `questions` channels of the wide
+ * type; other review callers consume different channels. The SET/graph/overlap
+ * lenses are still N=1-OFF in the PROMPT (intake never spawns the tasker loop's
+ * set-level sinks); the type itself is shared.
+ */
+export type LoneTaskReviewVerdict = ReviewVerdict;
+/** What the lone-task review gate needs to launch / answer ONE review round. */
+export interface LoneTaskReviewGateInput {
+    /** The drafted task's slug (the candidate under review). */
+    slug: string;
+    /** The source issue number (the destination check's target behaviour). */
+    issueNumber: number;
+    /** The drafted task's title (the candidate under review). */
+    title: string;
+    /** The drafted task BODY as it stands THIS round (after any prior in-memory edits). */
+    body: string;
+    /** Which review ROUND this is (1-based, 1..{@link LONE_TASK_REVIEW_MAX_ROUNDS}). */
+    round: number;
+    /** The working clone/checkout the review runs in. */
+    cwd: string;
+    /** Environment for the review-agent launch. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The lone-task review SEAM: run ONE adversarial review round on the SINGLE
+ * drafted task and return a parsed verdict (incl. an optional in-memory edit).
+ * Tests inject a canned verdict (no model/network) — the new testable seam, mirroring
+ * {@link IntakeDecider}. Production uses {@link harnessLoneTaskReviewGate}.
+ */
+export type LoneTaskReviewGate = (input: LoneTaskReviewGateInput) => Promise<LoneTaskReviewVerdict>;
+/** Options for the production harness-backed lone-task review gate. */
+export interface HarnessLoneTaskReviewGateOptions {
+    /** The harness seam used to launch the fresh-context review agent. */
+    harness?: Harness;
+    /** The configured agent command the harness shells out to. */
+    agentCmd?: string;
+    /** The model routing intent forwarded to the harness (ADR §13). */
+    model?: string;
+    /** The HOST-ONLY sessions root for the review session file. */
+    sessionsDir?: string;
+}
+/**
+ * The PRODUCTION lone-task review gate: launch the `review` SKILL as an agent
+ * through the EXISTING harness seam (the SAME wire {@link runDecision} uses), then
+ * PARSE the emitted `{verdict, findings, edit, questions}` via
+ * {@link parseLoneTaskReviewVerdict}. The agent makes the review JUDGEMENT (the
+ * per-task + destination lenses on the ONE task); this gate launches it and parses
+ * its verdict. A launch failure THROWS (the dispatcher's try/catch maps it onto
+ * `agent-failed`). MIRRORS {@link harnessTaskReviewGate} WITHOUT importing it.
+ */
+export declare function harnessLoneTaskReviewGate(options?: HarnessLoneTaskReviewGateOptions): LoneTaskReviewGate;
+/**
+ * Build the LONE-TASK review PROMPT: instruct a fresh-context agent to apply
+ * the **review discipline** (`work/protocol/REVIEW-PROTOCOL.md`) to the SINGLE
+ * drafted task — per-task well-formedness + the destination check ("if this
+ * task is built exactly as written, do we end up with the behaviour issue #N
+ * asks for?"). The SET / graph / overlap lenses are N=1 and EXPLICITLY OFF.
+ * A round may propose an `edit` (the FULL replacement task body) the runner
+ * applies IN MEMORY and re-reviews; converge when a round finds NO new blocking
+ * issue, else carry the open `questions` into the ASK comment for the human.
+ *
+ * The discipline body and the JSON-emitted-shape contract are SHARED helpers
+ * (task `review-protocol-doc-and-shared-machinery`); this builder owns ONLY
+ * the lone-task-specific framing.
+ */
+export declare function buildLoneTaskReviewPrompt(input: LoneTaskReviewGateInput): string;
+/**
+ * Backwards-compatible alias for the unified {@link parseReviewVerdict}
+ * (task `review-protocol-doc-and-shared-machinery`). The lone-task review
+ * verdict is now the unified {@link ReviewVerdict}; the alias keeps existing
+ * tests/callers compiling.
+ */
+export declare const parseLoneTaskReviewVerdict: typeof parseReviewVerdict;
+/**
+ * Build the intake decision PRD (an inline prompt builder, like `buildTaskingPrd`
+ * in `tasking.ts` / the reviewer prompts in `review-gate.ts` — NOT a standalone
+ * asset/`.md` file; no such convention exists in this package). It encodes the FULL
+ * four-outcome decision table (prd `issue-intake` — the source of truth) and the
+ * three DECISION AIDS stated once there:
+ *
+ * 1. the **"clear?" bar** = `to-task`/`needsAnswers`' "would I build the wrong
+ *    thing if I guessed?" — if a material requirement/scope/acceptance question is
+ *    unanswered, ASK (never guess a spec from a vague issue);
+ * 2. the **"one task?" bar** = `to-task`' tracer-bullet test (one thin end-to-end
+ *    path, demoable on its own) — fits → TASK, needs splitting → PRD;
+ * 3. **PRD vs BOUNCE** turns on a **SHARED VISION**: coupled (even if small) → PRD;
+ *    genuinely unrelated → BOUNCE. Size NEVER forces a bounce — only unrelatedness
+ *    (the over-bounce guard: a coupled-but-small pair gets a light PRD, never a
+ *    bounce).
+ *
+ * The prompt anchors to `to-task`/`to-spec` for the task/spec SHAPES it drafts. Its
+ * JUDGEMENT is NOT unit-tested (exactly as the review prompt's is not) — only the
+ * dispatch is. The agent only DRAFTS the verdict + its content; it does NO git/seam
+ * ops (the runner owns every postComment / write / integrate — the in-band boundary).
+ */
+export declare function buildIntakeDecisionSpec(issue: Issue, comments: IssueComment[], triage?: IntakeTriageDecision): string;
+//# sourceMappingURL=intake.d.ts.map

package/dist/intake.d.ts.map

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