heyspex 0.1.0 → 0.2.1

package/scripts/lib/template-pin.mjs

@@ -0,0 +1,34 @@
+/**
+ * template-pin.mjs — the ONE home of the customer-vault template version and
+ * the list of docs a healthy customer vault must always contain (HS-KH0Q).
+ *
+ * Zero dependencies (node builtins only) so BOTH consumers can import it:
+ *   - `spex-console/src/lib/cli/template-manifest.ts` re-exports it, and
+ *   - the zero-dependency standalone doctor (`scripts/lib/standalone-doctor.mjs`,
+ *     the `vault-template` row) reads it without pulling in the console.
+ *
+ * Bump `TEMPLATE_VERSION` whenever the shipped manifest content changes in a
+ * way a customer vault should be able to detect (new universal doc, changed
+ * skeleton, etc.). `TEMPLATE_CORE_DESTS` is guarded against drift from the
+ * real manifest by `spex-console/src/lib/cli/template-manifest.test.ts`.
+ */
+
+/** Bumped whenever the shipped manifest content changes. */
+export const TEMPLATE_VERSION = "1.1.0";
+
+/**
+ * Vault-relative (POSIX) paths every scaffolded customer vault must hold:
+ * the foundational docs plus every universal protocol.
+ */
+export const TEMPLATE_CORE_DESTS = Object.freeze([
+  "specs/north-star.md",
+  "specs/principles-index.md",
+  "specs/roadmap.md",
+  "specs/entity-model.md",
+  "specs/protocols/canonical-frontmatter-templates.md",
+  "specs/protocols/spec-hierarchy.md",
+  "specs/protocols/memory-protocol.md",
+  "specs/protocols/session-close-protocol.md",
+  "specs/protocols/spec-summary-authoring.md",
+  "specs/protocols/destructive-action-checklist.md",
+]);

package/scripts/lib/window-placement.mjs

@@ -0,0 +1,109 @@
+/**
+ * Window placement for the two-pane capture layout
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]).
+ *
+ * The owner wants the `hs view` window (pipeline + capture doc) and the
+ * PowerShell SpexCode agent window both visible at once. Neither launcher used
+ * to place its window, so they stacked wherever the OS put them. This module is
+ * the ONE place that decides the geometry; both launchers call it:
+ *
+ *   - `scripts/hs-view.mjs`        -> side "right" (this window)
+ *   - the agent launch (HS-TXFW)   -> `complementarySide("right")` = "left"
+ *
+ * Pure geometry (`computeWindowPlacement`) is separated from the one
+ * side-effecting probe (`getPrimaryWorkArea`) so the maths is unit-testable.
+ *
+ * Safety: placement is always BEST EFFORT. Any failure (non-Windows, probe
+ * timeout, nonsense numbers) yields `null` and the caller simply omits the
+ * position flags, i.e. today's behavior. Multi-monitor: only the primary
+ * monitor's work area is used by default (taskbar excluded), so a window can
+ * never be pushed onto a monitor that was unplugged or a negative coordinate
+ * the OS would clamp unpredictably.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Sides a window can take. `none` disables placement entirely. */
+export const PLACE_SIDES = new Set(['left', 'right', 'none']);
+
+/** The other half of the screen - what the sibling window should take. */
+export function complementarySide(side) {
+  if (side === 'left') return 'right';
+  if (side === 'right') return 'left';
+  return 'none';
+}
+
+/** Parse `left|right|none` (case-insensitive); anything else -> null. */
+export function parsePlaceSide(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  return PLACE_SIDES.has(v) ? v : null;
+}
+
+function validWorkArea(w) {
+  return (
+    w &&
+    [w.x, w.y, w.width, w.height].every((n) => Number.isFinite(n)) &&
+    w.width >= 400 &&
+    w.height >= 300
+  );
+}
+
+/**
+ * Geometry for one window on one half of a work area.
+ *
+ * Width is the requested width capped at half the work area, so the two
+ * windows can never overlap; height fills the work area. Returns
+ * `{ x, y, width, height }` or null when placement should be skipped.
+ */
+export function computeWindowPlacement({ workArea, side, width, height }) {
+  if (side !== 'left' && side !== 'right') return null;
+  if (!validWorkArea(workArea)) return null;
+  const half = Math.floor(workArea.width / 2);
+  const w = Math.max(1, Math.min(Number.isFinite(width) && width > 0 ? width : half, half));
+  const h = Math.max(
+    1,
+    Math.min(Number.isFinite(height) && height > 0 ? height : workArea.height, workArea.height),
+  );
+  // Full-height halves unless the caller asked for something shorter.
+  const x = side === 'left' ? workArea.x : workArea.x + workArea.width - w;
+  return { x, y: workArea.y, width: w, height: h };
+}
+
+/** The Chromium app-mode flags for a placement. */
+export function placementFlags(p) {
+  return p ? [`--window-position=${p.x},${p.y}`, `--window-size=${p.width},${p.height}`] : [];
+}
+
+/**
+ * Primary monitor work area (taskbar excluded) in the units Chromium's
+ * `--window-position` uses. Windows only; null elsewhere or on any failure.
+ * Override for tests / unusual setups with `HEYSPEX_VIEW_WORKAREA=x,y,w,h`.
+ */
+export function getPrimaryWorkArea(env = process.env, platform = process.platform) {
+  const override = String(env.HEYSPEX_VIEW_WORKAREA ?? '').trim();
+  if (override) {
+    const [x, y, width, height] = override.split(',').map((s) => Number(s.trim()));
+    const w = { x, y, width, height };
+    return validWorkArea(w) ? w : null;
+  }
+  if (platform !== 'win32') return null;
+  try {
+    const r = spawnSync(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Add-Type -AssemblyName System.Windows.Forms; ' +
+          '$a=[System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea; ' +
+          '"$($a.X),$($a.Y),$($a.Width),$($a.Height)"',
+      ],
+      { encoding: 'utf8', timeout: 4000, windowsHide: true },
+    );
+    if (r.status !== 0) return null;
+    const [x, y, width, height] = String(r.stdout).trim().split(',').map(Number);
+    const w = { x, y, width, height };
+    return validWorkArea(w) ? w : null;
+  } catch {
+    return null;
+  }
+}

