dorfl 0.1.2 → 0.2.1

package/src/tasking.ts

@@ -53,7 +53,7 @@ import type {ReviewGate} from './review-gate.js';
  * (`tasking-eligibility.ts`) and the tasking LOCK (`tasking-lock.ts`) together to
  * task a spec into `work/tasks/backlog/` STAGED items (task
  * `pre-backlog-staging-folder-and-promote-step-a` — the runner-owned promotion
- * moves them `pre-backlog/ → backlog/` later), with the RUNNER owning every git-state
+ * moves them `tasks/backlog/ → tasks/ready/` later), with the RUNNER owning every git-state
  * transition. This is the spec branch of the `do` worker (ADR
  * `command-surface-and-journeys.md` §3/§3a), NOT a standalone `task` command;
  * `do.ts` dispatches `resolved.namespace === 'spec'` here.
@@ -244,6 +244,18 @@ export interface PerformTaskOptions {
 	 * loop's {@link taskerLoopModel} — see the note there.
 	 */
 	acceptanceReviewModel?: string;
+	/**
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
+	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
+	 * (a)). Threaded VERBATIM into {@link performIntegration} so a wide-matrix CI's
+	 * raised cap actually reaches the cross-job land queue (the CAS loop IS the
+	 * queue across separate jobs) on the `do spec:<slug>` tasking-transition path
+	 * too. Resolved ONCE at the entry point through the gate-family precedence chain
+	 * (flag > env > per-repo > global > default), same as `complete`/`do`/`run`.
+	 * Unset ⇒ falls through to the engine's `DEFAULT_MERGE_RETRIES = 1000`
+	 * (byte-for-byte unchanged).
+	 */
+	mergeRetries?: number;
 	/** Injectable lock seam (tests stub acquire/release). Defaults to the real CAS. */
 	lock?: TaskingLockSeam;
 	/**
@@ -255,10 +267,10 @@ export interface PerformTaskOptions {
 	 * resolver (`src/placement.ts`). The resolver overlays an EXPLICIT operator
 	 * flag ({@link explicitTasksLandIn}, top) and the UNTRUSTED-ORIGIN force
 	 * (`originTrust: untrusted` ⇒ staging) on top. Unset ⇒ the resolver's
-	 * built-in floor applies (`staging` = `pre-backlog/`, the conservative
+	 * built-in floor applies (`staging` = `tasks/backlog/`, the conservative
 	 * landing that preserves zero behaviour change for the normal path).
 	 */
-	tasksLandIn?: 'pre-backlog' | 'ready';
+	tasksLandIn?: 'backlog' | 'ready';
 	/**
 	 * **The OPERATOR's EXPLICIT task-placement override** (the TOP precedence
 	 * rung). When set, the runner-deterministic resolver lands the tasks HERE
@@ -268,7 +280,7 @@ export interface PerformTaskOptions {
 	 * force-key"). Set ONLY when the operator typed `--tasks-land-in <where>`;
 	 * never when the value came from config.
 	 */
-	explicitTasksLandIn?: 'pre-backlog' | 'ready';
+	explicitTasksLandIn?: 'backlog' | 'ready';
 	/**
 	 * **The tasker review→edit→converge LOOP** (`slicer-review-edit-loop`, GATES spec
 	 * `work/specs/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A). When
@@ -322,10 +334,10 @@ const DEFAULT_ARBITER = 'origin';
  * task `pre-backlog-staging-folder-and-promote-step-a`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). The runner
  * lands the tasker's emitted task files HERE, NOT in `work/tasks/ready/`: an item
- * born in `pre-backlog/` is durable + readable but NOT in the agent-eligible
+ * born in `tasks/backlog/` is durable + readable but NOT in the agent-eligible
  * pool (`work/tasks/ready/` STILL means the pool — every reader is byte-for-byte
  * unchanged). A runner/human-owned promotion (`promoteFromPreBacklog` in
- * `needs-attention.ts`) moves an approved item `pre-backlog/ → backlog/` to make
+ * `needs-attention.ts`) moves an approved item `tasks/backlog/ → tasks/ready/` to make
  * it claimable. STEP A: ADDITIVE — no `work/tasks/ready/` reader changes here.
  */
 export const STAGED_TASKS_DIR = workFolderRel('tasks-backlog');
@@ -348,17 +360,19 @@ const TASK_PLACEMENT_SLOTS = {
 } as const;
 
 /**
- * Map the `tasksLandIn` value spelling (`pre-backlog` | `ready`) onto the
+ * Map the `tasksLandIn` value spelling (`backlog` | `ready`) onto the
  * resolver's lifecycle-generic side enum (`staging` | `pool`). Returns
  * `undefined` when no value is set, so the resolver's next precedence rung
- * applies (the built-in floor). The legacy `'backlog'`/`'todo'` pool spellings
- * are NOT accepted (clean break — the value was renamed `'backlog'` → `'todo'`
- * → `'ready'`, ADR `rename-task-pool-folder-todo-to-ready`).
+ * applies (the built-in floor). The legacy `'pre-backlog'`/`'todo'` spellings
+ * are NOT accepted (clean break — the staging value was renamed
+ * `'pre-backlog'` → `'backlog'`, and the pool value was renamed
+ * `'backlog'` → `'todo'` → `'ready'`, ADR
+ * `rename-task-pool-folder-todo-to-ready`).
  */
 function landingToSide(
-	landing: 'pre-backlog' | 'ready' | undefined,
+	landing: 'backlog' | 'ready' | undefined,
 ): 'staging' | 'pool' | undefined {
-	if (landing === 'pre-backlog') return 'staging';
+	if (landing === 'backlog') return 'staging';
 	if (landing === 'ready') return 'pool';
 	return undefined;
 }
@@ -661,6 +675,12 @@ export async function performTask(
 			reviewGate: options.reviewGate,
 			reviewModel: options.acceptanceReviewModel,
 			reviewMaxRounds: 1,
+			// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
+			// threaded so a wide-matrix CI's raised cap reaches the tasking-
+			// transition's land tail too (task
+			// `thread-merge-retries-cross-task-and-ratify-default`). Unset ⇒ falls
+			// through to the engine default (byte-for-byte unchanged).
+			mergeRetries: options.mergeRetries,
 			// The EXPLICITLY-chosen integrate mode proceeds AS-IS on an APPROVE — a
 			// `--merge` tasking run lands on main, `--propose` opens a PR. The tasking
 			// path's merge-vs-propose decision is the `integration` mode the user typed;
@@ -670,6 +690,17 @@ export async function performTask(
 			mode: options.integration ?? 'propose',
 			noPR: options.noPR,
 			providerInstance: options.providerInstance,
+			// PROPOSE-MODE PR BODY (task `slicing-pr-body-summary-threading`): mirror the
+			// BUILD path's body threading (`do.ts` — `body: agent.output`). The tasker
+			// agent produces no `LaunchResult.output` we can carry, but the slice-SET
+			// itself is a summary-worthy artifact: the emitted task slugs+titles, their
+			// coverage of the spec's user stories, the dependency graph (keystone +
+			// blockedBy edges), and any `needsAnswers` open questions the tasker review
+			// loop flagged. Compose it here and thread it into the shared core as `body`
+			// so the propose-mode PR carries the summary instead of degrading to
+			// `gh pr create --fill`. Empty-set (no emitted tasks) ⇒ undefined ⇒ the
+			// provider's `--fill` fallback (no regression on that edge).
+			body: composeTaskingProposeBody(slug, emitTasks),
 			type: 'tasking',
 			lifecycle: {
 				// Read the PR title / commit summary from the held spec (before it moves).
@@ -1058,7 +1089,7 @@ async function stageTaskingLifecycle(params: {
  * snapshot (the branch-base state of `work/tasks/ready/`, taken BEFORE the agent
  * ran), any new file is removed from the worktree and any changed file is
  * checked back out to HEAD — so the subsequent `git add -A` cannot land it. The
- * runner's commit then carries ONLY the explicit `pre-backlog/` placement.
+ * runner's commit then carries ONLY the explicit `tasks/backlog/` placement.
  */
 async function scrubPoolDrift(
 	cwd: string,
@@ -1122,8 +1153,9 @@ async function gitHard(
 /**
  * Build the needs-attention REASON for a task-SET ACCEPTANCE GATE block (task
  * `slice-acceptance-gate`): the fresh-context review of the produced set returned
- * `block`, so the spec is routed to `work/needs-attention/` with the review's
- * blocking findings as the body prose and NO tasks landed. Takes the core's
+ * `block`, so the spec is marked stuck on its per-item lock (post lock-cutover —
+ * `state: stuck` with this reason on the lock entry, no `work/needs-attention/`
+ * folder write) and NO tasks land. Takes the core's
  * structured `reviewBlockReason` (the gate's blocking findings); falls back to a
  * generic line when absent. DISTINCT from the improver loop's
  * {@link decompositionUnclearReason} (which carries the loop's open questions).
@@ -1141,8 +1173,8 @@ function taskGateBlockedReason(
 
 /**
  * Build the needs-attention REASON for a decomposition-unclear loop verdict (the
- * spec is routed to `work/needs-attention/` with these open questions, no guessed
- * tasks). Prose only — recorded as the spec's needs-attention body block.
+ * spec is marked stuck on its per-item lock with these open questions, no guessed
+ * tasks). Prose only — recorded as the spec's stuck-lock reason.
  */
 function decompositionUnclearReason(slug: string, questions: string[]): string {
 	const head =
@@ -1427,6 +1459,218 @@ function collectEmittedTasks(
 	return out;
 }
 
+/**
+ * Compose the propose-mode PR BODY for a slice-set (task
+ * `slicing-pr-body-summary-threading`): mirror the BUILD path's body threading
+ * (`do.ts` — `body: agent.output`) with a summary drawn from what the tasker
+ * ALREADY has in hand — the emitted task files. The shared
+ * {@link composeProposeBody} then wraps this prose with its runner-owned header.
+ *
+ * Sections (all suppressed when empty, so the body stays honest):
+ *   1. A lead line naming the source spec + emitted task count.
+ *   2. **Tasks** — one bullet per task: `slug — title`, plus `covers:` (which
+ *      spec user stories it maps to), `blockedBy:`, and `needsAnswers` if set.
+ *   3. **Dependency graph** — the KEYSTONE(S) (tasks whose `blockedBy` names no
+ *      other task in this set, so they land first) and the `blockedBy` edges.
+ *   4. **Needs answers** — any open questions the tasker review→edit loop
+ *      appended under `## Open questions` on `needsAnswers: true` tasks, so the
+ *      deferred seams are visible on the PR (not buried in task bodies).
+ *
+ * Returns `undefined` for the empty set (no emitted tasks) so the provider's
+ * `gh pr create --fill` fallback still applies on that edge (matches the build
+ * path's absent-body behaviour).
+ */
+export function composeTaskingProposeBody(
+	specSlug: string,
+	emitTasks: Record<string, string>,
+): string | undefined {
+	const entries = Object.entries(emitTasks);
+	if (entries.length === 0) {
+		return undefined;
+	}
+	const tasks = entries
+		.map(([rel, content]) => parseTaskSummary(rel, content))
+		.sort((a, b) => a.slug.localeCompare(b.slug));
+	const setSlugs = new Set(tasks.map((t) => t.slug));
+	const lines: string[] = [];
+	const n = tasks.length;
+	lines.push(
+		`Auto-tasked \`${specSlug}\` into ${n} backlog task${n === 1 ? '' : 's'}.`,
+	);
+	lines.push('');
+	lines.push('## Tasks');
+	lines.push('');
+	for (const t of tasks) {
+		lines.push(`- **${t.slug}** — ${t.title}`);
+		if (t.covers.length > 0) {
+			lines.push(`  - covers: ${t.covers.map((c) => `US #${c}`).join(', ')}`);
+		}
+		if (t.blockedBy.length > 0) {
+			lines.push(`  - blockedBy: ${t.blockedBy.join(', ')}`);
+		}
+		if (t.needsAnswers) {
+			lines.push('  - needsAnswers: true');
+		}
+	}
+	// Dependency graph: keystone(s) are tasks whose blockedBy names no OTHER
+	// member of this set (an external blocker — e.g. a task already in `done/` —
+	// does not prevent this set-relative starting point); the edges list every
+	// set-internal `blockedBy` link so a reviewer can trace the ordering.
+	const keystones = tasks.filter((t) =>
+		t.blockedBy.every((b) => !setSlugs.has(b)),
+	);
+	const edges = tasks.flatMap((t) =>
+		t.blockedBy.filter((b) => setSlugs.has(b)).map((b) => `${t.slug} ← ${b}`),
+	);
+	if (keystones.length > 0 || edges.length > 0) {
+		lines.push('');
+		lines.push('## Dependency graph');
+		lines.push('');
+		if (keystones.length > 0) {
+			const word = keystones.length === 1 ? 'Keystone' : 'Keystones';
+			lines.push(`- ${word}: ${keystones.map((k) => k.slug).join(', ')}`);
+		}
+		for (const edge of edges) {
+			lines.push(`- ${edge}`);
+		}
+	}
+	const uncertain = tasks.filter((t) => t.needsAnswers);
+	if (uncertain.length > 0) {
+		lines.push('');
+		lines.push('## Needs answers');
+		lines.push('');
+		for (const t of uncertain) {
+			lines.push(`- **${t.slug}**:`);
+			if (t.openQuestions.length === 0) {
+				lines.push('  - (no specific questions surfaced)');
+				continue;
+			}
+			for (const q of t.openQuestions) {
+				lines.push(`  - ${q}`);
+			}
+		}
+	}
+	return lines.join('\n');
+}
+
+/** Summary of one emitted task, for {@link composeTaskingProposeBody}. */
+interface TaskSummary {
+	slug: string;
+	title: string;
+	covers: string[];
+	blockedBy: string[];
+	needsAnswers: boolean;
+	openQuestions: string[];
+}
+
+/**
+ * Parse one emitted task file into a {@link TaskSummary}. Uses
+ * {@link parseFrontmatter} for the shared fields; scans the raw frontmatter
+ * block for `covers:` (not currently modelled on the parser's typed shape) and
+ * the body for a trailing `## Open questions` bullet list (the loop's
+ * uncertain-task disposition sink, see {@link appendQuestionsBlock}).
+ */
+function parseTaskSummary(rel: string, content: string): TaskSummary {
+	const fm = parseFrontmatter(content);
+	const slug = fm.slug ?? basename(rel).replace(/\.md$/i, '');
+	const title = readTitleField(content) ?? slug;
+	return {
+		slug,
+		title,
+		covers: readCoversField(content),
+		blockedBy: fm.blockedBy,
+		needsAnswers: fm.needsAnswers === true,
+		openQuestions: readOpenQuestions(content),
+	};
+}
+
+/**
+ * Extract the `title:` scalar from the raw frontmatter block (not on
+ * {@link parseFrontmatter}'s typed shape). Missing / malformed ⇒ `undefined`.
+ * Comment-tolerant: a trailing `# ...` after an UNQUOTED value is stripped.
+ */
+function readTitleField(content: string): string | undefined {
+	const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+	if (!normalized.startsWith('---\n')) {
+		return undefined;
+	}
+	const lines = normalized.split('\n');
+	const closing = lines.indexOf('---', 1);
+	if (closing === -1) {
+		return undefined;
+	}
+	for (let i = 1; i < closing; i++) {
+		const m = lines[i].match(/^title:\s*(.*)$/);
+		if (!m) continue;
+		let value = m[1].trim();
+		if (value === '') return undefined;
+		// Quoted ⇒ return inner text verbatim; unquoted ⇒ strip trailing `# ...`.
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
+			return value.slice(1, -1);
+		}
+		const hash = value.indexOf('#');
+		if (hash !== -1) value = value.slice(0, hash).trimEnd();
+		return value === '' ? undefined : value;
+	}
+	return undefined;
+}
+
+/**
+ * Extract the `covers: [...]` inline-list values from the raw frontmatter block
+ * of a task (not on {@link parseFrontmatter}'s typed shape, so we scan the raw
+ * fence here). Missing / malformed / empty ⇒ `[]`. Comment-tolerant (a trailing
+ * `# ...` after the `]` is ignored, matching the house style on `blockedBy: []
+ * # startable now`).
+ */
+function readCoversField(content: string): string[] {
+	const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+	if (!normalized.startsWith('---\n')) {
+		return [];
+	}
+	const lines = normalized.split('\n');
+	const closing = lines.indexOf('---', 1);
+	if (closing === -1) {
+		return [];
+	}
+	for (let i = 1; i < closing; i++) {
+		const line = lines[i];
+		const m = line.match(/^covers:\s*\[([^\]]*)\]/);
+		if (!m) continue;
+		return m[1]
+			.split(',')
+			.map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+			.filter((s) => s !== '');
+	}
+	return [];
+}
+
+/**
+ * Extract the bullets under a trailing `## Open questions` heading in a task
+ * body — the tasker review loop's uncertain-task sink (see
+ * {@link appendQuestionsBlock}). Returns `[]` when no such block exists.
+ */
+function readOpenQuestions(content: string): string[] {
+	const normalized = content.replace(/\r\n/g, '\n');
+	const idx = normalized.lastIndexOf(`\n${OPEN_QUESTIONS_HEADING}`);
+	if (idx === -1) {
+		return [];
+	}
+	const tail = normalized.slice(idx + 1);
+	const lines = tail.split('\n').slice(1);
+	const questions: string[] = [];
+	for (const raw of lines) {
+		const line = raw.trimEnd();
+		if (line === '') continue;
+		const m = line.match(/^- (.*)$/);
+		if (!m) break;
+		questions.push(m[1]);
+	}
+	return questions;
+}
+
 /** List `*.md` files in `dir`, sorted; an absent dir reads as empty. */
 function listMarkdown(dir: string): string[] {
 	let entries: string[];

package/src/triage-persist.ts

@@ -10,6 +10,7 @@ import {
 import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import type {TriageAutoKind} from './triage-gate.js';
 import {renderTaskBody, renderSpecBody} from './buildable-body.js';
+import {setFrontmatterMarker} from './frontmatter.js';
 
 /**
  * The engine-owned TRIAGE PERSIST (spec `advance-loop`, task `advance-rung-triage`,
@@ -233,7 +234,7 @@ export interface PromoteObservationOptions {
 	 * CAS) — NOT intake's branch+integrate band — so the CAS-loser-backs-off
 	 * guarantee and the same-commit note deletion are uniform across the two routes.
 	 * MIGRATE step (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
-	 * produced VALUE is `'spec'` (the verdict outcome renamed from `'prd'`).
+	 * produced VALUE is `'spec'` (the verdict outcome renamed from ''prd'').
 	 */
 	artifact?: 'task' | 'spec';
 	/**
@@ -273,11 +274,20 @@ export interface PromoteObservationOptions {
 export interface PromoteObservationResult {
 	/**
 	 * `promoted` (the new item landed via the CAS + the observation+sidecar were
-	 * deleted in the SAME commit), `lost` (the same-slug new-item race was lost —
-	 * the loser backs off, observation left INTACT), or `contended` (the CAS push
-	 * kept failing). Maps onto the claim-CAS exit codes.
+	 * deleted in the SAME commit), `already-triaged` (the target task ALREADY exists
+	 * on the arbiter AND was PROVABLY minted from THIS observation in a prior run — a
+	 * TERMINAL, benign idempotency fact, exit 0; the observation is left intact but a
+	 * retry can never succeed, so it is NOT loud), `lost` (a genuine concurrent-create
+	 * race for a same-path NEW item was lost — the loser backs off, observation left
+	 * INTACT, retry helps), or `contended` (the CAS push kept failing). Maps onto the
+	 * claim-CAS exit codes.
 	 */
-	outcome: 'promoted' | 'lost' | 'contended' | 'usage-error';
+	outcome:
+		| 'promoted'
+		| 'already-triaged'
+		| 'lost'
+		| 'contended'
+		| 'usage-error';
 	exitCode: 0 | 1 | 2 | 3;
 	/** The new task's path (relative to repo root) on a WIN. */
 	newItemPath?: string;
@@ -293,7 +303,7 @@ export interface PromoteObservationResult {
  * (create + delete).
  *
  * The artifact TYPE (`options.artifact`) selects the target + body shape: `'task'`
- * (default) mints `work/tasks/ready/<slug>.md`; `'prd'` mints
+ * (default) mints `work/tasks/ready/<slug>.md`; `'spec'` mints
  * `work/specs/proposed/<slug>.md` (SPEC staging — a human later promotes it to
  * `ready/`). BOTH routes use the SAME triage-local {@link createItemThroughCas}
  * writer (NOT intake's `switchToWorkBranch`/`performIntegration` branch+integrate
@@ -340,11 +350,24 @@ export async function promoteObservation(
 		`${newSlug}.md`,
 	);
 	const by = options.by || resolveBy(cwd, env);
-	const content = ensureTaskDispatchable(
-		artifact,
-		newSlug,
-		options.stubContent ??
-			buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env)),
+	// Stamp the observation→task PROVENANCE back-reference `promotedFrom: <item>` into
+	// the minted body (task `observation-triage-already-triaged-benign-skip`). It is
+	// the PROVABLE LINK the create-CAS lost-race disambiguator reads to tell case A
+	// (this observation ALREADY minted this task — already triaged, benign skip) from
+	// case B (a genuine concurrent-create race with an UNRELATED same-path item — loud
+	// exit 2). Distinct from `origin:` (how BORN: human/issue) and `reviewOf:` (the
+	// review-nits back-pointer); this is the triage-promote lineage. Matching on this
+	// explicit field — not the slug — is what keeps an unrelated same-slug task from
+	// false-positiving into a benign skip.
+	const content = setFrontmatterMarker(
+		ensureTaskDispatchable(
+			artifact,
+			newSlug,
+			options.stubContent ??
+				buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env)),
+		),
+		'promotedFrom',
+		item,
 	);
 
 	// The note + its answered sidecar `git rm` IN THE SAME create commit (promote =
@@ -359,6 +382,10 @@ export async function promoteObservation(
 		path: newItemPath,
 		content,
 		deletePaths: [itemPath, sidecarPath],
+		// The provenance disambiguator: on a LOST create-race, the CAS reads the
+		// existing file's `promotedFrom:` and, iff it equals THIS observation, reports
+		// the benign `already-exists-from-source` instead of the loud `lost`.
+		sourceItem: item,
 		cwd,
 		arbiter: options.arbiter,
 		by,
@@ -369,6 +396,23 @@ export async function promoteObservation(
 			? {contention: options.contention}
 			: {}),
 	});
+	// TERMINAL 'already triaged' (case A): the task this observation would mint
+	// ALREADY exists on the arbiter AND was provably minted from THIS observation in
+	// a prior run. A benign idempotency fact (exit 0) — the human already decided when
+	// they minted it — NOT a retry. The observation is left intact (a later
+	// discharge-by-deletion or a human deletes it); this leg does not red CI.
+	if (created.outcome === 'already-exists-from-source') {
+		const message =
+			`promote ${item}: ${newItemPath} was already minted FROM this observation ` +
+			`in a prior run (${created.message}) — already triaged. Benign skip, no retry.`;
+		note(message);
+		return {
+			outcome: 'already-triaged',
+			exitCode: 0,
+			newItemPath,
+			message,
+		};
+	}
 	if (created.exitCode !== 0) {
 		const message =
 			`promote ${item}: the new item ${newItemPath} ${created.outcome} the ` +
@@ -398,7 +442,7 @@ export async function promoteObservation(
  *
  * The artifact TYPE selects the frontmatter + lead heading: a `task` gets
  * `## What to build` + `blockedBy: []` + a `## Prompt` (the buildable-task shape);
- * a `prd` gets `## Problem Statement` (the SPEC document shape, with no `blockedBy` —
+ * a `spec` gets `## Problem Statement` (the SPEC document shape, with no `blockedBy` —
  * a SPEC is not a blockable task — and no `## Prompt`, since a SPEC is not
  * dispatched by `do`/`run`). BOTH carry the SAME transcribed mechanism prose +
  * open-question block, so a SPEC minted into `proposed/` is just as self-contained

package/src/vendor/incur/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present weth, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/vendor/incur/README.md

@@ -0,0 +1,19 @@
+# Vendored: `incur/src/internal/agents.ts` (MIT)
+
+`agents.ts` here is a **verbatim** copy of `src/internal/agents.ts` from
+[wevm/incur](https://github.com/wevm/incur) (MIT). See `LICENSE` beside it for the
+required copyright + permission notice, which is also duplicated as a header
+comment at the top of `agents.ts` itself so the file stays attribution-complete
+in isolation.
+
+We VENDOR rather than depend (see
+`docs/adr/skill-install-vendors-incur-agents-map.md`): the harness-destination
+map + copy/symlink logic are the one hard, drift-prone piece we need, and the
+file is dependency-free (only `node:fs`/`os`/`path`). Keep it BYTE-CLOSE to
+upstream so a future incur update is a mechanical re-copy — put all wrapper
+code outside this directory (`../../install-skills.ts`).
+
+To refresh: re-fetch `src/internal/agents.ts` from the upstream tag you want,
+overwrite `agents.ts`, keep the small ATTRIBUTION HEADER block at the top
+(above the original `import` lines) intact, and re-copy `LICENSE` if it
+changed upstream.