dorfl 0.0.0 → 0.1.0

package/dist/apply-decide.d.ts

@@ -0,0 +1,127 @@
+import { type Harness } from './harness.js';
+import { type SidecarModel } from './sidecar.js';
+import { type DecisionDecider, type DecisionOutcome } from './decision-engine.js';
+/**
+ * The **AGENTIC apply DECIDER** (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary` US #1/#2/#3, task
+ * `agentic-apply-retire-disposition-vocabulary`) — the input-ADAPTER + prompt +
+ * production decider for the apply rung's call into the SHARED
+ * `decide(input, allowedOutcomes)` engine (`decision-engine.ts`). It is the apply
+ * rung's analogue of intake's decision seam and `surface-gate.ts` / `triage-gate.ts`:
+ * the agent JUDGES (reads the human's answer(s) + the SOURCE item and returns a
+ * verdict); the engine VALIDATES it against the allowed set; the apply rung ACTS.
+ *
+ * This is the SUBSUME of the old disposition vocabulary: there is no longer a
+ * `disposition=` token the surface rung stamps and the apply rung executes. When a
+ * fully-answered OBSERVATION reaches the apply rung, this decider reads the answer
+ * + the source's FULL context (body, type, surrounding signal — decision 3, the
+ * analogue of intake reading the whole issue thread) and returns ONE of the LAUNCH
+ * outcomes the apply rung allows. The artifact-type SELECTION (task vs spec) comes
+ * from the agent's VERDICT, NOT a human `promote-*` field.
+ *
+ * **The allowed set** (the SUBSET the apply rung passes to `decide`):
+ * `{task | spec | adr | delete | ask}` \u2014 i.e. `{mint-task | mint-spec | mint-adr |
+ * delete-source | ask-follow-up}`. `adr` was DEFERRED at the keystone launch (no
+ * ADR-mint path existed yet) and is now WIRED by the follow-on task
+ * `agentic-apply-mint-adr-route`, which added the {@link
+ * import('./mint-adr.js').mintAdr} route and widened this set. Intake's set is
+ * UNCHANGED (`{task | spec | ask | bounce}`) \u2014 the engine stays outcome-AGNOSTIC
+ * (PRD decision 14), so widening this caller's subset does NOT touch intake or the
+ * engine's superset union.
+ *
+ * The INPUT adapter ({@link buildApplyDecisionInput}) sits HERE in the caller, not
+ * in the engine (the engine threads `input` opaquely) \u2014 decision 3: the input
+ * adapter is per-front-door and NOT forced to be shared with intake's issue-thread
+ * adapter.
+ */
+/**
+ * The allowed-outcome set the apply rung permits. `adr` is now INCLUDED (task
+ * `agentic-apply-mint-adr-route` widened the keystone's launch subset, which had
+ * deferred it). The engine's superset still carries `adr` either way (it is
+ * outcome-agnostic); this is purely the CALLER's permitted subset.
+ */
+export declare const APPLY_ALLOWED_OUTCOMES: readonly DecisionOutcome[];
+/**
+ * The input the apply decider reads: the answered source item + its answered
+ * sidecar. The decision is grounded in the source's FULL context (body, type,
+ * surrounding signal), not just the latest answer text (decision 3).
+ */
+export interface ApplyDecisionInput {
+    /** The namespaced source identity (`observation:<slug>` at launch). */
+    item: string;
+    /** The source item's type. */
+    type: SidecarModel['type'];
+    /** The source item's body (full context for the decision). */
+    itemBody: string;
+    /** The answered sidecar model (the human's recorded answers + the questions). */
+    sidecar: SidecarModel;
+    /** The working clone/checkout the decision runs in. */
+    cwd: string;
+    /** The model the apply-decision agent runs on (`undefined` \u21d2 the harness default). */
+    model?: string;
+    /** Environment for the decision-agent launch. */
+    env?: NodeJS.ProcessEnv;
+    /** The HOST-ONLY sessions root the decision session FILE is generated under. */
+    sessionsDir?: string;
+}
+/**
+ * The apply-decider SEAM: read the apply input and return a {@link DecisionVerdict}.
+ * Injected by tests (a CANNED verdict, no real model); production uses
+ * {@link harnessApplyDecider}. It is the apply rung's {@link DecisionDecider}
+ * specialised to {@link ApplyDecisionInput}.
+ */
+export type ApplyDecider = DecisionDecider<ApplyDecisionInput>;
+/**
+ * Build the apply-decision INPUT for an answered source item: read its body (from
+ * the working tree) + parse its answered sidecar. The adapter boundary the engine
+ * never sees (it threads this opaquely to the decider). Returns `undefined` when
+ * there is no sidecar or no item file (the apply rung handles those upstream).
+ */
+export declare function buildApplyDecisionInput(opts: {
+    item: string;
+    type: SidecarModel['type'];
+    itemPath: string;
+    cwd: string;
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    sessionsDir?: string;
+}): ApplyDecisionInput | undefined;
+/**
+ * Render the apply-decision agent PROMPT: instruct a fresh-context agent to read
+ * the human's recorded ANSWER(S) + the SOURCE item and emit a single
+ * `{outcome, \u2026}` verdict ({@link parseDecisionVerdict} reads it). The agent decides
+ * what to DO with the answered signal \u2014 mint a self-contained task, mint a SPEC,
+ * mint an ADR, delete the source, or ask one BATCH of follow-up questions \u2014
+ * grounded in the source's full context. It writes NOTHING (the engine acts on
+ * the verdict).
+ *
+ * Mirrors {@link import('./surface-gate.js').buildSurfacePrompt} /
+ * {@link import('./intake.js').buildIntakeDecisionSpec}: a fresh-context agent that
+ * EDITS nothing and EMITS one structured object the ENGINE routes/persists.
+ */
+export declare function buildApplyDecisionPrompt(input: ApplyDecisionInput): string;
+/** What a harness-backed apply decider needs to launch the decision agent. */
+export interface HarnessApplyDeciderOptions {
+    /** The harness seam used to launch the fresh-context decision agent. */
+    harness?: Harness;
+    /** The agent command the null/shell adapter shells out to (`{model}`-aware). */
+    agentCmd?: string;
+    /**
+     * Read the decision agent's textual output for parsing. Production reads
+     * `launched.output` (the ANSWER channel); tests inject `readOutput` to stub a
+     * canned verdict string.
+     */
+    readOutput?: (output: string | undefined) => string;
+}
+/**
+ * The PRODUCTION apply decider: launch a fresh-context agent through the EXISTING
+ * harness seam (routing an optional `model` via `LaunchInput.model` \u2014 the \u00a713
+ * model-routing intent, NOT a new mechanism), then PARSE the emitted verdict via
+ * the SHARED {@link parseDecisionVerdict}. The DIRECT mirror of
+ * `harnessSurfaceGate` / `harnessTriageGate`: a SEPARATE harness launch (fresh
+ * context) in the same checkout `cwd`, fed {@link buildApplyDecisionPrompt}; a
+ * DISTINCT session id (`<item>-apply-decide`) so its session never collides with a
+ * build / review / surface / triage session.
+ */
+export declare function harnessApplyDecider(options?: HarnessApplyDeciderOptions): ApplyDecider;
+//# sourceMappingURL=apply-decide.d.ts.map

