@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/extensions/output-style/README.md

@@ -0,0 +1,58 @@
+# Output Style
+
+Appends the always-on reply shape to the PI system prompt once per user prompt.
+
+This is the second slice of `docs/ideas/improve-pi-system-prompt.md`: the first
+(`agent-guardrails`) stops wasted work; this one stops the answer getting buried in
+it. The extension injects a stable block via the `before_agent_start` hook — which
+fires once per user prompt, before the agent loop — so the rules apply to every
+turn of the run without rewriting Pi's default prompt.
+
+## Rules
+
+- **Lead with the action** — the first line is the answer, command, path, or next
+  action; multi-step work is numbered; the reply ends with one next step.
+- **Keep the prose short** — no preamble, no recap, no closing offer; five items
+  per list at most; one topic per reply.
+- **Write Simplified Technical English (ASD-STE100)** — active voice, 20-word
+  sentences for instructions and 25-word sentences for description, verb over
+  noun, one word one meaning, literal words, no marketing adjectives, articles
+  kept.
+- **Restate the context** — never cite a bead, ticket, phase, or stage by ID alone;
+  say what it is in plain words first, and restate state after a gap or topic
+  switch.
+
+The rules shape the reply, never the work. When a rule would delete the answer,
+the task wins.
+
+## Structure
+
+```
+output-style/
+├── README.md              # This file
+├── index.ts               # Extension entry point — appends on before_agent_start
+├── output-style.ts        # Loads the block + appendOutputStyle composition
+├── output-style.md        # The block text (single source, also shipped to Claude)
+├── output-style.test.ts   # Composition tests
+├── package.json
+└── tsconfig.json
+```
+
+## Testing
+
+```bash
+cd extensions/output-style
+node --test --import tsx/esm output-style.test.ts
+```
+
+## Design notes
+
+- The block is a stable constant appended after any chained system-prompt changes,
+  so the prompt-cache prefix is preserved.
+- `appendOutputStyle` is idempotent — a prompt that already carries the marker is
+  returned unchanged, so a duplicate extension load cannot double the rules.
+- Separate from `agent-guardrails` because it is a different failure: guardrails
+  govern *whether* work continues, this governs *how the result is reported*.
+- The prose lives in `output-style.md`, not in the TypeScript, because there is a
+  second consumer: `agent-cortex install claude` wraps that file in the managed
+  `~/.claude/CLAUDE.md` section. One file, two harnesses, no drift.

package/extensions/output-style/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Output Style Extension
+ *
+ * Appends the always-on reply shape to the PI system prompt on every turn: lead
+ * with the action, write in Simplified Technical English (ASD-STE100), restate the
+ * context the reader cannot remember (the second slice of
+ * docs/ideas/improve-pi-system-prompt.md).
+ *
+ * The block is stable text appended after any chained system-prompt changes, so it
+ * keeps the prompt-cache prefix intact while remaining authoritative for the model.
+ * See output-style.ts for the rules and appendOutputStyle for composition.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendOutputStyle } from "./output-style.ts";
+
+export { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+export default function outputStyleExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => {
+    return { systemPrompt: appendOutputStyle(event.systemPrompt) };
+  });
+}

package/extensions/output-style/output-style.md

@@ -0,0 +1,43 @@
+## Output style (agent-cortex)
+
+How every reply is written. These rules shape the reply, never the work: do all
+the analysis and tool calls the task needs, then report the result this way. If a
+rule would delete the answer itself, the task wins; the shape stays.
+
+### Lead with the action
+
+- The first line is the answer, the command, the path, or the next action. Not
+  context, not a plan, not "Let me…".
+- Number multi-step work. One bounded action per step.
+- End with one concrete next step. Omit it when the work is finished.
+
+### Keep the prose short
+
+- No preamble ("Great question", "I'll now…"), no recap of work just completed,
+  no closing offer ("Let me know if…", "Hope this helps").
+- Five items maximum per list. Rank them; group related items.
+- One topic per reply. Name a tangent in one line at the end, then stop.
+
+### Write Simplified Technical English (ASD-STE100)
+
+- Active voice. Imperative for instructions.
+- Sentence limit: 20 words for instructions, 25 for descriptive text. One
+  instruction per sentence.
+- Use the verb, not the noun: "check the file", not "perform a check of the file".
+- One word, one meaning: pick the term for a thing, then reuse it.
+- Literal words only. No idioms, metaphors, or figures of speech ("circle back",
+  "under the hood", "ballpark").
+- No marketing adjectives or filler ("seamless", "robust", "comprehensive").
+- Keep articles and subjects. Do not compress into fragments that lose meaning.
+- Give times in concrete units ("about 10 minutes"), never "a bit of work".
+
+### Restate the context, never assume it
+
+The reader cannot hold earlier turns in working memory.
+
+- Never name a bead, ticket, phase, or pipeline stage by ID or number alone. Say
+  what it is in plain words first — "the login fix, verify step (bd-142)" — and
+  give the ID at most once.
+- After a gap, a topic switch, or a long tool run, restate in one line: what is
+  done, what is next.
+- Mark progress concretely: "Step 2 of 4 done: schema updated."

