catherd-cli 0.2.1 → 1.0.0

package/src/domain/profile.ts

@@ -0,0 +1,383 @@
+import { z } from "zod";
+import type { Budget } from "./budget.ts";
+import { BILLING_KEYS, type BillingKey } from "./catalog.ts";
+import { BILLING_MODES, type BillingMode, DEFAULT_BILLING } from "./cost.ts";
+import { CatherdError } from "./errors.ts";
+import { ADAPTER_IDS, parseRung, tryParseRung } from "./ids.ts";
+import { ACCESS, type Access } from "./record.ts";
+import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
+import { isPlain, slug } from "./util.ts";
+
+/** Spec §3.4: every file carries its schema version; a profile is schema 1. */
+const PROFILE_SCHEMA = 1;
+
+/** Profile names end up in agent names (`catherd-<profile>-…`), which Claude Code wants lowercase. */
+export const PROFILE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+export function assertProfileName(name: string): string {
+  if (!PROFILE_NAME.test(name))
+    throw new CatherdError("E_INPUT_INVALID", `bad profile name "${name}"`, {
+      fix: "use lowercase letters, digits and '-', at most 32, starting with a letter or digit",
+    });
+  return name;
+}
+
+export const NOTIFY = ["milestone", "finish", "blocked"] as const;
+export type NotifyMoment = (typeof NOTIFY)[number];
+
+/** The harnesses a profile can isolate (spec §7.1 `harness`); the native `claude` path has none. */
+export const HARNESS_KEYS = ADAPTER_IDS;
+
+const isRung = (s: string): boolean => tryParseRung(s) !== null;
+/** A `<backend>:<model>#<effort>` rung, for input schemas; stored profiles keep any string and validate. */
+const RungSchema = z.string().refine(isRung, "a rung is <backend>:<model>#<effort>");
+
+const positive = z.number().positive();
+
+// Stored files: every level is loose, so fields a newer catherd wrote survive a rewrite (spec §3.4), and
+// rung strings are checked by validateProfile rather than making the whole file unreadable. The same holds
+// for values: a stored enum takes any string, resolveProfile reads one it does not know as STORED_FALLBACK
+// says, validateProfile warns, and the file keeps it.
+const RoleDocSchema = z.looseObject({
+  enabled: z.boolean().optional(),
+  access: z.string().optional(),
+  rungs: z.array(z.string()).optional(),
+  defaultRung: z.string().optional(),
+});
+
+export const ProfileDocSchema = z.looseObject({
+  schema: z.literal(PROFILE_SCHEMA),
+  name: z.string().optional(),
+  objective: z.string().optional(),
+  jev: z.looseObject({ use: z.string().optional() }).optional(),
+  billing: z.record(z.string(), z.string()).optional(),
+  roles: z.record(z.string(), RoleDocSchema).optional(),
+  harness: z.record(z.string(), z.looseObject({ isolated: z.boolean().optional() })).optional(),
+  failover: z.record(z.string(), z.string()).optional(),
+  budget: z
+    .looseObject({ minutes: positive.optional(), tokens: positive.optional(), usd: positive.optional() })
+    .optional(),
+  timeouts: z.looseObject({ idleMin: positive.optional(), wallMin: positive.optional() }).optional(),
+  preflight: z.looseObject({ confirm: z.boolean().optional() }).optional(),
+  lock: z
+    .looseObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]).optional() })
+    .optional(),
+  notify: z.array(z.string()).optional(),
+});
+export type ProfileDoc = z.infer<typeof ProfileDocSchema>;
+
+const OBJECTIVES = ["cost", "speed"] as const;
+const JEV_USES = ["auto", "off"] as const;
+const known = <T extends string>(values: readonly T[], v: string | undefined): v is T =>
+  v !== undefined && (values as readonly string[]).includes(v);
+
+/**
+ * How a stored value this catherd does not know (a newer one wrote it) is read, always the cautious way:
+ * access as read-only, billing as the key's default mode, Jev as off, so nothing is sent or written that
+ * the value may not allow; an unknown notify moment is skipped.
+ */
+const STORED_FALLBACK = {
+  objective: "cost",
+  jevUse: "off",
+  access: "read-only",
+  billing: (key: string): BillingMode => DEFAULT_BILLING[key as BillingKey] ?? "metered",
+} as const;
+
+/** A stored value this catherd does not know, with what it is read as. */
+export interface UnknownValue {
+  path: string;
+  value: string;
+  readAs: string;
+}
+
+/** Every stored enum value in `doc` this catherd does not know (spec §3.4: newer files stay readable). */
+export function unknownValues(doc: ProfileDoc): UnknownValue[] {
+  const out: UnknownValue[] = [];
+  const check = (path: string, values: readonly string[], v: string | undefined, readAs: string) => {
+    if (v !== undefined && !values.includes(v)) out.push({ path, value: v, readAs });
+  };
+  check("objective", OBJECTIVES, doc.objective, STORED_FALLBACK.objective);
+  check("jev.use", JEV_USES, doc.jev?.use, STORED_FALLBACK.jevUse);
+  for (const [k, v] of Object.entries(doc.billing ?? {}))
+    check(`billing.${k}`, BILLING_MODES, v, STORED_FALLBACK.billing(k));
+  for (const role of ROLES)
+    check(`roles.${role}.access`, ACCESS, doc.roles?.[role]?.access, STORED_FALLBACK.access);
+  for (const n of doc.notify ?? []) check("notify", NOTIFY, n, "skipped");
+  return out;
+}
+
+// a type, not an interface, so the built-in roles can be written into a loose (indexed) document
+export type RoleConfig = {
+  enabled: boolean;
+  access: Access;
+  /** in ladder order, each `backend:model#effort`; `claude:` runs as a native subagent, `claude-code:` headless */
+  rungs: string[];
+  defaultRung?: string;
+};
+
+/** A profile with every default filled in: what the run engine, the CLI and the agent files read. */
+export interface Profile {
+  name: string;
+  objective: "cost" | "speed";
+  jev: { use: "auto" | "off" };
+  billing: Record<string, BillingMode>;
+  roles: Record<Role, RoleConfig>;
+  harness: Record<string, { isolated: boolean }>;
+  failover: Record<string, string>;
+  budget: Budget;
+  timeouts: { idleMin: number; wallMin: number };
+  preflight: { confirm: boolean };
+  lock: { heavy: number | "cpus/2" };
+  notify: NotifyMoment[];
+}
+
+const LUNA_HIGH = "codex:gpt-6-luna#high";
+const SOL = (effort: string) => `codex:gpt-6-sol#${effort}`;
+
+/**
+ * Spec §7.2, the owner's setup (Codex on a ChatGPT plan, a Claude plan, OpenCode Go). A role missing
+ * from a profile takes its entry here. Architect and verifier run as native Claude subagents (D3).
+ */
+export const BUILTIN_ROLES: Record<Role, RoleConfig> = {
+  architect: { enabled: true, access: DEFAULT_ACCESS.architect, rungs: ["claude:claude-opus-5-5#high"] },
+  verifier: { enabled: true, access: DEFAULT_ACCESS.verifier, rungs: ["claude:claude-opus-5-5#low"] },
+  worker: {
+    enabled: true,
+    access: DEFAULT_ACCESS.worker,
+    rungs: [LUNA_HIGH, SOL("medium"), SOL("high"), SOL("xhigh")],
+    defaultRung: SOL("medium"),
+  },
+  reviewer: { enabled: true, access: DEFAULT_ACCESS.reviewer, rungs: [SOL("high")] },
+  "ui-reviewer": { enabled: true, access: DEFAULT_ACCESS["ui-reviewer"], rungs: [SOL("medium")] },
+  artist: { enabled: true, access: DEFAULT_ACCESS.artist, rungs: [SOL("medium")] },
+  writer: { enabled: true, access: DEFAULT_ACCESS.writer, rungs: [LUNA_HIGH] },
+  researcher: { enabled: true, access: DEFAULT_ACCESS.researcher, rungs: [LUNA_HIGH] },
+};
+
+/**
+ * Spec §7.2: each Codex rung fails over to the best-matching OpenCode Go model. Go serves GPT-6 Luna
+ * itself; for Sol it has no GPT model, so Kimi K3 stands in through a shipped treat-like (scores.json),
+ * which `profile show` marks inferred.
+ */
+export const DEFAULT_FAILOVER: Record<string, string> = {
+  [LUNA_HIGH]: "opencode:opencode-go/gpt-6-luna#high",
+  [SOL("medium")]: "opencode:opencode-go/kimi-k3#max",
+  [SOL("high")]: "opencode:opencode-go/kimi-k3#max",
+  [SOL("xhigh")]: "opencode:opencode-go/kimi-k3#max",
+};
+
+/** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
+const WRITTEN_BILLING: BillingKey[] = ["codex", "claude", "claude-code", "opencode-go", "opencode"];
+
+/** The full default profile document, every field written out: what `init` and `profile new` save. */
+export function defaultProfileDoc(name = "default"): ProfileDoc {
+  return {
+    schema: PROFILE_SCHEMA,
+    name,
+    objective: "cost",
+    jev: { use: "auto" },
+    billing: Object.fromEntries(WRITTEN_BILLING.map((k) => [k, DEFAULT_BILLING[k]])),
+    roles: structuredClone(BUILTIN_ROLES),
+    harness: {
+      codex: { isolated: false },
+      "claude-code": { isolated: false },
+      opencode: { isolated: false },
+    },
+    failover: { ...DEFAULT_FAILOVER },
+    budget: {},
+    timeouts: { idleMin: 15, wallMin: 90 },
+    preflight: { confirm: false },
+    lock: { heavy: "cpus/2" },
+    notify: [...NOTIFY],
+  };
+}
+
+/** Spec §7.1: every field a document leaves out takes its default; a missing role takes the built-in one. */
+export function resolveProfile(doc: ProfileDoc, name: string): Profile {
+  const roles = {} as Record<Role, RoleConfig>;
+  for (const role of ROLES) {
+    const d = doc.roles?.[role];
+    const b = BUILTIN_ROLES[role];
+    // a role that lists its own rungs never inherits the built-in default rung, which may not be among them
+    const defaultRung = d?.defaultRung ?? (d?.rungs === undefined ? b.defaultRung : undefined);
+    roles[role] = {
+      enabled: d?.enabled ?? b.enabled,
+      access:
+        d?.access === undefined
+          ? DEFAULT_ACCESS[role]
+          : known(ACCESS, d.access)
+            ? d.access
+            : STORED_FALLBACK.access,
+      rungs: [...(d?.rungs ?? b.rungs)],
+      ...(defaultRung ? { defaultRung } : {}),
+    };
+  }
+  const harness: Profile["harness"] = {};
+  for (const k of new Set([...HARNESS_KEYS, ...Object.keys(doc.harness ?? {})]))
+    harness[k] = { isolated: doc.harness?.[k]?.isolated ?? false };
+  const budget: Budget = {};
+  for (const k of ["minutes", "tokens", "usd"] as const) {
+    const v = doc.budget?.[k];
+    if (v !== undefined) budget[k] = v;
+  }
+  const billing: Record<string, BillingMode> = { ...DEFAULT_BILLING };
+  for (const [k, v] of Object.entries(doc.billing ?? {}))
+    billing[k] = known(BILLING_MODES, v) ? v : STORED_FALLBACK.billing(k);
+  const use = doc.jev?.use;
+  return {
+    name,
+    objective: known(OBJECTIVES, doc.objective) ? doc.objective : STORED_FALLBACK.objective,
+    jev: { use: use === undefined ? "auto" : known(JEV_USES, use) ? use : STORED_FALLBACK.jevUse },
+    billing,
+    roles,
+    harness,
+    failover: { ...doc.failover },
+    budget,
+    timeouts: { idleMin: doc.timeouts?.idleMin ?? 15, wallMin: doc.timeouts?.wallMin ?? 90 },
+    preflight: { confirm: doc.preflight?.confirm ?? false },
+    lock: { heavy: doc.lock?.heavy ?? "cpus/2" },
+    notify: doc.notify === undefined ? [...NOTIFY] : doc.notify.filter((n) => known(NOTIFY, n)),
+  };
+}
+
+/** Spec §7.3: `catherd-<profile>-<role>-<model slug>-<effort>`, the native subagent for a `claude:` rung. */
+export function agentName(profile: string, role: Role, rung: string): string {
+  const r = parseRung(rung);
+  return `catherd-${profile}-${role}-${slug(r.model)}-${slug(r.effort)}`;
+}
+
+// Patches: what profile_set and `catherd profile set` accept. Strict at every level, so a misspelt key is
+// refused with E_INPUT_INVALID instead of dropped (plan-2 review m9). `null` removes a map entry.
+const RolePatchSchema = z
+  .strictObject({
+    enabled: z.boolean(),
+    access: z.enum(ACCESS),
+    rungs: z.array(RungSchema),
+    defaultRung: RungSchema.nullable(),
+  })
+  .partial();
+
+export const ProfilePatchSchema = z.strictObject({
+  objective: z.enum(["cost", "speed"]).optional(),
+  jev: z.strictObject({ use: z.enum(["auto", "off"]) }).optional(),
+  billing: z.partialRecord(z.enum(BILLING_KEYS), z.enum(BILLING_MODES).nullable()).optional(),
+  roles: z.partialRecord(z.enum(ROLES), RolePatchSchema).optional(),
+  harness: z.partialRecord(z.enum(HARNESS_KEYS), z.strictObject({ isolated: z.boolean() })).optional(),
+  failover: z.record(RungSchema, RungSchema.nullable()).optional(),
+  budget: z
+    .strictObject({ minutes: positive.nullable(), tokens: positive.nullable(), usd: positive.nullable() })
+    .partial()
+    .optional(),
+  timeouts: z.strictObject({ idleMin: positive, wallMin: positive }).partial().optional(),
+  preflight: z.strictObject({ confirm: z.boolean() }).optional(),
+  lock: z.strictObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]) }).optional(),
+  notify: z.array(z.enum(NOTIFY)).optional(),
+});
+export type ProfilePatch = z.infer<typeof ProfilePatchSchema>;
+
+/** RFC 7396 merge: objects merge key by key, `null` deletes, anything else (arrays too) replaces. */
+function mergePatch(target: unknown, patch: unknown): unknown {
+  if (!isPlain(patch)) return patch;
+  const out: Record<string, unknown> = isPlain(target) ? { ...target } : {};
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete out[k];
+    else out[k] = mergePatch(out[k], v);
+  }
+  return out;
+}
+
+/** The document with `patch` applied; every field the patch does not name, known or not, is kept. */
+export function applyPatch(doc: ProfileDoc, patch: ProfilePatch): ProfileDoc {
+  return ProfileDocSchema.parse(mergePatch(doc, patch));
+}
+
+/** Map fields whose keys are rungs or billing keys, which may hold dots: the rest of the path is one key. */
+const MAP_FIELDS = new Set(["failover", "billing"]);
+const LIST_FIELDS = (keys: string[]) =>
+  (keys[0] === "roles" && keys[2] === "rungs") || (keys[0] === "notify" && keys.length === 1);
+
+/**
+ * `catherd profile set <path> <value>` as a patch. The value is JSON when it parses (numbers, booleans,
+ * `null`, arrays), else the plain word; a rung list may also be comma-separated.
+ */
+export function patchAt(path: string, raw: string): ProfilePatch {
+  const segs = path.split(".");
+  const keys =
+    MAP_FIELDS.has(segs[0] ?? "") && segs.length > 1 ? [segs[0] as string, segs.slice(1).join(".")] : segs;
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    value = raw;
+  }
+  if (LIST_FIELDS(keys) && typeof value === "string")
+    value = value
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  const patch = keys.reduceRight<unknown>((inner, k) => ({ [k]: inner }), value);
+  const r = keys.some((k) => !k) ? null : ProfilePatchSchema.safeParse(patch);
+  if (!r?.success)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `cannot set ${path} to ${raw}${r ? `: ${z.prettifyError(r.error).replace(/\n\s*/g, " ")}` : ""}`,
+      {
+        fix: "catherd profile show --json lists the fields; e.g. catherd profile set roles.worker.access read-only",
+      },
+    );
+  return r.data;
+}
+
+export interface Change {
+  path: string;
+  before: unknown;
+  after: unknown;
+}
+
+/** Leaves by dotted path; an empty object has none, so `budget: {}` → `budget.usd: 5` is one change. */
+function flatten(v: unknown, prefix: string, out: Map<string, unknown>): void {
+  if (isPlain(v)) for (const [k, x] of Object.entries(v)) flatten(x, prefix ? `${prefix}.${k}` : k, out);
+  else if (v !== undefined) out.set(prefix, v);
+}
+
+/** Every leaf that differs between two profiles; lists compare whole. */
+export function diffProfiles(a: Profile, b: Profile): Change[] {
+  const fa = new Map<string, unknown>();
+  const fb = new Map<string, unknown>();
+  flatten({ ...a, name: undefined }, "", fa);
+  flatten({ ...b, name: undefined }, "", fb);
+  const changes: Change[] = [];
+  for (const path of [...new Set([...fa.keys(), ...fb.keys()])].sort()) {
+    const before = fa.get(path) ?? null;
+    const after = fb.get(path) ?? null;
+    if (JSON.stringify(before) !== JSON.stringify(after)) changes.push({ path, before, after });
+  }
+  return changes;
+}
+
+/**
+ * The patch that turns `a` into `b`: the leaves that differ, lists whole, a removed key as `null`. Fields
+ * both documents share unchanged, known or not, are left out, so applying it over a newer copy of `a`
+ * keeps whatever else changed there. Throws E_INPUT_INVALID when `b` holds what no patch may set.
+ */
+export function patchBetween(a: ProfileDoc, b: ProfileDoc): ProfilePatch {
+  const diff = (x: unknown, y: unknown): unknown => {
+    if (!isPlain(x) || !isPlain(y)) return y;
+    const out: Record<string, unknown> = {};
+    for (const k of new Set([...Object.keys(x), ...Object.keys(y)])) {
+      if (!(k in y)) out[k] = null;
+      else if (JSON.stringify(x[k]) !== JSON.stringify(y[k])) out[k] = diff(x[k], y[k]);
+    }
+    return out;
+  };
+  const r = ProfilePatchSchema.safeParse(diff(a, b));
+  if (!r.success)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `these changes cannot be saved: ${z.prettifyError(r.error).replace(/\n\s*/g, " ")}`,
+      {
+        fix: "undo the last change, or edit the field with catherd profile set",
+      },
+    );
+  return r.data;
+}

