heyspex 0.1.0

package/dist/cli/hs-init.mjs

@@ -0,0 +1,1145 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-init.ts
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync as readFileSync4,
+  writeFileSync
+} from "node:fs";
+import { dirname, join as join3, resolve } from "node:path";
+import process2 from "node:process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+// spex-console/src/lib/cli/customer-claude-md.ts
+function renderCustomerClaudeMd({
+  vaultName,
+  templateVersion
+}) {
+  return `# Agent Instructions \u2014 ${vaultName}
+
+This project's work is tracked in a git-tracked markdown vault under \`specs/\` \u2014 the files *are* the system of record (no separate database or issue tracker). The **HeySpex MCP server** is the source of truth for how to work here: procedures, project memory, and design patterns load **on demand** through its tools, so this file stays small and rarely needs editing.
+
+## Session start
+
+Recall project memory first: \`heyspex_recall_memories({ limit: 10 })\` \u2014 surfaces lessons, decisions, and conventions specific to this vault before you touch anything.
+
+## Procedure discovery \u2014 before any high-stakes action
+
+Before filing work, a destructive action, closing a session, or claiming a spec, consult the procedures via MCP (never guess from an example file):
+
+- \`heyspex_preflight({ intent })\` \u2014 call first; returns which procedures to consult. Intents include \`file_task\`, \`file_epic\`, \`destructive_action\`, \`close_session\`, \`claim_spec\`.
+- \`heyspex_get_procedure({ name })\` \u2014 fetch one full procedure body.
+- \`heyspex_list_procedures({ query? })\` \u2014 browse by tag or keyword.
+
+## The claim handshake
+
+1. \`/hs-next\` returns the on-deck task as a \`prompt_markdown\`.
+2. Confirm with the user, then call \`heyspex_claim_spec({ spec_id })\` \u2014 never start work unclaimed.
+3. After each acceptance criterion, call \`heyspex_report_progress({ acProgress, currentStage })\` so progress shows live.
+4. When every criterion is met, call \`heyspex_submit_for_review({ spec_id })\`. **Never hand-edit \`status:\` in frontmatter** \u2014 the status API flips it and rolls parents up.
+5. Release the claim (\`heyspex_release_spec\`) on hand-off. The agent does not commit or push \u2014 a dirty working tree is the expected hand-off shape; a human reviews and commits.
+
+## Filing new work
+
+The vault under \`specs/\` is the only persistent queue. File new work via \`heyspex_file_spec\` (or \`heyspex_push_plan\` for a batch of epics/tasks) \u2014 **never set an \`id\` by hand**, the server mints it. Cross-link specs with \`[[wikilinks]]\`; every link must resolve to a real file under \`specs/\`.
+
+## Capture knowledge as you go
+
+- Use \`/hs-capture\` to fast-offload an idea before it slips; it promotes to research when ready.
+- After any research or web search, save it via \`heyspex_save_research\` (Executive Summary + at least one cited source).
+- Notable decisions and lessons become memory specs under \`specs/memory/{lessons,decisions,references}\` \u2014 link them to the specs they bear on.
+
+## Conventions
+
+- New entities are always filed via \`heyspex_file_spec\` \u2014 never hand-write frontmatter \`id:\`.
+- The vault is the only durable queue \u2014 track real work as spec files, not ad-hoc TODOs.
+- Agents do not commit or push. A dirty tree at session end is normal hand-off, not an error.
+
+## This file vs. your vault
+
+This CLAUDE.md was generated for **${vaultName}** from HeySpex template version **${templateVersion}** \u2014 it is yours to edit. Unlike HeySpex's own platform contract (which carries HeySpex's internal build tooling), everything above applies to *your* vault and *your* agents. Edit it freely as your project's conventions evolve; a later template update will not overwrite your changes.
+`;
+}
+function customerClaudeMdHook() {
+  return (ctx) => {
+    const content = renderCustomerClaudeMd({
+      vaultName: ctx.vaultName,
+      templateVersion: ctx.templateVersion
+    });
+    const destPath = ctx.deps.joinPath(ctx.targetDir, "CLAUDE.md");
+    ctx.deps.writeFile(destPath, content);
+    ctx.recordWrite(destPath);
+  };
+}
+
+// spex-console/src/lib/cli/init.ts
+import { randomUUID } from "node:crypto";
+
+// scripts/lib/console-url-resolver.mjs
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function readCredentialsConsoleUrl({ homeDir = homedir() } = {}) {
+  try {
+    const raw = readFileSync(join(homeDir, ".heyspex", "credentials.yaml"), "utf8");
+    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
+  } catch {
+    return null;
+  }
+}
+function readDiscoveryFileConsoleUrl(repoRoot) {
+  if (!repoRoot) return null;
+  for (const name of [
+    "console-url",
+    "cockpit-url"
+    /* legacy-cockpit */
+  ]) {
+    try {
+      const discovery = readFileSync(join(repoRoot, ".heyspex", name), "utf8").trim();
+      if (discovery.length > 0) return trimTrailingSlash(discovery);
+    } catch {
+    }
+  }
+  return null;
+}
+var ConsoleUrlUnresolvedError = class extends Error {
+  constructor() {
+    super(
+      `resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`
+    );
+    this.name = "ConsoleUrlUnresolvedError";
+  }
+};
+function resolveConsoleUrl({
+  repoRoot,
+  env = process.env,
+  homeDir = homedir(),
+  strict = false
+} = {}) {
+  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (envUrl) return trimTrailingSlash(envUrl);
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
+  if (credentialsUrl) return credentialsUrl;
+  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
+  if (discoveryUrl) return discoveryUrl;
+  if (strict) throw new ConsoleUrlUnresolvedError();
+  return DEFAULT_CONSOLE_URL;
+}
+
+// spex-console/src/lib/cli/control-shared.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+var EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — unknown subcommand/flag, or a missing required argument. */
+  USAGE: 1,
+  /** Claim race lost — the spec is already claimed by another agent (409). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  FORBIDDEN: 15
+};
+
+// spex-console/src/lib/cli/init.ts
+var HEYSPEX_YAML_SCHEMA_VERSION = 2;
+var DEFAULT_CONSOLE_URL2 = resolveConsoleUrl();
+function mintVaultId() {
+  return randomUUID();
+}
+function parseVaultId(content) {
+  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
+}
+function appendVaultIdLine(content, vaultId) {
+  const trimmed = content.replace(/\n+$/, "");
+  return `${trimmed}
+vault_id: ${vaultId}
+`;
+}
+function parseInitArgs(argv) {
+  let consoleUrl = (process.env.HEYSPEX_CONSOLE_URL ?? process.env.HEYSPEX_COCKPIT_URL)?.trim() || // legacy-cockpit env
+  DEFAULT_CONSOLE_URL2;
+  let vaultRoot = "specs/";
+  let force = false;
+  let json = false;
+  let customerVaultDir;
+  let principles;
+  let vaultName;
+  let noGit = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--no-git") noGit = true;
+    else if (arg === "--principles" || arg.startsWith("--principles=")) {
+      const v = arg === "--principles" ? argv[++i] : arg.slice("--principles=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--principles requires a value" } };
+      }
+      principles = v.trim();
+    } else if (arg === "--vault-name" || arg.startsWith("--vault-name=")) {
+      const v = arg === "--vault-name" ? argv[++i] : arg.slice("--vault-name=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--vault-name requires a value" } };
+      }
+      vaultName = v.trim();
+    } else if (arg === "--console-url" || arg.startsWith("--console-url=") || arg === "--cockpit-url" || // legacy-cockpit alias
+    arg.startsWith("--cockpit-url=")) {
+      const eq = arg.indexOf("=");
+      const v = eq === -1 ? argv[++i] : arg.slice(eq + 1);
+      if (v === void 0 || v.trim() === "") {
+        return {
+          error: {
+            code: EXIT.INVALID_ARG,
+            message: `${eq === -1 ? arg : arg.slice(0, eq)} requires a value`
+          }
+        };
+      }
+      consoleUrl = v.trim();
+    } else if (arg === "--vault-root" || arg.startsWith("--vault-root=")) {
+      const v = arg === "--vault-root" ? argv[++i] : arg.slice("--vault-root=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--vault-root requires a value" } };
+      }
+      vaultRoot = v.trim();
+    } else if (arg === "--customer-vault" || arg.startsWith("--customer-vault=")) {
+      const v = arg === "--customer-vault" ? argv[++i] : arg.slice("--customer-vault=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--customer-vault requires a value" } };
+      }
+      customerVaultDir = v.trim();
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  return {
+    args: { consoleUrl, vaultRoot, force, json, customerVaultDir, principles, vaultName, noGit }
+  };
+}
+function renderHeyspexYaml(args) {
+  return [
+    `schema_version: ${HEYSPEX_YAML_SCHEMA_VERSION}`,
+    `console_url: ${args.consoleUrl}`,
+    `vault_root: ${args.vaultRoot}`,
+    `vault_id: ${args.vaultId}`,
+    ""
+  ].join("\n");
+}
+function readExistingContent(deps, markerPath) {
+  if (!deps.readFile) return null;
+  try {
+    return deps.readFile(markerPath);
+  } catch {
+    return null;
+  }
+}
+function runInit(args, deps) {
+  const markerPath = deps.joinPath(deps.repoRoot, "heyspex.yaml");
+  const exists = deps.fileExists(markerPath);
+  const existingContent = exists ? readExistingContent(deps, markerPath) : null;
+  const existingVaultId = existingContent ? parseVaultId(existingContent) : null;
+  if (exists && !args.force) {
+    if (existingVaultId) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: {
+          ok: true,
+          created: false,
+          path: markerPath,
+          reason: "already_initialized",
+          vault_id: existingVaultId
+        },
+        isError: false
+      };
+    }
+    if (existingContent === null) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: { ok: true, created: false, path: markerPath, reason: "already_initialized" },
+        isError: false
+      };
+    }
+    const mintedId = args.adoptedVaultId ?? mintVaultId();
+    const updatedContent = appendVaultIdLine(existingContent, mintedId);
+    try {
+      deps.writeFile(markerPath, updatedContent);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: `failed to write heyspex.yaml: ${message}`,
+        payload: { ok: false, error: "write_failed", path: markerPath, message },
+        isError: true
+      };
+    }
+    return {
+      code: EXIT.OK,
+      message: `Added vault_id to existing heyspex.yaml at ${markerPath} (schema_version unchanged).`,
+      payload: {
+        ok: true,
+        created: false,
+        backfilled: true,
+        path: markerPath,
+        vault_id: mintedId
+      },
+      isError: false
+    };
+  }
+  const vaultId = existingVaultId ?? args.adoptedVaultId ?? mintVaultId();
+  const content = renderHeyspexYaml({ ...args, vaultId });
+  try {
+    deps.writeFile(markerPath, content);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      code: EXIT.WRITE_FAILED,
+      message: `failed to write heyspex.yaml: ${message}`,
+      payload: { ok: false, error: "write_failed", path: markerPath, message },
+      isError: true
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `${exists ? "Overwrote" : "Wrote"} ${markerPath} (schema_version ${HEYSPEX_YAML_SCHEMA_VERSION}).`,
+    payload: {
+      ok: true,
+      created: true,
+      overwrote: exists,
+      path: markerPath,
+      schema_version: HEYSPEX_YAML_SCHEMA_VERSION,
+      console_url: args.consoleUrl,
+      vault_root: args.vaultRoot,
+      vault_id: vaultId
+    },
+    isError: false
+  };
+}
+var HELP = [
+  "Usage:",
+  "  hs init [--console-url <url>] [--vault-root <path>] [--force] [--json]",
+  "  hs init --customer-vault <dir> [--console-url <url>] [--principles <all|none|a,b>]",
+  "                          [--vault-name <name>] [--no-git] [--json]",
+  "",
+  "Write the top-level heyspex.yaml vault marker (schema_version, console_url,",
+  "vault_root, vault_id) \u2014 the committed file the console / web companion read",
+  "to bootstrap a vault. Idempotent: an existing marker is left untouched unless",
+  "--force, EXCEPT a missing vault_id is backfilled in place either way (backward",
+  "compatible \u2014 no schema_version bump). vault_id is reused exactly when already",
+  "present; a fresh one is minted only when absent.",
+  "Does not modify .heyspex/config.yaml or its templates (ADR-0009).",
+  "",
+  "--customer-vault <dir> scaffolds a REAL customer vault at <dir> instead: the",
+  "specs/ folder tree, heyspex.yaml, and every row of the template shipping",
+  "manifest (spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
+  "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
+  "plus a generated CLAUDE.md, the kept-principles index, and (unless --no-git)",
+  "one initial `git init` + commit pinning the template version. Refuses a",
+  "non-empty <dir> with a plain error. See init.customer-vault.ts.",
+  "",
+  "Flags:",
+  "  --console-url <url>  console_url value (default: $HEYSPEX_CONSOLE_URL or",
+  "                       https://console.heyspex.local).",
+  "  --vault-root <path>  vault_root value (default: specs/).",
+  "  --customer-vault <dir> Scaffold a new customer vault at <dir> (see above).",
+  "  --principles <all|none|a,b> Which universal principle docs to ship",
+  "                       (--customer-vault only). Omitted + a TTY: interactive",
+  "                       keep/skip prompt per principle. Omitted + no TTY: all.",
+  "  --vault-name <name>  Display name for the scaffolded vault (--customer-vault",
+  "                       only; default: <dir>'s basename).",
+  "  --no-git             Skip git init + the initial commit (--customer-vault only).",
+  "  --force              Overwrite an existing heyspex.yaml.",
+  "  --json               Emit a machine-readable JSON result.",
+  "  --help, -h           Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/init.customer-vault.ts
+import { basename } from "node:path";
+
+// spex-console/src/lib/cli/template-manifest.sources.mjs
+var UNIVERSAL_TEMPLATE_ROWS = [
+  { platformSource: "specs/entity-model.md", dest: "specs/entity-model.md" },
+  {
+    platformSource: "specs/protocols/canonical-frontmatter-templates.md",
+    dest: "specs/protocols/canonical-frontmatter-templates.md"
+  },
+  {
+    platformSource: "specs/protocols/spec-hierarchy.md",
+    dest: "specs/protocols/spec-hierarchy.md"
+  },
+  {
+    platformSource: "specs/protocols/memory-protocol.md",
+    dest: "specs/protocols/memory-protocol.md"
+  }
+];
+
+// dist/cli/._template-manifest-sources.cli-shim.mjs
+var CURATED_TEMPLATE_ROOT = "dist/cli-templates/customer-vault";
+
+// spex-console/src/lib/cli/template-manifest.ts
+var TEMPLATE_VERSION = "1.0.0";
+var TODO_NORTH_STAR = `---
+id: HS-L1
+name: TODO \u2014 your product name
+type: l1
+status: open
+priority: 0
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+tags:
+  - north-star
+---
+
+# TODO \u2014 your product name \u2014 North Star
+
+<!-- TODO: replace this whole file. This is a skeleton, not HeySpex's own vision doc \u2014 write
+     YOUR product's constitutional vision here: the problem, the customer, and the small number
+     of non-negotiable principles that every future architecture / entity-model / roadmap
+     decision must trace back to. -->
+
+## Problem
+
+TODO: what problem does this product solve, and for whom?
+
+## Vision
+
+TODO: what does "done" look like at the highest altitude?
+
+## Principles
+
+TODO: the small number of non-negotiable rules every feature decision must satisfy. See
+\`specs/principles-index.md\` for the index pattern this vault ships with.
+`;
+var TODO_PRINCIPLES_INDEX = `---
+id: HS-L2-PRINCIPLES-INDEX
+name: Design Principles Index
+type: l2
+status: open
+priority: 0
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+tags:
+  - l2
+  - principles
+  - index
+---
+
+# Design Principles Index
+
+<!-- TODO: this is a skeleton index, not content. Populate the table below with YOUR product's
+     own numbered design principles (P1, P2, ...) \u2014 each principle should be its own
+     \`memory-decision\` spec under specs/memory/decisions/, linked from this table. A few
+     HeySpex-originated architecture commitments, generalized, are pre-seeded there as a
+     starting point \u2014 keep, edit, or delete each one. -->
+
+One-page reference for the design principles that govern every feature decision in this vault.
+
+## The principles at a glance
+
+| # | One-line rule | When to cite | Refusal trigger | Memory |
+| --- | --- | --- | --- | --- |
+| P1 | TODO | TODO | TODO | TODO: link a real \`[[memory-decision]]\` spec here |
+
+## How to use this index
+
+TODO: describe how code review / feature design / roadmap decisions consult this index.
+`;
+var TODO_STARTER_TASK = `---
+id: HS-START-0001
+name: Your first task
+summary: TODO \u2014 one-line summary of this task.
+type: task
+status: open
+priority: 2
+kind: feature
+effort: 1
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+parent: '[[HS-START-0000-EPIC-your-first-epic]]'
+tags:
+  - near-term
+---
+
+# Your first task
+
+<!-- TODO: replace this with a real first task for your vault. This file exists so there is
+     something claimable the moment your vault is initialized \u2014 see
+     specs/protocols/canonical-frontmatter-templates.md for the full task template. Its
+     parent: field points at the starter epic (HS-START-0000) shipped alongside it, so the
+     vault lints clean (a task with no epic ancestor is an orphan) \u2014 see that epic's own file
+     for what it in turn required (a starter milestone + roadmap). -->
+
+## Intended outcome
+
+TODO: what observable condition does this task produce when done?
+
+## Scope
+
+TODO: what's in scope, what's explicitly out.
+
+## Acceptance criteria
+
+1. TODO: first checkable condition.
+2. TODO: second checkable condition.
+`;
+var TODO_STARTER_EPIC = `---
+id: HS-START-0000
+name: Your first epic
+summary: TODO \u2014 one-line summary of this epic.
+type: epic
+status: open
+kind: feature
+effort: 3
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+milestone: '[[HS-START-0002-MIL-your-first-milestone]]'
+children:
+  - '[[HS-START-0001-TASK-your-first-task]]'
+tags: []
+---
+
+# Your first epic
+
+<!-- TODO: replace this with a real first epic for your vault. This file (plus its starter
+     milestone and roadmap, shipped alongside it) exists so the starter task has a home the
+     moment your vault is initialized \u2014 see specs/protocols/canonical-frontmatter-templates.md
+     for the full epic template. -->
+
+## Intended outcome
+
+**User-visible outcome of this epic (required):** TODO \u2014 what changes for the user when this
+epic ships?
+
+**Moves (\u2191 link, required):** TODO \u2014 which milestone outcome does it move, and how?
+
+## Why this epic exists
+
+**Problem right now (required):** TODO \u2014 one sentence: what specific problem does this solve,
+and why is now the right time?
+
+## Tasks
+
+- [[HS-START-0001-TASK-your-first-task]]
+
+## Acceptance gate \u2014 epic close
+
+TODO: what must be true of every child task for this epic to be done?
+
+## Change log
+`;
+var TODO_STARTER_MILESTONE = `---
+id: HS-START-0002
+name: Your first milestone
+summary: TODO \u2014 one-line summary of this milestone.
+type: milestone
+status: open
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+epics:
+  - '[[HS-START-0000-EPIC-your-first-epic]]'
+target_date: ''
+tags:
+  - milestone
+---
+
+# Your first milestone
+
+<!-- TODO: replace this with a real first milestone for your vault. It exists so the starter
+     epic has a home \u2014 see specs/protocols/canonical-frontmatter-templates.md for the full
+     milestone template. -->
+
+## Intended outcome
+
+**Outcome at the milestone altitude (required):** TODO \u2014 what outcome does this milestone
+deliver?
+
+## Why this is a milestone, not loose epics
+
+TODO.
+
+## Suggested landing order
+
+- [[HS-START-0000-EPIC-your-first-epic]]
+
+## Out of scope
+
+TODO.
+`;
+var TODO_STARTER_ROADMAP = `---
+id: HS-START-ROADMAP
+name: Your roadmap
+type: roadmap
+status: open
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+roadmap_manifest:
+  version: 1
+  milestones:
+    - HS-START-0002-MIL-your-first-milestone
+tags:
+  - roadmap
+---
+
+# Your roadmap
+
+<!-- TODO: this is a skeleton roadmap, not content. \`roadmap_manifest.milestones\` is what makes
+     a milestone reachable from the roadmap (specs/entity-model.md \xA7roadmap) \u2014 list every
+     milestone you file here, in the order you intend to land them. -->
+
+## Now
+
+- [[HS-START-0000-EPIC-your-first-epic]] \u2014 TODO: one-line status.
+
+## Next
+
+TODO.
+
+## Later
+
+TODO.
+`;
+function principleSkeleton(args) {
+  return `---
+id: HS-DEC-${args.id}
+name: "${args.name}"
+type: memory-decision
+status: open
+priority: 0
+owner: TODO \u2014 your name/handle
+created: TODO \u2014 YYYY-MM-DD
+updated: TODO \u2014 YYYY-MM-DD
+topic: ${args.topic}
+decided: TODO \u2014 YYYY-MM-DD
+deciders:
+  - TODO \u2014 your name/handle
+tags:
+  - decision
+  - principle
+  - architecture
+---
+
+# ${args.name}
+
+<!-- TODO: this is one of HeySpex's own architecture commitments, generalized as a starting
+     point. Confirm it fits your product as-is, edit it, or delete this file and drop it from
+     specs/principles-index.md. -->
+
+## Decision
+
+${args.decision}
+
+## Rationale
+
+${args.rationalePrompt}
+`;
+}
+var TEMPLATE_MANIFEST = [
+  // --- Universal rows: copied byte-identical — but from the CURATED copy
+  // (`${CURATED_TEMPLATE_ROOT}/${dest}`), not the raw platform doc. The raw
+  // platform doc carries ~449 wikilinks to platform-only specs that would
+  // never resolve in a customer vault (HS-I2U9); `scripts/regenerate-
+  // customer-templates.mjs` rewrites those into plain text once, ahead of
+  // time, from this SAME `UNIVERSAL_TEMPLATE_ROWS` list (one list, shared —
+  // see that module's + `template-manifest.sources.mjs`'s doc comments).
+  ...UNIVERSAL_TEMPLATE_ROWS.map(
+    (row) => ({
+      source: `${CURATED_TEMPLATE_ROOT}/${row.dest}`,
+      classification: "universal-template",
+      dest: row.dest
+    })
+  ),
+  // --- Shape rows: inline skeleton content with a TODO author prompt. ---
+  {
+    source: "specs/heyspex-north-star.md",
+    classification: "template-shape",
+    dest: "specs/north-star.md",
+    content: TODO_NORTH_STAR
+  },
+  {
+    source: "specs/principles-index.md",
+    classification: "template-shape",
+    dest: "specs/principles-index.md",
+    content: TODO_PRINCIPLES_INDEX
+  },
+  {
+    // No single platform analog — authored against the task-entity schema so
+    // there is something claimable the moment a customer vault exists.
+    source: "specs/protocols/canonical-frontmatter-templates.md",
+    classification: "template-shape",
+    dest: "specs/tasks/HS-START-0001-TASK-your-first-task.md",
+    content: TODO_STARTER_TASK
+  },
+  {
+    // No single platform analog — authored against the epic-entity schema so
+    // the starter task (above) has a `parent:` and the vault lints clean
+    // (HS-I2U9). See `TODO_STARTER_EPIC`'s doc comment for the full chain
+    // this requires (epic -> milestone -> roadmap).
+    source: "specs/protocols/canonical-frontmatter-templates.md",
+    classification: "template-shape",
+    dest: "specs/epics/HS-START-0000-EPIC-your-first-epic.md",
+    content: TODO_STARTER_EPIC
+  },
+  {
+    // No single platform analog — the starter epic's `milestone:` target.
+    source: "specs/protocols/canonical-frontmatter-templates.md",
+    classification: "template-shape",
+    dest: "specs/milestones/HS-START-0002-MIL-your-first-milestone.md",
+    content: TODO_STARTER_MILESTONE
+  },
+  {
+    // No single platform analog — schema per specs/entity-model.md §roadmap.
+    // Makes the starter milestone reachable ("not an orphan" per
+    // validateLinkage): it must appear in a roadmap_manifest.milestones list.
+    source: "specs/entity-model.md",
+    classification: "template-shape",
+    dest: "specs/roadmap.md",
+    content: TODO_STARTER_ROADMAP
+  },
+  // --- Universal principle docs (shape rows, group: "principle") ---
+  // Generalized from HeySpex's own P3/P4/P6/P7/P8 design-principle decisions
+  // (see specs/principles-index.md). Of those five, P6 (JTBD-parity) was
+  // excluded from this set of four: its decision body is inseparably about
+  // HeySpex's own bd/SuperClaude migration inventory (specific JTBD counts,
+  // named predecessor tools), not a portable architecture commitment the way
+  // the other four are. P3/P4/P7/P8 generalize cleanly.
+  {
+    source: "specs/memory/decisions/vault-as-format-primacy-validated-by-bd-retreat.md",
+    classification: "template-shape",
+    dest: "specs/memory/decisions/principle-vault-is-canonical.md",
+    group: "principle",
+    summary: "Markdown-in-git is the canonical store; nothing else drifts.",
+    content: principleSkeleton({
+      id: "principle-vault-is-canonical",
+      name: "Vault-as-Format Primacy \u2014 Markdown Files in Git Are Canonical",
+      topic: "principle-vault-is-canonical",
+      decision: "Markdown files in the git-tracked spec vault are the canonical store. Any derived index (cache, search index, dashboard) follows the vault \u2014 never the other way around.",
+      rationalePrompt: "TODO: why does this decision hold for your product? What alternative (a database, a JSON export) did you reject, and why?"
+    })
+  },
+  {
+    source: "specs/memory/decisions/composability-via-git-commit-boundary.md",
+    classification: "template-shape",
+    dest: "specs/memory/decisions/principle-git-commit-is-the-atomic-batch.md",
+    group: "principle",
+    summary: "A git commit is the atomic multi-file batch; no bespoke orchestration tier.",
+    content: principleSkeleton({
+      id: "principle-git-commit-is-the-atomic-batch",
+      name: "Composability via Git Commit Boundary \u2014 No Orchestration Tier",
+      topic: "principle-git-commit-is-the-atomic-batch",
+      decision: "A git commit is the atomic batch for multi-file operations. There is no custom orchestration verb (batch/transaction/pipeline command) layered above the git commit boundary.",
+      rationalePrompt: "TODO: why does this decision hold for your product?"
+    })
+  },
+  {
+    source: "specs/memory/decisions/orthogonal-asset-composition-p7.md",
+    classification: "template-shape",
+    dest: "specs/memory/decisions/principle-orthogonal-asset-composition.md",
+    group: "principle",
+    summary: "Independent behavior axes (command/persona/mode/workflow) compose, not bundle.",
+    content: principleSkeleton({
+      id: "principle-orthogonal-asset-composition",
+      name: "Orthogonal Asset Composition",
+      topic: "principle-orthogonal-asset-composition",
+      decision: "Independent axes of configurable behavior (e.g. command, persona, mode, workflow) compose orthogonally rather than being hard-coded together \u2014 each axis is a separate, combinable asset.",
+      rationalePrompt: "TODO: what are the independent axes in your product, and why keep them orthogonal instead of bundling them?"
+    })
+  },
+  {
+    source: "specs/memory/decisions/tool-agnostic-mcp-first-cli-second.md",
+    classification: "template-shape",
+    dest: "specs/memory/decisions/principle-tool-agnostic-by-construction.md",
+    group: "principle",
+    summary: "The product works across host tools/IDEs, not locked to one.",
+    content: principleSkeleton({
+      id: "principle-tool-agnostic-by-construction",
+      name: "Tool-Agnostic by Construction",
+      topic: "principle-tool-agnostic-by-construction",
+      decision: "The product does not depend on one specific host tool/IDE/agent. Every feature is built across compatibility layers so it works wherever at least one integration point is supported.",
+      rationalePrompt: "TODO: which compatibility layers does your product need (CLI? API? plugin? an MCP-equivalent)?"
+    })
+  }
+];
+
+// spex-console/src/lib/cli/init.customer-vault.ts
+var DEFAULT_CONSOLE_URL3 = "https://console.heyspex.local";
+var SCAFFOLD_FOLDERS = [
+  "tasks",
+  "epics",
+  "milestones",
+  "research",
+  "memory/lessons",
+  "memory/decisions",
+  "memory/references",
+  "memory/ui-patterns",
+  "protocols",
+  "reviews",
+  "captures",
+  "adr",
+  "checks",
+  "events"
+];
+function defaultVaultName(targetDir) {
+  return basename(targetDir) || targetDir;
+}
+function runCustomerVaultInit(args, deps, options = {}) {
+  const { targetDir } = args;
+  const written = [];
+  if (deps.exists(targetDir)) {
+    const entries = deps.readdir(targetDir);
+    if (entries.length > 0) {
+      return {
+        code: EXIT.INVALID_ARG,
+        message: `${targetDir} is not empty \u2014 customer-vault init refuses to write into an existing, non-empty directory.`,
+        payload: { ok: false, error: "target_not_empty", path: targetDir },
+        isError: true,
+        written: []
+      };
+    }
+  } else {
+    deps.mkdirRecursive(targetDir);
+  }
+  const specsRoot = deps.joinPath(targetDir, "specs");
+  deps.mkdirRecursive(specsRoot);
+  for (const folder of SCAFFOLD_FOLDERS) {
+    deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
+  }
+  const vaultId = mintVaultId();
+  const yamlContent = renderHeyspexYaml({
+    consoleUrl: options.consoleUrl ?? DEFAULT_CONSOLE_URL3,
+    vaultRoot: "specs/",
+    vaultId
+  });
+  const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
+  deps.writeFile(heyspexYamlPath, yamlContent);
+  written.push(heyspexYamlPath);
+  const filter = options.manifestFilter ?? (() => true);
+  const rows = TEMPLATE_MANIFEST.filter(filter);
+  for (const row of rows) {
+    const destAbs = deps.joinPath(targetDir, ...row.dest.split("/"));
+    if (row.classification === "universal-template") {
+      const srcAbs = deps.joinPath(deps.platformRoot, ...row.source.split("/"));
+      deps.copyFile(srcAbs, destAbs);
+    } else {
+      if (row.content === void 0) {
+        throw new Error(
+          `template-manifest row for dest "${row.dest}" is classified template-shape but has no inline content`
+        );
+      }
+      deps.writeFile(destAbs, row.content);
+    }
+    written.push(destAbs);
+  }
+  if (options.afterScaffold && options.afterScaffold.length > 0) {
+    const ctx = {
+      targetDir,
+      vaultName: options.vaultName ?? defaultVaultName(targetDir),
+      templateVersion: TEMPLATE_VERSION,
+      manifestRows: rows,
+      deps,
+      recordWrite: (path) => {
+        written.push(path);
+      }
+    };
+    for (const hook of options.afterScaffold) hook(ctx);
+  }
+  return {
+    code: EXIT.OK,
+    message: `Initialized customer vault at ${targetDir} (${written.length} files written, template v${TEMPLATE_VERSION}).`,
+    payload: {
+      ok: true,
+      targetDir,
+      templateVersion: TEMPLATE_VERSION,
+      vaultId,
+      written
+    },
+    isError: false,
+    written
+  };
+}
+
+// spex-console/src/lib/cli/init-git-finalize.ts
+import { spawnSync } from "node:child_process";
+import { readFileSync as readFileSync3 } from "node:fs";
+var nodeGitRunner = {
+  run(args, cwd) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return {
+      ok: result.error === void 0 && result.status === 0,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? ""
+    };
+  }
+};
+function readTemplateVersion(yamlText) {
+  const m = yamlText.match(/^template_version:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
+}
+function ensureTemplateVersionLine(content, version) {
+  if (readTemplateVersion(content) !== null) {
+    return content.replace(/^template_version:.*$/m, `template_version: ${version}`);
+  }
+  const trimmed = content.replace(/\n+$/, "");
+  return `${trimmed}
+template_version: ${version}
+`;
+}
+function gitFinalizeHook(runner, notify) {
+  return (ctx) => {
+    const target = ctx.targetDir;
+    const yamlPath = ctx.deps.joinPath(target, "heyspex.yaml");
+    const existingYaml = readFileSync3(yamlPath, "utf8");
+    const updatedYaml = ensureTemplateVersionLine(existingYaml, ctx.templateVersion);
+    ctx.deps.writeFile(yamlPath, updatedYaml);
+    ctx.recordWrite(yamlPath);
+    const probe = runner.run(["--version"], target);
+    if (!probe.ok) {
+      notify("git not found - vault left uninitialized, run git init yourself");
+      return;
+    }
+    runner.run(["-C", target, "init"], target);
+    runner.run(["-C", target, "add", "-A"], target);
+    const commitMessage = `hs init --customer-vault - initial scaffold from HeySpex templates v${ctx.templateVersion}`;
+    runner.run(
+      [
+        "-C",
+        target,
+        "-c",
+        "user.name=HeySpex",
+        "-c",
+        "user.email=init@heyspex.local",
+        "commit",
+        "-m",
+        commitMessage
+      ],
+      target
+    );
+  };
+}
+
+// spex-console/src/lib/cli/principle-selection.ts
+import { basename as basename2 } from "node:path";
+var PRINCIPLES_INDEX_DEST = "specs/principles-index.md";
+function principleKey(row) {
+  const base = basename2(row.dest, ".md");
+  return base.startsWith("principle-") ? base.slice("principle-".length) : base;
+}
+function principleWikilink(row) {
+  return basename2(row.dest, ".md");
+}
+function parsePrinciplesFlag(value, rows) {
+  const principleRows = rows.filter((row) => row.group === "principle");
+  const validKeys = principleRows.map(principleKey);
+  const trimmed = value?.trim();
+  if (trimmed === void 0 || trimmed === "" || trimmed === "all") {
+    return { ok: true, selected: new Set(validKeys) };
+  }
+  if (trimmed === "none") {
+    return { ok: true, selected: /* @__PURE__ */ new Set() };
+  }
+  const requested = trimmed.split(",").map((key) => key.trim()).filter((key) => key.length > 0);
+  const unknown = requested.filter((key) => !validKeys.includes(key));
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      message: `Unknown principle key(s): ${unknown.join(", ")}. Valid keys are: ${validKeys.join(", ")} (or "all" / "none").`
+    };
+  }
+  return { ok: true, selected: new Set(requested) };
+}
+function listPrincipleChoices(rows) {
+  return rows.filter((row) => row.group === "principle").map((row) => ({ key: principleKey(row), summary: row.summary ?? "", dest: row.dest }));
+}
+async function promptPrincipleSelection(ask, rows) {
+  const selected = /* @__PURE__ */ new Set();
+  for (const choice of listPrincipleChoices(rows)) {
+    const keep = await ask(`Keep principle "${choice.key}" \u2014 ${choice.summary}? (y/n)`);
+    if (keep) {
+      selected.add(choice.key);
+    }
+  }
+  return selected;
+}
+function principleManifestFilter(selected) {
+  return (row) => {
+    if (row.group !== "principle") {
+      return true;
+    }
+    return selected.has(principleKey(row));
+  };
+}
+function principlesIndexHook(selected, rows) {
+  return (ctx) => {
+    const indexRow = rows.find((row) => row.dest === PRINCIPLES_INDEX_DEST);
+    if (!indexRow || indexRow.content === void 0) {
+      throw new Error(
+        `principlesIndexHook: no template-manifest row with inline content found for dest "${PRINCIPLES_INDEX_DEST}"`
+      );
+    }
+    const principleRows = rows.filter((row) => row.group === "principle");
+    const kept = principleRows.filter((row) => selected.has(principleKey(row)));
+    const keptSection = kept.length === 0 ? "" : "\n## Universal principles kept\n\n" + kept.map((row) => `- [[${principleWikilink(row)}]] \u2014 ${row.summary ?? ""}`).join("\n") + "\n";
+    const rendered = indexRow.content + keptSection;
+    const destAbs = ctx.deps.joinPath(ctx.targetDir, ...PRINCIPLES_INDEX_DEST.split("/"));
+    ctx.deps.writeFile(destAbs, rendered);
+    ctx.recordWrite(destAbs);
+  };
+}
+
+// spex-console/bin/hs-init.ts
+var INTERACTIVE = process2.stdin.isTTY === true;
+async function askYesNo(question) {
+  const rl = createInterface({ input: process2.stdin, output: process2.stdout });
+  try {
+    const answer = (await rl.question(`${question} `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes" || answer === "";
+  } finally {
+    rl.close();
+  }
+}
+async function resolvePrincipleSelection(principlesFlag) {
+  if (principlesFlag !== void 0) {
+    return parsePrinciplesFlag(principlesFlag, TEMPLATE_MANIFEST);
+  }
+  if (INTERACTIVE) {
+    process2.stdout.write("Select which universal principle docs to ship with this vault:\n");
+    for (const choice of listPrincipleChoices(TEMPLATE_MANIFEST)) {
+      process2.stdout.write(`  - ${choice.key}: ${choice.summary}
+`);
+    }
+    const selected = await promptPrincipleSelection(askYesNo, TEMPLATE_MANIFEST);
+    return { ok: true, selected };
+  }
+  return parsePrinciplesFlag(void 0, TEMPLATE_MANIFEST);
+}
+async function main() {
+  const repoRoot = process2.env.HS_VAULT_ROOT ? resolve(process2.env.HS_VAULT_ROOT) : process2.cwd();
+  const parsed = parseInitArgs(process2.argv.slice(3));
+  if (parsed.help) {
+    process2.stdout.write(`${HELP}
+`);
+    process2.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs init: ${parsed.error.message}
+`);
+    process2.exit(parsed.error.code);
+  }
+  const args = parsed.args;
+  if (args.customerVaultDir) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const platformRoot = resolve(here, "..", "..");
+    const targetDir = resolve(args.customerVaultDir);
+    const deps = {
+      platformRoot,
+      exists: (p) => existsSync(p),
+      readdir: (p) => readdirSync(p),
+      mkdirRecursive: (p) => {
+        mkdirSync(p, { recursive: true });
+      },
+      writeFile: (p, c) => writeFileSync(p, c, "utf8"),
+      copyFile: (src, dest) => copyFileSync(src, dest),
+      joinPath: (...s) => join3(...s)
+    };
+    const principlesResult = await resolvePrincipleSelection(args.principles);
+    if (!principlesResult.ok) {
+      process2.stderr.write(`hs init: ${principlesResult.message}
+`);
+      process2.exit(EXIT.INVALID_ARG);
+    }
+    const selected = principlesResult.selected;
+    const notices = [];
+    const afterScaffold = [
+      customerClaudeMdHook(),
+      principlesIndexHook(selected, TEMPLATE_MANIFEST)
+    ];
+    if (!args.noGit) {
+      afterScaffold.push(gitFinalizeHook(nodeGitRunner, (msg) => notices.push(msg)));
+    }
+    const result2 = runCustomerVaultInit({ targetDir }, deps, {
+      consoleUrl: args.consoleUrl,
+      vaultName: args.vaultName,
+      manifestFilter: principleManifestFilter(selected),
+      afterScaffold
+    });
+    const sink2 = result2.isError ? process2.stderr : process2.stdout;
+    if (args.json) {
+      sink2.write(`${JSON.stringify({ ...result2.payload, notices })}
+`);
+    } else {
+      sink2.write(`${result2.message}
+`);
+      for (const notice of notices) sink2.write(`${notice}
+`);
+    }
+    process2.exit(result2.code);
+  }
+  const result = runInit(args, {
+    repoRoot,
+    fileExists: (p) => existsSync(p),
+    readFile: (p) => {
+      try {
+        return readFileSync4(p, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    writeFile: (p, c) => writeFileSync(p, c, "utf8"),
+    joinPath: (...s) => join3(...s)
+  });
+  const sink = result.isError ? process2.stderr : process2.stdout;
+  sink.write(`${args.json ? JSON.stringify(result.payload) : result.message}
+`);
+  process2.exit(result.code);
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process2.stderr.write(`hs init: unhandled: ${message}
+`);
+  process2.exit(EXIT.WRITE_FAILED);
+});