@garygentry/feature-forge 0.2.8 → 0.2.10

package/adapters/gemini/skills/forge-5-loop/forge-5-loop.md

@@ -196,7 +196,7 @@ Then commit this state write before launching (mandatory). The runner refuses to
 
 ### 3b. Launch Background Process
 
-Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
+Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard and the root→`IS_SANDBOX` sandbox guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -288,17 +288,19 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 
    **Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the host's subagent mechanism, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `/feature-forge:forge-verify {feature} impl` for the user to run inline/manually (mirroring `autoInvokeNextStage`), and offer the auto-verify enable as plain text only if a config write is possible.
 2. **Then clear your session / start a fresh session.** Recommended **unconditionally** at this boundary for a clean start — independent of how full the context window is. Every artifact is on disk, so the work survives the clear. **I can't clear your session / start a fresh session for you — you have to run it yourself.**
-3. **Then run `/feature-forge:forge-1-prd {chosen}`** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk.
+3. **Then run the next command** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk:
+
+   ```
+   /feature-forge:forge-1-prd {chosen}
+   ```
 
 ## Gotchas
 
 - **Plugin-root discovery (1b-epic helper) covers installed paths, not workspace-dev checkouts.** The `forge-root.sh` search in 1b-epic probes `~/.claude/skills/feature-forge`, `~/.claude/plugins/cache/*/feature-forge/*` (marketplace-cache installs), `~/.claude/plugins/*/feature-forge`, and `./.agents/skills/feature-forge` — the locations of an **installed** plugin. A feature-forge **source checkout** (e.g. `~/workspace/feature-forge`) is not on that list, so the helper exits "cannot locate plugin root." That is expected in a dev environment, not a bug; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`). The bootstrap prelude wraps its candidate loop in `bash -c` so the `~/.claude/plugins/*/feature-forge` glob is zsh-safe: an empty expansion no longer aborts the loop under zsh's `nomatch`.
 - `{backlogDir}` is a **directory path**, not a file path. Pass `specs/auth`, not `specs/auth/backlog.json`.
-- rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
-- State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is isolated per backlog dir, so concurrent features don't collide.
-- If the session disconnects during a long-running loop, the runner process continues independently. The user can check results later with the status / list commands.
+- rauf resolves `RAUF.md` with fallback (`{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`) — found as long as the runner is installed in the project. State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/`, within the feature's spec directory (expected) and isolated per backlog dir, so concurrent features don't collide.
+- If the session disconnects during a long-running loop, the runner process continues independently — the user can check results later with the status / list commands. If a previous run left a stale lock, the user may need to pass `--force` to clear it (rauf reports this error clearly).
 - Never run the run command in the foreground (without the host's background-execution mechanism) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the host's monitoring mechanism (3d), never `sleep`/poll in the foreground. The host's monitoring mechanism must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
-- If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
 - **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.
 

package/adapters/gemini/skills/forge-5-loop/references/result-reporting.md

@@ -16,7 +16,11 @@ Loop completed for {feature}. All {N} items implemented successfully.
 
 1. **Verify is already offered above.** Impl-verify is offered interactively right after this report (Step 5b for a standalone feature, Step 6.1 for an epic member) — run it there rather than as a second gate. It runs clean-room, so it needs no fresh session.
 2. **Clearing is optional here — warm is fine.** `forge-6-docs` benefits from the still-warm context of what the loop actually did, so continuing in this same session is the easy default. A cold start also works — every artifact is on disk — but there is no need to force it.
-3. **Then run `/feature-forge:forge-6-docs {feature}`** — in this warm session, or a fresh one if you prefer.
+3. **Then run the next command** — in this warm session, or a fresh one if you prefer:
+
+   ```
+   /feature-forge:forge-6-docs {feature}
+   ```
 
 **Runner review pass.** A review flag (e.g. rauf's `--review`) makes the runner run
 a post-loop review that **auto-creates and implements fix items** rather than handing

package/adapters/gemini/skills/forge-5-loop/references/runner-contract.md

@@ -101,6 +101,13 @@ default / `claude-cli` path skips this guard (the aliases are valid there).
 > rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
 > document that writing a tier alias binds the backlog to Claude agents). That lives
 > in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+>
+> **Follow-up (out of scope here — rauf repo).** The durable fix for the root/sandbox
+> refusal (see "Root/sandbox env guard" under Step 3b) is for **rauf itself** to honor
+> `IS_SANDBOX` when it launches `claude --dangerously-skip-permissions` as root (or to
+> detect root+flag-refused and emit a clear error instead of an opaque circuit-break).
+> feature-forge's launch-time export is the mitigation; the upstream fix lives in the
+> rauf plugin/repo. Track as a follow-up.
 
 ## Optional flags catalog (Step 2d, rauf)
 
@@ -131,6 +138,19 @@ session, then supervise it live via the runner's structured event file.
 > changes after that commit, surface it and let the user commit/stash or pass
 > `--force`; never auto-pass `--force`.
 
+> **Root/sandbox env guard.** On a hosted remote (e.g. Claude.ai) the loop often runs
+> **as root**. rauf's default Claude launch is `claude -p --dangerously-skip-permissions
+> …`, which the Claude CLI **refuses under root unless `IS_SANDBOX` is set** — the remote
+> container is a legitimate ephemeral sandbox, but without the flag every spawn exits and
+> rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the
+> cause. So when — and only when — the launcher is root (`[ "$(id -u)" = 0 ]`), export
+> `IS_SANDBOX="${IS_SANDBOX:-1}"` in front of the launch (an explicitly-set value is
+> honored; the `:-1` only supplies a default). Non-root/local runs are unaffected — the
+> guard is a no-op. **Surface a one-line note** when you set it — e.g. *"running as root →
+> setting IS_SANDBOX=1 so the sandboxed runner can use --dangerously-skip-permissions"* —
+> so the behavior is never silent. `forge-session.py doctor` also reports this condition.
+> Both launch commands below already carry the guard.
+
 **Do NOT redirect the run's stdout into `{loopRunner.stateDir}`.** rauf **persists
 its own** `{stateDir}/events.ndjson` (structured) and `{stateDir}/{logFile}` (human)
 natively, and **rotates** them at the start of every run (the prior run's files are
@@ -150,7 +170,7 @@ rotation timing. So:
   (Step 3d). Guard the very first run with the state dir:
 
   ```
-  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered runCommand}
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && { [ "$(id -u)" = 0 ] && export IS_SANDBOX="${IS_SANDBOX:-1}" || true; } && {rendered runCommand}
   ```
 
   (Note: the `--ndjson` stdout stream and `loopRunner.eventStreamCommand` are **not**
@@ -160,7 +180,7 @@ rotation timing. So:
   collide with any native file or be swept into `archive/`, then Monitor that file:
 
   ```
-  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/forge-events.ndjson 2>&1
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && { [ "$(id -u)" = 0 ] && export IS_SANDBOX="${IS_SANDBOX:-1}" || true; } && {rendered eventStreamCommand} > {backlogDir}/forge-events.ndjson 2>&1
   ```
 
 The background task's exit notification remains the single authoritative terminal

package/adapters/gemini/skills/forge-bootstrap/references/templates/hygiene/AGENTS.md

@@ -22,3 +22,14 @@ This project was scaffolded by forge-bootstrap. To continue development:
 - Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
 - Do not flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
 - It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.
+
+## Tooling feedback (feature-forge / rauf)
+
+This project is driven by the feature-forge pipeline and the rauf loop. Help improve those tools by capturing friction as you hit it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **on the human's go-ahead, not silently.**
+- **In an autonomous rauf iteration:** do **not** open issues mid-loop. Note the friction in `progress.md` for the human to triage later.

package/adapters/gemini/skills/forge-bootstrap/references/templates/hygiene/CLAUDE.md

@@ -23,3 +23,14 @@ This project was scaffolded by forge-bootstrap. To continue development:
 - Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
 - Don't flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
 - It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.
+
+## Tooling feedback (feature-forge / rauf)
+
+I'm driving this project with the feature-forge pipeline and the rauf loop, and I want to keep improving them. When you hit friction with either tool, help me capture it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, `/feature-forge:*`, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **once I give the go-ahead, not silently.**
+- **In an autonomous rauf iteration:** don't open issues mid-loop. Note the friction in `progress.md` for me to triage later.

package/adapters/gemini/skills/forge-verify/forge-verify.md

@@ -161,9 +161,9 @@ Load into context ALL artifacts for this feature based on mode:
 
 Read `references/verification-checklists.md` for the detailed checklists per mode. Execute every check. Do not skip checks because things "look fine." That same reference also holds the relocated **Findings Document Template (Step 4)**, the worked **Example Findings (Step 4)**, and the **Epic Mode State Write Detail (Step 6)** sections used later in this skill.
 
-Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~8 checks), you likely skipped checks — go back and complete them.
+Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~9 checks), you likely skipped checks — go back and complete them.
 
-**Epic mode dispatch.** Epic mode is a small (~8-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E08 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 are verifier judgment) and returns its findings.
+**Epic mode dispatch.** Epic mode is a small (~9-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E09 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 and E09 are verifier judgment) and returns its findings.
 
 ### Important: Be Specific, Not General
 

package/adapters/gemini/skills/forge-verify/references/verification-checklists.md

@@ -223,6 +223,18 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   `.pipeline-state.json` `epic` value names this epic, and every `features[]` entry has a
   matching member directory. On conflict the **manifest wins** (REQ-STATE-01); report, do
   not auto-repair.
+- [ ] **CHECK-E09**: **open epic change requests** — any member whose `.pipeline-state.json`
+  carries `epicChangeRequests[]` entries with `status: "open"` is surfaced as a **non-fatal**
+  finding (one per open request). Severity keys off `blocksCurrent`: a **blocking** request →
+  `inconsistency` (the epic decomposition and an in-flight member disagree; specs written now
+  would build on a soon-invalid premise), a **non-blocking** request → `improvement` (a
+  peer/downstream change to reconcile when convenient). Name the request's `kind`, `target`,
+  and `rationale`, and point at `/feature-forge:forge-0-epic {epic}` to reconcile. **Report, do
+  not repair** (same posture as CHECK-E07). Which members have open requests comes from the
+  same `render-status --json` counts the navigator uses (`features[].openEpicChangeRequests` /
+  `.blockingEpicChangeRequests`); the per-request `kind`/`target`/`rationale` detail is read
+  from the member `.pipeline-state.json` already loaded in Step 2. This is the pre-emptive
+  surface for the divergence class CHECK-E06/E07 otherwise catch only after the fact.
 
 ## Findings Document Template (Step 4)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Cross-agent installer for the feature-forge skill suite — installs the canonical forge pipeline into Claude, Codex, Copilot, Cursor, or Gemini.",
   "license": "MIT",
   "type": "module",