kataster 0.0.0-stage → 0.2.0

package/.claude/skills/implement/scripts/check-language.ts

@@ -0,0 +1,15 @@
+/**
+ * Ubiquitous language in the code: flags words that CONTEXT.md lists under `_Avoid_`
+ *   - in message catalog values (files in messages/, locales/ or i18n/ starting with the artifact language)
+ *   - in identifiers declared in application code (generic programming words like "id" or "type" are skipped)
+ *
+ * Advisory: findings are warnings and never fail the build. A line containing `language-ok` is skipped
+ * (e.g. a third-party library's `user` object).
+ *
+ * Usage: node check-language.ts
+ */
+import * as e from "../../../lib/engineering.ts";
+
+const findings = e.languageFindings();
+for (const f of findings) console.log(`WARNING  ${f.file} (${f.where}): '${f.word}' – the glossary says '${f.preferred}'`);
+console.log(findings.length ? `${findings.length} language warning(s).` : "Glossary language OK.");

package/.claude/skills/implement/scripts/check-scenarios.ts

@@ -0,0 +1,59 @@
+/**
+ * Traceability between acceptance criteria and tests.
+ * Every scenario of a story that is in progress or done needs a test titled exactly `ST-NNN: <scenario title>`.
+ *
+ *   ERROR  a done story with a scenario without a test – unless a later story superseded the scenario
+ *   ERROR  a test title `ST-NNN: …` that matches no scenario (renamed scenario, typo, unknown story)
+ *   ERROR  a superseded scenario (docs/stories/superseded-scenarios.json) that is stale: no such scenario, the
+ *          superseding story not in progress or done, or a test for it still there
+ *   INFO   scenarios still missing for stories in progress
+ *
+ * Usage: node check-scenarios.ts [ST-NNN]   (with an ID: only that story, missing tests are listed)
+ */
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const only = process.argv[2]?.toUpperCase();
+const stories = e.storiesById();
+const titles = e.testTitles();
+const report = new d.Report();
+const info: string[] = [];
+const superseded = e.supersededScenarios();
+
+for (const [id, scenarios] of superseded) {
+  const story = stories.get(id);
+  const own = story ? e.scenarioTitles(story) : [];
+  for (const [scenario, by] of scenarios) {
+    if (!own.includes(scenario)) report.error(id, `superseded scenario "${scenario}" is no scenario of ${id}`);
+    const superseding = stories.get(by);
+    if (!superseding || !["in-progress", "done"].includes(superseding.meta.status)) {
+      report.error(id, `scenario "${scenario}" is superseded by ${by}, which is neither in progress nor done`);
+    }
+    if (titles.some((t) => t.title === e.testTitle(id, scenario).replace(/\s+/g, " "))) {
+      report.error(id, `superseded scenario "${scenario}" still has a test – remove the test or the entry`);
+    }
+  }
+}
+
+for (const [id, s] of stories) {
+  if (only ? id !== only : !["in-progress", "done"].includes(s.meta.status) || s.meta.type !== "story") continue;
+  const { covered, missing: untested } = e.scenarioCoverage(s, titles);
+  const missing = untested.filter((sc) => !superseded.get(id)?.has(sc));
+  for (const sc of missing) {
+    if (s.meta.status === "done") report.error(id, `scenario without test: "${e.testTitle(id, sc)}"`);
+    else info.push(`${id}: missing test "${e.testTitle(id, sc)}"`);
+  }
+  info.push(`${id}: ${covered.length}/${covered.length + missing.length} scenarios covered`);
+}
+
+const known = new Set<string>();
+for (const [id, s] of stories) for (const sc of e.scenarioTitles(s)) known.add(e.testTitle(id, sc).replace(/\s+/g, " "));
+for (const t of titles) {
+  if (only && !t.title.startsWith(`${only}:`)) continue;
+  if (!known.has(t.title)) report.error(t.file, `test title "${t.title}" matches no scenario of any story`);
+}
+
+for (const line of info) console.log(`INFO     ${line}`);
+for (const line of report.lines()) console.log(line);
+console.log(report.ok ? "Scenario traceability OK." : `${report.errors.length} error(s).`);
+process.exit(report.ok ? 0 : 1);

package/.claude/skills/implement/scripts/next-story.ts

