@anhlp/alp-core 0.0.0-beta.1

package/src/beads.js

@@ -0,0 +1,236 @@
+import { DESCRIPTION_CHARS, MAX_LABELS, TASK_TYPES, batch, isTaskId } from './tasks.js';
+
+/**
+ * Interchange with beads (github.com/gastownhall/beads) through its JSONL issue
+ * format: `bd export` writes one issue per line and `bd import` upserts them.
+ * Relations become beads dependencies stored on the dependent issue
+ * ({ issue_id, depends_on_id, type }); what beads has no field for (review,
+ * gates, paths, handoffs) rides in metadata.alp, so ALP → beads → ALP keeps it.
+ */
+
+const DEPENDENCY = { blockedBy: 'blocks', parent: 'parent-child', discoveredFrom: 'discovered-from', related: 'related' };
+const RELATION = Object.fromEntries(Object.entries(DEPENDENCY).map(([relation, type]) => [type, relation]));
+const LABEL = /^[\w.:/-]{1,50}$/;
+
+/** Tasks as beads issues, sorted by id like bd export. */
+export function exportBeads(tasks) {
+  return [...tasks].sort((a, b) => a.id.localeCompare(b.id)).map(task => {
+    const dependencies = [
+      ...task.blockedBy.map(id => [id, 'blocks']),
+      ...(task.parent ? [[task.parent, 'parent-child']] : []),
+      ...(task.discoveredFrom ? [[task.discoveredFrom, 'discovered-from']] : []),
+      ...task.related.map(id => [id, 'related']),
+    ].map(([dependsOn, type]) => ({ issue_id: task.id, depends_on_id: dependsOn, type }));
+    const timers = task.gates.filter(gate => gate.kind === 'timer' && !gate.resolved).map(gate => gate.until).sort();
+    const alp = {
+      ...(task.status === 'review' ? { status: 'review' } : {}),
+      ...(task.paths.length ? { paths: task.paths } : {}),
+      ...(task.gates.length ? { gates: task.gates } : {}),
+      ...(task.handoff ? { handoff: task.handoff } : {}),
+      ...(task.closed ? { closed: task.closed } : {}),
+      ...(task.compacted ? { compacted: task.compacted } : {}),
+      ...(task.step ? { step: task.step } : {}),
+      ...(task.formula ? { formula: task.formula } : {}),
+    };
+    return {
+      id: task.id,
+      title: task.title,
+      ...(task.description ? { description: task.description } : {}),
+      status: task.status === 'review' ? 'in_progress' : task.status,
+      priority: task.priority,
+      issue_type: task.type,
+      ...(task.assignee ? { assignee: task.assignee.agent } : {}),
+      ...(task.labels.length ? { labels: task.labels } : {}),
+      ...(dependencies.length ? { dependencies } : {}),
+      created_at: task.createdAt,
+      created_by: task.createdBy,
+      updated_at: task.updatedAt,
+      ...(task.closed ? { closed_at: task.closed.at, close_reason: task.closed.summary ?? task.closed.reason } : {}),
+      ...(timers.length ? { defer_until: timers.at(-1) } : {}),
+      ...(task.external ? { external_ref: task.external.id, source_system: task.external.system } : {}),
+      ...(Object.keys(alp).length ? { metadata: { alp } } : {}),
+    };
+  });
+}
+
+/** Parses JSONL, keeping the line number of every record or error. */
+export function parseJsonl(text) {
+  const records = [];
+  const errors = [];
+  text.split('\n').forEach((line, index) => {
+    if (!line.trim()) return;
+    try {
+      const record = JSON.parse(line);
+      if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('not a JSON object');
+      records.push({ line: index + 1, record });
+    } catch (error) {
+      errors.push({ line: index + 1, reason: error.message });
+    }
+  });
+  return { records, errors };
+}
+
+const sections = record => [
+  typeof record.description === 'string' ? record.description : '',
+  ...[['design', 'Design'], ['acceptance_criteria', 'Acceptance criteria'], ['notes', 'Notes']]
+    .filter(([key]) => typeof record[key] === 'string' && record[key].trim())
+    .map(([key, title]) => `## ${title}\n\n${record[key].trim()}`),
+].filter(Boolean).join('\n\n');
+
+/** metadata.alp, whether beads wrote metadata as an object or as JSON text. */
+function alpOf(record) {
+  let metadata = record.metadata;
+  if (typeof metadata === 'string') { try { metadata = JSON.parse(metadata); } catch { return {}; } }
+  return metadata?.alp && typeof metadata.alp === 'object' && !Array.isArray(metadata.alp) ? metadata.alp : {};
+}
+
+const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+
+/** What an issue becomes in ALP, apart from its relations and status. */
+function taskFields(record) {
+  const type = TASK_TYPES.includes(record.issue_type) ? record.issue_type : 'task';
+  const labels = [
+    ...(Array.isArray(record.labels) ? record.labels.filter(label => typeof label === 'string' && LABEL.test(label)) : []),
+    ...(record.issue_type && type !== record.issue_type && LABEL.test(`beads:${record.issue_type}`) ? [`beads:${record.issue_type}`] : []),
+  ];
+  const priority = Number.isInteger(record.priority) ? Math.min(4, Math.max(0, record.priority)) : 2;
+  const alp = alpOf(record);
+  return {
+    title: clip(String(record.title).trim(), 200),
+    description: clip(sections(record), DESCRIPTION_CHARS),
+    type,
+    priority,
+    labels: [...new Set(labels)].slice(0, MAX_LABELS),
+    ...(Array.isArray(alp.paths) ? { paths: alp.paths.filter(entry => typeof entry === 'string') } : {}),
+  };
+}
+
+/** Parents before children, so a child's numbered id can follow its parent's. */
+function byParent(entries, parentOf) {
+  const ordered = [];
+  const placed = new Set();
+  const visit = (entry, trail = new Set()) => {
+    if (placed.has(entry.record.id) || trail.has(entry.record.id)) return;
+    trail.add(entry.record.id);
+    const parent = entries.find(candidate => candidate.record.id === parentOf(entry.record));
+    if (parent) visit(parent, trail);
+    placed.add(entry.record.id);
+    ordered.push(entry);
+  };
+  for (const entry of entries) visit(entry);
+  return ordered;
+}
+
+/**
+ * Upserts beads issues into the project's tasks, as bd import does: an issue
+ * whose id is an ALP task id, or that ALP imported before (external beads id),
+ * updates that task; any other becomes a new task. Missing records are never deleted.
+ * @returns {Promise<{ created: Array<{ id: string, from: string }>, updated: Array<{ id: string, from: string }>, skipped: Array<{ line: number, reason: string }>, warnings: string[] }>}
+ */
+export async function importBeads(projectRoot, records, { dryRun = false, by = 'user' } = {}) {
+  const report = { created: [], updated: [], skipped: [], warnings: [] };
+  const usable = [];
+  for (const { line, record } of records) {
+    // bd export marks issues with _type; other record types are not tasks.
+    if (record._type !== undefined && record._type !== 'issue') report.skipped.push({ line, reason: `${record._type} record, not an issue` });
+    else if (typeof record.title !== 'string' || !record.title.trim()) report.skipped.push({ line, reason: 'no title' });
+    else if (typeof record.id !== 'string' || !record.id.trim()) report.skipped.push({ line, reason: 'no id' });
+    else if (record.status === 'tombstone') report.skipped.push({ line, reason: `${record.id} is deleted (tombstone)` });
+    else if (record.ephemeral === true || record.wisp === true) report.skipped.push({ line, reason: `${record.id} is ephemeral` });
+    else usable.push({ line, record });
+  }
+  const dependencies = record => (Array.isArray(record.dependencies) ? record.dependencies : [])
+    .filter(dep => dep && typeof dep.depends_on_id === 'string' && (dep.issue_id === undefined || dep.issue_id === record.id));
+  const parentOf = record => dependencies(record).find(dep => dep.type === 'parent-child')?.depends_on_id ?? (typeof record.parent === 'string' ? record.parent : undefined);
+
+  return batch(projectRoot, ({ tasks, add, touch, link }) => {
+    const ids = new Map();
+    const find = foreign => ids.get(foreign)
+      ?? tasks.find(task => task.id === foreign && isTaskId(foreign))?.id
+      ?? tasks.find(task => task.external?.system === 'beads' && task.external.id === foreign)?.id;
+
+    for (const { line, record } of byParent(usable, parentOf)) {
+      try {
+        const values = taskFields(record);
+        const alp = alpOf(record);
+        const existing = find(record.id);
+        let task;
+        let before;
+        if (existing) {
+          task = tasks.find(entry => entry.id === existing);
+          before = JSON.stringify(task);
+          Object.assign(task, values);
+        } else {
+          const parent = parentOf(record) ? find(parentOf(record)) : undefined;
+          if (parentOf(record) && !parent) report.warnings.push(`${record.id}: parent ${parentOf(record)} is not in the file or the project`);
+          task = add({ ...values, ...(parent ? { parent } : {}) }, by, {
+            id: record.id,
+            createdAt: typeof record.created_at === 'string' ? record.created_at : undefined,
+            event: 'imported', details: { from: record.id },
+            extra: {
+              ...(typeof record.created_by === 'string' && record.created_by ? { createdBy: record.created_by } : {}),
+              ...(Array.isArray(alp.gates) ? { gates: alp.gates } : {}),
+              ...(alp.step ? { step: alp.step } : {}),
+              ...(alp.formula ? { formula: alp.formula } : {}),
+            },
+          });
+          if (task.id !== record.id) task.external = { system: 'beads', id: record.id };
+          report.created.push({ id: task.id, from: record.id });
+        }
+        ids.set(record.id, task.id);
+        applyStatus(task, record, alp, by, report);
+        const deferred = typeof record.defer_until === 'string' && Date.parse(record.defer_until) > Date.now() ? new Date(record.defer_until).toISOString() : undefined;
+        // bd keeps whole seconds, so a timer within a second of defer_until is the same one.
+        if (deferred && !task.gates.some(gate => gate.kind === 'timer' && Math.abs(Date.parse(gate.until) - Date.parse(deferred)) < 1000)) {
+          const next = Math.max(0, ...task.gates.map(gate => Number(gate.id.slice(1)) || 0)) + 1;
+          task.gates = [...task.gates, { id: `g${next}`, kind: 'timer', until: deferred, at: new Date().toISOString(), by }];
+        }
+        if (existing && JSON.stringify(task) !== before) {
+          touch(task, by, 'imported', { from: record.id });
+          report.updated.push({ id: task.id, from: record.id });
+        }
+      } catch (error) {
+        report.skipped.push({ line, reason: `${record.id}: ${error.message}` });
+      }
+    }
+
+    // Relations once every issue has a task.
+    for (const { record } of usable) {
+      const id = ids.get(record.id);
+      if (!id) continue;
+      const task = tasks.find(entry => entry.id === id);
+      for (const dep of dependencies(record)) {
+        const relation = RELATION[dep.type];
+        if (!relation) { report.warnings.push(`${record.id}: dependency type ${dep.type} has no ALP relation; skipped`); continue; }
+        const other = find(dep.depends_on_id);
+        if (!other) { report.warnings.push(`${record.id}: ${dep.type} ${dep.depends_on_id} is not in the file or the project; skipped`); continue; }
+        const before = JSON.stringify(task);
+        const refused = link(task, relation, other);
+        if (refused) report.warnings.push(`${record.id}: ${dep.type} ${dep.depends_on_id} skipped: ${refused}`);
+        else if (JSON.stringify(task) !== before) touch(task);
+      }
+    }
+    return report;
+  }, { dryRun });
+}
+
+/** beads statuses in ALP: closed stays closed, review comes back from metadata, everything else is open again. */
+function applyStatus(task, record, alp, by, report) {
+  const status = record.status ?? 'open';
+  if (status === 'closed') {
+    if (task.status === 'closed') return;
+    task.status = 'closed';
+    task.assignee = null;
+    task.closed = alp.closed && typeof alp.closed === 'object'
+      ? alp.closed
+      : { at: typeof record.closed_at === 'string' ? record.closed_at : new Date().toISOString(), by: 'beads', reason: 'done', ...(typeof record.close_reason === 'string' && record.close_reason ? { summary: record.close_reason } : {}) };
+  } else if (alp.status === 'review' && alp.handoff) {
+    task.status = 'review';
+    task.handoff = alp.handoff;
+  } else if (status === 'in_progress' && task.status === 'open') {
+    // Nobody in ALP holds it; it is open until main or the user starts it.
+    report.warnings.push(`${record.id}: was in progress${record.assignee ? ` with ${record.assignee}` : ''} in beads; imported as open`);
+  } else if (!['open', 'in_progress', 'blocked', 'deferred'].includes(status)) {
+    report.warnings.push(`${record.id}: beads status ${status} imported as open`);
+  }
+}

