dorfl 0.0.0 → 0.1.1

package/dist/advance-ci-template.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The CI-integration deliverable for the `advance` loop (prd `advance-loop`,
+ * task `advance-install-ci`, US #27/28): the advance-loop CAPABILITY as a
+ * DOCUMENTED workflow TEMPLATE (not a CLI subcommand; see the task's `##
+ * Decisions`). The template at `docs/ci/advance-loop.yml.template` wires "on cron
+ * / on-answer-committed, run the RIGHT shape" and only INVOKES the existing
+ * `advance` driver; it is NOT entangled with the tick.
+ *
+ * The unified, per-capability `install-ci` CLI (auth/secrets wizard + GitHub
+ * adapter) is owned by the separate `runner-in-ci` prd
+ * (`work/prds/tasked/runner-in-ci.md`); when built it EMITS this template as its
+ * advance-loop capability. This module's job is unchanged either way: locate +
+ * STRUCTURALLY VALIDATE the template, so its shape is a contract the CLI can
+ * safely emit (see `docs/ci/README.md` "Relationship to the `install-ci` CLI").
+ *
+ * This module locates + reads that template and STRUCTURALLY VALIDATES it. The
+ * package depends on NO YAML library (see `frontmatter.ts` for the same
+ * constraint), so {@link validateAdvanceCiTemplate} checks the small set of
+ * invariants the task's acceptance criteria require directly:
+ *
+ *   - triggers on a CRON schedule AND on-answer-committed (a push touching
+ *     `work/questions/**`);
+ *   - `propose` mode → a MATRIX of independent jobs enumerated via the
+ *     mirror-side pool scan (`dorfl scan --json`), one `advance … --propose`
+ *     per item (the `--propose` flag TIES the integration mode to the matrix shape,
+ *     so a leg can never merge to main);
+ *   - `merge` mode → a MATRIX of independent jobs (one per item), each leg
+ *     running `dorfl advance <item> --merge` so build/gate/review run
+ *     concurrently across siblings; the LAND TAIL is serialised by the engine's
+ *     `mergeRetries` CAS-retry loop (the git-alone floor), NOT by this
+ *     workflow's job shape — a host-specific `concurrency:` group would be
+ *     load-bearing for safety, which the floor framing forbids;
+ *   - the dispatch input is `integrationMode` (ONE word, ONE meaning): it drives
+ *     BOTH the integration flag the legs pass AND the job shape, so they cannot
+ *     desync;
+ *   - it references the EXISTING `advance` driver only (no new execution model);
+ *   - it is a `.template` (so it never self-triggers in THIS repo).
+ *
+ * The check is deliberately a set of presence/shape assertions over the raw text
+ * rather than a full YAML parse — it is the dependency-free counterpart of "the
+ * template parses + references the right driver invocations" the task asks for.
+ */
+/** A single structural problem found in the template. */
+export interface AdvanceCiTemplateProblem {
+    /** A short, stable id for the violated invariant (for tests/assertions). */
+    id: string;
+    /** Human-readable description of what is missing or wrong. */
+    message: string;
+}
+/** The result of {@link validateAdvanceCiTemplate}. */
+export interface AdvanceCiTemplateValidation {
+    /** True iff the template satisfies EVERY structural invariant. */
+    ok: boolean;
+    /** Each violated invariant (empty when `ok`). */
+    problems: AdvanceCiTemplateProblem[];
+}
+/**
+ * Locate the workflow template `docs/ci/advance-loop.yml.template`. It is a
+ * REPO doc (the maintainer copies it into a consumer's `.github/workflows/`), so
+ * it is resolved relative to this source file's monorepo position — the same
+ * dev-monorepo walk `resolveProtocolDoc`'s last candidates use. `override`
+ * short-circuits for tests / unusual layouts.
+ */
+export declare function resolveAdvanceCiTemplatePath(override?: string): string;
+/** Read the raw template text. Throws (ENOENT) if it cannot be located. */
+export declare function loadAdvanceCiTemplate(override?: string): string;
+/**
+ * Structurally validate the advance-loop CI workflow template against the task's
+ * acceptance criteria. Dependency-free (no YAML lib): a set of presence/shape
+ * assertions over the raw text.
+ */
+export declare function validateAdvanceCiTemplate(text: string): AdvanceCiTemplateValidation;
+//# sourceMappingURL=advance-ci-template.d.ts.map

package/dist/advance-ci-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-ci-template.d.ts","sourceRoot":"","sources":["../src/advance-ci-template.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACxC,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,2BAA2B;IAC3C,kEAAkE;IAClE,EAAE,EAAE,OAAO,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,wBAAwB,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtE;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,MAAM,GACV,2BAA2B,CA2F7B"}

package/dist/advance-ci-template.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Locate the workflow template `docs/ci/advance-loop.yml.template`. It is a
+ * REPO doc (the maintainer copies it into a consumer's `.github/workflows/`), so
+ * it is resolved relative to this source file's monorepo position — the same
+ * dev-monorepo walk `resolveProtocolDoc`'s last candidates use. `override`
+ * short-circuits for tests / unusual layouts.
+ */
+export function resolveAdvanceCiTemplatePath(override) {
+    if (override) {
+        return override;
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    // here = .../packages/dorfl/{src,dist}; the doc lives at the monorepo
+    // root under docs/ci/. Walk up to the root from either src/ or dist/.
+    const candidates = [
+        resolve(here, '..', '..', '..', 'docs', 'ci', 'advance-loop.yml.template'),
+        resolve(here, '..', '..', '..', '..', 'docs', 'ci', 'advance-loop.yml.template'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    // Fall back to the first candidate so the error names the expected path.
+    return candidates[0];
+}
+/** Read the raw template text. Throws (ENOENT) if it cannot be located. */
+export function loadAdvanceCiTemplate(override) {
+    return readFileSync(resolveAdvanceCiTemplatePath(override), 'utf8');
+}
+/**
+ * Structurally validate the advance-loop CI workflow template against the task's
+ * acceptance criteria. Dependency-free (no YAML lib): a set of presence/shape
+ * assertions over the raw text.
+ */
+export function validateAdvanceCiTemplate(text) {
+    const problems = [];
+    const require = (id, present, message) => {
+        if (!present) {
+            problems.push({ id, message });
+        }
+    };
+    // --- Triggers: cron AND on-answer-committed ---------------------------------
+    require('trigger-cron', /\bschedule:\s*[\s\S]*?-\s*cron:/.test(text), 'must trigger on a cron schedule (`on.schedule[].cron`).');
+    require('trigger-on-answer-committed', /\bpush:\s*[\s\S]*?paths:[\s\S]*?work\/questions\//.test(text), 'must trigger on-answer-committed (a push touching `work/questions/**`).');
+    // --- propose ⇒ a MATRIX enumerated via the mirror-side pool scan -------------
+    require('propose-matrix', /strategy:\s*[\s\S]*?matrix:/.test(text), '`propose` mode must emit a MATRIX of jobs (`strategy.matrix`).');
+    require('propose-enumerates-via-scan', /dorfl scan --json/.test(text), 'the matrix items must be ENUMERATED via the mirror-side pool scan ' +
+        '(`dorfl scan --json`).');
+    // The `enumerate` `jq` must UNION taskable prds into the matrix
+    // (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`): a
+    // task-only `jq` would render `DORFL_AUTO_TASK` dead on the hourly
+    // cron — a ready ungated PRD would never become a matrix leg. The `jq` must
+    // read `scan --json`'s taskable-SPEC pool (`repos[].specs[]` + `cwd.repo.specs[]`)
+    // and emit `spec:<slug>` legs alongside the `task:<slug>` legs.
+    require('propose-enumerates-taskable-specs', /"spec:" \+ \.slug/.test(text) &&
+        /\.specs\[\]/.test(text), 'the propose-mode `enumerate` `jq` must union taskable specs into the ' +
+        "matrix as `spec:<slug>` legs (read from `scan --json`'s `repos[].specs[]` " +
+        '+ `cwd.repo.specs[]` pools), so a ready ungated SPEC becomes one auto-task ' +
+        'matrix leg alongside the eligible-task legs ' +
+        '(`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`).');
+    require('propose-one-advance-per-item', /dorfl advance "?\$\{\{\s*matrix\./.test(text), 'each matrix leg must run one `dorfl advance <matrix item>` ' +
+        '(one PR per item).');
+    // The matrix leg must carry `--propose` so the integration mode is TIED to the
+    // matrix shape (it cannot desync from the dispatch `integrationMode` input nor
+    // fall back to a repo config default of `merge`). Scoped to the `advance-propose`
+    // job so it is the LEG that carries it, not merely the file somewhere.
+    require('propose-leg-carries-propose-flag', /advance-propose:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--propose\b/.test(text), 'each `propose` matrix leg must pass `--propose` so the integration mode is ' +
+        'TIED to the matrix shape (a leg can never merge to main / desync from the ' +
+        'dispatch mode).');
+    // --- merge ⇒ a MATRIX per item (parallel build/gate/review, serialised land) -
+    // The engine's `integrateLock` + `mergeRetries` CAS-retry loop is what makes
+    // concurrent merge jobs LAND-SAFE (`land-time-reverify-and-parallel-merge-ceiling`):
+    // build/gate/review fan out across siblings, and a non-fast-forward push
+    // triggers re-rebase + re-gate + retry up to the resolved `mergeRetries` cap.
+    // The cross-job serialiser is the CAS-retry loop itself — the git-alone floor.
+    require('merge-matrix', /advance-merge:[\s\S]*?strategy:\s*[\s\S]*?matrix:/.test(text), 'the `merge` job must use a MATRIX (parallel build/gate/review per item; ' +
+        "the land tail is serialised by the engine's `mergeRetries` CAS-retry " +
+        "loop, not by the workflow's job shape).");
+    // Each merge matrix leg must run one `dorfl advance <matrix.item> --merge`,
+    // scoped to the `advance-merge:` job so the `--merge` flag is TIED to its leg
+    // (cannot desync from the dispatch `integrationMode` input nor fall back to a
+    // repo config default of `propose`).
+    require('merge-leg-carries-merge-flag', /advance-merge:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--merge\b/.test(text), 'each `merge` matrix leg must pass `--merge` so the integration mode is ' +
+        'TIED to the matrix shape (a leg can never propose-only / desync from the ' +
+        'dispatch mode).');
+    // The merge fan-out is the SAFETY-FLOOR shape: no `concurrency:` group on the
+    // `advance-merge:` job, because a GitHub Actions `concurrency:` serialiser
+    // would be load-bearing for cross-job land safety, and the floor must work on
+    // a bare arbiter with no host (Applied Answer q1: scaled CAS-retry is the
+    // floor; the portable cross-job ref-lock is the planned accelerator; GitHub
+    // `concurrency:` is OPTIONAL host sugar only, deliberately not used here).
+    require('merge-no-host-concurrency-serialiser', !/advance-merge:[\s\S]*?\n\s{4}concurrency:/.test(text), 'the `merge` job must NOT carry a `concurrency:` group: a host-specific ' +
+        'serialiser would make the cross-job land safety depend on a GitHub Actions ' +
+        "feature; the engine's `mergeRetries` CAS-retry loop is the git-alone " +
+        'floor.');
+    // --- It only INVOKES the existing `advance` driver (no new execution model) --
+    require('invokes-advance-driver', /dorfl advance\b/.test(text), 'the workflow must INVOKE the existing `advance` driver.');
+    return { ok: problems.length === 0, problems };
+}
+//# sourceMappingURL=advance-ci-template.js.map

package/dist/advance-ci-template.js.map

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

package/dist/advance-classify.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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';
+/**
+ * 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 = 
+/** 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'
+/** `needsAnswers` but NO sidecar yet → first-pass question generation. */
+ | 'surface'
+/** A sidecar with EVERY entry answered → apply the answers + advance. */
+ | 'apply'
+/** Nothing to do: a PENDING sidecar (awaiting human) or nothing eligible. */
+ | 'no-op'
+/** 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';
+}
+/**
+ * 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 declare function classifyTick(item: TickItem): TickClassification;
+/**
+ * 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 declare function isAdvanceable(classification: TickClassification): boolean;
+//# sourceMappingURL=advance-classify.d.ts.map

package/dist/advance-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-classify.d.ts","sourceRoot":"","sources":["../src/advance-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,cAAc,CAAC;AAG5D;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACxB,gFAAgF;IAChF,IAAI,EAAE,WAAW,CAAC;IAClB,mFAAmF;IACnF,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,kEAAkE;IAClE,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY;AAEvB,yEAAyE;AACvE,YAAY;AACd,6EAA6E;GAC3E,WAAW;AACb,qFAAqF;GACnF,oBAAoB;AAEtB,0EAA0E;GACxE,SAAS;AACX,yEAAyE;GACvE,OAAO;AAET,6EAA6E;GAC3E,OAAO;AAET,wEAAwE;GACtE,qBAAqB,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB;;;;;;;;;OASG;IACH,MAAM,CAAC,EACJ,iBAAiB,GACjB,8BAA8B,GAC9B,8BAA8B,CAAC;CAClC;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,kBAAkB,CAsC/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,kBAAkB,GAAG,OAAO,CAKzE"}

package/dist/advance-classify.js

@@ -0,0 +1,120 @@
+/**
+ * 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 { allAnswered } from './sidecar.js';
+/** The per-TYPE ANALYSE rung when there are no open questions (the no-gate path). */
+const ANALYSE_RUNG_FOR_TYPE = {
+    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) {
+    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) {
+    return (classification.kind !== 'no-op' &&
+        classification.kind !== 'invariant-violation');
+}
+//# sourceMappingURL=advance-classify.js.map

package/dist/advance-classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-classify.js","sourceRoot":"","sources":["../src/advance-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAqEzC,qFAAqF;AACrF,MAAM,qBAAqB,GAAsC;IAChE,IAAI,EAAE,YAAY;IAClB,0EAA0E;IAC1E,qCAAqC;IACrC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,oBAAoB;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IAC1C,MAAM,EAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAC,GAAG,IAAI,CAAC;IAC3C,MAAM,KAAK,GAAG,YAAY,KAAK,IAAI,CAAC;IAEpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,2EAA2E;QAC3E,oEAAoE;QACpE,qEAAqE;QACrE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;gBACN,IAAI,EAAE,qBAAqB;gBAC3B,IAAI;gBACJ,MAAM,EAAE,8BAA8B;aACtC,CAAC;QACH,CAAC;QACD,wEAAwE;QACxE,OAAO,EAAC,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAC,CAAC;IAClD,CAAC;IAED,0BAA0B;IAC1B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,6EAA6E;QAC7E,6EAA6E;QAC7E,oEAAoE;QACpE,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAC,CAAC;IAChC,CAAC;IAED,6EAA6E;IAC7E,4EAA4E;IAC5E,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,sEAAsE;QACtE,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,8EAA8E;IAC9E,gFAAgF;IAChF,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,cAAkC;IAC/D,OAAO,CACN,cAAc,CAAC,IAAI,KAAK,OAAO;QAC/B,cAAc,CAAC,IAAI,KAAK,qBAAqB,CAC7C,CAAC;AACH,CAAC"}

package/dist/advance-drivers.d.ts

@@ -0,0 +1,182 @@
+import { type AdvanceContext, type AdvanceResult, type AdvanceExitCode, type AdvanceOutcome } from './advance.js';
+import { type LedgerReadStrategy } from './ledger-read.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;
+}
+/**
+ * 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 declare function performAdvanceAuto(options: PerformAdvanceMultiOptions): Promise<AdvanceMultiResult>;
+/**
+ * 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 declare function performAdvanceArgs(args: string[], options: PerformAdvanceMultiOptions): Promise<AdvanceMultiResult>;
+/**
+ * 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 declare function runAdvanceTickWithTreelessPublish(options: AdvanceTickOptions, run: AdvanceTickRunner): Promise<AdvanceResult>;
+/**
+ * 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 declare function isCalmAtRest(result: AdvanceMultiResult): boolean;
+export type { AdvanceOutcome };
+//# sourceMappingURL=advance-drivers.d.ts.map

package/dist/advance-drivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-drivers.d.ts","sourceRoot":"","sources":["../src/advance-drivers.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,MAAM,cAAc,CAAC;AAMtB,OAAO,EAAa,KAAK,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAQrE,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAC/B,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,yEAAyE;AACzE,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC1B;AAED,sEAAsE;AACtE,KAAK,oBAAoB,GAAG,cAAc,CAAC;AAE3C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACvE;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,oFAAoF;IACpF,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAuE7B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAU7B;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,iCAAiC,CACtD,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,iBAAiB,GACpB,OAAO,CAAC,aAAa,CAAC,CAqBxB;AA+CD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAIhE;AAED,YAAY,EAAC,cAAc,EAAC,CAAC"}