@printpractical/cruze 0.0.1

package/dist/domain/validation/plan_rules.js

@@ -0,0 +1,105 @@
+import { factsOf, isUnbuilt } from "../elements.js";
+import { findIds, kindOf } from "../ids.js";
+                                                  
+                                                  
+import { isPlanned, readScope, readTasks, readTestPlan,            } from "../project/plan_parts.js";
+                                                              
+import { error, warning,              } from "./problem.js";
+
+const TEST_KINDS = ["behaviour", "contract", "domain", "smoke"];
+
+/**
+ * Rules for one buildable change: its scope names only things that can be built. Once it is
+ * planned, every scope ID is proved by a task, every delivered scenario has a behaviour test,
+ * and every port a built adapter implements has a contract test.
+ */
+export function changePlanProblems(
+  view             ,
+  path        ,
+  doc             ,
+  delta                                    ,
+  available             ,
+)            {
+  const scope = readScope(doc);
+  if (scope === null) return [error(path, undefined, "missing-section", 'the change needs a "## Scope" section')];
+  const problems            = [...scopeTargetProblems(view, path, scope, delta.delta)];
+  if (!isPlanned(doc)) return [...problems, warning(path, undefined, "not-planned", "the change has no test plan or tasks yet; plan fills them")];
+  const { tasks, malformed } = readTasks(doc);
+  for (const line of malformed) {
+    problems.push(error(path, line, "task-format", "task lines read: - T<n>: `<owner>` in `<path>`[, `<path>`], proves <ID>[, <ID>]"));
+  }
+  if (tasks.length === 0 && malformed.length === 0) problems.push(error(path, undefined, "missing-tasks", "the change has no tasks"));
+
+  const proved = new Set(tasks.flatMap((task) => task.proves));
+  const taskPaths = tasks.flatMap((task) => task.paths);
+  for (const task of tasks) {
+    for (const id of task.proves.filter((id) => !available.has(id))) {
+      problems.push(error(path, task.line, "unknown-id", `${task.number} proves ${id}, which is not defined`));
+    }
+  }
+  for (const id of [...scope.delivers, ...scope.builds]) {
+    if (kindOf(id) === "MOD") {
+      const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
+      if (!taskPaths.some((p) => modulePaths.some((m) => p.startsWith(m)))) {
+        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}`));
+      }
+    } else if (kindOf(id) === "REQ") {
+      const scenarios = delta.delta.entries.find((e) => e.element.id === id)?.scenarios.map((s) => s.id) ?? [];
+      if (!proved.has(id) && !scenarios.some((s) => proved.has(s))) problems.push(error(path, scope.line, "unproved-scope", `no task proves ${id} or its scenarios`));
+    } else if (!proved.has(id)) {
+      problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task proves it`));
+    }
+  }
+
+  const rows = readTestPlan(doc);
+  for (const row of rows) {
+    if (!TEST_KINDS.includes(row.kind)) problems.push(error(path, row.line, "test-kind", `test kind must be one of ${TEST_KINDS.join(", ")}`));
+    const subject = findIds(row.subject)[0];
+    if (subject === undefined || !available.has(subject)) problems.push(error(path, row.line, "unknown-id", `test subject "${row.subject}" is not a defined ID`));
+    if (row.file === "") problems.push(error(path, row.line, "test-file", "every test plan row names its test file"));
+  }
+  for (const id of scope.delivers.filter((id) => kindOf(id) === "SCN")) {
+    if (!rows.some((row) => findIds(row.subject)[0] === id && row.kind === "behaviour")) {
+      problems.push(error(path, scope.line, "missing-behaviour-test", `${id} is delivered but has no behaviour row in the test plan`));
+    }
+  }
+  for (const adapter of scope.builds.filter((id) => kindOf(id) === "ADP")) {
+    const ports = (factsOfScoped(view, delta.doc, delta.delta, adapter).get("Implements") ?? []).flatMap(findIds).filter((id) => kindOf(id) === "PORT");
+    for (const port of ports.filter((p) => !rows.some((row) => findIds(row.subject)[0] === p && row.kind === "contract"))) {
+      problems.push(error(path, scope.line, "missing-contract-test", `${adapter} implements ${port} but the test plan has no contract row for ${port}`));
+    }
+  }
+  return problems;
+}
+
+/** Scope IDs must come from the item's deltas or be planned in the living docs. */
+function scopeTargetProblems(view             , path        , scope       , delta       )            {
+  const problems            = [];
+  for (const id of [...scope.delivers, ...scope.builds]) {
+    if (delta.ids.has(id)) continue;
+    const living = view.living.elements.get(id);
+    if (living === undefined) problems.push(error(path, scope.line, "unknown-id", `${id} is in scope but defined nowhere`));
+    else if (!isUnbuilt(living.doc, living.element)) {
+      problems.push(error(path, scope.line, "scope-not-planned", `${id} is already built; change it through a MODIFIED operation in the delta`));
+    }
+  }
+  for (const id of scope.removes) {
+    const removal = delta.entries.find((e) => e.element.id === id && e.element.op === "REMOVED");
+    if (removal === undefined) problems.push(error(path, scope.line, "scope-removes", `${id} is in Removes but the delta has no REMOVED operation for it`));
+  }
+  if (scope.delivers.length + scope.builds.length + scope.removes.length === 0) {
+    problems.push(warning(path, scope.line, "empty-scope", "the scope delivers and builds nothing"));
+  }
+  return problems;
+}
+
+/** An element's facts as this item will build it: from its delta when it has one, else from the living docs. */
+function factsOfScoped(view             , doc             , delta       , id        )                        {
+  const fromDelta = delta.entries.find((e) => e.element.id === id);
+  const living = view.living.elements.get(id);
+  return fromDelta !== undefined ? factsOf(doc, fromDelta.element) : living !== undefined ? factsOf(living.doc, living.element) : new Map                  ();
+}
+
+function modulePathsOf(view             , doc             , delta       , id        )           {
+  return (factsOfScoped(view, doc, delta, id).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => p !== "");
+}

