@staix/agent-research 0.0.0-stage → 0.1.0

package/src/memory/amem.ts

@@ -0,0 +1,97 @@
+import { PROCESS_CONTEXT_ENV_KEYS, spawnRunner, type ProcessRunner } from "../exp/executor.ts";
+import { plain } from "../study.ts";
+
+export const AMEM_OUTPUT_BYTES = 262_144;
+export const AMEM_BRIEF_BYTES = 8192;
+export type AmemKind = "fail" | "finding" | "decision" | "contract";
+export interface AmemNote {
+  text: string; kind: AmemKind; title?: string;
+  approach?: string; symptom?: string; cause?: string; evidence?: string[]; retryWhen?: string;
+}
+export interface AmemHit { id: string; kind: AmemKind; title: string | null; at: string; relevance: number; about: string[] }
+export interface AmemBrief { brief: string; bytes: number; truncated: boolean; state: string }
+export interface AmemClient {
+  add(note: AmemNote): Promise<string>;
+  search(words: string, kind?: AmemKind, limit?: number): Promise<AmemHit[]>;
+  brief(text: string, bytes: number): Promise<AmemBrief>;
+}
+const kindOf = (value: unknown): value is AmemKind => ["fail", "finding", "decision", "contract"].includes(value as string);
+const identifier = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+function invalid(): never { throw new Error("amem bad JSON: invalid response shape; check amem --version and inspect --json output in the study directory"); }
+function input(text: string): void {
+  if (!text.trim() || text.includes("\0")) throw new Error("amem input: provide non-empty text without NUL; correct the input and retry");
+}
+function optionValue(value: string): string {
+  input(value);
+  // ponytail: amem 0.20.3 cannot escape -- values; one leading space works until its parser supports literal option values.
+  return value.startsWith("--") ? ` ${value}` : value;
+}
+function hit(raw: unknown): AmemHit {
+  if (!plain(raw) || !identifier(raw.id) || !kindOf(raw.kind) || (raw.title !== null && typeof raw.title !== "string")
+    || typeof raw.at !== "string" || !Number.isFinite(Date.parse(raw.at))
+    || !Array.isArray(raw.about) || !raw.about.every(node => typeof node === "string")) invalid();
+  const details = raw.scoreDetails;
+  if (!plain(details) || typeof details.finalScore !== "number" || !Number.isFinite(details.finalScore) || details.finalScore <= 0
+    || typeof details.recencyFactor !== "number" || !Number.isFinite(details.recencyFactor) || details.recencyFactor <= 0) scoreUnavailable();
+  const relevance = details.finalScore / details.recencyFactor;
+  if (!Number.isFinite(relevance) || relevance <= 0) scoreUnavailable();
+  return { id: raw.id, kind: raw.kind, title: raw.title, at: raw.at, relevance, about: [...raw.about] as string[] };
+}
+function scoreUnavailable(): never {
+  throw new Error("amem score unavailable: finite positive finalScore and recencyFactor required; inspect amem search <words> --json --explain in the study directory");
+}
+async function readAmem(args: string[], cwd: string, runner: ProcessRunner, context: NodeJS.ProcessEnv, stdin?: Uint8Array): Promise<unknown> {
+  let result;
+  try { result = await runner({ command: "amem", args, cwd, env: context, ...(stdin === undefined ? {} : { stdin }), maxOutputBytes: AMEM_OUTPUT_BYTES, timeoutMs: 30_000 }); }
+  catch { throw new Error("amem spawn failure; check amem is on PATH (amem --version)"); }
+  if (result.truncated || Buffer.byteLength(result.stdout) > AMEM_OUTPUT_BYTES) throw new Error("amem over-bound output; reduce the search limit or brief bytes and retry");
+  if (result.timedOut) throw new Error("amem timeout; check amem --version and retry in the study directory");
+  if (result.exitCode !== 0) throw new Error("amem nonzero exit; run amem search <words> --json in the study directory to see the cause");
+  try { return JSON.parse(result.stdout); } catch { throw new Error("amem bad JSON; check amem --version and inspect --json output in the study directory"); }
+}
+function searchRows(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw;
+  if (!plain(raw) || !Array.isArray(raw.hits)) invalid();
+  return raw.hits.flatMap(item => {
+    if (!plain(item)) invalid();
+    if (item.source !== "curated" || item.view === undefined) return [];
+    if (!plain(item.view)) invalid();
+    return [{ ...item.view, scoreDetails: item.scoreDetails }];
+  });
+}
+/** The process boundary returns projections only; raw diagnostics never escape in errors. */
+export function createAmemClient(cwd: string, runner: ProcessRunner = spawnRunner, env: NodeJS.ProcessEnv = process.env): AmemClient {
+  const context = Object.fromEntries([...PROCESS_CONTEXT_ENV_KEYS, "HOME"].flatMap(key => env[key] === undefined ? [] : [[key, env[key]!]]));
+  const read = (args: string[], stdin?: Uint8Array) => readAmem(args, cwd, runner, context, stdin);
+  return {
+    async add(note) {
+      input(note.text);
+      if (!kindOf(note.kind)) throw new Error("amem input: invalid kind; use fail, finding, decision or contract");
+      if (note.evidence && note.evidence.length > 16) throw new Error("amem input: at most 16 evidence refs; reduce evidence refs and retry");
+      const args = ["note", "add", "-", "--kind", note.kind];
+      for (const [flag, value] of [["--approach", note.approach], ["--symptom", note.symptom], ["--cause", note.cause],
+        ... (note.evidence ?? []).map(ref => ["--evidence", ref]), ["--retry-when", note.retryWhen], ["--title", note.title]]) {
+        if (value !== undefined) args.push(flag!, optionValue(value));
+      }
+      const raw = await read([...args, "--json"], Buffer.from(note.text, "utf8"));
+      if (!plain(raw) || !identifier(raw.id)) invalid();
+      return raw.id;
+    },
+    async search(words, kind, limit = 100) {
+      input(words);
+      if (kind !== undefined && !kindOf(kind)) throw new Error("amem input: invalid kind; use fail, finding, decision or contract");
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error("amem input: search limit must be 1..100; choose an integer in this range");
+      const raw = await read(["search", optionValue(words), "--json", "--explain", "--limit", String(limit)]);
+      const rows = searchRows(raw);
+      return rows.filter(row => kind === undefined || plain(row) && row.kind === kind).map(hit);
+    },
+    async brief(text, bytes) {
+      input(text);
+      if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > AMEM_BRIEF_BYTES) throw new Error("amem input: brief bytes must be 1..8192; choose an integer in this range");
+      const raw = await read(["brief", "--for", optionValue(text), "--json", "--bytes", String(bytes)]);
+      if (!plain(raw) || typeof raw.brief !== "string" || !Number.isSafeInteger(raw.bytes) || (raw.bytes as number) < 0
+        || (raw.bytes as number) > bytes || Buffer.byteLength(raw.brief) > bytes || typeof raw.truncated !== "boolean" || typeof raw.state !== "string") invalid();
+      return { brief: raw.brief, bytes: raw.bytes as number, truncated: raw.truncated, state: raw.state };
+    },
+  };
+}