package/dist/apply-decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-decide.d.ts","sourceRoot":"","sources":["../src/apply-decide.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,OAAO,EAAC,MAAM,cAAc,CAAC;AAEvD,OAAO,EAA+B,KAAK,YAAY,EAAC,MAAM,cAAc,CAAC;AAC7E,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,eAAe,EAGpB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAM5D,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE,YAAY,CAAC;IACtB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,kBAAkB,GAAG,SAAS,CAyBjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CA4C1E;AAED,8EAA8E;AAC9E,MAAM,WAAW,0BAA0B;IAC1C,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,GAAE,0BAA+B,GACtC,YAAY,CAuBd"}

package/dist/apply-decide.js

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { NullHarness } from './harness.js';
+import { launchWithOptionalWatch } from './agent-launch.js';
+import { parseSidecar, sidecarPathFor } from './sidecar.js';
+import { parseDecisionVerdict, } from './decision-engine.js';
+/**
+ * The **AGENTIC apply DECIDER** (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary` US #1/#2/#3, task
+ * `agentic-apply-retire-disposition-vocabulary`) — the input-ADAPTER + prompt +
+ * production decider for the apply rung's call into the SHARED
+ * `decide(input, allowedOutcomes)` engine (`decision-engine.ts`). It is the apply
+ * rung's analogue of intake's decision seam and `surface-gate.ts` / `triage-gate.ts`:
+ * the agent JUDGES (reads the human's answer(s) + the SOURCE item and returns a
+ * verdict); the engine VALIDATES it against the allowed set; the apply rung ACTS.
+ *
+ * This is the SUBSUME of the old disposition vocabulary: there is no longer a
+ * `disposition=` token the surface rung stamps and the apply rung executes. When a
+ * fully-answered OBSERVATION reaches the apply rung, this decider reads the answer
+ * + the source's FULL context (body, type, surrounding signal — decision 3, the
+ * analogue of intake reading the whole issue thread) and returns ONE of the LAUNCH
+ * outcomes the apply rung allows. The artifact-type SELECTION (task vs spec) comes
+ * from the agent's VERDICT, NOT a human `promote-*` field.
+ *
+ * **The allowed set** (the SUBSET the apply rung passes to `decide`):
+ * `{task | spec | adr | delete | ask}` \u2014 i.e. `{mint-task | mint-spec | mint-adr |
+ * delete-source | ask-follow-up}`. `adr` was DEFERRED at the keystone launch (no
+ * ADR-mint path existed yet) and is now WIRED by the follow-on task
+ * `agentic-apply-mint-adr-route`, which added the {@link
+ * import('./mint-adr.js').mintAdr} route and widened this set. Intake's set is
+ * UNCHANGED (`{task | spec | ask | bounce}`) \u2014 the engine stays outcome-AGNOSTIC
+ * (PRD decision 14), so widening this caller's subset does NOT touch intake or the
+ * engine's superset union.
+ *
+ * The INPUT adapter ({@link buildApplyDecisionInput}) sits HERE in the caller, not
+ * in the engine (the engine threads `input` opaquely) \u2014 decision 3: the input
+ * adapter is per-front-door and NOT forced to be shared with intake's issue-thread
+ * adapter.
+ */
+/**
+ * The allowed-outcome set the apply rung permits. `adr` is now INCLUDED (task
+ * `agentic-apply-mint-adr-route` widened the keystone's launch subset, which had
+ * deferred it). The engine's superset still carries `adr` either way (it is
+ * outcome-agnostic); this is purely the CALLER's permitted subset.
+ */
+export const APPLY_ALLOWED_OUTCOMES = [
+    'task',
+    'spec',
+    'adr',
+    'delete',
+    'ask',
+];
+/**
+ * Build the apply-decision INPUT for an answered source item: read its body (from
+ * the working tree) + parse its answered sidecar. The adapter boundary the engine
+ * never sees (it threads this opaquely to the decider). Returns `undefined` when
+ * there is no sidecar or no item file (the apply rung handles those upstream).
+ */
+export function buildApplyDecisionInput(opts) {
+    const sidecarAbs = join(opts.cwd, sidecarPathFor(opts.item));
+    if (!existsSync(sidecarAbs)) {
+        return undefined;
+    }
+    const itemAbs = join(opts.cwd, opts.itemPath);
+    if (!existsSync(itemAbs)) {
+        return undefined;
+    }
+    let sidecar;
+    try {
+        sidecar = parseSidecar(readFileSync(sidecarAbs, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        item: opts.item,
+        type: opts.type,
+        itemBody: readFileSync(itemAbs, 'utf8'),
+        sidecar,
+        cwd: opts.cwd,
+        model: opts.model,
+        env: opts.env,
+        sessionsDir: opts.sessionsDir,
+    };
+}
+/**
+ * Render the apply-decision agent PROMPT: instruct a fresh-context agent to read
+ * the human's recorded ANSWER(S) + the SOURCE item and emit a single
+ * `{outcome, \u2026}` verdict ({@link parseDecisionVerdict} reads it). The agent decides
+ * what to DO with the answered signal \u2014 mint a self-contained task, mint a SPEC,
+ * mint an ADR, delete the source, or ask one BATCH of follow-up questions \u2014
+ * grounded in the source's full context. It writes NOTHING (the engine acts on
+ * the verdict).
+ *
+ * Mirrors {@link import('./surface-gate.js').buildSurfacePrompt} /
+ * {@link import('./intake.js').buildIntakeDecisionSpec}: a fresh-context agent that
+ * EDITS nothing and EMITS one structured object the ENGINE routes/persists.
+ */
+export function buildApplyDecisionPrompt(input) {
+    const answers = input.sidecar.entries
+        .map((e) => `- ${e.question.trim()}\n  ANSWER: ${e.answer.trim()}`)
+        .join('\n');
+    return [
+        `You are a FRESH-CONTEXT decision agent for the answered work/ item`,
+        `"${input.item}" (type: ${input.type}). The human has answered every open`,
+        `question; decide what to DO with this signal, grounded in the source's FULL`,
+        `context (its body + type + the answers), NOT just the latest answer text.`,
+        `You write NOTHING \u2014 no file edit, no git, no commit (the advance ENGINE acts`,
+        `on what you emit). You JUDGE; the engine ACTS.`,
+        ``,
+        `The source item body:`,
+        `---`,
+        input.itemBody.trim(),
+        `---`,
+        ``,
+        `The human's answers:`,
+        answers,
+        ``,
+        `Choose ONE outcome and emit a single JSON object (no prose OUTSIDE it):`,
+        `  - "task": mint a SELF-CONTAINED task from this signal. Carry the answer(s)`,
+        `    + any remaining open-question scoping into the drafted body so the task is`,
+        `    buildable on its own. The taskBody MUST include a "## What to build" section`,
+        `    AND a "## Prompt" section (a blockquoted, self-contained instruction a fresh`,
+        `    agent can start from) — a task with no "## Prompt" is NOT dispatchable and the`,
+        `    build refuses it. Emit {"outcome":"task","taskSlug":"\u2026",`,
+        `    "taskTitle":"\u2026","taskBody":"\u2026 (markdown AFTER the frontmatter)"}.`,
+        `  - "spec": mint a SPEC from this signal (a larger, coherent piece of work).`,
+        `    Emit {"outcome":"spec","specSlug":"\u2026","specTitle":"\u2026","specBody":"\u2026"}.`,
+        `  - "adr": the answer SETTLES an architectural decision worth recording. Mint`,
+        `    a self-contained ADR (docs/adr/, the context/decision/why shape) carrying`,
+        `    the WHY from the answer(s). Emit {"outcome":"adr","adrSlug":"\u2026",`,
+        `    "adrTitle":"\u2026","adrBody":"\u2026 (markdown AFTER the frontmatter)"}.`,
+        `  - "delete": the answer means this signal should be DROPPED. Emit`,
+        `    {"outcome":"delete","deleteReason":"\u2026"} (a single revertible deletion;`,
+        `    the reason rides the commit message, git history is the archive).`,
+        `  - "ask": you need more from the human before acting. Emit`,
+        `    {"outcome":"ask","question":"\u2026"} \u2014 ask everything you still need as ONE`,
+        `    batch (never a drip); the engine appends it and re-pauses.`,
+        ``,
+        `Do NOT emit any other outcome. It is plain text inside the JSON string`,
+        `(escape newlines as \\n).`,
+    ].join('\n');
+}
+/**
+ * The PRODUCTION apply decider: launch a fresh-context agent through the EXISTING
+ * harness seam (routing an optional `model` via `LaunchInput.model` \u2014 the \u00a713
+ * model-routing intent, NOT a new mechanism), then PARSE the emitted verdict via
+ * the SHARED {@link parseDecisionVerdict}. The DIRECT mirror of
+ * `harnessSurfaceGate` / `harnessTriageGate`: a SEPARATE harness launch (fresh
+ * context) in the same checkout `cwd`, fed {@link buildApplyDecisionPrompt}; a
+ * DISTINCT session id (`<item>-apply-decide`) so its session never collides with a
+ * build / review / surface / triage session.
+ */
+export function harnessApplyDecider(options = {}) {
+    const harness = options.harness ?? new NullHarness();
+    const readOutput = options.readOutput ?? ((output) => output ?? '');
+    return async (input) => {
+        const sessionId = `${input.item.replace(/:/g, '-')}-apply-decide`;
+        const launched = await launchWithOptionalWatch({
+            harness,
+            dir: input.cwd,
+            slug: input.item,
+            command: options.agentCmd ?? '',
+            prompt: buildApplyDecisionPrompt(input),
+            model: input.model,
+            sessionId,
+            sessionsDir: input.sessionsDir,
+            env: input.env,
+        });
+        if (!launched.ok) {
+            throw new Error(`apply-decision agent launch failed${launched.detail ? `: ${launched.detail}` : ''}`);
+        }
+        return parseDecisionVerdict(readOutput(launched.output));
+    };
+}
+//# sourceMappingURL=apply-decide.js.map

package/dist/apply-decide.js.map

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

package/dist/apply-merge-action.d.ts

@@ -0,0 +1,206 @@
+import { type SidecarEntry } from './sidecar.js';
+import { type IntegrationCoreResult } from './integration-core.js';
+import type { VerifyConfig } from './verify.js';
+/**
+ * The **answered MERGE-QUESTION ACTION DISPATCH** (prd
+ * `land-time-reverify-and-parallel-merge-ceiling`, task
+ * `apply-rung-merge-disposition`; Stories #15, #16) — the deterministic,
+ * answer-driven RUNNER-ACTION layer that turns an answered
+ * `kind: merge` sidecar entry into a LAND through the EXISTING
+ * `integration-core.ts` land primitive (rebase → re-verify on the rebased tip →
+ * advance).
+ *
+ * This is a SIBLING of the agentic `decide()` content-decision in
+ * `apply-decide.ts`, NOT a route through it: a merge-acceptance has no
+ * judgement content (the human's plain `merge | hold | drop` answer IS the
+ * decision; the apply-time fresh-worktree re-verify on the rebased tip is the
+ * real correctness gate). Per the PRD's resolved mechanism, routing this
+ * through an LLM only adds cost and non-determinism, so the apply rung
+ * KIND-CHECKS the sidecar BEFORE calling the agentic decider: a sidecar entry
+ * carrying `kind: merge` (the typed dispatch field from `sidecar-kind-field`,
+ * stamped by `merge-question-surfacer`) dispatches HERE deterministically;
+ * content kinds (observation / triage / spec) keep going through `decide()` as
+ * today.
+ *
+ * The KEYING is the question identity + the human's plain answer:
+ *
+ *   - `answer ≈ merge` → invoke the LAND primitive (see {@link performMergeLand})
+ *     with `committedRecovery: true` + `freshWorktreeGate: true`. The unmerged
+ *     `work/<slug>` is checked out via the EXISTING `workspace.ts` per-job
+ *     worktree seam ({@link createJob} off the hub mirror), NOT a bespoke
+ *     worktree/clone; `performIntegration` then re-verifies the REBASED tip and
+ *     REFUSES on red (routes to needs-attention through its own shared seam),
+ *     so `main` never receives a tree that fails `verify`.
+ *   - `answer ≈ hold` → SKIP the land; the apply rung still records the answer
+ *     in the item body via the normal apply path (the work branch stays
+ *     unmerged; the next surface pass may re-emit a question).
+ *   - `answer ≈ drop` → SKIP the land; the apply rung still records the answer
+ *     in the item body via the normal apply path. (Cancellation of the work
+ *     branch itself is out of this task's scope — the question is recorded as
+ *     "drop" and the human / a later surfacer handles the artifact.)
+ *
+ * The STALE-APPROVAL POLICY (PRD OQ6, applied answer q1): default is the cheap
+ * "HONOUR the prior approval + land on a green re-verify" path; opt-in
+ * `strictMergeApproval` (resolved per-repo via the gate-family precedence chain
+ * by the sibling task `strict-merge-approval-gate`, default OFF) RE-SURFACES
+ * the merge-question instead of landing when the merge-base moved between the
+ * surfacer's question and this apply. The RED-re-verify refusal is unchanged
+ * in both modes.
+ *
+ * House-style boundary: this module is the DETERMINISTIC DISPATCH LAYER. It
+ * does NOT re-implement rebase / verify / integrate (it drives the EXISTING
+ * `performIntegration` with `committedRecovery: true` + `freshWorktreeGate:
+ * true`, which {@link createJob} cuts the worktree for), and it does NOT
+ * improvise a worktree or clone (it uses the same `createJob` seam the build /
+ * recovery callers use). Tests inject the {@link MergeActionHandler} seam so
+ * they assert on EXTERNAL behaviour (what lands on `main`, what routes to
+ * needs-attention, that `verify` ran on the rebased tip).
+ */
+/** The three deterministic actions a merge-question answer encodes. */
+export type MergeActionVerb = 'merge' | 'hold' | 'drop';
+/** A detected, answer-driven merge-action keyed off ONE answered `kind: merge` entry. */
+export interface DetectedMergeAction {
+    /** The deterministic verb parsed from the entry's answer text. */
+    verb: MergeActionVerb;
+    /** The answered `kind: merge` entry the verb came from. */
+    entry: SidecarEntry;
+}
+/**
+ * Parse the human's plain free-text answer into the deterministic
+ * {@link MergeActionVerb}. The merge-question surfacer renders
+ * `merge | hold | drop` in the entry's `default` as a human-readable hint, so
+ * the human typically types one of those words verbatim. We accept any text
+ * whose first whole word (case-insensitive) is one of `merge` / `hold` / `drop`
+ * — this is the same machine-parseable choice shape the surfacer's applied
+ * answer q1 documents ("a DETERMINISTIC CHOICE shape … the human picks and the
+ * system parses unambiguously").
+ *
+ * Returns `undefined` on ANYTHING else (an empty answer, a typo, a long
+ * narrative without one of the three words at the start) so the caller can
+ * route the ambiguity HONESTLY — never default-to-merge on a malformed answer,
+ * which would invent a land the human did not authorise.
+ */
+export declare function parseMergeAnswer(text: string): MergeActionVerb | undefined;
+/**
+ * Detect the FIRST answered `kind: merge` entry's deterministic action verb in
+ * a fully-answered sidecar (the apply rung's pre-decider kind-check). Returns
+ * `undefined` when the sidecar carries no answered `kind: merge` entry (the
+ * apply rung then proceeds to the existing path — agentic for observations,
+ * normal apply for task/prd content questions).
+ *
+ * The sidecar is read OFF DISK keyed off the namespaced item identity; the
+ * model is parsed via the SAME `parseSidecar` the rest of the engine uses.
+ * Returns `undefined` on a missing/unparseable sidecar (the caller's normal
+ * apply path will then raise the right error).
+ */
+export declare function detectAnsweredMergeAction(cwd: string, item: string): DetectedMergeAction | undefined;
+/** Input the production merge-action handler consumes. */
+export interface MergeActionInput {
+    /** The detected action (verb + source entry). */
+    action: DetectedMergeAction;
+    /** The namespaced item identity (`task:<slug>`). */
+    item: string;
+    /** The bare slug (the work branch is `work/task-<slug>` / `work/<slug>`). */
+    slug: string;
+    /** The apply rung's working clone (used to resolve the arbiter URL when needed). */
+    cwd: string;
+    /** The arbiter remote NAME in `cwd` (defaults to `origin`). */
+    arbiter: string;
+    /**
+     * The arbiter URL the land worktree mirrors from. When set, used DIRECTLY
+     * (the registry-set advance driver threads the per-mirror origin URL here).
+     * When unset, the URL is resolved from `cwd` + `arbiter` via `git remote
+     * get-url` (the in-place / one-shot caller).
+     */
+    arbiterUrl?: string;
+    /** The execution working area (`~/.dorfl` by default) `createJob` cuts under. */
+    workspacesDir: string;
+    /** Per-repo env-prep config the fresh-worktree gate runs before `verify`. */
+    prepare?: VerifyConfig;
+    /** Per-repo acceptance gate (`verify`). */
+    verify?: VerifyConfig;
+    /**
+     * `strictMergeApproval` (resolved per-repo by the sibling task
+     * `strict-merge-approval-gate`; default OFF). OFF ⇒ honour the prior answer
+     * + land on a green re-verify (the cheap default). ON ⇒ re-surface the
+     * merge-question when the merge-base moved between the surfacer's question
+     * and this apply (don't land; the apply rung folds this into a re-pause).
+     */
+    strictMergeApproval?: boolean;
+    /** Bounded recovery-rebase retry knob (mirrors the build path). */
+    recoveryRebaseRetries?: number;
+    /** Modest livelock-spreading jitter (ms) between recovery-rebase retries. */
+    recoveryRebaseJitterMs?: number;
+    /** Cross-job land-CAS retry cap (the `mergeRetries` precedence chain). */
+    mergeRetries?: number;
+    /** Environment for child git processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+/** The terminal verbs the dispatcher reports to the apply rung. */
+export type MergeActionOutcome = 
+/** `answer=merge` + green re-verify ⇒ the kept commit landed on `<arbiter>/main`. */
+'landed'
+/** `answer=merge` + the kept tip was already on `<arbiter>/main` (idempotent re-run). */
+ | 'already-integrated'
+/**
+ * `answer=merge` + RED re-verify on the rebased tip (or a rebase-conflict): the
+ * land was REFUSED; `performIntegration` routed the item to needs-attention
+ * through its shared seam — `main` never received the failing tree. The apply
+ * rung short-circuits (does NOT resolve the sidecar, so the open question
+ * stays surfaced for a human follow-up).
+ */
+ | 'refused'
+/**
+ * `answer=merge` + `strictMergeApproval` ON + the merge-base moved between
+ * the surfacer's question and this apply: the dispatcher RE-SURFACES the
+ * merge-question (the apply rung appends a fresh follow-up + re-pauses).
+ */
+ | 'restale'
+/** `answer=hold` ⇒ no land; the apply rung records the answer in body as usual. */
+ | 'hold'
+/** `answer=drop` ⇒ no land; the apply rung records the answer in body as usual. */
+ | 'drop';
+/** What the production handler returns to the apply rung. */
+export interface MergeActionResult {
+    outcome: MergeActionOutcome;
+    /** Human-readable summary for the rung's message. */
+    message: string;
+    /**
+     * The integration-core result, when the dispatcher reached
+     * `performIntegration` (i.e. `answer=merge` + not re-staled). Carries the
+     * routing observed by the land primitive (`gate-failed`, `completed`,
+     * `already-integrated`, …), so callers can branch on it.
+     */
+    integration?: IntegrationCoreResult;
+}
+/**
+ * The injectable dispatch SEAM. Production wires {@link performMergeAction}
+ * (which checks out via `createJob` + lands via `performIntegration`); tests
+ * inject a stub to assert the apply-rung short-circuits on `refused` and falls
+ * through on `landed` / `hold` / `drop` / `restale` WITHOUT spinning up a real
+ * hub mirror.
+ */
+export type MergeActionHandler = (input: MergeActionInput) => Promise<MergeActionResult>;
+/**
+ * The PRODUCTION dispatcher: an answered `kind: merge` entry's verb drives one
+ * of the four terminals (`landed` / `refused` / `restale` / `hold|drop`). For
+ * `answer=merge` it checks out the unmerged `work/<slug>` via the EXISTING
+ * `workspace.ts` per-job worktree seam ({@link createJob}, the same seam the
+ * build / recovery callers use) and invokes the LAND primitive
+ * ({@link performIntegration}) with `committedRecovery: true` +
+ * `freshWorktreeGate: true` — so the rebased tip is re-verified BEFORE it
+ * lands, the answered-merge land path NEVER integrates a clean-rebase-but-
+ * broken tree, and a refusal routes to needs-attention through the SAME
+ * shared seam (`applyNeedsAttentionTransition`) the build path uses. The job
+ * worktree is always disposed (success or failure) so the hub mirror does not
+ * accumulate stale per-job state.
+ *
+ * For `answer=hold` and `answer=drop` the dispatcher does not land — it just
+ * tells the apply rung to fall through to the normal answer-recording path.
+ * (Cancellation of the work branch on `drop` is OUT OF SCOPE; the answer is
+ * recorded and a future surfacer / human handles the artifact.)
+ */
+export declare function performMergeAction(input: MergeActionInput): Promise<MergeActionResult>;
+//# sourceMappingURL=apply-merge-action.d.ts.map

package/dist/apply-merge-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-merge-action.d.ts","sourceRoot":"","sources":["../src/apply-merge-action.ts"],"names":[],"mappings":"AAEA,OAAO,EAKN,KAAK,YAAY,EAEjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAEN,KAAK,qBAAqB,EAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IACnC,kEAAkE;IAClE,IAAI,EAAE,eAAe,CAAC;IACtB,2DAA2D;IAC3D,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAe1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACV,mBAAmB,GAAG,SAAS,CAmBjC;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAChC,iDAAiD;IACjD,MAAM,EAAE,mBAAmB,CAAC;IAC5B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mEAAmE;IACnE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,mEAAmE;AACnE,MAAM,MAAM,kBAAkB;AAC7B,qFAAqF;AACnF,QAAQ;AACV,yFAAyF;GACvF,oBAAoB;AACtB;;;;;;GAMG;GACD,SAAS;AACX;;;;GAIG;GACD,SAAS;AACX,mFAAmF;GACjF,MAAM;AACR,mFAAmF;GACjF,MAAM,CAAC;AAEV,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAChC,KAAK,EAAE,gBAAgB,KACnB,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAmEhC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,gBAAgB,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAuK5B"}