dorfl 0.0.0 → 0.1.0

package/dist/lifecycle-gather.js

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ledgerRead } from './ledger-read.js';
+import { parseSidecar, sidecarPathCandidates, } from './sidecar.js';
+import { runAsync } from './git.js';
+import { buildLifecyclePools, } from './lifecycle-pools.js';
+/**
+ * Read the ACTIVE sidecar for `<namespace>:<slug>` from a WORKING checkout (sync),
+ * or `undefined` when none exists. Identity-keyed at `work/questions/<type>-<slug>.md`
+ * \u2014 the SAME path `readItemSignals` reads in-place.
+ */
+function readSidecarInPlace(repoPath, namespace, slug) {
+    // Probe every candidate path (spec-<slug>.md, then the legacy prd-<slug>.md the
+    // migration command has not converted yet) and read the FIRST that exists.
+    for (const rel of sidecarPathCandidates(`${namespace}:${slug}`)) {
+        const abs = join(repoPath, rel);
+        if (existsSync(abs)) {
+            return parseSidecar(readFileSync(abs, 'utf8'));
+        }
+    }
+    return undefined;
+}
+/**
+ * Collect every `needsAnswers:true` task (from `work/backlog`) + prd (from
+ * `work/prds`) for the in-place repo, through the read seam (the SAME readers the
+ * build-pool scan uses). These are the SURFACE/APPLY candidates this task draws
+ * into the selection (today they are build/task-INELIGIBLE, so nothing else
+ * surfaces them).
+ */
+function blockedItemsInPlace(read, repoPath, surfaceStaging) {
+    const out = [];
+    const state = read.resolveLocalState({ repoPath });
+    for (const item of state.ready) {
+        if (item.needsAnswers === true) {
+            out.push({ namespace: 'task', slug: item.slug });
+        }
+    }
+    const pool = read.resolveSpecPool({ repoPath });
+    for (const spec of pool.specs) {
+        if (spec.needsAnswers === true) {
+            out.push({ namespace: 'spec', slug: spec.slug });
+        }
+    }
+    // TASKED resting prds (`prds/tasked/`) — enumerated UNCONDITIONALLY (NOT behind
+    // `surfaceStaging`), because a prd may legitimately carry `needsAnswers:true`
+    // while resting in `prds/tasked/` (WORK-CONTRACT "A PRD that has drifted AFTER
+    // it was TASKED"). This is NOT a staging widening: a tasked prd is a durable
+    // resting state, like the pool, so it is enumerated like the pool. Routing
+    // still respects the gates in `buildLifecyclePools` (an ANSWERED sidecar -> the
+    // always-on APPLY pool so the human's answer is never STRANDED; a NO-sidecar
+    // tasked prd -> SURFACE, still gated by `surfaceBlockers`). Without this, a
+    // tasked prd's answered sidecar is enumerated by no pool and apply never runs
+    // on it (observation `tasked-prd-needsanswers-sidecar-stranded-no-apply-pool`).
+    for (const spec of read.resolveLocalSpecTasked({ repoPath })) {
+        if (spec.needsAnswers === true) {
+            out.push({ namespace: 'spec', slug: spec.slug });
+        }
+    }
+    // SURFACE-on-STAGING widening (prd
+    // `staging-surface-and-apply-promote-safety` F2): when `surfaceStaging` is
+    // ON, the candidate set ADDITIONALLY enumerates `needsAnswers` items resting
+    // in STAGING (`tasks/backlog/` + `prds/proposed/`), so a tasked item
+    // surfaces its questions BEFORE the human promotes it. BUILD/claim still
+    // reads POOL-only (`scoreItems` over `state.ready`); only the surface polarity
+    // widens here.
+    if (surfaceStaging) {
+        for (const item of read.resolveLocalTaskStaging({ repoPath })) {
+            if (item.needsAnswers === true) {
+                out.push({ namespace: 'task', slug: item.slug });
+            }
+        }
+        for (const spec of read.resolveLocalSpecStaging({ repoPath })) {
+            if (spec.needsAnswers === true) {
+                out.push({ namespace: 'spec', slug: spec.slug });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Gather + build the lifecycle pools for an IN-PLACE working checkout (sync).
+ * Reads `work/notes/observations/` + the per-item sidecar state through the read seam +
+ * the filesystem, then hands them to the shared {@link buildLifecyclePools}. The
+ * gates default BOTH OFF (the interim hardcoded-off, calm by default).
+ */
+export function gatherLifecycleInPlace(input) {
+    const read = input.read ?? ledgerRead;
+    const repoPath = input.repoPath;
+    const rawObservations = read.resolveLocalState({ repoPath }).observations;
+    const observations = rawObservations.map((obs) => ({
+        slug: obs.slug,
+        triaged: obs.triaged,
+        sidecar: readSidecarInPlace(repoPath, 'observation', obs.slug),
+    }));
+    const surfaceStaging = input.gates?.surfaceStaging === true;
+    const needsAnswers = blockedItemsInPlace(read, repoPath, surfaceStaging).map((item) => ({
+        repoPath,
+        namespace: item.namespace,
+        slug: item.slug,
+        sidecar: readSidecarInPlace(repoPath, item.namespace, item.slug),
+    }));
+    return buildLifecyclePools({
+        repoPath,
+        observations,
+        needsAnswers,
+        gates: input.gates,
+    });
+}
+/**
+ * Read the ACTIVE sidecar for `<namespace>:<slug>` from a BARE hub mirror's
+ * committed `<ref>:work/questions/<type>-<slug>.md` via `git show` (the SAME
+ * mechanism the mirror-ref ledger reads use), or `undefined` when none exists.
+ */
+async function readSidecarMirror(mirrorPath, ref, namespace, slug, env) {
+    // Probe every candidate committed path (spec-<slug>.md, then the legacy
+    // prd-<slug>.md the migration command has not converted yet) via `git show`,
+    // returning the FIRST that resolves.
+    for (const rel of sidecarPathCandidates(`${namespace}:${slug}`)) {
+        const object = `${ref}:${rel}`;
+        const show = await runAsync('git', ['show', object], mirrorPath, { env });
+        if (show.status === 0) {
+            return parseSidecar(show.stdout);
+        }
+    }
+    return undefined;
+}
+/**
+ * Gather + build the lifecycle pools for a MIRROR-SIDE bare hub mirror (async).
+ * Reads the SAME logical inputs as {@link gatherLifecycleInPlace} \u2014 observations +
+ * the `needsAnswers` pool from the mirror's committed `main` (via
+ * `resolveMirrorState`), the prd pool via `resolveMirrorSpecPool`, and each item's
+ * sidecar via `git show` \u2014 then hands them to the SAME shared
+ * {@link buildLifecyclePools}, so the in-place + mirror enumerations AGREE.
+ */
+export async function gatherLifecycleMirror(input) {
+    const read = input.read ?? ledgerRead;
+    const mirrorPath = input.mirrorPath;
+    const ref = input.ref ?? 'main';
+    const env = input.env;
+    const state = await read.resolveMirrorState({ mirrorPath, ref, env });
+    const specPool = await read.resolveMirrorSpecPool({ mirrorPath, ref, env });
+    const surfaceStaging = input.gates?.surfaceStaging === true;
+    const [taskStaging, specStaging] = surfaceStaging
+        ? await Promise.all([
+            read.resolveMirrorTaskStaging({ mirrorPath, ref, env }),
+            read.resolveMirrorSpecStaging({ mirrorPath, ref, env }),
+        ])
+        : [[], []];
+    const blocked = [];
+    for (const item of state.ready) {
+        if (item.needsAnswers === true) {
+            blocked.push({ namespace: 'task', slug: item.slug });
+        }
+    }
+    for (const spec of specPool.specs) {
+        if (spec.needsAnswers === true) {
+            blocked.push({ namespace: 'spec', slug: spec.slug });
+        }
+    }
+    // TASKED resting prds (`<ref>:work/prds/tasked/`) — enumerated UNCONDITIONALLY,
+    // the mirror-side counterpart of the in-place tasked-prd enumeration above
+    // (so a `needsAnswers` tasked prd's answered sidecar is never stranded on the
+    // mirror/CI advance path either). Routing still respects the gates.
+    const specTasked = await read.resolveMirrorSpecTasked({ mirrorPath, ref, env });
+    for (const spec of specTasked) {
+        if (spec.needsAnswers === true) {
+            blocked.push({ namespace: 'spec', slug: spec.slug });
+        }
+    }
+    // SURFACE-on-STAGING widening (prd
+    // `staging-surface-and-apply-promote-safety` F2): mirror-side counterpart of
+    // the in-place widening above — enumerate `needsAnswers` items in
+    // STAGING (`tasks/backlog/` + `prds/proposed/`) from the bare mirror's
+    // committed `<ref>` tree, so the in-place + mirror surfaces AGREE. The
+    // staging reads are skipped entirely when the gate is OFF (no extra git
+    // ls-tree work in the legacy mode).
+    for (const item of taskStaging) {
+        if (item.needsAnswers === true) {
+            blocked.push({ namespace: 'task', slug: item.slug });
+        }
+    }
+    for (const spec of specStaging) {
+        if (spec.needsAnswers === true) {
+            blocked.push({ namespace: 'spec', slug: spec.slug });
+        }
+    }
+    const needsAnswers = await Promise.all(blocked.map(async (item) => ({
+        repoPath: mirrorPath,
+        namespace: item.namespace,
+        slug: item.slug,
+        sidecar: await readSidecarMirror(mirrorPath, ref, item.namespace, item.slug, env),
+    })));
+    const observations = await Promise.all(state.observations.map(async (obs) => ({
+        slug: obs.slug,
+        triaged: obs.triaged,
+        sidecar: await readSidecarMirror(mirrorPath, ref, 'observation', obs.slug, env),
+    })));
+    return buildLifecyclePools({
+        repoPath: mirrorPath,
+        observations,
+        needsAnswers,
+        gates: input.gates,
+    });
+}
+//# sourceMappingURL=lifecycle-gather.js.map

package/dist/lifecycle-gather.js.map

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

package/dist/lifecycle-pools.d.ts

@@ -0,0 +1,180 @@
+import type { SidecarModel } from './sidecar.js';
+import type { LifecycleSelectedItem } from './select-priority.js';
+/**
+ * The SHARED, PURE enumeration of the advance auto-pick's LIFECYCLE POOLS (task
+ * `advance-autopick-lifecycle-pools`) \u2014 the MISSING FOUNDATION a 2026-06-12 review
+ * found. Before this, `performAdvanceAuto` (in-place) and `scanMirrorPool`
+ * (mirror-side) enumerated ONLY the two BUILD pools (eligible tasks + taskable
+ * prds), so a bare / `-n` / loop / CI `advance` could ONLY build tasks + task
+ * prds. The lifecycle rungs (triage / surface / apply) were EXPLICIT-INVOCATION-
+ * ONLY because NOTHING enumerated observations or `needsAnswers`-blocked items
+ * into the selection. This unit closes that gap, at the SELECTION layer ONLY (it
+ * does NOT touch the classifier `advance-classify.ts` or the rung bodies \u2014 the
+ * tick still re-classifies each selected item and runs the right rung).
+ *
+ * It is ONE shared unit reused by BOTH the in-place caller (`performAdvanceAuto`)
+ * and the mirror-side caller (`scanMirrorPool` \u2192 the loop/CI drivers), NOT two
+ * divergent enumerations. The per-substrate I/O (reading `work/notes/observations/` +
+ * the per-item sidecar state) is done CALLER-SIDE through the read seam (sync
+ * in-place, async mirror-ref) and the already-resolved inputs are handed here \u2014
+ * exactly as `taskableSpecs` is fed by each caller. This unit is then pure: no I/O.
+ *
+ * **Three lifecycle sub-pools, gated by PURPOSE (ADR `ci-config-policy-and-gate-
+ * family.md` \u00a74 \u2014 gates govern CREATE only; CONSUME is always-on):**
+ *
+ *   - **triage** \u2014 UNTRIAGED observations (no `triaged:` settled marker). A CREATE
+ *     act (the bot mints a promote/keep/delete question), so gated by
+ *     {@link LifecyclePoolGates.triage} (the future `observationTriage` gate).
+ *   - **surface** \u2014 `needsAnswers`-blocked tasks/prds with NO all-answered sidecar
+ *     (no sidecar yet, or a still-pending one). A CREATE act (the bot mints the
+ *     blocker question), so gated by {@link LifecyclePoolGates.surface} (the future
+ *     `surfaceBlockers` gate). A PENDING sidecar is NOT enumerated (it would only
+ *     no-op \u2014 leaving it out keeps the pool calm + thrash-free).
+ *   - **apply** \u2014 `needsAnswers`-blocked items WITH an all-answered sidecar. A
+ *     CONSUME act (the bot applies the human's committed answer), ALWAYS allowed,
+ *     never gated \u2014 gating it would STRAND a human's answer (\u00a74's create-vs-consume
+ *     invariant). So an answered sidecar is selected even with BOTH create-gates
+ *     off.
+ *
+ * **INTERIM SAFETY (task `## Decisions`, DECIDED): the create-gates are born
+ * OFF.** The gate tasks (`observation-triage-tri-state-gate` /
+ * `surface-blockers-gate`) land AFTER this one, so this task must be SAFE
+ * STANDALONE: {@link LifecyclePoolGates} default `triage:false` + `surface:false`,
+ * so the triage + surface sub-pools contribute NOTHING by default and landing this
+ * task alone auto-triages / auto-surfaces NOTHING (it changes no repo's
+ * behaviour). The gate tasks REPLACE the hardcoded-off the callers pass with the
+ * real `observationTriage` / `surfaceBlockers` config read. The apply sub-pool is
+ * NOT gated (consume is always-on), so an answered sidecar always applies.
+ */
+/**
+ * The create-side gates for the lifecycle pools (ADR \u00a72/\u00a74). Both default OFF
+ * (the calm interim state) \u2014 the gate tasks flip them on by reading
+ * `observationTriage` / `surfaceBlockers` from config. `apply` is NOT here: it is
+ * the CONSUME phase, ALWAYS allowed (never gated).
+ */
+export interface LifecyclePoolGates {
+    /**
+     * May the TRIAGE sub-pool (untriaged observations) contribute to the selection?
+     * Default `false` (the interim hardcoded-off; the `observationTriage` gate
+     * replaces this). OFF \u21d2 observations are never auto-selected.
+     */
+    triage?: boolean;
+    /**
+     * May the SURFACE sub-pool (`needsAnswers`-blocked, no all-answered sidecar)
+     * contribute? Default `false` (the interim hardcoded-off; the `surfaceBlockers`
+     * gate replaces this). OFF \u21d2 blocked items are never auto-surfaced.
+     */
+    surface?: boolean;
+    /**
+     * Does the SURFACE candidate set widen to include STAGING (`tasks/backlog/` +
+     * `prds/proposed/`), or stay POOL-ONLY? This field is CONSUMED BY THE
+     * GATHER (`lifecycle-gather.ts`), NOT by {@link buildLifecyclePools} — the
+     * builder is pure and only routes already-resolved candidates between surface
+     * / apply by sidecar-answered-state. The gather decides WHICH items become
+     * candidates in the first place; this gate widens that input set when `true`.
+     * Default `false` at THIS library boundary (calm; the CLI threads
+     * `config.surfaceStaging` which itself defaults to `true`, so the user-visible
+     * default is `true`). Spec `staging-surface-and-apply-promote-safety` F2.
+     * BUILD/claim eligibility is UNCHANGED in either mode — staging items stay
+     * non-claimable, the trust model is untouched.
+     */
+    surfaceStaging?: boolean;
+}
+/**
+ * One `needsAnswers`-blocked task/spec candidate for the SURFACE/APPLY sub-pools,
+ * before this unit routes it. The caller resolves the item's namespace + slug
+ * (from `work/backlog` tasks + `work/specs` specs carrying `needsAnswers:true`) and
+ * its ACTIVE sidecar (parsed from `work/questions/<type>-<slug>.md`, or
+ * `undefined` when none exists) \u2014 through the read seam (sync in-place / async
+ * mirror-ref). This unit then routes it to APPLY (sidecar all-answered, consume,
+ * always-on) or SURFACE (no all-answered sidecar, create, gated). PURE: no I/O.
+ */
+export interface NeedsAnswersCandidate {
+    /** The repo this item lives in (a working checkout in-place, the mirror path remote). */
+    repoPath: string;
+    /** `'task'` (a `work/backlog/` task) or `'spec'` (a `work/specs/` spec). */
+    namespace: 'task' | 'spec';
+    /** The bare slug. */
+    slug: string;
+    /** The parsed ACTIVE sidecar, or `undefined` when none exists yet. */
+    sidecar: SidecarModel | undefined;
+}
+/**
+ * One OBSERVATION candidate for the TRIAGE/APPLY sub-pools, resolved through
+ * the same read seam as its `needsAnswers` task/spec siblings (task
+ * `route-answered-observation-sidecar-to-apply-pool`). The classifier receives
+ * a sidecar-aware observation shape so an ANSWERED observation sidecar routes
+ * to the always-on APPLY pool (a CONSUME act — the human's answer is never
+ * stranded), while a NO/PENDING sidecar UNTRIAGED observation stays a TRIAGE
+ * candidate (gated) as today. PURE: the caller resolves the active sidecar (via
+ * {@link sidecarPathFor} — the SAME resolver the task/prd `needsAnswers`
+ * candidates use); this unit only routes.
+ */
+export interface ObservationCandidate {
+    /** The observation's identity — its FILENAME slug (never a foreign frontmatter `slug:`). */
+    slug: string;
+    /**
+     * The SETTLED marker (`triaged:` frontmatter): a non-empty value drops the
+     * observation out of the TRIAGE pool; `undefined` ⇒ UNTRIAGED. IGNORED for
+     * the APPLY routing (an ANSWERED sidecar wins regardless of the marker: a
+     * human's answer must never be stranded — task `## Decisions`).
+     */
+    triaged: string | undefined;
+    /** The parsed ACTIVE sidecar (`work/questions/observation-<slug>.md`), or `undefined`. */
+    sidecar: SidecarModel | undefined;
+}
+/** Inputs to {@link buildLifecyclePools}: the raw lifecycle candidates + the gates. */
+export interface LifecyclePoolsInput {
+    /** The repo whose lifecycle items these are (carried onto each selected item). */
+    repoPath: string;
+    /**
+     * Every observation in `work/notes/observations/` (the read seam's observation
+     * read), each with its resolved active sidecar (task
+     * `route-answered-observation-sidecar-to-apply-pool`). This unit routes each
+     * to APPLY (sidecar all-answered, consume, always-on) or TRIAGE (untriaged, no
+     * all-answered sidecar; create, gated).
+     */
+    observations: ObservationCandidate[];
+    /**
+     * Every `needsAnswers:true` task/prd (the create-side blocked items), each
+     * with its resolved active sidecar. This unit routes each to SURFACE or APPLY.
+     */
+    needsAnswers: NeedsAnswersCandidate[];
+    /**
+     * The create-side gates (default BOTH OFF \u2014 the interim hardcoded-off). The
+     * apply sub-pool is never gated.
+     */
+    gates?: LifecyclePoolGates;
+}
+/**
+ * The three lifecycle sub-pools, each an ordered {@link LifecycleSelectedItem[]}.
+ * The caller concatenates them into the overall selection in the four-pool order
+ * (see {@link selectPrioritised}); `apply` is consume (always present), `triage` /
+ * `surface` are present only when their gate is on.
+ */
+export interface LifecyclePools {
+    /** `apply` items (answered sidecars; CONSUME, always present). */
+    apply: LifecycleSelectedItem[];
+    /** `surface` items (blocked, no all-answered sidecar; gated by `gates.surface`). */
+    surface: LifecycleSelectedItem[];
+    /** `triage` items (untriaged observations; gated by `gates.triage`). */
+    triage: LifecycleSelectedItem[];
+}
+/**
+ * Build the three lifecycle sub-pools from the raw candidates + the gates, PURE.
+ * Each selected item carries the lifecycle `namespace` discriminator so the
+ * driver's per-item dispatch can map it to the right TICK arg (observation \u2192
+ * `obs:<slug>`; a blocked task/prd \u2192 `task:`/`prd:<slug>`, which the tick then
+ * classifies into surface/apply/no-op). This unit decides WHICH sub-pool each item
+ * belongs to (and whether its gate lets it through); the TICK re-classifies and
+ * runs the actual rung (the classifier + rung bodies are unchanged).
+ *
+ * Routing:
+ *   - an UNTRIAGED observation \u2192 `triage` (gated by `gates.triage`);
+ *   - a `needsAnswers` item with an ALL-ANSWERED sidecar \u2192 `apply` (always);
+ *   - a `needsAnswers` item with NO all-answered sidecar \u2192 `surface` (gated by
+ *     `gates.surface`); a PENDING sidecar is NOT enumerated into either pool (it
+ *     would only no-op \u2014 leaving it out keeps the pool calm).
+ */
+export declare function buildLifecyclePools(input: LifecyclePoolsInput): LifecyclePools;
+//# sourceMappingURL=lifecycle-pools.d.ts.map

package/dist/lifecycle-pools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-pools.d.ts","sourceRoot":"","sources":["../src/lifecycle-pools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACrC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACpC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,0FAA0F;IAC1F,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IACnC,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,EAAE,oBAAoB,EAAE,CAAC;IACrC;;;OAGG;IACH,YAAY,EAAE,qBAAqB,EAAE,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,kEAAkE;IAClE,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC/B,oFAAoF;IACpF,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,wEAAwE;IACxE,MAAM,EAAE,qBAAqB,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,mBAAmB,GACxB,cAAc,CA6DhB"}

package/dist/lifecycle-pools.js

@@ -0,0 +1,78 @@
+import { allAnswered } from './sidecar.js';
+/**
+ * Build the three lifecycle sub-pools from the raw candidates + the gates, PURE.
+ * Each selected item carries the lifecycle `namespace` discriminator so the
+ * driver's per-item dispatch can map it to the right TICK arg (observation \u2192
+ * `obs:<slug>`; a blocked task/prd \u2192 `task:`/`prd:<slug>`, which the tick then
+ * classifies into surface/apply/no-op). This unit decides WHICH sub-pool each item
+ * belongs to (and whether its gate lets it through); the TICK re-classifies and
+ * runs the actual rung (the classifier + rung bodies are unchanged).
+ *
+ * Routing:
+ *   - an UNTRIAGED observation \u2192 `triage` (gated by `gates.triage`);
+ *   - a `needsAnswers` item with an ALL-ANSWERED sidecar \u2192 `apply` (always);
+ *   - a `needsAnswers` item with NO all-answered sidecar \u2192 `surface` (gated by
+ *     `gates.surface`); a PENDING sidecar is NOT enumerated into either pool (it
+ *     would only no-op \u2014 leaving it out keeps the pool calm).
+ */
+export function buildLifecyclePools(input) {
+    const gates = input.gates ?? {};
+    const triageOn = gates.triage === true;
+    const surfaceOn = gates.surface === true;
+    // --- observation routing: apply (all-answered sidecar) vs triage (untriaged) ---
+    const triage = [];
+    const apply = [];
+    for (const obs of input.observations) {
+        const answered = obs.sidecar !== undefined && allAnswered(obs.sidecar);
+        if (answered) {
+            // CONSUME (apply the human's committed answer) — ALWAYS allowed, even
+            // with the triage create-gate off (the create-vs-consume invariant, ADR
+            // `ci-config-policy-and-gate-family` §4). An answered sidecar wins even
+            // when the observation body also carries a `triaged:` marker: a human's
+            // answer must never be stranded (task `## Decisions`).
+            apply.push({
+                repoPath: input.repoPath,
+                slug: obs.slug,
+                namespace: 'observation',
+            });
+        }
+        else if (obs.triaged === undefined && triageOn) {
+            // CREATE (mint the promote/keep/delete question) — gated by
+            // `observationTriage`. An untriaged observation with NO sidecar or a
+            // PENDING sidecar is a triage candidate as today.
+            triage.push({
+                repoPath: input.repoPath,
+                slug: obs.slug,
+                namespace: 'observation',
+            });
+        }
+        // else: SETTLED (triaged:) with no answered sidecar — NOT enumerated.
+    }
+    // --- surface / apply: split `needsAnswers` items by sidecar answered-state ---
+    const surface = [];
+    for (const candidate of input.needsAnswers) {
+        const answered = candidate.sidecar !== undefined && allAnswered(candidate.sidecar);
+        if (answered) {
+            // CONSUME (apply the human's committed answer) \u2014 ALWAYS allowed, even with
+            // both create-gates off (the create-vs-consume invariant, ADR \u00a74).
+            apply.push({
+                repoPath: candidate.repoPath,
+                slug: candidate.slug,
+                namespace: candidate.namespace,
+            });
+        }
+        else if (candidate.sidecar === undefined && surfaceOn) {
+            // CREATE (mint the blocker question) \u2014 gated by `surfaceBlockers`. Only an
+            // item with NO sidecar yet is a surface candidate; a PENDING sidecar would
+            // only no-op, so it is left OUT of the pool (keeps the selection calm).
+            surface.push({
+                repoPath: candidate.repoPath,
+                slug: candidate.slug,
+                namespace: candidate.namespace,
+            });
+        }
+        // else: a PENDING sidecar (exists, not all-answered) \u2014 NOT enumerated.
+    }
+    return { apply, surface, triage };
+}
+//# sourceMappingURL=lifecycle-pools.js.map

package/dist/lifecycle-pools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-pools.js","sourceRoot":"","sources":["../src/lifecycle-pools.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAyKzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAClC,KAA0B;IAE1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;IAEzC,kFAAkF;IAClF,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvE,IAAI,QAAQ,EAAE,CAAC;YACd,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,wEAAwE;YACxE,uDAAuD;YACvD,KAAK,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,SAAS,EAAE,aAAa;aACxB,CAAC,CAAC;QACJ,CAAC;aAAM,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,EAAE,CAAC;YAClD,4DAA4D;YAC5D,qEAAqE;YACrE,kDAAkD;YAClD,MAAM,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,SAAS,EAAE,aAAa;aACxB,CAAC,CAAC;QACJ,CAAC;QACD,sEAAsE;IACvE,CAAC;IAED,gFAAgF;IAChF,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QAC5C,MAAM,QAAQ,GACb,SAAS,CAAC,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,QAAQ,EAAE,CAAC;YACd,gFAAgF;YAChF,wEAAwE;YACxE,KAAK,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,IAAI,EAAE,SAAS,CAAC,IAAI;gBACpB,SAAS,EAAE,SAAS,CAAC,SAAS;aAC9B,CAAC,CAAC;QACJ,CAAC;aAAM,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS,IAAI,SAAS,EAAE,CAAC;YACzD,gFAAgF;YAChF,2EAA2E;YAC3E,wEAAwE;YACxE,OAAO,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,IAAI,EAAE,SAAS,CAAC,IAAI;gBACpB,SAAS,EAAE,SAAS,CAAC,SAAS;aAC9B,CAAC,CAAC;QACJ,CAAC;QACD,4EAA4E;IAC7E,CAAC;IAED,OAAO,EAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAC,CAAC;AACjC,CAAC"}

package/dist/merge-question-surfacer.d.ts

@@ -0,0 +1,166 @@
+import { type SurfacePersistOptions, type SurfacePersistResult } from './surface-persist.js';
+/**
+ * The **MERGE-QUESTION SURFACER** (prd `land-time-reverify-and-parallel-merge-ceiling`,
+ * task `merge-question-surfacer`, US #14) — the SECOND, STATE-sourced surfacer
+ * in the advance loop. It is a clean SIBLING to the existing
+ * `surface-questions` JUDGEMENT surfacer (`surface-gate.ts` +
+ * `surface-persist.ts`) — that one spawns a fresh-context agent to JUDGE an
+ * item's open content questions; this one enumerates RUNNER STATE (unmerged
+ * `work/*` branches) and surfaces one MERGE-QUESTION per branch into the SAME
+ * binary sidecar shape. The judgement skill is UNTOUCHED.
+ *
+ * The shape is `surface → answer → apply` over the BINARY sidecar (the keystone
+ * `agentic-question-resolution-retire-disposition-vocabulary`): a sidecar entry
+ * is `no-answer | answered`; there is no `disposition=` token. The dispatch
+ * signal the (separate) apply rung reads is the typed `kind` field
+ * (`sidecar-kind-field`) — this surfacer STAMPS `kind: merge` on every entry it
+ * emits. The `merge | hold | drop` menu rides the entry's `default` as a
+ * human-readable HINT only; the apply layer must NEVER recognise a
+ * merge-question by the shape of `default` (that string-sniff workaround is
+ * exactly what a first build of this task was BLOCKED at review for).
+ *
+ * Layered like the spec asks: the FLOOR (git-alone reachability) is the
+ * authoritative enumerator — it works against a bare `--bare` arbiter with
+ * `NoneProvider`. The CEILING (`gh pr list` PR metadata) is pure ENRICHMENT
+ * layered on top when a GitHub host is configured; the surfacer functions
+ * identically without it.
+ *
+ * OUT OF SCOPE for this task (covered by sibling tasks of the same prd):
+ *
+ *   - The APPLY rung dispatch that lands an answered `kind: merge` through the
+ *     land primitive (rebase → re-verify → advance). Task
+ *     `apply-rung-merge-disposition`.
+ *   - The GATE axis that decides whether this surfacer runs at all on a given
+ *     advance tick. Task `merge-questions-gate-axis`.
+ *
+ * Tests inject the two seams ({@link listUnmergedWorkBranches},
+ * {@link listOpenPullRequests}) so they NEVER hit real GitHub — the floor uses
+ * `git for-each-ref` against a throwaway repo, the ceiling is the injected
+ * `gh pr list` stub.
+ */
+/** A `work/<slug>` branch whose tip is not reachable from `<base>`. */
+export interface UnmergedWorkBranch {
+    /** The full short ref, e.g. `work/foo`. */
+    ref: string;
+    /** The bare slug (`work/` prefix stripped), e.g. `foo`. */
+    slug: string;
+    /** Branch tip SHA (advisory). */
+    sha?: string;
+}
+/** Minimal PR metadata the ceiling renders into the question context. */
+export interface MergeQuestionPullRequest {
+    number: number;
+    url?: string;
+    title?: string;
+    state?: string;
+}
+/** Inputs to the listings seams (and the surfacer). */
+export interface ListUnmergedInput {
+    cwd: string;
+    base: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ListPullRequestsInput {
+    cwd: string;
+    ghBin: string;
+    base: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Options the surfacer takes (almost all seams are injectable for tests). */
+export interface SurfaceMergeQuestionsOptions {
+    /** Working clone the surfacer reads git refs + writes sidecars from. */
+    cwd: string;
+    /**
+     * The arbiter remote URL — when GitHub-shaped (per
+     * {@link isGitHubArbiterUrl}) the CEILING (`gh pr list`) runs. Absent /
+     * non-GitHub ⇒ the floor only (a bare arbiter with `NoneProvider`).
+     */
+    arbiterUrl?: string;
+    /** The base branch reachability is checked against. Default `main`. */
+    base?: string;
+    /** The `gh` CLI binary to invoke for the ceiling. Default `gh` on PATH. */
+    ghBin?: string;
+    /** Environment for spawned git/gh processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+    /**
+     * Seam: enumerate unmerged `work/*` branches (the FLOOR). Production uses
+     * `git for-each-ref` + `git merge-base --is-ancestor`. Tests inject a canned
+     * list so the surfacer is exercised over deterministic inputs.
+     */
+    listUnmergedWorkBranches?: (input: ListUnmergedInput) => UnmergedWorkBranch[];
+    /**
+     * Seam: list open PRs by branch (the CEILING). Production shells
+     * `gh pr list --json …`. Tests inject a stub map so they NEVER touch real
+     * GitHub. Skipped entirely when the arbiter is not GitHub-shaped.
+     */
+    listOpenPullRequests?: (input: ListPullRequestsInput) => Map<string, MergeQuestionPullRequest>;
+    /** Seam: persist a single merge-question. Defaults to {@link persistSurfacedQuestions}. */
+    persist?: (options: SurfacePersistOptions) => SurfacePersistResult;
+}
+/** One surfaced merge-question (a row in the result). */
+export interface MergeQuestionSurfaced {
+    /** The namespaced item identity (`task:<slug>`). */
+    item: string;
+    /** The bare slug. */
+    slug: string;
+    /** The `work/<slug>` ref the question is about. */
+    ref: string;
+    /** The sidecar path the persist touched (repo-relative). */
+    sidecarPath: string;
+    /** The persist commit (`undefined` if the persist was a no-op). */
+    commit?: string;
+    /** PR url when a GitHub ceiling matched the branch (advisory). */
+    prUrl?: string;
+}
+/** One branch the surfacer considered but did not surface (with the reason). */
+export interface MergeQuestionSkipped {
+    ref: string;
+    slug: string;
+    reason: 'no-item-body' | 'already-pending-merge-question' | 'persist-nothing';
+}
+/** Aggregate result of one surfacer pass. */
+export interface SurfaceMergeQuestionsResult {
+    /** How many `work/*` branches were unreachable from `<base>` (the floor). */
+    considered: number;
+    /** The branches a merge-question was emitted for. */
+    surfaced: MergeQuestionSurfaced[];
+    /** The branches that were considered but skipped, with the reason. */
+    skipped: MergeQuestionSkipped[];
+}
+/** Raised for fatal usage errors (a missing repo, etc.). */
+export declare class MergeQuestionSurfacerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Surface merge-questions for every unmerged `work/*` branch in `cwd`.
+ *
+ * The FLOOR (git reachability) is authoritative; the CEILING (`gh pr list`)
+ * runs only when {@link isGitHubArbiterUrl} accepts the arbiter URL, and is
+ * pure enrichment (a missing/failed `gh` degrades silently — the floor still
+ * surfaces the question).
+ *
+ * Idempotency: a branch whose sidecar ALREADY carries a PENDING `kind: merge`
+ * entry is SKIPPED (with `already-pending-merge-question`). A branch with no
+ * item body on `main` is SKIPPED (with `no-item-body`) — the cross-cutting
+ * branch-keyed sidecar identity (PRD sidecar Q5-i) is OOS for this task; an
+ * unmerged-branch-with-no-body lands on the same skip path until that
+ * generalisation arrives.
+ */
+export declare function surfaceMergeQuestions(options: SurfaceMergeQuestionsOptions): SurfaceMergeQuestionsResult;
+/**
+ * Production FLOOR: enumerate every `refs/heads/work/*` whose tip is NOT
+ * reachable from `<base>`. A repo with no `<base>` (e.g. a fresh init before
+ * the first commit) yields the empty list — the surfacer is a no-op until
+ * `main` exists.
+ */
+export declare function listUnmergedWorkBranchesViaGit(input: ListUnmergedInput): UnmergedWorkBranch[];
+/**
+ * Production CEILING: shell `gh pr list --state open --json …` and index the
+ * results by their `headRefName` so the surfacer can enrich the matching
+ * branch's question. A non-zero / missing `gh` is treated as "no host
+ * metadata available" — the floor still surfaces every unmerged branch.
+ */
+export declare function listOpenPullRequestsViaGh(input: ListPullRequestsInput): Map<string, MergeQuestionPullRequest>;
+//# sourceMappingURL=merge-question-surfacer.d.ts.map