dorfl 0.0.0 → 0.1.1

package/src/advance-classify.ts

@@ -0,0 +1,197 @@
+/**
+ * The pure `advance` TICK classifier (prd `advance-loop`, task
+ * `advance-tick-classifier`) — the substrate-agnostic, read-only seam BOTH the
+ * one-shot driver and the loop (`run`) driver wrap. Mirrors the existing pure
+ * `categorise.ts` / `eligibility.ts` seams: NO model, NO lock, NO file mutation
+ * — it returns WHICH rung on WHICH item from EXACTLY two signals plus the item
+ * type, and nothing executes here (the rung EXECUTION is later tasks).
+ *
+ * The two signals (and ONLY these two):
+ *   1. the item's `needsAnswers` flag (from `frontmatter.ts`); and
+ *   2. the sidecar's ANSWERED-STATE (from the `advance-sidecar-contract`
+ *      keystone: {@link allAnswered} / {@link pendingEntries} over the entries).
+ *
+ * The per-item state machine (the deterministic trigger — two signals only):
+ *
+ *   needsAnswers: true?
+ *   ├─ NO  → ANALYSE (state-appropriate rung: build a ready task / task a ready
+ *   │        prd / triage an untriaged observation). Analysis MAY advance, OR
+ *   │        SURFACE questions.
+ *   └─ YES → sidecar exists?
+ *            ├─ NO  → ANALYSE (first pass: generate questions → write the sidecar)
+ *            │        [transitional — surfacing normally writes the sidecar atomically]
+ *            └─ YES → all entries answered?
+ *                     ├─ YES → ANALYSE: apply the answers + advance.
+ *                     └─ NO  → NO-OP (awaiting human).
+ *
+ * Two invariants this classifier (and the downstream that executes the rung)
+ * MUST preserve:
+ *   1. `needsAnswers:false ⟺ NO active sidecar` (clear-flag and delete-sidecar are
+ *      the SAME atomic step — enforced in `advance-sidecar-contract`'s
+ *      `applyAtomic`, asserted HERE at the classifier boundary). A
+ *      contradictory input (one set without the other) is the only state the
+ *      classifier REFUSES to classify into an ANALYSE/NO-OP rung — it returns the
+ *      explicit `invariant-violation` kind so a caller can route it rather than
+ *      silently mis-advance.
+ *   2. A PENDING (not-all-answered) sidecar makes the tick a clean NO-OP (so a
+ *      `run` daemon never spins hot re-surfacing the same question). A SUBSET of
+ *      answered entries is still pending ⇒ SKIP (NO-OP).
+ *
+ * "ANALYSE" is NOT "always advance" — surface-and-pause is itself a rung, so the
+ * ANALYSE branch resolves to the per-TYPE rung the executor will run (the cells
+ * of the prd's "Per-item-type transitions" table): `build-task` (task),
+ * `task-spec` (spec), `triage-observation` (observation) when there are no open
+ * questions; `surface` (first-pass question generation) when `needsAnswers` but
+ * no sidecar yet; `apply` when all entries are answered.
+ */
+
+import type {SidecarModel, SidecarType} from './sidecar.js';
+import {allAnswered} from './sidecar.js';
+
+/**
+ * One TICK input: an item's TYPE + its two classification signals. `needsAnswers`
+ * is the item-body flag (`undefined`/`false` ⇒ not gated; `true` ⇒ gated). The
+ * `sidecar` is the parsed ACTIVE sidecar model when one exists, else `undefined`
+ * — the classifier reads its answered-state via the keystone's derived helpers,
+ * never a third state store.
+ */
+export interface TickItem {
+	/** The item type — the state machine is per-TYPE (task / prd / observation). */
+	type: SidecarType;
+	/** Autonomy axis 2 (DISCOVERED): `true` ⇒ open questions block autonomous work. */
+	needsAnswers: boolean | undefined;
+	/** The parsed ACTIVE sidecar, or `undefined` when none exists. */
+	sidecar: SidecarModel | undefined;
+}
+
+/**
+ * The CLASSIFIED rung kinds (a discriminated union NAMING the rung WITHOUT
+ * executing it). The ANALYSE rungs split per-type; `surface`/`apply` are
+ * type-agnostic transitions; `no-op` is the calm-at-rest result; and
+ * `invariant-violation` is the explicit refusal an inconsistent input yields.
+ */
+export type TickRungKind =
+	// --- ANALYSE rungs (no open questions; advance one lifecycle rung) ---
+	/** A ready task → build it (later: invoke the `do <slug>` machinery). */
+	| 'build-task'
+	/** A ready spec → task it (later: invoke the `do spec:<slug>` machinery). */
+	| 'task-spec'
+	/** An untriaged observation → triage it (auto-disposition or surface a question). */
+	| 'triage-observation'
+	// --- Transitional ANALYSE rungs (driven by the two signals) ---
+	/** `needsAnswers` but NO sidecar yet → first-pass question generation. */
+	| 'surface'
+	/** A sidecar with EVERY entry answered → apply the answers + advance. */
+	| 'apply'
+	// --- Calm-at-rest ---
+	/** Nothing to do: a PENDING sidecar (awaiting human) or nothing eligible. */
+	| 'no-op'
+	// --- The refused state ---
+	/** The `needsAnswers:false ⟺ no active sidecar` invariant is broken. */
+	| 'invariant-violation';
+
+/**
+ * The classifier's verdict: the rung kind, the item type it was classified for,
+ * and a short machine-stable `reason` tag for the NO-OP / refusal cases (so a
+ * caller — or a test — can distinguish "pending sidecar" from "nothing eligible"
+ * without re-deriving the signals).
+ */
+export interface TickClassification {
+	kind: TickRungKind;
+	type: SidecarType;
+	/**
+	 * A machine-stable tag explaining a `no-op` / `invariant-violation`:
+	 *   - `pending-sidecar` — an active sidecar still has unanswered entries.
+	 *   - `needsAnswers-without-sidecar` — `needsAnswers:true` but no sidecar AND
+	 *     this should have surfaced (kept for completeness; `surface` covers the
+	 *     normal first pass, so this only appears on the refusal path below).
+	 *   - `sidecar-without-needsAnswers` — a sidecar exists but `needsAnswers` is
+	 *     not `true` (invariant 1 broken — the flag and the sidecar disagree).
+	 * `undefined` for the ANALYSE rungs and `apply`/`surface`.
+	 */
+	reason?:
+		| 'pending-sidecar'
+		| 'needsAnswers-without-sidecar'
+		| 'sidecar-without-needsAnswers';
+}
+
+/** The per-TYPE ANALYSE rung when there are no open questions (the no-gate path). */
+const ANALYSE_RUNG_FOR_TYPE: Record<SidecarType, TickRungKind> = {
+	task: 'build-task',
+	// A `spec` analyses through the `task-spec` rung (spec IS the parent-spec
+	// artifact tasked into build tasks).
+	spec: 'task-spec',
+	observation: 'triage-observation',
+};
+
+/**
+ * Classify ONE tick PURELY from the item's two signals + its type — read-only,
+ * no model, no lock, no file mutation. Returns the classified rung the executor
+ * will later run (or `no-op` / `invariant-violation`). The decision tree is the
+ * prd's per-item state machine, with invariant 1 asserted at the boundary:
+ *
+ *   - `needsAnswers` NOT true:
+ *       - a sidecar present ⇒ INVARIANT 1 BROKEN (`sidecar-without-needsAnswers`)
+ *         → `invariant-violation`. (`needsAnswers:false ⟺ no active sidecar`.)
+ *       - no sidecar ⇒ ANALYSE: the per-type rung (`build-task` / `task-spec` /
+ *         `triage-observation`).
+ *   - `needsAnswers` true:
+ *       - NO sidecar ⇒ `surface` (first-pass question generation — transitional).
+ *       - a PENDING sidecar (a subset/none answered) ⇒ `no-op` (`pending-sidecar`)
+ *         — the clean NO-OP that keeps a `run` daemon from spinning hot; a SUBSET
+ *         of answered entries SKIPS here too.
+ *       - an ALL-ANSWERED sidecar ⇒ `apply` (apply the answers + advance; the
+ *         executor may append new Qs and re-pause, or resolve fully).
+ */
+export function classifyTick(item: TickItem): TickClassification {
+	const {type, needsAnswers, sidecar} = item;
+	const gated = needsAnswers === true;
+
+	if (!gated) {
+		// Invariant 1: `needsAnswers:false ⟺ no active sidecar`. A sidecar present
+		// here means the flag and the sidecar DISAGREE — refuse rather than
+		// silently advance past an open question the flag forgot to declare.
+		if (sidecar !== undefined) {
+			return {
+				kind: 'invariant-violation',
+				type,
+				reason: 'sidecar-without-needsAnswers',
+			};
+		}
+		// ANALYSE: the per-type lifecycle rung (read-only classification only).
+		return {kind: ANALYSE_RUNG_FOR_TYPE[type], type};
+	}
+
+	// `needsAnswers` is true.
+	if (sidecar === undefined) {
+		// First pass: no sidecar yet → surface the questions (write it). This is the
+		// transitional cell — surfacing normally writes the sidecar atomically, so a
+		// gated item without a sidecar is the moment to generate questions.
+		return {kind: 'surface', type};
+	}
+
+	// A sidecar exists: the two signals AGREE (invariant 1 holds). The answered-
+	// state — derived from the ENTRIES, never the frontmatter mirror — decides.
+	if (allAnswered(sidecar)) {
+		// Every entry answered → apply + advance (the executor may re-pause).
+		return {kind: 'apply', type};
+	}
+
+	// A PENDING sidecar (a SUBSET answered, or none) ⇒ clean NO-OP. This is the
+	// invariant-2 cell: the loop never thrashes on a half-answered item; it idles
+	// until the human answers the rest (equivalent to `pendingEntries.length > 0`).
+	return {kind: 'no-op', type, reason: 'pending-sidecar'};
+}
+
+/**
+ * Is this classified rung a CLASSIFIED-NO-OP (the calm-at-rest result)? A small
+ * predicate the loop/convergence tests use to assert "the candidate pool is
+ * STABLE" — a `no-op` OR an `invariant-violation` is NOT an advanceable rung. The
+ * ANALYSE rungs + `surface` + `apply` ARE advanceable.
+ */
+export function isAdvanceable(classification: TickClassification): boolean {
+	return (
+		classification.kind !== 'no-op' &&
+		classification.kind !== 'invariant-violation'
+	);
+}

