bearings 0.3.4 → 0.4.0

package/dist/{chunk-GEIRG7UT.js → chunk-KQPOIH7N.js}

@@ -13,6 +13,13 @@ var STARTER_SKILL_NAMES = [
   "recording-decisions"
 ];
 var SKILLS = STARTER_SKILL_NAMES;
+var MANUAL_TESTPLAN_FILES = [
+  "SKILL.md",
+  "schema.reference.json",
+  "scripts/validate.mjs",
+  "scripts/view.mjs",
+  "viewer.html"
+];
 function starterSkillNameFromTarget(targetPath) {
   return STARTER_SKILL_NAMES.find((skillName) => targetPath === `.agents/skills/${skillName}/SKILL.md`);
 }
@@ -40,6 +47,11 @@ var SCAFFOLD = [
     template: `agents/skills/${skill}/SKILL.md`,
     target: `.agents/skills/${skill}/SKILL.md`,
     owner: "bearings"
+  })),
+  ...MANUAL_TESTPLAN_FILES.map((file) => ({
+    template: `agents/skills/manual-testplan/${file}`,
+    target: `.agents/skills/manual-testplan/${file}`,
+    owner: "bearings"
   }))
 ];
 
@@ -680,7 +692,7 @@ async function runFreshInit(repoDir, flags, version) {
 async function runInit(repoDir, flags, version) {
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") return runFreshInit(repoDir, flags, version);
-  const { runUpdate } = await import("./update-XOUXGD2Z.js");
+  const { runUpdate } = await import("./update-TBMTUJUT.js");
   return runUpdate(repoDir, flags, version, state);
 }
 

package/dist/cli.js

@@ -8,13 +8,13 @@ import {
   skillBaselinePath,
   starterSkillNameFromTarget,
   validateHarnesses
-} from "./chunk-GEIRG7UT.js";
+} from "./chunk-KQPOIH7N.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 
 // src/verifier.ts
 import { access, lstat, readFile, readdir, readlink, stat } from "fs/promises";
@@ -150,9 +150,27 @@ async function runVerify(repoDir) {
   return v.failures.length ? 1 : 0;
 }
 
