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

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.5.0"
+GOBLIN_LIB_VERSION="0.6.0-alpha.1"
 
 # ---------------------------------------------------------------- output -----
 # g_trunc <width> <text> — fold a long detail to one line at <width> columns, keeping the
@@ -265,6 +265,168 @@ g_part_disabled() {
 }
 
 # ------------------------------------------------------------- class data ----
+# ------------------------------------------------------------- agents.md -----
+# v2 config engine: the project config lives in AGENTS.md FRONTMATTER, delimited by
+# fixed markers. There is no goblin.yaml. One file is the single source of truth:
+#
+#   <!-- gob:begin (gobstack config) -->
+#   class: software
+#   branch: main
+#   ratchet.ceiling: 160          # one nested level = a dotted key
+#   bans: [BN-01, BN-02]          # a list is a one-line JSON-ish array
+#   gate_commit_cmd: git rev-parse --verify --quiet HEAD
+#   <!-- gob:end -->
+#
+# The parser is the same flat, line-oriented reader the yaml subset used (no YAML
+# library, no network, no npm) — it just reads ONLY the lines between the markers, so
+# the rest of AGENTS.md (the prose the agent reads) is invisible to it. Rules:
+#   * a value is the rest of the line after `key:` — never quoted, never folded
+#   * one nested level: `block.key: value` (read with the dotted spelling)
+#   * a list: `key: [a, b, c]` on ONE line (g_agents_list splits it)
+#   * gates: one key per gate, `gate_<name>_cmd: <cmd>` (g_agents_gates)
+#   * comments on their own line, `#` first; blank lines allowed
+
+# The literal markers (grep -F targets; the begin marker carries no closing paren so a
+# future annotation after it cannot break the reader).
+GOB_AGENTS_BEGIN='<!-- gob:begin'
+GOB_AGENTS_END='<!-- gob:end -->'
+
+# g_agents_block <file> — the config lines between the markers (empty if no block).
+g_agents_block() {
+  sed -n "/^$GOB_AGENTS_BEGIN/,/^$GOB_AGENTS_END/p" "$1" 2>/dev/null | sed '1d;$d'
+}
+
+# g_agents_read <file> <key> — value of one key (dotted spelling for the nested level),
+# empty if the block or the key is absent.
+g_agents_read() {
+  g_agents_block "$1" | sed -n "s/^$2:[[:space:]]*//p" | head -n 1
+}
+
+# g_agents_keys <file> — every declared key, one per line, in file order.
+g_agents_keys() {
+  g_agents_block "$1" | sed -n 's/^\([A-Za-z_][A-Za-z0-9_.-]*\):.*/\1/p'
+}
+
+# g_agents_gates <file> — one "name<TAB>cmd" line per DECLARED gate. A gate is the key
+# `gate_<name>_cmd:`; the declaration and its command are one line, so a gate cannot
+# lose its cmd and survive the count (the G8-3 failure mode has no shape here).
+g_agents_gates() {
+  g_agents_block "$1" | sed -n 's/^gate_\([A-Za-z0-9_-]*\)_cmd:[[:space:]]*/\1\t/p'
+}
+
+# g_agents_gate_names <file> — one declared gate NAME per line.
+g_agents_gate_names() {
+  g_agents_gates "$1" | cut -f1
+}
+
+# g_agents_pairs <file> — every block line as `key<TAB>value`, file order. The round-trip
+# reader: `g_agents_pairs | g_agents_write` rewrites a block byte-identically, including
+# values that contain tabs (a keys+read loop through g_agents_read mangles those — the
+# sed in the reader stops at the first colon and the value is rebuilt, so a raw tab inside
+# a gate command lost its place and the line drifted on every re-write). Use this for any
+# read-modify-write of the block; g_agents_keys is for membership tests only.
+# A VALUE-LESS line is stored "key:" (no trailing space — the writer strips it), so the
+# ": "-split regex cannot fire: without the key fix below, k kept the trailing colon and
+# the pair read back "key:<TAB>key:" - on the next rewrite that rendered "key:: key:"
+# and every later read of the key returned its own name (IN-02/PF-01/FM-01 reds on a
+# fresh install that declares no practice/feature_map/measured).
+g_agents_pairs() {
+  # Split at the FIRST ": " (or a trailing bare ":" for a value-less line): index()
+  # drives the branch because the ": "-regex cannot fire on the stored "key:" form and
+  # a blind sub left k carrying its colon, so pairs read back "key:<TAB>key:".
+  g_agents_block "$1" | awk '{
+    p = index($0, ": ")
+    if (p > 0) { k = substr($0, 1, p - 1); v = substr($0, p + 2) }
+    else if ($0 ~ /:$/) { k = substr($0, 1, length($0) - 1); v = "" }
+    else { k = $0; v = "" }
+    printf "%s\t%s\n", k, v
+  }'
+}
+
+# g_agents_list <file> <key> — the items of a one-line `[a, b, c]` array, one per line.
+# Empty output = the key is absent or the array is empty. An item keeps its inner text
+# verbatim (trimmed); a comma inside an item cannot be expressed — split the key.
+g_agents_list() {
+  local v
+  v=$(g_agents_read "$1" "$2")
+  case "$v" in
+    ""|"[]") return 0 ;;
+    \[*\]) ;;
+    *) return 0 ;;   # a malformed array reads as absent, never as one garbage item
+  esac
+  v=${v#\[}; v=${v%\]}
+  printf '%s\n' "$v" | tr ',' '\n' \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | grep -v '^$' || true
+}
+
+# g_agents_disabled <file> — the disabled: array, one part per line.
+g_agents_disabled() { g_agents_list "$1" disabled; }
+
+# g_part_disabled <agents-file> <part>
+g_agents_part_disabled() {
+  g_agents_disabled "$1" | grep -qx "$2"
+}
+
+# g_agents_write <file> — rewrite ONLY the marker block from `key<TAB>value` lines on
+# stdin, preserving every line of the body. Idempotent: a second identical write leaves
+# the file byte-identical (it prints "unchanged", not "written"). No block + a body:
+# the block is inserted before the first line. No file: it is created.
+g_agents_write() {
+  local f="$1" tmp newbody
+  [ -f "$f" ] || : > "$f"
+  tmp=$(mktemp "${TMPDIR:-/tmp}/gob-agents.XXXXXX") || return 1
+  {
+    printf '%s (gobstack config — edit in place; the parser reads only this block) -->\n' "$GOB_AGENTS_BEGIN"
+    # A marker line on stdin is a RENDERED TEMPLATE's own first line, not a key: skip
+    # it, so a caller may pipe a whole rendered block in. A line is EITHER "key<TAB>
+    # value" (the tsv form) OR already-rendered "key: value" (a template form): with a
+    # tab, field 1 is the key and the value is rebuilt; without one, the line's own
+    # "key: value" shape is kept verbatim (a rendered placeholder keeps its text).
+    # A RENDERED line whose VALUE contains a tab would otherwise split at the value's
+    # own tab and corrupt it on the next rewrite ("a<TAB>b" became "a: b"), so a line
+    # whose pre-tab part already carries ": " is a rendered line: kept verbatim. A tsv
+    # key is a bare identifier and never contains ": ".
+    awk -F'\t' '
+      /^<!-- gob:(begin|end)/ { next }
+      NF >= 2 {
+        if ($1 ~ /: /) { print; next }
+        v = $2; for (i = 3; i <= NF; i++) v = v "\t" $i
+        sub(/ -->$/, "", v)   # a template end-marker glued to a value line
+        print $1 ": " v
+        next
+      }
+      NF == 1 && $1 != "" { print $1 }' \
+      | sed 's/: $/:/'
+    printf '%s\n' "$GOB_AGENTS_END"
+  } > "$tmp"
+  newbody=$(cat "$tmp")
+  # Replace the existing block, or insert the block before the first body line.
+  # All three values travel via ENVIRON, never -v: gawk (and mawk) process backslash
+  # escapes in -v assignment values (\b in a gate command became a backspace on every
+  # rewrite - through BOTH this splice and the render above it). ENVIRON passes the
+  # bytes raw with no escape processing on any awk.
+  if grep -q "^$GOB_AGENTS_BEGIN" "$f"; then
+    GOB_BLOCK="$newbody" GOB_BEGIN="$GOB_AGENTS_BEGIN" GOB_END="$GOB_AGENTS_END" \
+      awk '
+      BEGIN {
+        begin = "^" ENVIRON["GOB_BEGIN"]
+        end   = "^" ENVIRON["GOB_END"]
+        repl  = ENVIRON["GOB_BLOCK"]
+      }
+      $0 ~ begin { inb = 1; print repl; next }
+      $0 ~ end   { inb = 0; next }
+      !inb       { print }
+    ' "$f" > "$tmp.out" || { rm -f "$tmp" "$tmp.out"; return 1; }
+  else
+    { printf '%s\n' "$newbody"; cat "$f"; } > "$tmp.out"
+  fi
+  if cmp -s "$tmp.out" "$f"; then
+    rm -f "$tmp" "$tmp.out"; printf 'unchanged\n'; return 0
+  fi
+  cp "$tmp.out" "$f" && rm -f "$tmp" "$tmp.out" && { printf 'written\n'; return 0; }
+  rm -f "$tmp" "$tmp.out"; return 1
+}
+
 # g_class_canon <spelling> -> the canonical class NAME
 #   software | service | game | research | fleet
 # The taxonomy is five domain-named classes. The letters A-E and the older taught domain names