package/src/delegation.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { jsonObject } from './resolver.js';
+import { AlpError } from './errors.js';
+
+const name = value => typeof value === 'string' && value.trim() && !['.', '..'].includes(value) && !/[\\/\x00]/.test(value);
+
+/** The graph is project data, not a registry or provider-specific role enum. */
+export async function resolveDelegation(projectRoot) {
+  const source = path.join(projectRoot, '.alp', 'settings.json');
+  const settings = await jsonObject(source, 'INVALID_SETTINGS');
+  const graph = settings.delegation === undefined ? {} : settings.delegation;
+  const invalid = message => { throw new AlpError('INVALID_DELEGATION', `${source}: ${message}`); };
+  if (!graph || typeof graph !== 'object' || Array.isArray(graph)) invalid('delegation must map agent names to target arrays');
+  for (const [owner, targets] of Object.entries(graph)) {
+    if (!name(owner) || !Array.isArray(targets) || !targets.every(name) || new Set(targets).size !== targets.length) invalid(`invalid targets for '${owner}'`);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(owner) {
+    if (visiting.has(owner)) invalid(`delegation cycle at '${owner}'`);
+    if (visited.has(owner)) return;
+    visiting.add(owner);
+    for (const target of Object.hasOwn(graph, owner) ? graph[owner] : []) visit(target);
+    visiting.delete(owner); visited.add(owner);
+  }
+  for (const owner of Object.keys(graph)) visit(owner);
+  return graph;
+}

package/src/errors.js

@@ -0,0 +1,7 @@
+export class AlpError extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = 'AlpError';
+    this.code = code;
+  }
+}

