dorfl 0.1.2 → 0.2.0

package/src/install-skills.ts

@@ -0,0 +1,166 @@
+/**
+ * The dorfl-side wrapper around the VENDORED `incur/agents.ts` (MIT — see
+ * `./vendor/incur/`, and the ADR `docs/adr/skill-install-vendors-incur-agents-map.md`).
+ * The vendored file provides the ~22-harness destination map, `detect()`, and
+ * `install(sourceDir, options)` that copies each skill into the canonical
+ * `~/.agents/skills/` and symlinks non-universal harnesses. This module is the
+ * dorfl-authored code AROUND it: it resolves the packaged-skills SOURCE dir
+ * and drives the vendored `install()` — nothing more. Keep the vendored file
+ * untouched (byte-close to upstream) so future incur updates stay a mechanical
+ * re-copy.
+ *
+ * ## Decisions (in-scope, non-obvious)
+ *
+ * - **Sibling script over merged.** The build-time packaging lives in
+ *   `scripts/vendor-skills.mjs`, a SIBLING of the existing `vendor-protocol.mjs`
+ *   rather than an appended block on it. The two scripts copy DIFFERENT concept
+ *   sets (contract docs vs. hand-authored skills) into different dest subtrees;
+ *   each has its own set that evolves independently. See the header of
+ *   `vendor-skills.mjs` for the rationale (mirrors the wording here).
+ * - **Vendored file location.** `src/vendor/incur/agents.ts` (co-located with
+ *   its MIT `LICENSE` + a `README.md` provenance note). Under `src/` so `tsc`
+ *   compiles it into `dist/vendor/incur/agents.js`; under `vendor/incur/` so
+ *   the upstream origin is CLEAR from the path, and a future re-copy is a
+ *   drop-in overwrite. All dorfl wrapper code lives OUTSIDE that directory.
+ * - **Resolver home.** {@link resolveSkillsSourceDir} lives IN this module
+ *   (not in `prompt.ts` next to `resolveProtocolDoc`) because "the packaged
+ *   skills source" is a concept OWNED by skill-install; `resolveProtocolDoc`
+ *   is owned by the runner's prompt-assembly. Same SHAPE, different concept —
+ *   duplicating the small resolver body keeps the ownership boundary clean.
+ */
+
+import {existsSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {install, type Agent} from './vendor/incur/agents.js';
+
+/**
+ * Locate the SOURCE directory of the vendored skills the installer copies
+ * from. Resolution order, highest authority first:
+ *
+ *   1. `override` — explicit, for tests / unusual layouts (short-circuits).
+ *   2. `dist/skills/` — a copy VENDORED inside this package (by the
+ *      `vendor-skills` build step). The published-CLI primary: an installed
+ *      CLI has no sibling monorepo-root `skills/` tree.
+ *   3. the legacy monorepo-relative `skills/` walk — DEV-only, kept LAST (it
+ *      only resolves inside this dev monorepo; an installed CLI's walks escape
+ *      into the consumer's filesystem \u2192 nothing there, which is why it cannot
+ *      be the primary source).
+ *
+ * Mirrors the shape of {@link import('./prompt.js').resolveProtocolDoc} — the
+ * prefer-`dist/`-then-dev-walk order. Returns the first existing candidate;
+ * when nothing exists, returns the first candidate (the caller then hits a
+ * clean ENOENT rather than a silent no-op).
+ */
+export function resolveSkillsSourceDir(override?: string): string {
+	if (override) {
+		return override;
+	}
+	const here = dirname(fileURLToPath(import.meta.url));
+	// here = .../packages/dorfl/{src,dist}.
+	const candidates: string[] = [
+		// 2. Package-vendored copy (published-CLI primary). From `src/` (tsx)
+		//    `dist/` is a sibling; from `dist/` it is the dir itself.
+		resolve(here, '..', 'dist', 'skills'),
+		resolve(here, 'skills'),
+		// 3. Legacy monorepo-root walk \u2014 DEV-only, LAST.
+		resolve(here, '..', '..', '..', 'skills'),
+		resolve(here, '..', '..', '..', '..', 'skills'),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return candidates[0];
+}
+
+/**
+ * Options threaded through {@link installSkills} to the vendored `install()`.
+ * The shape mirrors incur's `install.Options` verbatim, plus a `sourceDir`
+ * override for the resolver seam. Everything is optional; a bare call
+ * `installSkills()` performs the "install every packaged skill, globally,
+ * into every detected harness" default.
+ */
+export interface InstallSkillsOptions {
+	/**
+	 * Override the resolved packaged-skills source dir. Tests pin this to a
+	 * scratch dir with fake skill folders; production callers omit it and take
+	 * whatever {@link resolveSkillsSourceDir} returns.
+	 */
+	sourceDir?: string;
+	/**
+	 * `false` \u21d2 project-local placement (canonical base is `<cwd>/.agents/skills/`,
+	 * and non-universal harnesses use their PROJECT-relative dirs). Default
+	 * `true` (or omitted) \u21d2 global placement under `~/.agents/skills/`.
+	 */
+	global?: boolean;
+	/**
+	 * Working directory for project-local installs. Ignored when `global` is not
+	 * `false`. Defaults (in the vendored file) to `process.cwd()`.
+	 */
+	cwd?: string;
+	/**
+	 * Override the detected harnesses. Tests use this to force a deterministic
+	 * set; production callers omit it and let the vendored `detect()` pick.
+	 */
+	agents?: Agent[];
+}
+
+/**
+ * The per-harness install detail returned by the vendored `install()` (for
+ * NON-UNIVERSAL harnesses only \u2014 universal harnesses read from the canonical
+ * `.agents/skills/` directly and need no per-harness entry).
+ */
+export interface InstalledAgent {
+	/** Harness display name (e.g. `'Claude Code'`, `'Windsurf'`). */
+	agent: string;
+	/** Absolute path the skill was placed at for this harness. */
+	path: string;
+	/** How the placement was materialised. Symlink is the norm; copy is the
+	 *  Windows/no-permission fallback. */
+	mode: 'symlink' | 'copy';
+}
+
+/** The report {@link installSkills} returns to its CLI caller. */
+export interface InstallSkillsResult {
+	/**
+	 * The SOURCE directory the vendored `install()` was driven from (the value
+	 * {@link resolveSkillsSourceDir} chose). Included so `dorfl skills add`
+	 * can print WHERE the skills were read from, and tests can assert the
+	 * resolver picked what they expected.
+	 */
+	sourceDir: string;
+	/** Canonical install paths (one per skill directory copied). */
+	paths: string[];
+	/** Per-harness placements for non-universal harnesses. */
+	agents: InstalledAgent[];
+}
+
+/**
+ * Resolve the packaged-skills source, drive the vendored `install()`, return
+ * the source + canonical paths + per-harness report. Global by default; pass
+ * `global: false` for project-local placement. Tests pin `sourceDir`/`agents`
+ * to keep the run hermetic; production callers pass nothing.
+ *
+ * The vendored `install()` reads `os.homedir()` (etc.) at MODULE LOAD, so
+ * shared-write isolation for `global: true` (the default) has to happen BEFORE
+ * this module is loaded (e.g. by pointing `HOME` at a scratch dir). Tests use
+ * `global: false` + a scratch `cwd` for the common path (no env dance needed);
+ * see `test/install-skills.test.ts`.
+ */
+export function installSkills(
+	options: InstallSkillsOptions = {},
+): InstallSkillsResult {
+	const sourceDir = resolveSkillsSourceDir(options.sourceDir);
+	const result = install(sourceDir, {
+		global: options.global,
+		cwd: options.cwd,
+		agents: options.agents,
+	});
+	return {
+		sourceDir,
+		paths: result.paths,
+		agents: result.agents,
+	};
+}

package/src/intake-trigger-template.ts

@@ -317,7 +317,7 @@ jobs:
     if: \${{ github.event.issue.number && !github.event.issue.pull_request }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}

package/src/intake.ts

@@ -95,7 +95,7 @@ import {renderTaskBody, renderSpecBody} from './buildable-body.js';
  * table). EXPAND step (spec
  * `prd-to-spec-vocabulary-cutover-and-migration-command`): the `spec` outcome
  * names the "clear + coherent but >1 task" classification (a parent SPEC). HARD
- * CUTOVER (contract step): the legacy `prd` outcome token is GONE — the prompt
+ * CUTOVER (contract step): the legacy ''prd'' outcome token is GONE — the prompt
  * emits `spec` and the parser rejects any other token.
  */
 export type IntakeOutcome = 'ask' | 'task' | 'spec' | 'bounce';
@@ -256,7 +256,7 @@ export interface PerformIntakeOptions {
 	 * The PER-OUTCOME integration modes (spec `issue-intake` US #9) the emitted artifact integrates
 	 * THROUGH the shared core with. Because `intake` decides the artifact TYPE at
 	 * RUNTIME, the mode is keyed per type: an emitted task integrates with
-	 * `integration.task`, an emitted spec with `integration.prd` (`propose` =
+	 * `integration.task`, an emitted spec with `integration.spec` (`propose` =
 	 * push the `work/<slug>` branch + open a PR, NO `main` touch; `merge` = land on
 	 * `main`). The CLI resolves this from the granular + aggregate flags via
 	 * {@link resolveIntakeIntegrationModes}; ask/bounce emit nothing, so the modes
@@ -267,7 +267,7 @@ export interface PerformIntakeOptions {
 	 * **The ORIGIN-TRUST verdict, passed IN** (task
 	 * `untrusted-origin-forces-build-propose`; the `--origin-trust <trusted|untrusted>`
 	 * CLI flag). `intake` STAMPS `origin: issue` + this `originTrust` onto every spec/
-	 * task it emits, so the author-trust signal SURVIVES the prd/task merge
+	 * task it emits, so the author-trust signal SURVIVES the spec/task merge
 	 * boundary (a landed-on-main artifact otherwise erases how it was born, the
 	 * laundering gap). `intake` does NOT resolve trust itself: the verdict is CI's
 	 * POLICY, computed in the `intake.yml` shell from the SAME `author_association`
@@ -325,6 +325,19 @@ export interface PerformIntakeOptions {
 	 * must not act as the bot. Absent ⇒ ambient (today's behaviour).
 	 */
 	identity?: Identity;
+	/**
+	 * **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 the shared integrate core so a wide-matrix CI's
+	 * raised cap reaches intake's task/spec emit land tail too (task
+	 * `thread-merge-retries-cross-task-and-ratify-default`). Resolved ONCE at the
+	 * entry point (the CLI) through the env + per-repo layers of the gate-family
+	 * precedence chain — the `intake` command has NO `--merge-retries` flag today
+	 * (the flag layer legitimately does not apply here; intake is
+	 * unattended-CI-first, env + per-repo cover the need). Unset ⇒ the engine's
+	 * `DEFAULT_MERGE_RETRIES = 1000` (byte-for-byte unchanged).
+	 */
+	mergeRetries?: number;
 	/** Environment for child git/agent processes (the AGENT-launch ambient env). */
 	env?: NodeJS.ProcessEnv;
 	/** Sink for human-readable progress notes. */
@@ -377,14 +390,14 @@ function specLandingToSide(
 
 /**
  * The emitted artifact TYPE `intake` decides at RUNTIME — a `task` verdict emits
- * `work/backlog/<slug>.md`, a `prd` verdict emits the spec file (`work/specs/ready/<slug>.md`). The two
+ * `work/backlog/<slug>.md`, a `spec` verdict emits the spec file (`work/specs/ready/<slug>.md`). The two
  * granular flag axes (`--merge-task`/`--propose-task` vs `--merge-spec`/
  * `--propose-spec`) are keyed on this. (ask/bounce emit NOTHING, so the modes are
  * no-ops for them.)
  */
 export type IntakeArtifactType = 'task' | 'spec';
-// `prd` → `spec` HARD CUTOVER: `'spec'` is the ONLY spec artifact type value; the
-// legacy `'prd'` alias is GONE (the contract task removed it).
+// ''prd'' → `spec` HARD CUTOVER: `'spec'` is the ONLY spec artifact type value; the
+// legacy ''prd'' alias is GONE (the contract task removed it).
 
 /**
  * The PER-OUTCOME integration mode FLAG SET (spec `issue-intake` US #9). Because
@@ -837,6 +850,9 @@ async function decideAndDispatch(
 				cwd,
 				arbiter,
 				integration: modes.task,
+				// The resolved cross-job CAS-retry cap (config `mergeRetries`) — threaded so
+				// intake's lone-task emit lands under the same per-repo cap the build path uses.
+				mergeRetries: options.mergeRetries,
 				// The origin-trust STAMP, passed IN (not resolved here): the emitted task
 				// carries `origin: issue` + this verdict so the becomes-code checkpoint is
 				// not laundered. Unset ⇒ unstamped (a local intake ⇒ human/trusted).
@@ -855,7 +871,7 @@ async function decideAndDispatch(
 				note,
 			});
 		// The `spec` outcome is the parent-spec verdict; it dispatches through
-		// `modes.spec`. HARD CUTOVER: the legacy `prd` outcome case is GONE.
+		// `modes.spec`. HARD CUTOVER: the legacy ''prd'' outcome case is GONE.
 		case 'spec':
 			return dispatchSpec({
 				verdict,
@@ -863,6 +879,9 @@ async function decideAndDispatch(
 				cwd,
 				arbiter,
 				integration: modes.spec,
+				// The resolved cross-job CAS-retry cap (config `mergeRetries`) — threaded so
+				// intake's spec emit lands under the same per-repo cap the build path uses.
+				mergeRetries: options.mergeRetries,
 				// Same origin-trust stamp on the spec outcome (propagated onto its tasks
 				// later by the tasker). Passed IN; not resolved here.
 				originTrust: options.originTrust,
@@ -1041,6 +1060,8 @@ async function dispatchTask(params: {
 	cwd: string;
 	arbiter: string;
 	integration: IntegrationMode;
+	/** The resolved cross-job CAS-retry cap (undefined ⇒ engine default). */
+	mergeRetries: number | undefined;
 	/** The origin-trust stamp passed IN (unset ⇒ emit unstamped ⇒ human/trusted). */
 	originTrust: OriginTrust | undefined;
 	noPR: boolean | undefined;
@@ -1063,6 +1084,7 @@ async function dispatchTask(params: {
 		cwd,
 		arbiter,
 		integration,
+		mergeRetries,
 		originTrust,
 		noPR,
 		providerInstance,
@@ -1185,6 +1207,12 @@ async function dispatchTask(params: {
 		// EXPLICITLY-chosen mode proceeds as-is: a future `--merge-task` lands on main
 		// (`merge` IS the auto-land mode, never downgraded).
 		mode: integration,
+		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — the
+		// git-alone floor of the cross-job land queue, resolved through the gate-
+		// family precedence chain in the CLI and threaded here so intake's lone-task
+		// emit lands under the same per-repo cap the build path uses. Unset ⇒ the
+		// engine default (byte-for-byte unchanged).
+		mergeRetries,
 		noPR,
 		providerInstance,
 		type: 'feat',
@@ -1217,8 +1245,8 @@ async function dispatchTask(params: {
 }
 
 /**
- * DISPATCH the `spec` outcome (canonical; the legacy `prd` outcome routes here too
- * through the cutover): derive a content-derived slug, write the spec file
+ * DISPATCH the `spec` outcome (the SOLE parent-spec outcome after the HARD CUTOVER;
+ * the legacy ''prd'' outcome token is GONE): derive a content-derived slug, write the spec file
  * (`work/specs/ready/<slug>.md`) carrying `issue: N` (the loop-closure linkage the
  * close JOB reaches via `task.spec: → spec issue:`; on a fanned spec the number
  * lives ONLY on the spec — a fanned task uses `spec:`, NOT its own `issue:`, which
@@ -1234,6 +1262,8 @@ async function dispatchSpec(params: {
 	cwd: string;
 	arbiter: string;
 	integration: IntegrationMode;
+	/** The resolved cross-job CAS-retry cap (undefined ⇒ engine default). */
+	mergeRetries: number | undefined;
 	/** The origin-trust stamp passed IN (unset ⇒ emit unstamped ⇒ human/trusted). */
 	originTrust: OriginTrust | undefined;
 	noPR: boolean | undefined;
@@ -1255,6 +1285,7 @@ async function dispatchSpec(params: {
 		cwd,
 		arbiter,
 		integration,
+		mergeRetries,
 		originTrust,
 		noPR,
 		specsLandIn,
@@ -1321,6 +1352,10 @@ async function dispatchSpec(params: {
 		// not a build), exactly as the task branch + the tasking transition skip it.
 		skipVerify: true,
 		mode: integration,
+		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — same
+		// rationale as the lone-task emit above; threaded so intake's spec emit lands
+		// under the same per-repo cap. Unset ⇒ the engine default (byte-for-byte).
+		mergeRetries,
 		noPR,
 		providerInstance,
 		type: 'feat',
@@ -1737,7 +1772,7 @@ async function stageIntakeContent(params: {
  * `intake-` PRODUCER prefix keeps this short-lived "create the item" branch
  * DISTINCT from the later build branch (`work/task-<slug>`) for the same slug
  * — the firing `intake` × `do task:` collision the observation traced. The
- * task-emit path passes `'task'`, the spec-emit path `'prd'`. A pre-existing
+ * task-emit path passes `'task'`, the spec-emit path `'spec'`. A pre-existing
  * local branch (a re-run) is force-recreated off fresh main.
  */
 async function switchToWorkBranch(
@@ -1860,7 +1895,7 @@ export function parseIntakeVerdict(output: string): IntakeVerdict {
 		outcome !== 'bounce'
 	) {
 		// The prompt teaches the LLM to emit `spec`, so the accepted outcome set is
-		// `ask|task|spec|bounce`. HARD CUTOVER: the legacy `prd` outcome token is
+		// `ask|task|spec|bounce`. HARD CUTOVER: the legacy ''prd'' outcome token is
 		// fully gone (rejected here + removed from the `IntakeOutcome` type + the
 		// dispatch `case`).
 		throw new Error(