dorfl 0.1.1 → 0.2.0

package/dist/work-layout.d.ts

@@ -3,7 +3,7 @@
  * folder-name union/array, the item-scan predicate, and the prefix-task helpers
  * used across `src/`.
  *
- * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` prd — the de-risking
+ * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` spec — the de-risking
  * checkpoint. EVERY raw work-path literal (`join(cwd, 'work', ...)`, `'work/<folder>'`,
  * `'work/<folder>/'.length` prefix-tasks) and EVERY folder-name union/array that
  * used to be scattered across ~70 files now routes through here. The NAMES are
@@ -14,7 +14,7 @@
  * {@link WORK_FOLDER_NAME} (and `git mv` the on-disk folders) and NOTHING ELSE.
  * Call sites reference folders by their SYMBOLIC key (`'tasks-ready'`,
  * `'specs-ready'`, …), never by a raw string, so a folder-VALUE flip never
- * re-touches a single call site (a KEY rename, e.g. the prd→spec cutover below,
+ * re-touches a single call site (a KEY rename, e.g. the spec→spec cutover below,
  * is a mechanical relabel of the key literal at each site — behaviour-preserving).
  *
  * Domain note (crown-jewel invariant): a `work/` tree is a set of governance
@@ -61,17 +61,19 @@ export declare const WORK_ROOT: "work";
  *     and `needs-attention` (both are really lock-ref state, NOT durable folders;
  *     routed here only so no reader hand-writes the literal).
  *
- * NOTE on the prd→spec vocabulary cutover
+ * NOTE on the spec→spec vocabulary cutover
  * (`rename-spec-work-layout-and-folders`, migrate-batch 1 of
  * `prd-to-spec-vocabulary-cutover-and-migration-command`): the spec-regime KEYS
  * below now read in the `spec` vocabulary (`specs-proposed`/`specs-ready`/
  * `specs-tasked`/`specs-dropped`) AND their VALUES flip to `work/specs/*` in
- * lockstep with the on-disk `git mv work/prds/* → work/specs/*`. Unlike the earlier
+ * lockstep with the on-disk `git mv work/specs/* → work/specs/*`. Unlike the earlier
  * key-only relabel, this batch moves the folders too, so the KEY and VALUE change
  * together and the self-renaming-folder guard stays green. The KEY rename is a
  * mechanical relabel of the key literal at each call site (behaviour-preserving);
- * the frontmatter `prd:` field (a DATA alias the migration command converts) is the
- * one deliberate survivor; the `--specs-land-in` flag/`specsLandIn` config + the
+ * the legacy frontmatter ''prd:'' field survives ONLY as un-migrated on-disk DATA the
+ * `dorfl prd-to-spec` command textually converts to `spec:` (HARD CUTOVER: it is no
+ * longer READ by `parseFrontmatter` — `spec:` is the only read key); the
+ * `--specs-land-in` flag/`specsLandIn` config + the
  * `Spec*` symbols were completed by the later batches + the contract task. The
  * folder-as-status invariant is unchanged.
  */
@@ -153,7 +155,7 @@ export declare function isWorkItemFile(name: string): boolean;
  * order: `in-progress` over `tasks-ready`, with `done` appended only behind the
  * stranded-continue gate. Order is load-bearing — kept exactly as the original
  * union/array. (`tasks-backlog` is NOT in this DEFAULT order: it is appended at
- * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, prd
+ * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion` — see
  * {@link TaskResolutionFolder}.)
  */
@@ -169,9 +171,13 @@ export type TaskResolutionFolder = (typeof TASK_RESOLUTION_FOLDERS)[number] | 't
 /**
  * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
  * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
- * `needs-attention`, `done`.
+ * `done`. `needs-attention` was dropped post-cutover
+ * (`finish-needs-attention-folder-cutover-remove-legacy-recovery-readers`, ratified
+ * in `docs/adr/needs-attention-folder-cutover-followup-nits.md`): the folder is
+ * retired — a stuck item is the per-item lock `state: stuck` with the body resting
+ * in `tasks/ready/`, so no task ever resides in `work/needs-attention/`.
  */
-export declare const TASK_LIFECYCLE_FOLDERS: readonly ["tasks-ready", "in-progress", "needs-attention", "done"];
+export declare const TASK_LIFECYCLE_FOLDERS: readonly ["tasks-ready", "in-progress", "done"];
 /** One of the task lifecycle folders (spec-complete.ts / close-job.ts). */
 export type TaskLifecycleFolder = (typeof TASK_LIFECYCLE_FOLDERS)[number];
 /**

package/dist/work-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-layout.d.ts","sourceRoot":"","sources":["../src/work-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAG,MAAe,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACnB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,iDAIS,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,GACxC,eAAe,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,oEAKU,CAAC;AAE9C,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,+CAIW,CAAC;AAE9C,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,0CAGoB,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"work-layout.d.ts","sourceRoot":"","sources":["../src/work-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAG,MAAe,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACnB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,iDAIS,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,GACxC,eAAe,CAAC;AAEnB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,iDAIU,CAAC;AAE9C,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,+CAIW,CAAC;AAE9C,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,0CAGoB,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/work-layout.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
  * folder-name union/array, the item-scan predicate, and the prefix-task helpers
  * used across `src/`.
  *
- * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` prd — the de-risking
+ * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` spec — the de-risking
  * checkpoint. EVERY raw work-path literal (`join(cwd, 'work', ...)`, `'work/<folder>'`,
  * `'work/<folder>/'.length` prefix-tasks) and EVERY folder-name union/array that
  * used to be scattered across ~70 files now routes through here. The NAMES are
@@ -15,7 +15,7 @@ import { join } from 'node:path';
  * {@link WORK_FOLDER_NAME} (and `git mv` the on-disk folders) and NOTHING ELSE.
  * Call sites reference folders by their SYMBOLIC key (`'tasks-ready'`,
  * `'specs-ready'`, …), never by a raw string, so a folder-VALUE flip never
- * re-touches a single call site (a KEY rename, e.g. the prd→spec cutover below,
+ * re-touches a single call site (a KEY rename, e.g. the spec→spec cutover below,
  * is a mechanical relabel of the key literal at each site — behaviour-preserving).
  *
  * Domain note (crown-jewel invariant): a `work/` tree is a set of governance
@@ -62,17 +62,19 @@ export const WORK_ROOT = 'work';
  *     and `needs-attention` (both are really lock-ref state, NOT durable folders;
  *     routed here only so no reader hand-writes the literal).
  *
- * NOTE on the prd→spec vocabulary cutover
+ * NOTE on the spec→spec vocabulary cutover
  * (`rename-spec-work-layout-and-folders`, migrate-batch 1 of
  * `prd-to-spec-vocabulary-cutover-and-migration-command`): the spec-regime KEYS
  * below now read in the `spec` vocabulary (`specs-proposed`/`specs-ready`/
  * `specs-tasked`/`specs-dropped`) AND their VALUES flip to `work/specs/*` in
- * lockstep with the on-disk `git mv work/prds/* → work/specs/*`. Unlike the earlier
+ * lockstep with the on-disk `git mv work/specs/* → work/specs/*`. Unlike the earlier
  * key-only relabel, this batch moves the folders too, so the KEY and VALUE change
  * together and the self-renaming-folder guard stays green. The KEY rename is a
  * mechanical relabel of the key literal at each call site (behaviour-preserving);
- * the frontmatter `prd:` field (a DATA alias the migration command converts) is the
- * one deliberate survivor; the `--specs-land-in` flag/`specsLandIn` config + the
+ * the legacy frontmatter ''prd:'' field survives ONLY as un-migrated on-disk DATA the
+ * `dorfl prd-to-spec` command textually converts to `spec:` (HARD CUTOVER: it is no
+ * longer READ by `parseFrontmatter` — `spec:` is the only read key); the
+ * `--specs-land-in` flag/`specsLandIn` config + the
  * `Spec*` symbols were completed by the later batches + the contract task. The
  * folder-as-status invariant is unchanged.
  */
@@ -170,7 +172,7 @@ export function isWorkItemFile(name) {
  * order: `in-progress` over `tasks-ready`, with `done` appended only behind the
  * stranded-continue gate. Order is load-bearing — kept exactly as the original
  * union/array. (`tasks-backlog` is NOT in this DEFAULT order: it is appended at
- * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, prd
+ * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion` — see
  * {@link TaskResolutionFolder}.)
  */
@@ -182,12 +184,15 @@ export const TASK_RESOLUTION_FOLDERS = [
 /**
  * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
  * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
- * `needs-attention`, `done`.
+ * `done`. `needs-attention` was dropped post-cutover
+ * (`finish-needs-attention-folder-cutover-remove-legacy-recovery-readers`, ratified
+ * in `docs/adr/needs-attention-folder-cutover-followup-nits.md`): the folder is
+ * retired — a stuck item is the per-item lock `state: stuck` with the body resting
+ * in `tasks/ready/`, so no task ever resides in `work/needs-attention/`.
  */
 export const TASK_LIFECYCLE_FOLDERS = [
     'tasks-ready',
     'in-progress',
-    'needs-attention',
     'done',
 ];
 /**

package/dist/work-layout.js.map

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

package/dist/workspace.d.ts

@@ -113,8 +113,8 @@ export interface CreateJobOptions {
     /** The work slug being processed (→ branch `work/<type>-<slug>` + work-id). */
     slug: string;
     /**
-     * The item TYPE — `'task'` (build) or `'prd'` (tasking) — namespacing the
-     * work branch via {@link workBranchRef} so a same-slug task and prd never
+     * The item TYPE — `'task'` (build) or `'spec'` (tasking) — namespacing the
+     * work branch via {@link workBranchRef} so a same-slug task and spec never
      * collide. Defaults to `'task'`.
      */
     type?: SlugNamespace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dorfl",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wighawag/dorfl.git",
@@ -39,7 +39,7 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "tsc && node scripts/vendor-protocol.mjs",
+    "build": "tsc && node scripts/vendor-protocol.mjs && node scripts/vendor-skills.mjs",
     "dev": "as-soon -w src pnpm build",
     "cli": "tsx src/cli.ts",
     "test": "vitest run",

package/src/advance-ci-template.ts

@@ -3,7 +3,7 @@ import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 /**
- * The CI-integration deliverable for the `advance` loop (prd `advance-loop`,
+ * The CI-integration deliverable for the `advance` loop (spec `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
@@ -11,8 +11,8 @@ import {fileURLToPath} from 'node:url';
  * `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
+ * adapter) is owned by the separate `runner-in-ci` spec
+ * (`work/specs/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").
@@ -136,7 +136,7 @@ export function validateAdvanceCiTemplate(
 	// 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
+	// cron — a ready ungated SPEC 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) &&

package/src/advance-classify.ts

@@ -1,5 +1,5 @@
 /**
- * The pure `advance` TICK classifier (prd `advance-loop`, task
+ * The pure `advance` TICK classifier (spec `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
@@ -15,7 +15,7 @@
  *
  *   needsAnswers: true?
  *   ├─ NO  → ANALYSE (state-appropriate rung: build a ready task / task a ready
- *   │        prd / triage an untriaged observation). Analysis MAY advance, OR
+ *   │        spec / triage an untriaged observation). Analysis MAY advance, OR
  *   │        SURFACE questions.
  *   └─ YES → sidecar exists?
  *            ├─ NO  → ANALYSE (first pass: generate questions → write the sidecar)
@@ -39,7 +39,7 @@
  *
  * "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),
+ * of the spec'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.
@@ -56,7 +56,7 @@ import {allAnswered} from './sidecar.js';
  * never a third state store.
  */
 export interface TickItem {
-	/** The item type — the state machine is per-TYPE (task / prd / observation). */
+	/** The item type — the state machine is per-TYPE (task / spec / observation). */
 	type: SidecarType;
 	/** Autonomy axis 2 (DISCOVERED): `true` ⇒ open questions block autonomous work. */
 	needsAnswers: boolean | undefined;
@@ -128,7 +128,7 @@ const ANALYSE_RUNG_FOR_TYPE: Record<SidecarType, TickRungKind> = {
  * 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:
+ * spec's per-item state machine, with invariant 1 asserted at the boundary:
  *
  *   - `needsAnswers` NOT true:
  *       - a sidecar present ⇒ INVARIANT 1 BROKEN (`sidecar-without-needsAnswers`)

package/src/advance-drivers.ts

@@ -10,6 +10,7 @@ import {
 	TREELESS_RUNGS,
 } from './advance-treeless-publish.js';
 import {scanRepoPaths} from './scan.js';
+import {heldTaskSlugs} from './item-lock.js';
 import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
 import {
 	selectPrioritised,
@@ -23,7 +24,7 @@ import type {Config} from './config.js';
 import type {ConfigOverrideMap} from './config-override.js';
 
 /**
- * The **`advance` one-shot DRIVER** (prd `advance-loop`, task
+ * The **`advance` one-shot DRIVER** (spec `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
@@ -49,7 +50,7 @@ import type {ConfigOverrideMap} from './config-override.js';
  *
  * **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
+ * when `autoBuild` is on and a task-a-spec 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
@@ -61,7 +62,7 @@ import type {ConfigOverrideMap} from './config-override.js';
  *
  * **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
+ * consumes (which orchestrates `do`/`do spec:` through the isolation-strategy seam
  * and rebase-before-integrate); a chain conflict routes to needs-attention as
  * today, inside the orchestrated `do`.
  */
@@ -83,7 +84,7 @@ 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
+	 * task pool), `autoTask` (the task-a-spec gate for the spec 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).
@@ -105,7 +106,7 @@ export interface PerformAdvanceMultiOptions extends SharedAdvanceContext {
 	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}. */
+	/** Override the read seam (spec pool); defaults to the active {@link ledgerRead}. */
 	read?: LedgerReadStrategy;
 	/**
 	 * The LIFECYCLE-POOL create-gates (task `advance-autopick-lifecycle-pools`),
@@ -168,6 +169,15 @@ export async function performAdvanceAuto(
 	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 (`active`/`stuck`) is not selected into the build pool NOR the
+	// lifecycle surface/apply pools — the same subtraction the CI enumerate path
+	// runs. `heldTaskSlugs` is the GRACEFUL variant (empty set on any read fault):
+	// the follow-on claim CAS is still the load-bearing safety net locally.
+	const heldSlugs = await heldTaskSlugs(cwd, options.arbiter);
+
 	// 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
@@ -175,12 +185,12 @@ export async function performAdvanceAuto(
 	const report = scanRepoPaths(
 		[cwd],
 		options.config,
-		new Set(),
+		heldSlugs,
 		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
+	// `autoTask`). With `autoTask` off NO spec 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) => ({
@@ -206,6 +216,9 @@ export async function performAdvanceAuto(
 		repoPath: cwd,
 		read,
 		gates: options.lifecycleGates,
+		// Subtract held task slugs from the triage/surface/apply candidate inputs,
+		// symmetric to Pool 1's `scoreItems` subtraction above.
+		heldSlugs,
 	});
 
 	// Order across the (up to) FIVE pools per the resolved `selectionOrder` (apply
@@ -237,8 +250,8 @@ export async function performAdvanceAuto(
 /**
  * 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
+ * through the existing advance tick, which itself resolves bare/`task:`/`spec:`/
+ * `obs:` (so a named spec 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.
  */
@@ -251,7 +264,7 @@ export async function performAdvanceArgs(
 		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.
+		// across task/spec/observation); the namespace is irrelevant for explicit args.
 		namespace: 'task' as const,
 	}));
 	return runSelectedInSequence(selected, options, run, {verbatimArg: true});
@@ -260,7 +273,7 @@ export async function performAdvanceArgs(
 /**
  * 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,
+ * the pool path the arg encodes 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. Each tick is INDEPENDENTLY `advancing`-lock-guarded inside
  * {@link performAdvance} — sequential here means one item at a time, never a
@@ -321,7 +334,7 @@ async function runSelectedInSequence(
  * 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`)
+ * `apply` rung whose agentic verdict mints an artifact (`mint-task`/`mint-spec`)
  * 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.
@@ -363,7 +376,7 @@ export async function runAdvanceTickWithTreelessPublish(
  *     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
+ * The tick re-classifies each arg, so a `needsAnswers`-blocked task/spec reaches
  * surface/apply and an untriaged observation reaches triage — the classifier +
  * rung bodies are unchanged; only this selection->arg mapping is new.
  */

package/src/advance-isolated.ts

@@ -21,7 +21,7 @@ import type {Config} from './config.js';
 import type {AdvanceTickRunner, AdvanceMultiResult} from './advance-drivers.js';
 
 /**
- * The **ISOLATED advance-tick RUNNER** + its sequential drivers (prd
+ * The **ISOLATED advance-tick RUNNER** + its sequential drivers (spec
  * `advance-loop`, task `advance-isolated-one-shot`, US #25/26) — the "isolated
  * one-shot" cell `advance` was missing. It gives `advance` the SAME isolation
  * ergonomic `do --isolated` has: run the advance TICK ({@link performAdvance}) in
@@ -83,7 +83,7 @@ export interface IsolatedAdvanceContext extends Omit<AdvanceContext, 'cwd'> {
 
 /** Options for {@link performAdvanceIsolated} — the per-item isolated tick. */
 export interface PerformAdvanceIsolatedOptions extends IsolatedAdvanceContext {
-	/** The raw advance arg: bare (= task), `prd:<slug>`, or `obs:<slug>`. */
+	/** The raw advance arg: bare (= task), `spec:<slug>`, or `obs:<slug>`. */
 	arg: string;
 	/** The read seam (slug resolution / pool); defaults to {@link ledgerRead}. */
 	read?: LedgerReadStrategy;
@@ -373,7 +373,7 @@ export async function performAdvanceIsolatedAuto(
  * Run the EXPLICIT multi-arg form (`advance --isolated <a> <b> …`): the NAMED items
  * in the GIVEN order (no pool/priority — the operator chose them), each through the
  * ISOLATED advance-tick runner, SEQUENTIALLY. No mirror scan is needed (the args
- * are explicit); the per-item tick resolves each bare/`prd:`/`obs:` arg itself.
+ * are explicit); the per-item tick resolves each bare/`spec:`/`obs:` arg itself.
  */
 export async function performAdvanceIsolatedArgs(
 	args: string[],