dorfl 0.1.1 → 0.2.0

package/src/triage-gate.ts

@@ -3,7 +3,7 @@ import {launchWithOptionalWatch} from './agent-launch.js';
 import {extractJsonObjectSpan} from './verdict-json.js';
 
 /**
- * The **TRIAGE auto-disposition GATE** (prd `advance-loop`, task
+ * The **TRIAGE auto-disposition GATE** (spec `advance-loop`, task
  * `advance-rung-triage`, US #17) — the CONSERVATIVE, `observationTriage: 'auto'`-
  * gated exception to the question-gated default. On `classify=triage-observation`
  * AND `observationTriage` resolved to `'auto'`, the engine asks this gate whether

package/src/triage-persist.ts

@@ -10,9 +10,10 @@ 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 (prd `advance-loop`, task `advance-rung-triage`,
+ * The engine-owned TRIAGE PERSIST (spec `advance-loop`, task `advance-rung-triage`,
  * US #16/17/24/30) — the half of the observation-triage rung the ENGINE owns (the
  * triage gate JUDGES, the engine ACTS). It is the SIBLING of `surface-persist.ts`
  * (the surface rung's persist) and `apply-persist.ts` (the apply rung's persist),
@@ -232,8 +233,8 @@ export interface PromoteObservationOptions {
 	 * triage-local {@link createItemThroughCas} writer (one local commit through the
 	 * 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 (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the
-	 * produced VALUE is `'spec'` (the verdict outcome renamed from `'prd'`).
+	 * MIGRATE step (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
+	 * 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;
@@ -287,22 +297,22 @@ export interface PromoteObservationResult {
 
 /**
  * Promote an ANSWERED observation to a NEW, SELF-CONTAINED artifact (US #1/#3/#8
- * for the task route; US #4/#9 for the PRD route): CAS-create the new item keyed
+ * for the task route; US #4/#9 for the SPEC route): CAS-create the new item keyed
  * on the NEW item's identity (its target path), with the observation note + its
  * answered sidecar `git rm`-ed IN THE SAME atomic commit. Promote is ONE commit
  * (create + delete).
  *
  * The artifact TYPE (`options.artifact`) selects the target + body shape: `'task'`
- * (default) mints `work/tasks/ready/<slug>.md`; `'prd'` mints
- * `work/prds/proposed/<slug>.md` (PRD staging — a human later promotes it to
+ * (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
  * band, which is intake's standalone front door): one create/integrate surface for
- * triage, the CAS-loser-backs-off guarantee uniform across task and PRD promotion.
+ * triage, the CAS-loser-backs-off guarantee uniform across task and SPEC promotion.
  *
  * The minted body is built FROM the observation (see {@link buildPromotedBody}):
  * its mechanism + fix prose is carried into the artifact's lead section (`## What
- * to build` for a task, `## Problem Statement` for a PRD), and its
+ * to build` for a task, `## Problem Statement` for a SPEC), and its
  * `## Open questions` scoping is transcribed into the new item's own
  * `## Open questions` block with `needsAnswers` set when questions remain (cleared
  * when none do) — so an agent can build from the artifact ALONE and no decision
@@ -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,10 +442,10 @@ 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 PRD document shape, with no `blockedBy` —
- * a PRD is not a blockable task — and no `## Prompt`, since a PRD is not
+ * 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 PRD minted into `proposed/` is just as self-contained
+ * open-question block, so a SPEC minted into `proposed/` is just as self-contained
  * as a task.
  *
  * The `## Prompt` (task only) is the STRUCTURAL dispatchability the validator
@@ -409,9 +453,9 @@ export async function promoteObservation(
  * dispatched build throws "has no '## Prompt' section". The body BELOW the
  * frontmatter (lead section + mechanism prose + optional `## Open questions` +
  * the task-only `## Prompt`) is rendered by the SHARED owner of the
- * buildable-task/PRD schema, {@link renderTaskBody} / {@link renderSpecBody}
+ * buildable-task/SPEC schema, {@link renderTaskBody} / {@link renderSpecBody}
  * (`buildable-body.ts`), so the producer and the consumer cannot drift apart
- * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`,
+ * (spec `centralize-buildable-task-renderer-shared-by-intake-and-promotion`,
  * US #3/#5/#6). This function owns only the FRONTMATTER writer; the section
  * skeleton lives in the one renderer. The empty-mechanism `## Prompt` seed is
  * passed EXPLICITLY (`Build the task '<slug>', described above.`) so promotion's
@@ -434,8 +478,8 @@ export async function promoteObservation(
  * fails with `has no '## Prompt' section` (the `extractPromptSection`/`resolveTask`
  * guard in `prompt.ts`). This is the robust backstop that closes that hole
  * regardless of agent compliance: for a TASK, if the body has no `## Prompt`
- * heading, append a seeded one (blockquoted, matching the renderer's shape). A PRD
- * is left UNTOUCHED — a PRD is a north-star doc, not dispatched by `do`/`run`, and carries no
+ * heading, append a seeded one (blockquoted, matching the renderer's shape). A SPEC
+ * is left UNTOUCHED — a SPEC is a north-star doc, not dispatched by `do`/`run`, and carries no
  * `## Prompt` by design.
  */
 function ensureTaskDispatchable(
@@ -472,7 +516,7 @@ function buildPromotedBody(
 		`title: ${slug}`,
 		`slug: ${slug}`,
 		`needsAnswers: ${hasQuestions ? 'true' : 'false'}`,
-		// A PRD is a north-star doc, not a blockable task — only the task shape carries
+		// A SPEC is a north-star doc, not a blockable task — only the task shape carries
 		// `blockedBy`.
 		...(artifact === 'spec' ? [] : ['blockedBy: []']),
 		'---',
@@ -488,8 +532,8 @@ function buildPromotedBody(
 	// no leading blank. Do NOT move the separator into the renderer.
 	const fenceToBody = frontmatter.join('\n') + '\n\n';
 	// The body BELOW the frontmatter is rendered by the SHARED schema owner so the
-	// section skeleton has one home, not two (prd
-	// `centralize-buildable-task-renderer-shared-by-intake-and-promotion`). A PRD
+	// section skeleton has one home, not two (spec
+	// `centralize-buildable-task-renderer-shared-by-intake-and-promotion`). A SPEC
 	// goes through `renderSpecBody` (no `## Prompt`); a task through
 	// `renderTaskBody` (always a `## Prompt`).
 	if (artifact === 'spec') {

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.

package/src/vendor/incur/agents.ts

@@ -0,0 +1,392 @@
+// ---------------------------------------------------------------------------
+// VENDORED FROM: https://github.com/wevm/incur
+//   Source:     src/internal/agents.ts
+//   License:    MIT (see ./LICENSE beside this file)
+//   Copyright:  (c) 2025-present weth, LLC
+//
+// This file is a VERBATIM copy of the upstream `src/internal/agents.ts` from
+// wevm/incur, preserved byte-close so future upstream updates are a mechanical
+// re-copy. Do NOT edit it in place — put all dorfl wrapper code OUTSIDE this
+// directory (see `../../install-skills.ts`). Only the block ABOVE this line is
+// dorfl-authored (attribution header). See `./README.md` for provenance and
+// the `docs/adr/skill-install-vendors-incur-agents-map.md` ADR for why we
+// vendor rather than depend.
+//
+// MIT permission notice (required by upstream license, kept in-file so the
+// attribution survives isolation from the sibling LICENSE):
+//
+//   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.
+// ---------------------------------------------------------------------------
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+/** Agent configuration for skill installation. */
+export type Agent = {
+  /** Display name. */
+  name: string
+  /** Absolute path to the global skills directory. */
+  globalSkillsDir: string
+  /** Project-relative skills directory path. */
+  projectSkillsDir: string
+  /** Whether this agent uses the canonical `.agents/skills` path. */
+  universal: boolean
+  /** Checks if the agent is installed on the system. */
+  detect(): boolean
+}
+
+const home = os.homedir()
+const configHome = process.env.XDG_CONFIG_HOME || path.join(home, '.config')
+const claudeHome = process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(home, '.claude')
+const codexHome = process.env.CODEX_HOME?.trim() || path.join(home, '.codex')
+
+/** All known agent definitions. */
+export const all: Agent[] = [
+  // Universal agents (project skillsDir = .agents/skills)
+  {
+    name: 'Amp',
+    globalSkillsDir: path.join(configHome, 'agents', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(configHome, 'amp')),
+  },
+  {
+    name: 'Cline',
+    globalSkillsDir: path.join(home, '.agents', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(home, '.cline')),
+  },
+  {
+    name: 'Codex',
+    globalSkillsDir: path.join(codexHome, 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(codexHome),
+  },
+  {
+    name: 'Cursor',
+    globalSkillsDir: path.join(home, '.cursor', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(home, '.cursor')),
+  },
+  {
+    name: 'Gemini CLI',
+    globalSkillsDir: path.join(home, '.gemini', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(home, '.gemini')),
+  },
+  {
+    name: 'GitHub Copilot',
+    globalSkillsDir: path.join(home, '.copilot', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(home, '.copilot')),
+  },
+  {
+    name: 'Kimi CLI',
+    globalSkillsDir: path.join(configHome, 'agents', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(home, '.kimi')),
+  },
+  {
+    name: 'OpenCode',
+    globalSkillsDir: path.join(configHome, 'opencode', 'skills'),
+    projectSkillsDir: '.agents/skills',
+    universal: true,
+    detect: () => fs.existsSync(path.join(configHome, 'opencode')),
+  },
+
+  // Non-universal agents (need symlink from their skills dir to canonical)
+  {
+    name: 'Claude Code',
+    globalSkillsDir: path.join(claudeHome, 'skills'),
+    projectSkillsDir: '.claude/skills',
+    universal: false,
+    detect: () => fs.existsSync(claudeHome),
+  },
+  {
+    name: 'Windsurf',
+    globalSkillsDir: path.join(home, '.codeium', 'windsurf', 'skills'),
+    projectSkillsDir: '.windsurf/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.codeium', 'windsurf')),
+  },
+  {
+    name: 'Continue',
+    globalSkillsDir: path.join(home, '.continue', 'skills'),
+    projectSkillsDir: '.continue/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.continue')),
+  },
+  {
+    name: 'Roo',
+    globalSkillsDir: path.join(home, '.roo', 'skills'),
+    projectSkillsDir: '.roo/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.roo')),
+  },
+  {
+    name: 'Kilo',
+    globalSkillsDir: path.join(home, '.kilocode', 'skills'),
+    projectSkillsDir: '.kilocode/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.kilocode')),
+  },
+  {
+    name: 'Goose',
+    globalSkillsDir: path.join(configHome, 'goose', 'skills'),
+    projectSkillsDir: '.goose/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(configHome, 'goose')),
+  },
+  {
+    name: 'Augment',
+    globalSkillsDir: path.join(home, '.augment', 'skills'),
+    projectSkillsDir: '.augment/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.augment')),
+  },
+  {
+    name: 'Trae',
+    globalSkillsDir: path.join(home, '.trae', 'skills'),
+    projectSkillsDir: '.trae/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.trae')),
+  },
+  {
+    name: 'Junie',
+    globalSkillsDir: path.join(home, '.junie', 'skills'),
+    projectSkillsDir: '.junie/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.junie')),
+  },
+  {
+    name: 'Crush',
+    globalSkillsDir: path.join(configHome, 'crush', 'skills'),
+    projectSkillsDir: '.crush/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(configHome, 'crush')),
+  },
+  {
+    name: 'Kiro CLI',
+    globalSkillsDir: path.join(home, '.kiro', 'skills'),
+    projectSkillsDir: '.kiro/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.kiro')),
+  },
+  {
+    name: 'Qwen Code',
+    globalSkillsDir: path.join(home, '.qwen', 'skills'),
+    projectSkillsDir: '.qwen/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.qwen')),
+  },
+  {
+    name: 'OpenHands',
+    globalSkillsDir: path.join(home, '.openhands', 'skills'),
+    projectSkillsDir: '.openhands/skills',
+    universal: false,
+    detect: () => fs.existsSync(path.join(home, '.openhands')),
+  },
+]
+
+/** Detects which agents are installed on the system. */
+export function detect(): Agent[] {
+  return all.filter((a) => a.detect())
+}
+
+/**
+ * Installs skill directories to the canonical location and creates symlinks for
+ * detected non-universal agents.
+ *
+ * @param sourceDir - Directory containing skill subdirectories (each with a `SKILL.md`).
+ * @param options - Installation options.
+ * @returns Installed canonical paths.
+ */
+export function install(sourceDir: string, options: install.Options = {}): install.Result {
+  const isGlobal = options.global !== false
+  const cwd = options.cwd || process.cwd()
+  const base = isGlobal ? home : cwd
+  const canonicalBase = path.join(base, '.agents', 'skills')
+  const detected = options.agents ?? detect()
+
+  const paths: string[] = []
+  const agents: install.AgentInstall[] = []
+
+  for (const skill of discoverSkills(sourceDir)) {
+    const canonicalDir = path.join(canonicalBase, skill.name)
+
+    // Copy to canonical location
+    rmForce(canonicalDir)
+    fs.mkdirSync(canonicalDir, { recursive: true })
+    if (skill.root)
+      fs.copyFileSync(path.join(skill.dir, 'SKILL.md'), path.join(canonicalDir, 'SKILL.md'))
+    else fs.cpSync(skill.dir, canonicalDir, { recursive: true })
+    paths.push(canonicalDir)
+
+    // Create symlinks for non-universal agents
+    for (const agent of detected) {
+      if (agent.universal) continue
+      const agentSkillsDir = isGlobal
+        ? agent.globalSkillsDir
+        : path.join(cwd, agent.projectSkillsDir)
+      const agentDir = path.join(agentSkillsDir, skill.name)
+
+      // Skip if agent dir resolves to canonical (no symlink needed)
+      if (agentDir === canonicalDir) continue
+
+      try {
+        rmForce(agentDir)
+        fs.mkdirSync(path.dirname(agentDir), { recursive: true })
+        // Resolve through any existing symlinks in parent directories
+        const realLinkDir = resolveParent(path.dirname(agentDir))
+        const realTarget = resolveParent(canonicalDir)
+        const rel = path.relative(realLinkDir, realTarget)
+        fs.symlinkSync(rel, agentDir)
+        agents.push({ agent: agent.name, path: agentDir, mode: 'symlink' })
+      } catch {
+        // Fallback to copy if symlink fails (e.g. Windows without permissions)
+        try {
+          fs.cpSync(canonicalDir, agentDir, { recursive: true })
+          agents.push({ agent: agent.name, path: agentDir, mode: 'copy' })
+        } catch {}
+      }
+    }
+  }
+
+  return { paths, agents }
+}
+
+export declare namespace install {
+  type Options = {
+    /** Override detected agents. */
+    agents?: Agent[] | undefined
+    /** Working directory for project-local installs. */
+    cwd?: string | undefined
+    /** Install globally. Defaults to `true`. */
+    global?: boolean | undefined
+  }
+  type Result = {
+    /** Canonical install paths. */
+    paths: string[]
+    /** Per-agent install details (non-universal agents only). */
+    agents: AgentInstall[]
+  }
+  type AgentInstall = {
+    /** Agent display name. */
+    agent: string
+    /** Installed path. */
+    path: string
+    /** Whether it was symlinked or copied. */
+    mode: 'symlink' | 'copy'
+  }
+}
+
+/**
+ * Removes a skill by name from the canonical location and all detected agent directories.
+ */
+export function remove(
+  skillName: string,
+  options: { global?: boolean | undefined; cwd?: string | undefined } = {},
+) {
+  const isGlobal = options.global !== false
+  const cwd = options.cwd || process.cwd()
+  const base = isGlobal ? home : cwd
+  const canonicalDir = path.join(base, '.agents', 'skills', skillName)
+  rmForce(canonicalDir)
+
+  for (const agent of detect()) {
+    if (agent.universal) continue
+    const agentSkillsDir = isGlobal ? agent.globalSkillsDir : path.join(cwd, agent.projectSkillsDir)
+    const agentDir = path.join(agentSkillsDir, skillName)
+    rmForce(agentDir)
+  }
+}
+
+/** Recursively discovers skill directories (those containing a `SKILL.md`). */
+function discoverSkills(rootDir: string): { name: string; dir: string; root?: boolean }[] {
+  const results: { name: string; dir: string; root?: boolean }[] = []
+
+  function visit(dir: string) {
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const subDir = path.join(dir, entry.name)
+      const skillPath = path.join(subDir, 'SKILL.md')
+      if (fs.existsSync(skillPath)) {
+        const content = fs.readFileSync(skillPath, 'utf8')
+        const nameMatch = content.match(/^name:\s*(.+)$/m)
+        results.push({ name: sanitizeName(nameMatch?.[1] ?? entry.name), dir: subDir })
+      }
+      visit(subDir)
+    }
+  }
+
+  visit(rootDir)
+
+  // Root-level SKILL.md (e.g. depth=0)
+  const rootSkill = path.join(rootDir, 'SKILL.md')
+  if (fs.existsSync(rootSkill)) {
+    const content = fs.readFileSync(rootSkill, 'utf8')
+    const nameMatch = content.match(/^name:\s*(.+)$/m)
+    const name = sanitizeName(nameMatch?.[1] ?? 'skill')
+    if (!results.some((r) => r.name === name)) results.push({ name, dir: rootDir, root: true })
+  }
+
+  return results
+}
+
+/** Sanitizes a skill name for use as a directory name. */
+function sanitizeName(name: string): string {
+  return name.trim().replace(/[/\\]/g, '-').replace(/\.\./g, '').slice(0, 255)
+}
+
+/** Removes a file, directory, or symlink (including broken symlinks). */
+function rmForce(target: string) {
+  try {
+    const stat = fs.lstatSync(target)
+    if (stat.isSymbolicLink()) fs.unlinkSync(target)
+    else fs.rmSync(target, { recursive: true, force: true })
+  } catch {}
+}
+
+/** Resolves parent directories through symlinks. */
+function resolveParent(dir: string): string {
+  try {
+    return fs.realpathSync(dir)
+  } catch {
+    const parent = path.dirname(dir)
+    if (parent === dir) return dir
+    try {
+      return path.join(fs.realpathSync(parent), path.relative(parent, dir))
+    } catch {
+      return dir
+    }
+  }
+}

package/src/verify-workflow-template.ts

@@ -1,5 +1,5 @@
 /**
- * The `install-ci` VERIFY-WORKFLOW capability (prd
+ * The `install-ci` VERIFY-WORKFLOW capability (spec
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `install-ci-tier1-branch-protection`; Story 11 — the Tier-1 GitHub ceiling).
  * Emits a small `verify.yml` workflow whose ONLY job is `verify` and runs on
@@ -49,7 +49,7 @@ export const VERIFY_WORKFLOW_PATH = 'workflows/verify.yml';
  */
 export function generateVerifyWorkflow(_config: ResolvedCIConfig): string {
 	return `\
-# dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; prd
+# dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; spec
 # land-time-reverify-and-parallel-merge-ceiling, task
 # install-ci-tier1-branch-protection). EMITTED by \`dorfl install-ci\`; the
 # human commits it. DO NOT hand-edit a copy — re-run install-ci to upgrade.
@@ -100,7 +100,7 @@ jobs:
   ${VERIFY_CHECK_CONTEXT}:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup