@techgoblin/gobstack 0.4.4-beta.1 → 0.4.4-beta.2

package/README.md

@@ -5,13 +5,34 @@ installs an **executable rule manifest**, a set of **project-local skills**, and
 **installer/verifier pair** into any project — so that an AI coding session never re-improvises,
 and a rule that cannot be checked is counted rather than asserted.
 
-Install it from npm — the one documented install path:
+Install it from npm — globally; it is a CLI, not a library:
 
-    npm i -g @techgoblin/gobstack        # gives you the `goblin` CLI
+    npm install -g @techgoblin/gobstack@beta   # gives you the `goblin` CLI (and `gob`)
+    npx @techgoblin/gobstack@beta init         # or the one-shot: run the wizard, install nothing globally
 
 ## Install
 
-    npm i -g @techgoblin/gobstack
+**Global, not local.** gobstack is a CLI with zero runtime dependencies. Install it once per
+machine:
+
+    npm install -g @techgoblin/gobstack@beta
+
+or run a single command without installing:
+
+    npx @techgoblin/gobstack@beta init
+
+**Do NOT add it to an app project's `package.json`.** A `npm install @techgoblin/gobstack` (or a
+`package.json` dependency) inside your app pollutes the app's lockfile with a package the app
+never imports, and can fail resolution outright with `ERESOLVE` when the app's own peer
+dependencies disagree with npm's. If you see `ERESOLVE` after a local install, remove the
+dependency from `package.json` and install globally instead.
+
+**The two-layer model.** The global install gives you the CLI only. `goblin init` (or
+`goblin install --target <dir> --class A`) then vendors a self-contained engine into the target
+repo under `.goblin/` — verifier, manifest, ban probes, skills, all of it. That second layer is
+why an initialized repo keeps working on machines with **no gobstack installed at all**: the
+engine lives in the repo, not in your `node_modules`, and `bash .goblin/bin/goblin-verify` (or a
+plain `git` + `bash` box) is the only runtime the repo's gate needs.
 
 Then, from any project:
 
@@ -63,7 +84,7 @@ The measurement and the vacuous-pass reading are in `docs/CONTRACTS.md`.
 | `goblin bans` | run the ban list (per-pattern red lines over the source tree) |
 | `goblin audit` | check recorded dependency claims against live advisory feeds — the only command that touches the network |
 | `goblin install` | install the manifest, skills and verifier into a target repo |
-| `goblin uninstall` | remove everything an install wrote (npm shim `goblin install --target <dir> --uninstall`) |
+| `goblin uninstall` | remove everything an install wrote, byte-exactly (`goblin install --target <dir> --uninstall` is the same job) |
 | `goblin upgrade` | migrate a repo to the shared global engine at `~/.goblin/engine` — 8 steps, two commits, one report |
 | `goblin doctor` | one run across the platforms below: DETECTED / NOT-DETECTED / DRIFT per platform |
 | `goblin emit` | write the skills + context block for one platform (`--scope project` or `global`); `--unshadow` removes a hermes project skill whose hash equals the source |
@@ -138,11 +159,44 @@ failure**, so that file is the one that matters most.
 
 ## Uninstall
 
-    goblin install --target <dir> --uninstall
+gobstack lives in three layers. Each is removed by its own command, and removing one never
+touches the others.
+
+**(a) The global CLI** — the npm package itself:
+
+    npm uninstall -g @techgoblin/gobstack
+
+This removes the `goblin` and `gob` commands from the machine and nothing else: no project, no
+repo, no `.goblin/` directory anywhere is touched. Repos you already initialized keep working
+fully — the engine is vendored into each repo's `.goblin/`, so the CLI's absence removes no
+capability (you lose the installer/upgrade/emit entry points, not the gate; see layer (c) for
+the machine-level skills the CLI wrote).
+
+**(b) A project's harness** — the `.goblin/` tree an install created in one repo:
+
+    goblin uninstall --target .
+
+(equivalently `goblin install --target . --uninstall`; through the short alias:
+`gob uninstall --target .`). The uninstall is **byte-exact**: it removes exactly the files
+`installed.json` records — hash-compared preimages, so a file you edited after install is
+reported and kept, never clobbered — then every directory that leaves empty. After it, the repo
+has zero goblin files; only the project's own record (`HANDOFF.md`, `AGENTS.md`, `reviews/`, the
+`.gitignore` block) survives, because that is the project's, not the harness's to delete. And
+because the engine is vendored, the repo needs no gobstack installed to run this — it is
+self-contained until the moment you remove it.
+
+**(c) Global agent skills** — the machine-level skills an `emit --scope global` wrote outside any
+repo:
+
+    goblin emit --undo --platform <p> --scope global
+
+(`--undo` is the same byte-exact reversal as `--uninstall`, under its friendlier name). By hand,
+the same job is deleting the platform's anchor entries: `~/.claude/skills/goblin-*` (and the
+equivalents under `~/.hermes`, `~/.copilot`, `~/.cursor`, `~/.config/opencode`, `~/.codex`,
+`~/.gemini` — `goblin doctor` lists which platforms were detected).
 
-Removes the installed artifacts, `.goblin/goblin.yaml` and every directory that leaves empty, and
-leaves `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md`, `reviews/` and the `.gitignore` block —
-the project's record is not the harness's to delete.
+The short version, for a full removal from a machine and its repos: (c) first, then (b) in each
+initialized repo, then (a).
 
 ## Re-pin the referenced standard
 

package/bin/goblin-emit

@@ -80,6 +80,7 @@ goblin emit — per-platform emission (W4a, the seven platforms since W4b).
   --skills     core (the 6 procedure skills), all (every shipped skill), none (context block only)
   --source     the skills payload; default: this CLI checkout's skills/
   --uninstall  reverse every recorded write for the platform, byte-exactly, newest first
+               (--undo is the same job under its friendlier name)
   --unshadow   hermes only: remove project skills whose hash EQUALS the source;
                refuse-and-name on any that differ (a real local edit is never auto-removed)
   --dry-run    print the full write plan (every path + the priced index size), write nothing
@@ -127,6 +128,7 @@ while [ $# -gt 0 ]; do
     --target)    TARGET="${2:-}"; OPT_TARGET=1; shift 2 ;;
     --source)    SRCSKILLS="${2:-}"; shift 2 ;;
     --uninstall) UNINSTALL=1; shift ;;
+    --undo)      UNINSTALL=1; shift ;;
     --unshadow)  UNSHADOW=1; shift ;;
     --dry-run)   DRYRUN=1; shift ;;
     --strict)    STRICT=1; shift ;;

package/bin/goblin.js

@@ -13,7 +13,13 @@
 //   goblin doctor [...]                   -> bin/goblin-doctor (W4a)
 //   goblin emit   [...]                   -> bin/goblin-emit (W4a)
 //   goblin init   [...]                   -> bin/goblin-init (W6, the first-run wizard)
-//   anything else (install)               -> bin/goblin-install
+//   goblin uninstall [--target <dir>]     -> bin/goblin-install --uninstall
+//   goblin 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.
 //
 // 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
@@ -40,9 +46,58 @@ if (arg0 === "--version" || arg0 === "-V" || arg0 === "-v") {
 
 const SCRIPT = { verify: "goblin-verify", bans: "goblin-bans", audit: "goblin-audit", upgrade: "goblin-upgrade", doctor: "goblin-doctor", emit: "goblin-emit", init: "goblin-init" };
 const [cmd, ...rest] = process.argv.slice(2);
-const target = SCRIPT[cmd] ?? "goblin-install"; // install → goblin-install (v1); init is a real subcommand since W6
+
+// 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 `goblin install ...` keeps the
+// installer; everything else stops here and names the word it did not know.
+function usage() {
+  process.stderr.write(
+[
+"goblin <command>",
+"",
+"  goblin init      start here — the guided first step (detect, class, emit, first verify)",
+"  goblin verify    run the rule matrix against the current repo",
+"  goblin bans      run the ban list (per-pattern red lines over the source tree)",
+"  goblin audit     check recorded dependency claims against live advisory feeds",
+"  goblin upgrade   migrate a repo to the shared global engine at ~/.goblin/engine",
+"  goblin doctor    one detection/drift run across the agent platforms",
+"  goblin emit      write the skills + context block for one platform",
+"  goblin uninstall --target .        remove exactly what an install wrote (preimages)",
+"",
+"start here: goblin init",
+"uninstall: npm uninstall -g @techgoblin/gobstack",
+"",
+].join("\n"));
+}
+
+if (cmd === undefined || cmd.startsWith("-")) {
+  usage();
+  process.exit(2);
+}
+if (!SCRIPT[cmd] && cmd !== "install" && cmd !== "uninstall") {
+  process.stderr.write(`goblin: unrecognized command: ${cmd}\n\n`);
+  usage();
+  process.exit(2);
+}
+
+let target;
+let extra = [];
+if (cmd === "install") {
+  target = "goblin-install"; // the one legacy fallback, kept verbatim
+} else if (cmd === "uninstall") {
+  // `goblin 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.
+  target = "goblin-install";
+  extra = ["--uninstall"];
+} else {
+  target = SCRIPT[cmd];
+}
 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, ...rest], { stdio: "inherit" });
+const r = spawnSync("bash", [file, ...extra, ...rest], { stdio: "inherit" });
 process.exit(r.status ?? 2);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@techgoblin/gobstack",
-  "version": "0.4.4-beta.1",
+  "version": "0.4.4-beta.2",
   "description": "Agent-discipline toolkit: one verify command, an enforcement matrix, and LIMITS. bash engine, npm shim.",
   "bin": {
-    "goblin": "bin/goblin.js"
+    "goblin": "bin/goblin.js",
+    "gob": "bin/goblin.js"
   },
   "publishConfig": {
     "access": "public"