package/src/memory/archive.ts

@@ -0,0 +1,63 @@
+import { commit, prepareCommit, openStudy, plain, sha256, type Actor, type LedgerEvent } from "../study.ts";
+import { canonical } from "../plan/state.ts";
+import { createAmemClient, type AmemNote } from "./amem.ts";
+import { deriveLessons, readLessonSources } from "./lessons.ts";
+import type { ProcessRunner } from "../exp/executor.ts";
+
+export const ARCHIVE_NOTES = 200;
+export interface ArchiveReceipt { sha256: string; id: string }
+export interface ArchivePreview { fingerprint: string; notes: { sha256: string; note: AmemNote }[] }
+export interface ArchiveResult extends ArchivePreview { written: ArchiveReceipt[]; remaining: number }
+/** Carries receipt progress for adapters; CLI/MCP retain the existing retry instruction verbatim. */
+export class ArchivePartialError extends Error {
+  readonly failureMessage: string;
+  constructor(readonly exportedCount: number, failure: unknown) {
+    const detail = failure instanceof Error ? failure.message : "amem failure; check amem --version before retrying";
+    super(`archive: ${exportedCount} note(s) written and receipted; rerun with the same --confirm to continue; ${detail}`);
+    this.failureMessage = detail;
+  }
+}
+function hex(value: unknown, length: 32 | 64): value is string {
+  return typeof value === "string" && value.length === length && /^[a-f0-9]+$/.test(value);
+}
+function badReceipt(): never { throw new Error("archive receipt: malformed or conflicting exported notes; restore the last valid archive.exported ledger event before retrying ares archive"); }
+function exported(events: LedgerEvent[]): Set<string> {
+  const known = new Map<string, string>();
+  for (const event of events) if (event.type === "archive.exported") {
+    if (!hex(event.data.fingerprint, 64) || !Array.isArray(event.data.notes) || event.data.notes.length > ARCHIVE_NOTES) badReceipt();
+    for (const row of event.data.notes) {
+      if (!plain(row) || !hex(row.sha256, 64) || !hex(row.id, 32)) badReceipt();
+      if (known.has(row.sha256) && known.get(row.sha256) !== row.id) badReceipt();
+      known.set(row.sha256, row.id);
+    }
+  }
+  return new Set(known.keys());
+}
+/** No lock, subprocess or write: confirmation binds the full list, receipts only narrow pending writes. */
+export function previewArchive(dir: string): ArchivePreview {
+  const sources = readLessonSources(dir), notes = deriveLessons(sources), known = exported(sources.events);
+  const unique = new Map(notes.map(note => [sha256(canonical(note)), note]));
+  const pending = [...unique].filter(([hash]) => !known.has(hash)).map(([sha256, note]) => ({ sha256, note }));
+  return { fingerprint: sha256(canonical(notes)), notes: pending };
+}
+/** Caller holds the study lock across the confirmed write and its single receipt commit. */
+export async function exportArchive(dirArg: string, fingerprint: string, actor: Actor, runner?: ProcessRunner, env: NodeJS.ProcessEnv = process.env): Promise<ArchiveResult> {
+  const { dir } = openStudy(dirArg), preview = previewArchive(dir);
+  if (!hex(fingerprint, 64) || fingerprint !== preview.fingerprint) throw new Error("archive: stale fingerprint; run ares archive <dir> again and confirm its current fingerprint");
+  const batch = preview.notes.slice(0, ARCHIVE_NOTES);
+  if (batch.length) {
+    try { prepareCommit(dir, [], [{ actor, type: "archive.exported", data: {
+      fingerprint, notes: batch.map(note => ({ sha256: note.sha256, id: "f".repeat(32) })),
+    } }]); }
+    catch { throw new Error("archive receipt: capacity check failed; restore a valid bounded ledger or start a new study before exporting"); }
+  }
+  const client = createAmemClient(dir, runner, env), written: ArchiveReceipt[] = [];
+  let failure: unknown;
+  for (const item of batch) {
+    try { written.push({ sha256: item.sha256, id: await client.add(item.note) }); }
+    catch (error) { failure = error; break; }
+  }
+  if (written.length) commit(dir, [], [{ actor, type: "archive.exported", data: { fingerprint, notes: written } }]);
+  if (failure) throw new ArchivePartialError(written.length, failure);
+  return { ...preview, written, remaining: preview.notes.length - written.length };
+}

package/src/memory/lessons.ts