package/src/advance-drivers.ts

@@ -0,0 +1,414 @@
+import {
+	performAdvance,
+	type AdvanceContext,
+	type AdvanceResult,
+	type AdvanceExitCode,
+	type AdvanceOutcome,
+} from './advance.js';
+import {
+	pushTreelessResult,
+	TREELESS_RUNGS,
+} from './advance-treeless-publish.js';
+import {scanRepoPaths} from './scan.js';
+import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
+import {
+	selectPrioritised,
+	taskableSpecs,
+	type SpecCandidate,
+	type SelectedItem,
+} from './select-priority.js';
+import {gatherLifecycleInPlace} from './lifecycle-gather.js';
+import type {LifecyclePoolGates} from './lifecycle-pools.js';
+import type {Config} from './config.js';
+import type {ConfigOverrideMap} from './config-override.js';
+
+/**
+ * The **`advance` one-shot DRIVER** (prd `advance-loop`, task
+ * `advance-drivers-and-gates`, US #2/7/23/25/26) — the SEQUENTIAL driver that
+ * WRAPS the substrate-agnostic advance TICK ({@link performAdvance}) over named
+ * item(s) or the bare eligible-SET form. It is the in-place counterpart of
+ * `do-autopick`'s {@link performDoAuto}/{@link performDoArgs}: it SELECTS +
+ * ORDERS items and runs the EXISTING tick per item, SEQUENTIALLY.
+ *
+ * **One substrate-agnostic TICK, two drivers (US #7).** The tick (classify →
+ * lock → execute, already built in {@link performAdvance}) is the shared
+ * contract. The TWO drivers wrap it:
+ *
+ *   - the **one-shot driver** (this module) — human `advance`-style or a CI
+ *     invocation: runs the tick over named item(s) / the eligible set
+ *     SEQUENTIALLY (`advance` is sequential, exactly like `do`);
+ *   - the **loop driver** (`run`, `run.ts`) — loops the tick over the eligible
+ *     set with genuine parallelism, each item lock-guarded by the `advancing`
+ *     borrow (already in {@link performAdvance}). `run` ≡ CI (same tick, different
+ *     substrate); NO new execution model is introduced.
+ *
+ * **`-n x` is ALWAYS SEQUENTIAL (US #25)** — a dumb "run the tick N times" loop,
+ * for BOTH `do -n` ({@link performDoAuto}) and `advance -n` (here). Parallelism is
+ * NEVER a property of `-n`; it comes only from `run` (the concurrent loop) or the
+ * CI matrix.
+ *
+ * **The FLAT per-action gate family (US #23)** falls out of the SELECTION layer,
+ * exactly as it does for `do`: the eligible-pool scan only SURFACES a build item
+ * when `autoBuild` is on and a task-a-prd item when `autoTask` is on (the gate
+ * is a policy on the autonomous-SELECTION step, NOT on the explicit verb a human
+ * typed — an explicitly-NAMED `advance <slug>` builds regardless, mirroring
+ * `do <task>` vs `autoBuild`). SURFACE + APPLY are ALWAYS allowed — they run
+ * through the tick on any named item and are never pool-gated, so a repo with
+ * EVERY flag off still gets the QUESTION LOOP (surface + apply) but no autonomous
+ * build/task in the bare/`-n` selection ("question loop with zero autonomy").
+ * The triage rung's ask-vs-auto distinction (`observationTriage`) is read inside
+ * the tick; its SELECTION-layer `off` gate drops the observation pool here.
+ *
+ * **Isolation + chaining FALL OUT (US #26):** this driver builds NO new isolation
+ * or chaining machinery — it threads the SAME `AdvanceContext` the tick already
+ * consumes (which orchestrates `do`/`do prd:` through the isolation-strategy seam
+ * and rebase-before-integrate); a chain conflict routes to needs-attention as
+ * today, inside the orchestrated `do`.
+ */
+
+/** The single-`advance` tick runner this driver drives per selected item. */
+export type AdvanceTickRunner = (
+	options: AdvanceTickOptions,
+) => Promise<AdvanceResult>;
+
+/** The per-item tick options: the run context + the one resolved arg. */
+export interface AdvanceTickOptions extends AdvanceContext {
+	arg: string;
+	read?: LedgerReadStrategy;
+}
+
+/** Options shared with every per-item tick run, threaded verbatim. */
+type SharedAdvanceContext = AdvanceContext;
+
+export interface PerformAdvanceMultiOptions extends SharedAdvanceContext {
+	/**
+	 * The resolved repo config — provides `autoBuild` (the build gate for the
+	 * task pool), `autoTask` (the task-a-prd gate for the prd pool), and
+	 * `selectionOrder` (the configurable cross-pool order). The per-action gate
+	 * family is APPLIED HERE, at the selection layer (the policy-on-autonomous-
+	 * selection point).
+	 */
+	config: Config;
+	/**
+	 * The per-machine {@link ConfigOverrideMap}. Threaded into the in-place pool
+	 * scan (`scanRepoPaths`) so the per-machine override applies to advance
+	 * autopick eligibility — WITHOUT it the committed `.dorfl.json` silently
+	 * beats the override on this path (the in-place advance autopick mirror of the
+	 * `do` autopick defect).
+	 */
+	override?: ConfigOverrideMap;
+	/**
+	 * `advance -n <x>`: how many eligible items to advance, IN SEQUENCE. Bare
+	 * `advance` (no arg, no count) ⇒ 1. SEQUENTIAL — never a parallelism knob
+	 * (US #25; parallelism is `run` or the CI matrix).
+	 */
+	count?: number;
+	/** Override the single-tick runner (tests inject a stub). Defaults to {@link performAdvance}. */
+	run?: AdvanceTickRunner;
+	/** Override the read seam (prd pool); defaults to the active {@link ledgerRead}. */
+	read?: LedgerReadStrategy;
+	/**
+	 * The LIFECYCLE-POOL create-gates (task `advance-autopick-lifecycle-pools`),
+	 * the internal hook the gate tasks (`observation-triage-tri-state-gate` /
+	 * `surface-blockers-gate`) will wire to the `observationTriage` /
+	 * `surfaceBlockers` config read. INTERIM, born OFF: omitted ⇒ BOTH create-gates
+	 * OFF, so the triage + surface sub-pools contribute NOTHING and a bare/`-n`
+	 * `advance` auto-triages / auto-surfaces nothing (it changes no repo's
+	 * behaviour). The apply sub-pool is NOT gated (consume is always-on), so an
+	 * answered sidecar applies regardless. Tests FORCE the create-gates on through
+	 * this same hook to exercise the triage/surface paths.
+	 */
+	lifecycleGates?: LifecyclePoolGates;
+}
+
+/** The aggregate result of a multi-item `advance` invocation. */
+export interface AdvanceMultiResult {
+	/** Each per-item {@link AdvanceResult}, in the order they ran. */
+	results: AdvanceResult[];
+	/**
+	 * The process exit code for the whole invocation: 0 iff EVERY item that ran
+	 * succeeded (or there was nothing eligible — an empty bare `advance` is not a
+	 * failure); otherwise the first non-zero per-item exit code (the worst outcome
+	 * surfaces). Mirrors `do`'s multi-item exit contract.
+	 */
+	exitCode: AdvanceExitCode;
+	/** Human-readable summary (printed by the CLI). */
+	message: string;
+}
+
+/**
+ * The task-pool caps for an in-place `advance` selection. `advance` (one-shot) is
+ * per-repo + SEQUENTIAL, so the REAL bound is the requested `count`. We cap the
+ * task pool at "all eligible" and let {@link selectPrioritised}'s `count` trim
+ * across both pools — identical to `do-autopick`'s {@link performDoAuto}.
+ */
+const ALL_ELIGIBLE = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Run the BARE / `-n <x>` form: build the two ELIGIBLE pools for `cwd` (eligible
+ * TASKS gated by `autoBuild`, taskable prds gated by `autoTask`), order them
+ * (plus the lifecycle pools) per the resolved `selectionOrder` with `apply`
+ * pinned first, take `count` (default 1), and run the EXISTING advance tick per
+ * selected item, SEQUENTIALLY. The pools are the EXACT
+ * `do-autopick` pools (the SAME `scoreItems`/`taskableSpecs` predicates), so the
+ * per-action gate family is honoured by construction.
+ *
+ * The bare/`-n` selection draws ONLY from the autonomous pools (eligible tasks +
+ * taskable prds); SURFACE + APPLY of a gated item are reached by NAMING the item
+ * ({@link performAdvanceArgs}) — they are always-allowed and not pool-gated, so the
+ * bare form with every flag off correctly selects NOTHING (zero autonomy) while a
+ * named `advance <slug>` still surfaces/applies.
+ */
+export async function performAdvanceAuto(
+	options: PerformAdvanceMultiOptions,
+): Promise<AdvanceMultiResult> {
+	const run = options.run ?? performAdvance;
+	const read = options.read ?? ledgerRead;
+	const note = options.note ?? (() => {});
+	const cwd = options.cwd;
+	const count = options.count ?? 1;
+
+	// Pool 1 — eligible TASKS via the EXISTING scan/select path. `scoreItems`
+	// inside `scanRepoPaths` gates eligibility on `autoBuild` (the build gate), so
+	// with `autoBuild` off NO task is selected — the build rung is never reached
+	// by the bare/`-n` selection.
+	const report = scanRepoPaths(
+		[cwd],
+		options.config,
+		new Set(),
+		options.override,
+	);
+
+	// Pool 2 — TASKABLE prds filtered by `autoslice-gate`'s predicate (gated on
+	// `autoTask`). With `autoTask` off NO prd is selected — the task rung is
+	// never reached by the bare/`-n` selection.
+	const pool = read.resolveSpecPool({repoPath: cwd});
+	const specCandidates: SpecCandidate[] = pool.specs.map((spec) => ({
+		repoPath: cwd,
+		slug: spec.slug,
+		humanOnly: spec.humanOnly,
+		needsAnswers: spec.needsAnswers,
+		taskedAfter: spec.taskedAfter,
+	}));
+	const eligibleSpecs = taskableSpecs({
+		candidates: specCandidates,
+		taskedSlugs: pool.taskedSlugs,
+		autoTask: options.config.autoTask,
+	});
+
+	// Pools 3 + 4 — the LIFECYCLE pools (untriaged observations + `needsAnswers`-
+	// blocked tasks/prds + answered-sidecar items), built CALLER-SIDE (here, the
+	// `advance` caller) through the SHARED enumeration unit and passed in — NOT baked
+	// into `selectPrioritised` (so `do` is provably unchanged). The create-gates
+	// default OFF (interim hardcoded-off): triage + surface contribute nothing; the
+	// apply sub-pool is always-on (consume), so an answered sidecar still applies.
+	const lifecycle = gatherLifecycleInPlace({
+		repoPath: cwd,
+		read,
+		gates: options.lifecycleGates,
+	});
+
+	// Order across the (up to) FIVE pools per the resolved `selectionOrder` (apply
+	// pinned first) + bound by count — the SAME shared, pure `selectPrioritised` the
+	// `do` auto-pick driver uses (which passes NO lifecycle pools, so it is unchanged).
+	const selected = selectPrioritised({
+		report,
+		caps: {maxParallel: ALL_ELIGIBLE, perRepoMax: ALL_ELIGIBLE},
+		specs: eligibleSpecs,
+		selectionOrder: options.config.selectionOrder,
+		lifecycle,
+		count,
+	});
+
+	if (selected.length === 0) {
+		// With every gate off this is the "zero autonomy" case: nothing autonomous to
+		// select. The question loop (surface/apply) is reached by NAMING an item, not
+		// the bare form — so this is calm-at-rest, NOT a failure.
+		const message =
+			'Nothing eligible to advance (no eligible tasks and no taskable prds ' +
+			'under the per-action gates; name an item to surface/apply its questions).';
+		note(message);
+		return {results: [], exitCode: 0, message};
+	}
+
+	return runSelectedInSequence(selected, options, run);
+}
+
+/**
+ * Run the EXPLICIT multi-arg form (`advance <a> <b> …`): the named items in the
+ * GIVEN order (no pool/priority — the operator chose them). Each arg is run
+ * through the existing advance tick, which itself resolves bare/`task:`/`prd:`/
+ * `obs:` (so a named prd drives the task rung, an `obs:` the triage rung, a
+ * collision errors), SEQUENTIALLY. A NAMED item is the always-allowed path — its
+ * surface/apply rung runs regardless of the per-action gates.
+ */
+export async function performAdvanceArgs(
+	args: string[],
+	options: PerformAdvanceMultiOptions,
+): Promise<AdvanceMultiResult> {
+	const run = options.run ?? performAdvance;
+	const selected: SelectedItem[] = args.map((arg) => ({
+		repoPath: options.cwd,
+		slug: arg,
+		// The arg is passed VERBATIM to the tick (it does its own slug resolution
+		// across task/prd/observation); the namespace is irrelevant for explicit args.
+		namespace: 'task' as const,
+	}));
+	return runSelectedInSequence(selected, options, run, {verbatimArg: true});
+}
+
+/**
+ * Run a list of selected items through the existing advance tick, SEQUENTIALLY
+ * (US #25 — `-n` is always sequential), threading the shared context to each. For
+ * the pool path the arg encodes the namespace (`prd:<slug>` for a selected prd,
+ * bare slug for a task); for the explicit-arg path the caller's raw arg is passed
+ * verbatim. Each tick is INDEPENDENTLY `advancing`-lock-guarded inside
+ * {@link performAdvance} — sequential here means one item at a time, never a
+ * parallelism knob.
+ */
+async function runSelectedInSequence(
+	selected: SelectedItem[],
+	options: PerformAdvanceMultiOptions,
+	run: AdvanceTickRunner,
+	mode: {verbatimArg?: boolean} = {},
+): Promise<AdvanceMultiResult> {
+	const shared = sharedAdvanceContext(options);
+	const results: AdvanceResult[] = [];
+	for (const item of selected) {
+		const arg = mode.verbatimArg ? item.slug : argForSelectedItem(item);
+		const result = await runAdvanceTickWithTreelessPublish(
+			{...shared, arg, read: options.read},
+			run,
+		);
+		results.push(result);
+	}
+
+	const firstFailure = results.find((r) => r.exitCode !== 0);
+	const exitCode: AdvanceExitCode = firstFailure ? firstFailure.exitCode : 0;
+	const ok = results.filter((r) => r.exitCode === 0).length;
+	const message =
+		`advanced ${results.length} item${results.length === 1 ? '' : 's'} ` +
+		`(${ok} ok, ${results.length - ok} not).`;
+	return {results, exitCode, message};
+}
+
+/**
+ * Run ONE in-place advance tick + ff-push a tree-less rung's result to the
+ * arbiter — task `advance-in-place-publishes-treeless-results`. Wraps the
+ * substrate-agnostic tick ({@link AdvanceTickRunner}) with the shared
+ * {@link pushTreelessResult} so a surfaced sidecar / `triaged:` marker /
+ * applied-answer commit committed LOCALLY in the in-place cwd LANDS on the
+ * arbiter's `main` (today the in-place tick commits locally and the work is lost
+ * on an ephemeral CI runner). Mirrors the `--isolated` one-shot + `run` loop
+ * driver call sites byte-for-byte:
+ *
+ *   - gates PURELY on `result.exitCode === 0 && TREELESS_RUNGS.has(result.rung)
+ *     && context.arbiter !== undefined` — the SAME gate the existing drivers
+ *     use, no cleverer guard (a build/task rung integrates through the
+ *     `doDriver` band; a no-arbiter laptop checkout already sits on the real
+ *     `main`);
+ *   - reuses `pushTreelessResult` VERBATIM (its bounded re-fetch+rebase retry is
+ *     LOAD-BEARING for a sequential `-n` batch that integrates a build/task rung
+ *     mid-batch and then runs a later tree-less rung whose `HEAD:main` push is
+ *     non-fast-forward by construction);
+ *   - NEVER `--force`. A push that keeps failing (or a genuine rebase conflict)
+ *     is REPORTED via the `note` sink and does NOT crash the tick — the work
+ *     stays committed in the cwd for the next pass / a human.
+ *
+ * Used by BOTH in-place entry points: {@link runSelectedInSequence} (the
+ * multi-item `-n` / auto-pick / multi-arg path) AND the CLI single-named-item
+ * path (which calls {@link performAdvance} directly, bypassing the sequence
+ * runner — the easy-to-miss site).
+ *
+ * The promote-apply edge mirrors the existing drivers without a special case: an
+ * `apply` rung whose agentic verdict mints an artifact (`mint-task`/`mint-prd`)
+ * runs `promoteObservation`'s OWN arbiter CAS and commits NOTHING tree-less, so the
+ * ff-push here is a harmless no-op (a `HEAD` with nothing new) — it does NOT
+ * double-publish nor clobber the promote CAS.
+ */
+export async function runAdvanceTickWithTreelessPublish(
+	options: AdvanceTickOptions,
+	run: AdvanceTickRunner,
+): Promise<AdvanceResult> {
+	const result = await run(options);
+	if (
+		result.exitCode === 0 &&
+		result.rung !== undefined &&
+		TREELESS_RUNGS.has(result.rung) &&
+		options.arbiter !== undefined
+	) {
+		await pushTreelessResult({
+			cwd: options.cwd,
+			arbiter: options.arbiter,
+			// Large liveness ceiling — see `pushTreelessResult`'s C2 docs (task
+			// `c2-rebase-until-real-on-durable-main-promotions`). A clean re-rebase
+			// no longer counts against a small budget; a genuine conflict (slug gone
+			// from its source folder on the new `main`) still stops definitively.
+			retries: 1000,
+			env: undefined,
+			note: options.note ?? (() => {}),
+		});
+	}
+	return result;
+}
+
+/**
+ * The advance TICK arg for a pool-selected item — the SELECTION->ARG dispatch
+ * (task `advance-autopick-lifecycle-pools`, F-NAMESPACE). The `namespace`
+ * discriminator the selection carried maps to the tick arg the tick then
+ * classifies into the right rung:
+ *   - `observation` → `obs:<slug>` (the triage rung; bare would resolve to a
+ *     task, so the `obs:` prefix is required);
+ *   - `spec` → `spec:<slug>` (a taskable spec's task rung, OR a `needsAnswers` spec
+ *     the tick surfaces/applies);
+ *   - `task` → bare `<slug>` (an eligible task's build rung, OR a `needsAnswers`
+ *     task the tick surfaces/applies).
+ * The tick re-classifies each arg, so a `needsAnswers`-blocked task/prd reaches
+ * surface/apply and an untriaged observation reaches triage — the classifier +
+ * rung bodies are unchanged; only this selection->arg mapping is new.
+ */
+function argForSelectedItem(item: SelectedItem): string {
+	if (item.namespace === 'observation') {
+		return `obs:${item.slug}`;
+	}
+	if (item.namespace === 'spec') {
+		return `spec:${item.slug}`;
+	}
+	return item.slug;
+}
+
+/** Strip the multi-only fields, leaving exactly the per-item {@link AdvanceContext}. */
+function sharedAdvanceContext(
+	options: PerformAdvanceMultiOptions,
+): SharedAdvanceContext {
+	const {
+		config: _config,
+		count: _count,
+		run: _run,
+		read: _read,
+		lifecycleGates: _lifecycleGates,
+		...rest
+	} = options;
+	void _config;
+	void _count;
+	void _run;
+	void _read;
+	void _lifecycleGates;
+	return rest;
+}
+
+/**
+ * Is this aggregate result a CALM-AT-REST (US #31 convergence) one — every item
+ * that ran was a NO-OP (a pending sidecar idling) AND nothing failed? The
+ * convergence/drain tests use this to assert the loop IDLES when there are no
+ * answers (no thrash) and DRAINS monotonically as answers arrive. A pool of
+ * pending-sidecar items advances NOTHING (every tick a clean no-op); as the human
+ * answers, the answered items flip to `apply` and the no-op count shrinks.
+ */
+export function isCalmAtRest(result: AdvanceMultiResult): boolean {
+	return (
+		result.exitCode === 0 && result.results.every((r) => r.outcome === 'no-op')
+	);
+}
+
+export type {AdvanceOutcome};