@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/pi/references/verify-state.md

@@ -0,0 +1,98 @@
+# `verify-state` — deterministic upstream-verification classification
+
+`forge-4-backlog`, `forge-5-loop` and `forge-6-docs` each open by reading a served
+stage's `stages.forge-verify-*` entry to answer one question — *has the upstream
+artifact been verified, and what do I say if not?* Each answered it with its own
+hand-rolled branch set: forge-4-backlog a binary verified/not check, forge-5-loop
+four cases, forge-6-docs five. `forge-session.py verify-state` derives that answer
+from the authoritative on-disk entry instead — one case enum, one message table,
+the same "never eyeball the graph" move `select-outcome` makes for the exit outcome
+(issue #277, part of the #265 guard-first program).
+
+The verb reads, never writes. It reads the **raw** `forge-verify-{token}` status the
+gates key on — it does **not** apply the version-aware freshness `verify_state()`
+computes for the navigator's most-recent-stage gate. A `passed` entry classifies
+`passed` regardless of the stage version, because that is exactly what the gates read
+today; layering re-verify-on-revision onto them would be a behaviour change, not an
+additive one.
+
+## Synopsis
+
+```
+python3 forge-session.py verify-state \
+  --feature F --for-stage S [--specs-dir DIR] [--epic E] [--json]
+```
+
+`--for-stage` is one of the five verify-token production stages (`forge-1-prd`,
+`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`) — the stage whose
+`forge-verify-{token}` entry is classified. `forge-0-epic` (verification lives in
+`.epic-state.json`) and `forge-6-docs` (no verify token) are **out of scope** and
+rejected at parse time.
+
+Output — always `{case, verified, stale, message, nextCommand}`:
+
+```json
+{
+  "case": "findings-applied",
+  "verified": false,
+  "stale": true,
+  "message": "Fixes were applied to auth's forge-4-backlog but nothing re-verified them; re-verification is still outstanding — run /skill:forge-verify auth backlog.",
+  "nextCommand": "/skill:forge-verify auth backlog"
+}
+```
+
+- **`case`** — one `VerifyStateCase`, the union of the cases the three gates spell out.
+- **`verified`** — `true` only for `passed`. An explicit `skipped` is resolved but *not*
+  verified, so it is `false`.
+- **`stale`** — `true` only for `findings-applied`: fixes landed but nothing re-verified
+  them, so a re-verify is still owed.
+- **`message`** — the single canonical operator sentence for the case.
+- **`nextCommand`** — the forge-verify retry for every unresolved case; `null` for
+  `passed`, which needs no action.
+
+## The case enum
+
+`VerifyStateCase` is the union of the raw `forge-verify-*` statuses the three gates
+key on, plus `never` for the absent / `pending` / unrecognized bucket every gate
+folds into "not verified". `tests/test_verify_state.py` pins the enum to the
+enumerating gate bodies, both directions, so a gate cannot grow a seventh case or
+spell an existing one differently.
+
+| `case` | on-disk status | `verified` | `stale` | meaning |
+| --- | --- | :---: | :---: | --- |
+| `passed` | `passed` | ✓ | | verification passed — proceed |
+| `findings-reported` | `findings-reported` | | | blocking findings live and unresolved |
+| `findings-applied` | `findings-applied` | | ✓ | fixes applied, re-verify still owed |
+| `auto-verify-pending` | `auto-verify-pending` | | | scheduled automatic verification, owed but unrun |
+| `skipped` | `skipped` | | | user explicitly proceeded without verifying |
+| `never` | absent / `pending` / unrecognized | | | never verified |
+
+## Classification
+
+The status ordering mirrors `verify_state()` — an explicit `skipped` and recorded
+`auto-verify-pending` debt are tested **before** the generic bucket, so neither can
+fall through to `never`:
+
+1. `skipped` → **skipped**.
+2. `auto-verify-pending` → **auto-verify-pending**. Unusable scheduling metadata
+   (missing/malformed `scheduledStageVersion`) warns once (REQ-DEBT-02) but the debt
+   stays owed — degrading it to `never` is exactly the conflation that requirement
+   forbids.
+3. `findings-reported` → **findings-reported**.
+4. `findings-applied` → **findings-applied**.
+5. `passed` → **passed**.
+6. anything else (absent, `pending`, or an out-of-vocabulary status) → **never**. A
+   present-but-unrecognized status is flagged once (#148) then treated as unverified,
+   the same answer an absent entry gets; a known `pending` (or an absent entry) is
+   quiet.
+
+A missing, unreadable, or torn state file never raises — the entry reads as absent
+and classifies `never`, the same fail-safe the three gates take.
+
+## Messages
+
+`VERIFY_STATE_MESSAGES` holds one canonical sentence per case; the `auto-verify-pending`
+case reuses `AUTO_PENDING_DIAGNOSTIC` — the single normative owed-debt sentence every
+read-side emitter already shares — and appends the revision-advance clause when the
+recorded schedule predates the current artifact. `{subject}` is the feature (or epic
+member), `{stage}` the served production stage, `{command}` the forge-verify retry.

package/adapters/pi/scripts/forge-bootstrap.py

@@ -642,7 +642,28 @@ def _compose_agent_file(answers: Answers, filename: str) -> str:
 
 
 def write_hygiene(answers: Answers, target: Path, sentinel: Sentinel) -> None:
-    """Emit README, LICENSE, and the host agent-instruction file(s) (02 §4.5)."""
+    """Emit README, LICENSE, and the host agent-instruction file(s) (02 §4.5).
+
+    Interop with ``forge-init``'s root hygiene step
+    (``references/shared-conventions.md`` § "Root Hygiene (Tooling Feedback)"), which
+    writes the same "Tooling feedback" section into a root ``AGENTS.md``/``CLAUDE.md``.
+    The two writers cannot duplicate each other, but NOT because of the guard below:
+    a target that ``forge-init`` has touched holds ``forge.config.json`` (and possibly
+    ``AGENTS.md``), neither of which ``ALLOWED_META_FILE_RE`` permits, so ``check()``
+    reports ``eligible: false`` and the greenfield gate refuses the whole bootstrap run
+    before ``scaffold()`` is reached. In the other direction it is ``forge-init``'s own
+    shell ``[ -f … ] ||`` guard that protects this file. ``_write_artifact``'s
+    never-overwrite guard is load-bearing here only for an interrupted-bootstrap resume
+    (REQ-LIFE-02) — worth knowing, since the obvious reading of "never overwrites" is
+    that it is what makes the two writers safe together, and it is not.
+
+    On that one resume path the skip has a cost worth stating: forge-init's template is
+    a stub carrying only the "Tooling feedback" section, so keeping it means the project
+    never receives the rest of THIS template — Project Purpose, Getting Started,
+    Conventions, and "Specs are pre-implementation". Keeping the user's file is still
+    the right call (it is not ours to overwrite), but the two files are not equivalent
+    and the block is a subset, not a superset.
+    """
     _write_artifact(target, "README.md", _compose_readme(answers), sentinel)
     if answers["license"] != "none":
         _write_artifact(target, "LICENSE", _compose_license(answers), sentinel)
@@ -806,7 +827,7 @@ def verify(target: Path, answers: Answers) -> VerifyResult:
     return {"toolchainPresent": True, "lint": lint, "test": test, "green": green}
 
 
-#: mirrors ``load_json_with_duplicates``/``warn_duplicate_keys`` in scripts/forge-session.py
+#: mirrors ``load_json_with_duplicates``/``warn_duplicate_keys`` in scripts/forge_session/_common.py
 def load_json_with_duplicates(path: Path) -> tuple[object, list[str]]:
     """Load JSON with last-key-wins values and ordered duplicate key names.
 

package/adapters/pi/scripts/forge-root.sh

@@ -12,6 +12,44 @@
 # generator (REQ-RES-05); keep it dependency-free beyond POSIX/Bash + the sentinel files.
 set -euo pipefail
 
+# ── Explain mode (#323; consumed only by doctor — the no-arg stdout contract is unchanged). ──
+# `--explain` prints `channel<TAB>path` for the resolved root instead of the bare path;
+# `--explain --all` prints one `channel<TAB>path` line for EVERY candidate root probed (complete
+# or degraded) WITHOUT stopping at the first, so doctor can enumerate every install on the host.
+# No args → the historic bare-path-to-stdout contract, byte-for-byte.
+EXPLAIN=0
+EXPLAIN_ALL=0
+if [ "${1:-}" = "--explain" ]; then
+  EXPLAIN=1
+  [ "${2:-}" = "--all" ] && EXPLAIN_ALL=1
+fi
+
+# Print a resolved root: `channel<TAB>path` under --explain, else the bare path (the contract
+# every prelude fence and tests/test_forge_root.py depend on).
+emit_root() {  # $1 = channel, $2 = path
+  if [ "$EXPLAIN" -eq 1 ]; then
+    printf '%s\t%s\n' "$1" "$2"
+  else
+    printf '%s\n' "$2"
+  fi
+}
+
+# Classify a resolved path to its install channel — used only by the discovery probe, whose
+# fixed candidate list mixes every agent's layout. The explicit steps pass their own channel.
+classify_channel() {  # $1 = path
+  case "$1" in
+    *"/.claude/plugins/cache/"*) printf 'marketplace-cache' ;;
+    *"/.claude/plugins/"*)       printf 'plugins-dir' ;;
+    *"/.claude/skills/"*)        printf 'skills-dir' ;;
+    *"/.agents/skills/"*)        printf 'agents-skills' ;;
+    *"/.pi"*)                    printf 'pi-dir' ;;
+    *"/.cursor/"*)               printf 'cursor-dir' ;;
+    *"/.gemini/"*)               printf 'gemini-dir' ;;
+    *"/.github/"*)               printf 'copilot-dir' ;;
+    *)                           printf 'discovery' ;;
+  esac
+}
+
 # Sentinel predicate (00-core-definitions.md §2 / SENTINEL_FILES). A directory is a valid
 # feature-forge root iff it carries the neutral bundle sentinel `.feature-forge-bundle.json`
 # (emitted into EVERY per-agent adapter bundle) OR the legacy Claude plugin manifest
@@ -33,12 +71,30 @@ CORE_ASSETS=(
   "references/stage-exit-protocol.md"
 )
 
+# scripts/forge-session.py is a thin shim that imports the sibling scripts/forge_session/
+# package (#279); a bundle that ships the shim but not the package cannot run the CLI, so
+# the package is part of a COMPLETE install. It is enforced only when the shipped
+# forge-session.py is ACTUALLY the shim (its body references `forge_session`): a legacy
+# self-contained forge-session.py that predates the split has no such package and must not
+# be spuriously flagged. This marker file proves the package dir shipped alongside the shim.
+PACKAGE_MARKER="scripts/forge_session/__init__.py"
+
+# Precise proxy for "this forge-session.py actually imports the forge_session package" — an
+# `import forge_session` / `from forge_session… import` STATEMENT at line start (leading
+# whitespace allowed). Anchoring to the statement avoids a bare token match (a comment or an
+# unrelated symbol mentioning `forge_session`) firing the package requirement, and a real
+# import line always satisfies it.
+SHIM_IMPORT_RE='^[[:space:]]*(from|import)[[:space:]]+forge_session([._[:space:]]|$)'
+
 # Echo the first missing core asset (relative path) for $1, or nothing when complete.
 first_missing_asset() {  # $1 = candidate dir
   local a
   for a in "${CORE_ASSETS[@]}"; do
     [ -f "$1/$a" ] || { printf '%s' "$a"; return 0; }
   done
+  if grep -qE "$SHIM_IMPORT_RE" "$1/scripts/forge-session.py" 2>/dev/null; then
+    [ -f "$1/$PACKAGE_MARKER" ] || { printf '%s' "$PACKAGE_MARKER"; return 0; }
+  fi
 }
 
 # A sentinel-bearing candidate that lacks a core asset is remembered here (first one wins)
@@ -47,16 +103,22 @@ first_missing_asset() {  # $1 = candidate dir
 partial_root=""
 partial_missing=""
 
-# Given a candidate that already passed is_root: print + exit 0 if it is complete; otherwise
+# Given a candidate that already passed is_root: emit + exit 0 if it is complete; otherwise
 # record it as the degraded fallback and return so probing continues. Always returns 0 on the
-# fall-through path so `set -e` never aborts the resolver on a partial candidate.
-accept_root() {  # $1 = candidate dir (already is_root)
-  local miss
+# fall-through path so `set -e` never aborts the resolver on a partial candidate. Under
+# --explain --all it emits every candidate (tagged) and never exits, for enumeration.
+accept_root() {  # $1 = candidate dir (already is_root); $2 = channel ("auto" → classify by path)
+  local miss channel
+  channel="$2"
+  [ "$channel" = "auto" ] && channel="$(classify_channel "$1")"
   miss="$(first_missing_asset "$1")"
   if [ -z "$miss" ]; then
-    printf '%s\n' "$1"
-    exit 0
+    emit_root "$channel" "$1"
+    [ "$EXPLAIN_ALL" -eq 1 ] || exit 0
+    return 0
   fi
+  # Degraded candidate: --all reports it tagged so doctor sees the full picture.
+  [ "$EXPLAIN_ALL" -eq 1 ] && emit_root "${channel}(degraded)" "$1"
   if [ -z "$partial_root" ]; then
     partial_root="$1"
     partial_missing="$miss"
@@ -64,13 +126,34 @@ accept_root() {  # $1 = candidate dir (already is_root)
   return 0
 }
 
+# ── Step 0: explicit operator override — FEATURE_FORGE_ROOT is authoritative (#323). ────────
+# A set value MUST resolve here or fail loudly; it never silently falls back to discovery, so a
+# dev-override pointing at the wrong/absent bundle is an actionable error rather than a surprise
+# run of some other install on a multi-install host. (CLAUDE_PLUGIN_ROOT is a host-set fact, not
+# an operator override, so it stays in Step 3.) --explain --all only enumerates, so it neither
+# exits nor fails here.
+if [ -n "${FEATURE_FORGE_ROOT:-}" ]; then
+  if is_root "$FEATURE_FORGE_ROOT"; then
+    accept_root "$FEATURE_FORGE_ROOT" "FEATURE_FORGE_ROOT"
+    # accept_root exited 0 on a complete override. Reaching here means it is DEGRADED (or we are
+    # enumerating): a set-but-incomplete override fails loudly, never falls back.
+    if [ "$EXPLAIN_ALL" -ne 1 ]; then
+      echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT is a degraded install (missing $partial_missing) — reinstall/update it, or unset FEATURE_FORGE_ROOT to fall back to discovery." >&2
+      exit 1
+    fi
+  elif [ "$EXPLAIN_ALL" -ne 1 ]; then
+    echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT is not a feature-forge root (no .feature-forge-bundle.json or .claude-plugin/plugin.json) — fix or unset it; discovery is skipped for an explicit override." >&2
+    exit 1
+  fi
+fi
+
 # ── Step 1: self-location — parent of this script's dir is the install root. ─────────────
 # This is the PRIMARY path: a bundle ships its own scripts/forge-root.sh, so the parent of
 # this script's dir is that bundle's root under any agent's layout.
 self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
 root="$(cd -- "$self_dir/.." && pwd -P)"
 if is_root "$root"; then
-  accept_root "$root"
+  accept_root "$root" "self-location"
 fi
 
 # ── Step 2a: Claude marketplace-cache installs — ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/.
@@ -84,7 +167,7 @@ fi
 while IFS= read -r manifest; do
   candidate="${manifest%/.claude-plugin/plugin.json}"
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
 done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/plugin.json 2>/dev/null || true)
 
@@ -105,7 +188,7 @@ if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
     "$PI_CODING_AGENT_DIR"/node_modules/@garygentry/feature-forge/adapters/pi \
   ; do
     if is_root "$candidate"; then
-      accept_root "$candidate"
+      accept_root "$candidate" "auto"
     fi
   done
 fi
@@ -137,7 +220,7 @@ for candidate in \
   "$PWD"/.pi/node_modules/@garygentry/feature-forge/adapters/pi \
 ; do
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
 done
 
@@ -150,7 +233,7 @@ probe_dir="$PWD"
 while :; do
   candidate="$probe_dir/.pi/skills/feature-forge"
   if is_root "$candidate"; then
-    accept_root "$candidate"
+    accept_root "$candidate" "auto"
   fi
   [ "$probe_dir" = "/" ] && break
   next_probe_dir="$(dirname -- "$probe_dir")"
@@ -158,19 +241,19 @@ while :; do
   probe_dir="$next_probe_dir"
 done
 
-# ── Step 3: env fallback — neutral FEATURE_FORGE_ROOT, then the legacy CLAUDE_PLUGIN_ROOT. ─
-# The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
-# compatibility with existing Claude installs (C-4).
-if [ -n "${FEATURE_FORGE_ROOT:-}" ] && is_root "$FEATURE_FORGE_ROOT"; then
-  accept_root "$FEATURE_FORGE_ROOT"
-fi
+# ── Step 3: legacy env fallback — CLAUDE_PLUGIN_ROOT. ────────────────────────────────────
+# The neutral FEATURE_FORGE_ROOT override is handled authoritatively in Step 0 (#323).
+# CLAUDE_PLUGIN_ROOT is a host-set fact (Claude exports it), NOT an operator override, so it
+# stays here as a last discovery hint — kept only for backwards compatibility with existing
+# Claude installs (C-4).
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
-  accept_root "$CLAUDE_PLUGIN_ROOT"
+  accept_root "$CLAUDE_PLUGIN_ROOT" "CLAUDE_PLUGIN_ROOT"
 fi
 
-# ── Step 4: failure. A sentinel-bearing but asset-incomplete root found along the way is a
-# DEGRADED install (#152) — report it distinctly and actionably rather than the generic
-# cannot-locate message, so the operator knows to reinstall/update rather than reconfigure. ─
+# ── Step 4: failure (or, under --explain --all, the end of enumeration). A sentinel-bearing but
+# asset-incomplete root found along the way is a DEGRADED install (#152) — report it distinctly
+# and actionably rather than the generic cannot-locate message. ─
+[ "$EXPLAIN_ALL" -eq 1 ] && exit 0  # --all printed every candidate; it is diagnostic, never a failure
 if [ -n "$partial_root" ]; then
   echo "feature-forge: install incomplete/degraded at $partial_root (missing $partial_missing) — reinstall with 'npx @garygentry/feature-forge' (or 'feature-forge update' for a stale install)." >&2
   exit 1