@@ -0,0 +1,88 @@
+import { openStudy, readLedger, type LedgerEvent, type Study } from "../study.ts";
+import { foldIdeas } from "../exp/ideas.ts";
+import { readProtocol } from "../exp/protocol.ts";
+import { readSelection, selectionHash, type Selection } from "../exp/selection.ts";
+import { readClosedInvestigation, type InvestigateResult } from "../exp/investigate.ts";
+import { readClosedFinal, readFinalSeeds, finalSeedsHash, type FinalResult, type FinalSeeds } from "../exp/final.ts";
+import { foldReviews } from "../paper/review.ts";
+import type { AmemNote, AmemHit } from "./amem.ts";
+
+export interface LessonSources {
+  study: Pick<Study, "id" | "question">; events: LedgerEvent[];
+  investigation?: InvestigateResult; final?: FinalResult; selection?: Selection; finalSeeds?: FinalSeeds;
+}
+export const LESSON_EVIDENCE_REFS = 16;
+/** Read current committed sources only. An absent close yields no lesson; an invalid close refuses. */
+export function readLessonSources(dirArg: string): LessonSources {
+  const { dir, study } = openStudy(dirArg), events = readLedger(dir), protocol = readProtocol(dir);
+  const sources: LessonSources = { study, events };
+  if (protocol) {
+    sources.selection = readSelection(dir, protocol);
+    sources.finalSeeds = readFinalSeeds(dir, protocol);
+    for (const [type, value, hash] of [["selection.set", sources.selection, selectionHash(dir, protocol)], ["final.seeds.set", sources.finalSeeds, finalSeedsHash(dir, protocol)]]) {
+      if (value && events.findLast(event => event.type === type)?.data.sha256 !== hash) throw new Error("lessons: design file lacks a matching receipt; restore the committed selection/final seeds with ares selection or ares final seeds");
+    }
+  }
+  if (sources.selection && events.some(event => event.type === "investigate.closed" && event.data.run === sources.selection!.run)) sources.investigation = readClosedInvestigation(dir).result;
+  if (events.some(event => event.type === "final.closed")) sources.final = readClosedFinal(dir).result;
+  return sources;
+}
+/** Pure derivation. Ledger order, fixed source order and evidence chunks keep export fingerprints stable. */
+export function deriveLessons(sources: LessonSources): AmemNote[] {
+  const { study, events } = sources, notes: AmemNote[] = [], prefix = `${study.id}: ${study.question}\n`;
+  const attemptRef = (id: string) => `ares:${study.id}/attempt:${id}`;
+  const runRef = (run: string) => `ares:${study.id}/run:${run}`;
+  const add = (note: AmemNote) => {
+    const refs = [...new Set(note.evidence ?? [])];
+    // Split long evidence lists rather than silently dropping cited attempts.
+    for (let index = 0; index < Math.max(1, refs.length); index += LESSON_EVIDENCE_REFS) {
+      notes.push({ ...note, text: prefix + note.text, evidence: refs.slice(index, index + LESSON_EVIDENCE_REFS) });
+    }
+  };
+  for (const idea of foldIdeas(events)) {
+    for (const decision of idea.decisions) if (decision.decision === "pivot") add({ kind: "fail", title: idea.title,
+      text: `Pivot ${idea.id}: ${decision.reason}`, approach: `${idea.title}\n${idea.hypothesis}`, symptom: decision.reason,
+      cause: decision.cause ?? "not recorded", retryWhen: decision.retryWhen ?? "not recorded", evidence: decision.attempts.map(attemptRef) });
+  }
+  const investigation = sources.investigation;
+  if (investigation) {
+    const winner = investigation.winner, candidate = investigation.candidates.find(row => row.commit === winner?.commit);
+    add({ kind: "finding", title: `Investigation ${investigation.run}`,
+      text: winner ? `Investigation ${investigation.run}: winner ${winner.commit}; paired delta ${winner.delta}; seeds ${JSON.stringify(candidate?.pairedSeeds ?? [])}`
+        : `Investigation ${investigation.run}: no winner; reason ${investigation.reason}`,
+      evidence: [runRef(investigation.run), ...(winner?.attempts ?? []).map(attemptRef)] });
+  }
+  const final = sources.final;
+  if (final) add({ kind: "finding", title: `Final ${final.status}`,
+    text: `Final ${final.status}: winner ${final.winner}; baseline ${final.baseline}; reason ${final.reason ?? "qualified"}; paired delta ${final.delta}; seeds ${JSON.stringify(final.seeds)}`,
+    evidence: [runRef("final"), ...final.decisive.map(row => attemptRef(row.id))] });
+  if (sources.selection) add({ kind: "decision", title: "Selection rule", text: `Selection rule: ${JSON.stringify(sources.selection)}`, evidence: [runRef(sources.selection.run)] });
+  if (sources.finalSeeds) add({ kind: "decision", title: "Final seeds", text: `Final seeds: ${JSON.stringify(sources.finalSeeds.seeds)}`, evidence: [runRef("final")] });
+  for (const review of foldReviews(events)) {
+    for (const finding of review.report.findings) {
+      const resolution = review.resolutions[finding.id];
+      if (finding.kind === "contradiction" && resolution) add({ kind: "finding", title: `Review ${review.id}/${finding.id}`,
+        text: `Review contradiction ${review.id}/${finding.id}: ${finding.text}; resolution: ${resolution.reason}`, evidence: [] });
+    }
+  }
+  return notes;
+}
+
+export interface LessonRankOptions { halfLife?: number; limit?: number }
+export interface RankedLesson { id: string; kind: AmemHit["kind"]; title: string | null; age: number; relevance: number; score: number; rank: number }
+export const LESSON_HALF_LIFE = 180, LESSON_LIMIT = 50;
+const DAY_MS = 86_400_000;
+/** Pure ranking: age is days, relevance excludes amem recency, score is decayed and rank is 1-based. */
+export function rankLessons(hits: readonly AmemHit[], now: number, options: LessonRankOptions = {}): RankedLesson[] {
+  const halfLife = options.halfLife ?? LESSON_HALF_LIFE, limit = options.limit ?? LESSON_LIMIT;
+  if (!Number.isFinite(now)) throw new Error("lessons clock: finite timestamp required; supply a valid current time and retry");
+  if (!Number.isFinite(halfLife) || halfLife < 1 || halfLife > 3650) throw new Error("lessons half-life: outside 1..3650 days; pass --half-life DAYS within that range");
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LESSON_LIMIT) throw new Error("lessons limit: outside 1..50; pass --limit with an integer in that range");
+  const ranked = hits.map(hit => {
+    const at = Date.parse(hit.at);
+    if (!Number.isFinite(at) || !Number.isFinite(hit.relevance) || hit.relevance <= 0) throw new Error("lessons score unavailable: invalid timestamp or relevance; inspect amem search --json --explain in the study directory before retrying");
+    const age = Math.max(0, (now - at) / DAY_MS), score = hit.relevance * 0.5 ** (age / halfLife);
+    return { id: hit.id, kind: hit.kind, title: hit.title, age, relevance: hit.relevance, score };
+  });
+  return ranked.sort((a, b) => b.score - a.score || Number(b.kind === "fail") - Number(a.kind === "fail") || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, limit).map((row, index) => ({ ...row, rank: index + 1 }));
+}

package/src/memory/skills.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritable, boundedText, commit, onlyKeys, openStudy, plain, readLedger, readTextBounded, sha256, type Actor, type LedgerEvent } from "../study.ts";
+
+export const SKILL_PROPOSAL_VERSION = 1, SKILL_PROPOSALS = 100, SKILL_BYTES = 16 * 1024, SKILL_EVIDENCE = 64;
+export interface SkillProposal { name: string; summary: string; steps: string[]; evidence: string[] }
+export type SkillDecision = "accept" | "reject" | "withdraw";
+export interface SkillRecord extends SkillProposal {
+  skillProposal: 1; state: "proposed" | "accepted" | "rejected" | "withdrawn"; sha256: string; actor: Actor; at: string;
+  decision?: { action: SkillDecision; reason: string; pr?: string; actor: Actor; at: string };
+}
+function bad(message: string): never { throw new Error(`skill: ${message}; inspect ares skill list, correct the input or restore the last valid proposal and retry`); }
+function nameOf(value: unknown): string {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) bad("name must follow the run-name rule (1..64 letters, digits, underscores or hyphens)");
+  return value;
+}
+function text(value: unknown, field: string): string {
+  let result: string;
+  try { result = boundedText(value, `skill ${field}`, SKILL_BYTES); } catch { bad(`${field} must be nonblank text within 16 KiB`); }
+  if (result.includes("\0") || Buffer.byteLength(result) > SKILL_BYTES) bad(`${field} contains NUL or exceeds 16 KiB`);
+  return result;
+}
+function markdown(proposal: SkillProposal): string {
+  const list = (values: string[]) => values.map(value => `- ${value.replaceAll("\n", "\n  ")}`).join("\n");
+  return `---\nskillProposal: 1\nname: ${proposal.name}\n---\n\n# ${proposal.name}\n\n${proposal.summary}\n\n## Steps\n\n${list(proposal.steps)}\n\n## Evidence\n\n${list(proposal.evidence)}\n`;
+}
+/** Strict for new input, additive-field tolerant when replaying existing v1 records. */
+export function validateSkillProposal(raw: unknown, strict = true): SkillProposal {
+  if (!plain(raw)) bad("proposal object required");
+  if (strict) { try { onlyKeys(raw, ["name", "summary", "steps", "evidence"], "skill proposal"); } catch { bad("unknown proposal field; use only name, summary, steps and evidence"); } }
+  if (!Array.isArray(raw.steps) || !raw.steps.length || !Array.isArray(raw.evidence)) bad("steps must be a nonempty array and evidence an array");
+  if (raw.evidence.length < 1 || raw.evidence.length > SKILL_EVIDENCE) bad("evidence requires 1..64 refs; supply at least one recorded amem id or ares: reference");
+  if (raw.steps.length > SKILL_BYTES) bad("proposal arrays exceed the 16 KiB format ceiling; shorten steps or evidence");
+  const proposal: SkillProposal = { name: nameOf(raw.name), summary: text(raw.summary, "summary"), steps: raw.steps.map(value => text(value, "step")), evidence: raw.evidence.map(value => text(value, "evidence")) };
+  if (proposal.evidence.some(value => !/^[a-f0-9]{32}$/.test(value) && !/^ares:[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(value))) bad("evidence must contain 32-hex amem ids or ares:<study-id>/... refs");
+  try { assertWritable(markdown(proposal), SKILL_BYTES, "skill proposal"); } catch { bad("proposal Markdown exceeds 16 KiB; shorten summary, steps or evidence"); }
+  return proposal;
+}
+function decisionOf(value: unknown): SkillDecision {
+  if (value !== "accept" && value !== "reject" && value !== "withdraw") bad("decision must be accept, reject or withdraw");
+  return value;
+}
+function prOf(value: unknown, action: SkillDecision): string | undefined {
+  if (value === undefined) { if (action === "accept") bad("accept requires --pr URL for the reviewed PR"); return undefined; }
+  const result = text(value, "PR URL");
+  try { const url = new URL(result); if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) bad("PR must be an HTTP(S) URL without credentials"); }
+  catch { bad("PR must be an HTTP(S) URL without credentials"); }
+  return result;
+}
+function version(event: LedgerEvent): void {
+  if (event.data.skillProposal !== 1) throw new Error("skill proposal: unsupported version; use an ares version supporting this journal and keep its files unchanged");
+}
+export function foldSkills(events: LedgerEvent[]): SkillRecord[] {
+  const rows = new Map<string, SkillRecord>();
+  for (const event of events) {
+    if (event.type === "skill.proposed") {
+      version(event); const proposal = validateSkillProposal(event.data.proposal, false), hash = sha256(markdown(proposal));
+      if (event.data.sha256 !== hash || rows.has(proposal.name) || rows.size >= SKILL_PROPOSALS) bad("journal has a mismatched hash, duplicate name or more than 100 proposals");
+      rows.set(proposal.name, { ...proposal, skillProposal: 1, state: "proposed", sha256: hash, actor: event.actor, at: event.at });
+    } else if (event.type === "skill.decided") {
+      version(event); const name = nameOf(event.data.name), row = rows.get(name), action = decisionOf(event.data.decision);
+      if (!row || row.state !== "proposed") bad("decision references a missing or already decided proposal");
+      const reason = text(event.data.reason, "reason"), pr = prOf(event.data.pr, action);
+      row.state = action === "accept" ? "accepted" : action === "reject" ? "rejected" : "withdrawn";
+      row.decision = { action, reason, ...(pr === undefined ? {} : { pr }), actor: event.actor, at: event.at };
+    }
+  }
+  return [...rows.values()];
+}
+function file(dir: string, name: string): string { return join(dir, "proposals", "skills", `${name}.md`); }
+/** Read only tracked proposals; every file is regular/bounded and bound to its original event. */
+function readSkills(dirArg: string) {
+  const { dir } = openStudy(dirArg), events = readLedger(dir), rows = foldSkills(events);
+  for (const row of rows) {
+    let content: string;
+    try { content = readTextBounded(file(dir, row.name), SKILL_BYTES); } catch { bad("proposal file missing, unreadable or larger than 16 KiB; restore its committed Markdown"); }
+    if (!content.startsWith("---\nskillProposal: 1\n")) throw new Error("skill proposal file: unsupported version; use an ares version supporting this file and keep it unchanged");
+    if (sha256(content) !== row.sha256) bad("proposal file differs from its receipt; restore the original Markdown");
+  }
+  return { dir, events, rows };
+}
+export function listSkills(dir: string): SkillRecord[] { return readSkills(dir).rows; }
+/** Caller holds the study lock. One bounded file and one event share the existing commit preflight. */
+export function proposeSkill(dirArg: string, raw: unknown, actor: Actor): SkillRecord {
+  const proposal = validateSkillProposal(raw), { dir, events, rows } = readSkills(dirArg);
+  if (rows.length >= SKILL_PROPOSALS) bad("100-proposal limit reached; start a new study for further proposals");
+  if (rows.some(row => row.name === proposal.name) || existsSync(file(dir, proposal.name))) bad("name or proposal file already exists; choose a new name without replacing prior work");
+  const content = markdown(proposal), hash = sha256(content);
+  const added = commit(dir, [[file(dir, proposal.name), content, SKILL_BYTES]], [{ actor, type: "skill.proposed", data: { skillProposal: 1, proposal, sha256: hash } }]);
+  return foldSkills([...events, ...added]).find(row => row.name === proposal.name)!;
+}
+/** Final actor-recorded decisions never open, inspect or merge a PR. */
+export function decideSkill(dirArg: string, name: string, decision: string, reason: string, pr: string | undefined, actor: Actor): SkillRecord {
+  const target = nameOf(name), action = decisionOf(decision), why = text(reason, "reason"), reference = prOf(pr, action), { dir, events, rows } = readSkills(dirArg);
+  const row = rows.find(row => row.name === target);
+  if (!row || row.state !== "proposed") bad("proposal is missing or already decided; decisions including withdrawal are final");
+  const added = commit(dir, [], [{ actor, type: "skill.decided", data: { skillProposal: 1, name: target, decision: action, reason: why, ...(reference === undefined ? {} : { pr: reference }) } }]);
+  return foldSkills([...events, ...added]).find(row => row.name === target)!;
+}