package/dist/domain/validation/problem.js

@@ -0,0 +1,21 @@
+/** One way a document breaks the cruze-formats rules. */
+                          
+               
+                                                              
+                
+               
+                  
+                                
+ 
+
+export function error(path        , line                    , rule        , message        )          {
+  return line === undefined ? { path, rule, message, severity: "error" } : { path, line: line + 1, rule, message, severity: "error" };
+}
+
+export function warning(path        , line                    , rule        , message        )          {
+  return { ...error(path, line, rule, message), severity: "warning" };
+}
+
+export function sortProblems(problems           )            {
+  return [...problems].sort((a, b) => a.path.localeCompare(b.path) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
+}

package/dist/domain/validation/project_rules.js

@@ -0,0 +1,99 @@
+import { factsOf } from "../elements.js";
+import { matchesAny } from "../glob.js";
+import { findIds } from "../ids.js";
+import { parseMarkdown,                  } from "../markdown.js";
+import { PATHS } from "../project/layout.js";
+import { readRoadmapItems } from "../project/roadmap.js";
+                                                              
+import { error, warning,              } from "./problem.js";
+
+/** Rules that span the project: leftover template guides, the roadmap and the config. */
+
+const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
+const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
+
+/**
+ * Unfilled `<guides>` and `{{placeholders}}` outside code, in living docs and active work.
+ * Managed blocks are skipped: the CLI writes them, and they may quote text such as `<COMMAND>`.
+ */
+export function templateLeftovers(view             )            {
+  const paths = [...view.living.docs.keys(), PATHS.roadmap, PATHS.glossary, ...view.items.filter((i) => !i.archived).map((i) => i.path)];
+  return paths.flatMap((path) => {
+    const text = view.snapshot.get(path);
+    if (text === undefined) return [];
+    const doc = parseMarkdown(text);
+    return doc.lines.flatMap((line, i) => {
+      if (doc.inFence[i] || doc.inManaged[i]) return [];
+      const withoutCode = line.replace(/`[^`]*`/g, "");
+      if (GUIDE.test(withoutCode) || PLACEHOLDER.test(withoutCode)) {
+        return [error(path, i, "template-leftover", "replace the template guide or placeholder on this line")];
+      }
+      return [];
+    });
+  });
+}
+
+export function roadmapProblems(view             )            {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return [];
+  const doc = parseMarkdown(text);
+  const problems            = [];
+  const items = new Map                                               ();
+  for (const { slug: item, kind, blockedBy, line } of readRoadmapItems(text)) {
+    if (items.has(item)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} appears twice`));
+    if (!["feature", "change"].includes(kind)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} kind must be feature or change`));
+    items.set(item, { blockedBy, line });
+  }
+  for (const [item, { blockedBy, line }] of items) {
+    for (const blocker of blockedBy.filter((b) => !items.has(b))) problems.push(error(PATHS.roadmap, line, "roadmap-blocker", `${item} is blocked by unknown item ${blocker}`));
+  }
+  const cycle = findCycle(items);
+  if (cycle !== null) problems.push(error(PATHS.roadmap, undefined, "roadmap-cycle", `blocking cycle: ${cycle.join(" -> ")}`));
+  const coverage = doc.lines.join("\n").split(/^## Coverage$/m)[1] ?? "";
+  for (const goal of [...view.living.elements.keys()].filter((id) => id.startsWith("GOAL-"))) {
+    if (!findIds(coverage).includes(goal)) problems.push(warning(PATHS.roadmap, undefined, "goal-uncovered", `${goal} has no items in the coverage table`));
+  }
+  return problems;
+}
+
+function findCycle(items                                      )                  {
+  const state = new Map                             ();
+  const visit = (item        , path          )                  => {
+    if (state.get(item) === "done") return null;
+    if (state.get(item) === "visiting") return [...path.slice(path.indexOf(item)), item];
+    state.set(item, "visiting");
+    for (const next of items.get(item)?.blockedBy ?? []) {
+      const found = visit(next, [...path, item]);
+      if (found !== null) return found;
+    }
+    state.set(item, "done");
+    return null;
+  };
+  for (const item of items.keys()) {
+    const found = visit(item, []);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+export function configProblems(view             )            {
+  if (view.config === null) return [error(PATHS.config, undefined, "config-missing", "the project has no .cruze/config.yaml; run cruze init")];
+  const problems = view.config.problems.map((message) => error(PATHS.config, undefined, "config", message));
+  const config = view.config.config;
+  const architecture = view.living.docs.get(PATHS.architecture);
+  if (config === null || architecture === undefined || config.layers.length === 0) return problems;
+  for (const { element } of [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-"))) {
+    for (const path of modulePaths(architecture, element)) {
+      const probe = path.endsWith("/") ? `${path}probe.file` : path;
+      const layers = config.layers.filter((layer) => matchesAny(probe, layer.paths));
+      if (layers.length !== 1) {
+        problems.push(warning(PATHS.config, undefined, "module-layer", `${element.id} path ${path} falls in ${layers.length} layers; it should fall in exactly one`));
+      }
+    }
+  }
+  return problems;
+}
+
+function modulePaths(doc             , element                               )           {
+  return (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? ""));
+}

package/dist/domain/validation/validate_project.js

@@ -0,0 +1,31 @@
+                                                              
+import { livingProblems } from "./living_rules.js";
+import { error, sortProblems,              } from "./problem.js";
+import { configProblems, roadmapProblems, templateLeftovers } from "./project_rules.js";
+import { workItemProblems } from "./work_item_rules.js";
+
+/** Every rule in the cruze-formats skill, applied to the whole project. */
+export function validateProject(view             )            {
+  const approvalProblems = [...view.approvalProblems].map(([path, message]) => error(path, undefined, "approvals-file", message));
+  const journalProblems = [...view.journalProblems].flatMap(([path, lines]) =>
+    lines.map((line) => error(path, line - 1, "journal-line", "this journal line is not a valid entry")),
+  );
+  return sortProblems([
+    ...configProblems(view),
+    ...livingProblems(view),
+    ...roadmapProblems(view),
+    ...workItemProblems(view),
+    ...templateLeftovers(view),
+    ...approvalProblems,
+    ...journalProblems,
+  ]);
+}
+
+/** Problems that concern one document. */
+export function problemsFor(problems           , path        )            {
+  return problems.filter((problem) => problem.path === path);
+}
+
+export function hasErrors(problems           )          {
+  return problems.some((problem) => problem.severity === "error");
+}

package/dist/domain/validation/work_item_rules.js

@@ -0,0 +1,144 @@
+import { isUnbuilt } from "../elements.js";
+import { findIds, kindOf } from "../ids.js";
+import { elementHash } from "../hashing.js";
+import { findSection,                  } from "../markdown.js";
+import { readDelta,            } from "../project/deltas.js";
+import { readChangesTable, readScope } from "../project/plan_parts.js";
+import { readProgress } from "../project/progress.js";
+                                                              
+import { changesOf, featureOf,               } from "../project/work_items.js";
+import { deltaProblems } from "./delta_rules.js";
+import { malformedIdHeadings, lineOf } from "./living_rules.js";
+import { changePlanProblems } from "./plan_rules.js";
+import { error, warning,              } from "./problem.js";
+
+const REQUIRED_SECTIONS                                     = {
+  feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
+  change: ["Scope", "Test plan", "Tasks"],
+  standalone: ["Intent", "Spec delta", "Architecture delta", "Scope", "Test plan", "Tasks"],
+};
+
+/** Rules for every active feature and change. Archived work is history and is not checked. */
+export function workItemProblems(view             )            {
+  return view.items.filter((item) => !item.archived).flatMap((item) => itemProblems(view, item));
+}
+
+function itemProblems(view             , item          )            {
+  const { path, doc } = item;
+  const problems            = [...malformedIdHeadings(path, doc)];
+  const id = doc.frontmatter?.["id"];
+  if (id !== item.folderName) problems.push(error(path, 0, "frontmatter", `frontmatter id must be "${item.folderName}", the folder name`));
+  const title = doc.frontmatter?.["title"];
+  if (typeof title !== "string" || title.trim() === "") problems.push(error(path, 0, "frontmatter", "frontmatter needs a title"));
+  for (const section of REQUIRED_SECTIONS[item.kind]) {
+    if (findSection(doc, section) === null) problems.push(error(path, undefined, "missing-section", `missing "## ${section}"`));
+  }
+
+  const feature = item.kind === "change" ? featureOf(view.items, item) : undefined;
+  if (item.kind === "change" && feature === undefined) problems.push(error(path, undefined, "orphan-change", "the change's feature.md is missing"));
+  const deltaSource = item.kind === "change" ? feature : item;
+  const delta = deltaSource === undefined ? readDelta(doc) : readDelta(deltaSource.doc);
+  const available = new Set([...view.living.elements.keys(), ...delta.ids]);
+
+  const text = doc.lines.join("\n");
+  for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
+    problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
+  }
+  if (item.kind !== "change") problems.push(...deltaProblems(view, item));
+  if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
+  // A landed change is history: its scope named what it built, which is now built.
+  const landed = item.kind !== "feature" && readProgress(doc).landed !== undefined;
+  if (item.kind !== "feature" && deltaSource !== undefined && !landed) {
+    problems.push(...changePlanProblems(view, path, doc, { delta, doc: deltaSource.doc }, available));
+  }
+  if (item.kind === "standalone") problems.push(...coverageProblems(view, path, delta, doc, [{ name: "this change", ids: scopeIds(item) }]));
+  return problems;
+}
+
+/** A feature's Changes table covers its deltas, and each change folder agrees with its row. */
+function featureScopeProblems(view             , feature          , delta       )            {
+  const rows = readChangesTable(feature.doc);
+  if (rows.length === 0) return [warning(feature.path, undefined, "not-designed", "the feature has no changes yet; architect designs and splits it")];
+  const problems            = [];
+  const landedChanges = new Set(
+    [...readProgress(feature.doc).changes].filter(([, state]) => state === "landed").map(([change]) => change),
+  );
+  const names = rows.map((row) => row.change);
+  for (const row of rows) {
+    if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
+    if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));
+    for (const dependency of row.dependsOn) {
+      const at = names.indexOf(dependency);
+      if (at === -1 || at >= names.indexOf(row.change)) problems.push(error(feature.path, row.line, "change-order", `${row.change} depends on ${dependency}, which must be an earlier change`));
+    }
+    for (const id of landedChanges.has(row.change) ? [] : [...row.delivers, ...row.builds]) {
+      const living = view.living.elements.get(id);
+      const planned = living !== undefined && isUnbuilt(living.doc, living.element);
+      if (!delta.ids.has(id) && !planned) problems.push(error(feature.path, row.line, "scope-not-planned", `${id} must come from this feature's deltas or be planned in the living docs`));
+    }
+  }
+  problems.push(...coverageProblems(view, feature.path, delta, feature.doc, rows.map((row) => ({ name: row.change, ids: [...row.delivers, ...row.builds, ...row.removes], landed: landedChanges.has(row.change) }))));
+
+  for (const change of changesOf(view.items, feature)) {
+    const row = rows.find((r) => r.change === change.folderName);
+    if (row === undefined) {
+      problems.push(error(change.path, undefined, "change-not-listed", `${change.folderName} is not in the feature's Changes table`));
+      continue;
+    }
+    const expected = new Set([...row.delivers, ...row.builds, ...row.removes]);
+    const actual = new Set(scopeIds(change));
+    const differ = [...expected].filter((id) => !actual.has(id)).concat([...actual].filter((id) => !expected.has(id)));
+    if (differ.length > 0) problems.push(error(change.path, readScope(change.doc)?.line, "scope-mismatch", `Scope differs from the feature's Changes row: ${differ.join(", ")}`));
+  }
+  return problems;
+}
+
+/**
+ * Every delta ID lands exactly once. A requirement is covered by its own ID or one of its
+ * scenarios. A scenario must be covered when it is new or its text changed; an unchanged
+ * scenario kept by a MODIFIED requirement may be left out.
+ */
+function coverageProblems(
+  view             ,
+  path        ,
+  delta       ,
+  deltaDoc             ,
+  groups                                                          ,
+)            {
+  const coveredBy = new Map                  ();
+  const pendingBy = new Map                  ();
+  for (const group of groups) {
+    for (const id of group.ids) {
+      coveredBy.set(id, [...(coveredBy.get(id) ?? []), group.name]);
+      if (group.landed !== true) pendingBy.set(id, [...(pendingBy.get(id) ?? []), group.name]);
+    }
+  }
+  const problems            = [];
+  // A change that already landed may be followed by one that rebuilds the same element after a rethink.
+  const once = (id        , line        , required         )       => {
+    const pending = pendingBy.get(id) ?? [];
+    if (required && (coveredBy.get(id) ?? []).length === 0) problems.push(error(path, line, "uncovered", `${id} is not in any change's scope`));
+    if (pending.length > 1) problems.push(error(path, line, "covered-twice", `${id} is in the scope of ${pending.join(" and ")}; it must land exactly once`));
+  };
+  for (const { element, scenarios } of delta.entries) {
+    if (kindOf(element.id) !== "REQ") {
+      once(element.id, element.start, true);
+      continue;
+    }
+    once(element.id, element.start, false);
+    if (![element.id, ...scenarios.map((s) => s.id)].some((id) => coveredBy.has(id))) {
+      problems.push(error(path, element.start, "uncovered", `${element.id} is not delivered by any change`));
+    }
+    for (const scenario of scenarios) {
+      const living = view.living.elements.get(scenario.id);
+      const changed = living === undefined || elementHash(living.doc, living.element) !== elementHash(deltaDoc, scenario);
+      once(scenario.id, scenario.start, element.op !== "REMOVED" && changed);
+    }
+  }
+  return problems;
+}
+
+function scopeIds(item          )           {
+  const scope = readScope(item.doc);
+  return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
+}

package/dist/main.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Composition root: the only place that constructs adapters.
+import { basename } from "node:path";
+import { runCli } from "./adapters/inbound/cli/run_cli.js";
+import { GitRepository } from "./adapters/outbound/git_repository.js";
+import { NodeProjectFiles } from "./adapters/outbound/node_project_files.js";
+import { PackageBundle } from "./adapters/outbound/package_bundle.js";
+import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.js";
+import { SystemClock } from "./adapters/outbound/system_clock.js";
+import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.js";
+
+const cwd = process.cwd();
+const exitCode = await runCli(
+  process.argv.slice(2),
+  {
+    files: new NodeProjectFiles(cwd),
+    bundle: await PackageBundle.locate(),
+    clock: new SystemClock(),
+    repository: new GitRepository(cwd),
+    interactivePrompter: new TerminalPrompter(),
+    unattendedPrompter: new DefaultAnswerPrompter(),
+    runner: new ProcessAgentRunner(cwd),
+    interactive: process.stdin.isTTY === true,
+    directoryName: basename(cwd),
+  },
+  {
+    stdout: (text) => process.stdout.write(`${text}\n`),
+    stderr: (text) => process.stderr.write(`${text}\n`),
+    stdoutIsTerminal: process.stdout.isTTY === true,
+  },
+);
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@printpractical/cruze",
+  "version": "0.0.1",
+  "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
+  "license": "Apache-2.0",
+  "author": "Chris Buchter",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PrintPractical/cruze.git"
+  },
+  "type": "module",
+  "bin": {
+    "cruze": "bin/cruze.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "scripts",
+    "src",
+    "skills",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "build": "node --no-warnings scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,37 @@
+// Builds dist/ from src/ by erasing the TypeScript types with Node's own type stripper.
+// It needs no dependencies, so it also runs on a user's machine: bin/cruze.mjs calls it on
+// first run when dist/ is missing, as it is after a git install. The sources use erasable
+// syntax only (tsconfig's erasableSyntaxOnly), so erasing the types is the whole build.
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { stripTypeScriptTypes } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const src = join(root, "src");
+const dist = join(root, "dist");
+const RELATIVE_TS_IMPORT = /((?:from|import)\s*\(?\s*)(["'])(\.{1,2}\/[^"']+)\.ts\2/g;
+
+const sources = (dir) =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+    entry.isDirectory() ? sources(join(dir, entry.name)) : entry.name.endsWith(".ts") ? [join(dir, entry.name)] : [],
+  );
+
+// Build beside dist/ and swap it in, so a concurrent first run never sees half a build.
+const staging = `${dist}.${process.pid}`;
+rmSync(staging, { recursive: true, force: true });
+for (const file of sources(src)) {
+  const code = stripTypeScriptTypes(readFileSync(file, "utf8"), { mode: "strip" }).replace(RELATIVE_TS_IMPORT, "$1$2$3.js$2");
+  const target = join(staging, relative(src, file)).replace(/\.ts$/, ".js");
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, code);
+}
+chmodSync(join(staging, "main.js"), 0o755);
+rmSync(dist, { recursive: true, force: true });
+try {
+  renameSync(staging, dist);
+} catch (error) {
+  // Another process finished its build first; use that one.
+  rmSync(staging, { recursive: true, force: true });
+  if (!existsSync(join(dist, "main.js"))) throw error;
+}

package/skills/about/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: cruze-about
+description: Explains what Cruze is and what it can do in this repository. Use when the user asks about Cruze, its commands, or how to start working with it.
+---
+
+# About Cruze
+
+Cruze is a spec-driven development framework. It keeps one living model of the system (vision, glossary, architecture and behaviour specs in `docs/`) and delivers work as small changes against that model, each merged back into it when it lands.
+
+This installation is an early preview. It has:
+
+- The `cruze` CLI: `cruze init` sets up a repository, `cruze install` updates the skills after an upgrade, and `cruze help` lists the commands that validate, approve, check, trace and land work.
+- `cruze-formats`, the format of every Cruze document.
+- Knowledge skills holding the standards to design and code to: `cruze-hexagonal-design`, `cruze-behavioural-testing`, `cruze-grilling`, `cruze-domain-language`, `cruze-dependency-approval` and `cruze-research`.
+- The workflow: `explore` (optional), `envision` for the what, `architect` for the how, `roadmap` for the order of work, then `plan`, `build`, `verify` and `land` for each change. `triage` handles bugs, `rethink` steps back from anywhere, and `next` says what to do now.
+
+When the user asks what Cruze can do:
+
+1. Read `.cruze/config.yaml` and report the project name and Cruze version.
+2. Run `cruze --version`, and say whether it differs from the version in `.cruze/config.yaml`. When `cruze` isn't found, tell the user to install it globally as https://github.com/PrintPractical/cruze#quick-start describes; every Cruze skill needs it.
+3. Run `cruze next` and explain the step it names, in the context of the whole workflow.

package/skills/architect/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cruze-architect
+description: Decides how to build and how big, at project scope (domain model, contexts, ports, adapters, module map, layer rules, ADRs and the roadmap with its walking skeleton), feature scope (the architecture delta and its split into changes) or tweak scope (a standalone change), ending with a design review and a walkthrough for your approval.
+---
+
+# Architect
+
+Architect decides the how and the how big. It designs the domain, the ports and adapters, and where every element lives in the source tree, before any code exists. It ends with the one heavy human gate, the design walkthrough, where the user sees the entities, their interactions, the ports and the files, and approves the design.
+
+## Steps
+
+1. **Pick the scope.**
+   - **Project scope:** `docs/architecture.md` doesn't exist yet. Reworking an approved architecture goes through `rethink` instead.
+   - **Feature scope:** the user names a feature, or a feature folder exists without changes.
+   - **Tweak scope:** the user asks for a small change to existing behaviour. When the design shows it needs any architecture change, it becomes a feature: say so and continue at feature scope.
+   - Done when you can say which, and why.
+2. **Check what it builds on.** Run `cruze status`. `docs/vision.md` must be approved and current. At feature and tweak scope, `docs/architecture.md` must be approved and current as well. When a document isn't, stop and name the step that fixes it: `envision` for the vision, and `rethink` for an architecture that changed since its approval.
+3. **Read the living model.** Read `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, the ADRs in `docs/adr/`, `docs/roadmap.md`, `.cruze/config.yaml`, and the specs and code the work touches. Read any note in `.cruze/notes/` the user points to.
+4. **Load the standards.** Read these, and follow them for the rest of this step:
+   - `.agents/skills/cruze-hexagonal-design/SKILL.md`
+   - `.agents/skills/cruze-grilling/SKILL.md`
+   - `.agents/skills/cruze-domain-language/SKILL.md`
+   - `.agents/skills/cruze-research/SKILL.md`
+   - `.agents/skills/cruze-dependency-approval/SKILL.md`
+   - `.agents/skills/cruze-formats/reference/architecture.md`
+5. **Design.** Follow the scope's procedure: [project.md](project.md), [feature.md](feature.md) or [tweak.md](tweak.md). Tweak scope ends there and hands off to `plan`.
+6. **Review the design.** Run the design review in `.agents/skills/cruze-roles/SKILL.md`, with the design reviewer role. Done when every finding has a journaled disposition and no blocker is open without the user's decision.
+7. **Walk the user through it.** Follow [walkthrough.md](walkthrough.md). Apply what the user changes, run `cruze validate` again, and repeat the parts of the walkthrough those changes affect.
+8. **Record the approval.** Only after the user says they approve, run the scope's `cruze approve` command and quote its result, then commit. At project scope, the roadmap follows as its own approval, described in [project.md](project.md).
+
+## Rules
+
+- **Design for the roadmap, build for the phase.** Read the whole feature map and roadmap. When a later feature will need a seam, name it now in a `Future` fact, such as "transport will gain MQTT in phase 3, so inbound adapters stay behind `CommandSource`". Build only what the current work needs.
+- **Adopt before you build.** Before designing any component that isn't domain logic, run the researcher role from `.agents/skills/cruze-roles/SKILL.md` on it. Record every decision in `## Adopt or build`, or at project scope in the adapter's `Adopts` fact. Every new dependency goes to the user through the dependency-approval skill.
+- **Every element with code has a home.** Each `ENT`, `UC`, `PORT`, `ADP` and `FLOW` names its `Module` and `File`. Each file has one responsibility and fits the budget in `.cruze/config.yaml`.
+- **Ask, challenge and defer** as the grilling skill describes. Contexts, ports, public contracts, dependency direction and dependencies are always the user's decisions.
+- **Stepping back is normal.** When the design shows that the vision or an earlier decision is wrong, stop and say so. The vision changes through `envision`, and an approved architecture through `rethink`.
+
+## Next step
+
+- Project scope: `plan` for the walking-skeleton change.
+- Feature scope: `plan` for the feature's first change.
+- Tweak scope: `plan` for the standalone change.

package/skills/architect/feature.md

@@ -0,0 +1,29 @@
+# Architect at feature scope
+
+The result is a `feature.md` with a complete architecture delta and an ordered list of changes, approved at the walkthrough. Formats: `.agents/skills/cruze-formats/reference/work-items.md` and `.agents/skills/cruze-formats/reference/architecture.md`.
+
+## Settle what it does
+
+1. **Find the feature folder.** When `envision "<feature>"` created one, read its intent, settled decisions and spec delta.
+2. **Or settle it now.** When there is no folder, follow `.agents/skills/cruze-envision/feature.md` from its step 2 up to, but not including, its step 8. That puts the feature on the roadmap, checks its blockers, creates the folder and settles the intent and spec delta.
+
+## Design the delta
+
+3. **Trace each scenario through the model.** For every scenario in the spec delta, name the inbound adapter it enters through, the use case that runs it, the domain elements that decide it, and the ports it crosses. Done when every scenario has a path, and each missing piece is a named gap.
+4. **Place each gap,** following "Placing an owner" in the hexagonal-design skill. Prefer extending an existing element when it is the right owner. Each change to the living model becomes an operation under `## Architecture delta`:
+   - `ADDED` for a new element, with its full body.
+   - `MODIFIED` for an existing element, with its full new body. Copy the current body from `docs/architecture.md` and edit it, so nothing is lost by accident.
+   - `REMOVED` with a `Reason`, for an element the feature retires.
+5. **Link behaviour to design.** Each use case that runs a requirement lists it under `Serves`. Add or modify a `FLOW` for each key scenario, with `Serves` naming its scenarios and the failure paths they need.
+6. **Research and decide.** For each new component that isn't domain logic, run the researcher role and record a row in `## Adopt or build`. Take every new dependency to the user.
+7. **Keep later seams open.** When the feature map shows a later feature that will extend this area, record the seam in a `Future` fact, and don't build it.
+8. Done when `cruze validate` reports no errors in the delta itself, and every cited ID exists in the living docs or this delta.
+
+## Split it into changes
+
+9. **Slice vertically.** Each change delivers one or more scenarios end to end, through every layer they need, and can land on its own. The first change is the thinnest slice that proves the design, a tracer bullet. Later changes widen it.
+10. **Fill the Changes table.** Give each row a number and a slug, such as `01-local-serial`. List the scenario and requirement IDs it `Delivers`, the architecture IDs it `Builds`, any IDs it `Removes`, and the changes it `Depends on`.
+11. **Cover everything exactly once.** Every delta ID appears in exactly one change. A module the delta adds, or one still `planned` in the living docs, is built by the first change that writes a file in it. A module already `built` isn't listed. Done when `cruze validate` reports no errors for the feature, and no `not-designed` warning.
+12. **Size each change.** A change that would need more than about 12 tasks, or touches more than one context's domain, splits in two.
+
+Then continue with the review and walkthrough steps of the skill. When the user approves, run `cruze approve <feature>` and quote its result. The command takes the feature's full ID, such as `2026-09-25-open-console`, or its slug when no other active item shares it.