@garygentry/feature-forge 0.2.13 → 0.3.0

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

@@ -21,14 +21,56 @@ is_root() {  # $1 = candidate dir
   [ -f "$1/.feature-forge-bundle.json" ] || [ -f "$1/.claude-plugin/plugin.json" ]
 }
 
+# Completeness gate (#152). A dir can carry the sentinel yet be a partial/stale install —
+# a skill-only extraction, or an install predating the shared-reference fan-out — where the
+# scripts/references the skills load at every stage are absent. Such a root looks usable but
+# runs DEGRADED silently (hand-improvised state schema, skipped Mint Guard + scripted exit).
+# These are the assets a complete install MUST carry beyond the sentinel; a resolved root
+# missing any of them is reported as degraded rather than handed back as if it were whole.
+CORE_ASSETS=(
+  "scripts/forge-session.py"
+  "references/pipeline-state-schema.json"
+  "references/stage-exit-protocol.md"
+)
+
+# 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
+}
+
+# A sentinel-bearing candidate that lacks a core asset is remembered here (first one wins)
+# so a COMPLETE root found later in the probe order still takes precedence; only if the probe
+# ends with no complete root do we report this degraded install (step 4).
+partial_root=""
+partial_missing=""
+
+# Given a candidate that already passed is_root: print + 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
+  miss="$(first_missing_asset "$1")"
+  if [ -z "$miss" ]; then
+    printf '%s\n' "$1"
+    exit 0
+  fi
+  if [ -z "$partial_root" ]; then
+    partial_root="$1"
+    partial_missing="$miss"
+  fi
+  return 0
+}
+
 # ── 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
-  printf '%s\n' "$root"
-  exit 0
+  accept_root "$root"
 fi
 
 # ── Step 2a: Claude marketplace-cache installs — ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/.
@@ -42,8 +84,7 @@ fi
 while IFS= read -r manifest; do
   candidate="${manifest%/.claude-plugin/plugin.json}"
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/plugin.json 2>/dev/null || true)
 
@@ -51,9 +92,24 @@ done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/pl
 # Globs that match nothing expand to themselves; the is_root test rejects such literals. Covers
 # every supported agent's install destination under BOTH global ($HOME) and project ($PWD) scope,
 # matching the installer's per-agent layout: claude .claude/skills, codex .agents/skills, copilot
-# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions. The cache glob repeats
-# step 2a's path for a cache install that carries only the neutral bundle sentinel (no
-# plugin.json for ls -t to key on).
+# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions, pi .pi/skills or
+# $PI_CODING_AGENT_DIR/skills. The cache glob repeats step 2a's path for a cache install that
+# carries only the neutral bundle sentinel (no plugin.json for ls -t to key on).
+if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
+  for candidate in \
+    "$PI_CODING_AGENT_DIR/skills/feature-forge" \
+    "$PI_CODING_AGENT_DIR"/git/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/git/*/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/packages/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/npm/*/@garygentry/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/node_modules/@garygentry/feature-forge/adapters/pi \
+  ; do
+    if is_root "$candidate"; then
+      accept_root "$candidate"
+    fi
+  done
+fi
+
 for candidate in \
   "$HOME/.claude/skills/feature-forge" \
   "$PWD/.claude/skills/feature-forge" \
@@ -67,25 +123,57 @@ for candidate in \
   "$PWD/.cursor/rules/feature-forge" \
   "$HOME/.gemini/extensions/feature-forge" \
   "$PWD/.gemini/extensions/feature-forge" \