package/src/paper/build.ts

@@ -0,0 +1,70 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritable, commit, openStudy, plain, readLedger, readTextBounded, sha256, type Actor } from "../study.ts";
+import { checkPaper, manuscriptPath } from "./check.ts";
+import { MANUSCRIPT_BYTES } from "./placeholders.ts";
+
+export const PAPER_EVIDENCE_BYTES = 8 * 1024 * 1024;
+export interface PaperEvidence {
+  v: 1;
+  manuscriptSha256: string;
+  placeholders: {
+    kind: "number" | "literal"; raw: string; start: number; end: number; line: number; column: number;
+    ref?: string; format?: number; value: string | number; rendered: string;
+    source: { file: string; sha256: string };
+  }[];
+}
+export function paperBuildPaths(dir: string) { return { manuscript: join(dir, "paper", "build", "manuscript.md"), evidence: join(dir, "paper", "build", "evidence.json") }; }
+function previous(file: string, bound: number): string | undefined {
+  if (!existsSync(file)) return undefined;
+  try { return readTextBounded(file, bound); }
+  catch { throw new Error(`paper build: previous output is unreadable, non-regular, invalid UTF-8 or oversized; restore the last valid ${file.endsWith("evidence.json") ? "paper/build/evidence.json" : "paper/build/manuscript.md"} before rebuilding`); }
+}
+function evidenceBytes(dir: string): string | undefined {
+  const oldEvidence = previous(paperBuildPaths(dir).evidence, PAPER_EVIDENCE_BYTES);
+  if (oldEvidence !== undefined) {
+    let raw: unknown;
+    try { raw = JSON.parse(oldEvidence); } catch { throw new Error("paper evidence: invalid JSON; restore the last valid paper/build/evidence.json before rebuilding"); }
+    if (!plain(raw) || raw.v !== 1) throw new Error("paper evidence: unsupported version; use an ares version that supports it, keeping paper/build/evidence.json unchanged");
+  }
+  return oldEvidence;
+}
+function calculatePaper(dir: string) {
+  const report = checkPaper(dir);
+  if (!report.ok) {
+    const reasons = report.findings.slice(0, 10).map(f => `${f.code} at ${f.line}:${f.column}`).join(", ");
+    throw new Error(`paper build: paper check found ${report.findings.length} finding(s): ${reasons}; run ares paper check <dir> --json and fix every finding before rebuilding`);
+  }
+  const evidence: PaperEvidence = { v: 1, manuscriptSha256: report.manuscriptSha256, placeholders: report.placeholders.map(entry => {
+    const token = entry.placeholder;
+    return { kind: token.kind, raw: token.raw, start: token.start, end: token.end, line: token.line, column: token.column,
+      ...(token.kind === "number" ? { ref: token.ref, ...(token.format === undefined ? {} : { format: token.format }) } : {}),
+      value: entry.value, rendered: entry.rendered,
+      source: entry.source ?? { file: "paper/manuscript.md", sha256: report.manuscriptSha256 },
+    };
+  }) };
+  const text = JSON.stringify(evidence, null, 2) + "\n";
+  assertWritable(report.rendered, MANUSCRIPT_BYTES, "rendered manuscript; shorten paper/manuscript.md before rebuilding");
+  assertWritable(text, PAPER_EVIDENCE_BYTES, "paper evidence; reduce paper/manuscript.md or its placeholders before rebuilding");
+  return { report, evidence, text, manuscriptSha256: sha256(report.rendered), evidenceSha256: sha256(text) };
+}
+/** Caller holds the study lock. Refusals precede the single output-and-receipt commit. */
+export function buildPaper(dirArg: string, actor: Actor) {
+  const { dir } = openStudy(dirArg), paths = paperBuildPaths(dir), oldEvidence = evidenceBytes(dir);
+  const { report, text, manuscriptSha256, evidenceSha256 } = calculatePaper(dir), oldManuscript = previous(paths.manuscript, MANUSCRIPT_BYTES);
+  const receipt = readLedger(dir).findLast(event => event.type === "paper.built");
+  const changed = oldManuscript !== report.rendered || oldEvidence !== text || receipt?.data.manuscriptSha256 !== manuscriptSha256 || receipt.data.evidenceSha256 !== evidenceSha256;
+  if (sha256(readTextBounded(manuscriptPath(dir), MANUSCRIPT_BYTES)) !== report.manuscriptSha256) throw new Error("paper build: source manuscript changed during checking; rerun ares paper check and paper build on the current manuscript");
+  if (changed) commit(dir, [[paths.manuscript, report.rendered, MANUSCRIPT_BYTES], [paths.evidence, text, PAPER_EVIDENCE_BYTES]], [{ actor, type: "paper.built", data: { manuscriptSha256, evidenceSha256, sourceManuscriptSha256: report.manuscriptSha256 } }]);
+  return { manuscriptSha256, evidenceSha256, changed };
+}
+
+
+/** The exact fresh build and both output receipts must agree; never repairs or writes files. */
+export function readCurrentBuild(dirArg: string) {
+  const { dir } = openStudy(dirArg), paths = paperBuildPaths(dir), evidence = evidenceBytes(dir), manuscript = previous(paths.manuscript, MANUSCRIPT_BYTES);
+  if (evidence === undefined || manuscript === undefined) throw new Error("paper build: missing output; run ares paper build before reviewing");
+  const fresh = calculatePaper(dir), receipt = readLedger(dir).findLast(event => event.type === "paper.built");
+  if (evidence !== fresh.text || manuscript !== fresh.report.rendered || receipt?.data.manuscriptSha256 !== fresh.manuscriptSha256 || receipt.data.evidenceSha256 !== fresh.evidenceSha256 || receipt.data.sourceManuscriptSha256 !== fresh.report.manuscriptSha256) throw new Error("paper build: stale outputs or missing/mismatched receipt; run ares paper check and ares paper build before reviewing");
+  return { manuscriptSha256: fresh.manuscriptSha256, evidenceSha256: fresh.evidenceSha256, check: fresh.report };
+}