package/src/domain/record.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+export const ACCESS = ["read-only", "workspace-write", "full"] as const;
+export type Access = (typeof ACCESS)[number];
+
+const RUN_STATUSES = ["ok", "failed", "limit", "cli-too-old", "timeout", "cancelled"] as const;
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+const REPLY_STATUSES = ["complete", "partial", "blocked", "refused"] as const;
+export type ReplyStatus = (typeof REPLY_STATUSES)[number];
+
+export interface Tokens {
+  input: number;
+  cached: number;
+  output: number;
+}
+export const ZERO_TOKENS: Readonly<Tokens> = Object.freeze({ input: 0, cached: 0, output: 0 });
+
+/** Spec §7: a thread past this many input tokens is spent; its next piece starts fresh. */
+export const THREAD_HEAVY_INPUT = 8_000_000;
+
+/** How a supervised worker ended, as the supervisor records it in exit.json. */
+export const EXIT_REASONS = [
+  "exited",
+  "after-final",
+  "idle-timeout",
+  "wall-timeout",
+  "cancelled",
+  "lost",
+] as const;
+export type ExitReason = (typeof EXIT_REASONS)[number];
+export interface ExitInfo {
+  code: number | null;
+  signal: string | null;
+  reason: ExitReason;
+  endedAt: string;
+}
+
+const TokensSchema = z.object({ input: z.number(), cached: z.number(), output: z.number() });
+
+export const RunRecordSchema = z.looseObject({
+  schema: z.literal(1),
+  runId: z.string(),
+  dispatchId: z.string(),
+  name: z.string(),
+  role: z.string(),
+  lane: z.string().nullable(),
+  backend: z.string(),
+  rung: z.string(),
+  attempt: z.number().int().min(1),
+  failoverFrom: z.string().nullable(),
+  thread: z.string().nullable(),
+  status: z.enum(RUN_STATUSES),
+  startedAt: z.string(),
+  endedAt: z.string(),
+  secs: z.number(),
+  exitCode: z.number().nullable(),
+  signal: z.string().nullable(),
+  cliVersion: z.string().nullable(),
+  tokens: TokensSchema,
+  costUsd: z.number().nullable(),
+  changedOwned: z.array(z.string()),
+  violations: z.array(z.string()),
+  /** true when git failed at finalize: changedOwned and violations are then unknown, not empty */
+  gitUnavailable: z.boolean().optional(),
+  replyStatus: z.enum(REPLY_STATUSES).nullable(),
+  replyWhy: z.string().nullable(),
+  threadHeavy: z.boolean(),
+  access: z.enum(ACCESS),
+  isolated: z.boolean(),
+  images: z.array(z.string()),
+  error: z.object({ code: z.string(), message: z.string() }).nullable(),
+  replyPath: z.string(),
+});
+export type RunRecord = z.infer<typeof RunRecordSchema>;
+
+const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
+
+/** The role's claim about its own work: the reply's last line, `STATUS: <s> — <why>`. */
+export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {
+  const last = reply.trimEnd().split("\n").at(-1)?.trim() ?? "";
+  const m = STATUS_LINE.exec(last);
+  return m ? { status: m[1] as ReplyStatus, why: (m[2] ?? "").trim() } : { status: null, why: null };
+}

package/src/{profile → domain}/role-prompts.ts

@@ -1,8 +1,8 @@
-import type { Role } from "../types.ts";
-import { VERSION } from "../version.ts";
+import type { Access } from "./record.ts";
+import type { Role } from "./roles.ts";
 
-const READ_ONLY = ["Write", "Edit", "NotebookEdit", "Agent"];
-const WRITES = ["Agent"];
+// The role prompts of the native Claude subagents, ported from 0.x (spec D9). Headless backends get the
+// same text from the orchestrator's briefs; only native agents carry it in their agent file.
 
 const RUN_FILES =
   "The run folder is outside the project. Read and write it only through the catherd MCP tools read_run_file and write_run_file (in the tool list as mcp__plugin_catherd_catherd__read_run_file and mcp__plugin_catherd_catherd__write_run_file), with the run id the orchestrator gave you. Paths are relative to the run folder.";
@@ -15,6 +15,8 @@ const architect = [
   "",
   `Start from the dossier. Open a project file yourself only to settle a decision the dossier leaves open, and read each file once. Bash is for inspection only. Change nothing in the project. ${RUN_FILES}`,
   "",
+  "When the acceptance lines include plan: <path>[, <path>…], the user already has a plan and there is no dossier. Translate it, do not design: each plan task becomes lanes, each merge request or phase a milestone with its full check. Copy the plan's decisions into plan.md and the lane files, and decide only what the plan leaves undecided.",
+  "",
   "Write plan.md with exactly these parts, in this order:",
   "",
   "1. Decisions D1…Dn: each one is a choice, the alternative you rejected, and one line on why. Cover only choices where two reasonable engineers would differ.",
@@ -22,20 +24,22 @@ const architect = [
   "3. Lanes inside each milestone, M1.L1…: each lane gives",
   "   - the files it owns (two lanes of one milestone never share a file);",
   "   - what changes, stated as behavior plus the exact signatures and data shapes it introduces;",
-  "   - its fast check: the targeted command a worker reruns while it works, seconds to a minute or two.",
+  "   - its fast check: the command a worker reruns while it works, seconds to a minute or two: its targeted tests plus the linter, and the type check when the project has one, scoped to the packages the lane owns.",
   "",
   "   Every lane of a milestone runs at the same time, so split for width: more small lanes beat one long one.",
   "4. Speed: if the full check takes more than about five minutes, name why and make speeding it up (parallel tests, one shared fixture, fewer real-time waits) a lane of the first milestone.",
   "5. Edge cases the tests must pin, one line each.",
   "6. Out of scope: what no worker may touch.",
   "",
-  "Then write one file per lane, lanes/Mx.Ly.md. It is everything that worker needs and nothing else: the lane's section, the decisions and edge cases it relies on (copied, not referenced), and the out-of-scope lines. A worker reads its lane file, never plan.md. Its first three lines are exactly:",
+  "Then write one file per lane, lanes/Mx.Ly.md. It is everything that worker needs and nothing else: the lane's section, the decisions and edge cases it relies on (copied, not referenced), and the out-of-scope lines. A worker reads its lane file, never plan.md. Its first five lines are exactly:",
   "",
   "    # Mx.Ly — <one line>",
   "    Owns: <repo-relative paths, comma-separated>",
   "    Fast check: <command>",
+  "    Kind: repo_code|terminal|ui|prose|research",
+  "    Difficulty: copy|build|logic|hard",
   "",
-  "catherd reads the Owns: line to keep two running lanes off the same file, and to tell a refusal (owned files unchanged) from work.",
+  "catherd reads the Owns: line to keep two running lanes off the same file, and to tell a refusal (owned files unchanged) from work. It reads Kind: and Difficulty: to pick the lane's model when its router is unsure.",
   "",
   "Signatures, data shapes and test case names are yours. Function bodies are the worker's. A plan that contains the implementation turns the worker into a typist and spends the most expensive model on typing.",
   "",
@@ -62,15 +66,16 @@ const verifier = [
   "- What you could not check, and why.",
 ].join("\n");
 
-const worker = [
-  "You are a worker in a catherd run. The orchestrator's message is your brief: the acceptance lines, the lane file to read, the files you own and the files you must not touch, and your fast check.",
-  "",
-  `Read your lane file first. ${RUN_FILES} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
-  "",
-  `Change only the files you own. Run your fast check until it passes. Run the full suite only if the brief says so, and wrap any full build or full test suite in: bunx catherd-cli@${VERSION} lock -- <command>. Other lanes share this machine.`,
-  "",
-  REPLY,
-].join("\n");
+const worker = (version: string) =>
+  [
+    "You are a worker in a catherd run. The orchestrator's message is your brief: the acceptance lines, the lane file to read, the files you own and the files you must not touch, and your fast check.",
+    "",
+    `Read your lane file first. ${RUN_FILES} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
+    "",
+    `Change only the files you own. Run your fast check until it passes. Run the full suite only if the brief says so, and wrap any full build or full test suite in: bunx catherd-cli@${version} lock -- <command>. Other lanes share this machine.`,
+    "",
+    REPLY,
+  ].join("\n");
 
 const reviewer = [
   "You review a milestone's diff that you did not write. The brief gives the acceptance lines and the changed files; read new files in full. Change nothing in the project.",
@@ -113,18 +118,29 @@ const writer = [
 const researcher = [
   "You answer a factual question about the code, or map it for a dossier. Change nothing in the project. Give file:line for every claim.",
   "",
-  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${RUN_FILES}`,
+  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes when the docs, the CI config or a log say so (never run the suite to find out; write "unknown" instead); the lint and type-check commands, and how to scope each to one package; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${RUN_FILES}`,
   "",
   "For a single question, reply in at most 15 lines. The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>",
 ].join("\n");
 
-export const ROLE_PROMPTS: Record<Role, { disallowedTools: string[]; body: string }> = {
-  architect: { disallowedTools: READ_ONLY, body: architect },
-  verifier: { disallowedTools: READ_ONLY, body: verifier },
-  worker: { disallowedTools: WRITES, body: worker },
-  reviewer: { disallowedTools: READ_ONLY, body: reviewer },
-  "ui-reviewer": { disallowedTools: READ_ONLY, body: uiReviewer },
-  artist: { disallowedTools: WRITES, body: artist },
-  writer: { disallowedTools: WRITES, body: writer },
-  researcher: { disallowedTools: READ_ONLY, body: researcher },
+const BODIES: Record<Role, (version: string) => string> = {
+  architect: () => architect,
+  verifier: () => verifier,
+  worker,
+  reviewer: () => reviewer,
+  "ui-reviewer": () => uiReviewer,
+  artist: () => artist,
+  writer: () => writer,
+  researcher: () => researcher,
 };
+
+/** The role's prompt; the worker's names the catherd version whose `lock` it must use. */
+export const rolePrompt = (role: Role, version: string): string => BODIES[role](version);
+
+/**
+ * Spec D10 for native subagents, whose only lever is the agent file's tool list: read-only drops the
+ * editing tools (its Bash stays, for inspection, so enforcement is advisory); every role drops Agent,
+ * so a role never spawns its own subagents.
+ */
+export const nativeDisallowedTools = (access: Access): string[] =>
+  access === "read-only" ? ["Write", "Edit", "NotebookEdit", "Agent"] : ["Agent"];

package/src/domain/roles.ts

@@ -0,0 +1,25 @@
+import type { Access } from "./record.ts";
+
+export const ROLES = [
+  "architect",
+  "verifier",
+  "worker",
+  "reviewer",
+  "ui-reviewer",
+  "artist",
+  "writer",
+  "researcher",
+] as const;
+export type Role = (typeof ROLES)[number];
+
+/** Spec §7.1: the access mode a role runs with unless its profile says otherwise. */
+export const DEFAULT_ACCESS: Record<Role, Access> = {
+  architect: "read-only",
+  reviewer: "read-only",
+  researcher: "read-only",
+  worker: "workspace-write",
+  writer: "workspace-write",
+  artist: "workspace-write",
+  verifier: "full",
+  "ui-reviewer": "full",
+};