dorfl 0.1.2 → 0.2.1

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

@@ -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

package/src/watch-session.ts

@@ -13,6 +13,16 @@ import {open, type FileHandle} from 'node:fs/promises';
  * `--mode json` STREAM `ar-run.sh` piped. The tailer is pointed at that EXACT
  * path (no newest-by-mtime dir guessing), so the stale-sibling race is gone.
  *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`, pinned against pi 0.73.1 +
+ * session format v3): tailing the session file is deliberately the CHOSEN
+ * channel for `--watch`, not just what was easiest to reuse. `--mode json`'s
+ * STDOUT event vocabulary would be lower-latency but it is unversioned, would
+ * fork a second parser away from pi-remote's `session-pool.ts` reference walk
+ * this classifier mirrors, and the vocabulary-drift risk that already bit
+ * `do --watch` once applies MORE to it than to the versioned+migrated session
+ * file. Revisit only if pi's session format changes.
+ *
  * A session-log record is `{"type":"message", "message":{role, content[]}}` (or a
  * `session`/`model_change`/`thinking_level_change` preamble record). The earlier
  * classifier matched the STREAM vocabulary (`tool_start`/`message_end`/`agent_end`),
@@ -21,8 +31,10 @@ import {open, type FileHandle} from 'node:fs/promises';
  * surfaces the same high-signal level `ar-run.sh --watch` gave, read off the
  * SESSION-LOG shape:
  *
- *   - an `assistant` `message` → its `content[]` `text` parts, then `▶ <name>`
- *     (cyan) per `content[]` `toolCall` part;
+ *   - an `assistant` `message` → its `content[]` `text` parts, then
+ *     `▶ <name> <detail>` (cyan) per `content[]` `toolCall` part, where
+ *     `<detail>` is the high-signal argument for that tool (a `read`'s path, a
+ *     `bash`'s command, …), truncated to 64 chars with a trailing `…`;
  *   - `✓ agent finished` (green) on PROCESS EXIT — the session log has no
  *     `agent_end` event, so the tailer emits it once on `stop()`;
  *   - everything else (`session`/`model_change`/user messages/tool results/…) →
@@ -50,6 +62,77 @@ function paint(text: string, color: boolean, code: string): string {
 	return color ? `${code}${text}${RESET}` : text;
 }
 
+/**
+ * The max width of a tool-call DETAIL string (the `read <path>` / `bash <cmd>`
+ * argument summary appended after the tool name). A longer detail is truncated
+ * to this many characters with a trailing `…`, so a giant `bash` heredoc or a
+ * long path never floods the live view with one enormous line.
+ */
+const MAX_DETAIL_LENGTH = 64;
+
+/** Truncate `text` to {@link MAX_DETAIL_LENGTH} chars, appending `…` when cut. */
+function truncateDetail(text: string): string {
+	// Collapse any embedded newlines/tabs to single spaces first: a multi-line
+	// `bash` command must stay ONE line in the tail view.
+	const oneLine = text.replace(/\s+/g, ' ').trim();
+	if (oneLine.length <= MAX_DETAIL_LENGTH) {
+		return oneLine;
+	}
+	return `${oneLine.slice(0, MAX_DETAIL_LENGTH)}…`;
+}
+
+/**
+ * The FIRST non-empty string among `keys` in a tool-call's arguments object, or
+ * `undefined` when the args are absent / none of the keys carry a string. The
+ * args live under `arguments` (pi's canonical key) OR `args` (the variant seen
+ * in some session records), mirroring the `name || toolName` defensiveness used
+ * for the tool name itself.
+ */
+function firstArgString(
+	part: Record<string, unknown>,
+	keys: readonly string[],
+): string | undefined {
+	const rawArgs =
+		(typeof part.arguments === 'object' && part.arguments) ||
+		(typeof part.args === 'object' && part.args) ||
+		undefined;
+	if (!rawArgs || rawArgs === null) {
+		return undefined;
+	}
+	const args = rawArgs as Record<string, unknown>;
+	for (const key of keys) {
+		const value = args[key];
+		if (typeof value === 'string' && value !== '') {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * The high-signal ARGUMENT to show after a tool name, chosen per tool so the
+ * `▶ <name>` marker reads like the agent's actual action (`▶ read work/x.md`,
+ * `▶ bash pnpm -r build`). The mapping mirrors this harness's own tool set
+ * (read/edit/write/grep/find/ls take a `path`; bash a `command`; grep a
+ * `pattern`; find/ls a `pattern`/`path`); any unmapped tool falls back to a
+ * generic `path`/`command`/`pattern`/`query` probe so a new tool still shows
+ * *something* useful. Returns `''` when no informative arg is present.
+ */
+function toolCallDetail(name: string, part: Record<string, unknown>): string {
+	const byTool: Record<string, readonly string[]> = {
+		read: ['path'],
+		edit: ['path'],
+		write: ['path'],
+		ls: ['path'],
+		find: ['pattern', 'path'],
+		grep: ['pattern', 'path'],
+		bash: ['command'],
+	};
+	const keys = byTool[name] ?? ['path', 'command', 'pattern', 'query', 'file'];
+	const detail = firstArgString(part, keys);
+	return detail === undefined ? '' : truncateDetail(detail);
+}
+
 /**
  * A structural view of the pi SESSION-LOG records we classify. It mirrors the
  * `@earendil-works/pi-coding-agent` `SessionEntry` / `SessionMessageEntry`
@@ -94,9 +177,10 @@ export function boundaryLine(label: string, color: boolean): string {
  *   - a `{type:"message", message:{role:"assistant", content}}` record → for each
  *     `content[]` part: a `text` part yields its text (parts concatenated into
  *     ONE line, like the old `jq` `.content[]` select); a `toolCall` part yields
- *     `▶ <name>` (cyan; `name` OR `toolName`, defaulting to `tool`); a `thinking`
- *     part (and anything else) is skipped. A plain-string `content` yields one
- *     text line.
+ *     `▶ <name> <detail>` (cyan; `name` OR `toolName`, defaulting to `tool`;
+ *     `<detail>` is the per-tool argument summary, truncated to 64 chars with a
+ *     `…`); a `thinking` part (and anything else) is skipped. A plain-string
+ *     `content` yields one text line.
  *   - everything else (`session`/`model_change`/`thinking_level_change`, user
  *     messages, tool results, blank/malformed lines) → `[]` (skipped).
  *
@@ -138,7 +222,9 @@ export function formatWatchEvent(line: string, color: boolean): string[] {
  * pi-remote's `session-pool.ts` reference parser. The `text` parts are
  * concatenated into a SINGLE leading line (so a multi-part assistant turn reads
  * as one sentence, as `ar-run.sh --watch` showed it); each `toolCall` part adds a
- * `▶ <name>` line after it. A plain-string content yields the single text line.
+ * `▶ <name> <detail>` line after it (`<detail>` = the tool's high-signal
+ * argument, truncated to 64 chars). A plain-string content yields the single
+ * text line.
  * `thinking` parts and any other block type are skipped.
  */
 function assistantLines(content: unknown, color: boolean): string[] {
@@ -160,7 +246,9 @@ function assistantLines(content: unknown, color: boolean): string[] {
 				(typeof p.name === 'string' && p.name !== '' && p.name) ||
 				(typeof p.toolName === 'string' && p.toolName !== '' && p.toolName) ||
 				'tool';
-			lines.push(paint(`▶ ${name}`, color, CYAN));
+			const detail = toolCallDetail(name, p);
+			const label = detail === '' ? name : `${name} ${detail}`;
+			lines.push(paint(`▶ ${label}`, color, CYAN));
 		}
 		// `text` is collected by assistantContentText; `thinking` and any other
 		// block type are skipped.
@@ -203,6 +291,13 @@ function assistantContentText(content: unknown): string {
  * message:{role:"assistant", content[]}}` records, takes the LAST one carrying
  * non-empty `text`, and returns its concatenated text.
  *
