@techgoblin/gobstack 0.6.0-alpha.3 → 0.6.0-alpha.4

package/README.md

@@ -87,7 +87,7 @@ is unwired in this alpha: the shim refuses the verb by name and prints the usage
 | `gob bans` | run the ban list (per-pattern red lines over the source tree) |
 | `gob extras` | the curated extras catalogue: `list [category]` / `show <id>` / `install <id...> [­-target <dir>] [--platform <id>] [--with-mcp-config]` — init only SUGGESTS; installs come from the catalogue (the allowlist rule), never the web |
 | `gob mcp` | serve the harness to your coding agent over MCP stdio — three tools (`gob_verify`, `gob_map_status`, `gob_init_status`), local only, no SDK, no network |
-| `gob uninstall` | remove everything an install wrote, byte-exactly (`gob install --target <dir> --uninstall` is the same job) |
+| `gob uninstall` | remove everything an install wrote, byte-exactly (the same job as `goblin-install --target <dir> --uninstall` from the checkout/install tree) |
 
 `goblin` remains as a legacy alias for every command above — existing scripts keep working, but
 new commands and docs use `gob`.
@@ -254,14 +254,17 @@ capability.
 
     gob uninstall --target .
 
-(equivalently `gob install --target . --uninstall` — through the legacy alias, spell it `goblin`
+(the same job as `goblin-install --target . --uninstall` — through the legacy alias, spell it `goblin`
 instead of `gob`). 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, and it strips the
 `<!-- gob:begin --> … <!-- gob:end -->` block out of `AGENTS.md` (the body prose stays). After
 it, the repo has zero harness files; only the project's own record (`HANDOFF.md`, `AGENTS.md`'s
 prose, `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
+harness's to delete. Two residues are left **by design, and named in the output**: the
+`.gitignore` ignore-rules block stays (removing it could eat a line the project added inside
+it — delete that block by hand if you want it gone), and prose that named `.gob/` paths
+(HANDOFF, the AGENTS.md body, SPECs) now points at removed files. 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.
 
 The short version, for a full removal from a machine and its repos: (b) in each initialized
@@ -269,7 +272,7 @@ repo, then (a).
 
 ## Re-pin the referenced standard
 
-    gob install --target <dir> --re-pin
+    goblin-install --target <dir> --re-pin   # from the gobstack checkout / install tree
 
 `practice_sha256:` in the AGENTS.md gob block pins the referenced standard and `IN-02`
 re-checks it, so editing that standard — a legitimate, intended edit — reds `IN-02` in every

package/VERSION

@@ -1 +1 @@
-0.6.0-alpha.3
+0.6.0-alpha.4

package/bin/goblin-audit

@@ -23,7 +23,7 @@
 #      because an empty record reads to SC-07 as "clean" and that would be a fabricated pass
 set -uo pipefail
 
-GOBLIN_AUDIT_VERSION="0.6.0-alpha.3"
+GOBLIN_AUDIT_VERSION="0.6.0-alpha.4"
 
 usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
 

package/bin/goblin-bans

@@ -28,7 +28,7 @@
 
 set -uo pipefail
 
-GOBLIN_BANS_VERSION="0.6.0-alpha.3"
+GOBLIN_BANS_VERSION="0.6.0-alpha.4"
 SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=goblin-lib.sh
 . "$SELF_DIR/goblin-lib.sh"

package/bin/goblin-extras

@@ -54,7 +54,7 @@ usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
 CATALOGUE="${GOB_EXTRAS_CATALOGUE:-$SRC/extras-catalogue/catalogue.tsv}"
 PAYLOAD="${GOB_EXTRAS_PAYLOAD:-$SRC/extras-catalogue/payload}"
 
-die() { g_err "extras: $*"; exit "${2:-2}"; }
+die() { local msg="$1"; shift; g_err "extras: $msg"; exit "${1:-2}"; }
 
 # catalogue_row <id> — the whole data row (tab-separated), empty when absent.
 catalogue_row() {
@@ -250,7 +250,12 @@ install_skill() {
     [ -d "$d" ] || continue
     name=$(basename "$d")
     n=$((n + 1))
-    g_info "extras: skill $name -> ${dst_root#"$TARGET"/}$name/"
+    # QA fix (v2-qa issue 9): the display path must carry exactly one separator between
+    # $dst_root and $name — the old single format printed `.gob/extras` + `taste` as
+    # `.gob/extrastaste/` (files landed in the right place, only the LOG lied). The
+    # platform branch normalizes $dst_root to end in /, the standalone branch does not,
+    # so the trailing slashes are stripped at print time and one / is always inserted.
+    printf 'extras: skill %s -> %s/%s/\n' "$name" "${dst_root%/}" "$name"
     copy_tree "$d" "$dst_root/$name"
   done
   [ "$n" -gt 0 ] || die "payload for '$id' holds no skill dirs ($src_root/*/ with SKILL.md each) — see extras-catalogue/payload/README.md" 2

package/bin/goblin-init

@@ -133,6 +133,10 @@ back one proposal file. Do this now:
      found in step 1 — react, vue, playwright, godot, unity, node, postgres, …);
    - RECOMMEND rows are pre-ticked (write `- id` with `[x]`); MAYBE rows are
      listed but NOT pre-ticked (`[ ]`) — they are visible choices, never defaults;
+   - a row with NO vendored payload (no `extras-catalogue/payload/<id>/` directory)
+     must NOT be pre-ticked even when RECOMMEND — print it as `[ ]` instead;
+     `--write` installs through `gob extras install`, which refuses a
+     payload-missing id and fails the whole --write;
    - a row whose `conflicts:` names an id you also picked: pick at most one of them;
    - SKIP rows are never suggested and refuse install; leave them out entirely.
 
@@ -226,13 +230,21 @@ print_heuristic() {
   # files). The SAME matches column the agent brief reads — the fallback suggests from
   # the catalogue, never from its own private list. Verdicts are respected: only
   # RECOMMEND rows pre-tick; MAYBE rows print unticked; SKIP rows never appear.
+  # QA fix (v2-qa): a row pre-ticks ONLY when its vendored payload exists —
+  # extras-catalogue/payload/<id>/ — because --write installs through
+  # `gob extras install`, which refuses a payload-missing row and fails the whole
+  # --write after everything else was already written. A RECOMMEND row with no
+  # payload prints as a visible, unticked `[ ]` choice instead. (41 researched rows,
+  # 1 vendored payload: the old pre-tick turned a day-one init into a guaranteed
+  # exit 2 halfway through writing.)
   if [ -f "$CATALOGUE_TSV" ]; then
     local scan
     scan=$(cat "$TARGET/package.json" "$TARGET"/*.lock "$TARGET"/pnpm-lock.yaml \
               "$TARGET"/vue.config.* "$TARGET"/nuxt.config.* "$TARGET"/godot/project.godot \
               "$TARGET"/unity/ProjectSettings/ProjectVersion.txt 2>/dev/null | tr 'A-Z' 'a-z')
     if [ -n "$scan" ]; then
-      local ticked="" maybe=""
+      local ticked="" maybe="" payload_root
+      payload_root="${GOB_EXTRAS_PAYLOAD:-$SRC/extras-catalogue/payload}"
       while IFS=$'\t' read -r cid ccat ckind cname crepo cpath chmd clic cstars cpush \
                           cmatches cconf creq chint cverdict cby cdate; do
         [ -n "$cid" ] || continue
@@ -242,6 +254,12 @@ print_heuristic() {
           case "$scan" in *"$tok"*) hit=1; break ;; esac
         done
         [ "$hit" -eq 1 ] || continue
+        if [ ! -d "$payload_root/$cid" ]; then
+          # no vendored payload: the row stays visible but never pre-ticks —
+          # a tick --write cannot honour is a refusal waiting to happen
+          maybe="$maybe    - [ ] $cid  # matches this repo, NO VENDORED PAYLOAD yet (gob extras install would refuse — vendor it under extras-catalogue/payload/$cid/ first)"$'\n'
+          continue
+        fi
         case "$cverdict" in
           RECOMMEND) ticked="$ticked    - [x] $cid  # matches this repo ($cmatches)"$'\n' ;;
           MAYBE)     maybe="$maybe    - [ ] $cid  # matches, verdict MAYBE (not pre-ticked)"$'\n' ;;
@@ -326,6 +344,37 @@ SYNC_SEL=$(g_agents_list "$PROP" sync_platforms | tr '\n' ' ')
 # cannot install anything the catalogue does not carry.
 EXTRAS_SEL=$(sed -n '/catalogue_suggestions:/,/^[^ -]/{s/^[[:space:]]*-[[:space:]]*\[x\][[:space:]]*\([A-Za-z0-9_-]*\).*/\1/p;}' "$PROP" | sort -u | tr '\n' ' ')
 
+# ---------------------------------------------------------------- pre-flight ---
+# QA fix (v2-qa issue 1b): the TICKED extras are validated BEFORE anything is written.
+# The old order installed the harness first and ran `gob extras install` last, so a
+# missing vendored payload refused AFTER 23 files were already in the tree (the day-one
+# exit 2 with the repo half-initialized). Here every ticked id is resolved through the
+# same allowlist path goblin-extras uses (row exists, verdict installable, license gate,
+# vendored payload present) while the target is still untouched; a refusal names the id
+# and the fix and exits before the first write.
+if [ -n "$EXTRAS_SEL" ] && [ "$DRYRUN" -eq 0 ]; then
+  PAYLOAD_ROOT="${GOB_EXTRAS_PAYLOAD:-$SRC/extras-catalogue/payload}"
+  for xid in $EXTRAS_SEL; do
+    row=$(awk -F'\t' -v id="$xid" 'NR>1 && $1==id { print; exit }' "$CATALOGUE_TSV" 2>/dev/null)
+    [ -n "$row" ] || { g_err "pre-flight: catalogue has no row '$xid' — fix the proposal's catalogue_suggestions (gob extras list names the allowlist)"; exit 2; }
+    verdict=$(printf '%s' "$row" | awk -F'\t' '{print $15}')
+    lic=$(printf '%s' "$row" | awk -F'\t' '{print $18}')
+    case "$verdict" in
+      RECOMMEND|MAYBE) ;;
+      *) g_err "pre-flight: '$xid' carries verdict '$verdict' — untick it in the proposal's catalogue_suggestions"; exit 2 ;;
+    esac
+    # the same license gate goblin-extras enforces, read before any write
+    case "$lic" in
+      verified) ;;
+      *) g_err "pre-flight: '$xid' refuses install: license pending verification — untick it in the proposal's catalogue_suggestions"; exit 2 ;;
+    esac
+    [ -d "$PAYLOAD_ROOT/$xid" ] || {
+      g_err "pre-flight: no vendored payload for '$xid' at $PAYLOAD_ROOT/$xid — untick it in the proposal's catalogue_suggestions, or vendor the payload there first";
+      exit 2;
+    }
+  done
+fi
+
 if [ "$DRYRUN" -eq 1 ]; then
   g_info "gob init --write --dry-run: validated OK (class $CLASS, branch $BRANCH, owner $EMAIL, 1+ gate)"
   g_info "  sync: ${SYNC_SEL:-none}"

package/bin/goblin-install

@@ -1,19 +1,23 @@
 #!/usr/bin/env bash
 # goblin-install — drop the harness into a target repo, idempotently.
 #
-# Usage: gob install --target <dir> [options]   (script: bin/goblin-install)
+# Usage: bash bin/goblin-install --target <dir> [options]   # checkout-only; `gob init --write` is the user surface
 #   --target <dir>        required; the repo root to install into
 #   --class <name>        required unless --uninstall or --re-pin; one of
 #                         software|service|game|research|fleet, or the aliases A-E / app / agent
 #                         / desktop (desktop/F => software + --electron); anything else is refused
 #   --electron            the electron opt-in overlay over the software class (electron: true):
 #                         the app_bundle_bytes ratchet, BN-06..09 bans, the host-gate declaration
-#   --models <path>       model mapping file   (default: $GOBLIN_MODELS -> ~/projects/fleet-model.yaml)
-#   --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE -> ~/projects/PROJECT-PRACTICE.md); a named path that is absent is reported, never silently dropped
+#   --models <path>       model mapping file   (default: $GOBLIN_MODELS; unset = rendered as an
+#                         empty models_file: the repo's machine-specific input, never a path
+#                         from the machine the installer ran on)
+#   --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE; unset = empty
+#                         practice: pin — a named path that is absent is reported, never
+#                         silently dropped)
 #   --parts <list>        comma list to install; default = every part the class requires
 #   --archive             mark the project archive: verify requires no HANDOFF and no gates
 #   --skills yes|no       install agent skills under .hermes/skills (default no; opt in per
-#                         platform with: gob emit --platform <p>)
+#                         catalogue row with: gob extras install <id>)
 #   --dry-run             print the plan; write nothing
 #   --upgrade             re-install at the current version; report created/updated/unchanged/skipped
 #   --opt-out <part>      record the part in disabled: so its required checks are skipped
@@ -31,7 +35,7 @@
 
 set -uo pipefail
 
-GOBLIN_INSTALL_VERSION="0.6.0-alpha.3"
+GOBLIN_INSTALL_VERSION="0.6.0-alpha.4"
 SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 SRC=$(cd "$SELF_DIR/.." && pwd)
 # shellcheck source=goblin-lib.sh
@@ -39,8 +43,16 @@ SRC=$(cd "$SELF_DIR/.." && pwd)
 
 TARGET=""
 CLASS=""
-MODELS="${GOBLIN_MODELS:-$HOME/projects/fleet-model.yaml}"
-PRACTICE="${GOBLIN_PRACTICE:-$HOME/projects/PROJECT-PRACTICE.md}"
+# QA fix (v2-qa issue 4): the old defaults were $HOME/projects/fleet-model.yaml and
+# $HOME/projects/PROJECT-PRACTICE.md - the MAINTAINER's home layout baked into every
+# rendered config on every machine, including a fresh contributor's (their rendered
+# AGENTS.md pointed at a file that does not exist on their machine). The neutral default
+# is EMPTY: no --models / no GOBLIN_MODELS renders an empty models_file: line, and the
+# practice pin stays empty (verify already treats both as the legitimate no-mapping /
+# no-standard state). A machine that HAS a fleet mapping exports GOBLIN_MODELS (or
+# passes --models) and gets the same rendering as before.
+MODELS="${GOBLIN_MODELS:-}"
+PRACTICE="${GOBLIN_PRACTICE:-}"
 # W5-3: `--practice <path>` naming a file that is not there used to be IGNORED IN SILENCE -
 # exit 0, `practice: ~`, `practice_sha256: ~`, and not one line about it in the install log.
 # The empty pin is a legitimate state (a repo may reference no standard, and the default path is
@@ -220,6 +232,15 @@ if [ "$UNINSTALL" -eq 1 ]; then
       printf '.goblin\n.gob/bin\n.gob/manifest\n.gob/bans\n.hermes\n.hermes/skills\n'
     } | awk 'NF' | awk -F/ '{print NF " " $0}' | sort -rn | cut -d' ' -f2- | awk '!seen[$0]++')
   g_info "removed $n file(s) and $nd empty director(y|ies). Left in place: HANDOFF.md, AGENTS.md, ROUND-000-SPEC.md, reviews/, the .gitignore block${KEPT:+, and the decision record(s) you edited:$KEPT}."
+  # QA fix (v2-qa issue 10): honesty about what the uninstall leaves UNTOUCHED. Two
+  # by-design residues a reader could otherwise read as a clean sweep:
+  #   - the .gitignore block the install appended stays (removing it could eat a
+  #     line the project added inside the block; the preimage is untracked text),
+  #   - prose in kept files (HANDOFF.md, AGENTS.md body, SPECs) may still name
+  #     now-deleted paths (.gob/bin/goblin-verify, checks/) — those references are
+  #     dead after this command.
+  g_info "  note: the .gitignore ignore-rules block stays (by design: it may carry lines the project added; remove it by hand if you want it gone)"
+  g_info "  note: prose that names .gob/ paths (HANDOFF.md, AGENTS.md body, SPECs) now points at removed files — those references are dead"
   exit 0
 fi
 
@@ -852,7 +873,7 @@ if [ "$DRY_RUN" -eq 0 ]; then
   if [ "$SKILLS" = "yes" ]; then
     g_info "  4. hermes skills trust $TARGET   # one-time, so the project-tier skills load"
   else
-    g_info "  4. agent skills are opt-in: gob emit --platform <p>   # run gob doctor for the platform list"
+    g_info "  4. agent skills are opt-in: gob extras install <id...>   # gob extras list shows the catalogue"
   fi
   g_info ""
   g_info "automations (optional; neither writes outside this repo, and A-02 has no agent in it):"

package/bin/goblin-lib.sh

@@ -16,7 +16,7 @@
 #     - name: typecheck        four-space-indented second member of a list entry
 #       cmd: npx tsc --noEmit
 
-GOBLIN_LIB_VERSION="0.6.0-alpha.3"
+GOBLIN_LIB_VERSION="0.6.0-alpha.4"
 
 # ---------------------------------------------------------------- output -----
 # g_trunc <width> <text> — fold a long detail to one line at <width> columns, keeping the
@@ -31,6 +31,9 @@ g_trunc() {
 # <indent> (the cannot-see footer shape). Byte-safe: awk length on bytes approximates
 # columns for ASCII prose, which is all this text is.
 g_fold() {
+  # QA fix (v2-qa issue 9): the rest-assignment used to inline substr() as sub()'s third
+  # parameter — not a changeable lvalue, a hard error on gawk 5.2+ (the helper had never
+  # been exercised until the remedy fold called it). A temp variable is portable awk.
   awk -v w="$1" -v ind="$2" '
     {
       line = $0
@@ -39,10 +42,9 @@ g_fold() {
         while (cut > 1 && substr(line, cut, 1) != " ") cut--
         if (cut <= 1) cut = w
         print substr(line, 1, cut)
-        sub(/^[ ]+/, "", substr(line, cut + 1))
-        line = substr(line, cut + 1)
-        sub(/^[ ]+/, "", line)
-        line = ind line
+        rest = substr(line, cut + 1)
+        sub(/^[ ]+/, "", rest)
+        line = ind rest
       }
       print line
     }'
@@ -71,12 +73,16 @@ g_fail() {
   case "$rem" in
     —*) return 0 ;;   # an em-dash cell: history and blindness, never a remedy
   esac
-  # Whole in verbose/--only mode (the mode that reads, not scans), width-folded otherwise —
-  # the same contract the row printers keep.
-  if [ "${GOB_VERIFY_VERBOSE:-0}" -eq 1 ]; then
-    [ -n "$rem" ] && printf 'remedy: %s\n' "$rem"
-  else
-    [ -n "$rem" ] && printf 'remedy: %s\n' "$(g_trunc "${GOB_REPORT_COLS:-100}" "$rem")"
+  # QA fix (v2-qa issue 9): a remedy is an instruction, not a detail line — truncating it
+  # with a ~ cut the command the operator had to type (measured: 'git -c user.ema~').
+  # The remedy is now WORD-FOLDED to continuation lines at the report width in every
+  # mode (whole text either way); --verbose keeps the single-line form it always had.
+  if [ -n "$rem" ]; then
+    if [ "${GOB_VERIFY_VERBOSE:-0}" -eq 1 ]; then
+      printf 'remedy: %s\n' "$rem"
+    else
+      printf 'remedy: %s\n' "$rem" | g_fold "${GOB_REPORT_COLS:-100}" "        "
+    fi
   fi
 }
 g_remedy() {

package/bin/goblin-map

@@ -45,7 +45,7 @@
 #
 # Never-clobber contract:
 #   features/ absent (or empty of .md)  -> generate README + one file per slug, exit 0
-#   features/ already a map, no --force -> write NOTHING, name the path and --force, exit 1
+#   features/ already a map, no --force -> validate only; the index is kept (never rewritten)
 #   --force                             -> regenerate ONLY README.md (indexing every existing
 #                                          feature file too) and add files for NEW slugs;
 #                                          existing feature files are never touched, exit 0
@@ -129,8 +129,9 @@ Notes:
      human pass has actually driven the feature once.
    - entry_paths tokens must be repo-relative paths that EXIST, and should occur in
      source text (a route literal, an import) so FM-02 can grep for them.
-   - An existing map is never overwritten without --force (the index only); if a map
-     already exists, hand-pass the files instead of regenerating them.
+   - --write validates and never rewrites: your hand-written README index is KEPT
+     (pass --force only if you want the index REGENERATED from the feature files);
+     existing feature files are never touched either way.
 
 == FEATURE-FILE SCHEMA =========================================================
 
@@ -201,13 +202,15 @@ if [ -n "$WRITE_DIR" ]; then
   WDIR=$(cd "$WRITE_DIR" && pwd) || { g_err "cannot enter: $WRITE_DIR"; exit 2; }
   # A map, for --write purposes, is the README index: --write never writes feature
   # files (they are its INPUT), so the only thing it could clobber is the index.
+  # QA fix (v2-qa issue 5): an existing index used to be a refusal ("pass --force") —
+  # but the AGENT BRIEF itself tells the agent to WRITE features/README.md before
+  # running --write, so the first --write of the brief's own prescribed flow demanded
+  # the scary flag. The coherent contract: --write VALIDATES and never rewrites the
+  # index without --force; an existing index is the author's own output and is kept,
+  # named in the done line. (The never-clobber promise is unchanged: --write still
+  # writes NOTHING without --force — the refusal was protecting an empty write.)
   HAVE_WMAP=0
   if [ -f "$WDIR/README.md" ]; then HAVE_WMAP=1; fi
-  if [ "$HAVE_WMAP" -eq 1 ] && [ "$FORCE" -ne 1 ]; then
-    g_err "refusing to overwrite an existing feature map: $WDIR"
-    printf 'error: map: pass --force to regenerate the README index and add NEW files only; existing files are never rewritten\n' >&2
-    exit 1
-  fi
   # Validation: the frontmatter + H2 + verified contract, per file, fail closed.
   BAD=0; N=0
   for f in "$WDIR"/*.md; do
@@ -264,7 +267,10 @@ if [ -n "$WRITE_DIR" ]; then
     for f in "$WDIR"/*.md; do
       [ -f "$f" ] || continue
       slug=$(basename "$f"); slug=${slug%.md}
-      case "$slug" in README.md) continue ;; esac
+      # QA fix (v2-qa issue 6): $slug is the STEM (README, not README.md) — the old
+      # pattern compared README against README.md, never matched, and the regenerated
+      # index listed the index itself as a feature.
+      case "$slug" in README) continue ;; esac
       printf '%s\t%s\n' "$slug" "$(printf '%s' "${f#"$WDIR"/}" | sed 's#^#./#')" >> "$SLUGS_TSV"
     done
     TODAY=$(date +%F)
@@ -509,7 +515,9 @@ MID
       for f in "$FEAT"/*.md; do
         [ -f "$f" ] || continue
         slug=$(basename "$f"); slug=${slug%.md}
-        case "$slug" in README.md) continue ;; esac
+        # QA fix (v2-qa issue 6): stem comparison, same bug as the --write index loop —
+        # the slug is README after .md is stripped, so the old README.md pattern never fired.
+        case "$slug" in README) continue ;; esac
         awk -F'\t' -v s="$slug" '$1 == s { found=1 } END { exit !found }' "$SLUGS_TSV" && continue
         title=$(file_title "$f" "$slug")
         printf '%s\n' "- [${title}](./${slug}.md) covers TODO — existing feature file kept by --force (not re-described)"

package/bin/goblin-mcp.js

@@ -211,7 +211,29 @@ function remedyMap(root) {
 }
 
 function toolGobVerify(args) {
-  const root = process.cwd();
+  // QA fix (v2-qa issue 7): the tool honours an explicit `target` — an agent calling from
+  // an installed repo with a different repo named as target used to get the CWD's matrix
+  // with the bogus target silently dropped (wrong-repo-as-verified). Resolution rules:
+  //   - target absent/empty        -> process.cwd() (the documented default)
+  //   - target relative            -> resolved against process.cwd()
+  //   - resolved dir carries no .gob/engine and no AGENTS.md gob block -> REFUSAL (the
+  //     exact resolved path is named), never a silent fall-back to the CWD's matrix
+  // The result's first line names the verified path, so the agent sees WHICH repo was judged.
+  const cwd = process.cwd();
+  let root = cwd;
+  const target = args && typeof args.target === "string" ? args.target.trim() : "";
+  if (target) {
+    root = path.resolve(cwd, target);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      return errText("gob_verify: target is not a directory: " + root);
+    }
+    const blockText = readBlock(path.join(root, "AGENTS.md"));
+    if (!fs.existsSync(path.join(root, ".gob", "bin", "goblin-verify")) && !blockText) {
+      return errText(
+        "gob_verify: target is not a gobstack repo (no .gob/bin/goblin-verify, no AGENTS.md gob block): " + root
+      );
+    }
+  }
   const engine = path.join(root, ".gob", "bin", "goblin-verify");
   if (!fs.existsSync(engine)) {
     return errText(
@@ -235,7 +257,9 @@ function toolGobVerify(args) {
   const verdict = parsed.failed === 0 && r.status === 0 ? "PASS" : "FAIL";
   const lines = [];
   lines.push(
-    "gate: " + verdict + " — " + parsed.passed + " passed, " + parsed.failed + " failed, " +
+    // the resolved repo is named first: the consumer sees WHICH tree was judged
+    "verified: " + root +
+    "\ngate: " + verdict + " — " + parsed.passed + " passed, " + parsed.failed + " failed, " +
     parsed.advisory + " advisory, " + parsed.skipped + " skipped (exit " + r.status + ")"
   );
   for (const row of parsed.rows) {
@@ -358,7 +382,9 @@ const TOOLS = [
       type: "object",
       properties: {
         only: { type: "string", description: "optional comma-separated rule ids to run (e.g. FM-01,FM-02)" },
+        target: { type: "string", description: "optional repo root to verify (absolute, or relative to the CWD); defaults to the current working directory" },
       },
+      additionalProperties: false,
     },
   },
   {

package/bin/goblin-upgrade

@@ -30,7 +30,7 @@
 # `git revert` of this command's own two commits (W3-SPEC §5).
 set -uo pipefail
 
-GOBLIN_UPGRADE_VERSION="0.6.0-alpha.3"
+GOBLIN_UPGRADE_VERSION="0.6.0-alpha.4"
 
 usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
 

package/bin/goblin-verify

@@ -19,7 +19,7 @@
 
 set -uo pipefail
 
-GOBLIN_VERIFY_VERSION="0.6.0-alpha.3"
+GOBLIN_VERIFY_VERSION="0.6.0-alpha.4"
 SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=goblin-lib.sh
 . "$SELF_DIR/goblin-lib.sh"
@@ -276,9 +276,9 @@ if [ ! -f "$CONFIG" ]; then
   if [ "$ROOT" != "$PWD" ]; then
     g_err "not installed: $CONFIG is absent — and $PWD is not the installed repo ($ROOT)."
     g_err "fix: cd to your project repo, then re-run gob verify."
-    g_err "    (installing here would initialize $PWD: goblin-install --target $PWD --class <software|service|game|research|fleet>)"
+    g_err "    (installing here would initialize $PWD: npx @techgoblin/gobstack init)"
   else
-    g_err "not installed: $CONFIG is absent. Run: goblin-install --target $ROOT --class <software|service|game|research|fleet>"
+    g_err "not installed: $CONFIG is absent. Run: npx @techgoblin/gobstack init   # or: gob init, inside $ROOT"
   fi
   exit 2
 fi
@@ -484,7 +484,7 @@ check_in_01() {
   # IN-01 recovery line (review 1, scope 4): the record is corrupt or missing; name the two
   # restores. The matrix's remedy: line rides under the payload via g_fail.
   printf 'installed.json is absent or records no version\n'
-  printf 'recover: gob install --upgrade, or git checkout -- .gob/installed.json\n'
+  printf 'recover: git checkout -- .gob/installed.json, or re-run npx @techgoblin/gobstack init --write to re-install\n'
   return 1
 }
 
@@ -609,7 +609,7 @@ check_in_02() {
         # catch a SILENT edit, so re-pinning is a deliberate act: one explicit command, which
         # prints the old and new hash (docs/CONTRACTS.md, "An edited standard is not a dead end").
         printf '  if the edit is yours and intended, re-pin it deliberately:\n'
-        printf '    goblin-install --target %s --re-pin\n' "$ROOT"
+        printf '    goblin-install --target %s --re-pin   # from the gobstack checkout/install tree\n' "$ROOT"
         bad=1; pin=" | practice EDITED"
       else
         pin=" | practice pin ok"
@@ -626,7 +626,7 @@ check_in_02() {
   # naming the drifted file the payload above reported. Sits between the row's own lines and
   # the summary; g_fail appends the matrix's remedy: line under the whole payload.
   if [ "$bad" -ne 0 ] && [ -n "$DRIFTED" ]; then
-    printf 'recover: git checkout -- %s, or gob install --upgrade\n' "$DRIFTED"
+    printf 'recover: git checkout -- %s, or re-run npx @techgoblin/gobstack init --write to re-install\n' "$DRIFTED"
   fi
   [ "$bad" -eq 0 ]
 }

package/docs/CONTRACTS.md

@@ -13,12 +13,15 @@ same way the fleet's own tool reads it. Everything else is line-oriented shell.
                           software · service · game · research · fleet. The letters A-E and the
                           older names app (software), agent (fleet) and desktop/F (software + the
                           electron opt-in) are read-time aliases.
-    --models <path>       model mapping file   (default: $GOBLIN_MODELS -> ~/projects/fleet-model.yaml)
-    --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE -> ~/projects/PROJECT-PRACTICE.md)
+    --models <path>       model mapping file   (default: $GOBLIN_MODELS; unset = an empty
+                          models_file: the repo's machine-specific input, set per machine)
+    --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE; unset = no
+                          practice pin; a named path that is absent is reported, never
+                          silently dropped)
     --parts <list>        comma list to install; default = every part the class requires
     --archive             mark the project archive: verify requires no HANDOFF and no gates
     --skills yes|no       install agent skills under .hermes/skills (default no — the harness is
-                          neutral; opt in per platform with: gob emit --platform <p>). On a repo whose
+                          neutral; opt in per catalogue row with: gob extras install <id...>). On a repo whose
                           record already has skills installed, an OMITTED flag keeps them; an explicit
                           --skills no removes them.
     --dry-run             print the plan; write nothing

package/docs/ENFORCEMENT.md

@@ -31,7 +31,7 @@ Measured shape of this table: **87 rows** - 82 target, 5 source; advisory 10, ga
 | id | scope | enforced by | rule | check | if it cannot be enforced, why |
 |---|---|---|---|---|---|
 | `IN-01` | target | script | The install exists and records its version + every file's hash. | goblin-verify --only IN-01 | — (W1: the check is a builtin so the engine.mode=global clause can run — a global, declaration-only repo has no install record and SKIPs with `global engine mode — no per-repo install record`; the vendored clauses are the old one-liner: the record exists and names its version) |
-| `IN-02` | target | script | Every installed file still matches its recorded hash. | goblin-verify --only IN-02 | recover: gob install --upgrade, or git checkout -- .gob/installed.json; for a file it names drifted: git checkout -- <path> (if the edit is yours and intended, re-pin it: gob install --target <dir> --re-pin) |
+| `IN-02` | target | script | Every installed file still matches its recorded hash. | goblin-verify --only IN-02 | recover: git checkout -- .gob/installed.json (or re-run `npx @techgoblin/gobstack init --write` to re-install); for a file it names drifted: git checkout -- <path> (if the edit is yours and intended, re-pin it: `goblin-install --target <dir> --re-pin` from the checkout/install tree) |
 | `IN-03` | target | script | The verifier's own manifest is complete: every rule has a check or is advisory. | goblin-verify --only IN-03 | — (this row is the reason the matrix cannot rot; the second clause is D6's shape in general: a row that carries no check must be labelled advisory, or it claims verification it does not perform. The third clause is Z1-5: `enforced_by` is documented as a closed enum in docs/ENFORCEMENT.md and was read by NOTHING, so a typo in that cell changed nothing - `script\|lint\|gate\|advisory` plus `test`, the source-scope value whose check is tests/run-tests.sh. W1: the check runs against whichever manifest the engine actually resolved (the chain in bin/goblin-verify), no longer the hardcoded per-repo path — the rule's meaning is untouched, only the path input follows the engine) |
 | `IN-04` | target | script | No file goblin-stack did not create has been overwritten. | goblin-verify --only IN-04 | Detects a file the installer recorded as pre-existing (a `refused` entry) that has since vanished, or that is listed as installed anyway. The second clause is an internal-consistency guard: with correct code a refused path is never written, so it fires only if the installer regresses. The negative control exercises the vanished branch. |
 | `HP-01` | target | gate | HANDOFF.md exists at the root. | test -f HANDOFF.md | — |

package/docs/GUIDE.md

@@ -3,7 +3,7 @@
 A step-by-step guide for your first week. **Read this before the README.** The README tells you
 what the pieces are; this tells you what to *do*, in order, and what you should see when it works.
 
-Version: `0.6.0-alpha.2` · Last measured: 2026-10-09 · Every command and every output below was run on a
+Version: `0.6.0-alpha.4` · Last measured: 2026-10-09 · Every command and every output below was run on a
 real repository while writing this guide.
 
 ---
@@ -267,7 +267,8 @@ Open it. The keys that matter on day one:
     branch: main                          # DECLARED, never assumed
     owner_email: you@example.com          # the commit identity this repo expects
     practice: /path/to/your-standard.md   # optional: your own house rules, hash-pinned
-    models_file: /path/to/fleet-model.yaml # the ONE machine-specific input
+    models_file: /path/to/fleet-model.yaml # the ONE machine-specific input (per machine; a
+                                           # fresh install without --models leaves it empty)
     gate_<name>_cmd: <one command>        # YOUR real commands, one line each
 
 **The single most valuable edit you will make:** replace the gate line(s) with the commands you
@@ -290,7 +291,7 @@ repos follow an old version.
 
 When *you* legitimately edit your own standard:
 
-    gob install --target . --re-pin
+    goblin-install --target . --re-pin   # from the gobstack checkout / install tree
 
 It re-records the hash and prints the old and new value. Nothing re-pins automatically — not even
 a re-install — an edited standard is never a silent no-op.
@@ -528,8 +529,8 @@ same commands are available outside any repo through the npm CLI: `gob init` / `
 
     .gob/bin/goblin-verify [--only <id[,id...]>] [--json] [--list]
     .gob/bin/goblin-bans           # run the ban list
-    gob install --target <dir> --uninstall   # the uninstall job
-    gob install --target <dir> --re-pin      # the deliberate re-pin
+    gob uninstall --target <dir>             # the uninstall job
+    goblin-install --target <dir> --re-pin   # the deliberate re-pin (from the checkout/install tree)
     bin/goblin-model <role>        # checkout-only; resolve a role to a profile (docs/ROLES.md)
 
 ### Register the harness with your agent (MCP)

package/manifest/enforcement.tsv

@@ -1,6 +1,6 @@
 id	scope	rule	enforced_by	artifact	check	if_not_why
 IN-01	target	The install exists and records its version + every file's hash.	script	.gob/installed.json	goblin-verify --only IN-01	— (W1: the check is a builtin so the engine.mode=global clause can run — a global, declaration-only repo has no install record and SKIPs with `global engine mode — no per-repo install record`; the vendored clauses are the old one-liner: the record exists and names its version)
-IN-02	target	Every installed file still matches its recorded hash.	script	.gob/installed.json	goblin-verify --only IN-02	recover: gob install --upgrade, or git checkout -- .gob/installed.json; for a file it names drifted: git checkout -- <path> (if the edit is yours and intended, re-pin it: gob install --target <dir> --re-pin)
+IN-02	target	Every installed file still matches its recorded hash.	script	.gob/installed.json	goblin-verify --only IN-02	recover: git checkout -- .gob/installed.json (or re-run npx @techgoblin/gobstack init --write to re-install); for a file it names drifted: git checkout -- <path> (if the edit is yours and intended, re-pin it: goblin-install --target <dir> --re-pin from the checkout/install tree)
 IN-03	target	The verifier's own manifest is complete: every rule has a check or is advisory.	script	manifest/enforcement.tsv	goblin-verify --only IN-03	— (this row is the reason the matrix cannot rot; the second clause is D6's shape in general: a row that carries no check must be labelled advisory, or it claims verification it does not perform. The third clause is Z1-5: `enforced_by` is documented as a closed enum in docs/ENFORCEMENT.md and was read by NOTHING, so a typo in that cell changed nothing - `script|lint|gate|advisory` plus `test`, the source-scope value whose check is tests/run-tests.sh. W1: the check runs against whichever manifest the engine actually resolved (the chain in bin/goblin-verify), no longer the hardcoded per-repo path — the rule's meaning is untouched, only the path input follows the engine)
 IN-04	target	No file goblin-stack did not create has been overwritten.	script	.gob/installed.json	goblin-verify --only IN-04	Detects a file the installer recorded as pre-existing (a `refused` entry) that has since vanished, or that is listed as installed anyway. The second clause is an internal-consistency guard: with correct code a refused path is never written, so it fires only if the installer regresses. The negative control exercises the vanished branch.
 HP-01	target	HANDOFF.md exists at the root.	gate	HANDOFF.md	test -f HANDOFF.md	—

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techgoblin/gobstack",
-  "version": "0.6.0-alpha.3",
+  "version": "0.6.0-alpha.4",
   "description": "Agent-discipline toolkit: one verify command, an enforcement matrix, and LIMITS. bash engine, npm shim.",
   "bin": {
     "goblin": "bin/goblin.js",

package/skills/goblin-bootstrap/SKILL.md

@@ -13,7 +13,7 @@ Use when adopting goblin-stack in a repo, or starting one.
    with the electron bans and a host gate, not a sixth class. The letters `A`-`E` and the older
    names are read-time aliases.
 2. **`goblin-install --target <dir> --class <x>`** — the default install is a NEUTRAL harness:
-   no agent skills. Opt in per platform afterwards with `gob emit --platform <p>` (or vendor the
+   no agent skills. Opt in per catalogue row afterwards with `gob extras install <id>` (or vendor the
    Hermes project tier with `--skills yes`).
 3. **`goblin-verify`** — a default software-class install (no agent skills) verifies green:
    `37 passed, 0 failed, 11 advisory, 34 skipped`, exit 0, once `HANDOFF.md` names a commit that