@@ -422,6 +584,77 @@ YAML
   got=$(g_yaml_disabled "$tmp/g.yaml" | tr '\n' ',')
   [ "$got" = "spec,tokens," ] || { g_err "disabled: got '$got'"; rc=1; }
 
+  # ---- the v2 AGENTS.md frontmatter engine (the same RED control, new file) ----
+  cat > "$tmp/AGENTS.md" <<'EOF'
+# AGENTS.md
+
+House rules the agent reads. The block below is machine-read.
+
+<!-- gob:begin (gobstack config — edit in place; the parser reads only this block) -->
+class: software
+branch: main
+archive: false
+owner_email: team@example.com
+disabled: [spec, tokens]
+ratchet.name: hex
+ratchet.ceiling: 160
+gate_typecheck_cmd: npx tsc --noEmit
+gate_commit_cmd: git rev-parse --verify --quiet HEAD
+<!-- gob:end -->
+
+Body prose continues here. A line like `class: decoy` outside the block must stay
+invisible to the parser.
+EOF
+  printf 'class: decoy\n' >> "$tmp/AGENTS.md"
+  got=$(g_agents_read "$tmp/AGENTS.md" class)
+  [ "$got" = "software" ] || { g_err "agents scalar: expected software, got '$got'"; rc=1; }
+  got=$(g_agents_read "$tmp/AGENTS.md" nosuchkey)
+  [ -z "$got" ] || { g_err "agents scalar: absent key should be empty, got '$got'"; rc=1; }
+  got=$(g_agents_read "$tmp/AGENTS.md" ratchet.ceiling)
+  [ "$got" = "160" ] || { g_err "agents dotted key: expected 160, got '$got'"; rc=1; }
+  got=$(g_agents_read "$tmp/AGENTS.md" ratchet.name)
+  [ "$got" = "hex" ] || { g_err "agents dotted key: expected hex, got '$got'"; rc=1; }
+  got=$(g_agents_gates "$tmp/AGENTS.md" | tr '\t' ':')
+  [ "$got" = "typecheck:npx tsc --noEmit
+commit:git rev-parse --verify --quiet HEAD" ] \
+    || { g_err "agents gates: got '$got'"; rc=1; }
+  got=$(g_agents_gate_names "$tmp/AGENTS.md" | tr '\n' ',')
+  [ "$got" = "typecheck,commit," ] || { g_err "agents gate-names: got '$got'"; rc=1; }
+  got=$(g_agents_list "$tmp/AGENTS.md" disabled | tr '\n' ',')
+  [ "$got" = "spec,tokens," ] || { g_err "agents list: got '$got'"; rc=1; }
+  got=$(g_agents_keys "$tmp/AGENTS.md" | head -n 1)
+  [ "$got" = "class" ] || { g_err "agents keys: got '$got'"; rc=1; }
+  # g_agents_write: stdin IS the whole new block (key<TAB>value lines); it rewrites
+  # ONLY the block and preserves the body. Idempotent on a second identical write.
+  {
+    printf '%s\tsoftware\n' class
+    printf '%s\tmain\n' branch
+    printf '%s\t42\n' max_dirty
+  } | g_agents_write "$tmp/AGENTS.md" >/dev/null
+  grep -q '^max_dirty: 42$' "$tmp/AGENTS.md" || { g_err "agents write: the new key is absent"; rc=1; }
+  grep -qF 'Body prose continues here' "$tmp/AGENTS.md" \
+    || { g_err "agents write: the body was not preserved"; rc=1; }
+  grep -qF 'class: decoy' "$tmp/AGENTS.md" \
+    || { g_err "agents write: the body below the block was not preserved"; rc=1; }
+  W1=$(g_agents_read "$tmp/AGENTS.md" class)
+  [ "$W1" = "software" ] || { g_err "agents write: the block was destroyed ($W1)"; rc=1; }
+  {
+    printf '%s\tsoftware\n' class
+    printf '%s\tmain\n' branch
+    printf '%s\t42\n' max_dirty
+  } | g_agents_write "$tmp/AGENTS.md" > "$tmp/w2"
+  grep -q unchanged "$tmp/w2" || { g_err "agents write: the second identical write is not a no-op"; rc=1; }
+  # A fresh file: the block is created, and a body-less write stays parseable.
+  printf '%s\ttrue\n' "electron" | g_agents_write "$tmp/fresh.md" >/dev/null
+  [ "$(g_agents_read "$tmp/fresh.md" electron)" = "true" ] \
+    || { g_err "agents write: a fresh file was not created parseable"; rc=1; }
+  # A body-only file: the block is inserted before the first line.
+  printf 'the body\n' > "$tmp/bodyonly.md"
+  printf '%s\tmain\n' "branch" | g_agents_write "$tmp/bodyonly.md" >/dev/null
+  [ "$(g_agents_read "$tmp/bodyonly.md" branch)" = "main" ] \
+    && grep -qx 'the body' "$tmp/bodyonly.md" \
+    || { g_err "agents write: insertion into a body-only file failed"; rc=1; }
+
   rm -rf "$tmp"
   if [ "$rc" -eq 0 ]; then
     printf 'OK\n'

package/bin/goblin-map

@@ -1,13 +1,36 @@
 #!/usr/bin/env bash
-# goblin-map — `gob map`: generate a STARTER feature map for this repo (standalone).
+# goblin-map — `gob map`: the AI-DRIVEN feature map (v2 prompt engine) + the heuristic starter.
 #
-#   gob map [target] [--force] [--target <dir>] [--help]
+#   gob map                                  print the AGENT BRIEF + feature-file schema
+#   gob map --heuristic [target] [--force]   run the starter scanner (the fallback)
+#   gob map --write <dir> [--force]          validate the agent-written map and install it
+#   gob map [target] --force                 shorthand: heuristic --force (kept for scripts)
 #
-# Standalone by design (product decision, 2026-10): works in ANY git repo with NO .goblin/
-# install and NEVER reads goblin.yaml. The verify rows FM-01/FM-02 stay opt-in through a
-# `feature_map:` declaration in .goblin/goblin.yaml (empty = SKIP — unchanged); this command
-# only writes the starter files the human pass then edits. See docs/GUIDE.md, the feature-map
-# section, and skills/goblin-feature-map/SKILL.md (the format contract this output follows).
+# v2 SURFACE (AI-driven development): a bare `gob map` prints:
+#   1. the AGENT BRIEF — a structured prompt telling whichever agent is already running in
+#      this repo exactly what to inventory (routes, entry points, user-visible features)
+#      and how to justify each entry;
+#   2. the SCHEMA of the feature files it must write under a directory it chooses (for
+#      example features/) — the same frontmatter + four-H2 contract the heuristic starter
+#      renders and FM-01/FM-02 verify.
+# The agent writes the files with its own tools, then (or a human does) runs
+# `gob map --write <dir>` to validate: every file carries the frontmatter block, >=1
+# entry_paths, the four H2s in order, and a `verified:` line that is either a date or the
+# never-driven form. Exit 0 validated | 2 bad input (the named file + the fix).
+#
+# NEVER-CLOBBER (both modes, mirror of the heuristic contract):
+#   --write into a dir that is already a map WITHOUT --force -> refusal, exit 1, nothing
+#   written, the path and the remedy named;
+#   --write --force -> regenerate ONLY the README index (indexing every existing feature
+#   file too) and ADD files for new slugs; hand-written feature files are never touched.
+#
+# The heuristic detector (package.json scripts + route tokens) is the --heuristic
+# FALLBACK: a starter skeleton, never the answer. Its never-clobber rules are unchanged.
+#
+# Standalone by design: works in ANY git repo with NO .gob/ install and NEVER reads the
+# AGENTS.md gob block. The verify rows FM-01/FM-02 stay opt-in through a `feature_map:`
+# declaration in AGENTS.md frontmatter (empty = SKIP — unchanged). See docs/GUIDE.md, the
+# feature-map section, and skills/goblin-feature-map/SKILL.md (the format contract).
 #
 # What it scans (best-effort, honest about being a STARTER):
 #   next-app      app/**/page.tsx|page.jsx|route.ts  -> one feature per top-level route segment
@@ -49,32 +72,108 @@ g_err() { printf 'error: map: %s\n' "$*" >&2; }
 
 usage() {
   cat <<'USAGE'
-gob map — generate a starter feature map for this repo (standalone; no install needed).
+gob map — the AI-driven feature map (prompt + schema), with a heuristic starter fallback.
 
-  gob map [target] [--force]
+  gob map                          print the AGENT BRIEF + the feature-file schema
+  gob map --write <dir> [--force]  validate the agent-written map in <dir>
+  gob map --heuristic [target] [--force]
+                                   run the starter scanner (the fallback)
+  gob map [target] --force         shorthand for the heuristic --force path
 
-  target       the repo to scan (default: the current directory)
-  --force      when features/ already exists: regenerate ONLY the README index and add
-               files for NEW slugs; existing feature files are never touched
+The brief tells the agent already running in this repo what to inventory (routes, entry
+points, user-visible features) and the schema its feature files must follow (frontmatter,
+>=1 entry_paths, the four H2 sections, verified: date-or-never-driven). The agent writes
+the files with its own tools; `gob map --write <dir>` validates them.
 
-Detection: Next.js app router (app/**/page.tsx|jsx|route.ts), Next.js pages router
-(pages/**/*.tsx|jsx), Nuxt (pages/**/*.vue), route files (routes/ dirs, *route* files),
-or — with no framework — top-level src/ and lib/ module dirs as TODO placeholders.
-package.json dev/build/test/lint scripts seed the Baseline preconditions section.
+NEVER-CLOBBER: --write (or the heuristic path) into a dir that is already a map without
+--force is a refusal — the path and the remedy are named, nothing is written. --force
+regenerates ONLY the README index and adds NEW files; existing feature files are never
+touched.
 
-The output is a STARTER: each feature file needs a human pass before its verified: date
-means anything. It never reads or writes .goblin/, and FM-01/FM-02 stay opt-in through a
-feature_map: declaration in goblin.yaml.
+Standalone: no .gob/ install needed, none created; FM-01/FM-02 stay opt-in through a
+feature_map: declaration in the AGENTS.md gob block.
 
-Exit codes: 0 generated or nothing-to-do | 1 refusal (existing map, no --force) | 2 bad input.
+Exit codes: 0 generated/validated/nothing-to-do | 1 refusal (existing map, no --force) |
+2 bad input.
 USAGE
 }
 
+# ------------------------------------------------------------- the brief ------
+# `gob map` with no --write and no --heuristic: print the prompt + schema.
+print_brief() {
+  cat <<'BRIEF'
+
+== gob map — AGENT BRIEF =======================================================
+
+You are the agent running inside this repository. gobstack is an AI-driven-development
+harness: the CLI does not scan this repo — YOU do, with your own tools, and you write the
+feature map directly. Do this now:
+
+1. INVENTORY the repository:
+   - routes and entry points (app/ or pages/ trees, routes/ dirs, *route* files)
+   - the user-visible features behind them (what a user can DO, not what a file contains)
+   - the test/harness layout, so each feature names how it is driven
+
+2. WRITE the map under a directory you choose (the convention is features/):
+   - features/README.md — the index: baseline preconditions (launch/seed/health-check
+     commands), driving conventions, proof and skip reporting, one line per feature
+   - one features/<slug>.md per feature (slug: lowercase [a-z0-9-]), exactly in the
+     SCHEMA below
+
+3. VALIDATE what you wrote:
+
+       npx @techgoblin/gobstack map --write features/
+
+Notes:
+   - `verified:` is NOT a drive claim: write `never-driven (generated <date>)` until a
+     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.
+
+== FEATURE-FILE SCHEMA =========================================================
+
+---
+feature: <slug — lowercase [a-z0-9-], equals the filename stem>
+entry_paths:
+  - <repo-relative path that exists, one or more>
+verified: never-driven (generated <today>)
+---
+
+# <slug>
+
+<one paragraph of user-visible behaviour, no implementation detail>
+
+## Sub-features
+
+- <the sub-behaviours, one `<id>` per line>
+
+## How to get to it (user POV)
+
+- <how a user reaches this feature, and what they should see>
+
+## Driving it with <harness>
+
+Preconditions: <what must be true first>.
+**<action>.** Run `<exact command>`. <the observable result.>
+
+## Gotchas
+
+- <what commonly breaks, or what the entry-path token does and does not prove>
+============================================================================== =
+BRIEF
+}
+
 # ----------------------------------------------------------------- input ----
-TARGET="" FORCE=0
+TARGET="" FORCE=0 AGENT=0 HEURISTIC=0 WRITE_DIR=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --force)  FORCE=1; shift ;;
+    --agent)  AGENT=1; shift ;;
+    --heuristic) HEURISTIC=1; shift ;;
+    --write)  [ -n "$WRITE_DIR" ] && { g_err "write-dir given twice"; exit 2; }
+              WRITE_DIR="${2:-}"; shift 2 ;;
     --target) [ -z "$TARGET" ] || { g_err "target given twice"; exit 2; }
               TARGET="${2:-}"; shift 2 ;;
     -h|--help) usage; exit 0 ;;