+// src/commands/testplan.ts
+import { access as access2 } from "fs/promises";
+import { join as join2 } from "path";
+import { spawn } from "child_process";
+async function runTestplan(repoDir) {
+  const launcher = join2(repoDir, ".agents/skills/manual-testplan/scripts/view.mjs");
+  try {
+    await access2(launcher);
+  } catch {
+    throw new Error("Manual test-plan viewer is not installed. Run `bearings init` to update this repository.");
+  }
+  return new Promise((resolve2, reject) => {
+    const child = spawn(process.execPath, [launcher], { cwd: repoDir, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code) => resolve2(code ?? 1));
+  });
+}
+
 // src/cli.ts
 var pkg = JSON.parse(
-  readFileSync(join2(dirname2(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
+  readFileSync(join3(dirname2(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
 );
 var program = new Command("bearings").version(pkg.version);
 program.command("init").description("Scaffold the agent-friendly setup in the current repository").option("--harness <name...>", "claude and/or opencode").option("--copy", "copy instead of symlink").option("-y, --yes", "accept defaults, no prompts").action(async (o) => {
@@ -166,6 +184,9 @@ program.command("init").description("Scaffold the agent-friendly setup in the cu
 program.command("verify").description("Check the agent-friendly setup for drift and breakage").action(async () => {
   process.exitCode = await runVerify(process.cwd());
 });
+program.command("testplan").description("Open the manual test-plan visualizer").action(async () => {
+  process.exitCode = await runTestplan(process.cwd());
+});
 program.parseAsync().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);

package/dist/{update-XOUXGD2Z.js → update-TBMTUJUT.js}

@@ -14,7 +14,7 @@ import {
   starterSkillNameFromTarget,
   templatesDir,
   validateHarnesses
-} from "./chunk-GEIRG7UT.js";
+} from "./chunk-KQPOIH7N.js";
 
 // src/semver.ts
 function parseSemver(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {

package/templates/agents/skills/manual-testplan/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: manual-testplan
+description: Generate a human-run browser or curl happy-path test checklist from agreed product scope. Use when the developer asks for a manual test plan, acceptance checklist, smoke-test guide, or release verification flow.
+---
+
+# Manual Test Plan
+
+Generate one evidence-backed JSON plan for a human tester. The plan describes
+reachable behavior; the bundled viewer owns presentation and completion state.
+
+## Workflow
+
+1. Read the repository's state/source maps and
+   `.agents/skills/manual-testplan/schema.reference.json`.
+2. Resolve the requested scope to actual public routes, commands, API contracts,
+   or UI flows. Inspect runtime wiring for authentication, feature flags, stub
+   adapters, workers, tenancy, seed data, and external integrations.
+3. If the interface set is empty, broad, or uncertain, list the interfaces you
+   found and ask the developer to confirm or narrow the scope.
+4. Write exactly one plan at `testplans/<scope>.testplan.json` after the scope is
+   clear. Create the directory when needed.
+5. Run
+   `node .agents/skills/manual-testplan/scripts/validate.mjs testplans/<scope>.testplan.json`.
+   Fix every reported violation until it exits zero and prints `OK`.
+6. Run `node .agents/skills/manual-testplan/scripts/view.mjs`. It opens the
+   browser automatically; keep the process available while the developer tests.
+   Report the printed localhost URL only when automatic browser launch fails.
+
+## Content Policy
+
+- Start with section `0`, "Prerequisites & bootstrap". Include only setup needed
+  by this scope; use sub-checks for independent confirmations.
+- Cover happy paths through real interfaces and actual request, response, and UI
+  shapes. Fold cheap negative checks into success expectations instead of
+  creating separate rows.
+- End with "Known limitations" as an `info` section. State stubs, mocks, feature
+  flags, external-delivery behavior, required seed data, and incomplete wiring.
+- Set the top-level `callout` to the single biggest caveat a tester must not
+  mistake for a failure.
+- Use raw HTML only in rich-text fields. Keep it small and semantic; the viewer
+  sanitizes it before rendering. Keep code as `[language, text]` tuples.
+- Never invent interfaces or expected behavior. Requirements describe intent;
+  running code, configuration, schemas, and tests establish what is reachable.
+- Keep completion state out of the plan. The viewer stores it by `scope`.
+
+## Completion
+
+Finish only when the validator prints `OK`, every test maps to a reachable
+interface, limitations match runtime wiring, and the localhost viewer loads the
+generated plan.

package/templates/agents/skills/manual-testplan/schema.reference.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bearings.dev/schemas/manual-testplan.json",
+  "title": "Manual test plan",
+  "$comment": "validate.mjs is the executable authority and additionally enforces globally unique test and sub-check IDs.",
+  "type": "object",
+  "required": ["scope", "title", "sections"],
+  "properties": {
+    "scope": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "title": { "type": "string", "pattern": "\\S" },
+    "subtitle": { "type": "string" },
+    "intro": { "type": "string" },
+    "callout": { "type": "string" },
+    "conventions": { "type": "string" },
+    "sections": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/section" }
+    }
+  },
+  "$defs": {
+    "pair": {
+      "type": "array",
+      "prefixItems": [{ "type": "string" }, { "type": "string" }],
+      "items": false,
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "test": {
+      "type": "object",
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "pattern": "\\S" },
+        "title": { "type": "string", "pattern": "\\S" },
+        "note": { "type": "string" },
+        "code": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/pair" }
+        },
+        "expect": { "type": "string" },
+        "subs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/pair" }
+        },
+        "optional": { "type": "boolean" }
+      }
+    },
+    "section": {
+      "type": "object",
+      "required": ["n", "title", "kind", "tests"],
+      "properties": {
+        "n": { "type": "string", "pattern": "\\S" },
+        "title": { "type": "string", "pattern": "\\S" },
+        "kind": { "enum": ["checklist", "info"] },
+        "intro": { "type": "string" },
+        "tests": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/test" }
+        }
+      }
+    }
+  }
+}

package/templates/agents/skills/manual-testplan/scripts/validate.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const SCOPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TOP_LEVEL_STRINGS = ['title', 'subtitle', 'intro', 'callout', 'conventions'];
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function optionalString(value) {
+  return value === undefined || typeof value === 'string';
+}
+
+function validatePairs(value, path, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((pair, index) => {
+    if (!Array.isArray(pair) || pair.length !== 2 || pair.some((part) => typeof part !== 'string')) {
+      errors.push(`${path}[${index}] must be a two-string tuple`);
+    }
+  });
+}
+
+export function validatePlan(plan) {
+  const errors = [];
+  const ids = new Set();
+
+  if (!isObject(plan)) return ['$ must be an object'];
+  if (!nonEmptyString(plan.scope) || !SCOPE.test(plan.scope)) {
+    errors.push('$.scope must be a lowercase slug');
+  }
+  for (const field of TOP_LEVEL_STRINGS) {
+    if (field === 'title' ? !nonEmptyString(plan[field]) : !optionalString(plan[field])) {
+      errors.push(`$.${field} must be ${field === 'title' ? 'a non-empty string' : 'a string'}`);
+    }
+  }
+  if (!Array.isArray(plan.sections) || plan.sections.length === 0) {
+    errors.push('$.sections must be a non-empty array');
+    return errors;
+  }
+
+  plan.sections.forEach((section, sectionIndex) => {
+    const sectionPath = `$.sections[${sectionIndex}]`;
+    if (!isObject(section)) {
+      errors.push(`${sectionPath} must be an object`);
+      return;
+    }
+    for (const field of ['n', 'title']) {
+      if (!nonEmptyString(section[field])) errors.push(`${sectionPath}.${field} must be a non-empty string`);
+    }
+    if (!['checklist', 'info'].includes(section.kind)) {
+      errors.push(`${sectionPath}.kind must be "checklist" or "info"`);
+    }
+    if (!optionalString(section.intro)) errors.push(`${sectionPath}.intro must be a string`);
+    if (!Array.isArray(section.tests) || section.tests.length === 0) {
+      errors.push(`${sectionPath}.tests must be a non-empty array`);
+      return;
+    }
+
+    section.tests.forEach((test, testIndex) => {
+      const testPath = `${sectionPath}.tests[${testIndex}]`;
+      if (!isObject(test)) {
+        errors.push(`${testPath} must be an object`);
+        return;
+      }
+      for (const field of ['id', 'title']) {
+        if (!nonEmptyString(test[field])) errors.push(`${testPath}.${field} must be a non-empty string`);
+      }
+      if (nonEmptyString(test.id)) {
+        if (ids.has(test.id)) errors.push(`${testPath}.id duplicates "${test.id}"`);
+        ids.add(test.id);
+      }
+      for (const field of ['note', 'expect']) {
+        if (!optionalString(test[field])) errors.push(`${testPath}.${field} must be a string`);
+      }
+      if (test.optional !== undefined && typeof test.optional !== 'boolean') {
+        errors.push(`${testPath}.optional must be a boolean`);
+      }
+      validatePairs(test.code, `${testPath}.code`, errors);
+      validatePairs(test.subs, `${testPath}.subs`, errors);
+      if (Array.isArray(test.subs)) {
+        test.subs.forEach((sub, subIndex) => {
+          if (!Array.isArray(sub) || !nonEmptyString(sub[0])) return;
+          if (ids.has(sub[0])) errors.push(`${testPath}.subs[${subIndex}][0] duplicates "${sub[0]}"`);
+          ids.add(sub[0]);
+        });
+      }
+    });
+  });
+
+  return errors;
+}
+
+export async function loadAndValidatePlan(path) {
+  let plan;
+  try {
+    plan = JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    return { errors: [`Unable to read valid JSON: ${error.message}`] };
+  }
+  const errors = validatePlan(plan);
+  return errors.length === 0 ? { plan, errors } : { errors };
+}
+
+async function main() {
+  const path = process.argv[2];
+  if (!path || process.argv.length !== 3) {
+    console.error('Usage: node validate.mjs <testplan.json>');
+    process.exitCode = 1;
+    return;
+  }
+  const { errors } = await loadAndValidatePlan(path);
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`ERROR ${error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('OK');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

package/templates/agents/skills/manual-testplan/scripts/view.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadAndValidatePlan } from './validate.mjs';
+
+const viewerPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'viewer.html');
+
+export async function listPlans(repoDir) {
+  const plansDir = join(repoDir, 'testplans');
+  const entries = await readdir(plansDir, { withFileTypes: true }).catch((error) => {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  });
+  return Promise.all(entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.testplan.json'))
+    .map(async ({ name: file }) => {
+      const result = await loadAndValidatePlan(join(plansDir, file));
+      return result.plan
+        ? { file, scope: result.plan.scope, title: result.plan.title, valid: true, plan: result.plan }
+        : { file, valid: false, errors: result.errors };
+    }))
+    .then((plans) => plans.sort((a, b) => a.file.localeCompare(b.file)));
+}
+
+function sendJson(response, status, value) {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  response.end(`${JSON.stringify(value)}\n`);
+}
+
+export async function startViewer(repoDir = process.cwd(), port = 0) {
+  const viewer = await readFile(viewerPath);
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? '/', 'http://localhost');
+      response.setHeader('Cache-Control', 'no-store');
+      response.setHeader('X-Content-Type-Options', 'nosniff');
+      if (request.method === 'GET' && url.pathname === '/') {
+        response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        response.end(viewer);
+        return;
+      }
+      if (request.method === 'GET' && url.pathname === '/plans') {
+        const plans = await listPlans(repoDir);
+        sendJson(response, 200, plans.map(({ plan: _, ...summary }) => summary));
+        return;
+      }
+      if (request.method === 'GET' && url.pathname === '/plan') {
+        const file = url.searchParams.get('file');
+        if (!file || basename(file) !== file || !file.endsWith('.testplan.json')) {
+          sendJson(response, 400, { errors: ['Invalid test-plan filename'] });
+          return;
+        }
+        const selected = (await listPlans(repoDir)).find((plan) => plan.file === file);
+        if (!selected) {
+          sendJson(response, 404, { errors: ['Test plan not found'] });
+          return;
+        }
+        if (!selected.valid) {
+          sendJson(response, 422, { errors: selected.errors });
+          return;
+        }
+        sendJson(response, 200, selected.plan);
+        return;
+      }
+      response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      response.end('Not found\n');
+    } catch (error) {
+      sendJson(response, 500, { errors: [error.message] });
+    }
+  });
+
+  await new Promise((resolveListening, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolveListening);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Unable to determine viewer address');
+  return { server, url: `http://127.0.0.1:${address.port}/` };
+}
+
+export function browserCommand(url, platform = process.platform) {
+  if (platform === 'darwin') return { command: 'open', args: [url] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', url] };
+  return { command: 'xdg-open', args: [url] };
+}
+
+export function openBrowser(url, platform = process.platform, spawnProcess = spawn) {
+  const { command, args } = browserCommand(url, platform);
+  return new Promise((resolveOpen) => {
+    const child = spawnProcess(command, args, { stdio: 'ignore', windowsHide: true });
+    child.once('error', () => resolveOpen(false));
+    child.once('close', (code) => resolveOpen(code === 0));
+  });
+}
+
+export async function runViewer(repoDir = process.cwd(), port = 0, open = openBrowser, log = console.log) {
+  const running = await startViewer(repoDir, port);
+  log(running.url);
+  if (!await open(running.url)) log('Could not open the browser. Open the URL above manually.');
+  log('Press Ctrl-C to stop the viewer.');
+  return running;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const portIndex = args.indexOf('--port');
+  let port = 0;
+  if (portIndex !== -1) {
+    const value = args[portIndex + 1];
+    if (!value || !/^\d+$/.test(value) || Number(value) > 65535) {
+      throw new Error('--port must be an integer from 0 to 65535');
+    }
+    port = Number(value);
+    args.splice(portIndex, 2);
+  }
+  if (args.length !== 0) throw new Error('Usage: node view.mjs [--port <port>]');
+  const { server } = await runViewer(process.cwd(), port);
+  const close = () => server.close(() => process.exit(0));
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/templates/agents/skills/manual-testplan/viewer.html

@@ -0,0 +1,313 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; connect-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+  <title>Manual test plan</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --ink: #17202a;
+      --muted: #59636e;
+      --paper: #f5f1e8;
+      --card: #fffdf8;
+      --line: #d8d0c2;
+      --navy: #16324f;
+      --orange: #d45b2c;
+      --green: #27745a;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; color: var(--ink); background: var(--paper); }
+    header { color: #fff; background: var(--navy); border-bottom: 5px solid var(--orange); }
+    .header-inner, main { width: min(1080px, calc(100% - 32px)); margin: 0 auto; }
+    .header-inner { padding: 38px 0 30px; }
+    .eyebrow { margin: 0 0 8px; color: #c7d6e5; font: 700 12px/1.2 ui-monospace, monospace; letter-spacing: .12em; text-transform: uppercase; }
+    h1 { max-width: 850px; margin: 0; font: 750 clamp(30px, 6vw, 58px)/1.03 Georgia, serif; letter-spacing: -.025em; }
+    .subtitle { max-width: 760px; margin: 12px 0 0; color: #dbe6ef; font-size: 16px; }
+    .toolbar { position: sticky; top: 0; z-index: 5; background: rgba(245, 241, 232, .96); border-bottom: 1px solid var(--line); backdrop-filter: blur(8px); }
+    .toolbar-inner { width: min(1080px, calc(100% - 32px)); min-height: 68px; margin: 0 auto; display: flex; align-items: center; gap: 16px; }
+    .plan-select { display: flex; align-items: center; gap: 8px; color: var(--muted); font: 750 12px/1 ui-monospace, monospace; text-transform: uppercase; }
+    select { max-width: min(360px, 35vw); padding: 9px 32px 9px 10px; color: var(--ink); background: var(--card); border: 1px solid var(--line); border-radius: 4px; font: 650 14px/1.2 Inter, ui-sans-serif, system-ui, sans-serif; text-transform: none; }
+    .progress-copy { min-width: 110px; font-weight: 750; }
+    .progress-track { height: 9px; flex: 1; overflow: hidden; background: #ddd6ca; border-radius: 99px; }
+    .progress-fill { width: 0; height: 100%; background: var(--green); transition: width .18s ease; }
+    button { border: 1px solid var(--navy); padding: 8px 13px; color: var(--navy); background: transparent; border-radius: 4px; font: inherit; font-weight: 700; cursor: pointer; }
+    button:hover { color: #fff; background: var(--navy); }
+    main { padding: 34px 0 80px; }
+    .intro, .conventions, .callout { max-width: 850px; margin: 0 0 20px; }
+    .conventions { padding: 18px 20px; background: #e7edf1; border-left: 4px solid var(--navy); }
+    .callout { padding: 18px 20px; background: #fff0e8; border: 1px solid #e2aa91; border-left: 6px solid var(--orange); }
+    section { margin-top: 52px; }
+    .section-heading { display: grid; grid-template-columns: auto 1fr; gap: 14px; align-items: baseline; padding-bottom: 12px; border-bottom: 2px solid var(--navy); }
+    .section-number { color: var(--orange); font: 800 14px/1 ui-monospace, monospace; }
+    h2 { margin: 0; font: 750 clamp(22px, 4vw, 32px)/1.1 Georgia, serif; }
+    .section-intro { max-width: 820px; margin: 15px 0 0; color: var(--muted); }
+    .tests { display: grid; gap: 14px; margin-top: 20px; }
+    article { display: grid; grid-template-columns: 34px minmax(0, 1fr); gap: 10px; padding: 20px; background: var(--card); border: 1px solid var(--line); border-radius: 7px; box-shadow: 0 3px 0 rgba(23, 32, 42, .06); }
+    article.info { grid-template-columns: 1fr; border-left: 5px solid var(--navy); }
+    article.checked { border-color: #91b7a8; background: #f4faf6; }
+    input[type="checkbox"] { width: 21px; height: 21px; margin: 2px 0 0; accent-color: var(--green); cursor: pointer; }
+    h3 { margin: 0; font-size: 18px; line-height: 1.3; }
+    .test-id { margin-right: 8px; color: var(--orange); font: 800 13px/1 ui-monospace, monospace; }
+    .optional { display: inline-block; margin-left: 8px; padding: 2px 6px; color: var(--muted); border: 1px solid var(--line); border-radius: 3px; font: 700 10px/1.4 ui-monospace, monospace; text-transform: uppercase; }
+    .rich { line-height: 1.58; }
+    .rich > :first-child { margin-top: 0; }
+    .rich > :last-child { margin-bottom: 0; }
+    .note { margin-top: 10px; color: var(--muted); }
+    pre { overflow-x: auto; margin: 14px 0 0; padding: 15px; color: #e9f0f5; background: #111c26; border-radius: 5px; font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; }
+    .language { display: block; margin-bottom: 8px; color: #92adc4; font-size: 10px; letter-spacing: .1em; text-transform: uppercase; }
+    .expect { margin-top: 15px; padding: 14px 16px; background: #edf5f1; border-left: 4px solid var(--green); }
+    .expect::before { display: block; margin-bottom: 5px; color: var(--green); content: "EXPECT"; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .1em; }
+    .subs { display: grid; gap: 9px; margin-top: 15px; }
+    .sub { display: grid; grid-template-columns: 24px 1fr; gap: 8px; align-items: start; }
+    .sub input { width: 17px; height: 17px; }
+    .sub-id { color: var(--muted); font: 700 12px/1.5 ui-monospace, monospace; }
+    .error { margin: 50px auto; padding: 22px; color: #761e16; background: #fff0ee; border: 1px solid #d88f87; white-space: pre-wrap; }
+    .empty { margin: 50px auto; padding: 28px; text-align: center; color: var(--muted); background: var(--card); border: 1px dashed var(--line); }
+    a { color: #145d85; }
+    code, kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+    @media (max-width: 620px) {
+      .header-inner, main, .toolbar-inner { width: min(100% - 22px, 1080px); }
+      .header-inner { padding: 28px 0 24px; }
+      .toolbar-inner { gap: 10px; }
+      .toolbar-inner { flex-wrap: wrap; padding: 10px 0; }
+      .plan-select { width: 100%; }
+      select { max-width: none; flex: 1; }
+      .progress-copy { min-width: 86px; font-size: 13px; }
+      article { padding: 16px 14px; }
+      section { margin-top: 38px; }
+    }
+  </style>
+</head>
+<body>
+  <header><div class="header-inner"><p class="eyebrow" id="scope">Test-plan library</p><h1 id="title">Select a test plan</h1><p class="subtitle" id="subtitle">Plans are loaded from the repository's testplans directory.</p></div></header>
+  <div class="toolbar"><div class="toolbar-inner"><label class="plan-select">Plan <select id="plan-picker"><option>Loading plans...</option></select></label><div class="progress-copy" id="progress">0 / 0</div><div class="progress-track"><div class="progress-fill" id="progress-fill"></div></div><button id="reset" type="button">Reset</button></div></div>
+  <main id="content"></main>
+  <script>
+    const allowedTags = new Set(['A', 'B', 'BR', 'CODE', 'EM', 'I', 'KBD', 'LI', 'OL', 'P', 'SPAN', 'STRONG', 'UL']);
+    const lastPlanKey = 'manual-testplan:last-plan';
+    let storageKey = '';
+    let completed = new Set();
+    let total = 0;
+
+    function sanitizedFragment(html) {
+      const template = document.createElement('template');
+      template.innerHTML = html || '';
+      for (const element of [...template.content.querySelectorAll('*')]) {
+        const href = element.getAttribute('href') || '';
+        if (['EMBED', 'IFRAME', 'MATH', 'OBJECT', 'SCRIPT', 'STYLE', 'SVG'].includes(element.tagName)) {
+          element.remove();
+          continue;
+        }
+        if (!allowedTags.has(element.tagName)) {
+          element.replaceWith(...element.childNodes);
+          continue;
+        }
+        for (const attribute of [...element.attributes]) element.removeAttribute(attribute.name);
+        if (element.tagName === 'A') {
+          if (/^(https?:|mailto:|#)/i.test(href)) {
+            element.setAttribute('href', href);
+            element.setAttribute('rel', 'noreferrer');
+          }
+        }
+      }
+      return template.content;
+    }
+
+    function rich(className, html) {
+      const element = document.createElement('div');
+      element.className = `rich ${className}`;
+      element.append(sanitizedFragment(html));
+      return element;
+    }
+
+    function save() {
+      try { localStorage.setItem(storageKey, JSON.stringify([...completed])); } catch {}
+    }
+
+    function updateProgress() {
+      const done = completed.size;
+      document.getElementById('progress').textContent = `${done} / ${total}`;
+      document.getElementById('progress-fill').style.width = `${total ? (done / total) * 100 : 0}%`;
+    }
+
+    function checkbox(id, article) {
+      const input = document.createElement('input');
+      input.type = 'checkbox';
+      input.checked = completed.has(id);
+      input.setAttribute('aria-label', `Mark ${id} complete`);
+      input.addEventListener('change', () => {
+        if (input.checked) completed.add(id); else completed.delete(id);
+        if (article) article.classList.toggle('checked', input.checked);
+        save();
+        updateProgress();
+      });
+      return input;
+    }
+
+    function renderTest(test, kind) {
+      const article = document.createElement('article');
+      if (kind === 'info') article.className = 'info';
+      const body = document.createElement('div');
+      if (kind === 'checklist') {
+        article.append(checkbox(test.id, article));
+        article.classList.toggle('checked', completed.has(test.id));
+      }
+      const heading = document.createElement('h3');
+      const id = document.createElement('span');
+      id.className = 'test-id';
+      id.textContent = test.id;
+      heading.append(id, document.createTextNode(test.title));
+      if (test.optional) {
+        const optional = document.createElement('span');
+        optional.className = 'optional';
+        optional.textContent = 'Optional';
+        heading.append(optional);
+      }
+      body.append(heading);
+      if (test.note) body.append(rich('note', test.note));
+      for (const [language, code] of test.code || []) {
+        const pre = document.createElement('pre');
+        const label = document.createElement('span');
+        label.className = 'language';
+        label.textContent = language;
+        const content = document.createElement('code');
+        content.textContent = code;
+        pre.append(label, content);
+        body.append(pre);
+      }
+      if (test.expect) body.append(rich('expect', test.expect));
+      if (test.subs?.length) {
+        const subs = document.createElement('div');
+        subs.className = 'subs';
+        for (const [subId, copy] of test.subs) {
+          const row = document.createElement('label');
+          row.className = 'sub';
+          if (kind === 'checklist') row.append(checkbox(subId));
+          const text = document.createElement('span');
+          const idText = document.createElement('span');
+          idText.className = 'sub-id';
+          idText.textContent = `${subId} `;
+          text.append(idText, sanitizedFragment(copy));
+          row.append(text);
+          subs.append(row);
+        }
+        body.append(subs);
+      }
+      article.append(body);
+      return article;
+    }
+
+    function render(plan) {
+      document.title = `${plan.title} - Manual test plan`;
+      document.getElementById('scope').textContent = plan.scope;
+      document.getElementById('title').textContent = plan.title;
+      document.getElementById('subtitle').textContent = plan.subtitle || '';
+      storageKey = `manual-testplan:${plan.scope}`;
+      const allIds = plan.sections.flatMap((section) => section.kind === 'checklist'
+        ? section.tests.flatMap((test) => [test.id, ...(test.subs || []).map(([id]) => id)])
+        : []);
+      total = allIds.length;
+      try {
+        completed = new Set(JSON.parse(localStorage.getItem(storageKey) || '[]').filter((id) => allIds.includes(id)));
+      } catch { completed = new Set(); }
+
+      const content = document.getElementById('content');
+      content.className = '';
+      content.replaceChildren();
+      if (plan.intro) content.append(rich('intro', plan.intro));
+      if (plan.callout) content.append(rich('callout', plan.callout));
+      if (plan.conventions) content.append(rich('conventions', plan.conventions));
+      for (const section of plan.sections) {
+        const sectionElement = document.createElement('section');
+        const heading = document.createElement('div');
+        heading.className = 'section-heading';
+        const number = document.createElement('span');
+        number.className = 'section-number';
+        number.textContent = section.n;
+        const title = document.createElement('h2');
+        title.textContent = section.title;
+        heading.append(number, title);
+        sectionElement.append(heading);
+        if (section.intro) sectionElement.append(rich('section-intro', section.intro));
+        const tests = document.createElement('div');
+        tests.className = 'tests';
+        for (const test of section.tests) tests.append(renderTest(test, section.kind));
+        sectionElement.append(tests);
+        content.append(sectionElement);
+      }
+      updateProgress();
+    }
+
+    function showMessage(copy, className = 'empty') {
+      storageKey = '';
+      completed = new Set();
+      total = 0;
+      updateProgress();
+      document.getElementById('scope').textContent = 'Test-plan library';
+      document.getElementById('title').textContent = 'Select a test plan';
+      document.getElementById('subtitle').textContent = 'Plans are loaded from the repository\'s testplans directory.';
+      const content = document.getElementById('content');
+      content.className = className;
+      content.textContent = copy;
+    }
+
+    async function loadPlan(file) {
+      const response = await fetch(`/plan?file=${encodeURIComponent(file)}`);
+      const body = await response.json();
+      if (!response.ok) throw new Error((body.errors || [`Plan request failed (${response.status})`]).join('\n'));
+      try { localStorage.setItem(lastPlanKey, file); } catch {}
+      render(body);
+    }
+
+    async function loadLibrary() {
+      const response = await fetch('/plans');
+      if (!response.ok) throw new Error(`Plan-list request failed (${response.status})`);
+      const plans = await response.json();
+      const picker = document.getElementById('plan-picker');
+      picker.replaceChildren(new Option(plans.length ? 'Choose a plan...' : 'No test plans found', ''));
+      for (const plan of plans) {
+        const suffix = plan.valid ? '' : ' (invalid)';
+        picker.append(new Option(`${plan.title || plan.file}${suffix}`, plan.file));
+      }
+      if (plans.length === 0) {
+        showMessage('No *.testplan.json files were found in testplans/.');
+        return;
+      }
+      let lastPlan = '';
+      try { lastPlan = localStorage.getItem(lastPlanKey) || ''; } catch {}
+      const selected = plans.find((plan) => plan.file === lastPlan && plan.valid);
+      if (selected) {
+        picker.value = selected.file;
+        await loadPlan(selected.file);
+      } else {
+        showMessage('Choose a test plan from the Plan menu above.');
+      }
+      picker.addEventListener('change', async () => {
+        if (!picker.value) {
+          showMessage('Choose a test plan from the Plan menu above.');
+          return;
+        }
+        const plan = plans.find((item) => item.file === picker.value);
+        if (!plan?.valid) {
+          showMessage(`Cannot open ${picker.value}:\n${(plan?.errors || ['Invalid test plan']).join('\n')}`, 'error');
+          return;
+        }
+        try { await loadPlan(picker.value); }
+        catch (error) { showMessage(`Unable to load plan: ${error.message}`, 'error'); }
+      });
+    }
+
+    document.getElementById('reset').addEventListener('click', () => {
+      if (!storageKey || !confirm('Clear completion state for this plan?')) return;
+      completed.clear();
+      save();
+      location.reload();
+    });
+
+    loadLibrary().catch((error) => showMessage(`Unable to load test-plan library: ${error.message}`, 'error'));
+  </script>
+</body>
+</html>