package/extensions/output-style/output-style.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+// ─── appendOutputStyle ────────────────────────────────────────────────────────
+
+describe("appendOutputStyle", () => {
+  it("appends the output-style block after the base prompt", () => {
+    const result = appendOutputStyle("You are a helpful agent.");
+
+    assert.ok(result.startsWith("You are a helpful agent."));
+    assert.ok(result.includes(OUTPUT_STYLE));
+  });
+
+  it("preserves a chained base prompt from earlier handlers", () => {
+    const base = "Base prompt.\n\n---\nAgent mode instructions.";
+    const result = appendOutputStyle(base);
+
+    assert.ok(result.startsWith(base));
+  });
+
+  it("trims trailing whitespace before appending", () => {
+    const result = appendOutputStyle("Base prompt.\n\n");
+
+    assert.equal(result, `Base prompt.\n\n${OUTPUT_STYLE}`);
+  });
+
+  it("keeps a block appended by another extension", () => {
+    const withGuardrails = "Base prompt.\n\n## Operating discipline (agent-cortex)\n\nRules.\n";
+    const result = appendOutputStyle(withGuardrails);
+
+    assert.ok(result.includes("## Operating discipline (agent-cortex)"));
+    assert.ok(result.endsWith(OUTPUT_STYLE));
+  });
+
+  it("is idempotent when applied twice", () => {
+    const once = appendOutputStyle("Base prompt.");
+    const twice = appendOutputStyle(once);
+
+    assert.equal(twice, once);
+    assert.equal(twice.split(OUTPUT_STYLE_MARKER).length - 1, 1);
+  });
+
+  it("returns the prompt unchanged when the output style is already present", () => {
+    const existing = `Base prompt.\n\n${OUTPUT_STYLE}`;
+
+    assert.equal(appendOutputStyle(existing), existing);
+  });
+});

package/extensions/output-style/output-style.ts

@@ -0,0 +1,32 @@
+/**
+ * Output style for the PI system prompt.
+ *
+ * The second slice of docs/ideas/improve-pi-system-prompt.md: the reply shape, not
+ * the task discipline. Three concerns, in order — lead with the action, write in
+ * Simplified Technical English, restate the context the reader cannot remember.
+ *
+ * The prose lives in output-style.md so one file feeds both harnesses: this
+ * extension appends it to the PI system prompt, and the Claude installer wraps it
+ * in a managed CLAUDE.md section. It is read once at load, so the appended text is
+ * stable across turns and keeps the prompt-cache prefix intact. The marker doubles
+ * as an idempotency guard: a chained prompt that already carries the block is
+ * returned unchanged.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const OUTPUT_STYLE_MARKER = "## Output style (agent-cortex)";
+
+export const OUTPUT_STYLE = readFileSync(new URL("./output-style.md", import.meta.url), "utf-8");
+
+/**
+ * Append the output-style block to a system prompt.
+ *
+ * The base prompt is preserved verbatim (minus trailing whitespace) so callers can
+ * chain this after other `before_agent_start` handlers. Idempotent: a prompt that
+ * already contains the marker is returned unchanged.
+ */
+export function appendOutputStyle(systemPrompt: string): string {
+  if (systemPrompt.includes(OUTPUT_STYLE_MARKER)) return systemPrompt;
+  return `${systemPrompt.trimEnd()}\n\n${OUTPUT_STYLE}`;
+}

package/extensions/output-style/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/output-style",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm output-style.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/hooks/claude/scripts/notify.mjs

@@ -20,6 +20,7 @@ for await (const chunk of process.stdin) {
   raw += chunk;
 }
 
