@ludi-uni/ludi-agent-kit 0.1.0

package/docs/phase2-report.md

@@ -0,0 +1,39 @@
+# Phase 2 — minimal executable path (report)
+
+Goal: `task -> scout -> Context Pack -> coder -> validation -> success | escalation candidate`,
+running on pi with capability-routed models.
+
+## What runs for real (verified on this machine)
+
+| Step | Evidence |
+| --- | --- |
+| Registry merge | `adapters/pi/models.local.json` (gitignored) overrides the `TODO-*` template; `scripts/resolve-capabilities.mjs` prints `registrySources.local`. |
+| Model resolution | scout -> cheap-code -> `openai-codex/gpt-5.6-luna:low` -> fallback `freetoken/Qwen3.6-35B-A3B-NVFP4:off` -> `openai-codex/gpt-5.6-sol:medium`; coder -> strong-code -> `openai-codex/gpt-5.6-sol:medium` -> `openai-codex/gpt-5.5:high`. (Names come from `models.local.json`, not code.) |
+| Settings proposal | `adapters/pi/out/settings.proposal.json` = `{"subagents":{"agentOverrides":{scout,coder,visual,reviewer:{model,thinking}}}}`, diffed against live `~/.pi/agent/settings.json` (all `add`). Live settings never written. |
+| Real invocation | `adapters/pi/lib/invoke.mjs` runs `node <pi cli.js> -p --model ... --no-tools --no-session --no-approve`. Both `openai-codex` (OAuth) and `freetoken` (local endpoint) returned text with system prompt honored. |
+| Real E2E | Fixture copied to `%TEMP%`; baseline red. scout (`gpt-5.6-luna:low`, 38 s) produced a pack that normalized cleanly (4 files, 2 snippets, in-repo relative paths; external `~/.pi/agent/AGENTS.md` reported, not rewritten). coder (`gpt-5.6-sol:medium`, 13 s) returned one FILE block; applied `src/math.js`; `npm test` 3/3. `outcome: success`. |
+| Real escalation | With `sol` bound to a non-existent id: attempt 1 failed (`Codex error: ... model is not supported`), runner moved to fallback `codex` (`gpt-5.5:high`), tests passed, `outcome: success, escalated: true, attempts: 2`; failure appended to `## previous_attempts`. |
+| Loop/limit | Later a real `usage limit has been reached` on all openai-codex models: scout fell back to the local model successfully, coder exhausted both candidates after exactly 2 attempts, `outcome: exhausted`, no retry of the same modelId. |
+
+## Still mock / proposal
+
+- `settings.proposal.json` is not applied; pi-subagents launches still inherit the session model until the block is merged.
+- pi-subagents cannot express fallback (removed `fallbackModels`); escalation exists only in the kit runner (`lib/pipeline.mjs withEscalation`), not inside `subagent(...)` launches.
+- The runner uses one-shot `pi -p` with `--no-tools`; agents do not use tools. Coder returns whole-file blocks confined to `relevant_files`.
+- No task classifier; the pipeline is fixed scout->coder. `--agent/--capability` only influence `--dry-run` reporting.
+- `visual`/`reviewer` resolve and appear in the proposal but are not exercised.
+
+## Context Pack schema adjustment (v1.1, backwards compatible)
+
+Real greenfield run ("add src/greet.js + test") showed `relevant_files` legitimately containing only
+*new* files or nothing. Added, all optional: `discovery: {status: found|partial|none, note?}` — `none`
+is the only case that permits an empty `relevant_files`; `relevant_files[].create: true` (Markdown
+reason prefix `(new)`) marks files the coder may create. Validator, JSON schema (`if/then/else`),
+`toMarkdown`, prompts and tests updated. v1.0 packs validate unchanged; older validators would reject
+the new keys, so producers should omit them when not needed.
+
+## Test inventory (47 + 1 PowerShell + 1 opt-in real)
+
+`node --test "tests/*.test.mjs"`: routing 9, context-pack 9, kit 7, loop-guard 6, pipeline 16
+(registry merge ×3, resolution, proposal, normalizer ×2, escalation ×2, loop prevention, scripted
+E2E ×5, parser). `tests/test-sync-pi.ps1` PASS. `tests/e2e-real-pi.mjs` (opt-in, spends quota).

