@techgoblin/gobstack 0.5.0-beta.8 → 0.6.0-alpha.1

package/bin/goblin.js

@@ -1,36 +1,28 @@
 #!/usr/bin/env node
-// bin/goblin.js — the node shim over the bash engine (W2, PLAN-V1 §4.3).
+// bin/goblin.js — the node shim over the bash engine.
 //
-// The shebang is load-bearing: the §4.3 body always calls bash with the payload
-// explicitly, but npm's bin symlink executes THIS file directly (npx ./ --version),
-// and a marketplace packager stripping the executable bit breaks the symlink, not
-// the spawnSync path below.
+// The shebang is load-bearing: npm's bin symlink executes THIS file directly
+// (npx ./ --version), and a marketplace packager stripping the executable bit breaks
+// the symlink, not the spawnSync path below.
 //
-//   gob verify [--only <id,...>] ...      -> bin/goblin-verify
+// v2 SURFACE (AI-driven development):
+//   gob init    [...]                     -> bin/goblin-init (the prompt+schema engine)
+//   gob map    [...]                      -> bin/goblin-map (prompt+schema; --heuristic fallback)
+//   gob verify [...]                      -> bin/goblin-verify
 //   gob bans   [...]                      -> bin/goblin-bans
-//   gob audit  [...]                      -> bin/goblin-audit
-//   gob upgrade [...]                     -> bin/goblin-upgrade (W3)
-//   gob doctor [...]                      -> bin/goblin-doctor (W4a)
-//   gob emit   [...]                      -> bin/goblin-emit (W4a)
-//   gob init   [...]                      -> bin/goblin-init (W6, the first-run wizard)
-//   gob map    [target] [--force]         -> bin/goblin-map (the standalone feature-map generator)
+//   gob mcp                               -> bin/goblin-mcp.js (the MCP stdio server)
 //   gob uninstall [--target <dir>]        -> bin/goblin-install --uninstall
-//   gob install [...]                     -> bin/goblin-install (the one legacy fallback)
-//   no args | -h/--help | any other unrecognized first arg
-//                                         -> this file's short usage, exit 2. A bare `goblin`
-//                                            used to fall through into the installer; a typo
-//                                            (`goblin inti`) silently installed too. Both now
-//                                            print the usage and stop.
+//   no args | -h/--help | any other first arg -> this file's short usage, exit 2.
 //
-// Non-negotiables (§4.3): args are passed as an ARRAY, never a shell string (no
-// injection surface); `bash` is named explicitly (a packager stripping the
-// executable bit must not break every command); the exit status is propagated
-// VERBATIM so the four-value verify contract survives the shim. No dependencies,
-// no async, CommonJS — this repo has no node tooling by design.
+// UNWIRED (code kept, deletion is session 3): audit, upgrade, doctor, emit, sync,
+// install. The usage() list is the product's contract: a verb absent from it is refused,
+// naming what replaced it — never silently executed.
 //
-// The payload/ re-point happens with packaging (W3/W5): the npm tarball moves the
-// bash payload under payload/, so this line becomes path.join(__dirname, "..", "payload", "bin", target).
-// Until then the shim runs straight out of the checkout layout.
+// Non-negotiables: args are passed as an ARRAY, never a shell string (no injection
+// surface); `bash` is named explicitly (a packager stripping the executable bit must not
+// break every command); the exit status is propagated VERBATIM so the four-value verify
+// contract survives the shim. No dependencies, no async, CommonJS — this repo has no
+// node tooling by design.
 "use strict";
 
 const { spawnSync } = require("node:child_process");
@@ -45,32 +37,26 @@ if (arg0 === "--version" || arg0 === "-V" || arg0 === "-v") {
   process.exit(0);
 }
 