+/** @type {{ message?: unknown, title?: unknown, notification_type?: unknown }} */
 let payload = {};
 try {
   payload = raw.trim() ? JSON.parse(raw) : {};
@@ -36,7 +37,13 @@ const type = typeof payload.notification_type === "string" ? payload.notificatio
 
 process.stdout.write(JSON.stringify({ terminalSequence: pickSequence(title, message, type) }) + "\n");
 
-/** Pick an OSC notification escape sequence for the detected terminal. */
+/**
+ * Pick an OSC notification escape sequence for the detected terminal.
+ * @param {string} title
+ * @param {string} message
+ * @param {string} type
+ * @returns {string}
+ */
 function pickSequence(title, message, type) {
   const body = message.replace(/\u001b/g, "").replace(/\n/g, " ").trim();
   const label = type ? `${type}: ${title}` : title;

package/lib/cli.mjs

@@ -1,9 +1,28 @@
+/**
+ * Result of parsing the CLI argv. Every branch returns `command`; the rest are
+ * populated only for the commands that accept them.
+ * @typedef {object} ParsedArgs
+ * @property {"help" | "version" | "install" | "migrate" | "unknown"} command
+ * @property {string | null} [harness]
+ * @property {string} [name]
+ * @property {string} [optionError]
+ * @property {boolean} [dryRun]
+ * @property {string} [output]
+ * @property {string} [pluginRoot]
+ * @property {boolean} [requireRegister]
+ * @property {boolean} [apply]
+ * @property {string} [dir]
+ */
+
+/** @typedef {{ key: string, boolean?: boolean }} OptionSpec */
+
 const SUPPORTED_HARNESSES = ["claude", "pi"];
 
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
 // malformed options surface as `optionError` on the parsed result; the CLI
 // prints them and exits 1.
+/** @type {Record<string, OptionSpec>} */
 const INSTALL_OPTIONS = {
   "--dry-run": { key: "dryRun", boolean: true },
   "--output": { key: "output" },
@@ -11,11 +30,22 @@ const INSTALL_OPTIONS = {
   "--require-register": { key: "requireRegister", boolean: true },
 };
 
+/**
+ * Parse the CLI argv.
+ * @param {string[]} argv
+ * @returns {ParsedArgs}
+ */
 export function parseArgs(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     return { command: "help" };
   }
 
+  // Like `--help`, the version flags are only recognised as the first argument,
+  // so they never shadow a command's own options.
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    return { command: "version" };
+  }
+
   const [command, ...rest] = argv;
 
   if (command === "install") {
@@ -26,6 +56,7 @@ export function parseArgs(argv) {
       i = 1;
     }
 
+    /** @type {Record<string, string | true>} */
     const options = {};
     for (; i < rest.length; i++) {
       const arg = rest[i];
@@ -57,9 +88,54 @@ export function parseArgs(argv) {
     return { command: "install", harness, ...options };
   }
 
+  if (command === "migrate") {
+    // Dry run is the default, so `--apply` is the only state-changing flag;
+    // `--dry-run` stays accepted for scripts that pass it explicitly. `--dir`
+    // points the ideas step at a workspace that keeps its idea files elsewhere.
+    let sawApply = false;
+    let sawDryRun = false;
+    /** @type {string | undefined} */
+    let dir;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--help" || arg === "-h") return { command: "help" };
+      if (arg === "--apply") {
+        sawApply = true;
+        continue;
+      }
+      if (arg === "--dry-run") {
+        sawDryRun = true;
+        continue;
+      }
+      // Support both `--dir=<path>` and `--dir <path>`, like install's `--output`.
+      const inlineDir = arg.startsWith("--dir=") ? arg.slice("--dir=".length) : null;
+      if (inlineDir !== null && inlineDir !== "") {
+        dir = inlineDir;
+        continue;
+      }
+      if (arg === "--dir" || inlineDir !== null) {
+        const value = rest[i + 1];
+        if (inlineDir !== null || value == null || value.startsWith("--")) {
+          return { command: "migrate", optionError: `Missing value for "--dir". Run "agent-cortex --help" for usage.` };
+        }
+        dir = value;
+        i += 1;
+        continue;
+      }
+      return { command: "migrate", optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
+    }
+    if (sawApply && sawDryRun) {
+      return { command: "migrate", optionError: '"--apply" and "--dry-run" are mutually exclusive.' };
+    }
+    return dir === undefined ? { command: "migrate", apply: sawApply } : { command: "migrate", apply: sawApply, dir };
+  }
+
   return { command: "unknown", name: command };
 }
 
+/**
+ * @returns {string}
+ */
 export function buildHelpText() {
   return `Usage: agent-cortex <command> [options]
 
@@ -125,11 +201,24 @@ Commands:
                                               cannot register the staged package
                                               (missing from PATH); default warns and
                                               prints the manual commands
-  --help, -h          Show this help text`;
+  migrate             Migrate the current beads workspace to the latest
+                      agent-cortex migration version, applying versioned steps
+                      in order (repo-agnostic — works in any beads workspace)
+                      Options:
+                        (no option)     Dry run — print the pending plan, write nothing
+                        --apply         Apply every pending step, verifying each
+                        --dir <path>    Read idea files from <path> instead of
+                                        docs/ideas (step v2's source)
+  --help, -h          Show this help text
+  --version, -V       Print the package version`;
 }
 
+/**
+ * @param {string | null | undefined} harness
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
 export function validateHarness(harness) {
-  if (harness === null) {
+  if (harness === null || harness === undefined) {
     return {
       ok: false,
       error: `Missing harness argument. Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -13,12 +13,35 @@
   "bin": {
     "agent-cortex": "./bin/agent-cortex.mjs"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "skills/",
+    "agents/",
+    "extensions/*.ts",
+    "extensions/lib/",
+    "extensions/*/*.ts",
+    "extensions/*/*.md",
+    "extensions/*/package.json",
+    "extensions/*/agents/",
+    "extensions/*/prompts/",
+    "hooks/",
+    "claude/",
+    "claude-extras/",
+    "token-map.json",
+    "token-map.README.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
+    "@types/node": "^22.20.1",
     "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
     "yaml": "^2.0.0"
   },
   "pi": {
@@ -35,13 +58,15 @@
   },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
-    "lint": "pnpm typecheck && pnpm check:sync",
+    "lint": "pnpm typecheck && pnpm check:sync && pnpm check:skills",
     "check:sync": "node scripts/check-no-sync.mjs",
+    "check:skills": "node scripts/check-skill-frontmatter.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
-    "typecheck": "pnpm -r typecheck",
+    "typecheck": "tsc --noEmit -p tsconfig.json && pnpm -r typecheck",
+    "verify": "pnpm typecheck && pnpm test",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
+    "publish-package": "pnpm verify && TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "publish-noop": "echo 'No publish: the merged PR carries the no-publish label.'",
     "release": "changeset publish"
   }

package/scripts/check-changeset.mjs

@@ -10,6 +10,10 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
 function readLabels(raw) {
   try {
     return JSON.parse(raw);

package/scripts/check-no-sync.mjs

@@ -14,7 +14,11 @@ const SELF = "scripts/check-no-sync.mjs";
 
 const SYNC_CALL = /\b\w*Sync\s*\(/;
 
-/** Recursively collect files under dir, skipping this script and node_modules. */
+/**
+ * Recursively collect files under dir, skipping this script and node_modules.
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
 async function collect(dir) {
   const out = [];
   const entries = await readdir(dir, { withFileTypes: true });

package/scripts/check-skill-frontmatter.mjs

@@ -0,0 +1,21 @@
+// Repo convention: every SKILL.md frontmatter must parse and declare a name and
+// description, because PI silently drops a skill whose frontmatter throws. Runs
+// via `pnpm lint` (CI) and locally. Scans the repository root, so both skills/
+// and repo-local .agents/skills/ are covered.
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSkills } from "./lib/skill-frontmatter.mjs";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+const { checked, failures } = await checkSkills({ root: ROOT });
+
+if (failures.length > 0) {
+  console.error("✗ Invalid SKILL.md frontmatter — PI would silently drop these skills:");
+  for (const { file, errors } of failures) {
+    for (const error of errors) console.error(`  ${file}: ${error}`);
+  }
+  process.exit(1);
+}
+
+console.log(`✓ SKILL.md frontmatter valid (${checked} files)`);

package/scripts/lib/compose-agent.mjs

@@ -32,7 +32,49 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
-/** True when a path exists (stat succeeds). */
+/** @typedef {{ base: string, relative: string }} PathSpec */
+
+/**
+ * Parsed token-map.json. `tools` maps a canonical tool key to its per-harness
+ * name (null = the harness has no equivalent); `paths` maps a path key to its
+ * per-harness spec (a literal string, or a {base, relative} pair resolved
+ * recursively through the same table).
+ * @typedef {object} TokenMap
+ * @property {number} [version]
+ * @property {Record<string, Record<string, string | null>>} tools
+ * @property {Record<string, Record<string, string | PathSpec>>} paths
+ */
+
+/**
+ * Options shared by the composer entry points.
+ * @typedef {object} ComposeOptions
+ * @property {boolean} [dropNullTools]
+ * @property {string} [pluginRoot]
+ * @property {boolean} [resolveRelativePaths]
+ * @property {(message: string) => void} [warn]
+ * @property {string} [context]
+ */
+
+/**
+ * Parsed and schema-checked harness frontmatter.json.
+ * @typedef {object} AgentFrontmatter
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} tools
+ * @property {string} [model]
+ * @property {string} [argumentHint]
+ */
+
+/**
+ * A composed agent: its frontmatter plus the substituted body.
+ * @typedef {AgentFrontmatter & { body: string }} ComposedAgent
+ */
+
+/**
+ * True when a path exists (stat succeeds).
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 async function pathExists(p) {
   try {
     await stat(p);
@@ -47,6 +89,7 @@ async function pathExists(p) {
 const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
 const PATH_RE = /\{\{PATH:([^}]+)\}\}/g;
 
+/** @returns {void} */
 function noop() {}
 
 /**
@@ -62,8 +105,8 @@ function noop() {}
  *
  * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
  * @param {string} harness  Harness id: "claude" | "pi"
- * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
- * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
+ * @param {TokenMap} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {ComposeOptions} [options]  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
  * @returns {string}
  */
 export function substituteTokens(content, harness, tokenMap, options = {}) {
@@ -100,7 +143,8 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  * @param {string} root    Package root (contains agents/ and token-map.json)
  * @param {string} name    Agent directory name (e.g. "ralph", "plan")
  * @param {string} harness Harness id: "claude" | "pi"
- * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
+ * @param {ComposeOptions} [options]
+ * @returns {Promise<ComposedAgent>}
  */
 export async function composeAgent(root, name, harness, options = {}) {
   const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
@@ -144,14 +188,21 @@ export async function composeAgent(root, name, harness, options = {}) {
 const REQUIRED_FIELDS = ["name", "description", "tools"];
 const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
-/** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
+/**
+ * Parse and schema-check a harness frontmatter.json (strict, per agents/README.md).
+ * @param {string} path
+ * @param {string} name
+ * @param {string} harness
+ * @returns {Promise<AgentFrontmatter>}
+ */
 async function parseFrontmatter(path, name, harness) {
   const raw = await readFile(path, "utf-8");
+  /** @type {Record<string, unknown>} */
   let fm;
   try {
     fm = JSON.parse(raw);
   } catch (err) {
-    throw new Error(`agent "${name}": invalid JSON in ${path}: ${err.message}`);
+    throw new Error(`agent "${name}": invalid JSON in ${path}: ${/** @type {Error} */ (err).message}`);
   }
   if (typeof fm !== "object" || fm === null) {
     throw new Error(`agent "${name}": ${path} must be a JSON object`);
@@ -188,6 +239,11 @@ async function parseFrontmatter(path, name, harness) {
  * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
  * plugin_root base and bare relative paths resolve against the actual install
  * layout instead.
+ * @param {string} arg
+ * @param {string} harness
+ * @param {TokenMap} tokenMap
+ * @param {ComposeOptions} [opts]
+ * @returns {string}
  */
 function resolvePath(arg, harness, tokenMap, opts = {}) {
   const entry = tokenMap.paths?.[arg];
@@ -217,9 +273,9 @@ function resolvePath(arg, harness, tokenMap, opts = {}) {
  * translation in extensions/agent-modes/discover.ts.
  *
  * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
- * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {TokenMap} tokenMap Parsed token-map.json (from loadTokenMap)
  * @param {string} harness  Harness id: "claude" | "pi"
- * @param {object} options  { warn }
+ * @param {ComposeOptions} [options]  { warn }
  * @returns {string[]}
  */
 export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}) {
@@ -242,7 +298,11 @@ export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}
 
 // ─── Token map ───────────────────────────────────────────────────────────────
 
-/** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
+/**
+ * Load token-map.json from the package root; missing/incomplete maps hard-fail.
+ * @param {string} root
+ * @returns {Promise<TokenMap>}
+ */
 export async function loadTokenMap(root) {
   const path = join(root, "token-map.json");
   let raw;

package/scripts/lib/fs.mjs

@@ -12,7 +12,11 @@
 
 import { stat } from "node:fs/promises";
 
-/** True when `p` exists and is a regular file; false on any error. */
+/**
+ * True when `p` exists and is a regular file; false on any error.
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 export async function isFile(p) {
   try {
     return (await stat(p)).isFile();
@@ -21,7 +25,11 @@ export async function isFile(p) {
   }
 }
 
-/** True when `p` exists and is a directory; false on any error. */
+/**
+ * True when `p` exists and is a directory; false on any error.
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
 export async function isDirectory(p) {
   try {
     return (await stat(p)).isDirectory();