@@ -0,0 +1,23 @@
+/**
+ * Prints the story to work on: a story already in progress, otherwise the first `ready` story
+ * in backlog order whose dependencies are all done.
+ *
+ * Usage: node next-story.ts [--json]
+ */
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const { inProgress, next, blocked } = e.nextStory();
+const brief = (s: d.Story) => ({ id: d.storyId(s), title: s.meta.title, type: s.meta.type, size: s.meta.size, path: d.rel(s.path) });
+
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify({ inProgress: inProgress.map(brief), next: next && brief(next), blocked: blocked.length }, null, 2));
+  process.exit(0);
+}
+for (const s of inProgress) console.log(`IN PROGRESS  ${d.storyId(s)} – ${s.meta.title} (${d.rel(s.path)}) – finish this first`);
+if (next) {
+  console.log(`NEXT         ${d.storyId(next)} – ${next.meta.title} [${next.meta.type}, ${next.meta.size}] (${d.rel(next.path)})`);
+} else {
+  console.log("NEXT         none – no ready story has all its dependencies done");
+}
+console.log(`${blocked.length} ready stories are waiting for dependencies.`);

package/.claude/skills/implement/scripts/story-context.ts

@@ -0,0 +1,135 @@
+/**
+ * Builds the context pack for one story as Markdown: everything the implementation needs from discovery,
+ * collected deterministically instead of by searching.
+ *
+ *   - the story itself and the exact test titles its scenarios need
+ *   - dependencies and their status
+ *   - from events.yaml: linked events, the commands producing them (with rules), their aggregates (with invariants),
+ *     policies triggered by the events, every other ID the story mentions (read models, policies, hotspots, …)
+ *     and the hotspots referring to any of these
+ *   - glossary entries of every CONTEXT.md term the story uses
+ *   - the data model sections of the aggregates involved
+ *   - ADRs: those the story mentions in full, the others as a list
+ *   - answered open questions about the story
+ *
+ * Usage: node story-context.ts ST-010 [> file]
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const id = process.argv[2]?.toUpperCase();
+if (!id) {
+  console.error("Usage: node story-context.ts ST-NNN");
+  process.exit(1);
+}
+let story: d.Story;
+try {
+  story = e.findStory(id);
+} catch (err) {
+  console.error(String(err instanceof Error ? err.message : err));
+  process.exit(1);
+}
+const stories = e.storiesById();
+const list = (v: unknown): string[] => (Array.isArray(v) ? v : []);
+const read = (p: string): string => (existsSync(p) ? readFileSync(p, "utf8") : "");
+const storyText = read(story.path);
+const out: string[] = [`# Context pack – ${id}: ${story.meta.title}`, ""];
+
+// Story
+out.push("## Story file", "", `\`${d.rel(story.path)}\``, "", "````markdown", storyText.trimEnd(), "````", "");
+if (story.meta.type === "story") {
+  out.push("## Test titles (exact)", "", "Every scenario gets one test with exactly this title:", "");
+  for (const sc of e.scenarioTitles(story)) out.push(`- \`${e.testTitle(id, sc)}\``);
+  out.push("");
+} else {
+  out.push("## Acceptance checklist", "", "Tick each item (`- [x]`) in the story file when it is done.", "");
+}
+const deps = list(story.meta.depends_on);
+if (deps.length) {
+  out.push("## Dependencies", "");
+  for (const dep of deps) {
+    const s = stories.get(dep);
+    out.push(`- ${dep} – ${s?.meta.title ?? "(missing)"} – **${s?.meta.status ?? "?"}**`);
+  }
+  out.push("");
+}
+
+// Domain model
+const model = d.loadEventsModel();
+const aggregates = new Set<string>();
+if (model) {
+  const idx = d.indexModel(model);
+  const items = (key: string): d.Obj[] => (model[key] ?? []) as d.Obj[];
+  const picked = new Map<string, d.Obj>();
+  const pick = (x: string) => {
+    const item = idx.get(x);
+    if (item) picked.set(x, item);
+  };
+  const events = list(story.meta.events);
+  events.forEach(pick);
+  for (const c of items("commands")) if (list(c.produces).some((ev) => events.includes(ev))) pick(c.id);
+  for (const p of items("policies")) if (list(p.when).some((ev) => events.includes(ev))) pick(p.id);
+  for (const m of storyText.matchAll(/\b(?:AGG|EVT|CMD|POL|RM|HS|ACT|EXT)-[A-Za-z0-9]+\b/g)) pick(m[0]);
+  for (const item of picked.values()) if (item.aggregate) aggregates.add(item.aggregate);
+  aggregates.forEach(pick);
+  const ids = new Set(picked.keys());
+  for (const h of items("hotspots")) if (list(h.refs).some((r) => ids.has(r))) pick(h.id);
+
+  const order = ["EVT", "CMD", "AGG", "POL", "RM", "ACT", "EXT", "HS"];
+  const sorted = [...picked.values()].sort(
+    (a, b) => order.indexOf(a.id.split("-")[0]) - order.indexOf(b.id.split("-")[0]) || a.id.localeCompare(b.id),
+  );
+  out.push("## Event storming model (`docs/domain/events.yaml`)", "", "```yaml", stringify(sorted, { lineWidth: 0 }).trimEnd(), "```", "");
+}
+
+// Glossary
+const glossary = read(join(d.ROOT, "CONTEXT.md"));
+if (glossary) {
+  const entries: string[] = [];
+  const blocks = glossary.split(/\n(?=\*\*[^*]+\*\*:?\s*\n)/);
+  const lowerStory = storyText.toLowerCase();
+  for (const block of blocks.slice(1)) {
+    const term = /^\*\*(.+?)\*\*/.exec(block)?.[1].replace(/:$/, "");
+    if (!term) continue;
+    const re = new RegExp(`\\b${term.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i");
+    if (re.test(lowerStory)) entries.push(block.split(/\n(?=#)/)[0].trim());
+  }
+  if (entries.length) out.push("## Glossary (`CONTEXT.md`, terms used by the story)", "", ...entries.flatMap((x) => [x, ""]));
+}
+
+// Data model
+const dataModel = read(join(d.ROOT, "docs", "architecture", "data-model.md"));
+if (dataModel && aggregates.size) {
+  const secs = dataModel.split(/\n(?=## )/);
+  const hits = secs.filter((s) => [...aggregates].some((a) => s.split("\n")[0].includes(`\`${a}\``)));
+  if (hits.length) out.push("## Data model (`docs/architecture/data-model.md`)", "", ...hits.flatMap((s) => [s.trim().replace(/^## /, "### "), ""]));
+}
+
+// ADRs
+const adrDir = join(d.ROOT, "docs", "adr");
+if (existsSync(adrDir)) {
+  const adrs = readdirSync(adrDir).filter((f) => /^\d{4}-.*\.md$/.test(f)).sort();
+  const mentioned = adrs.filter((f) => {
+    const n = f.slice(0, 4);
+    return storyText.includes(f) || new RegExp(`\\bADR[ -]?${n}\\b`).test(storyText);
+  });
+  out.push("## ADRs (`docs/adr/`)", "");
+  for (const f of adrs) {
+    const text = read(join(adrDir, f));
+    const title = /^# (.+)$/m.exec(text)?.[1] ?? f;
+    const status = /^status:\s*(.+)$/m.exec(text)?.[1] ?? "?";
+    out.push(`- \`${f}\` – ${title} – ${status}${mentioned.includes(f) ? " – **mentioned by the story, full text below**" : ""}`);
+  }
+  out.push("");
+  for (const f of mentioned) out.push(`### ${f}`, "", read(join(adrDir, f)).replace(/^---[\s\S]*?---\n/, "").trim().replace(/^# .*\n/, ""), "");
+}
+
+// Open questions
+const oq = read(join(d.STORIES_DIR, "OPEN_QUESTIONS.md"));
+const rows = oq.split("\n").filter((l) => l.startsWith("|") && new RegExp(`\\b${id}\\b`).test(l));
+if (rows.length) out.push("## Open questions about this story", "", "| Story/artifact | Question | Since | Answer |", "|---|---|---|---|", ...rows, "");
+
+console.log(out.join("\n"));

package/.claude/skills/implement/scripts/story-status.ts

@@ -0,0 +1,47 @@
+/**
+ * Moves a story to a new status, enforcing the workflow and its preconditions:
+ *   in-progress / done – all depends_on are done
+ *   done (story)       – every Gherkin scenario has a test titled `ST-NNN: <scenario title>`
+ *   done (all types)   – every checklist item in the acceptance criteria is ticked (`- [x]`) – also a story's foundation checklist
+ *   done is final      – changes become a new story
+ *   superseded         – from draft, review or ready: done elsewhere or replaced by a new planning; final as well
+ *
+ * Usage: node story-status.ts ST-010 in-progress|ready|done|review|superseded
+ */
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+import { syncStatusAfterChange } from "../../../lib/backlog-sync.ts";
+
+const [id, to] = process.argv.slice(2);
+if (!id || !to || !(d.STATUSES as readonly string[]).includes(to)) {
+  console.error(`Usage: node story-status.ts ST-NNN <${d.STATUSES.join("|")}>`);
+  process.exit(1);
+}
+const stories = e.storiesById();
+const story = stories.get(id.toUpperCase());
+if (!story) {
+  console.error(`Story '${id}' not found in docs/stories/.`);
+  process.exit(1);
+}
+const from = String(story.meta.status);
+const errs = e.transitionErrors(story, from, to, stories);
+if (errs.length) {
+  console.error(`${d.storyId(story)} cannot go from '${from}' to '${to}':\n${errs.map((x) => `  - ${x}`).join("\n")}`);
+  process.exit(1);
+}
+e.writeStatus(story, to);
+
+const report = new d.Report();
+d.validateStories(report, story.path, true);
+if (!report.ok) {
+  e.writeStatus(story, from);
+  console.error(`Validation failed, status left at '${from}':\n${report.lines().join("\n")}`);
+  process.exit(1);
+}
+d.writeBacklogMd();
+console.log(`${d.storyId(story)}: ${from} → ${to}`);
+
+// With a tracker the local mirror is only half the change. GitHub can follow from here (gh); for Jira this prints
+// the MCP transition the agent has to run. A failure here never rolls the status back.
+const tracker = syncStatusAfterChange({ ...story, meta: { ...story.meta, status: to } }, to);
+if (tracker) console.log(tracker);

package/.claude/skills/implement/scripts/verify.ts

@@ -0,0 +1,92 @@
+/**
+ * The one quality gate – used by /implement, CI (`verify` in the project's task runner) and developers.
+ *
+ *   1. Project checks, from `commands` in `.claude/project.json` (falling back to the root package.json
+ *      scripts): lint (incl. module boundary rules), typecheck, test (with --e2e also test:e2e)
+ *   2. Discovery artifacts: events.yaml and stories are valid
+ *   3. Traceability: scenario ↔ test titles, domain IDs in the code
+ *   4. Glossary language (warnings only)
+ *
+ * Writes the result to .claude/state/last-verify.json (shown at session start). Exit 1 if any step failed.
+ *
+ * Usage: node verify.ts [--e2e]
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const here = import.meta.dirname;
+const steps: e.VerifyState["steps"] = [];
+
+function run(name: string, command: string, args: string[] = [], advisory = false): void {
+  console.log(`\n━━ ${name} ━━`);
+  const r = spawnSync(command, args, { cwd: d.ROOT, stdio: "inherit" });
+  const ok = r.status === 0;
+  steps.push({ name, ok: ok || advisory });
+  if (!ok) console.log(advisory ? `⚠ ${name} (advisory, not blocking)` : `✗ ${name} failed`);
+}
+
+function shell(name: string, command: string): void {
+  console.log(`\n━━ ${name} ━━\n$ ${command}`);
+  const r = spawnSync(command, { cwd: d.ROOT, stdio: "inherit", shell: true });
+  const ok = r.status === 0;
+  steps.push({ name, ok });
+  if (!ok) console.log(`✗ ${name} failed`);
+}
+
+/** Commands from the project profile; empty values are skipped. */
+function profileCommands(): Record<string, string> {
+  const file = join(d.ROOT, ".claude", "project.json");
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8")).commands ?? {};
+  } catch {
+    return {};
+  }
+}
+
+const commands = profileCommands();
+const appSteps = ["lint", "typecheck", "test", ...(process.argv.includes("--e2e") ? ["e2e"] : [])];
+const scripts = e.appScripts();
+const configured = appSteps.filter((s) => commands[s]);
+const fallback = appSteps.filter((s) => !commands[s] && scripts[s]);
+
+if (!configured.length && !fallback.length) {
+  console.log(
+    "━━ project ━━\nNo lint/typecheck/test commands configured in `.claude/project.json` and no root package.json scripts – project checks skipped.",
+  );
+}
+for (const s of configured) shell(s, commands[s]);
+for (const s of fallback) run(`npm run ${s}`, "npm", ["run", s]);
+for (const s of appSteps.filter((s) => !commands[s] && !scripts[s])) {
+  if (Object.keys(commands).length || Object.keys(scripts).length) {
+    console.log(`\n━━ ${s} ━━\nno '${s}' command configured – skipped`);
+    steps.push({ name: s, ok: true, skipped: true });
+  }
+}
+
+const node = process.execPath;
+const disc = join(here, "..", "..");
+run("events.yaml", node, [join(disc, "event-storming", "scripts", "validate-events.ts")]);
+run("stories", node, [join(disc, "user-stories", "scripts", "validate-stories.ts")]);
+// The map is generated; staleness is a warning (adoption may not have run yet), not a failed gate.
+run("repository map", node, [join(disc, "adopt", "scripts", "repo-map.ts"), "--check"], true);
+run("path-scoped rules", node, [join(disc, "adopt", "scripts", "rule-doc.ts"), "--check"], true);
+run("project checks", node, [join(d.ROOT, ".claude", "hooks", "project-check.ts"), "--phase", "stop"]);
+run("scenario ↔ test traceability", node, [join(here, "check-scenarios.ts")]);
+run("domain ID traceability", node, [join(here, "check-commands.ts")]);
+run("glossary language", node, [join(here, "check-language.ts")], true);
+
+const ok = steps.every((s) => s.ok);
+e.writeVerifyState({
+  at: new Date().toISOString(),
+  branch: e.git("rev-parse", "--abbrev-ref", "HEAD"),
+  commit: e.git("rev-parse", "--short", "HEAD"),
+  dirty: (e.git("status", "--porcelain") ?? "") !== "",
+  ok,
+  steps,
+});
+console.log(`\n${ok ? "✓ verify passed" : "✗ verify FAILED: " + steps.filter((s) => !s.ok).map((s) => s.name).join(", ")}`);
+process.exit(ok ? 0 : 1);

package/.claude/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review for {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files**: monospaced list, `font-mono text-sm`.
+- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
+- **Problem**: one sentence. What hurts.
+- **Solution**: one sentence. What changes.
+- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable): one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow: interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/.claude/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the `skill` tool with `codebase-design` for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow**, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux – under WSL `wslview <path>` or `explorer.exe "$(wslpath -w <path>)"` –, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files**: which files/modules are involved
+- **Problem**: why the current architecture is causing friction
+- **Solution**: plain English description of what would change
+- **Benefits**: explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, call the `skill` tool with `grilling` to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize; call the `skill` tool with `domain-model` to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the `skill` tool with `codebase-design` and use its design-it-twice parallel sub-agent pattern.

package/.claude/skills/retro/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: retro
+description: "Conduct a retrospective on a coding session."
+disable-model-invocation: true
+---
+
+The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs.
+
+## Steps
+
+1. Call the `skill` tool with `writing-for-agents` for the writing style guide.
+
+2. Read the primary sources for the session the user specifies. This may mean searching through session history on this machine (the current session, or the OpenCode session store under `~/.local/share/opencode/` when running in OpenCode; sessions run on another machine are not there – ask the user). If the user doesn't specify a session, default to the current one.
+
+3. Look for candidates for improvement in these categories.
+
+- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information.
+- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
+- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve `CODING_STANDARDS.md` for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake.
+- **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope.
+- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call.
+- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy.
+- **Information access**: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. _Use when_ a crucial piece of information was not available to the agent.
+
+4. Present these candidates to the user, in order of severity. Removing or simplifying a rule, check or instruction is a candidate on equal footing with adding one, and "the environment held up, nothing to change" is a complete result. Each candidate names the concrete mistake in the session it would have prevented. The user picks; change nothing before they do.
+
+## Reference
+
+### Implementation vs Review
+
+Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures.
+
+The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug.
+
+This means that the review agent should be responsible for imposing coding standards, not the implementation agent.
+
+### Files
+
+You have access to several files in the repo:
+
+- `CLAUDE.md`/`AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files.
+- `CODING_STANDARDS.md`: this file is read during review, not implementation. Add **navigation pointers** to docs folders if the standards file gets more than 1,000 lines long.
+- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
+- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill.
+
+### In this project
+
+The files above map onto this repository:
+
+- `AGENTS.md` (or `CLAUDE.md` when Claude Code is also used) is the always-loaded file.
+- The coding standards are `docs/engineering/conventions.md`; the review agents are `.opencode/agents/code-reviewer.md` and `.opencode/agents/acceptance-tester.md`.
+- The check command is `node .claude/skills/implement/scripts/verify.ts`; the guardrails are `.claude/hooks/*.ts`, wired for OpenCode in `.opencode/plugins/kataster/index.ts` (and for Claude Code in `.claude/settings.json`), and CI in `.github/workflows/`.
+- The rules in `AGENTS.md` bind the retro's proposals too, e.g. the follow-up hurdle and tooling in `.claude/` as TypeScript run directly by Node.