package/src/formulas.d.ts

@@ -0,0 +1,25 @@
+import type { Task } from './tasks.js';
+
+export type FormulaStep = { id: string; title: string; description?: string; type: string; needs: string[]; priority?: number; labels?: string[]; paths?: string[] };
+export type Formula = {
+  formula: string;
+  title?: string;
+  description?: string;
+  version?: number;
+  priority?: number;
+  vars: Record<string, { description?: string; required: boolean; default?: string }>;
+  steps: FormulaStep[];
+};
+/** Parses TOML text; the core has none of its own (e.g. smol-toml's parse). */
+export type TomlParser = (text: string) => unknown;
+type Parsers = { toml?: TomlParser };
+export type FormulaEntry = { name: string; file: string; formula?: Formula; error?: string };
+
+export const MAX_STEPS: number;
+export function formulaDirs(projectRoot: string, home?: string): string[];
+export function listFormulas(projectRoot: string, home?: string, parsers?: Parsers): Promise<FormulaEntry[]>;
+export function findFormula(projectRoot: string, home: string | undefined, name: string, parsers?: Parsers): Promise<FormulaEntry & { formula: Formula }>;
+export function loadFormula(file: string, parsers?: Parsers): Promise<Formula>;
+export function validateFormula(data: unknown): Formula;
+export function resolveVars(formula: Formula, given?: Record<string, string>): Record<string, string>;
+export function pourFormula(projectRoot: string, formula: Formula, given: Record<string, string> | undefined, by: string, options?: { dryRun?: boolean; parent?: string }): Promise<{ epic: Task; tasks: Task[] }>;

