@garygentry/feature-forge 0.2.2 → 0.2.3

package/adapters/gemini/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/gemini/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/dist/manifest.d.ts

@@ -28,7 +28,7 @@ export interface BuildManifestArgs {
     readonly skills: readonly string[];
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (spec 03). */
     readonly sourceHash: string;
-    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.10.1"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.11.0"); `null` when `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** Symlink mode only: the source bundle the namespace dir links to (REQ-SAFE-02). */
     readonly link?: {

package/dist/rauf.d.ts

@@ -19,13 +19,13 @@ import { type Result } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.10.1.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.11.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.10.1` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.11.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export declare const RAUF_PIN = "@garygentry/rauf@0.10.1";
+export declare const RAUF_PIN = "@garygentry/rauf@0.11.0";
 /**
  * An injectable, READ-ONLY registry query (D1). Given a coordinate `name@version`, returns the
  * resolved version string on success, or an `InstallerError` if it is not resolvable.
@@ -37,7 +37,7 @@ export declare const RAUF_PIN = "@garygentry/rauf@0.10.1";
  * Contract: the query MUST be read-only — it MUST NOT install, MUST NOT mutate global npm
  * state, and MUST NOT execute rauf. `npm view` satisfies this (it only reads registry metadata).
  *
- * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.10.1"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.11.0"
  * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
  */
 export type RegistryQuery = (coordinate: string) => Result<string>;

package/dist/rauf.js

@@ -20,13 +20,13 @@ import { err, ok } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.10.1.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.11.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.10.1` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.11.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export const RAUF_PIN = "@garygentry/rauf@0.10.1";
+export const RAUF_PIN = "@garygentry/rauf@0.11.0";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *

package/dist/types.d.ts

@@ -216,7 +216,7 @@ export interface InstallManifest {
     readonly featureForgeVersion: string | null;
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (OQ-4, spec 03). */
     readonly sourceHash: string;
-    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.10.1"; `null` if `--skip-rauf` (spec 06). */
+    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.11.0"; `null` if `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** ISO-8601 timestamps. */
     readonly installedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",