dorfl 0.1.1 → 0.2.0

package/src/advance-lifecycle-template.ts

@@ -1,5 +1,5 @@
 /**
- * The `install-ci` ADVANCE-LIFECYCLE capability (prd `runner-in-ci`, task
+ * The `install-ci` ADVANCE-LIFECYCLE capability (spec `runner-in-ci`, task
  * `install-ci-advance-lifecycle-workflow`; capability C: auto-triage observations
  * + surface declared blockers + apply committed answers). This module GENERATES
  * the advance-lifecycle workflow by ABSORBING and PARAMETERISING the existing seed
@@ -43,7 +43,7 @@
  *     each leg carries `--propose` so it can NEVER merge to `main`); `merge` ⇒ ALSO
  *     a MATRIX (one leg per item; build/gate/review fan out, the LAND tail is
  *     serialised by the engine's `mergeRetries` CAS-retry loop — the git-alone
- *     floor — NOT by the workflow shape; PRD
+ *     floor — NOT by the workflow shape; SPEC
  *     `land-time-reverify-and-parallel-merge-ceiling`). This is integration-mode
  *     behaviour, IDENTICAL to the build tick (integration mode is
  *     verb-independent).
@@ -101,7 +101,7 @@ export function generateAdvanceLifecycleWorkflow(
 	const setupWith = providerSecretsWithBlock(config);
 	return `\
 # dorfl — the ADVANCE LIFECYCLE loop in CI (capability C: auto-triage
-# observations + surface declared blockers + apply committed answers, prd
+# observations + surface declared blockers + apply committed answers, spec
 # runner-in-ci). EMITTED by \`dorfl install-ci\` by PARAMETERISING the seed
 # \`docs/ci/advance-loop.yml.template\` (the advance-loop capability's output) — the
 # human commits it. DO NOT hand-edit a copy — re-run install-ci to upgrade the
@@ -127,7 +127,7 @@ export function generateAdvanceLifecycleWorkflow(
 #   * merge   ⇒ ALSO a MATRIX (one leg per item; build/gate/review fan out, the
 #               LAND tail — rebase + CAS push to \`main\` — is serialised by the
 #               engine's \`mergeRetries\` CAS-retry loop, NOT by the workflow shape.
-#               PRD \`land-time-reverify-and-parallel-merge-ceiling\`: a
+#               SPEC \`land-time-reverify-and-parallel-merge-ceiling\`: a
 #               non-fast-forward push triggers re-rebase + re-gate + retry, never
 #               a \`--force\`. The cross-job serialiser is the CAS-retry FLOOR;
 #               there is NO host-specific \`concurrency:\` group on the merge job).
@@ -284,8 +284,19 @@ jobs:
     outputs:
       items: \${{ steps.scan.outputs.items }}
       any: \${{ steps.scan.outputs.any }}
+      # Dynamic GitHub-backstop cap (spec
+      # \`graceful-pre-timeout-wip-checkpoint\`): the agent-leg jobs
+      # (advance-propose / advance-merge) read this as their
+      # \`timeout-minutes\` — replacing the retired static
+      # \`legTimeoutMinutes\`. Computed at run time from the committed
+      # \`dorfl.json\` (via \`dorfl config --json\`) as
+      # \`agentDeadlineMinutes + checkpointHeadroomMinutes\`, so an edit to
+      # \`dorfl.json\` reflects EVERYWHERE (the internal deadline the legs
+      # honour AND this GitHub cap) on the NEXT tick — no \`install-ci\`
+      # re-run, no baked-in YAML number.
+      githubTimeout: \${{ steps.timeout.outputs.githubTimeout }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup
@@ -329,6 +340,22 @@ jobs:
           else
             echo "any=false" >> "$GITHUB_OUTPUT"
           fi
+      - id: timeout
+        # Dynamic GitHub-backstop cap (spec
+        # \`graceful-pre-timeout-wip-checkpoint\` — step 5): read the committed
+        # \`dorfl.json\` via \`dorfl config --json\` (in-place, so the resolution
+        # chain reads THIS repo's file exactly like \`scan --here\`), and emit
+        # \`githubTimeout = agentDeadlineMinutes + checkpointHeadroomMinutes\` as
+        # a job OUTPUT the agent-leg jobs consume via
+        # \`timeout-minutes: \${{ needs.enumerate.outputs.githubTimeout }}\`. So
+        # the SAME committed config drives BOTH the legs' internal deadline AND
+        # this GitHub cap — edit + commit, next tick uses it for both, no
+        # \`install-ci\` re-run, no baked YAML number. \`dorfl.json\` is the
+        # single source read at run time by BOTH consumers.
+        run: |
+          cap="$(dorfl config --json \\
+            | jq '.agentDeadlineMinutes + .checkpointHeadroomMinutes')"
+          echo "githubTimeout=\${cap}" >> "$GITHUB_OUTPUT"
 
   # ── PROPOSE: a MATRIX of independent jobs (one PR per item) ──────────────────
   # True parallelism — each item is an independent PR, so a matrix is the right
@@ -340,6 +367,20 @@ jobs:
     needs: enumerate
     if: \${{ (github.event.inputs.integrationMode || 'propose') == 'propose' && needs.enumerate.outputs.any == 'true' }}
     runs-on: ubuntu-latest
+    # Per-leg wall-clock cap: the DYNAMIC GitHub backstop the enumerate job
+    # emits (spec \`graceful-pre-timeout-wip-checkpoint\`), computed at run
+    # time from the committed \`dorfl.json\` as
+    # \`agentDeadlineMinutes + checkpointHeadroomMinutes\`. It is a STRICTLY
+    # LARGER backstop than the dorfl-internal deadline the leg self-stops at
+    # (which SAVES its WIP + auto-continues on the next tick), so the GitHub
+    # SIGKILL only fires if the graceful save itself wedges. Editing
+    # \`dorfl.json\` flips BOTH the internal deadline AND this cap on the
+    # next tick — no \`install-ci\` re-run, no baked-in YAML number.
+    # A job output is always a STRING; \`timeout-minutes\` needs an INTEGER, so
+    # coerce it with \`fromJson(...)\` (the same pattern the \`item\` matrix uses).
+    # A raw \`\${{ ... }}\` substitution makes GitHub reject it ("Unexpected
+    # value '45'").
+    timeout-minutes: \${{ fromJson(needs.enumerate.outputs.githubTimeout) }}
     strategy:
       # Independent PRs: one failing item must NOT cancel the others.
       fail-fast: false
@@ -352,7 +393,7 @@ jobs:
       matrix:
         item: \${{ fromJson(needs.enumerate.outputs.items) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -389,7 +430,7 @@ jobs:
         run: dorfl advance "\${{ matrix.item }}" --propose --watch --arbiter origin
 
   # ── MERGE: a MATRIX of independent jobs (parallel build/gate/review, serialised land) ──
-  # PRD \`land-time-reverify-and-parallel-merge-ceiling\` (stories 4 + 6): each item
+  # SPEC \`land-time-reverify-and-parallel-merge-ceiling\` (stories 4 + 6): each item
   # gets its own leg; 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 the workflow shape. A non-fast-forward push triggers
@@ -403,6 +444,10 @@ jobs:
     needs: enumerate
     if: \${{ (github.event.inputs.integrationMode || 'propose') == 'merge' && needs.enumerate.outputs.any == 'true' }}
     runs-on: ubuntu-latest
+    # Per-leg wall-clock cap: the DYNAMIC GitHub backstop the enumerate job
+    # emits (see advance-propose for the rationale). \`fromJson(...)\` coerces the
+    # string job output to the INTEGER \`timeout-minutes\` requires.
+    timeout-minutes: \${{ fromJson(needs.enumerate.outputs.githubTimeout) }}
     strategy:
       # Independent landings: one failing item must NOT cancel the others; a
       # loser of the CAS race re-rebases + re-gates + retries.
@@ -413,7 +458,7 @@ jobs:
       matrix:
         item: \${{ fromJson(needs.enumerate.outputs.items) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -463,7 +508,7 @@ jobs:
     if: \${{ (github.event.inputs.sweepMergedBranches || 'true') == 'true' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup
@@ -573,7 +618,7 @@ export function validateAdvanceLifecycleWorkflow(
 		'dispatch mode).');
 
 	// --- merge ⇒ a MATRIX per item (parallel build/gate/review, serialised land) -
-	// PRD `land-time-reverify-and-parallel-merge-ceiling` stories 4 + 6: build/
+	// SPEC `land-time-reverify-and-parallel-merge-ceiling` stories 4 + 6: build/
 	// gate/review fan out; the LAND tail is serialised by the engine's
 	// `mergeRetries` CAS-retry loop (the git-alone floor), NOT the workflow.
 	require('merge-matrix', /advance-merge:[\s\S]*?strategy:\s*[\s\S]*?matrix:/.test(
@@ -690,7 +735,7 @@ export function validateAdvanceLifecycleWorkflow(
 		text,
 	), 'the `sweepMergedBranches` dispatch input (capability F, opt-out) must be ' +
 		'preserved.');
-	// The ORPHAN-SIDECAR reap (prd
+	// The ORPHAN-SIDECAR reap (spec
 	// `agentic-question-resolution-retire-disposition-vocabulary`, US #10) rides
 	// the SAME scheduled `dorfl gc --remote-branches` invocation, so it provably
 	// FIRES on the cron tick (not behind an un-passed flag). The reap step that
@@ -745,7 +790,7 @@ export function validateAdvanceLifecycleWorkflow(
 	// --- The propose `enumerate` matrix must UNION taskable prds --------------
 	// (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`): a
 	// task-only `jq` would render `DORFL_AUTO_TASK: 'true'` dead on the
-	// hourly cron — a ready ungated PRD would never become a matrix leg. The `jq`
+	// hourly cron — a ready ungated SPEC would never become a matrix leg. The `jq`
 	// must enumerate `spec:<slug>` ids from `scan --json`'s taskable-SPEC pool
 	// (`repos[].specs[]` + `cwd.repo.specs[]`) alongside the eligible-task legs.
 	require('propose-enumerates-taskable-specs', /"spec:" \+ \.slug/.test(text) &&
@@ -760,7 +805,7 @@ export function validateAdvanceLifecycleWorkflow(
 	// --- The propose `enumerate` matrix must UNION the LIFECYCLE pools ----------
 	// (`ci-propose-matrix-enumerates-lifecycle-items`): a build/task-only `jq`
 	// runs the answer-loop ONLY in merge mode — a `needsAnswers` item is
-	// `eligible:false` and untriaged observations are not in the task/prd pools at
+	// `eligible:false` and untriaged observations are not in the task/spec pools at
 	// all, so NO lifecycle rung (triage/surface/apply) ever gets a propose leg. The
 	// `jq` must enumerate the three lifecycle sub-pools from `scan --json`
 	// (`repos[].lifecycle.*` + `cwd.repo.lifecycle.*`): `triage[]` → `obs:<slug>`,
@@ -781,6 +826,46 @@ export function validateAdvanceLifecycleWorkflow(
 		'not only in merge mode ' +
 		'(`ci-propose-matrix-enumerates-lifecycle-items`).');
 
+	// --- DYNAMIC GitHub backstop (spec `graceful-pre-timeout-wip-checkpoint`) ---
+	// The agent-leg jobs (advance-propose / advance-merge) must consume the
+	// enumerate job's dynamic `githubTimeout` output, NOT a baked-in number. This
+	// closes the drift where the static `legTimeoutMinutes` render only refreshed
+	// on `install-ci` re-run; now the same committed `dorfl.json` drives BOTH the
+	// internal deadline AND the GitHub cap on every tick.
+	require('enumerate-emits-github-timeout-output', /enumerate:[\s\S]*?outputs:[\s\S]*?githubTimeout:/.test(
+		text,
+	), 'the `enumerate` job must declare a `githubTimeout` job OUTPUT (computed ' +
+		'from the committed `dorfl.json` as ' +
+		'`agentDeadlineMinutes + checkpointHeadroomMinutes`).');
+	require('enumerate-reads-dorfl-config-json', /dorfl config --json/.test(
+		text,
+	), 'the `enumerate` job must read the committed config via ' +
+		'`dorfl config --json` at run time (so an edit to `dorfl.json` ' +
+		'reflects on the next tick without an `install-ci` re-run).');
+	require('enumerate-computes-deadline-plus-headroom', /agentDeadlineMinutes \+ checkpointHeadroomMinutes/.test(
+		text,
+	), 'the `enumerate` job must compute `githubTimeout` as ' +
+		'`agentDeadlineMinutes + checkpointHeadroomMinutes` (the backstop is ' +
+		'DELIBERATELY head-room above the internal deadline).');
+	require('propose-uses-dynamic-github-timeout', /advance-propose:[\s\S]*?timeout-minutes:\s*\$\{\{\s*fromJson\(needs\.enumerate\.outputs\.githubTimeout\)\s*\}\}/.test(
+		text,
+	), 'the `advance-propose` job must set `timeout-minutes: ${{ ' +
+		'fromJson(needs.enumerate.outputs.githubTimeout) }}` (the DYNAMIC GitHub ' +
+		'backstop, fromJson-coerced to an integer, not a baked-in number).');
+	require('merge-uses-dynamic-github-timeout', /advance-merge:[\s\S]*?timeout-minutes:\s*\$\{\{\s*fromJson\(needs\.enumerate\.outputs\.githubTimeout\)\s*\}\}/.test(
+		text,
+	), 'the `advance-merge` job must set `timeout-minutes: ${{ ' +
+		'fromJson(needs.enumerate.outputs.githubTimeout) }}` (the DYNAMIC GitHub ' +
+		'backstop, fromJson-coerced to an integer).');
+	// A baked static `timeout-minutes: <number>` on an agent-leg job is the
+	// retired `legTimeoutMinutes` render — forbid it so a future edit cannot
+	// silently re-introduce the drift the dynamic backstop is fixing.
+	require('no-static-agent-leg-timeout', !/(?:advance-propose|advance-merge):[\s\S]*?timeout-minutes:\s*\d/.test(
+		text,
+	), 'no agent-leg job may set a baked-in numeric `timeout-minutes` ' +
+		'(the retired `legTimeoutMinutes` render); the GitHub backstop is ' +
+		'DYNAMIC (read from `dorfl.json` at run time).');
+
 	// --- Wires the SHARED composite setup action -------------------------------
 	require('uses-shared-setup-action', /uses:\s*\.\/\.github\/actions\/dorfl-setup\b/.test(
 		text,

package/src/advance-loop-driver.ts

@@ -26,7 +26,7 @@ import type {
 } from './run.js';
 
 /**
- * The **`advance` LOOP DRIVER** (prd `advance-loop`, task
+ * The **`advance` LOOP DRIVER** (spec `advance-loop`, task
  * `advance-drivers-and-gates`, US #7/22/26/31) — the second of the two drivers
  * over the substrate-agnostic advance TICK. Where the one-shot driver
  * (`advance-drivers.ts`) runs the tick over named item(s) SEQUENTIALLY, this
@@ -113,7 +113,7 @@ export interface AdvanceOnceOptions {
 
 /** One advanced item's result + the identity it was for (input order preserved). */
 export interface AdvanceBatchItem {
-	/** The namespaced arg the tick was run on (`prd:<slug>` / bare slug). */
+	/** The namespaced arg the tick was run on (`spec:<slug>` / bare slug). */
 	arg: string;
 	/** The tick's result, or a captured throw mapped to a usage-error result. */
 	result: AdvanceResult;
@@ -549,7 +549,7 @@ export interface AdvanceRunTickDeps extends Omit<
  * Adapt the {@link advanceOnce} LOOP DRIVER to the {@link RunTick} swap SEAM so
  * `run` (≡ CI, US #7) drives the ADVANCE tick over the mirror-side eligible pool
  * instead of the build tick. `run.ts` deliberately writes {@link runLoop} against
- * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop prd can
+ * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop spec can
  * swap the tick WITHOUT re-architecting the loop — this is that swap.
  *
  * The seam is `(RunOnceOptions) => Promise<RunOnceResult>`; one advance batch is

package/src/advance-treeless-publish.ts

@@ -34,7 +34,7 @@ import {runAsync} from './git.js';
  *
  * **C2 rebase-until-real-conflict (task `c2-rebase-until-real-on-durable-main-
  * promotions`).** This same `HEAD:main` push carries the won't-proceed terminal
- * `tasks/ready → tasks/cancelled` / `prds/ready → prds/dropped` (slug-RELOCATION
+ * `tasks/ready → tasks/cancelled` / `specs/ready → specs/dropped` (slug-RELOCATION
  * family) when `apply-persist.ts` resolves a `dropped` disposition; under sustained
  * parallel load on the shared `main` ref two DIFFERENT items' concurrent promotions
  * can falsely-contend even though nothing tree-conflicts, exhausting a small fixed
@@ -92,6 +92,31 @@ export interface PushTreelessResultParams {
  */
 export const DEFAULT_TREELESS_JITTER_MS = 25;
 
+/**
+ * Stderr signatures of a PERMANENT push rejection that NO re-fetch+rebase can
+ * ever cure, so the retry loop MUST stop at once instead of burning the whole
+ * liveness ceiling ({@link PushTreelessResultParams.retries}, `1000` in prod) on
+ * identical round-trips.
+ *
+ * The tree-less rungs publish by a DIRECT `git push HEAD:main` of a freshly-made
+ * commit (see the module header). If the arbiter's `main` hard-requires a status
+ * check on EVERY push (GitHub classic branch protection with a non-empty
+ * `required_status_checks.contexts`, or a `pre-receive`/ruleset hook), that fresh
+ * commit is rejected with `GH006 ... Required status check "..." is expected` /
+ * `protected branch hook declined` / `pre-receive hook declined`. A rebase onto
+ * the newest `main` does NOT change the fact that the pushed commit has no green
+ * check, so retrying is pointless: the push is rejected identically every time.
+ *
+ * This is DISTINCT from a fast-forward RACE (`non-fast-forward` / `fetch first` /
+ * `stale info`), which a rebase DOES cure — and it must win OVER the broad
+ * `rejected` contention alternation, because a protected-branch rejection
+ * literally contains the word `rejected` (`! [remote rejected] HEAD -> main
+ * (protected branch hook declined)`) and would otherwise be mis-read as a race
+ * and retried uselessly. See the observation trail for the live incident.
+ */
+export const PERMANENT_PUSH_REJECTION =
+	/GH006|protected branch|hook declined|required status check|cannot force-update the branch/i;
+
 function sleepMs(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -118,6 +143,26 @@ export async function pushTreelessResult(
 		if (push.status === 0) {
 			return;
 		}
+		// A PERMANENT rejection (branch protection / required status check / a
+		// pre-receive or ruleset hook) can NEVER be cured by a rebase+re-push — the
+		// fresh commit still carries no green check — so stop AT ONCE with an honest,
+		// distinct note instead of exhausting the liveness ceiling on identical
+		// round-trips. This MUST be checked before `contended`, because a protected-
+		// branch rejection contains the word `rejected` and would otherwise be
+		// mistaken for a fast-forward race and retried uselessly (see the incident
+		// observation).
+		if (PERMANENT_PUSH_REJECTION.test(push.stderr)) {
+			note(
+				`advance: the arbiter's \`main\` rejected the direct tree-less push ` +
+					`(${push.stderr.trim() || 'protected branch'}); a re-fetch+rebase cannot ` +
+					`cure a required-status-check / protected-branch rule on a direct push, so ` +
+					`the work is saved in the working clone for the next pass / a human. ` +
+					`Reconcile \`main\`'s protection so direct tree-less ledger writes are ` +
+					`allowed (the required check belongs in a ruleset with ` +
+					`\`do_not_enforce_on_create\`, not the classic on-every-push gate).`,
+			);
+			return;
+		}
 		const contended = /non-fast-forward|rejected|fetch first|stale info/i.test(
 			push.stderr,
 		);