package/src/formulas.js

@@ -0,0 +1,202 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { DESCRIPTION_CHARS, TASK_TYPES, batch } from './tasks.js';
+
+/**
+ * Formulas, after beads: a workflow template whose steps become tasks. A
+ * formula file is <name>.formula.toml or <name>.formula.json in the project's
+ * .alp/formulas, the user's $ALP_HOME/formulas, or the project's .beads/formulas
+ * (searched in that order; the first of a name wins). Pouring it creates an
+ * epic and one child task per step, with `needs` as blockedBy between them. A
+ * `human` step is the user's: it waits on a human gate, and approving it completes it.
+ * The core has no TOML parser of its own; callers pass one as `toml`.
+ */
+
+const fail = (message) => { throw new AlpError('INVALID_FORMULA', message); };
+const NAME = /^[\w.-]{1,64}$/;
+const STEP_ID = /^[\w-]{1,64}$/;
+const VAR = /\{\{\s*([\w-]+)\s*\}\}/g;
+export const MAX_STEPS = 50;
+
+export function formulaDirs(projectRoot, home) {
+  return [
+    path.join(path.resolve(projectRoot), '.alp', 'formulas'),
+    ...(home ? [path.join(home, 'formulas')] : []),
+    path.join(path.resolve(projectRoot), '.beads', 'formulas'),
+  ];
+}
+
+const FILE = /^(.+)\.formula\.(toml|json)$/;
+
+/** Every formula file found, first of each name, with what parsing it reported. */
+export async function listFormulas(projectRoot, home, { toml } = {}) {
+  const found = new Map();
+  for (const dir of formulaDirs(projectRoot, home)) {
+    let names;
+    try { names = await readdir(dir); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    for (const name of names.sort()) {
+      const match = FILE.exec(name);
+      if (!match || found.has(match[1])) continue;
+      const file = path.join(dir, name);
+      try {
+        const formula = await loadFormula(file, { toml });
+        found.set(match[1], { name: match[1], file, formula });
+      } catch (error) {
+        found.set(match[1], { name: match[1], file, error: error.message });
+      }
+    }
+  }
+  return [...found.values()];
+}
+
+export async function findFormula(projectRoot, home, name, { toml } = {}) {
+  if (!NAME.test(name ?? '')) fail('A formula name has letters, digits, dots, dashes and underscores');
+  const entry = (await listFormulas(projectRoot, home, { toml })).find(candidate => candidate.name === name);
+  if (!entry) fail(`No formula ${name} in ${formulaDirs(projectRoot, home).join(', ')}`);
+  if (entry.error) fail(`${entry.file}: ${entry.error}`);
+  return entry;
+}
+
+export async function loadFormula(file, { toml } = {}) {
+  const text = await readFile(file, 'utf8');
+  if (!file.endsWith('.json') && !toml) fail('reading TOML formulas needs a TOML parser');
+  let data;
+  try { data = file.endsWith('.json') ? JSON.parse(text) : toml(text); }
+  catch (error) { fail(`cannot parse: ${error.message.split('\n')[0]}`); }
+  return validateFormula(data);
+}
+
+const optionalText = (value, name, limit) => {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.length > limit) fail(`${name} must be text of at most ${limit} characters`);
+  return value;
+};
+
+/** Checks a parsed formula and returns it normalized. */
+export function validateFormula(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) fail('A formula is an object');
+  if (typeof data.formula !== 'string' || !NAME.test(data.formula)) fail('formula must name it: letters, digits, dots, dashes and underscores');
+  const vars = {};
+  if (data.vars !== undefined) {
+    if (!data.vars || typeof data.vars !== 'object' || Array.isArray(data.vars)) fail('vars must be a table of variables');
+    for (const [name, spec] of Object.entries(data.vars)) {
+      if (!/^[\w-]{1,64}$/.test(name)) fail(`Variable ${name} has an invalid name`);
+      const value = spec && typeof spec === 'object' ? spec : {};
+      vars[name] = {
+        ...(typeof value.description === 'string' ? { description: value.description } : {}),
+        required: value.required === true,
+        ...(value.default !== undefined ? { default: String(value.default) } : {}),
+      };
+    }
+  }
+  if (!Array.isArray(data.steps) || !data.steps.length || data.steps.length > MAX_STEPS) fail(`steps must list 1 to ${MAX_STEPS} steps`);
+  const ids = new Set();
+  const steps = data.steps.map((step, index) => {
+    if (!step || typeof step !== 'object') fail(`Step ${index + 1} is not a table`);
+    if (typeof step.id !== 'string' || !STEP_ID.test(step.id)) fail(`Step ${index + 1} needs an id of letters, digits, dashes and underscores`);
+    if (ids.has(step.id)) fail(`Two steps have id ${step.id}`);
+    ids.add(step.id);
+    if (typeof step.title !== 'string' || !step.title.trim()) fail(`Step ${step.id} needs a title`);
+    const needs = step.needs === undefined ? [] : step.needs;
+    if (!Array.isArray(needs) || !needs.every(need => typeof need === 'string')) fail(`Step ${step.id}: needs must list step ids`);
+    if (step.priority !== undefined && (!Number.isInteger(step.priority) || step.priority < 0 || step.priority > 4)) fail(`Step ${step.id}: priority must be 0 to 4`);
+    return {
+      id: step.id,
+      title: step.title,
+      ...(optionalText(step.description, `Step ${step.id} description`, DESCRIPTION_CHARS) ? { description: step.description } : {}),
+      type: typeof step.type === 'string' ? step.type : 'task',
+      needs: [...new Set(needs)],
+      ...(step.priority !== undefined ? { priority: step.priority } : {}),
+      ...(Array.isArray(step.labels) ? { labels: step.labels.filter(label => typeof label === 'string') } : {}),
+      ...(Array.isArray(step.paths) ? { paths: step.paths.filter(entry => typeof entry === 'string') } : {}),
+    };
+  });
+  for (const step of steps) for (const need of step.needs) if (!ids.has(need)) fail(`Step ${step.id} needs unknown step ${need}`);
+  // Steps must form no cycle.
+  const state = new Map();
+  const visit = (id, trail) => {
+    if (state.get(id) === 'done') return;
+    if (state.get(id) === 'open') fail(`Steps form a cycle: ${[...trail, id].join(' → ')}`);
+    state.set(id, 'open');
+    for (const need of steps.find(step => step.id === id).needs) visit(need, [...trail, id]);
+    state.set(id, 'done');
+  };
+  for (const step of steps) visit(step.id, []);
+  return {
+    formula: data.formula,
+    ...(optionalText(data.title, 'title', 200) ? { title: data.title } : {}),
+    ...(optionalText(data.description, 'description', DESCRIPTION_CHARS) ? { description: data.description } : {}),
+    ...(Number.isInteger(data.version) ? { version: data.version } : {}),
+    ...(Number.isInteger(data.priority) && data.priority >= 0 && data.priority <= 4 ? { priority: data.priority } : {}),
+    vars,
+    steps,
+  };
+}
+
+/** The variables a pour uses: given values over defaults; unknown or missing required ones refuse it. */
+export function resolveVars(formula, given = {}) {
+  const unknown = Object.keys(given).filter(name => !(name in formula.vars));
+  if (unknown.length) fail(`${formula.formula} has no variable ${unknown.join(', ')}; it takes ${Object.keys(formula.vars).join(', ') || 'none'}`);
+  const values = {};
+  for (const [name, spec] of Object.entries(formula.vars)) {
+    const value = given[name] ?? spec.default;
+    if (value === undefined && spec.required) fail(`${formula.formula} needs --var ${name}=…${spec.description ? ` (${spec.description})` : ''}`);
+    if (value !== undefined) values[name] = String(value);
+  }
+  return values;
+}
+
+function fill(text, values, where) {
+  return text.replace(VAR, (whole, name) => {
+    if (!(name in values)) fail(`${where} uses {{${name}}}, which has no value`);
+    return values[name];
+  });
+}
+
+/**
+ * Pours a formula: an epic for the run and a child task per step, in step order,
+ * so step n is <epic>.n. Returns the epic and its steps' tasks.
+ */
+export async function pourFormula(projectRoot, formula, given, by, { dryRun = false, parent } = {}) {
+  const values = resolveVars(formula, given);
+  const summary = Object.entries(values).map(([name, value]) => `${name}=${value}`).join(', ');
+  const title = formula.title ? fill(formula.title, values, 'title') : `${formula.formula}${summary ? ` (${summary})` : ''}`;
+  const steps = formula.steps.map(step => ({
+    ...step,
+    title: fill(step.title, values, `Step ${step.id}`),
+    ...(step.description ? { description: fill(step.description, values, `Step ${step.id}`) } : {}),
+  }));
+  return batch(projectRoot, ({ add, link }) => {
+    const epic = add({
+      title: title.slice(0, 200), type: 'epic', priority: formula.priority ?? 2, labels: [`formula:${formula.formula}`.slice(0, 50)],
+      ...(formula.description ? { description: fill(formula.description, values, 'description') } : {}),
+      ...(parent ? { parent } : {}),
+    }, by, { event: 'poured', details: { formula: formula.formula }, extra: { formula: { name: formula.formula, ...(formula.version ? { version: formula.version } : {}), vars: values } } });
+    const made = new Map();
+    for (const step of steps) {
+      const human = step.type === 'human';
+      const type = TASK_TYPES.includes(step.type) && step.type !== 'epic' ? step.type : 'task';
+      const task = add({
+        title: step.title.slice(0, 200), type, priority: step.priority ?? formula.priority ?? 2, parent: epic.id,
+        ...(step.description ? { description: step.description } : {}),
+        ...(step.labels ? { labels: step.labels } : {}),
+        ...(step.paths ? { paths: step.paths } : {}),
+      }, by, {
+        event: 'poured', details: { formula: formula.formula, step: step.id },
+        extra: {
+          step: { formula: formula.formula, id: step.id, ...(human ? { human: true } : {}) },
+          ...(human ? { gates: [{ id: 'g1', kind: 'human', note: `Your step: ${step.title}`.slice(0, 2000), at: new Date().toISOString(), by }] } : {}),
+        },
+      });
+      made.set(step.id, task);
+    }
+    for (const step of steps) {
+      for (const need of step.needs) {
+        const refused = link(made.get(step.id), 'blockedBy', made.get(need).id);
+        if (refused) fail(`Step ${step.id} cannot need ${need}: ${refused}`);
+      }
+    }
+    return { epic, tasks: [...made.values()] };
+  }, { dryRun });
+}

