dorfl 0.1.1 → 0.2.0

package/src/do-autopick.ts

@@ -1,5 +1,6 @@
 import {performDo, type DoOptions, type DoResult} from './do.js';
 import {scanRepoPaths} from './scan.js';
+import {heldTaskSlugs} from './item-lock.js';
 import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
 import {
 	selectPrioritised,
@@ -24,9 +25,9 @@ import type {ConfigOverrideMap} from './config-override.js';
  * Auto-pick / `-n` draw from TWO POOLS ordered by the configurable
  * `selectionOrder` (the shared, pure {@link selectPrioritised} helper): eligible
  * TASKS (the `build` pool — the existing `scan`/`selectCandidates`/eligibility
- * path) and TASKABLE prds (the `task` pool — built from the prd reader +
+ * path) and TASKABLE prds (the `task` pool — built from the spec reader +
  * `autoslice-gate`'s predicate), in the per-repo `selectionOrder` (default `drain`
- * = tasks-first). A selected prd dispatches to the `do prd:<slug>` path (tasking
+ * = tasks-first). A selected spec dispatches to the `do spec:<slug>` path (tasking
  * itself is `autoslice-command`, not built here).
  *
  * Explicit multi-arg (`do <a> <b>`) bypasses the pools/priority entirely — the
@@ -41,7 +42,7 @@ type SharedDoOptions = Omit<DoOptions, 'arg'>;
 
 export interface PerformDoMultiOptions extends SharedDoOptions {
 	/**
-	 * The resolved repo config (provides `autoTask` for the prd gate,
+	 * The resolved repo config (provides `autoTask` for the spec gate,
 	 * `selectionOrder` for the pool order, and the task-pool selection caps). The
 	 * per-item runs still receive `autoTask`/`integration`/etc. via the spread
 	 * `SharedDoOptions`.
@@ -62,7 +63,7 @@ export interface PerformDoMultiOptions extends SharedDoOptions {
 	count?: number;
 	/** Override the single-`do` runner (tests inject a stub). Defaults to {@link performDo}. */
 	run?: DoRunner;
-	/** Override the read seam (prd pool); defaults to the active {@link ledgerRead}. */
+	/** Override the read seam (spec pool); defaults to the active {@link ledgerRead}. */
 	read?: LedgerReadStrategy;
 }
 
@@ -85,7 +86,7 @@ export interface DoMultiResult {
  * The task-pool caps for an in-place `do` selection. `do` is per-repo +
  * sequential, so the REAL bound is the requested `count` (handled by the
  * priority helper); the task-pool selection should not truncate BEFORE the
- * count + the prd pool are combined. We therefore cap the task pool at "all
+ * count + the spec pool are combined. We therefore cap the task pool at "all
  * eligible" (a large bound) and let {@link selectPrioritised}'s `count` do the
  * trimming across both pools.
  */
@@ -105,6 +106,16 @@ export async function performDoAuto(
 	const cwd = options.cwd;
 	const count = options.count ?? 1;
 
+	// Held-slug subtraction (task
+	// `in-place-scan-subtracts-held-locked-slugs-from-propose-matrix`): read the
+	// coordination arbiter's held task-lock refs and pass them into `scanRepoPaths`
+	// so a held item (state `active`/`stuck`) does not enter the item pool NOR the
+	// lifecycle surface/apply pools. `heldTaskSlugs` is the GRACEFUL variant (empty
+	// set on any read fault): the follow-on claim CAS is still the load-bearing
+	// safety net locally — this subtraction is a courtesy that avoids selecting an
+	// item that would immediately lose its claim race.
+	const heldSlugs = await heldTaskSlugs(cwd, options.arbiter, options.env);
+
 	// Pool 1 — eligible TASKS via the EXISTING scan/select path (task-only).
 	// Thread `override` so the per-machine override is applied per repo (the
 	// inner `resolveRepoConfig` re-applies it AFTER the committed file, restoring
@@ -112,11 +123,11 @@ export async function performDoAuto(
 	const report = scanRepoPaths(
 		[cwd],
 		options.config,
-		new Set(),
+		heldSlugs,
 		options.override,
 	);
 
-	// Pool 2 — TASKABLE prds: the NEW pool from the shared prd read path
+	// Pool 2 — TASKABLE prds: the NEW pool from the shared spec read path
 	// (`resolveSpecPool`) filtered by `autoslice-gate`'s predicate (not reinvented).
 	const pool = read.resolveSpecPool({repoPath: cwd});
 	const specCandidates: SpecCandidate[] = pool.specs.map((spec) => ({
@@ -155,8 +166,8 @@ export async function performDoAuto(
 /**
  * Run the EXPLICIT multi-arg form (`do <a> <b> …`): the named items in the GIVEN
  * order (no pool/priority — the operator chose them). Each arg is run through the
- * existing `do` pipeline, which itself resolves bare/`task:`/`prd:` (so a named
- * prd dispatches to the tasking path and a collision errors), SEQUENTIALLY.
+ * existing `do` pipeline, which itself resolves bare/`task:`/`spec:` (so a named
+ * spec dispatches to the tasking path and a collision errors), SEQUENTIALLY.
  */
 export async function performDoArgs(
 	args: string[],
@@ -176,7 +187,7 @@ export async function performDoArgs(
 /**
  * Run a list of selected items through the existing `do` pipeline, SEQUENTIALLY,
  * threading the shared options to each. For the pool path the `do` arg encodes
- * the namespace (`prd:<slug>` for a selected prd, bare slug for a task); for the
+ * the namespace (`spec:<slug>` for a selected spec, bare slug for a task); for the
  * explicit-arg path the caller's raw arg is passed verbatim.
  */
 async function runSelectedInSequence(

package/src/do-config.ts

@@ -90,7 +90,7 @@ export function doFlagOverrides(
 		...surfaceBlockersFlagOverrides(flags),
 		// `--merge-questions <off|ask|auto>` rides the SAME flag-override chain
 		// (flag > env > per-repo > global > default `ask`): the 3-state gate over
-		// the merge-question SURFACER (prd `land-time-reverify-and-parallel-
+		// the merge-question SURFACER (spec `land-time-reverify-and-parallel-
 		// merge-ceiling` Story 17 / task `merge-questions-gate-axis`). SEPARATE
 		// axis from `--observation-triage` with a HIGHER default — NEVER rides
 		// `--observation-triage`.
@@ -122,7 +122,7 @@ export function doFlagOverrides(
 		// `--no-pr` (the PR-INTENT axis): suppress the PR even on an authed GitHub
 		// arbiter. Rides the SAME flag > env > per-repo > global > default chain.
 		...noPRFlagOverrides(flags),
-		// `--merge-retries <n>` (the cross-job merge serialiser's CAS-retry cap — prd
+		// `--merge-retries <n>` (the cross-job merge serialiser's CAS-retry cap — spec
 		// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer
 		// q1 (a)) rides the SAME chain (flag > env > per-repo > global > default).
 		...mergeRetriesFlagOverrides(flags),
@@ -130,7 +130,7 @@ export function doFlagOverrides(
 	if (integration !== undefined) {
 		// An explicit `--merge`/`--propose` flag ALWAYS wins for the transition this
 		// command runs. `do` runs EITHER the build transition (a task) OR the tasking
-		// transition (a `do prd:`) per invocation, and the typed flag is
+		// transition (a `do spec:`) per invocation, and the typed flag is
 		// transition-AGNOSTIC, so it must override BOTH the build mode (`integration`)
 		// AND the tasking mode (`taskingIntegration`). Setting both at the top of the
 		// precedence chain means a `--propose` on a `taskingIntegration:'merge'` repo
@@ -346,7 +346,7 @@ export function observationTriageFlagOverrides(
 /**
  * The surface-blockers CLI flag (`advance`): `--surface-blockers` /
  * `--no-surface-blockers`, the BOOLEAN gate over DECLARED blocked work (whether a
- * `needsAnswers:true` task/prd is rendered into a question sidecar; ADR
+ * `needsAnswers:true` task/spec is rendered into a question sidecar; ADR
  * `ci-config-policy-and-gate-family`). The orthogonal PEER of
  * `--observation-triage`. Resolved through the SAME
  * `flag > env > per-repo > global > default` chain as the other gate flags.
@@ -375,7 +375,7 @@ export function surfaceBlockersFlagOverrides(
 
 /**
  * **The cross-job merge-serialiser CAS-retry cap CLI flag** (`--merge-retries
- * <n>`) — prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied
+ * <n>`) — spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied
  * Answer q1 (a). The git-alone FLOOR of the cross-job land-queue; a wide-matrix
  * CI raises the cap so more contenders converge before any spurious bounce to
  * needs-attention. Offered by `do`/`run`/`complete`. Resolved through the SAME
@@ -414,7 +414,7 @@ export function mergeRetriesFlagOverrides(
 
 /**
  * The merge-questions CLI flag (`advance`): `--merge-questions <off|ask|auto>`,
- * the 3-state gate over the MERGE-QUESTION SURFACER (prd
+ * the 3-state gate over the MERGE-QUESTION SURFACER (spec
  * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
  * `merge-questions-gate-axis`). MIRRORS `--observation-triage`'s SHAPE but is a
  * SEPARATE axis with a HIGHER default (`ask`, never `off` — a dropped merge-
@@ -459,7 +459,7 @@ export function mergeQuestionsFlagOverrides(
 
 /**
  * **The strict-merge-approval CLI flag** (`--strict-merge-approval` /
- * `--no-strict-merge-approval`) — prd
+ * `--no-strict-merge-approval`) — spec
  * `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6 / task
  * `strict-merge-approval-gate`. The OPT-IN strictness layered on the OQ6
  * stale-approval default: ON re-surfaces the merge-question on a merge-base

package/src/do-remote-auto.ts

@@ -6,7 +6,7 @@ import {selectPrioritised, type SelectedItem} from './select-priority.js';
 import type {Config} from './config.js';
 
 /**
- * The MIRROR-SIDE auto-pick / `-n` caller for `do --remote` (prd `advance-loop`,
+ * The MIRROR-SIDE auto-pick / `-n` caller for `do --remote` (spec `advance-loop`,
  * task `advance-drivers-and-gates`, US #25) — the THIN caller the mirror-side
  * eligible-pool scan (`mirror-side-eligible-pool-scan`) makes possible, the
  * isolated counterpart of `do-autopick`'s in-place {@link performDoAuto}.
@@ -154,7 +154,7 @@ function remoteArgFor(item: SelectedItem): string {
  * the GIVEN order (no pool/priority — the operator chose them), each through the
  * EXISTING {@link performDoRemote} pipeline, SEQUENTIALLY. No mirror scan is
  * needed (the args are explicit); the per-item pipeline resolves each
- * bare/`task:`/`prd:` arg itself.
+ * bare/`task:`/`spec:` arg itself.
  */
 export async function performDoRemoteArgs(
 	args: string[],