@taicho-ai/framework 0.1.0

package/src/core/turn-audit.ts

@@ -0,0 +1,100 @@
+/** Plan 01 Phase 5 — the turn-outcome audit SEAM, moved from the UI into the engine.
+ *
+ *  Before this, `App.tsx submit()` carried two near-identical ~30-line audit blocks (chat vs @agent)
+ *  and PR #17 de-duplicated them into an App-LOCAL `recordTurnOutcome`. That still lived in the React
+ *  component, so any non-Ink caller (headless `taicho run`, tests) got run evidence but silently NO
+ *  ledger, NO task, NO replay cache. This module lifts the audit into ONE engine seam that
+ *  `executeRun` calls (guarded by `triggeredBy === "user"`), so every caller gets identical audit —
+ *  and cross-turn compaction (Plan 05 Ph3) hooks the SAME seam to write the rolling replay summary.
+ *
+ *  The seam has two halves, both keyed off the ledger (append-only TRUTH — see context-hygiene
+ *  audit decision C):
+ *   - `recordUserTurn` at run START: append the user turn (status `submitted`) + open the task record.
+ *   - `recordTurnOutcome` at run END: append the assistant turn (status = outcome), record the
+ *     include/exclude context decision for BOTH turns, fold the run into its task, and REBUILD the
+ *     derived boot-replay cache (rolling summary + recent-K tail). Compaction changes what REPLAYS,
+ *     never what is RECORDED. */
+import type { Database } from "bun:sqlite";
+import type { RunTrace } from "@taicho-ai/contracts/trace";
+import { appendLedgerTurn, newTurnId, recordContextDecision } from "../store/conversation";
+import { createTaskState, taskIdForRun, updateTaskFromTrace, setTaskFields } from "../store/task-state";
+import { rebuildReplayCache } from "./conversation-replay";
+
+export interface UserTurn {
+  userTurnId: string;
+  taskId: string;
+}
+
+/** Run START (user turns only): record the user message in the ledger + open the task record. */
+export function recordUserTurn(ws: string, db: Database, o: { agent: string; runId: string; text: string }): UserTurn {
+  const userTurnId = newTurnId(o.agent, o.runId, "user");
+  appendLedgerTurn(ws, o.agent, {
+    turnId: userTurnId, runId: o.runId, timestamp: new Date().toISOString(),
+    agent: o.agent, role: "user", content: o.text, status: "submitted",
+  });
+  createTaskState(ws, { runId: o.runId, title: o.text, userTurnId }, db);
+  return { userTurnId, taskId: taskIdForRun(o.runId) };
+}
+
+/** Run END (user turns only): record the assistant turn + the context decision + the task update,
+ *  then rebuild the derived boot-replay cache. A COMPLETED run is safe to replay as context; any
+ *  other outcome is recorded in the ledger but EXCLUDED from replay (and leaves the cache untouched,
+ *  since it rebuilds from the included set). */
+export function recordTurnOutcome(
+  ws: string,
+  db: Database,
+  o: {
+    agent: string;
+    runId: string;
+    userTurn?: UserTurn;
+    trace: RunTrace;
+    children?: RunTrace[];
+    text: string;
+    keepRecentTurns?: number;
+  },
+): void {
+  const assistantTurnId = newTurnId(o.agent, o.runId, "assistant");
+  appendLedgerTurn(ws, o.agent, {
+    turnId: assistantTurnId, runId: o.runId, timestamp: new Date().toISOString(),
+    agent: o.agent, role: "assistant", content: o.text,
+    status: o.trace.outcome,          // outcome ⊂ LedgerStatus (was statusFromOutcome, an identity)
+    artifacts: o.trace.artifacts,     // handles this turn produced — carried by REFERENCE into replay
+  });
+  if (o.userTurn) {
+    const include = o.trace.outcome === "completed";
+    const reason = include ? "completed_turn" : `${o.trace.outcome}_run_not_safe_as_context`;
+    recordContextDecision(ws, o.agent, { include, turnId: o.userTurn.userTurnId, runId: o.runId, reason });
+    recordContextDecision(ws, o.agent, { include, turnId: assistantTurnId, runId: o.runId, reason });
+    updateTaskFromTrace(ws, o.userTurn.taskId, o.trace, o.children ?? [], db);
+  }
+  // The replay cache is DERIVED from the ledger's INCLUDED turns; only a completed turn changes that
+  // set, so only then is a rebuild meaningful (a failed/interrupted turn is already excluded and the
+  // cache stays as it was). Older turns fold into the rolling summary here — Plan 05 Ph3.
+  if (o.trace.outcome === "completed") {
+    rebuildReplayCache(ws, o.agent, { keepRecentTurns: o.keepRecentTurns });
+  }
+}
+
+/** Run START opened an append-only `submitted` ledger turn + a `running` task BEFORE the model was
+ *  even resolved (recordUserTurn). If something between there and the normal close THROWS — e.g.
+ *  `resolveModel` hitting the OpenRouter/explicit-model guard — the turn/task would otherwise DANGLE:
+ *  a `submitted` turn with no terminal reply and a `running` task that never settles (and would only
+ *  be swept to `interrupted` by the NEXT boot reconciliation). This closes the OPEN turn with a
+ *  terminal `failed` outcome so the ledger + task are never left mid-flight. It mirrors the failed
+ *  branch of `recordTurnOutcome` (append a `failed` assistant turn + EXCLUDE both turns from replay,
+ *  leaving the replay cache untouched), but needs no RunTrace since no run ever completed. */
+export function recordTurnFailure(
+  ws: string,
+  db: Database,
+  o: { agent: string; runId: string; userTurn: UserTurn; error: string },
+): void {
+  const assistantTurnId = newTurnId(o.agent, o.runId, "assistant");
+  appendLedgerTurn(ws, o.agent, {
+    turnId: assistantTurnId, runId: o.runId, timestamp: new Date().toISOString(),
+    agent: o.agent, role: "assistant", content: `error: ${o.error}`, status: "failed",
+  });
+  const reason = "failed_run_not_safe_as_context";
+  recordContextDecision(ws, o.agent, { include: false, turnId: o.userTurn.userTurnId, runId: o.runId, reason });
+  recordContextDecision(ws, o.agent, { include: false, turnId: assistantTurnId, runId: o.runId, reason });
+  setTaskFields(ws, db, o.userTurn.taskId, { status: "failed", stepStatus: "failed" });
+}