package/src/hook-run.js

@@ -0,0 +1,57 @@
+import { signalShell, spawnShell } from './shell.js';
+
+const OUTPUT_LIMIT = 64 * 1024;
+const GRACE_MS = 2000;
+
+/**
+ * Runs a hook's command once (ALPD §43): through /bin/sh (cmd.exe on Windows) in `cwd`, with the event as JSON
+ * on stdin and `env` added to ALP's environment. It runs in its own process group, so
+ * past its timeout the whole group gets SIGTERM, then SIGKILL two seconds later; a
+ * shell's children do not outlive it. Output beyond 64 KiB per stream is cut.
+ * @param {{ command: string, timeoutSec?: number }} hook
+ * @param {unknown} payload
+ * @param {{ cwd: string, env?: Record<string, string>, timeoutMs?: number }} options
+ * @returns {Promise<{ exitCode: number | null, signal: string | null, timedOut: boolean, stdout: string, stderr: string, durationMs: number }>}
+ */
+export function runHook(hook, payload, { cwd, env = {}, timeoutMs } = {}) {
+  const limit = timeoutMs ?? (hook.timeoutSec ?? 60) * 1000;
+  const started = Date.now();
+  return new Promise((resolve, reject) => {
+    const child = spawnShell(hook.command, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    const signal = name => signalShell(child, name);
+    const output = { stdout: '', stderr: '' };
+    for (const stream of ['stdout', 'stderr']) {
+      child[stream].setEncoding('utf8');
+      child[stream].on('data', chunk => { if (output[stream].length < OUTPUT_LIMIT) output[stream] = (output[stream] + chunk).slice(0, OUTPUT_LIMIT); });
+    }
+    let timedOut = false;
+    let kill;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      signal('SIGTERM');
+      kill = setTimeout(() => signal('SIGKILL'), GRACE_MS);
+    }, limit);
+    child.on('error', error => { clearTimeout(timer); clearTimeout(kill); reject(error); });
+    // A background process the hook started may keep its output open; the hook is done when its shell exits.
+    child.on('exit', () => setTimeout(() => { child.stdout.destroy(); child.stderr.destroy(); }, 200).unref());
+    child.on('close', (exitCode, signalName) => {
+      clearTimeout(timer);
+      clearTimeout(kill);
+      resolve({ exitCode, signal: signalName, timedOut, ...output, durationMs: Date.now() - started });
+    });
+    // A command that does not read stdin closes it early; that is not an error.
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(payload) + '\n');
+  });
+}
+
+/** A payload like the one ALP sends for an event, for trying a hook out. */
+export function samplePayload(event, { project, agent = 'main', session = 'alp-sample-session', task } = {}) {
+  return {
+    event, sample: true, project, session, agent,
+    ...(task ? { task } : {}),
+    ...(event === 'handoff' ? { handoff: { outcome: 'complete', summary: 'Sample handoff for a hook test' } } : {}),
+    ...(event === 'task.close' ? { task: task ?? 'alp-sample', reason: 'done' } : {}),
+    ...(event === 'merge' ? { branch: 'alp/sample', files: [] } : {}),
+  };
+}