+ * Kept as a PURE `string → string | undefined` function on purpose: the pi
+ * adapter reads the session file and passes the JSONL text in, but a future
+ * stream/HTTP-shaped harness (opencode-style) can accumulate its own event
+ * stream into the same JSONL-shaped text and reuse this reader unchanged — the
+ * file shape does NOT leak through the `LaunchResult.output` seam (Option C).
+ * See `work/notes/findings/pi-harness-channels.md` (task `pi-harness-polish`).
+ *
  * Returns `undefined` when the log has no assistant text at all — an absent log,
  * a malformed/short log, or a run whose only assistant turn was tool-calls (no
  * `text` part). A tool-only assistant turn is NOT a final answer, so a LATER

package/src/work-layout.ts

@@ -74,7 +74,7 @@ export const WORK_ROOT = 'work' as const;
  * key-only relabel, this batch moves the folders too, so the KEY and VALUE change
  * together and the self-renaming-folder guard stays green. The KEY rename is a
  * mechanical relabel of the key literal at each call site (behaviour-preserving);
- * the legacy frontmatter `prd:` field survives ONLY as un-migrated on-disk DATA the
+ * the legacy frontmatter ''prd:'' field survives ONLY as un-migrated on-disk DATA the
  * `dorfl prd-to-spec` command textually converts to `spec:` (HARD CUTOVER: it is no
  * longer READ by `parseFrontmatter` — `spec:` is the only read key); the
  * `--specs-land-in` flag/`specsLandIn` config + the
@@ -219,12 +219,15 @@ export type TaskResolutionFolder =
 /**
  * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
  * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
- * `needs-attention`, `done`.
+ * `done`. `needs-attention` was dropped post-cutover
+ * (`finish-needs-attention-folder-cutover-remove-legacy-recovery-readers`, ratified
+ * in `docs/adr/needs-attention-folder-cutover-followup-nits.md`): the folder is
+ * retired — a stuck item is the per-item lock `state: stuck` with the body resting
+ * in `tasks/ready/`, so no task ever resides in `work/needs-attention/`.
  */
 export const TASK_LIFECYCLE_FOLDERS = [
 	'tasks-ready',
 	'in-progress',
-	'needs-attention',
 	'done',
 ] as const satisfies readonly WorkFolderKey[];
 

package/src/workspace.ts

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