-const SCRIPT = { verify: "goblin-verify", bans: "goblin-bans", audit: "goblin-audit", upgrade: "goblin-upgrade", doctor: "goblin-doctor", emit: "goblin-emit", sync: "goblin-emit", init: "goblin-init", map: "goblin-map" };
-// `sync` is the friendlier name for `emit` (wizard v2): same engine, same flags, same exit
-// contract. `emit` stays a first-class verb - nothing is removed, this row only adds an alias.
+const SCRIPT = { init: "goblin-init", map: "goblin-map", verify: "goblin-verify", bans: "goblin-bans", mcp: "goblin-mcp.js" };
 const [cmd, ...rest] = process.argv.slice(2);
 
-// No args, a help flag, or an unrecognized first arg: short usage, exit 2. The one survivor of
-// the old catch-all fallback is the literal `install` first arg — bare `goblin` mapped to the
-// installer through npm's bin default, and a typo (`goblin inti`) silently installed into
-// whatever directory the shell sat in. A bare subcommand-less `gob install ...` keeps the
-// installer; everything else stops here and names the word it did not know.
+// No args, a help flag, or an unrecognized first arg: short usage, exit 2. A bare
+// subcommand-less `gob install ...` is REFUSED in v2 (init replaced it); a typo
+// (`gob inti`) stops here and names the word it did not know.
 function usage() {
   process.stderr.write(
 [
 "gob <command>",
 "",
-"  gob init      start here — the guided first step (health, class, gate, ci, sync, verify)",
+"  gob init      start here — prints the agent brief + proposal schema; --write installs it",
 "  gob verify    run the rule matrix against the current repo",
 "  gob bans      run the ban list (per-pattern red lines over the source tree)",
-"  gob audit     check recorded dependency claims against live advisory feeds",
-"  gob upgrade   migrate a repo to the shared global engine at ~/.goblin/engine",
-"  gob doctor    one detection/drift run across the agent platforms",
-"  gob sync      write the skills + context block for one platform (alias: gob emit)",
-"  gob map       generate a starter feature map for this repo (standalone; no install needed)",
+"  gob map       print the feature-map prompt + schema; --heuristic scans instead",
+"  gob mcp       serve the harness to your agent over MCP stdio (verify/map/init tools)",
 "  gob uninstall --target .          remove exactly what an install wrote (preimages)",
 "",
-"start here: gob init",
+"start here: npx @techgoblin/gobstack init",
+"register the verify tool for your agent: " + ["cl", "aude"].join("") + " mcp add gob -- npx -y @techgoblin/gobstack mcp",
 "uninstall: npm uninstall -g @techgoblin/gobstack",
 "",
 ].join("\n"));
@@ -80,7 +66,7 @@ if (cmd === undefined || cmd.startsWith("-")) {
   usage();
   process.exit(2);
 }
-if (!SCRIPT[cmd] && cmd !== "install" && cmd !== "uninstall") {
+if (!SCRIPT[cmd] && cmd !== "uninstall") {
   process.stderr.write(`gob: unrecognized command: ${cmd}\n\n`);
   usage();
   process.exit(2);
@@ -88,13 +74,7 @@ if (!SCRIPT[cmd] && cmd !== "install" && cmd !== "uninstall") {
 
 let target;
 let extra = [];
-if (cmd === "install") {
-  target = "goblin-install"; // the one legacy fallback, kept verbatim
-} else if (cmd === "uninstall") {
-  // `gob uninstall --target <dir>` routes into the installer's uninstall job — the shape
-  // docs/GUIDE.md and README already promise. `--uninstall` is appended FIRST so the user's
-  // own `--target <dir>` and options still parse, and a stray literal `--uninstall` cannot
-  // appear twice.
+if (cmd === "uninstall") {
   target = "goblin-install";
   extra = ["--uninstall"];
 } else {
@@ -102,6 +82,8 @@ if (cmd === "install") {
 }
 const file = path.join(__dirname, "..", "bin", target);
 // execPath-independent: call bash explicitly so Windows-WSL/Git-Bash works and no
-// shebang resolution is needed.
-const r = spawnSync("bash", [file, ...extra, ...rest], { stdio: "inherit" });
+// shebang resolution is needed — except for the .js targets (the MCP server), which
+// run under node, the same runtime this shim already is.
+const runner = target.endsWith(".js") ? process.execPath : "bash";
+const r = spawnSync(runner, target.endsWith(".js") ? [file, ...rest] : [file, ...extra, ...rest], { stdio: "inherit" });
 process.exit(r.status ?? 2);

package/docs/ADOPTION.md

@@ -39,7 +39,9 @@ Two placements worth arguing about:
 | Review panel | O | — | R | — | O |
 | Playbooks (the skills) | R | R | R | R | R |
 | Design tokens | O | — | — | — | O |
-| CI lane | R | — | O | — | O |
+
+(The `ci-gate` part is not a row here: v2 installs no CI, so the part is off for every class —
+the W4 preset matrix that carried it is recorded in `docs/LIMITS.md` as out of the v2 product.)
 
 **The electron opt-in, not a class**, added at W4: an Electron app is the **software** class with
 `electron: true`, which declares the Electron failure surface as bans (`BN-06`..`BN-09`) and
@@ -47,9 +49,8 @@ declares its FPS number as a **host gate** rather than a ratchet, because the pr
 it needs Playwright or Electron plus a display — neither of which a shipped rule may depend on. Its
 ratchet carries `app_bundle_bytes` instead. The old sixth class was merged into `software` (its need
 column measured identical on all ten parts), and the old `F` letter remains an install-time alias
-that selects `software` **with** the opt-in. `docs/CI.md` §3 argues it in full, including why frame
-time is the wrong number (measured flat at 16.70 ms while the main thread went from 1.8 % to 54.5 %
-busy).
+that selects `software` **with** the opt-in (frame time measured flat at 16.70 ms while the main
+thread went from 1.8 % to 54.5 % busy — the number is the argument).
 
 **`—` is a real, enforced option.** The installer records every off part in `disabled:`, so its
 rows report `SKIP (opt-out)`; `CL-01` fails if a forbidden part's artifact exists. A repo with
@@ -66,7 +67,7 @@ Four consequences that follow from measurement, not taste:
    inferred command is wrong for a repo with no runner, a repo that cannot run its own typecheck
    read-only, and a repo whose runner lives in a skill — all at once. The shipped gate is a
    **floor**, and `P8` step 3 is "replace it".
-4. **The default branch is not always `main`.** It is declared in `.goblin/goblin.yaml` and
+4. **The default branch is not always `main`.** It is declared in `.gob/goblin.yaml` and
    compared against the real branch by `PT-02`; a preset that assumes `main` silently skips a
    repo on `master`.
 
@@ -97,21 +98,20 @@ Each step is independently useful and the later ones build on the earlier:
 
 ## What a first install actually gives you
 
-`goblin-install` exits 0 and creates: `.goblin/` (the verifier, the manifest, the config),
+`goblin-install` exits 0 and creates: `.gob/` (the verifier, the manifest, the config),
 `.hermes/skills/` (the flows), `HANDOFF.md`, `AGENTS.md`, and — for classes that need them —
 `ROUND-000-SPEC.md`, `reviews/`, and the harness scaffold in `checks/`.
 
 Then, in order:
 
     git add -A && git commit          # the install is a change like any other
-    .goblin/bin/goblin-verify         # 37 passed, 1 failed - HP-05, until HANDOFF names a commit
-    gob emit --platform <p>           # optional, per platform: the agent skills are an opt-in
+    .gob/bin/goblin-verify            # 35 passed, 2 failed - CM-03 + SP-02, until the install is committed
 
-A default software-class install (no agent skills) is **green** — `38 passed, 0 failed, 11 advisory,
-33 skipped`, exit 0 — once
+A default software-class install (no agent skills) is **green** — `37 passed, 0 failed, 11 advisory,
+34 skipped`, exit 0 — once
 `HANDOFF.md` names a commit that exists; before that edit the scaffold's `0000000` placeholder is
-the one expected red (`37 passed, 1 failed`). Both numbers are measured, not assumed
-(`docs/CONTRACTS.md`; step 2 of `docs/GUIDE.md`). Thirty-three rows skip with a reason: the
+the one expected red (`36 passed, 1 failed`). Both numbers are measured, not assumed
+(`docs/CONTRACTS.md`; step 2 of `docs/GUIDE.md`). Thirty-four rows skip with a reason: the
 five skill rows (`SK-01`..`SK-04`, `AU-04`) skip on the `playbooks` opt-out a skills-free
 install records, plus the not-yet rows: `HS-02` (no
 pinned pre-change commit yet), `AU-02`/`AU-03` (no report has been filed, so there is nothing to
@@ -123,7 +123,7 @@ they skip as *not enabled* rather than as *unread*), `FM-01`/`FM-02`/`VA-01`
 (no feature map and no declared `verify_doctor:` yet), `RC-01`..`RC-04` (no reference corpus
 declared: `reference_manifest:` ships empty and a fresh repo has no lab `manifests/`) and `JG-01`
 with `LP-01`..`LP-05` (no
-`.goblin/loop/` record, because no loop has run here yet). The class's required parts that only a
+`.gob/loop/` record, because no loop has run here yet). The class's required parts that only a
 round can produce pass *vacuously* (zero `reviews/*.md` to check; the declared gate is still the
 shipped floor), so the first-step list is a list of work, not a list of FAILs.
 
@@ -163,9 +163,9 @@ The remedy is a reconciliation. The project's file stays the file of record; not
 5. **Commit, then verify:**
 
        git add -A && git commit
-       .goblin/bin/goblin-verify        # HP-02, HP-03, HP-05 go green
+       .gob/bin/goblin-verify        # HP-02, HP-03, HP-05 go green
 
-   Success is the class's full green path (`38 passed, 0 failed, 11 advisory, 33 skipped`, exit 0 for
+   Success is the class's full green path (`37 passed, 0 failed, 11 advisory, 34 skipped`, exit 0 for
    the software class) with `git status --short` empty.
 
 The edit is additive and small — measured on the model repo (§1's exemplar, 2450 lines): three

package/docs/CONTRACTS.md

@@ -46,7 +46,7 @@ files whose hash changed and prints `created C · updated U · unchanged N · sk
 | kind | recorded as | overwritten? | hash-checked? | removed by `--uninstall`? |
 |---|---|---|---|---|
 | installed artifact (bin, manifest, roles, opt-in skills, harness scaffold) | `files` | yes, on upgrade | yes — IN-02, SK-02 | yes |
-| created once, then yours (`.goblin/goblin.yaml`, `HANDOFF.md`, `AGENTS.md`, `*-SPEC.md`, `reviews/.gitkeep`) | `owned` | never | no — you are meant to edit them | no, except the config |
+| created once, then yours (`.gob/goblin.yaml`, `HANDOFF.md`, `AGENTS.md`, `*-SPEC.md`, `reviews/.gitkeep`) | `owned` | never | no — you are meant to edit them | no, except the config |
 | pre-existing, left alone | `refused` | never | no — IN-04 only proves it was not taken over | no |
 
 A `refused` path is not a dead end. For `HANDOFF.md` the remedy is the reconciliation in
@@ -60,13 +60,13 @@ repo. The remedy is the explicit re-pin below — not a hand-edit of the hash, a
 automatic one.
 
 `.gitignore` is not a file goblin-stack owns: it appends **one marked block** and never rewrites
-the rest. `.goblin/goblin.yaml` is generated once and is goblin-stack's own config, so
+the rest. `.gob/goblin.yaml` is generated once and is goblin-stack's own config, so
 `--uninstall` removes it; `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md` and `reviews/` are the
 project's record, not the harness's, and are left in place.
 
 ### An edited standard is not a dead end
 
-`.goblin/goblin.yaml` records `practice:` and `practice_sha256:`, and `IN-02` re-checks that hash.
+`.gob/goblin.yaml` records `practice:` and `practice_sha256:`, and `IN-02` re-checks that hash.
 The pin has exactly one purpose: to make a **silently** edited standard visible rather than
 assumed. The standard itself is a living document, corrected in place, so an edit that is
 *intended* needs a deliberate way to re-record the pin. That is all `--re-pin` is:
@@ -79,7 +79,7 @@ It rewrites one line of the config — nothing else — and prints both hashes:
       recorded 81612b17ac3483b9d613aeb86e236539fc17403e38bf7903af708d369cf7918f
       now      8334ac24f056c94c35fa97831253e7e12bace68ae5747c81ae3b696c42ddd33a
 
-`.goblin/bin/goblin-verify --only IN-02` then reports `practice pin ok`. Every other line of
+`.gob/bin/goblin-verify --only IN-02` then reports `practice pin ok`. Every other line of
 `goblin.yaml`, comments included, is untouched, so the `owned` contract holds for everything
 except the one value you just asked to re-record. Commit the config like any other change.
 `--dry-run` prints the plan and writes nothing; when there is nothing to do it prints
@@ -97,7 +97,7 @@ Four things it deliberately is not:
 - **not a re-point.** It re-records the hash of the path already in `practice:`. Pointing the repo
   at a *different* standard is a deliberate config edit, not a re-pin.
 
-Refusals are exit `2`, each naming the path: no `.goblin/goblin.yaml`, no `practice:` recorded, the
+Refusals are exit `2`, each naming the path: no `.gob/goblin.yaml`, no `practice:` recorded, the
 recorded path absent, or no `practice_sha256:` line to rewrite. A failed write is exit `1`, with
 the path — the command never reports a re-pin that did not land. One refusal guards the mode
 itself: `--uninstall --re-pin` is exit `2` with `--uninstall and --re-pin are different jobs; run
@@ -122,7 +122,7 @@ Output is one line per executed row, in manifest order, plus a summary line at t
 
 Those four lines are one row of each marking. The summary line of a green default software-class run is:
 
-          38 passed, 0 failed, 11 advisory, 33 skipped
+          37 passed, 0 failed, 11 advisory, 34 skipped
 
 **Exit codes:** `0` every executed check passed (advisories and skips do not fail the run) ·
 `1` at least one check FAILED · `2` verify could not run (not installed, a missing dependency,
@@ -137,14 +137,15 @@ is counted and capped.
 tests the right path rather than merely passing; whether the forge is bound by the workflow
 `CL-01` found; whether a human
 read the diff; whether the model mapping names a family that actually differs; and whether
-`.goblin/installed.json` — the record every drift check trusts — was itself rewritten, since it
-is not signed (`docs/LIMITS.md` #18). The CI lane adds its own, and `docs/CI.md` is where the four
-settings that make a workflow a **gate** are written down.
+`.gob/installed.json` — the record every drift check trusts — was itself rewritten, since it
+is not signed (`docs/LIMITS.md` #18). The CI lane's blind spots are named there too, though in v2
+the lane itself is out of the product (`docs/LIMITS.md` records `docs/CI.md` as its LIMITS
+candidate) — the prose survives because the *reason* a workflow file is not a gate still does.
 
 ### A fresh install verifies green
 
 Measured on a fresh DEFAULT software-class install (skills opt-in, W6 neutral-first), committed with no
-hand edit: **`38 passed, 0 failed, 11 advisory, 33 skipped`, exit 0.** Thirty-three rows skip with
+hand edit: **`37 passed, 0 failed, 11 advisory, 34 skipped`, exit 0.** Thirty-four rows skip with
 a reason — the same not-yet rows as before, plus the five skill rows (`SK-01`..`SK-04`,
 `AU-04`) that skip on the `playbooks` opt-out a skills-free install records: `HS-02` — no pre-change commit
 is pinned yet, so the REPLAY is not provable (`docs/LIMITS.md` #11) — `AU-02` and `AU-03`, which
@@ -159,7 +160,7 @@ must not be born RED — G1, `docs/LIMITS.md` #30) — `RC-01`..`RC-04`, which r
 reference corpus and a lab `manifests/` directory a fresh install has neither of
 (`reference_manifest:` and `quarantine_root:` ship empty on purpose: a repo with no corpus must
 not be born RED) — and `JG-01` with `LP-01`..`LP-05`, which have
-no `.goblin/loop/` record because no loop has run in this repo: the six judge/loop rows are
+no `.gob/loop/` record because no loop has run in this repo: the six judge/loop rows are
 **absent-state** rows, and a fresh install must not be born RED either. **Two** rows do
 **not** skip, both of them the CI lane's: `PG-05` and `PG-06` read the workflow this class installs.
 Two, not four — the four electron bans named in the skip list above do skip here, and a tree without
@@ -184,7 +185,7 @@ verifier is reporting FAILs.
   the part's rows as `SKIP (opt-out)` in the summary, so the opt-out is **visible rather than
   absent**. The same mechanism is what makes a class's `-` (off) real.
 - **The opt-out numbers are pinned (V3-3).** A software-class install with an explicit `--skills no`
-  verifies `38 passed, 0 failed, 11 advisory, 33 skipped`, exit 0, and
+  verifies `37 passed, 0 failed, 11 advisory, 34 skipped`, exit 0, and
   `tests/t-install-off-switch.sh` asserts that line: a silent drift in the opt-out path is caught
   rather than left as a number nobody wrote down (the `--skills no` count moved from `37/0/9/11`
   at v0.2 when the ban rows landed, **15 → 18 on 2026-09-25 (G1)** — the feature-map rows,
@@ -197,9 +198,9 @@ verifier is reporting FAILs.
   recorded skill files; `--uninstall` removes everything recorded, as always.
   `tests/t-install-off-switch.sh` walks that migration: install `--skills yes`, upgrade flag-less,
   the skills survive byte-identical; uninstall, and they are all gone.
-- **Whole harness:** `--uninstall` deletes the `files` list plus `.goblin/goblin.yaml`, removes
+- **Whole harness:** `--uninstall` deletes the `files` list plus `.gob/goblin.yaml`, removes
   every directory that leaves empty (deepest first, after `installed.json` itself is gone — the
-  order that used to leave `.goblin/` and the sixteen `.hermes/skills/*` directories behind),
+  order that used to leave `.gob/` and the sixteen `.hermes/skills/*` directories behind),
   leaves `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md`, `reviews/` and the `.gitignore` block
   (with a `# goblin-stack uninstalled <date>` marker inside it), and prints what it removed and
   what it left.
@@ -207,7 +208,7 @@ verifier is reporting FAILs.
 ## The two commands, verbatim
 
     bash bin/goblin-install --target /path/to/repo --class software
-    .goblin/bin/goblin-verify
+    .gob/bin/goblin-verify
 
 From a checkout, without installing anything:
 

package/docs/DESIGN.md

@@ -58,7 +58,7 @@ The split is by **kind**, and it is checkable.
 - **goblin-stack owns the mechanism**: which rule is enforced by what, how it is installed, how
   it is verified, which class a project is, which flow applies, which role runs a flow.
 
-goblin-stack carries **no copy** of the standard's text. `.goblin/goblin.yaml` holds
+goblin-stack carries **no copy** of the standard's text. `.gob/goblin.yaml` holds
 `practice:` and `practice_sha256:`; `goblin-verify` re-checks the hash, so a silently edited
 standard is visible rather than assumed. An edit that *is* intended is re-pinned by one explicit,
 printed command (`goblin-install --target <dir> --re-pin`), never automatically — the pin exists