package/scripts/provenance-lib.mjs

@@ -0,0 +1,91 @@
+/**
+ * Shared authorship-provenance targeting predicate
+ * ([[HS-EPIC-IKIM-authorship-provenance-frontmatter-owner]]).
+ *
+ * SSOT for "which specs carry the universal `owner` requirement" — imported by
+ * both the gate (`validate-vault-provenance.mjs`) and the one-time backfill
+ * (`backfill-vault-provenance.mjs`) so they cannot drift. If they drifted, the
+ * post-backfill `block` gate could fire on a file the backfill never touched.
+ *
+ * `owner` is universally required ([[entity-model]] §Authorship provenance). The
+ * `contributors` / `assisted_by` lists are intentionally OPTIONAL (auto-stamped,
+ * omit-when-empty), so they are NOT part of this predicate. Frozen statuses
+ * (closed/superseded/cancelled/duplicate) are skipped — their frontmatter is
+ * immutable historical record.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SPECS_DIR = path.join(REPO_ROOT, "specs");
+
+// Reuse spex-console's installed js-yaml (transitive via gray-matter) — same pattern
+// as validate-vault-frontmatter.mjs; no deps of our own.
+const spexConsoleRequire = createRequire(path.join(REPO_ROOT, "spex-console", "package.json"));
+export const yaml = spexConsoleRequire("js-yaml");
+
+/** Statuses whose frontmatter is frozen historical record — never flagged. */
+export const FROZEN_STATUSES = new Set(["closed", "superseded", "cancelled", "duplicate"]);
+
+/** Recursively collect every *.md under specs/ (relative to repo root, posix sep). */
+export function allSpecFiles() {
+  /** @type {string[]} */
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        out.push(path.relative(REPO_ROOT, abs).split(path.sep).join("/"));
+      }
+    }
+  };
+  if (fs.existsSync(SPECS_DIR)) walk(SPECS_DIR);
+  return out;
+}
+
+/** Extract the raw frontmatter block (between the leading `---` fences). */
+export function extractFrontmatter(raw) {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  return m[1];
+}
+
+/**
+ * Parse a spec's frontmatter to an object.
+ * @returns {object|null} null when there is no frontmatter, the YAML is
+ *   malformed, or it is not a mapping — all of which this gate skips (malformed
+ *   YAML is the frontmatter gate's job, not ours).
+ */
+export function parseFrontmatter(raw) {
+  const fm = extractFrontmatter(raw);
+  if (fm === null) return null;
+  let data;
+  try {
+    data = yaml.load(fm);
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object") return null;
+  return data;
+}
+
+/**
+ * True when this spec carries the universal `owner` requirement: a typed entity
+ * spec whose status is not frozen. Prose-only docs and frozen records are out of
+ * scope for both the gate and the backfill.
+ */
+export function isTypedNonFrozen(data) {
+  if (!data || typeof data !== "object") return false;
+  if (typeof data.type !== "string" || !data.type.trim()) return false;
+  const status = typeof data.status === "string" ? data.status.trim().toLowerCase() : "";
+  if (FROZEN_STATUSES.has(status)) return false;
+  return true;
+}
+
+/** The trimmed `owner` scalar, or "" when absent/blank. */
+export function ownerOf(data) {
+  return typeof data.owner === "string" ? data.owner.trim() : "";
+}

package/scripts/stamp-provenance-on-edit.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * Write-time `assisted_by` stamp for direct Edit/Write/MultiEdit tool writes
+ * ([[HS-EPIC-IKIM-authorship-provenance-frontmatter-owner]] Phase 3).
+ *
+ * Wired as a Claude Code **PostToolUse** hook (`.claude/settings.json`). The
+ * `updateSpec` edit-path stamp only fires for console-UI / MCP PUT writes; an
+ * agent that edits a spec file directly via the Edit tool bypasses it. The
+ * literal "git pre-commit stamp" can't fix this — the human reviewer runs the
+ * commit and the agent has released its claim by then, so neither the committer
+ * nor the claim trail names the editing agent. The only place the agent identity
+ * is reliably present is *at edit time*, in the agent's own process env — which
+ * is exactly when a PostToolUse hook runs.
+ *
+ * SAFETY (this runs on every spec edit): it only ever APPENDS one `assisted_by`
+ * entry, append-only + de-duped, and NO-OPS (touches nothing) on any frontmatter
+ * shape it isn't fully confident about. It always exits 0 — a stamp failure must
+ * never disrupt the agent's edit. Reads the PostToolUse payload as JSON on stdin.
+ *
+ * Targeting (typed + non-frozen) and frontmatter parsing are shared with the gate
+ * via `provenance-lib.mjs`, so this stamps exactly the specs the gate governs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { REPO_ROOT, parseFrontmatter, isTypedNonFrozen } from "./provenance-lib.mjs";
+import { getActiveConfig } from "../vendor/heyspex-mcp/vault-resolve.mjs";
+
+/** Exit without touching anything — the safe default for every uncertain case. */
+function bail() {
+  process.exit(0);
+}
+
+/** The acting agent's display name, or null when it can't be identified. */
+function detectAgent() {
+  const claude = (
+    process.env.CLAUDE_CODE_SESSION_ID ||
+    process.env.CLAUDE_SESSION_ID ||
+    process.env.CLAUDECODE ||
+    ""
+  ).trim();
+  if (claude) return "Claude Code";
+  const cursor = (
+    process.env.CURSOR_TRACE_ID ||
+    process.env.CURSOR_SESSION_ID ||
+    process.env.COMPOSER_SESSION_ID ||
+    ""
+  ).trim();
+  if (cursor) return "Cursor";
+  const explicit = process.env.HEYSPEX_AGENT?.trim();
+  if (explicit) return explicit;
+  return null; // unknown agent — don't stamp a placeholder
+}
+
+/** Read all of stdin (the PostToolUse JSON payload). */
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Append `agent` to the frontmatter's `assisted_by` list via surgical text edit
+ * (no YAML reflow). Returns the patched text, or null to signal "no safe edit"
+ * (caller no-ops). `current` is the parsed value of `assisted_by` (for dedup).
+ */
+function appendAssistedBy(raw, agent, current) {
+  // Unexpected shape (present but not a list) → never touch it.
+  if (current !== undefined && !Array.isArray(current)) return null;
+  // Already present → idempotent no-op. An entry counts as "this agent" whether
+  // it is bare ("Claude Code") or model-qualified ("Claude Code:Fable 5") — the
+  // `AGENT:MODEL` form ([[entity-model]] §Authorship provenance). Without the
+  // prefix check, stamping a bare "Claude Code" onto a spec already crediting
+  // "Claude Code:Fable 5" would append a redundant, less-informative duplicate.
+  if (
+    Array.isArray(current) &&
+    current.some((v) => {
+      if (typeof v !== "string") return false;
+      const t = v.trim();
+      return t === agent || t.startsWith(`${agent}:`);
+    })
+  ) {
+    return null;
+  }
+
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const lines = raw.split(/\r?\n/);
+
+  // Frontmatter fences (the first must be line 0; parseFrontmatter guaranteed it).
+  let f1 = -1;
+  let f2 = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      if (f1 < 0) f1 = i;
+      else {
+        f2 = i;
+        break;
+      }
+    }
+  }
+  if (f1 !== 0 || f2 < 0) return null;
+
+  // Locate a top-level `assisted_by:` line within the block.
+  let abIdx = -1;
+  for (let i = f1 + 1; i < f2; i++) {
+    if (/^assisted_by\s*:/.test(lines[i])) {
+      abIdx = i;
+      break;
+    }
+  }
+
+  if (abIdx < 0) {
+    // No assisted_by yet — insert a block list after owner: / status: / type:.
+    let anchor = -1;
+    for (const key of ["owner", "status", "type"]) {
+      for (let i = f1 + 1; i < f2; i++) {
+        if (new RegExp(`^${key}\\s*:`).test(lines[i])) {
+          anchor = i;
+          break;
+        }
+      }
+      if (anchor >= 0) break;
+    }
+    if (anchor < 0) return null;
+    lines.splice(anchor + 1, 0, "assisted_by:", `  - ${agent}`);
+    return lines.join(eol);
+  }
+
+  const abLine = lines[abIdx];
+  const inlineMatch = abLine.match(/^(assisted_by\s*:\s*)\[(.*)\]\s*$/);
+  if (inlineMatch) {
+    // Inline form: assisted_by: [A, B]  or  assisted_by: []
+    const inner = inlineMatch[2].trim();
+    const next = inner.length === 0 ? agent : `${inner}, ${agent}`;
+    lines[abIdx] = `${inlineMatch[1]}[${next}]`;
+    return lines.join(eol);
+  }
+
+  if (/^assisted_by\s*:\s*$/.test(abLine)) {
+    // Block form: find the last contiguous `- ` item under it and insert after.
+    let lastItem = abIdx;
+    let itemIndent = "  ";
+    for (let i = abIdx + 1; i < f2; i++) {
+      const m = lines[i].match(/^(\s+)-\s+/);
+      if (m) {
+        lastItem = i;
+        itemIndent = m[1];
+      } else if (lines[i].trim() === "") {
+        continue; // tolerate blank lines inside the block
+      } else {
+        break; // next key — list ended
+      }
+    }
+    if (lastItem === abIdx) {
+      // `assisted_by:` with no items yet — add the first.
+      lines.splice(abIdx + 1, 0, `  - ${agent}`);
+    } else {
+      lines.splice(lastItem + 1, 0, `${itemIndent}- ${agent}`);
+    }
+    return lines.join(eol);
+  }
+
+  // `assisted_by:` in some other shape (e.g. a scalar) → don't touch.
+  return null;
+}
+
+function main() {
+  const payload = readStdin();
+  let filePath = "";
+  try {
+    const obj = JSON.parse(payload);
+    filePath = obj?.tool_input?.file_path || obj?.tool_input?.filePath || "";
+  } catch {
+    return bail();
+  }
+  if (typeof filePath !== "string" || !filePath.trim()) return bail();
+
+  const abs = path.resolve(filePath);
+  // Must be a markdown spec under a specs/ dir — the code repo's (legacy) or
+  // the registry-resolved vault's (the live one since the 2026-08-31 repo split).
+  if (!abs.endsWith(".md")) return bail();
+  const bases = [REPO_ROOT];
+  try {
+    const vault = getActiveConfig()?.repoRootAbs;
+    if (vault && vault !== REPO_ROOT) bases.push(vault);
+  } catch {
+    // registry unreadable — the code-repo base still applies
+  }
+  const underSpecs = bases.some((b) => abs.startsWith(path.join(b, "specs") + path.sep));
+  if (!underSpecs) return bail();
+
+  let raw;
+  try {
+    raw = fs.readFileSync(abs, "utf8");
+  } catch {
+    return bail();
+  }
+
+  const data = parseFrontmatter(raw);
+  if (data === null) return bail(); // no/ malformed frontmatter — not our concern
+  if (!isTypedNonFrozen(data)) return bail(); // prose-only or frozen historical record
+
+  const agent = detectAgent();
+  if (!agent) return bail();
+
+  const patched = appendAssistedBy(raw, agent, data.assisted_by);
+  if (patched === null || patched === raw) return bail();
+
+  try {
+    fs.writeFileSync(abs, patched);
+  } catch {
+    // Swallow — a stamp must never disrupt the edit.
+  }
+  process.exit(0);
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}