dorfl 0.0.0 → 0.1.1

package/src/tasking-eligibility.ts

@@ -0,0 +1,114 @@
+/**
+ * Pure tasking-eligibility resolution — the auto-task decision layer, one level
+ * UP from the build gate (`eligibility.ts`). No I/O: callers pass in the prd's
+ * two autonomy axes (`humanOnly`, `needsAnswers`), the repo's `autoTask` policy,
+ * the prd's `taskedAfter` slugs, and the set of slugs whose prds are already
+ * TASKED (resolved against `work/prds/tasked/` residence, NOT `work/done/`).
+ *
+ * This mirrors the build-gate shape deliberately (CONTEXT.md / the `auto-slice`
+ * prd): the same `needsAnswers !== true && humanOnly !== true && <repo policy>`
+ * predicate, applied to a prd's two axes + the repo's `autoTask` toggle — and a
+ * cross-prd ordering check that resolves against tasked-ness rather than done-ness.
+ */
+
+import type {HumanOnlyGate} from './eligibility.js';
+
+export type {HumanOnlyGate};
+
+/** Resolution of a prd's `taskedAfter` against the set of already-tasked prds. */
+export interface TaskedAfterResult {
+	/** True when every listed prd is already tasked. */
+	satisfied: boolean;
+	/** Listed prd slugs not yet tasked, in declaration order. */
+	missing: string[];
+}
+
+export interface TaskingEligibilityInput {
+	/** Autonomy axis 1 (DECIDED): a human must drive THIS prd's tasking. */
+	humanOnly: HumanOnlyGate;
+	/** Autonomy axis 2 (DISCOVERED): the prd has unresolved questions. */
+	needsAnswers: HumanOnlyGate;
+	/** Cross-prd order: prd slugs that must already be tasked before this one. */
+	taskedAfter: string[];
+	/** Slugs of prds that are already TASKED (residence in `work/prds/tasked/`). */
+	taskedSlugs: Set<string>;
+	/** Per-repo policy: may an agent auto-task *undeclared* prds in this repo? */
+	autoTask: boolean;
+	/**
+	 * The target was named EXPLICITLY by the operator (`do prd:<slug>`), so the
+	 * `autoTask` POLICY is already satisfied — naming the prd IS the authorization,
+	 * exactly as `do <task>` builds a named task regardless of `autoBuild` (the
+	 * `autoBuild` precedent: the pool/scan gates the policy, the explicit claim path
+	 * never re-checks it). When `true`, the policy term drops from the gate and ONLY
+	 * the prd's own readiness axes (`humanOnly`/`needsAnswers`) + `taskedAfter` bind.
+	 * Defaults `false` (the AUTO-PICK pool path, where the `autoTask` policy DOES
+	 * gate). The pool is the single policy-enforcement point; the per-invocation gate
+	 * applies the policy only when NOT explicit.
+	 */
+	explicit?: boolean;
+}
+
+export interface TaskingEligibilityResult {
+	/** Taskable now = gate passes AND every `taskedAfter` prd is already tasked. */
+	taskable: boolean;
+	/** Whether the autonomy gate alone passes (agent-taskable on its own axes). */
+	gatePass: boolean;
+	taskedAfter: TaskedAfterResult;
+}
+
+/**
+ * Resolve the tasking autonomy gate: agent-taskable iff `needsAnswers` is not
+ * `true` AND `humanOnly` is not `true` AND the repo's `autoTask` POLICY is
+ * satisfied — where the policy is satisfied either by the repo's `autoTask`
+ * toggle being on (the AUTO-PICK pool path) OR by the target being named
+ * EXPLICITLY (`explicit: true` — `do prd:<slug>`, where naming IS the
+ * authorization, mirroring `do <task>` vs `autoBuild`). Both readiness axes
+ * block orthogonally and are never agent-taskable regardless of policy; a human
+ * is never bound by either. The exact mirror of `resolveGate` (the build gate),
+ * one level up.
+ */
+export function resolveTaskGate(
+	humanOnly: HumanOnlyGate,
+	needsAnswers: HumanOnlyGate,
+	autoTask: boolean,
+	explicit = false,
+): boolean {
+	if (needsAnswers === true || humanOnly === true) {
+		return false;
+	}
+	// EXPLICIT naming satisfies the policy term (the build path's autoBuild
+	// precedent); otherwise the repo's autoTask toggle gates the auto-pick pool.
+	return explicit || autoTask;
+}
+
+/**
+ * Resolve a prd's `taskedAfter` against the slugs of prds already TASKED (NOT
+ * `done/`): satisfied iff every listed prd is present in `taskedSlugs`. An
+ * untasked blocker ⇒ not yet taskable (so this prd's emitted tasks can
+ * reference the real slugs of those prds' tasks).
+ */
+export function resolveTaskedAfter(
+	taskedAfter: string[],
+	taskedSlugs: Set<string>,
+): TaskedAfterResult {
+	const missing = taskedAfter.filter((slug) => !taskedSlugs.has(slug));
+	return {satisfied: missing.length === 0, missing};
+}
+
+/** Combine the tasking gate and `taskedAfter` resolution into a verdict. */
+export function resolveTaskingEligibility(
+	input: TaskingEligibilityInput,
+): TaskingEligibilityResult {
+	const gatePass = resolveTaskGate(
+		input.humanOnly,
+		input.needsAnswers,
+		input.autoTask,
+		input.explicit,
+	);
+	const taskedAfter = resolveTaskedAfter(input.taskedAfter, input.taskedSlugs);
+	return {
+		taskable: gatePass && taskedAfter.satisfied,
+		gatePass,
+		taskedAfter,
+	};
+}