package/src/core/verification.ts

@@ -0,0 +1,102 @@
+/** The delegation checker (Plan 06). When a delegate_task carries acceptance `criteria`, the
+ *  child's output is judged by ONE independent model call — not the parent's self-assessment and
+ *  not the child grading itself — against the criteria, before the result reaches the parent's
+ *  context. The verdict is `{ pass, reasons[] }`. A fail triggers exactly one bounded retry
+ *  (orchestrated in tools.ts); a second fail surfaces the result WITH the failed verdict attached. */
+import { runLoop } from "@taicho-ai/agent";
+import type { AgentDef } from "@taicho-ai/contracts/agent";
+import type { SpendLedger, SpendScope } from "../store/spend-ledger";
+import { VerificationVerdict } from "@taicho-ai/contracts/trace";
+
+/** The checker uses the SAME model plumbing the loop uses — passed in by run.ts (the delegating
+ *  agent's resolved model), so verification is symmetric with the work it checks. */
+type CheckerModel = Parameters<typeof runLoop>[0]["model"];
+
+export const VERIFIER_SYSTEM =
+  "You are an impartial acceptance checker. You receive a GOAL, the ACCEPTANCE CRITERIA a delegated " +
+  "worker's output had to satisfy, and the CANDIDATE OUTPUT it produced. Judge ONLY whether the output " +
+  "meets the criteria — do NOT do the task yourself, and do NOT be charitable about missing requirements. " +
+  'Respond with ONLY a single-line JSON object: {"pass": <boolean>, "reasons": [<short strings>]}. ' +
+  "When pass is false, each reason names one unmet criterion. When pass is true, reasons may be empty.";
+
+/** Extract the {pass, reasons} verdict from the checker's text. Lenient: strips code fences and
+ *  parses the first {...} object. On any parse failure it returns a NON-blocking pass with a note —
+ *  the checker is advisory quality tooling, not a hard gate, so a flaky/garbled verifier must never
+ *  wedge delegation or burn a retry on its own bug. */
+export function parseVerdict(text: string): VerificationVerdict {
+  const cleaned = text.replace(/```(?:json)?/gi, "").trim();
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start !== -1 && end > start) {
+    try {
+      const parsed = VerificationVerdict.safeParse(JSON.parse(cleaned.slice(start, end + 1)));
+      if (parsed.success) return parsed.data;
+    } catch { /* fall through to the non-blocking default */ }
+  }
+  return { pass: true, reasons: [`verifier output was unparseable, treated as pass: ${text.slice(0, 120)}`] };
+}
+
+/** Run one independent checker call. Reuses runLoop with an empty toolset so it inherits the exact
+ *  same model plumbing (codex streaming, idle-timeout guard, token/cost metering, abort) as a normal
+ *  agent turn; with no tools the loop returns after the first response. */
+export async function runChecker(params: {
+  model: CheckerModel;
+  agent: AgentDef;                 // only its budgets bound the (single) checker call
+  subscription: boolean;           // Codex backend ⇒ stream + instructions, and cost is unpriced
+  priceUsd?: (u: { inputTokens: number; outputTokens: number }) => number;
+  captureProviderCost?: boolean;
+  signal?: AbortSignal;
+  /** Plan 09: the squad-wide ledger. Threaded through so the verifier's model call is BOTH bounded by
+   *  the squad ceiling AND committed to the running total, exactly like a primary agent loop — an
+   *  independent checker call is real squad spend, so the ceiling must see it. Undefined ⇒ no ceilings. */
+  spendLedger?: SpendLedger;
+  /** Plan 19: the delegating agent's scopes — the checker is spend IT caused. */
+  spendScopes?: SpendScope[];
+  goal: string;
+  criteria: string;
+  output: string;
+}): Promise<{ verdict: VerificationVerdict; tokens: number; costUsd: number | null; costNote?: string; checkerError?: boolean }> {
+  const user =
+    `GOAL:\n${params.goal}\n\n` +
+    `ACCEPTANCE CRITERIA:\n${params.criteria}\n\n` +
+    `CANDIDATE OUTPUT:\n${params.output}\n\n` +
+    `Does the candidate output satisfy every acceptance criterion? Reply with ONLY the JSON verdict.`;
+  const result = await runLoop({
+    model: params.model,
+    agent: params.agent,
+    system: VERIFIER_SYSTEM,
+    messages: [{ role: "user", content: user }],
+    tools: {},
+    signal: params.signal,
+    priceUsd: params.priceUsd,
+    codexBackend: params.subscription,
+    captureProviderCost: params.captureProviderCost,
+    spendLedger: params.spendLedger, // Plan 09: commit + bound the checker call against the ceilings
+    spendScopes: params.spendScopes,
+  });
+  // Plan 20: a checker that NEVER RAN must not pass. It used to parse "[error]"/"[cancelled]"/
+  // "[… budget exhausted …]" into the advisory PASS — a squad relying on criteria got silent passes
+  // during a provider outage, and (the more routine trigger) whenever a spend ceiling or per-run cap
+  // refused the checker call before it was made. Now it surfaces pass=false + checkerError:true, and
+  // tools.ts skips the retry (re-running the CHILD is pointless when the judge can't run) and the
+  // annotation/coaching side effects (such a verdict says nothing about the artifact). A GARBLED
+  // verdict from a checker that DID run still parses to the advisory pass in parseVerdict — deliberate.
+  if (result.error || result.aborted || result.exhausted) {
+    const why = result.error ?? (result.aborted ? "cancelled" : result.text || "budget exhausted");
+    return {
+      verdict: { pass: false, reasons: [`checker unavailable: ${why}`] },
+      checkerError: true,
+      tokens: result.tokens,
+      costUsd: params.subscription ? null : result.costUsd,
+      costNote: params.subscription ? "subscription" : undefined,
+    };
+  }
+  // Cost honesty (mirrors run.ts/loop.ts): a subscription checker has NO measurable USD, so costUsd is
+  // null + costNote:"subscription" — never a fabricated 0 that claims an unmeasured price. Tokens always meter.
+  return {
+    verdict: parseVerdict(result.text),
+    tokens: result.tokens,
+    costUsd: params.subscription ? null : result.costUsd,
+    costNote: params.subscription ? "subscription" : undefined,
+  };
+}

package/src/core/workflow-run.ts

@@ -0,0 +1,119 @@
+/** Plan 25: the integration layer — wire the pure workflow driver's injected seams to the real engine.
+ *
+ *  core/workflow.ts stays decoupled from run.ts (so the orchestration is unit-testable without a model);
+ *  THIS module is where a workflow step becomes a real executeRun, a check becomes runChecker, and a human
+ *  gate becomes a requestApproval. `runTeamWorkflow` loads a team's structured workflow and drives it.
+ *
+ *  The human gate reuses the EXISTING `ask_human` approval — the packet summary rides in the question, the
+ *  choices are the options — so it works in the REPL and headless today with zero changes to the shared
+ *  ApprovalRequest union. A rich workflow-gate card is a later (Phase 4) enhancement. */
+import { executeRun, type RunDeps } from "./run";
+import { runChecker } from "./verification";
+import { executeWorkflow, resumeWorkflow, type WorkflowExecDeps, type WorkflowInput } from "@taicho-ai/graph";
+import { loadWorkflowDef } from "../store/workflows";
+import { loadAgent } from "../store/roster";
+import { readArtifactBody } from "../store/artifacts";
+import type { WorkflowDef, WorkflowRunState } from "@taicho-ai/graph";
+
+/** Adapt RunDeps → the driver's injected seams for a specific workflow. */
+export function wireWorkflowDeps(deps: RunDeps, def: WorkflowDef): Omit<WorkflowExecDeps, "ws"> {
+  return {
+    signal: deps.signal,
+
+    runAgent: async ({ step, brief, inputs, runId, triggeredBy }) => {
+      const target = step.run.replace(/^@/, ""); // `@writer` in the file is the agent id `writer`
+      const agent = await loadAgent(deps.ws, target);
+      const child = await executeRun(deps, {
+        agent,
+        messages: [{ role: "user", content: brief || step.id }],
+        brief: { from: `workflow:${def.id}`, goal: brief || step.id, fromRun: runId },
+        inputArtifacts: inputs, // the edge state, by reference
+        triggeredBy,
+        viaTeam: def.team, // run UNDER the team, so it gets its Plan 23 lane if any
+      });
+      // The handle the step produced is the newest artifact THIS run wrote (trace.artifacts, id@vN).
+      const produced = child.trace.artifacts[child.trace.artifacts.length - 1];
+      return { childRunId: child.runId, outcome: child.trace.outcome, produced };
+    },
+
+    runCheck: async ({ node, target }) => {
+      if (!target) return { pass: false, reasons: [`check "${node.id}" has no upstream artifact to verify`] };
+      const body = readArtifactBody(deps.ws, target);
+      if (body === null) return { pass: false, reasons: [`check "${node.id}": artifact ${target} is unreadable`] };
+      const resolved = deps.resolveModel?.("root");
+      const checkerAgent = await loadAgent(deps.ws, "root");
+      const r = await runChecker({
+        model: resolved?.model ?? deps.model,
+        agent: checkerAgent,
+        subscription: resolved?.subscription ?? false,
+        priceUsd: deps.priceUsd,
+        captureProviderCost: resolved?.captureCost,
+        signal: deps.signal,
+        spendLedger: deps.spendLedger,
+        goal: `verify: ${node.check}`,
+        criteria: node.check,
+        output: body.toString("utf8"),
+      });
+      return { pass: r.verdict.pass, reasons: r.verdict.reasons };
+    },
+
+    requestGate: async ({ node, packet }) => {
+      const summary = packet.items.map((i) => `${i.name} → ${i.handle}`).join(" · ") || "(no artifacts produced yet)";
+      const question = `${node.human}\n\nreview packet: ${summary}`;
+      const d = await deps.requestApproval({ kind: "ask_human", question, options: node.choices });
+      return d.type === "answered" ? { choice: d.answer } : null;
+    },
+
+    classify: async ({ node, target }) => {
+      const labels = Object.keys(node.routes);
+      const agent = await loadAgent(deps.ws, node.branch.replace(/^@/, ""));
+      const body = target ? (readArtifactBody(deps.ws, target)?.toString("utf8") ?? "") : "";
+      const child = await executeRun(deps, {
+        agent,
+        messages: [{ role: "user", content: `Classify the input into exactly one of these labels: ${labels.join(", ")}.\nReply with ONLY the label.\n\n${body}` }],
+        triggeredBy: `workflow:${def.id}:${node.id}`,
+        viaTeam: def.team,
+      });
+      const text = child.text.toLowerCase();
+      return labels.find((l) => text.includes(l.toLowerCase())) ?? labels[0] ?? "";
+    },
+
+    listItems: async (handle) => {
+      const body = readArtifactBody(deps.ws, handle);
+      if (!body) return [];
+      const text = body.toString("utf8");
+      try {
+        const parsed = JSON.parse(text); // a JSON array is the tidy case
+        if (Array.isArray(parsed)) return parsed.map((x) => (typeof x === "string" ? x : JSON.stringify(x)));
+      } catch { /* not JSON — fall through to line-splitting */ }
+      return text.split("\n").map((l) => l.trim()).filter(Boolean); // else one item per non-empty line
+    },
+  };
+}
+
+/** Load a team's structured workflow and run it deterministically. Null if the team has no `steps:` workflow.
+ *  `unattended` (a scheduled/headless run) PARKS at a human gate instead of blocking — see resumeTeamWorkflow. */
+export async function runTeamWorkflow(
+  deps: RunDeps,
+  teamId: string,
+  input?: WorkflowInput,
+  opts?: { unattended?: boolean },
+): Promise<WorkflowRunState | null> {
+  const def = loadWorkflowDef(deps.ws, teamId);
+  if (!def) return null;
+  return executeWorkflow({ ws: deps.ws, parkGates: opts?.unattended, ...wireWorkflowDeps(deps, def) }, def, input);
+}
+
+/** Ph6: answer a workflow run that PARKED at a human gate, and drive the rest. Null if the team has no
+ *  structured workflow. Subsequent gates are attended (the wired requestGate) — the captain is here now. */
+export async function resumeTeamWorkflow(
+  deps: RunDeps,
+  teamId: string,
+  runId: string,
+  choice: string,
+  note?: string,
+): Promise<WorkflowRunState | null> {
+  const def = loadWorkflowDef(deps.ws, teamId);
+  if (!def) return null;
+  return resumeWorkflow({ ws: deps.ws, ...wireWorkflowDeps(deps, def) }, def, runId, choice, note);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./core/run";
+export { buildModel, createModelResolver, type ResolvedModel } from "./core/model";
+export * from "./core/workflow-run";
+export * from "./core/headless";
+export * from "./core/logger";
+export * from "./store/config";
+export * from "./store/files";
+export * from "./store/roster";

package/src/knowledge/retrieval.ts

@@ -0,0 +1,73 @@
+/** Hybrid squad-knowledge recall: a semantic (or keyword) seed, then a typed-edge graph expansion.
+ *  Mirrors coaching/retrieval.ts. Degrades to keyword+graph when no embedder is available, so the
+ *  KB is fully usable under any provider (incl. subscription/Anthropic with no embeddings endpoint). */
+import type { Database } from "bun:sqlite";
+import { topK } from "../store/vectors";
+import { getNodes, neighbors } from "../store/knowledge";
+
+const tokenize = (s: string): string[] => s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+const DECAY = 0.5;
+
+export interface KbHit {
+  id: string; title: string; summary?: string; kind: string;
+  score: number; via: "semantic" | "keyword" | "graph"; depth: number;
+}
+export interface KbSearchResult { hits: KbHit[]; mode: "semantic" | "keyword"; seeds: string[]; }
+
+export async function searchKnowledge(opts: {
+  db: Database;
+  query: string;
+  embed?: (t: string) => Promise<Float32Array>;
+  k?: number;       // seed count
+  hops?: number;    // graph expansion depth
+  rels?: string[];  // restrict edge types
+  limit?: number;   // final cap
+}): Promise<KbSearchResult> {
+  const { db, query } = opts;
+  const k = opts.k ?? 6, hops = opts.hops ?? 1, limit = opts.limit ?? 10;
+  const scores = new Map<string, { score: number; via: KbHit["via"]; depth: number }>();
+  let mode: "semantic" | "keyword" = "keyword";
+
+  // 1. Seed — semantic when an embedder is present, else keyword token-overlap.
+  if (opts.embed) {
+    try {
+      const q = await opts.embed(query);
+      for (const { ref, score } of topK(db, "kb", q, k)) scores.set(ref, { score, via: "semantic", depth: 0 });
+      mode = "semantic";
+    } catch { /* embedder failed → fall back to keyword below */ }
+  }
+  if (scores.size === 0) {
+    mode = "keyword";
+    const qset = new Set(tokenize(query));
+    if (qset.size) {
+      const rows = db.query("SELECT id, title, summary, content FROM kb_nodes").all() as
+        { id: string; title: string; summary: string | null; content: string }[];
+      const scored = rows.map((r) => {
+        const terms = tokenize(`${r.title} ${r.summary ?? ""} ${r.content}`);
+        let overlap = 0; for (const t of terms) if (qset.has(t)) overlap++;
+        return { id: r.id, score: overlap };
+      }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, k);
+      for (const s of scored) scores.set(s.id, { score: s.score, via: "keyword", depth: 0 });
+    }
+  }
+
+  const seeds = [...scores.keys()];
+  const topSeed = Math.max(0, ...seeds.map((s) => scores.get(s)!.score));
+
+  // 2. Expand along typed edges (both directions), decaying by depth.
+  for (const { id, depth } of neighbors(db, seeds, hops, opts.rels)) {
+    const decayed = topSeed * Math.pow(DECAY, depth);
+    const prev = scores.get(id);
+    if (!prev || decayed > prev.score) scores.set(id, { score: decayed, via: "graph", depth });
+  }
+
+  // 3. Hydrate + rank.
+  const rows = getNodes(db, [...scores.keys()]);
+  const hits: KbHit[] = [];
+  for (const [id, s] of scores) {
+    const r = rows.get(id); if (!r) continue;
+    hits.push({ id, title: r.title, summary: r.summary ?? undefined, kind: r.kind, score: s.score, via: s.via, depth: s.depth });
+  }
+  hits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  return { hits: hits.slice(0, limit), mode, seeds };
+}

package/src/knowledge/sync.ts

@@ -0,0 +1,28 @@
+/** Hash-sync orchestration: detect changed/deleted source docs (deterministic), then for each changed
+ *  doc clear its prior subgraph (by provenance) and re-extract via the injected `ingest`. Detection is
+ *  plumbing; extraction is an agent (the librarian) supplied as `ingest`. Idempotent. */
+import type { Database } from "bun:sqlite";
+import { diffSources, upsertSourceHash, deleteSourceHash } from "../store/sources";
+import { forgetNodes } from "../store/knowledge";
+
+export type IngestFn = (path: string, hash: string) => Promise<void>;
+export interface SyncSummary { changedDocs: number; deletedDocs: number; removedNodes: number }
+
+export async function syncKnowledgeSources(opts: { ws: string; db: Database; ingest: IngestFn }): Promise<SyncSummary> {
+  const { ws, db, ingest } = opts;
+  const diff = diffSources(ws, db);
+  let removedNodes = 0;
+
+  for (const path of diff.deleted) {
+    removedNodes += forgetNodes(ws, db, { sourcePrefix: `${path}@` }).removedNodes;
+    deleteSourceHash(db, path);
+  }
+
+  for (const src of diff.changed) {
+    removedNodes += forgetNodes(ws, db, { sourcePrefix: `${src.path}@` }).removedNodes; // drop old subgraph
+    await ingest(src.path, src.hash);                                                    // re-extract
+    upsertSourceHash(db, src.path, src.hash);
+  }
+
+  return { changedDocs: diff.changed.length, deletedDocs: diff.deleted.length, removedNodes };
+}

package/src/skills/retrieval.ts

@@ -0,0 +1,22 @@
+/** Keyword discovery over active skills — mirrors core/discovery.ts (rankAgents). Semantic search
+ *  (reusing the KB embeddings) is a deferred upgrade behind this same interface. */
+import type { SkillRow } from "../store/skills";
+
+export interface SkillHit { id: string; name: string; description: string; score: number }
+
+const tokenize = (s: string): string[] => s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+
+export function rankSkills(rows: SkillRow[], query: string, k: number): SkillHit[] {
+  const q = new Set(tokenize(query));
+  if (q.size === 0) return [];
+  const scored: SkillHit[] = [];
+  for (const r of rows) {
+    if (r.status !== "active") continue;
+    const terms = tokenize(`${r.name} ${r.description} ${r.tags.join(" ")}`);
+    let overlap = 0;
+    for (const t of terms) if (q.has(t)) overlap++;
+    if (overlap > 0) scored.push({ id: r.id, name: r.name, description: r.description, score: overlap });
+  }
+  scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  return scored.slice(0, k);
+}

package/src/store/annotations.ts

@@ -0,0 +1,107 @@
+/** Annotations: feedback attached to an artifact VERSION (id@vN). Append-only log per artifact id at
+ *  artifacts/<id>/annotations.jsonl — one Annotation JSON per line; the LATEST line per annotation id
+ *  wins on read (so resolving/dismissing appends a new record, never rewrites). Same append-only
+ *  discipline as the conversation ledger (store/conversation.ts): the file is the truth, reads fold it.
+ *
+ *  An OPEN annotation is the input to a revision run — run.ts surfaces open annotations under each input
+ *  artifact handed to a child; the reviser saves a new version linked back and (optionally) resolves the
+ *  annotation against it. A verification verdict (Plan 06) is written here like any other annotation. */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Annotation, mkAnnotationId, type AnnotationKind, type AnnotationStatus } from "@taicho-ai/contracts/annotation";
+import type { VerificationVerdict } from "@taicho-ai/contracts/trace";
+import { parseHandle, artifactHandle } from "@taicho-ai/contracts/artifact";
+import { paths } from "./files";
+import { readArtifact } from "./artifacts";
+
+function annotationsFile(ws: string, id: string): string {
+  return join(paths.artifactDir(ws), id, "annotations.jsonl");
+}
+
+/** Resolve a handle to its CONCRETE version handle "id@vN" (bare "id" ⇒ latest); null if absent. */
+function pinHandle(ws: string, handle: string): string | null {
+  const a = readArtifact(ws, handle);
+  return a ? artifactHandle(a) : null;
+}
+
+export interface AnnotateInput {
+  target: string;                 // artifact handle ("id" ⇒ latest version, or "id@vN")
+  author: string;                 // "human" | agentId | "checker"
+  body: string;
+  kind?: AnnotationKind;
+  verdict?: VerificationVerdict;  // Plan 06 hook: a verification verdict IS an annotation
+}
+
+/** Attach an annotation to an artifact version. A bare id pins to its LATEST version so the feedback is
+ *  anchored to the immutable content it was written about. Throws if the artifact doesn't exist. When a
+ *  `verdict` is supplied and no explicit kind is given, the annotation is a `verification`. */
+export function annotateArtifact(ws: string, input: AnnotateInput): Annotation {
+  const pinned = pinHandle(ws, input.target);
+  if (!pinned) throw new Error(`no artifact "${input.target}" to annotate`);
+  const { id } = parseHandle(pinned);
+  const annotation = Annotation.parse({
+    id: mkAnnotationId(),
+    target: pinned,
+    author: input.author,
+    kind: input.kind ?? (input.verdict ? "verification" : "feedback"),
+    body: input.body,
+    verdict: input.verdict,
+    status: "open",
+    created: new Date().toISOString(),
+  });
+  mkdirSync(join(paths.artifactDir(ws), id), { recursive: true });
+  appendFileSync(annotationsFile(ws, id), JSON.stringify(annotation) + "\n");
+  return annotation;
+}
+
+export interface AnnotationFilter {
+  status?: AnnotationStatus;
+  version?: number;   // restrict to annotations targeting a specific version (also implied by an "id@vN" handle)
+}
+
+/** Annotations for an artifact, folded latest-per-annotation-id. A bare `id` returns annotations across
+ *  EVERY version; an "id@vN" handle restricts to that version. Newest first. */
+export function listAnnotations(ws: string, handle: string, filter: AnnotationFilter = {}): Annotation[] {
+  const { id, version } = parseHandle(handle);
+  const f = annotationsFile(ws, id);
+  if (!existsSync(f)) return [];
+  const byId = new Map<string, Annotation>();
+  const appendOrder = new Map<string, number>(); // annotation id → first-seen line index (= creation append order)
+  let seen = 0;
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const a = Annotation.parse(JSON.parse(line));
+      if (!appendOrder.has(a.id)) appendOrder.set(a.id, seen++);
+      byId.set(a.id, a);
+    } catch { /* skip corrupt audit line */ }
+  }
+  const wantVersion = version ?? filter.version;
+  return [...byId.values()]
+    .filter((a) => !filter.status || a.status === filter.status)
+    .filter((a) => wantVersion === undefined || parseHandle(a.target).version === wantVersion)
+    // Newest first. `created` is millisecond-resolution, so two annotations minted in the same tick tie
+    // on localeCompare — an unstable order that flakes any test asserting sequence. Break the tie by
+    // append order DESCENDING (the later-appended record is the newer one), making the sort total + stable.
+    .sort((x, y) => y.created.localeCompare(x.created) || (appendOrder.get(y.id)! - appendOrder.get(x.id)!));
+}
+
+/** One annotation by id (searches across all versions of the artifact). */
+export function readAnnotation(ws: string, artifactId: string, annId: string): Annotation | null {
+  const { id } = parseHandle(artifactId);
+  return listAnnotations(ws, id).find((a) => a.id === annId) ?? null;
+}
+
+/** Mark an annotation `addressed` (by a revision handle) or `dismissed`. Appends an updated record —
+ *  the append-only log never rewrites, so the original open record is preserved as history. */
+export function resolveAnnotation(
+  ws: string, artifactId: string, annId: string,
+  opts: { status?: "addressed" | "dismissed"; resolvedBy?: string } = {},
+): Annotation | null {
+  const { id } = parseHandle(artifactId);
+  const cur = readAnnotation(ws, id, annId);
+  if (!cur) return null;
+  const updated = Annotation.parse({ ...cur, status: opts.status ?? "addressed", resolvedBy: opts.resolvedBy ?? cur.resolvedBy });
+  appendFileSync(annotationsFile(ws, id), JSON.stringify(updated) + "\n");
+  return updated;
+}