package/docs/roadmap.md

@@ -0,0 +1,27 @@
+# Roadmap — minimal next items
+
+Phase 1 (structure/schema) and Phase 2 (executable path, see `phase2-report.md`) are done.
+Ordered by dependency; each is small and independently testable.
+
+1. **Apply settings proposal safely.** `sync-pi.ps1 -ApplySettings`: back up `settings.json`,
+   merge only `subagents.agentOverrides.{scout,coder,visual,reviewer}`, verify JSON round-trip,
+   refuse on concurrent change. Then `subagent({agent:"coder"})` in pi uses routed models.
+2. **Tool-enabled agents.** Replace one-shot `pi -p --no-tools` for coder with a pi-subagents launch
+   (child gets `read/edit/powershell`), keeping the kit runner as escalation wrapper. Keep the
+   FILE-block path as fallback for tool-less/local models.
+3. **Reviewer step.** After coder success, run `reviewer` (deep-review) read-only on the diff + pack;
+   block "success" on severity-high findings. Same escalation wrapper.
+4. **Rule-based classifier.** `routing/classify.json` (keywords / file globs / has-image -> capability);
+   `--task` only entry; still no LLM classifier.
+5. **Usage-limit awareness.** Recognise provider limit errors in the invoker and mark the backend
+   cooling for the run so both scout and coder skip it (currently each step discovers it separately).
+6. **pi startup check.** Port `check-pi.mjs` (offline RPC `get_commands`) against a temp agent dir
+   populated by `sync-pi.ps1 -Apply`, asserting kit skills, agents and single loop guard.
+7. **codex adapter sync.** `sync-codex.ps1` rendering `rules/` and skills (+ metadata overlay), dry-run first.
+8. **local backend adapter.** `adapters/local/` documenting an OpenAI-compatible endpoint and binding it to `local`.
+
+Orchestrator Phase 1 adds the plan/delegate/evaluate loop. Phase 2 (`docs/orchestrator.md`)
+persists that loop in SQLite so a later process can resume it, including user decisions and
+short-lived backend health. Phase 3 gaps (Asana) are listed there.
+
+Explicit non-goals until the above exist: unbounded autonomous loops, agent-to-agent chat, cost optimization, GUI, pi-web changes.

package/docs/third-party.md