package/src/paper/check.ts

@@ -0,0 +1,180 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { openStudy, readTextBounded, sha256 } from "../study.ts";
+import { loadCandidates } from "../lit/candidates.ts";
+import { checkCitations, citationOccurrences } from "../lit/cite.ts";
+import { readProtocol } from "../exp/protocol.ts";
+import { readSelection } from "../exp/selection.ts";
+import { investigateResultPath, readClosedInvestigation } from "../exp/investigate.ts";
+import { finalResultPath } from "../exp/final.ts";
+import { MANUSCRIPT_BYTES, parsePlaceholders, resolvePlaceholders } from "./placeholders.ts";
+
+export const MAX_CODE_NUMBERS = 500;
+export interface PaperFinding { code: "bare-number" | "unresolved-ref" | "bad-format" | "unknown-citation" | "unverified-citation" | "missing-negative-result"; start: number; end: number; line: number; column: number; message: string }
+function blank(text: string, mask: Uint8Array): string { return text.split("").map((char, index) => mask[index] && char !== "\n" && char !== "\r" ? " " : char).join(""); }
+function mark(mask: Uint8Array, start: number, end: number) { mask.fill(1, start, end); }
+function escaped(text: string, index: number): boolean { let slashes = 0; while (index > 0 && text[--index] === "\\") slashes++; return slashes % 2 === 1; }
+/** Masks syntax-only destinations and code while retaining original offsets. Visible link labels remain prose. */
+function markdownMask(text: string, knownHidden?: Uint8Array): { mask: Uint8Array; code: Uint8Array; hidden: Uint8Array } {
+  const mask = new Uint8Array(text.length), protectedText = new Uint8Array(text.length), tokens = parsePlaceholders(text);
+  for (const token of [...tokens.placeholders, ...tokens.findings]) mark(protectedText, token.start, token.end);
+  let fence: { char: string; length: number } | undefined, paragraph = false, indented = false;
+  const listIndents: number[] = [];
+  for (const match of text.matchAll(/[^\n]*(?:\n|$)/g)) {
+    const line = match[0], start = match.index;
+    if (!line) continue;
+    if (!line.trim()) { paragraph = false; continue; }
+    if (!fence && knownHidden?.[start + /^[ \t]*/.exec(line)![0].length]) { paragraph = false; continue; }
+    if (fence) {
+      mark(mask, start, start + line.length);
+      const close = /^ {0,3}(`+|~+)[ \t]*\r?\n?$/.exec(line);
+      if (close && close[1]![0] === fence.char && close[1]!.length >= fence.length) fence = undefined;
+      paragraph = false; indented = false;
+    } else if (!protectedText[start]) {
+      const open = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)/.exec(line);
+      if (open && !(open[1]![0] === "`" && open[2]!.includes("`"))) { fence = { char: open[1]![0]!, length: open[1]!.length }; mark(mask, start, start + line.length); paragraph = false; indented = false; }
+      else {
+        const prefix = /^[ \t]*/.exec(line)![0];
+        let indent = 0; for (const char of prefix) indent += char === "\t" ? 4 - indent % 4 : 1;
+        const item = /^[ \t]*(?:[-+*]|[0-9]+[.)])[ \t]+/.exec(line);
+        let parent = listIndents.length; while (parent && listIndents[parent - 1]! > indent) parent--;
+        if (item && indent < (listIndents[parent - 1] ?? 0) + 4) {
+          listIndents.length = parent; listIndents.push(item[0].length); paragraph = true; indented = false;
+        }
+        else {
+          if (!paragraph) listIndents.length = parent;
+          if (indent >= (listIndents.at(-1) ?? 0) + 4 && (indented || !paragraph)) { mark(mask, start, start + line.length); indented = true; }
+          else { indented = false; paragraph = !/^ {0,3}(?:#{1,6}[ \t]|(?:---+|\*\*\*+|___+)[ \t]*$)/.test(line.trimEnd()); }
+        }
+      }
+    }
+  }
+  // Backtick runs must have an exactly matching closer; unmatched delimiters remain prose.
+  const runs = [...text.matchAll(/`+/g)].filter(hit => !mask[hit.index] && !protectedText[hit.index] && !knownHidden?.[hit.index]);
+  const regions: number[] = []; let region = 0, previous = 0;
+  for (const hit of runs) {
+    if (/\n[ \t]*\r?\n/.test(text.slice(previous, hit.index)) || mask.subarray(previous, hit.index).includes(1)) region++;
+    regions.push(region); previous = hit.index + hit[0].length;
+  }
+  const next = new Map<number, number>(), closers = new Map<string, number>();
+  for (let i = runs.length - 1; i >= 0; i--) {
+    const hit = runs[i]!, key = `${regions[i]}:${hit[0].length}`;
+    if (closers.has(key)) next.set(i, closers.get(key)!); closers.set(key, i);
+  }
+  for (let i = 0; i < runs.length; i++) {
+    if (escaped(text, runs[i]!.index)) continue;
+    const close = next.get(i);
+    if (close !== undefined) { mark(mask, runs[i]!.index, runs[close]!.index + runs[close]![0].length); i = close; }
+  }
+  const code = mask.slice();
+  const labels: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    if (mask[i] || protectedText[i] || knownHidden?.[i] || (text[i] !== "<" && text[i] !== "]" && text[i] !== "[") || escaped(text, i)) continue;
+    if (text[i] === "[") { labels.push(i); continue; }
+    if (text[i] === "<") {
+      const end = text.indexOf(">", i + 1), target = text.slice(i + 1, end < 0 ? i + 1 : end);
+      if (end >= 0 && /^(?:[A-Za-z][A-Za-z0-9+.-]{1,31}:[^\s<>]*|[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+)$/.test(target)) { mark(mask, i, end + 1); i = end; }
+    }
+    if (text[i] !== "]") continue;
+    const label = labels.pop();
+    if (label === undefined || text[i + 1] !== "(") continue;
+    let start = i + 2; while (/\s/.test(text[start] ?? "") && start < text.length) start++;
+    let end = start, depth = 0;
+    if (text[start] === "<") { end = text.indexOf(">", start + 1); if (end < 0) continue; end++; }
+    else {
+      while (end < text.length) {
+        const char = text[end]!;
+        if (char === "\\") { end += 2; continue; }
+        if (/\s/.test(char) || (char === ")" && depth === 0)) break;
+        if (char === "(") depth++;
+        if (char === ")") depth--;
+        end++;
+      }
+      if (depth) continue;
+    }
+    let tail = end; while (/\s/.test(text[tail] ?? "") && tail < text.length) tail++;
+    if (["\"", "'"].includes(text[tail] ?? "")) {
+      const quote = text[tail++]!; while (tail < text.length && (text[tail] !== quote || escaped(text, tail))) tail++;
+      if (tail >= text.length) continue; tail++; while (/\s/.test(text[tail] ?? "") && tail < text.length) tail++;
+    }
+    if (text[tail] === ")") mark(mask, start, end);
+  }
+  const hidden = new Uint8Array(text.length); let hasComment = false;
+  for (const comment of text.matchAll(/<!--[\s\S]*?(?:-->|$)/g)) {
+    if (!code[comment.index] && !protectedText[comment.index]) { mark(mask, comment.index, comment.index + comment[0].length); mark(hidden, comment.index, comment.index + comment[0].length); hasComment = true; }
+  }
+  // Reference definitions do not count as visible negative-result prose; labels/titles still get numeric checks.
+  for (const match of text.matchAll(/^ {0,3}\[[^\]\n]+\]:[ \t]*(<[^>\n]*>|[^\s]+)(?:[ \t]|$)/gm)) {
+    const target = match[1]!, start = match.index + match[0].lastIndexOf(target);
+    if (!mask[start] && !protectedText[start]) {
+      mark(mask, start, start + target.length);
+      const lineEnd = text.indexOf("\n", match.index); mark(hidden, match.index, lineEnd < 0 ? text.length : lineEnd);
+    }
+  }
+  // Reclassify once with non-code comments excluded, so a fence inside a comment cannot hide later prose.
+  if (!knownHidden && hasComment) return markdownMask(text, hidden);
+  return { mask, code, hidden };
+}
+export function manuscriptPath(dir: string): string { return join(dir, "paper", "manuscript.md"); }
+export function checkPaper(dirArg: string) {
+  const { dir, study } = openStudy(dirArg), file = manuscriptPath(dir);
+  let manuscript: string;
+  try { manuscript = readTextBounded(file, MANUSCRIPT_BYTES); }
+  catch { throw new Error("paper manuscript: missing, unreadable, invalid UTF-8, non-regular or larger than 2 MiB; restore paper/manuscript.md as a bounded UTF-8 regular file before paper check"); }
+  const masks = markdownMask(manuscript), prose = blank(manuscript, masks.mask), parsed = parsePlaceholders(prose), resolution = resolvePlaceholders(dir, prose);
+  const lines = [0]; for (let i = 0; i < manuscript.length; i++) if (manuscript[i] === "\n") lines.push(i + 1);
+  const location = (start: number) => {
+    let lo = 0, hi = lines.length; while (lo + 1 < hi) { const mid = (lo + hi) >>> 1; if (lines[mid]! <= start) lo = mid; else hi = mid; }
+    return { line: lo + 1, column: start - lines[lo]! + 1 };
+  };
+  const finding = (code: PaperFinding["code"], start: number, end: number, message: string): PaperFinding => ({ code, start, end, ...location(start), message });
+  const findings: PaperFinding[] = resolution.findings.map(f => finding(f.code, f.start, f.end, f.message));
+  const codeNumbers: { value: string; line: number; column: number }[] = [];
+  let codeNumberCount = 0;
+  const codeText = manuscript.split("").map((char, index) => masks.code[index] || char === "\n" || char === "\r" ? char : " ").join("");
+  for (const hit of codeText.matchAll(/\p{Nd}+(?:[.,]\p{Nd}+)*/gu)) {
+    codeNumberCount++;
+    if (codeNumbers.length < MAX_CODE_NUMBERS) codeNumbers.push({ value: hit[0], ...location(hit.index) });
+  }
+  const numberMask = masks.mask.slice(), citationMask = masks.mask.slice();
+  for (const placeholder of parsed.placeholders) {
+    mark(numberMask, placeholder.start, placeholder.end);
+    if (placeholder.kind === "number") mark(citationMask, placeholder.start, placeholder.end);
+  }
+  for (const problem of parsed.findings) { mark(numberMask, problem.start, problem.end); mark(citationMask, problem.start, problem.end); }
+  const citationText = blank(manuscript, citationMask), citations = checkCitations(citationText, loadCandidates(dir));
+  const groups = new Map<number, number>();
+  for (const hit of citationOccurrences(citationText)) {
+    mark(numberMask, hit.start, hit.end); groups.set(hit.groupStart, hit.groupEnd);
+    if (citations.unknown.includes(hit.key)) findings.push(finding("unknown-citation", hit.start, hit.end, `citation ${hit.key}: unknown key; add and verify the reference, then regenerate the bibliography`));
+    else if (citations.notVerified.includes(hit.key)) findings.push(finding("unverified-citation", hit.start, hit.end, `citation ${hit.key}: not included and identifier-verified; inspect ares lit list, verify the reference or exclude this citation`));
+  }
+  // Only locator-number syntax is exempt inside citation brackets; arbitrary prose numbers remain checked.
+  const locators = /(?:^|[^\p{L}\p{N}_])(p\.|pp\.|sec\.|§|ch\.|chap\.|fig\.|tbl\.|table|eq\.|l\.|ll\.|para\.)[ \t\r\n]*(\p{Nd}+(?:[ \t]*(?:--?|–|—)[ \t]*\p{Nd}+)?(?:[ \t]*,[ \t]*\p{Nd}+(?:[ \t]*(?:--?|–|—)[ \t]*\p{Nd}+)?)*)(?=$|[\s,;:\]\)]|\.(?!\p{Nd}))/giu;
+  for (const [start, end] of groups) {
+    const group = citationText.slice(start, end);
+    for (const hit of group.matchAll(locators)) {
+      const numbers = hit[2]!, offset = start + hit.index + hit[0].length - numbers.length;
+      mark(numberMask, offset, offset + numbers.length);
+    }
+  }
+  if (study.mode === "experiment") {
+    for (const match of manuscript.matchAll(/^ {0,3}[0-9]+[.)](?=[ \t])/gm)) mark(numberMask, match.index, match.index + match[0].length);
+    for (const match of blank(manuscript, numberMask).matchAll(/\p{Nd}+(?:[.,]\p{Nd}+)*/gu)) findings.push(finding("bare-number", match.index, match.index + match[0].length, "prose number has no evidence ref; use {{n:REF}} for a measured value or {{lit:TEXT}} for a reviewer-visible literal"));
+    const requireRef = (ref: string) => {
+      if (!parsed.placeholders.some(p => p.kind === "number" && p.ref === ref && p.format === undefined && !masks.hidden[p.start])) findings.push(finding("missing-negative-result", 0, 0, `paper omits ${ref}; include {{n:${ref}}} in prose so the result cannot be hidden`));
+    };
+    if (existsSync(finalResultPath(dir))) requireRef("final.status");
+    try {
+      const protocol = readProtocol(dir), rule = protocol ? readSelection(dir, protocol) : undefined;
+      if (rule && existsSync(investigateResultPath(dir, rule.run))) {
+        try { if (readClosedInvestigation(dir).result.winner === null) requireRef("investigate.reason"); }
+        catch { findings.push(finding("unresolved-ref", 0, 0, "investigate result is not current and closed; run ares investigate close before checking the paper")); }
+      }
+    } catch { findings.push(finding("unresolved-ref", 0, 0, "experiment design or selection is invalid; restore the current validated inputs before paper check")); }
+  }
+  let rendered = "", cursor = 0;
+  for (const entry of resolution.placeholders) { rendered += manuscript.slice(cursor, entry.placeholder.start) + entry.rendered; cursor = entry.placeholder.end; }
+  rendered += manuscript.slice(cursor);
+  return { ok: findings.length === 0, manuscriptSha256: sha256(manuscript), rendered, placeholders: resolution.placeholders, findings: findings.sort((a, b) => a.start - b.start || a.code.localeCompare(b.code)), literals: resolution.literals, codeNumbers, codeNumberCount, citations };
+}