package/src/hooks.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { validateHook } from './validation.js';
+
+/**
+ * The hook definitions an agent uses (ALPD §45): those it names in agent.json and the
+ * JSON files in its own hooks/ directory. `project` marks a hook that comes from the
+ * project's .alp/, which runs only once the user trusts the workspace.
+ * @param {import('./types.js').ResolvedAgent} agent
+ * @returns {Promise<Array<{ name: string, path: string, project: boolean, event: string, command: string, blocking?: boolean, timeoutSec?: number, match?: { agent?: string, label?: string }, description?: string }>>}
+ */
+export async function loadHooks(agent) {
+  const project = path.join(agent.projectRoot, '.alp') + path.sep;
+  const hooks = [];
+  for (const { name, path: file } of agent.hooks) {
+    if (!file.endsWith('.json')) throw new AlpError('INVALID_HOOK', `${file}: a hook is a JSON definition, hooks/<name>.json, with an event and a command`);
+    let config;
+    try { config = JSON.parse(await readFile(file, 'utf8')); }
+    catch (cause) { throw new AlpError('INVALID_HOOK', `${file}: ${cause.message}`, { cause }); }
+    validateHook(config, file);
+    hooks.push({ ...config, name: name.replace(/\.json$/, ''), path: file, project: file.startsWith(project) });
+  }
+  return hooks;
+}
+
+/**
+ * Whether a hook applies: to its agent, if it names one, and to tasks with its label, if it names one.
+ * @param {{ match?: { agent?: string, label?: string } }} hook
+ * @param {{ agent: string, labels?: string[] }} context
+ */
+export function hookMatches(hook, { agent, labels = [] }) {
+  if (hook.match?.agent && hook.match.agent !== agent) return false;
+  if (hook.match?.label && !labels.includes(hook.match.label)) return false;
+  return true;
+}

package/src/index.js

@@ -0,0 +1,31 @@
+// Stable module namespaces avoid collisions between domain exports.
+export * as adapter from './adapter.js';
+export * as atomic from './atomic.js';
+export * as backup from './backup.js';
+export * as beads from './beads.js';
+export * as delegation from './delegation.js';
+export * as errors from './errors.js';
+export * as formulas from './formulas.js';
+export * as hook_run from './hook-run.js';
+export * as hooks from './hooks.js';
+export * as init from './init.js';
+export * as library_edit from './library-edit.js';
+export * as library from './library.js';
+export * as log from './log.js';
+export * as migrations from './migrations.js';
+export * as models from './models.js';
+export * as permissions from './permissions.js';
+export * as profiles from './profiles.js';
+export * as promptsafe from './promptsafe.js';
+export * as providers from './providers.js';
+export * as resolver from './resolver.js';
+export * as state_schema from './state-schema.js';
+export * as task_rows from './task-rows.js';
+export * as tasks from './tasks.js';
+export * as teams from './teams.js';
+export * as trust from './trust.js';
+export * as upgrade from './upgrade.js';
+export * as user_settings from './user-settings.js';
+export * as validation from './validation.js';
+export * as verify from './verify.js';
+export * as workflow from './workflow.js';