@@ -0,0 +1,15 @@
+# OSS and external dependencies
+
+This repository contains its own source, documentation and scripts under the [MIT license](../LICENSE). Material reused from the predecessor `codex-setting` is enumerated in [the migration notes](migration-from-codex-setting.md); its `LICENSE` carries the same 2026 `ludi-uni` MIT notice. The repository does **not** bundle the executables, Python packages or npm packages below. Installing them separately does not change this repository's license; when redistributing their binaries, read the exact installed version's license, notices and bundled-component terms.
+
+| Tool / project | Used for | Availability / license reference |
+| --- | --- | --- |
+| [pi coding agent](https://github.com/badlogic/pi-mono) and optionally [pi-subagents](https://www.npmjs.com/package/pi-subagents) | Live agent/model calls; subagent integration | Separately installed; verify the license of the **actual pi distribution or fork** in use. `pi-subagents` npm metadata declares MIT. Neither is needed for source validation. |
+| [TypeBox](https://github.com/sinclairzx81/sinclair-typebox) | `Type` import in optional pi extensions (`adapters/pi/{shell-gate,orchestrator-ext}/index.js`) | Provided by the compatible pi extension environment; upstream license: MIT. Not a dependency of core CLI scripts. |
+| [agent-browser](https://github.com/vercel-labs/agent-browser) | Optional browser capability and opt-in browser E2E | Separately installed CLI; upstream license: Apache-2.0. |
+| [Playwright](https://github.com/microsoft/playwright) | Browser UI verification guidance | External tool; upstream license: Apache-2.0. No bundled browser binaries. |
+| [Microsoft WinApp CLI](https://github.com/microsoft/winappCli) | Optional Windows desktop inspection/capture | Separately installed preview CLI; upstream license: MIT. |
+| [FFmpeg](https://ffmpeg.org/legal.html) / `ffprobe` | Optional media capture, frame/audio processing | Separately installed. FFmpeg's licensing is build-dependent (LGPL or GPL options); inspect the actual build before redistribution. |
+| [WhisperX](https://github.com/m-bain/WhisperX) | Optional speech analysis via the local Python adapter | Separately installed Python environment/models; upstream license: BSD-2-Clause. Downloaded models and transitive dependencies may have separate terms. |
+
+Core CLI validation uses Node.js built-ins (including `node:sqlite` for orchestration). The npm manifest declares `typebox` as a peer dependency for the Pi extensions, not a bundled runtime dependency. Provider/model API usage can incur charges and is subject to provider terms; the JSON model catalog is not a statement of licensing, entitlement or present availability. `scripts/check-environment.ps1` probes optional tools but does not install them. The precise licenses of an installed version should be checked at its upstream package/repository before including it in a release archive.

package/lib/agents.mjs

@@ -0,0 +1,79 @@
+// Minimal agent definition loader: YAML-ish frontmatter (flat scalars + comma lists) + body.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateAccess, EXECUTION_MODES } from './orchestrator/permissions.mjs';
+import { withLanguagePolicy } from './language-policy.mjs';
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+function scalar(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?[0-9]+$/.test(value)) return Number(value);
+  return value;
+}
+
+export function parseFrontmatter(text) {
+  const m = text.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) throw new Error('agent: missing frontmatter');
+  const lines = m[1].split('\n');
+  const meta = {};
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+    if (/^\s/.test(raw)) throw new Error(`agent: unexpected indent "${raw.trim()}"`);
+    const idx = raw.indexOf(':');
+    if (idx < 0) throw new Error(`agent: invalid frontmatter line "${raw.trim()}"`);
+    const key = raw.slice(0, idx).trim();
+    const value = raw.slice(idx + 1).trim();
+    if (value !== '') { meta[key] = scalar(value); continue; }
+    const block = {};
+    let nested = false;
+    while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
+      nested = true;
+      const line = lines[++i].trim();
+      if (!line || line.startsWith('#')) continue;
+      const j = line.indexOf(':');
+      if (j < 0) throw new Error(`agent: invalid frontmatter line "${line}"`);
+      block[line.slice(0, j).trim()] = scalar(line.slice(j + 1).trim());
+    }
+    if (nested) meta[key] = block;
+  }
+  return { meta, body: m[2].trim() };
+}
+
+export function validateAgent(agent, routing) {
+  const errors = [];
+  const { meta } = agent;
+  if (typeof meta.name !== 'string' || !NAME.test(meta.name)) errors.push('agent: name must be a lowercase identifier');
+  if (typeof meta.description !== 'string' || !meta.description.trim()) errors.push(`agent ${meta.name}: description required`);
+  if (typeof meta.capability !== 'string') errors.push(`agent ${meta.name}: capability required`);
+  else if (routing && !(meta.capability in routing.capabilities)) errors.push(`agent ${meta.name}: capability "${meta.capability}" not defined in routing`);
+  if ('model' in meta) errors.push(`agent ${meta.name}: must not pin a model; use capability`);
+  if ('provider' in meta) errors.push(`agent ${meta.name}: must not pin a provider; use capability`);
+  const execution = meta.execution?.preferred_mode ?? meta.execution;
+  if (execution !== undefined && !EXECUTION_MODES.includes(execution)) errors.push(`agent ${meta.name}: execution must be oneshot|subagent|pipeline`);
+  errors.push(...validateAccess(meta.access, meta.name));
+  if (!agent.body) errors.push(`agent ${meta.name}: empty system prompt`);
+  return errors;
+}
+
+export function loadAgents(dir, routing) {
+  const agents = [];
+  const errors = [];
+  for (const file of readdirSync(dir).filter(f => f.endsWith('.md') && f !== 'README.md').sort()) {
+    const agent = parseFrontmatter(readFileSync(join(dir, file), 'utf8'));
+    agent.file = file;
+    // Shared language policy (Japanese default) appended once here — not duplicated
+    // into each agents/*.md. Provider-agnostic; schema keys/enums stay untranslated.
+    agent.body = withLanguagePolicy(agent.body);
+    // A locally disabled capability also disables its agents without changing
+    // their shared definitions. Do not surface it as a validation error.
+    if (routing && typeof agent.meta.capability === 'string' && !(agent.meta.capability in routing.capabilities)) continue;
+    const errs = validateAgent(agent, routing);
+    if (agent.meta.name !== file.replace(/\.md$/, '')) errs.push(`agent ${file}: name "${agent.meta.name}" must match filename`);
+    errors.push(...errs);
+    agents.push(agent);
+  }
+  return { agents, errors };
+}

package/lib/context-pack.mjs

@@ -0,0 +1,215 @@
+// Context Pack v1: Markdown parser + structural validator (see context-pack/SPEC.md).
+// Dependency-free so it can run under plain Node in any adapter.
+import { readFileSync } from 'node:fs';
+
+export const SCALAR_FIELDS = ['task', 'goal', 'expected_output'];
+export const LIST_FIELDS = ['constraints', 'repo_rules', 'observed_errors', 'test_commands'];
+export const STRUCT_FIELDS = ['relevant_files', 'relevant_snippets', 'previous_attempts'];
+export const REQUIRED_FIELDS = ['task', 'goal', 'constraints', 'relevant_files', 'expected_output'];
+export const ALL_FIELDS = [...SCALAR_FIELDS, ...LIST_FIELDS, ...STRUCT_FIELDS];
+const META_FIELDS = ['version', 'capability', 'produced_by', 'budget', 'discovery'];
+export const DISCOVERY_STATUS = ['found', 'partial', 'none'];
+const LINES = /^[0-9]+-[0-9]+$/;
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+function splitSections(markdown, { lenient = false } = {}) {
+  const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+  const sections = new Map();
+  const order = [];
+  let current = null, fence = null, buffer = [];
+  let sawTitle = false;
+  const flush = () => { if (current !== null) sections.set(current, buffer.join('\n').trim()); buffer = []; };
+  for (const line of lines) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!fence) fence = fenceMatch[1];
+      else if (line.trim().startsWith(fence)) fence = null;
+      buffer.push(line);
+      continue;
+    }
+    if (!fence && /^# /.test(line)) { sawTitle = true; continue; }
+    const heading = !fence && line.match(/^## +(\S.*?)\s*$/);
+    if (heading) {
+      flush();
+      current = heading[1];
+      if (sections.has(current)) throw new Error(`context-pack: duplicate section "## ${current}"`);
+      order.push(current);
+      sections.set(current, '');
+      continue;
+    }
+    if (current !== null) buffer.push(line);
+  }
+  flush();
+  if (!sawTitle && !(lenient && sections.has('task'))) throw new Error('context-pack: missing "# Context Pack" title');
+  return { sections, order };
+}
+
+function listItems(body) {
+  // Top-level bullets become items; indented sub-bullets are folded into the preceding item.
+  const items = [];
+  for (const raw of body.split('\n')) {
+    if (/^[-*] /.test(raw)) items.push(raw.slice(2).trim());
+    else if (/^\s+[-*] /.test(raw) && items.length) items[items.length - 1] += ' ' + raw.trim().slice(2).trim();
+  }
+  return items;
+}
+function fencedBlocks(body) {
+  const blocks = [];
+  const re = /^ *(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)\n? *\1[ \t]*$/gm;
+  let m;
+  while ((m = re.exec(body))) blocks.push({ language: m[2].trim() || undefined, content: m[3].replace(/\n$/, '') });
+  return blocks;
+}
+const strip = s => s.replace(/^`|`$/g, '');
+
+// Accepts: `path` (lines a-b) — reason | `path:a-b` — reason | `path:a` | path — reason
+function parseFileItem(item) {
+  const m = item.match(/^`([^`]+)`(?:\s*\(lines?\s+([0-9]+(?:-[0-9]+)?)\))?(?:\s*(?:—|--|-|:)\s*(.*))?$/);
+  let path, lines, reason;
+  if (m) { path = m[1]; lines = m[2]; reason = m[3]?.trim(); }
+  else {
+    const first = item.split(/\s+/)[0];
+    path = strip(first);
+    reason = item.slice(first.length).replace(/^\s*(?:—|--|-|:)\s*/, '').trim() || undefined;
+  }
+  let create = false;
+  if (reason && /^\(new\)/i.test(reason)) { create = true; reason = reason.replace(/^\(new\)\s*(?:—|--|-|:)?\s*/i, '').trim() || undefined; }
+  const suffix = path.match(/^(.*?):(\d+)(?:-(\d+))?$/);
+  if (suffix && !/^[A-Za-z]:$/.test(suffix[1])) { path = suffix[1]; lines = lines ?? (suffix[3] ? `${suffix[2]}-${suffix[3]}` : `${suffix[2]}-${suffix[2]}`); }
+  if (lines && !lines.includes('-')) lines = `${lines}-${lines}`;
+  const out = { path };
+  if (lines) out.lines = lines;
+  if (reason) out.reason = reason;
+  if (create) out.create = true;
+  return out;
+}
+function parseSnippets(body) {
+  const out = [];
+  let parts = body.split(/^### +/m).slice(1);
+  // Lenient: list-style headers "- `path:a-b`" followed by a fenced block.
+  if (!parts.length) parts = body.split(/^[-*] +(?=`)/m).slice(1);
+  for (const part of parts) {
+    const nl = part.indexOf('\n');
+    const head = (nl >= 0 ? part.slice(0, nl) : part).trim();
+    const rest = nl >= 0 ? part.slice(nl + 1) : '';
+    const hm = head.match(/^`([^`]+)`(?:\s*\(lines?\s+([0-9]+(?:-[0-9]+)?)\))?/);
+    const block = fencedBlocks(rest)[0];
+    const fileish = parseFileItem(hm ? `\`${hm[1]}\`${hm[2] ? ` (lines ${hm[2]})` : ''}` : head);
+    const snippet = { path: fileish.path, content: block ? block.content : rest.trim() };
+    if (fileish.lines) snippet.lines = fileish.lines;
+    if (block?.language) snippet.language = block.language;
+    out.push(snippet);
+  }
+  return out;
+}
+function parseAttempts(body) {
+  return listItems(body).map(item => {
+    const m = item.match(/^(.*?)\s*(?:—|--|-)\s*outcome:\s*(.*)$/i);
+    return m ? { summary: m[1].trim(), outcome: m[2].trim() } : { summary: item };
+  });
+}
+
+/** Parse Markdown Context Pack into the JSON form. Throws on structural errors. `lenient` tolerates a missing title. */
+export function parseContextPackMarkdown(markdown, { lenient = false } = {}) {
+  const { sections } = splitSections(markdown, { lenient });
+  const pack = { version: 1 };
+  for (const [name, body] of sections) {
+    if (SCALAR_FIELDS.includes(name)) pack[name] = body;
+    else if (LIST_FIELDS.includes(name)) {
+      const blocks = name === 'observed_errors' ? fencedBlocks(body) : [];
+      const items = blocks.length ? blocks.map(b => b.content) : listItems(body);
+      pack[name] = name === 'test_commands' ? items.map(i => i.replace(/^`(.*)`$/, '$1')) : items;
+    }
+    else if (name === 'relevant_files') pack[name] = listItems(body).map(parseFileItem);
+    else if (name === 'relevant_snippets') pack[name] = parseSnippets(body);
+    else if (name === 'previous_attempts') pack[name] = parseAttempts(body);
+    else if (name === 'capability' || name === 'produced_by') pack[name] = body;
+    else if (name === 'discovery') {
+      const m = body.match(/^\s*(found|partial|none)\b\s*(?:(?:—|--|-|:)\s*(.*))?/is);
+      pack.discovery = m ? { status: m[1].toLowerCase(), ...(m[2]?.trim() ? { note: m[2].trim() } : {}) } : { status: body.trim() };
+    }
+    else throw new Error(`context-pack: unknown section "## ${name}"`);
+  }
+  return pack;
+}
+
+/** Structural validation mirroring context-pack.schema.json. Returns an array of error strings. */
+export function validateContextPack(pack) {
+  const errors = [];
+  const err = m => errors.push(m);
+  if (!pack || typeof pack !== 'object' || Array.isArray(pack)) return ['context-pack: root must be an object'];
+  for (const key of Object.keys(pack)) if (!ALL_FIELDS.includes(key) && !META_FIELDS.includes(key)) err(`context-pack: unknown field "${key}"`);
+  for (const f of REQUIRED_FIELDS) if (!(f in pack)) err(`context-pack: missing required field "${f}"`);
+  if (pack.version !== undefined && pack.version !== 1) err('context-pack: version must be 1');
+  if (pack.capability !== undefined && !(typeof pack.capability === 'string' && NAME.test(pack.capability))) err('context-pack: capability must be a lowercase capability name');
+  if (pack.budget !== undefined) {
+    if (typeof pack.budget !== 'object' || pack.budget === null) err('context-pack: budget must be an object');
+    else if (pack.budget.max_tokens !== undefined && !(Number.isInteger(pack.budget.max_tokens) && pack.budget.max_tokens > 0)) err('context-pack: budget.max_tokens must be a positive integer');
+  }
+  for (const f of SCALAR_FIELDS) if (f in pack && !(typeof pack[f] === 'string' && pack[f].trim())) err(`context-pack: "${f}" must be a non-empty string`);
+  for (const f of LIST_FIELDS) if (f in pack) {
+    if (!Array.isArray(pack[f])) err(`context-pack: "${f}" must be an array`);
+    else pack[f].forEach((v, i) => { if (!(typeof v === 'string' && v.trim())) err(`context-pack: "${f}[${i}]" must be a non-empty string`); });
+  }
+  if (pack.discovery !== undefined) {
+    if (!pack.discovery || typeof pack.discovery !== 'object') err('context-pack: discovery must be an object');
+    else {
+      if (!DISCOVERY_STATUS.includes(pack.discovery.status)) err(`context-pack: discovery.status must be one of ${DISCOVERY_STATUS.join('|')}`);
+      if (pack.discovery.note !== undefined && typeof pack.discovery.note !== 'string') err('context-pack: discovery.note must be a string');
+      for (const k of Object.keys(pack.discovery)) if (!['status', 'note'].includes(k)) err(`context-pack: discovery has unknown key "${k}"`);
+    }
+  }
+  if ('relevant_files' in pack) {
+    const allowEmpty = pack.discovery?.status === 'none';
+    if (!Array.isArray(pack.relevant_files)) err('context-pack: "relevant_files" must be an array');
+    else if (pack.relevant_files.length === 0 && !allowEmpty) err('context-pack: "relevant_files" must contain at least one entry (or set discovery.status = none)');
+    else pack.relevant_files.forEach((v, i) => {
+      if (v?.create !== undefined && typeof v.create !== 'boolean') err(`context-pack: "relevant_files[${i}].create" must be boolean`);
+      for (const k of Object.keys(v ?? {})) if (!['path', 'reason', 'lines', 'create'].includes(k)) err(`context-pack: "relevant_files[${i}]" has unknown key "${k}"`);
+      if (!v || typeof v.path !== 'string' || !v.path.trim()) err(`context-pack: "relevant_files[${i}].path" is required`);
+      if (v?.lines !== undefined && !LINES.test(v.lines)) err(`context-pack: "relevant_files[${i}].lines" must be "start-end"`);
+      if (v?.path && /^[A-Za-z]:[\\/]|^\\\\/.test(v.path)) err(`context-pack: "relevant_files[${i}].path" must be repository-relative, not absolute`);
+    });
+  }
+  if ('relevant_snippets' in pack) {
+    if (!Array.isArray(pack.relevant_snippets)) err('context-pack: "relevant_snippets" must be an array');
+    else pack.relevant_snippets.forEach((v, i) => {
+      if (!v || typeof v.path !== 'string' || !v.path.trim()) err(`context-pack: "relevant_snippets[${i}].path" is required`);
+      if (!v || typeof v.content !== 'string') err(`context-pack: "relevant_snippets[${i}].content" is required`);
+      if (v?.lines !== undefined && !LINES.test(v.lines)) err(`context-pack: "relevant_snippets[${i}].lines" must be "start-end"`);
+    });
+  }
+  if ('previous_attempts' in pack) {
+    if (!Array.isArray(pack.previous_attempts)) err('context-pack: "previous_attempts" must be an array');
+    else pack.previous_attempts.forEach((v, i) => {
+      if (!v || typeof v.summary !== 'string' || !v.summary.trim()) err(`context-pack: "previous_attempts[${i}].summary" is required`);
+    });
+  }
+  return errors;
+}
+
+export function loadContextPack(path) {
+  const text = readFileSync(path, 'utf8');
+  const pack = path.toLowerCase().endsWith('.json') ? JSON.parse(text) : parseContextPackMarkdown(text);
+  const errors = validateContextPack(pack);
+  if (errors.length) throw new Error(errors.join('\n'));
+  return pack;
+}
+
+/** Serialize the JSON form back to canonical Markdown. */
+export function toMarkdown(pack) {
+  const out = ['# Context Pack', ''];
+  const section = (name, body) => { out.push(`## ${name}`, body.trimEnd(), ''); };
+  section('task', pack.task);
+  section('goal', pack.goal);
+  section('constraints', pack.constraints.map(c => `- ${c}`).join('\n') || '-');
+  if (pack.discovery) section('discovery', `${pack.discovery.status}${pack.discovery.note ? ` — ${pack.discovery.note}` : ''}`);
+  section('relevant_files', pack.relevant_files.map(f => `- \`${f.path}\`${f.lines ? ` (lines ${f.lines})` : ''}${f.create || f.reason ? ` — ${f.create ? '(new) ' : ''}${f.reason ?? ''}`.trimEnd() : ''}`).join('\n') || '(none)');
+  if (pack.relevant_snippets?.length) section('relevant_snippets', pack.relevant_snippets.map(s => `### \`${s.path}\`${s.lines ? ` (lines ${s.lines})` : ''}\n\`\`\`${s.language ?? ''}\n${s.content}\n\`\`\``).join('\n\n'));
+  if (pack.repo_rules?.length) section('repo_rules', pack.repo_rules.map(c => `- ${c}`).join('\n'));
+  if (pack.observed_errors?.length) section('observed_errors', pack.observed_errors.map(e => `\`\`\`\n${e}\n\`\`\``).join('\n\n'));
+  if (pack.test_commands?.length) section('test_commands', pack.test_commands.map(c => `- \`${c}\``).join('\n'));
+  if (pack.previous_attempts?.length) section('previous_attempts', pack.previous_attempts.map(a => `- ${a.summary}${a.outcome ? ` — outcome: ${a.outcome}` : ''}`).join('\n'));
+  section('expected_output', pack.expected_output);
+  return out.join('\n');
+}