@@ -84,6 +183,112 @@ while [ $# -gt 0 ]; do
               else g_err "unexpected argument: $1"; exit 2; fi ;;
   esac
 done
+
+# ------------------------------------------------------------ mode split ------
+# Bare invocation (no --write, no --heuristic): the agent brief. This IS the product.
+# `--agent` is the explicit spelling of the same thing; a --write suppresses it.
+if [ "$HEURISTIC" -eq 0 ] && [ -z "$WRITE_DIR" ]; then
+  print_brief
+  printf '%s\n' "== end of brief — the agent writes the map; gob map --write <dir> validates it =="
+  exit 0
+fi
+
+# --write <dir>: validate the agent-written map. Needs --force semantics from the
+# never-clobber contract; --heuristic and --write are separate modes, never both.
+if [ -n "$WRITE_DIR" ]; then
+  [ "$HEURISTIC" -eq 0 ] || { g_err "--write and --heuristic are separate modes"; exit 2; }
+  [ -d "$WRITE_DIR" ] || { g_err "--write dir does not exist (the agent creates it): $WRITE_DIR"; exit 2; }
+  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.
+  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
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md) continue ;; esac
+    N=$((N + 1))
+    slug=$(basename "$f"); slug=${slug%.md}
+    # frontmatter block present
+    sed -n '1,2p' "$f" | grep -q '^---[[:space:]]*$' \
+      || { g_err "$f: no frontmatter block (must start: ---)"; BAD=1; continue; }
+    fm=$(awk 'BEGIN{fm=0} /^---[[:space:]]*$/ {fm++; if (fm==1) next; else exit} fm==1 {print}' "$f")
+    printf '%s\n' "$fm" | grep -q "^feature:[[:space:]]*$slug[[:space:]]*$" \
+      || { g_err "$f: feature: must equal the filename stem ($slug)"; BAD=1; }
+    printf '%s\n' "$fm" | awk '/^entry_paths:/{f=1;next} f&&/^  - /{found=1} END{exit !found}' \
+      || { g_err "$f: entry_paths: carries no item (>=1 existing repo-relative path)"; BAD=1; }
+    # every entry path exists under the CWD (repo-relative) and is a single token
+    while IFS= read -r tok; do
+      [ -n "$tok" ] || continue
+      case "$tok" in *" "*) g_err "$f: entry path with whitespace: $tok"; BAD=1; continue ;; esac
+      [ -e "$tok" ] || { g_err "$f: entry path does not exist: $tok"; BAD=1; }
+    done < <(printf '%s\n' "$fm" | awk '/^entry_paths:/{f=1;next} f&&/^  - /{sub(/^  - /,"");print;next} f&&!/^[[:space:]]/{f=0}')
+    v=$(printf '%s\n' "$fm" | sed -n 's/^verified:[[:space:]]*//p')
+    case "$v" in
+      ""|"")
+        g_err "$f: no verified: line"; BAD=1 ;;
+      "never-driven"*)
+        : ;;
+      *) # a date, or anything else is refused — the line is either a date or never-driven
+        case "$v" in [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) : ;; *)
+          g_err "$f: verified: must be a date or the never-driven form (got: $v)"; BAD=1 ;;
+        esac ;;
+    esac
+    # the four H2s, in order
+    hn=0; hok=1
+    while IFS= read -r line; do
+      hn=$((hn + 1))
+      case "$hn" in
+        1) [ "$line" = "Sub-features" ] || hok=0 ;;
+        2) [ "$line" = "How to get to it (user POV)" ] || hok=0 ;;
+        3) case "$line" in "Driving it with "*) ;; *) hok=0 ;; esac ;;
+        4) [ "$line" = "Gotchas" ] || hok=0 ;;
+        *) hok=0 ;;
+      esac
+    done < <(grep -n '^## ' "$f" | sed 's/^[0-9]*:## //; s/[[:space:]]*$//')
+    [ "$hn" -eq 4 ] && [ "$hok" -eq 1 ] || { g_err "$f: the four H2 sections are missing or out of order (Sub-features / How to get to it (user POV) / Driving it with <harness> / Gotchas)"; BAD=1; }
+  done
+  [ "$N" -ge 1 ] || { g_err "$WDIR carries no feature file (only README.md) — the map is the features"; exit 2; }
+  [ "$BAD" -eq 0 ] || { g_err "validation failed — fix the named file(s) and re-run"; exit 2; }
+  # --write --force: regenerate ONLY the README index (every existing feature file is
+  # listed; the files themselves are never touched). Without --force, the index is
+  # untouched.
+  if [ "$FORCE" -eq 1 ]; then
+    SLUGS_TSV="$WDIR/.wmap.tsv"; : > "$SLUGS_TSV"
+    for f in "$WDIR"/*.md; do
+      [ -f "$f" ] || continue
+      slug=$(basename "$f"); slug=${slug%.md}
+      case "$slug" in README.md) continue ;; esac
+      printf '%s\t%s\n' "$slug" "$(printf '%s' "${f#"$WDIR"/}" | sed 's#^#./#')" >> "$SLUGS_TSV"
+    done
+    TODAY=$(date +%F)
+    {
+      printf '%s\n' '# Features'
+      printf '%s\n' ''
+      printf '%s\n' "regenerated by gob map --write ${TODAY} — the index only; every feature file was written by hand (or by an agent) and is never touched by --write."
+      printf '%s\n' ''
+      printf '%s\n' '## Features'
+      printf '%s\n' ''
+      while IFS= read -r row; do
+        [ -n "$row" ] || continue
+        slug=${row%%	*}
+        printf '%s\n' "- [${slug}](./${slug}.md) — entry listed in the file's frontmatter"
+      done < "$SLUGS_TSV"
+    } > "$WDIR/README.md"
+    rm -f "$SLUGS_TSV"
+    printf 'map --write: validated %d feature file(s) in %s and regenerated the README index (feature files untouched; declare feature_map: in AGENTS.md to opt FM-01/FM-02 in)\n' "$N" "$WDIR"
+  else
+    printf 'map --write: validated %d feature file(s) in %s (index untouched; declare feature_map: in AGENTS.md to opt FM-01/FM-02 in)\n' "$N" "$WDIR"
+  fi
+  exit 0
+fi
+
 [ -n "$TARGET" ] || TARGET="$PWD"
 [ -d "$TARGET" ] || { g_err "not a directory: $TARGET"; exit 2; }
 T=$(cd "$TARGET" && pwd) || { g_err "cannot enter: $TARGET"; exit 2; }