heyspex 0.2.0 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "heyspex-marketplace",
+  "owner": {
+    "name": "pwher",
+    "email": "paul@monstergrowth.com"
+  },
+  "plugins": [
+    {
+      "name": "heyspex",
+      "source": "./plugins/heyspex",
+      "description": "SpexCode plugin (for Claude Code and GitHub Copilot CLI): HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+    }
+  ]
+}

package/bin/hs.mjs

@@ -25,7 +25,9 @@ import {
   vaultConfigCheckRow,
 } from "../scripts/lib/standalone-doctor.mjs";
 import {
+  findBrokenSatellitePin,
   isVaultRoot,
+  readMarkerSatellite,
   readSatellitePin,
   resolveActiveVault,
 } from "../vendor/heyspex-mcp/vault-resolve.mjs";
@@ -58,6 +60,7 @@ const PKG_ROOT = path.resolve(__dirname, "..");
 export const SPAWN_TARGETS = {
   "setup:claude": { path: "scripts/install-claude-code-hooks.mjs" },
   "setup:cursor": { path: "scripts/install-cursor-hooks.mjs" },
+  "setup:copilot": { path: "scripts/install-copilot-hooks.mjs" },
   "skills:sync": {
     path: "scripts/sync-skills.mjs",
     devOnly: true,
@@ -85,6 +88,7 @@ export const SPAWN_TARGETS = {
   "source:preflight": { path: "scripts/lib/hs-source-preflight.mjs" },
   "source:commit": { path: "scripts/lib/hs-source-commit.mjs" },
   "source:push": { path: "scripts/lib/hs-source-push.mjs" },
+  "source:branch": { path: "scripts/lib/hs-source-branch.mjs" },
   "source:log": { path: "scripts/lib/hs-source-log.mjs" },
   // `hs source identity` — the ONE sanctioned git-identity writer (human-only
   // set/clear, read-only show). Incident 2026-09-19, vault lesson
@@ -175,6 +179,8 @@ export const BUILTIN_VERBS = [
   "doctor",
   "index",
   "pull",
+  "push",
+  "import",
   "milestone",
   "factory",
   "code-watcher",
@@ -286,6 +292,13 @@ export function findVaultRoot(start, stopAt) {
     if (pinned) {
       return pinned;
     }
+    // A committed, portable satellite marker (heyspex.yaml with a relative
+    // `vault_path`): the attached vault's clone when it is on this machine,
+    // else this repo itself (cloud-only; the marker's vault_id binds it).
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return marked.vaultRootAbs ?? dir;
+    }
     if (isVaultRoot(dir)) {
       return dir;
     }
@@ -331,6 +344,72 @@ export function findRegistryVaultRoot(options = {}) {
   return resolved.repoRootAbs;
 }
 
+/** Env hatch: follow the account-wide active-vault pointer on purpose (same name the MCP transport uses). */
+export function pointerVaultAllowed(env = process.env) {
+  const v = String(env.HEYSPEX_ALLOW_POINTER_VAULT ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * Verbs that may legitimately run with only the machine's last-active vault
+ * (or none): they onboard, sign in, or manage the registry itself. EVERY other
+ * verb acts on a vault, and P1 (owner, 2026-10-16) says that vault is the one
+ * bound to the repo the agent runs in -- never the account-wide pointer.
+ */
+const POINTER_FALLBACK_NAMESPACES = new Set([
+  "init", "install", "join", "setup", "skills", "vault", "workspace",
+  "login", "whoami", "logout", "doctor", "registry", "companion", "trust",
+]);
+
+/** True when `hs <namespace> <command>` may run on the pointer-only fallback. */
+export function pointerFallbackAllowedFor(namespace, command) {
+  if (namespace === "mcp") return command === "pair" || command === "login" || command === "install";
+  return POINTER_FALLBACK_NAMESPACES.has(namespace);
+}
+
+/** The refusal printed when a satellite's pin / marker cannot be honoured. */
+export function brokenPinRefusalLine(broken) {
+  return (
+    `hs: this repo's vault pin cannot be honoured, so nothing was run. ${broken.dir}/${broken.source} ` +
+    `names \`${broken.raw}\`, but ${broken.reason}. ` +
+    "Fix the pin (a relative path such as ../<vault-repo> or ${CLAUDE_PROJECT_DIR:-.}/../<vault-repo> is portable), " +
+    "or commit a heyspex.yaml with vault_id and vault_path; hs will NOT fall back to the account-wide active vault.\n"
+  );
+}
+
+/** Nearest directory at/above `start` whose heyspex.yaml is a satellite marker (has vault_path), else null. */
+export function markerSatelliteDirFrom(start) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 256; i += 1) {
+    if (readMarkerSatellite(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/** The refusal for disk-writing verbs in a satellite whose vault clone is missing. */
+export function unclonedVaultRefusalLine(repo) {
+  const m = readMarkerSatellite(repo);
+  return (
+    `hs: ${repo} is bound to vault ${m?.vaultId ?? "(no vault_id)"} by its heyspex.yaml, but the vault ` +
+    `is not cloned at ${m?.vaultPath ?? "its vault_path"} on this machine, so this verb has no local vault to act on. ` +
+    "Clone the vault repo to that relative path (agents and cloud-routed MCP writes work without it).\n"
+  );
+}
+
+/** The refusal printed when only the account-wide pointer answered and the verb acts on a vault. */
+export function pointerOnlyRefusalLine(cwd, vaultRoot) {
+  return (
+    `hs: ${cwd} is not bound to a HeySpex vault (no heyspex.yaml, no specs/, no vault pin in .mcp.json), ` +
+    `so \`hs\` refused to follow the account-wide active vault${vaultRoot ? ` (${vaultRoot})` : ""}. ` +
+    "Bind this repo: run `hs connect` in a vault repo, `hs install --attach-vault <id> --target <repo>` for a code repo, " +
+    "or commit a heyspex.yaml with vault_id and a relative vault_path. " +
+    "To follow the pointer on purpose set HEYSPEX_ALLOW_POINTER_VAULT=1.\n"
+  );
+}
+
 /**
  * The vault-resolution ladder `main()` runs at the top of every invocation,
  * factored out so it is unit-testable without spawning a child process
@@ -358,6 +437,12 @@ export function resolveVaultRootForMain(cwd, env, stopAt) {
   if (env.HS_VAULT_ROOT) {
     return { vaultRoot: env.HS_VAULT_ROOT, usedRegistryFallback: false };
   }
+  // A pin that cannot be honoured is a REFUSAL, never a reason to fall
+  // through to the account-wide pointer (owner principle P1, 2026-10-16).
+  const brokenPin = findBrokenSatellitePin(cwd, stopAt);
+  if (brokenPin) {
+    return { vaultRoot: null, usedRegistryFallback: false, brokenPin };
+  }
   const walkedRoot = findVaultRoot(cwd, stopAt);
   if (walkedRoot) {
     return { vaultRoot: walkedRoot, usedRegistryFallback: false };
@@ -481,15 +566,17 @@ function usage() {
       "  hs gateway validate [slug] [--json]        Validate user-authored gateway skills (.heyspex/skills/user/)",
       "  hs mode on|off|status|toggle               Master switch: HeySpex layer on or off (restart Claude Code)",
       "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
-      "  hs setup claude|cursor [--check|--uninstall]  Install agent lifecycle hooks",
+      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (copilot also: --print, --hooks)",
       "  hs skills sync|check                       Propagate skills to Cursor/Codex/Claude (cwd-safe)",
       "  hs skills add <module-path> --name <n> --trigger </slash> [--export <n>] [--description <t>]  Register a skill (extension seam)",
       "  hs skills remove <name>                    Remove a customer-registered skill",
       "  hs skills list [--json]                    List registered skills (built-ins first, locked)",
       "  hs index rebuild [--verbose] [--dry-run]   Full idempotent rebuild of the index",
       "  hs index reconcile [--apply] [--cap-docs keep-out|index]  Per-spec newest-wins between disk and cloud (reports unless --apply)",
-      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply)",
-      "  hs source status|preflight|commit|push     Local git: tree status, path-scoped checks, commit, safe push",
+      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply; --watch --push adds the disk -> cloud leg)",
+      "  hs push [--apply] [--only <id>] [--force]  Send local spec edits up to the cloud vault (reports unless --apply)",
+      "  hs import <source-dir> [--folders a,b] [--plan f] [--dry-run] [--limit N]  Import a doc tree as GROUNDED spec-import captures (never raw, never research)",
+      "  hs source status|preflight|commit|push|branch  Local git: tree status, path-scoped checks, commit, safe push, session branch",
       "  hs source identity [show|set|clear]        Git author identity: show (read-only) / set, clear (HUMAN-ONLY)",
       "  hs milestone show <id> [--json]            Show a milestone (flags needs-breakdown when epicless)",
       "  hs factory status|fleet|results [--json]   Dev-Factory read-only status (fleet, routing, calibrations, results)",
@@ -858,10 +945,27 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
-  const { vaultRoot, usedRegistryFallback } = resolveVaultRootForMain(
-    process.cwd(),
-    process.env,
-  );
+  const resolvedMain = resolveVaultRootForMain(process.cwd(), process.env);
+  const { usedRegistryFallback, brokenPin } = resolvedMain;
+  // P1: the pointer is not a binding. A verb that acts on a vault runs with
+  // NO vault (and is refused at the gate) rather than on whatever vault the
+  // console last selected; onboarding/registry verbs keep the old fallback.
+  const pointerOnly =
+    usedRegistryFallback &&
+    !pointerVaultAllowed(process.env) &&
+    !pointerFallbackAllowedFor(namespace, command);
+  const vaultRoot = pointerOnly ? null : resolvedMain.vaultRoot;
+  if (pointerOnly) {
+    process.stderr.write(pointerOnlyRefusalLine(process.cwd(), resolvedMain.vaultRoot));
+  }
+  if (
+    brokenPin &&
+    namespace !== "doctor" &&
+    !pointerFallbackAllowedFor(namespace, command)
+  ) {
+    process.stderr.write(brokenPinRefusalLine(brokenPin));
+    process.exit(2);
+  }
 
   // `hs init` writes the top-level heyspex.yaml vault marker AND scaffolds
   // specs/ ([[HS-EPIC-AEHR-audit-export-heyspex-yaml-and-heyspex-retirement]]
@@ -920,7 +1024,9 @@ function main(argv) {
     dispatchSpexConsoleEntry(
       "hs-install.ts",
       argv,
-      vaultRoot || process.cwd(),
+      // In a committed-marker satellite the install target is the CODE repo
+      // (MCP entry, hooks, commands), never the vault clone the marker names.
+      markerSatelliteDirFrom(INVOKED_CWD) ?? (vaultRoot || process.cwd()),
       {
         HS_PKG_ROOT: PKG_ROOT,
       },
@@ -965,20 +1071,33 @@ function main(argv) {
     const SPAWN_KEYS = {
       claude: "setup:claude",
       cursor: "setup:cursor",
+      copilot: "setup:copilot",
     };
     if (!agent || !Object.hasOwn(SPAWN_KEYS, agent)) {
       process.stderr.write(
-        `hs setup: expected \`claude\` or \`cursor\` (got \`${command ?? ""}\`)\n` +
+        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` +
           "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
-          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n",
+          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
+          "  hs setup copilot [--check|--uninstall|--print|--hooks]   GitHub Copilot (plugin; --hooks for the cloud agent)\n",
       );
       process.exit(2);
     }
     const setupFlags = rest.filter(
       (a) => a === "--check" || a === "--uninstall",
     );
+    if (agent === "copilot") {
+      // Copilot takes more flags: --print, --hooks, --json, --target <dir>.
+      setupFlags.length = 0;
+      for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (["--check", "--uninstall", "--print", "--hooks", "--json"].includes(a)) setupFlags.push(a);
+        else if (a === "--target" && rest[i + 1]) setupFlags.push(a, rest[++i]);
+        else if (a.startsWith("--target=")) setupFlags.push(a);
+      }
+    }
     const script = spawnTargetPath(SPAWN_KEYS[agent]);
-    const target = vaultRoot || process.cwd();
+    // Copilot sets up the repo you are standing in, never the (possibly sibling) vault root.
+    const target = agent === "copilot" ? process.cwd() : vaultRoot || process.cwd();
     const child = spawn(process.execPath, [script, ...setupFlags], {
       cwd: target,
       stdio: "inherit",
@@ -1197,6 +1316,18 @@ function main(argv) {
     process.exit(1);
   }
 
+  // A committed satellite marker whose vault clone is NOT on this machine
+  // resolves to the code repo itself (cloud-only binding). Verbs that write the
+  // vault's files to disk must never scaffold specs/ into a code repo.
+  if (
+    ["pull", "push", "index"].includes(namespace) &&
+    readMarkerSatellite(vaultRoot) &&
+    !existsSync(path.join(vaultRoot, "specs"))
+  ) {
+    process.stderr.write(unclonedVaultRefusalLine(vaultRoot));
+    process.exit(2);
+  }
+
   if (namespace === "index" && command === "rebuild") {
     dispatchSpexConsoleEntry("hs-index-rebuild.ts", rest, vaultRoot, {
       ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
@@ -1228,6 +1359,31 @@ function main(argv) {
     return;
   }
 
+  // `hs import <source-dir>` — a doc tree becomes GROUNDED spec-import captures
+  // in the cwd's vault (heyspex.yaml marker, never the account pointer): group-
+  // intent pass, foundational-to-specific order, sequential Ground=Expand with
+  // a running batch ledger, one intent-map doc, source links; never promotes
+  // ([[HS-0GOV-43G9-CAP-the-spec-import-function-should-not-stop]]). Forwards
+  // the full argv; the entrypoint drops the leading `import` token and resolves
+  // a relative <source-dir> against HS_INVOKED_CWD.
+  if (namespace === "import") {
+    dispatchSpexConsoleEntry("hs-import.ts", argv, vaultRoot, {
+      HS_INVOKED_CWD: INVOKED_CWD,
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs push` — disk -> cloud (SpexRelay local leg, HS-FCNH). Report-only
+  // unless --apply; never creates specs, never pushes status, refuses over a
+  // newer cloud copy. Forwards the full argv; the entrypoint drops `push`.
+  if (namespace === "push") {
+    dispatchSpexConsoleEntry("hs-vault-push.ts", argv, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
   // `hs milestone show <id>` — print a milestone, flagging needs-breakdown when
   // it has no epics ([[HS-TASK-HMSE]] / [[HS-EPIC-MNBD]]). Forwards the full
   // argv; the entrypoint drops the leading `milestone` token.
@@ -1357,7 +1513,9 @@ function main(argv) {
           "  hs source status              Read-only tree status + path-scoped stage plan\n" +
           "  hs source preflight           Alias of status\n" +
           "  hs source commit              Stage + commit per the preflight plan\n" +
-          "  hs source push                Push the committed branch\n" +
+          "  hs source push [branch]       Push the committed branch (no branch: the shared session-branch resolver's target)\n" +
+          "  hs source branch declare [<branch>] | show\n" +
+          "                                Declare the branch this session works on (cloud spec saves then land on it) / show the target\n" +
           "  hs source log <spec-id>       Commit-history lookup for a spec (console settlement,\n" +
           "                                 falling back to local git log)\n" +
           "  hs source identity [show] [--json]\n" +
@@ -1378,6 +1536,7 @@ function main(argv) {
       preflight: "source:preflight",
       commit: "source:commit",
       push: "source:push",
+      branch: "source:branch",
       log: "source:log",
       identity: "source:identity",
     };
@@ -1648,13 +1807,20 @@ function main(argv) {
       process.exit(2);
     }
     const cliPath = spawnTargetPath("heyspex-mcp-cli");
+    // The MCP engine resolves its vault by walking UP from ITS cwd. Launching
+    // it with cwd = the HeySpex checkout made every `hs mcp call` read the
+    // HeySpex vault no matter where the agent stood (found 2026-10-16 from
+    // mlc-specs / mlc-app). Run it from the repo the caller is in; an explicit
+    // HS_VAULT_ROOT keeps winning (the engine is started inside that vault).
+    const mcpCwd = process.env.HS_VAULT_ROOT && vaultRoot ? vaultRoot : INVOKED_CWD;
     const child = spawn(process.execPath, [cliPath, command, ...rest], {
-      cwd: PKG_ROOT,
+      cwd: mcpCwd,
       stdio: "inherit",
       env: {
         ...process.env,
-        HEYSPEX_VAULT_ROOT: vaultRoot,
-        HS_VAULT_ROOT: vaultRoot,
+        CLAUDE_PROJECT_DIR: mcpCwd,
+        HEYSPEX_VAULT_ROOT: vaultRoot ?? "",
+        HS_VAULT_ROOT: vaultRoot ?? "",
         // One-shot MCP tool — no stdio loop, no stderr brief-tier noise in PS.
         HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
       },