+  "$HOME/.pi/agent/skills/feature-forge" \
+  "$PWD/.pi/skills/feature-forge" \
+  "$HOME"/.pi/agent/git/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/git/*/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/packages/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/node_modules/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/packages/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/node_modules/@garygentry/feature-forge/adapters/pi \
 ; do
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done
 
+# Project-scoped Pi installs may be discovered from a subdirectory of the repository. Probe
+# ancestor .pi roots up to the filesystem root; this is bounded by path depth and avoids
+# recursive globs. Scoped to .pi ONLY — every other agent's project layout is probed at $PWD
+# in the fixed list above, and widening those to ancestors here would silently change
+# established discovery behaviour for agents this bundle did not introduce.
+probe_dir="$PWD"
+while :; do
+  candidate="$probe_dir/.pi/skills/feature-forge"
+  if is_root "$candidate"; then
+    accept_root "$candidate"
+  fi
+  [ "$probe_dir" = "/" ] && break
+  next_probe_dir="$(dirname -- "$probe_dir")"
+  [ "$next_probe_dir" = "$probe_dir" ] && break
+  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
-  printf '%s\n' "$FEATURE_FORGE_ROOT"
-  exit 0
+  accept_root "$FEATURE_FORGE_ROOT"
 fi
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
-  printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
-  exit 0
+  accept_root "$CLAUDE_PLUGIN_ROOT"
 fi
 
-# ── Step 4: failure — actionable message to stderr, exit 1 (REQ-RES-04). ─────────────────
+# ── 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. ─
+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
+fi
 echo "feature-forge: cannot locate install root. Set FEATURE_FORGE_ROOT to the bundle dir, or run from an installed skill dir." >&2
 exit 1

package/adapters/gemini/scripts/forge-session.py

@@ -117,8 +117,20 @@ VERIFY_TOKEN_BY_STAGE: Final[dict[str, str]] = {
 
 #: A production stage status that counts as "done" for next-stage selection.
 _DONE_STATUS: Final = "complete"
-#: Verify statuses that count as "resolved" (no outstanding verify needed).
+#: The authoritative forge-verify status vocabulary. SOURCE OF TRUTH:
+#: references/pipeline-state-schema.json (definitions.verifyEntry.properties.status.enum).
+#: A status outside this set is unrecognized and must not be silently interpreted (#148).
+#: NOTE: epic-manifest.py keeps a byte-identical copy — flat, self-contained scripts have
+#: no shared import module (each is copied verbatim into per-agent adapter bundles).
+KNOWN_VERIFY_STATUSES: Final = frozenset(
+    {"pending", "passed", "findings-reported", "findings-applied", "skipped"}
+)
+#: Verify statuses that count as "resolved" (no outstanding verify needed). A STRICT
+#: subset of KNOWN_VERIFY_STATUSES — not collapsible into it (different meaning).
 _VERIFY_RESOLVED: Final = frozenset({"passed", "findings-applied", "skipped"})
+#: Per-process dedupe for the unknown-verify-status diagnostic (#148) so a single
+#: bogus status is flagged once, not once per verify_state() call in a command.
+_UNKNOWN_VERIFY_WARNED: set[str] = set()
 
 #: Default context window when the model can't be inferred and config is silent.
 _DEFAULT_WINDOW: Final = 200_000
@@ -257,6 +269,25 @@ def _verify_entry(state: dict, verify_key: str) -> dict:
     return entry if isinstance(entry, dict) else {}
 
 
+def _warn_unknown_verify_status(stage_name: str, status: object) -> None:
+    """Emit a one-time stderr diagnostic for an out-of-vocabulary verify status (#148).
+
+    The freshness classifier maps an unrecognized status to "never verified" — correct,
+    but silent, so a typo poisons the downstream gate (e.g. forge-5-loop's dependency
+    check) with no clue. Flagging it here makes the bad value visible where it is read.
+    """
+    key = f"{stage_name}={status!r}"
+    if key in _UNKNOWN_VERIFY_WARNED:
+        return
+    _UNKNOWN_VERIFY_WARNED.add(key)
+    known = ", ".join(sorted(KNOWN_VERIFY_STATUSES))
+    print(
+        f"feature-forge: unknown {stage_name} status {status!r} "
+        f"(treated as unverified; expected one of {known})",
+        file=sys.stderr,
+    )
+
+
 def verify_state(state: dict) -> tuple[str | None, str]:
     """Classify verify freshness for the most-recently-completed stage.
 
@@ -299,6 +330,12 @@ def verify_state(state: dict) -> tuple[str | None, str]:
         if status not in _VERIFY_RESOLVED:
             if status == "findings-reported":
                 return stage, "failing"
+            # An unrecognized status (outside KNOWN_VERIFY_STATUSES) is treated as
+            # "never verified" — defensible, but flag it once so a typo (e.g. the
+            # eye-slip 'findings-resolved') doesn't silently poison the gate that
+            # reads this label (#148). ``pending``/``None`` are known/absent → quiet.
+            if status is not None and status not in KNOWN_VERIFY_STATUSES:
+                _warn_unknown_verify_status(f"forge-verify-{token}", status)
             return stage, "never"
         verified_version = entry.get("verifiedStageVersion")
         stage_version = _stage_version(state, stage)
@@ -1397,6 +1434,17 @@ def _resolve_feature_dir(specs_dir: Path, feature: str, epic: str | None) -> Pat
     return flat
 
 
+def _host_command(command: str, host: str) -> str:
+    """Rewrite a `/feature-forge:` slash command to the host's surface.
+
+    Pi's slash-command surface is `/skill:` (matching the adapter body's
+    `/feature-forge:` -> `/skill:` translation). The scripted stage-exit output bypasses
+    that body translation, so it rewrites the commands it emits here. No-op for
+    claude/generic, which keep the canonical `/feature-forge:` form.
+    """
+    return command.replace("/feature-forge:", "/skill:") if host == "pi" else command
+
+
 def _next_steps_block(
     next_command: str, host: str, reconcile: dict | None = None
 ) -> str:
@@ -1426,6 +1474,18 @@ def _next_steps_block(
             "2. Then start a fresh session and run the next stage below — or "
             "re-run `/feature-forge:forge` to let the navigator resume from disk."
         )
+    elif host == "pi":
+        # Pi's fresh-session command is `/new` (not `/clear`); its slash-command
+        # surface is `/skill:` (the fenced command below is rewritten to match).
+        clear_line = (
+            "1. `/new` — recommended unconditionally at this stage boundary; every "
+            "artifact is on disk, so the work survives starting a fresh session. "
+            "I can't run `/new` for you — you have to run it yourself."
+        )
+        next_line = (
+            "2. Then, in the new session, run the next stage below — or re-run "
+            "`/skill:forge` to let the navigator resume from disk."
+        )
     else:
         clear_line = (
             "1. Clear your session / start a fresh session — recommended "
@@ -1442,7 +1502,7 @@ def _next_steps_block(
     # epic-change request the primary is the reconcile command; otherwise it is the
     # normal next-stage command. The fence sits before the sentinel, so the
     # sentinel remains the absolute last line.
-    fenced_command = reconcile["command"] if blocking else next_command
+    fenced_command = _host_command(reconcile["command"] if blocking else next_command, host)
     lines = ["**Next steps**", clear_line]
     if blocking:
         count = reconcile["count"]
@@ -1458,15 +1518,14 @@ def _next_steps_block(
     lines.append("")
     lines.append(f"```\n{fenced_command}\n```")
     if blocking and reconcile.get("deferred"):
-        lines.append(
-            f"After reconciling, continue the pipeline with: `{reconcile['deferred']}`"
-        )
+        deferred_cmd = _host_command(reconcile["deferred"], host)
+        lines.append(f"After reconciling, continue the pipeline with: `{deferred_cmd}`")
     elif reconcile and reconcile.get("reminder"):
         count = reconcile["count"]
         plural = "s" if count != 1 else ""
         lines.append(
             f"You also flagged {count} epic change{plural} to reconcile when "
-            f"convenient: `{reconcile['command']}`"
+            f"convenient: `{_host_command(reconcile['command'], host)}`"
         )
     lines.append(NEXT_STEPS_SENTINEL)
     return "\n".join(lines)
@@ -1593,10 +1652,10 @@ def stage_exit(
         "verifyGate": verify_gate,
         "autoFixEligible": auto_fix_eligible,
         "verifyState": verify_label,
-        "verifyCommand": f"/feature-forge:forge-verify {feature}",
+        "verifyCommand": _host_command(f"/feature-forge:forge-verify {feature}", host),
         "autoVerifyEffective": effective_auto_verify,
         "nextStage": next_stage_id,
-        "nextCommand": next_command,
+        "nextCommand": _host_command(next_command, host) if next_command else next_command,
         "invalidAutoVerifyKeys": invalid_auto_verify_keys(config),
         "gitRepo": git_repo,
         "cleanTree": clean_tree,
@@ -1722,7 +1781,7 @@ def main() -> int:
     p_exit.add_argument("--epic", default=None, help="Epic name for a nested member")
     p_exit.add_argument("--next-feature", default=None, dest="next_feature",
                         help="First actionable feature (epic handoff next-command arg)")
-    p_exit.add_argument("--host", default="claude", choices=("claude", "generic"),
+    p_exit.add_argument("--host", default="claude", choices=("claude", "generic", "pi"),
                         help="Host wording for the NEXT-STEPS block")
     p_exit.add_argument("--json", action="store_true", dest="json_output")
 

package/adapters/gemini/skills/forge/references/shared-conventions.md

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-0-epic/references/shared-conventions.md

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-1-prd/forge-1-prd.md

@@ -121,6 +121,8 @@ Iterate until the user confirms the PRD is complete.
 
 ## Step 6: Update Pipeline State and Commit
 
+Before writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-conventions.md` with `{stage}` = `forge-1-prd` — a resumed mid-stage continuation must not overwrite a committed `PRD.md` or re-fire a finished exit.
+
 Write pipeline state conforming to `references/pipeline-state-schema.json`.
 
 1. Create or update `{resolvedFeatureDir}/.pipeline-state.json`:

package/adapters/gemini/skills/forge-1-prd/references/shared-conventions.md

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-2-tech/forge-2-tech.md

@@ -183,6 +183,8 @@ Use the host's question mechanism to collect this feedback.
 
 ## Step 7: Update Pipeline State and Commit
 
+Before writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-conventions.md` with `{stage}` = `forge-2-tech` — a resumed mid-stage continuation must not overwrite a committed `tech-spec.md` or re-fire a finished exit.
+
 Write pipeline state conforming to `references/pipeline-state-schema.json`.
 
 1. Update `{resolvedFeatureDir}/.pipeline-state.json`:

package/adapters/gemini/skills/forge-2-tech/references/shared-conventions.md

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-2-tech/references/stacks/_generic.md

@@ -79,6 +79,27 @@ Replace stack-specific checks with these generic equivalents:
 | "JSDoc on every field" | "Documentation comments on every field" |
 | "tsconfig.json extends root" | "Build configuration follows project conventions" |
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+Since no dedicated profile applies, identify these by role rather than exact filename:
+
+- **Runtime entrypoints (a legitimate non-test call site):** the process/main entry the build's
+  run command actually launches (from the CI/`Makefile`/manifest "start" target), an HTTP/RPC handler
+  or route, a scheduled/worker task, or a CLI subcommand — **not** a file in the project's test
+  directory or matching its test-file convention.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** any
+  module/hook the framework runs **once per process before serving** — a startup/lifecycle hook, an
+  import-time initializer, a global preload, or a shared test-setup module that bootstraps production
+  graphs. Side effects here run on every process start (and, under a dev/watch runtime, on every
+  reload).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** database/ORM
+  clients and connection pools, message/queue clients, telemetry/observability SDKs, or a broad
+  whole-service-layer import. An init pulling any of these into a universal bootstrap entry is the
+  CHECK-I23 pattern — recommend lazy initialization at the first handler/worker that needs the graph,
+  not eagerly at process start.
+
 ## Acceptance Criteria Patterns
 
 Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure:

package/adapters/gemini/skills/forge-2-tech/references/stacks/go.md

@@ -84,6 +84,25 @@ When examining a Go project, check for:
 - **Formatting**: `gofmt -l .` or `goimports -l .` (should produce no output)
 - **Module tidiness**: `go mod tidy` (ensures `go.mod` and `go.sum` are consistent)
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** `func main()` in a `package main` under
+  `cmd/…` or the module root, an HTTP handler registered on a `*http.ServeMux` / router, a gRPC service
+  registration, or a worker/consumer goroutine started from `main` — not a `*_test.go` file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package-level
+  `func init()` that constructs heavy clients, package-level `var` initializers that dial/connect at
+  import time, or a single `bootstrap`/`wire` module `main` calls before serving. `init()` and
+  package-var side effects run on **every** binary start, before `main` gets control.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB drivers/pools
+  (`database/sql` + a driver, `pgx`, `gorm`, `mongo-driver`), message/queue clients (`sarama`/Kafka,
+  `amqp`, `go-redis`), telemetry SDKs (`go.opentelemetry.io/*`, `sentry-go`), or a broad internal
+  service package. An `init()` or package-var that dials any of these is the CHECK-I23 pattern —
+  recommend a `sync.Once` lazy constructor invoked from the first handler that needs it, not an
+  eager package-level connect.
+
 ## Testing
 
 - **Framework**: `testing` stdlib package

package/adapters/gemini/skills/forge-2-tech/references/stacks/python.md

@@ -111,6 +111,27 @@ async def refresh_session_token(
 - **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
 - **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `if __name__ == "__main__":` block, a
+  `[project.scripts]` console-script target in `pyproject.toml`, an ASGI/WSGI app object
+  (`app = FastAPI()` / Django `wsgi.py` / `asgi.py`), a route/view/handler, a Celery/RQ task module, or
+  a management command — not a `test_*.py` / `conftest.py`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package
+  `__init__.py` that eagerly instantiates heavy clients at import time, a framework startup hook
+  (FastAPI `lifespan` / `@app.on_event("startup")`, Django `AppConfig.ready()`, a Gunicorn/uvicorn
+  `--preload` module), or a `conftest.py` that bootstraps production graphs. Import-time side effects
+  here run on every process start.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM engines
+  (`sqlalchemy.create_engine`, `psycopg`, Django ORM, `pymongo`, `redis`), task queues (`celery`,
+  `rq`, `kafka`), telemetry SDKs (`opentelemetry`, `sentry_sdk`), or a whole-service-layer package
+  import. An init pulling any of these at a universal entry is the CHECK-I23 pattern — recommend lazy
+  init (module-level `@lru_cache` factory, `Depends()` provider, or first-use lazy import) at the
+  handler that needs it.
+
 ## Testing
 
 - **Framework**: pytest (with `conftest.py` for fixtures)

package/adapters/gemini/skills/forge-2-tech/references/stacks/rust.md

@@ -90,6 +90,25 @@ When examining a Rust project, check for:
 - **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
 - **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** `fn main()` in `main.rs` or a `[[bin]]`
+  target, an async runtime entry (`#[tokio::main]`), an HTTP handler registered on an axum/actix/warp
+  router, or a worker task spawned from `main` — not a `#[cfg(test)]` module or a `tests/` integration
+  file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a `lazy_static!`
+  / `once_cell::sync::Lazy` static that eagerly constructs heavy clients, a single `bootstrap`/`setup`
+  fn `main` calls before serving, or a `#[ctor]`-style pre-`main` initializer. A `Lazy` static is only
+  a risk when it is *forced* at startup rather than on first use.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB pools
+  (`sqlx::Pool`, `diesel`, `deadpool`, `mongodb`), message/queue clients (`rdkafka`, `lapin`,
+  `redis`), telemetry SDKs (`opentelemetry`, `sentry`), or a broad internal service crate. Constructing
+  any of these eagerly at a universal entry is the CHECK-I23 pattern — recommend a `OnceCell`/`Lazy`
+  forced on **first use** by the handler that needs it, not at process start.
+
 ## Testing
 
 - **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)

package/adapters/gemini/skills/forge-2-tech/references/stacks/typescript.md

@@ -64,6 +64,29 @@ When examining a TypeScript project, check for:
 - **Cross-package type checks**: `bun run typecheck` (or equivalent) passes for both the feature package AND packages that depend on it
 - **Import path validation**: All import paths resolve correctly per the `exports` map in `package.json`
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `package.json` `bin` / CLI `main`; a
+  server entry that actually starts listening (`src/server.ts`, `src/index.ts` invoking `listen`); a
+  worker/consumer file; and for Next.js — `middleware.ts`, `app/**/route.ts` route handlers,
+  `app/**/{page,layout,template}.tsx`, server actions, and `instrumentation.ts`. Express/Hono/Fastify:
+  the file that constructs the app and calls `.listen()`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** Next.js
+  `instrumentation.ts` / `instrumentation.js` (its `register()` runs once per server process before
+  any request), an app-server preload/`register`/`--import` hook, a root `app/layout.tsx` that
+  eagerly imports server singletons, and global test setup (`vitest.setup.ts`, `jest.setup.ts`) if it
+  bootstraps production graphs. Wiring a heavy init here loads it on **every** cold start (and, under
+  the dev server, on every module re-evaluation).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM clients
+  (`drizzle-orm`, `@prisma/client`, `pg`, `mongoose`, `kysely`), queue/worker libs (`bullmq`, `bull`,
+  `kafkajs`, `ioredis`), telemetry/observability SDKs (`@opentelemetry/*`, `@sentry/node`), and a
+  whole-service-layer barrel (`import * as services from "@repo/services"`). An init that pulls any of
+  these into a universal bootstrap entry is the CHECK-I23 pattern — recommend lazy init at the first
+  route/handler/worker that needs it.
+
 ## Testing
 
 - **Framework**: Vitest (most common in modern TS), Jest, or testing-library

package/adapters/gemini/skills/forge-3-specs/forge-3-specs.md

@@ -116,6 +116,8 @@ do not reload everything. This keeps quality up under context pressure.
 
 ## Step 5: Cross-Reference Validation
 
+Before writing `TRACEABILITY.md` or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-conventions.md` with `{stage}` = `forge-3-specs` — a resumed mid-stage continuation must not overwrite a committed `TRACEABILITY.md` or re-fire a finished exit.
+
 After writing all documents, verify:
 
 1. Every PRD requirement has coverage in at least one spec document

package/adapters/gemini/skills/forge-3-specs/references/shared-conventions.md

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-3-specs/references/stacks/_generic.md

@@ -79,6 +79,27 @@ Replace stack-specific checks with these generic equivalents:
 | "JSDoc on every field" | "Documentation comments on every field" |
 | "tsconfig.json extends root" | "Build configuration follows project conventions" |
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+Since no dedicated profile applies, identify these by role rather than exact filename:
+
+- **Runtime entrypoints (a legitimate non-test call site):** the process/main entry the build's
+  run command actually launches (from the CI/`Makefile`/manifest "start" target), an HTTP/RPC handler
+  or route, a scheduled/worker task, or a CLI subcommand — **not** a file in the project's test
+  directory or matching its test-file convention.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** any
+  module/hook the framework runs **once per process before serving** — a startup/lifecycle hook, an
+  import-time initializer, a global preload, or a shared test-setup module that bootstraps production
+  graphs. Side effects here run on every process start (and, under a dev/watch runtime, on every
+  reload).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** database/ORM
+  clients and connection pools, message/queue clients, telemetry/observability SDKs, or a broad
+  whole-service-layer import. An init pulling any of these into a universal bootstrap entry is the
+  CHECK-I23 pattern — recommend lazy initialization at the first handler/worker that needs the graph,
+  not eagerly at process start.
+
 ## Acceptance Criteria Patterns
 
 Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure: