@garygentry/feature-forge 0.2.1 → 0.2.3

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

@@ -121,8 +121,7 @@ user requests additional flags, append them to the rendered run command.
 ## Launch detail (Step 3b — background process)
 
 Launch the loop **backgrounded** so it survives session end and does not block the
-session, and prefer the machine-readable event stream so the session can supervise
-it live.
+session, then supervise it live via the runner's structured event file.
 
 > **Clean-tree precondition.** rauf refuses to run with uncommitted changes
 > (*"Refusing to run the loop with uncommitted changes… pass --force"*). Step 3a's
@@ -132,22 +131,41 @@ it live.
 > changes after that commit, surface it and let the user commit/stash or pass
 > `--force`; never auto-pass `--force`.
 
-- **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
-  (it appends `--ndjson` to the run) and launch via the Bash tool with
-  `run_in_background: true`, redirecting stdout to a stable events file:
+**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
+renamed into `{stateDir}/archive/`). A redirect like `… --ndjson >
+{stateDir}/events.ndjson` therefore (a) is **redundant** — the runner writes that
+file regardless — and (b) **collides** with the runner's own writer: the shell holds
+a descriptor on the file the runner immediately rotates away, so the redirected
+`--ndjson` stdout is orphaned into a bogus `archive/` file while the live
+`events.ndjson` is the runner's native stream. It only *looks* clean by accident of
+rotation timing. So:
+
+- **Self-persisting runner (default — rauf writes `{stateDir}/events.ndjson`):**
+  launch the **plain `runCommand`** with `run_in_background: true` and **no
+  redirect** — the Bash tool already captures the run's stdout/stderr to the
+  background task's output file (use it to diagnose a launch refusal). Supervise by
+  arming the Monitor on the runner's **native** `{backlogDir}/{stateDir}/events.ndjson`
+  (Step 3d). Guard the very first run with the state dir:
 
   ```
-  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered runCommand}
   ```
 
-  (The `mkdir -p` guards the very first run, before the runner has created its
-  state dir.) This emits one JSON event per line **and** keeps the loop detached. The background
-  task's exit notification remains the single authoritative terminal signal (Step 4).
-- **Fallback (runner has no `eventStreamCommand`):** launch the plain `runCommand`
-  with `run_in_background: true`. The session will then supervise by tailing the
-  human log (3d fallback) instead of the NDJSON file.
+  (Note: the `--ndjson` stdout stream and `loopRunner.eventStreamCommand` are **not**
+  used on this path — the native file already carries the same structured records.)
+- **Stdout-only runner (no native event file):** render `eventStreamCommand` (it adds
+  `--ndjson`) and redirect its stdout to a file **outside `{stateDir}`** so it cannot
+  collide with any native file or be swept into `archive/`, then Monitor that file:
 
-Loop runs can take significant time (minutes to hours depending on backlog size).
+  ```
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/forge-events.ndjson 2>&1
+  ```
+
+The background task's exit notification remains the single authoritative terminal
+signal (Step 4). Loop runs can take significant time (minutes to hours depending on
+backlog size).
 
 ## Arm a Monitor on the event stream (Step 3d)
 
@@ -161,16 +179,24 @@ terminal and exception state, not just the happy path — otherwise a crash or h
 looks identical to "still running." Monitor command (NDJSON path):
 
 ```
-tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1 \
+tail -n +1 -F {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>/dev/null \
   | jq -rc --unbuffered 'select(.type | test("item_completed|item_blocked|needs_human|signal_parsed|loop_completed|loop_error|loop_cancelled|llm_stuck_warning"))'
 ```
 
+> **Use `tail -F` (follow by name), not `-f` (follow by descriptor).** The runner
+> **rotates** `events.ndjson` at the start of each run (renames the prior file into
+> `archive/`, creates a fresh one). A Monitor that attaches with `-f` during that
+> brief rotation window would follow the **archived** inode and then see silence —
+> indistinguishable from a healthy quiet loop. `-F` re-opens the live file by name,
+> so it always tracks the runner's current native stream. (Send `tail`'s own
+> rotation chatter to `/dev/null` so it can't reach the `jq` filter.)
+
 - **Fallback (log tail, no NDJSON):** match the runner's **structured prose
   prefixes**, never the `RAUF_*` tokens (those leak inside agent output and
   false-match). For rauf:
 
   ```
-  tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/{loopRunner.logFile} \
+  tail -n +1 -F {backlogDir}/{loopRunner.stateDir}/{loopRunner.logFile} 2>/dev/null \
     | grep -E --line-buffered 'Item [^ ]+ (completed|blocked):|Item [^ ]+ needs human input|Loop completed|Loop error:|Circuit breaker:'
   ```
 

package/adapters/copilot/skills/forge-init/forge-init.md

@@ -23,6 +23,9 @@ After initialization, the config file will contain defaults for:
 - `stack`: `null` (detected during `/feature-forge:forge-2-tech`)
 - `typeCheckCommand`: `null` (set during `/feature-forge:forge-2-tech`)
 - `testCommand`: `null` (set during `/feature-forge:forge-2-tech`)
+- `autoInvokeNextStage`: `true` (the navigator auto-starts the next stage after you confirm; set `false` to only print the command)
+- `contextWindowTokens`: `null` (the navigator infers the context window; set to your model's window, e.g. `1000000` for a 1M-context model, for accurate context-usage advice)
+- `contextWarnThreshold`: `0.7` (fraction of the window past which the navigator suggests a clean session)
 
 If `forge.config.json` already exists, the script will not overwrite it.
 

package/adapters/cursor/references/forge-config-schema.json

@@ -56,6 +56,23 @@
       "minimum": 1,
       "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
     },
+    "autoInvokeNextStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
+    },
+    "contextWindowTokens": {
+      "type": ["integer", "null"],
+      "default": null,
+      "description": "Context window size (tokens) used by the navigator's context-usage check to compute how full the current session is. Null (default) lets the helper infer from the session model and fall back to 200000 — and if observed usage already exceeds 200000 it auto-bumps the assumed window to 1000000 (proof a 1M-beta window is active). Set this explicitly to your model's window (e.g. 1000000 for a 1M-context model) for accurate percentages below 200000 too, since 1M cannot be detected from the transcript until usage crosses 200000."
+    },
+    "contextWarnThreshold": {
+      "type": "number",
+      "default": 0.7,
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraction of the context window (0-1) past which the navigator recommends starting the next stage in a clean session rather than continuing. Default: 0.7."
+    },
     "workspaces": {
       "type": "array",
       "description": "Monorepo members. Absent for single-package projects.",
@@ -94,7 +111,7 @@
         "eventStreamCommand": {
           "type": "string",
           "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
-          "description": "PREFERRED launch command for forge-5. Same as runCommand but emits one machine-readable JSON event per stdout line (NDJSON): item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). forge-5 redirects this stdout to {backlogDir}/{stateDir}/events.ndjson and arms a Monitor on it for live, structured supervision. If a runner cannot emit NDJSON, omit this field — forge-5 falls back to runCommand + tailing the human log."
+          "description": "Stdout NDJSON launch command for a runner that does NOT persist its own event file — same as runCommand but emits one machine-readable JSON event per stdout line: item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). NOTE: rauf (the default runner) ALREADY persists {stateDir}/events.ndjson natively and rotates it per run, so forge-5 launches the plain runCommand and monitors that native file — it does NOT use this field, and must NOT redirect --ndjson into {stateDir} (redundant, and it collides with the runner's own writer / archive rotation). This field is only for a stdout-only runner with no native event file; forge-5 then redirects its stdout to a file OUTSIDE {stateDir} and monitors that. Omit it entirely for a runner that self-persists or cannot emit NDJSON."
         },
         "validateCommand": {
           "type": "string",
@@ -173,8 +190,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.8.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.8.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.8.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.11.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.11.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.11.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/cursor/references/shared-conventions.md

@@ -68,6 +68,9 @@ Extract these config values (use defaults if not present):
 - `branchPerFeature` (default: true)
 - `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
+- `autoInvokeNextStage` (default: `true` — the `/feature-forge:forge` navigator auto-invokes the next stage via the `Skill` tool after the user confirms; `false` keeps copy-paste behavior. Navigator-only.)
+- `contextWindowTokens` (default: `null` — context window used by the navigator's context-usage check; `null` infers from the session model and falls back to 200000. Set to the model's window, e.g. `1000000` on a 1M model. Navigator-only.)
+- `contextWarnThreshold` (default: `0.7` — fraction of the window past which the navigator recommends a clean session. Navigator-only.)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
 
 ## Feature Directory Resolution

package/adapters/cursor/scripts/forge-init.sh

@@ -21,7 +21,10 @@ cat > "$CONFIG_FILE" << 'EOF'
   "stack": null,
   "typeCheckCommand": null,
   "testCommand": null,
-  "loopIterationMultiplier": 1.5
+  "loopIterationMultiplier": 1.5,
+  "autoInvokeNextStage": true,
+  "contextWindowTokens": null,
+  "contextWarnThreshold": 0.7
 }
 EOF
 
@@ -37,6 +40,9 @@ echo "  stack:               null (auto-detected during forge-2-tech)"
 echo "  typeCheckCommand:    null (auto-detected during forge-2-tech)"
 echo "  testCommand:         null (auto-detected during forge-2-tech)"
 echo "  loopIterationMultiplier: 1.5 (multiplier for loop iterations)"
+echo "  autoInvokeNextStage: true (navigator auto-starts the next stage after you confirm)"
+echo "  contextWindowTokens: null (infer; set to 1000000 on a 1M-context model)"
+echo "  contextWarnThreshold: 0.7 (suggest a clean session past this fraction of the window)"
 echo ""
 echo "The loop runner defaults to rauf. To target a different ralph-style runner,"
 echo "add a \"loopRunner\" block (see references/forge-config-schema.json)."