package/src/tasking-lock.ts

@@ -0,0 +1,416 @@
+import {runAsync, type RunResult} from './git.js';
+import {
+	acquireItemLock,
+	releaseItemLock,
+	markStuckItemLock,
+} from './item-lock.js';
+import {workItemRel} from './work-layout.js';
+
+/**
+ * The **tasking concurrency lock** (prd `auto-slice`, task `autoslice-lock`).
+ *
+ * Serialises *concurrent* taskers (two CI runs, or human + CI) so a prd is never
+ * double-tasked. As of the capstone cut-over (task
+ * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, prd
+ * `ledger-status-per-item-lock-refs`; ADR `ledger-status-on-per-item-lock-refs`)
+ * the legacy `git mv work/prds/ready/<slug>.md → work/tasking/<slug>.md` MARKER on `main`
+ * is GONE: the body NEVER relocates until the durable promotion, exactly as claim
+ * no longer moves the task body (task
+ * `cutover-claim-body-stays-and-complete-sources-from-backlog`). The tasking lock
+ * is now ONLY the UNIFIED per-item lock (`refs/dorfl/lock/<entry>`,
+ * `action: task`, keyed `prd:<slug>`) — the SAME ref claim and advance use for
+ * the same item, so tasking a prd is mutually exclusive with claiming/advancing
+ * the SAME item BY CONSTRUCTION (the second acquirer loses the SAME create-only
+ * ref CAS, with NO retry budget and NO false contention). There is no transient
+ * status in `main`'s tree anymore, so a work branch cut from `main` inherits no
+ * stale `tasking/` marker.
+ *
+ * - **Acquire** ({@link acquireTaskingLock}) acquires the unified per-item lock.
+ *   A `lost` (the item is already held for implement/task/advance) makes the
+ *   tasking acquire lose DEFINITIVELY (exit 2, no retry). On a successful acquire
+ *   it returns {@link AcquireTaskingLockResult.lockedBlob}: the git blob sha of the
+ *   prd body the lock TOOK, read from `work/prds/ready/<slug>.md` on the arbiter — the
+ *   snapshot the tasker reads + tasks from, handed back so the integrate
+ *   transition can fail loud if the held prd was edited concurrently (the
+ *   read-stability backstop). A dry-run takes no lock (it mutates nothing).
+ *
+ * - **Release** ({@link releaseTaskingLock}) DELETES the unified lock ref. It
+ *   moves NO lifecycle file: the durable `prd → prd-tasked` success move is owned
+ *   by the integrate band (`tasking.ts`/`integration-core.ts`), and there is no
+ *   `tasking/ → prd/` abort bounce anymore (the body never left `prd/`). When
+ *   `routeToNeedsAttention` is set (the tasker review/edit loop's
+ *   decomposition-unclear verdict, or the task-SET acceptance gate's `block`),
+ *   release amends the lock `active → stuck` with the reason on the entry INSTEAD
+ *   of deleting it — the per-item-lock stuck state IS the tasking needs-attention
+ *   surface now (no `work/needs-attention/` folder write), consistent with the
+ *   needs-attention cut-over (task
+ *   `cutover-needs-attention-becomes-lock-stuck-recovery-surface`). A human reads
+ *   it via `dorfl status` / `gc --ledger` and resolves via
+ *   `release-lock`/`resume`.
+ *
+ * The READ-STABILITY backstop (the content-identity stale check that used to live
+ * in the release, comparing the held `work/tasking/<slug>.md` blob against the
+ * acquire-time snapshot) now lives at the integrate seam (`tasking.ts`
+ * `heldSpecIsStale`, comparing `work/prds/ready/<slug>.md`) — relocated because the
+ * completing transition, not the release, owns the commit. See
+ * `work/notes/observations/tasking-lock-does-not-stabilise-prd-content.md`.
+ *
+ * This module provides the lock PRIMITIVES only. The orchestrating `do prd:<slug>`
+ * tasking command (`tasking.ts`) acquires, drives the agent's tasking, integrates
+ * the emitted tasks + the durable `prd → prd-tasked` move, and releases. The
+ * human path (no contention) may task on `main` directly without the lock.
+ */
+
+const DEFAULT_ARBITER = 'origin';
+
+/** A semantic label for the lock-acquire outcome (never the verdict itself). */
+export type AcquireTaskingLockOutcome =
+	| 'acquired'
+	| 'usage-error'
+	| 'lost'
+	| 'contended';
+
+/** Maps onto the claim-CAS exit codes (identical semantics). */
+export type AcquireTaskingLockExitCode = 0 | 1 | 2 | 3;
+
+export interface AcquireTaskingLockOptions {
+	/** The prd slug to lock (`work/prds/ready/<slug>.md`). */
+	slug: string;
+	/** Working clone/worktree the lock acquire runs in. */
+	cwd: string;
+	/** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
+	arbiter?: string;
+	/** Advisory locker id. Defaults to git user.name, then $USER. */
+	by?: string;
+	/** Cap on push retries when main merely advanced. Default 3. (Unified lock is retry-free; retained for API parity.) */
+	retries?: number;
+	/** Show the intended acquire without mutating the arbiter (`--dry-run`). */
+	dryRun?: boolean;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface AcquireTaskingLockResult {
+	exitCode: AcquireTaskingLockExitCode;
+	outcome: AcquireTaskingLockOutcome;
+	/** Human-readable summary of the terminal condition. */
+	message: string;
+	/**
+	 * On a successful acquire (`acquired`), the git BLOB sha of the prd body that
+	 * the lock TOOK (`work/prds/ready/<slug>.md` on the arbiter). This IS the snapshot the
+	 * tasker reads + tasks from; the integrate transition compares the current
+	 * `work/prds/ready/<slug>.md` blob against it to fail loud on a concurrent edit (the
+	 * read-stability backstop). `undefined` unless `outcome === 'acquired'` (and on
+	 * dry-run, where nothing was published).
+	 */
+	lockedBlob?: string;
+}
+
+/** Raised for usage/environment errors (exit 1). */
+class TaskingLockUsageError extends Error {}
+
+/**
+ * Acquire the tasking lock for `slug`: take the item's unified `action: task`
+ * lock (a parentless ref CAS). Never throws for the expected "lost the race"
+ * (exit 2) case — it is returned. Usage/environment problems surface as exit 1; a
+ * held lock is exit 0.
+ */
+export async function acquireTaskingLock(
+	options: AcquireTaskingLockOptions,
+): Promise<AcquireTaskingLockResult> {
+	const note = options.note ?? (() => {});
+	try {
+		return await runAcquire(options, note);
+	} catch (err) {
+		if (err instanceof TaskingLockUsageError) {
+			return {exitCode: 1, outcome: 'usage-error', message: err.message};
+		}
+		const message = err instanceof Error ? err.message : String(err);
+		return {exitCode: 1, outcome: 'usage-error', message};
+	}
+}
+
+async function runAcquire(
+	options: AcquireTaskingLockOptions,
+	note: (m: string) => void,
+): Promise<AcquireTaskingLockResult> {
+	const slug = options.slug;
+	const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+	const dryRun = options.dryRun ?? false;
+	const cwd = options.cwd;
+	const env = options.env;
+
+	if (!slug) {
+		throw new TaskingLockUsageError(
+			'missing <slug>. usage: acquireTaskingLock({slug, cwd, arbiter})',
+		);
+	}
+	if ((await gitSoft(['rev-parse', '--git-dir'], cwd, env)).status !== 0) {
+		throw new TaskingLockUsageError('not inside a git repository');
+	}
+	if ((await gitSoft(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+		throw new TaskingLockUsageError(
+			`no git remote named '${arbiter}' (set one, or pass --arbiter)`,
+		);
+	}
+	const by = options.by || (await resolveBy(cwd, env));
+
+	// Is the prd still lockable (present in work/prds/ready/ on the arbiter's main)?
+	await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+	const spec = workItemRel('specs-ready', `${slug}.md`);
+	const specBlob = await gitSoft(
+		['rev-parse', `${arbiter}/main:${spec}`],
+		cwd,
+		env,
+	);
+	if (specBlob.status !== 0) {
+		const message = `'${spec}' not found on ${arbiter}/main (no such prd, or it was already moved/tasked).`;
+		note(message);
+		return {exitCode: 2, outcome: 'lost', message};
+	}
+	const lockedBlob = specBlob.stdout.trim();
+
+	// A dry-run takes no lock (it mutates nothing) but still reports the lockable
+	// snapshot it WOULD take.
+	if (dryRun) {
+		const message = `[dry-run] would acquire the tasking lock for '${slug}' (${spec} present on ${arbiter}/main).`;
+		note(message);
+		return {exitCode: 0, outcome: 'acquired', message, lockedBlob};
+	}
+
+	// Acquire the UNIFIED per-item lock (`action: task`, keyed `prd:<slug>` so it
+	// shares the ONE ref with claim/advance of the SAME item). A create-only ref
+	// CAS: the winner holds it, the loser is DEFINITIVELY `lost` (exit 2, no retry
+	// budget). No auto-steal of an orphaned lock, consistent with claim/advance and
+	// the ADR's recovery model (no liveness heartbeat / auto-sweep; a human asserts
+	// a lock is dead via `release-lock` + `gc --ledger`).
+	// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
+	// EMIT the parent-spec item identity as `spec:<slug>` so the unified per-item
+	// lock ref is `refs/dorfl/lock/spec-<slug>` (the expand-lock task made
+	// `spec:<slug>` resolve to a `spec-<slug>` entry). The resolver still ACCEPTS
+	// `prd:<slug>`, so any lock taken under the old identity stays readable; the
+	// contract task removes the legacy form.
+	const lock = await acquireItemLock({
+		item: `spec:${slug}`,
+		action: 'task',
+		cwd,
+		arbiter,
+		holder: by,
+		env,
+	});
+	if (lock.outcome === 'error') {
+		throw new TaskingLockUsageError(
+			`failed to acquire the item lock for '${slug}': ${lock.message}`,
+		);
+	}
+	if (lock.outcome === 'lost') {
+		note(lock.message);
+		return {exitCode: 2, outcome: 'lost', message: lock.message};
+	}
+	const message = `LOCKED '${slug}' for tasking on ${arbiter} (unified lock).`;
+	note(message);
+	return {exitCode: 0, outcome: 'acquired', message, lockedBlob};
+}
+
+// --- Release --------------------------------------------------------------
+
+/** A semantic label for the lock-release outcome. */
+export type ReleaseTaskingLockOutcome =
+	| 'released'
+	| 'usage-error'
+	| 'lost'
+	| 'contended'
+	| 'stale';
+
+/** Maps onto the claim-CAS exit codes, plus `4` for a STALE (conflicting) lock. */
+export type ReleaseTaskingLockExitCode = 0 | 1 | 2 | 3 | 4;
+
+export interface ReleaseTaskingLockOptions {
+	/** The prd slug whose lock to release. */
+	slug: string;
+	/** Working clone/worktree the release runs in. */
+	cwd: string;
+	/** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
+	arbiter?: string;
+	/**
+	 * The git BLOB sha the lock TOOK ({@link AcquireTaskingLockResult.lockedBlob}).
+	 * RETAINED for API parity; the content-identity stale check now lives at the
+	 * integrate seam (`tasking.ts` `heldSpecIsStale`), which runs BEFORE the
+	 * completing commit. The release itself no longer reads the held body (there is
+	 * no `tasking/` marker), so it does not consult this.
+	 */
+	lockedBlob?: string;
+	/** Advisory releaser id. Defaults to git user.name, then $USER. */
+	by?: string;
+	/** Cap on push retries when main merely advanced. Default 3. */
+	retries?: number;
+	/**
+	 * The tasker review→edit LOOP's **decomposition-unclear** verdict
+	 * (`slicer-review-edit-loop`), or the task-SET acceptance gate's `block`:
+	 * instead of DELETING the lock (returning the prd to the claimable/taskable
+	 * pool), amend it `active → stuck` with this reason recorded on the entry,
+	 * emitting NO guessed tasks. The prd body stays in `work/prds/ready/` (it never moved
+	 * under the lock); the stuck lock IS the tasking needs-attention surface (no
+	 * `work/needs-attention/` folder write), so it is NOT re-taskable until a human
+	 * resolves it via `release-lock`/`resume`. Omitted ⇒ the normal release DELETES
+	 * the lock ref.
+	 */
+	routeToNeedsAttention?: {reason: string};
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface ReleaseTaskingLockResult {
+	exitCode: ReleaseTaskingLockExitCode;
+	outcome: ReleaseTaskingLockOutcome;
+	/** Human-readable summary of the terminal condition. */
+	message: string;
+}
+
+/**
+ * Release the tasking lock for `slug`: DELETE the unified `action: task` lock ref
+ * (idempotent — an already-absent ref is a clean `released`). It moves NO lifecycle
+ * file: the durable `prd → prd-tasked` success move is owned by the integrate band,
+ * and the prd body never left `work/prds/ready/` under the lock, so there is no
+ * `tasking/ → prd/` restore.
+ *
+ * When `routeToNeedsAttention` is set (the tasker decomposition-unclear verdict /
+ * the task-SET acceptance gate `block`), the lock is AMENDED `active → stuck`
+ * with the reason on the entry INSTEAD of deleted — the stuck per-item lock IS the
+ * tasking needs-attention surface now (no folder write).
+ *
+ * Outcomes:
+ *   - `released` (0): the lock ref is deleted (or amended stuck), the tasking is done.
+ *   - `usage-error` (1): bad input / environment / a lock-amend fault.
+ *   - `lost` (2): the lock is not held (nothing to release).
+ */
+export async function releaseTaskingLock(
+	options: ReleaseTaskingLockOptions,
+): Promise<ReleaseTaskingLockResult> {
+	const note = options.note ?? (() => {});
+	try {
+		return await runRelease(options, note);
+	} catch (err) {
+		if (err instanceof TaskingLockUsageError) {
+			return {exitCode: 1, outcome: 'usage-error', message: err.message};
+		}
+		const message = err instanceof Error ? err.message : String(err);
+		return {exitCode: 1, outcome: 'usage-error', message};
+	}
+}
+
+async function runRelease(
+	options: ReleaseTaskingLockOptions,
+	note: (m: string) => void,
+): Promise<ReleaseTaskingLockResult> {
+	const slug = options.slug;
+	const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+	const cwd = options.cwd;
+	const env = options.env;
+
+	if (!slug) {
+		throw new TaskingLockUsageError(
+			'missing <slug>. usage: releaseTaskingLock({slug, cwd, arbiter})',
+		);
+	}
+	if ((await gitSoft(['rev-parse', '--git-dir'], cwd, env)).status !== 0) {
+		throw new TaskingLockUsageError('not inside a git repository');
+	}
+	if ((await gitSoft(['remote', 'get-url', arbiter], cwd, env)).status !== 0) {
+		throw new TaskingLockUsageError(
+			`no git remote named '${arbiter}' (set one, or pass --arbiter)`,
+		);
+	}
+
+	// DECOMPOSITION-UNCLEAR / TASK-GATE BLOCK: amend the lock `active → stuck` with
+	// the reason on the entry (the tasking needs-attention surface), NOT delete it.
+	// The prd body stays in `work/prds/ready/`; the stuck lock keeps it out of the
+	// taskable pool until a human resolves it (`release-lock`/`resume`).
+	if (options.routeToNeedsAttention !== undefined) {
+		// MIGRATE: EMIT `spec:<slug>` (keyed to the `spec-<slug>` lock entry).
+		const stuck = await markStuckItemLock({
+			item: `spec:${slug}`,
+			reason: options.routeToNeedsAttention.reason,
+			cwd,
+			arbiter,
+			env,
+		});
+		if (stuck.outcome === 'transitioned' || stuck.outcome === 'wrong-state') {
+			// `wrong-state` (already stuck) is a tolerated idempotent re-surface.
+			const message = `Routed the tasking of '${slug}' to needs-attention (per-item lock marked stuck).`;
+			note(message);
+			return {exitCode: 0, outcome: 'released', message};
+		}
+		if (stuck.outcome === 'not-held') {
+			const message = `'${slug}' is not locked for tasking — nothing to mark stuck.`;
+			note(message);
+			return {exitCode: 2, outcome: 'lost', message};
+		}
+		const message = `could not mark the per-item lock for '${slug}' stuck (${stuck.outcome}: ${stuck.message}).`;
+		note(message);
+		return {exitCode: 1, outcome: 'usage-error', message};
+	}
+
+	// NORMAL release: delete the lock ref (idempotent).
+	// MIGRATE: EMIT `spec:<slug>` (keyed to the `spec-<slug>` lock entry).
+	const released = await releaseItemLock({
+		item: `spec:${slug}`,
+		cwd,
+		arbiter,
+		env,
+	});
+	if (released.outcome === 'error') {
+		throw new TaskingLockUsageError(
+			`failed to release the item lock for '${slug}': ${released.message}`,
+		);
+	}
+	const message =
+		released.outcome === 'not-held'
+			? `'${slug}' was not locked for tasking (already released).`
+			: `RELEASED the tasking lock for '${slug}' on ${arbiter}.`;
+	note(message);
+	return {exitCode: 0, outcome: 'released', message};
+}
+
+// --- Shared helpers -------------------------------------------------------
+
+/** Resolve the advisory locker: git user.name, else $USER/$USERNAME, else ''. */
+async function resolveBy(
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<string> {
+	const name = await gitSoft(['config', 'user.name'], cwd, env);
+	if (name.status === 0 && name.stdout.trim() !== '') {
+		return name.stdout.trim();
+	}
+	const e = env ?? process.env;
+	return e.USER ?? e.USERNAME ?? '';
+}
+
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<RunResult> {
+	return runAsync('git', args, cwd, {env});
+}
+
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<RunResult> {
+	const result = await runAsync('git', args, cwd, {env});
+	if (result.status !== 0) {
+		throw new Error(
+			`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`,
+		);
+	}
+	return result;
+}