@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/skills/forge-5-loop/references/agent-selection.md

@@ -0,0 +1,116 @@
+# forge-5-loop — Agent Selection (Step 2d, conditional)
+
+The agent-selection surface, its Claude-only model-alias guard, and the optional-
+flags catalog. Loaded ONLY when `loopRunner.agentArgument` is present (the Step 2d
+capability gate); when the gate is off, Step 2d is byte-identical to today and this
+file is never read.
+
+## Agent selection (Step 2d)
+
+This section is **parallel** to `## Model selection precedence` in
+`references/runner-contract.md`: it governs which **coding agent** rauf drives for the
+run. The entire surface is
+**presence-gated** on `loopRunner.agentArgument` — when that field is absent or
+empty, there is no selector, no probe, and no `{agent}` substitution, and Step 2d /
+Step 3c are byte-identical to today (capability gate;
+`02-config-schema-and-gating.md`, REQ-PLUG-02). The rest assumes the gate is on.
+
+**Precedence (highest wins):**
+
+```
+item.provider  >  --agent (run selection)  >  loopRunner.defaultAgent (project)  >  runner default (claude-cli)
+```
+
+**Run-layer mapping — why forge never re-implements rauf's resolver.** forge owns
+**only** its run and project layers and collapses them into **one** value
+(`resolve()`: `run_selection or defaultAgent or none`), which it emits as a single
+`--agent {agent}` occupying rauf's **run layer only**. rauf alone resolves
+item-vs-run via its own 5-layer resolver, sitting the per-item `BacklogItem.provider`
+**above** forge's run layer — so a run selection can never clobber a deliberate
+per-item agent. forge **never reads, writes, or overrides** `BacklogItem.provider`
+(REQ-AGENT-05). When forge sends nothing (the default path), rauf applies its own
+default `claude-cli`, byte-identical to today. Empty/whitespace selections are
+treated as unset, and an explicit pick of the runner default id collapses to the
+default path (append nothing, run no probe). See
+`03-selection-resolution-observability.md §3–§4`.
+
+**Availability pre-check + disambiguation.** For a **non-default** resolved id only,
+forge runs `loopRunner.agentsProbeCommand` **once** (no retries) and classifies the
+id by **membership** in the advertised set (`{ row.id for row in agents }`), then the
+matching row's `available` flag — **never** by exit code, because `rauf agents
+--json` always exits 0 (an unknown id is simply absent; a known-unavailable one is
+present with `available: false`):
+
+- **UNKNOWN** (`∉` advertised set): hard-reject **before any loop side-effect**,
+  listing the sorted valid ids; **no proceed-anyway**; the value never interpolates
+  into `{agent}` (the advertised set IS the allow-list — REQ-SEC-01).
+- **UNAVAILABLE** (member, `available == False`): warn with the row's `detail`, then
+  offer **proceed-anyway OR choose-another** — never silent.
+- **AVAILABLE** (member, `available == True`): proceed; the validated id fills
+  `{agent}`.
+- **Probe failure** (non-zero exit / unparseable / wrong shape / empty `agents[]` /
+  row missing `id`): surface it and offer **choose-another OR abort**; never launch
+  the non-default agent unvalidated, never silently fall back to the default.
+
+The default / `claude-cli` path runs **no** probe (zero extra cost). See
+`04-availability-precheck.md` for the full pre-check, classification, and allow-list,
+and `02-config-schema-and-gating.md` for the capability gate.
+
+> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
+> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
+> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
+> authenticates elsewhere — the probe's credential heuristic doesn't cover every
+> install. This is a rauf probe concern, not something forge-5-loop fixes. The
+> **default-agent path skips the probe entirely**, so an ordinary default run is
+> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
+> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
+> patch rauf's probe from here.
+
+### Claude-only model-alias guard (Step 2d, sub-step d-model)
+
+When the resolved agent is **non-default** (not the default / `claude-cli` path),
+forge must guard against a backlog whose items pin **Claude-specific** model aliases.
+forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
+(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
+`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
+agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
+supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
+rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
+of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
+the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
+launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
+(remove the key from each affected item so each spawn uses the agent's own default) or
+**proceed as-is**. forge only ever touches the `model` field — never `provider`. The
+default / `claude-cli` path skips this guard (the aliases are valid there).
+
+> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
+> 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
+> `## Launch detail (Step 3b — background process)` in `references/runner-contract.md`)
+> 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)
+
+These are the optional flags the user may add to the rendered run command. If the
+user requests additional flags, append them to the rendered run command.
+
+```
+  --agent <id>      Coding agent rauf drives this run (see `## Agent selection` above).
+                    Only the runner's advertised ids are valid; an unknown id is
+                    rejected before launch. Shown only when the runner advertises
+                    an agent surface (loopRunner.agentArgument present).
+  --review          Run a review pass after all iterations (extra agent session)
+  --model <model>   Override the model (see `## Model selection precedence` in
+                    `references/runner-contract.md`)
+  --timeout <min>   Per-session timeout in minutes (default: 60)
+  --retry-blocked   Unblock and retry previously blocked items
+```
+

package/adapters/pi/skills/forge-5-loop/references/ralph-loop-contract.md

@@ -0,0 +1,221 @@
+# The Loop-Runner Contract (consumer side)
+
+feature-forge's pipeline ends by handing a `backlog.json` to an autonomous
+**loop runner** that implements each item. feature-forge does not embed any
+runner's internals — it talks to the runner through one indirection point: the
+**`loopRunner`** block in `forge.config.json`.
+
+## The seam
+
+Every command feature-forge runs against the runner is a template in
+`loopRunner`, with `{bin}`, `{backlogDir}`, `{specsDir}`, and `{iterations}`
+substituted at call time. `forge-5-loop` (execution), `forge-4-backlog`
+(validation), and `forge-verify` (backlog validation) all render their commands
+from this block — there are no hardcoded `rauf …` commands in the skills, and
+even the human log filename is tokenized via `{loopRunner.logFile}`.
+
+When `forge.config.json` has no `loopRunner` block, feature-forge uses the
+built-in defaults (see `references/forge-config-schema.json`) and announces
+"defaulting to the rauf loop runner."
+
+## The contract a runner MUST satisfy
+
+A conforming runner MUST implement the **backlog-tool / loop-runner contract**
+defined authoritatively in rauf's
+[`SPEC-BACKLOG-TOOL-CONTRACT.md`](https://github.com/garygentry/rauf/blob/main/docs/SPEC-BACKLOG-TOOL-CONTRACT.md)
+(Part A). In summary, it must provide:
+
+- **A backlog schema** with the published `$id` and an optional `schemaVersion`,
+  whose `type`/`status` vocabularies match the contract
+  (`type ∈ bug|bugfix|refactor|feature|chore|test`,
+  `status ∈ pending|in_progress|done|blocked`).
+- **A `validate` verb** with exit codes `0` (valid) / `1` (findings) / `2`
+  (usage/IO) that emits `{ valid, findings[] }` under `--json`. This is the
+  single check feature-forge trusts — it never re-implements validation.
+- **The signal protocol** (`RAUF_DONE` / `RAUF_BLOCKED` / `RAUF_NEEDS_HUMAN` /
+  `RAUF_REVIEW`). These are emitted by the *coding agent* into its stdout and
+  parsed by the runner — they are not runner-authored log lines, so consumers key
+  off the runner's parsed events (below), never the raw `RAUF_*` tokens (which can
+  also appear inside an agent's prose and produce false matches).
+- **A machine-readable event stream** for live supervision (`loopRunner.eventStreamCommand`,
+  rauf: `loop run … --ndjson`): one JSON event per line with a stable `type`
+  vocabulary — `item_completed` / `item_blocked` / `needs_human` / `signal_parsed`
+  / `loop_completed` / `loop_error` / `loop_cancelled` / `llm_stuck_warning` (a
+  circuit-breaker halt surfaces as `loop_error`) — plus a
+  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`) and
+  per-iteration telemetry with a `stuckWarning` flag (`loopRunner.watchCommand`,
+  rauf: `status … --json` — the `loop watch` verb was removed in v0.5.0). `forge-5-loop` supervises the run through these,
+  **not** by parsing the human log. `followCommand` / `logCommand` are
+  human-formatted streams for a person watching in a terminal, not machine surfaces.
+- **The state-dir layout** (per-`--backlog` isolation under `loopRunner.stateDir`).
+- **The CLI verbs** mapped by `loopRunner`: run (+ event-stream) / validate /
+  status (+ `--json`) / list / follow / log / version.
+- **A `version` verb** (`{bin} version --json` → `{ version: <semver> }`) so
+  feature-forge can enforce `loopRunner.minRunnerVersion` before running.
+
+> **The runner does not pause for human input.** When the coding agent signals
+> `RAUF_NEEDS_HUMAN`/`RAUF_BLOCKED`/`RAUF_REVIEW`, a conforming runner sets that
+> item aside and **keeps working other runnable items to completion** (rauf:
+> `runner.ts` needs_human handler). So a supervising session can surface those
+> events live (visibility) and cancel early, but it cannot inject an answer and
+> resume the set-aside item mid-run — resolution is a follow-up retry pass. A
+> first-class pause/resume-with-answer capability is a desirable runner
+> enhancement (see `plans/rauf-enhancement-recommendations.md`).
+
+## rauf is the default and reference implementation
+
+rauf owns the contract spec and is the runner feature-forge defaults to. The
+authoring craft itself (how to decompose specs into well-scoped, verifiable
+items) lives in rauf's **`author-backlog`** skill, which `forge-4-backlog`
+delegates to — so the only thing binding feature-forge to a particular runner is
+the schema + `validate` verb that this contract formalizes. A future runner swap
+supplies its own `loopRunner` block (its own `bin`, schema, and `validate`
+command) without touching any pipeline skill.
+
+The coding-agent dimension this contract adds (below) is **additive and
+presence-gated**: it exists only when the `loopRunner` block advertises it via
+`agentArgument`. A runner that omits that field has no agent dimension at all —
+the seam degrades to exactly today's behavior with no error, so default-to-rauf
+and pluggability are unchanged. See `## Agent selection`.
+
+## Agent selection
+
+This section is **contract-level**: it states what a conforming runner exposes
+and what forge does with it, and defers every algorithm to the owning specs
+(`02`/`03`/`04`/`05`).
+
+### What a conforming runner exposes (the consumed surface)
+
+A runner that carries a coding-agent dimension exposes, in its `loopRunner`
+block:
+
+- an **`agentArgument`** template (rauf default `--agent {agent}`) — the
+  tokenized launch-time flag; its **presence** advertises the agent surface;
+- an **`agentsProbeCommand`** (rauf default `{bin} agents --json`) emitting
+  `{ agents: [{ id, displayName, available, detail? }] }` and **always exiting
+  0**;
+- an optional **`defaultAgent`** project-default id.
+
+These three fields are specified in full in `references/forge-config-schema.json`
+and are the schema half of this contract. forge consumes rauf's existing
+`--agent <id>` flag, `rauf agents` probe, `BacklogItem.provider`, and 5-layer
+precedence — it conforms to them, it does not redesign them.
+
+### Precedence and the run-layer mapping
+
+The agent-selection precedence is **`item > run > project > default`**,
+deliberately parallel to the model-selection precedence (`item.model >
+--model/options > project default > provider default`). It is realized as:
+
+- **item** — `BacklogItem.provider`, applied by **rauf** from the backlog. forge
+  **never reads, writes, or overrides** it (pass-through), so a deliberate
+  per-item agent always wins.
+- **run** — forge's per-run selector (`forge-5-loop` Step 2d).
+- **project** — forge's `loopRunner.defaultAgent`.
+- **default** — the runner's own default (`claude-cli` for rauf) when forge sends
+  nothing.
+
+forge owns **only** the run and project layers. It collapses run-over-project
+*inside itself* into the **single** `--agent {agent}` value it emits at the
+**run layer**, and lets rauf apply the item override *above* that. forge **never
+re-implements rauf's resolver**. The resolution algorithm itself lives in
+`03-selection-resolution-observability.md`.
+
+### Availability probe + unknown/unavailable disambiguation
+
+When the resolved agent is a **non-default** id, forge runs `agentsProbeCommand`
+**once (no retries)** before any loop side-effect, parses the advertised
+`agents[]`, and builds the advertised id set. Because the probe **always exits
+0**, an unknown id is distinguished from a known-but-unavailable one **only by
+set membership**, not by exit code:
+
+- **Unknown id** (not in the advertised set — a typo or unsupported agent):
+  **hard-reject before launch**, listing the valid ids. No proceed-anyway path.
+  No value is interpolated into `{agent}`.
+- **Known but unavailable** (`available: false`): **warn** (showing the probe's
+  `detail`) and let the user **proceed-anyway or choose another** — never
+  silently abort, never silently proceed.
+- **Available**: proceed.
+
+The advertised id set is also the **allow-list**: the only value ever
+interpolated into `{agent}` is a validated, advertised id. The **default /
+claude path never reaches the probe** — it incurs no extra cost. The
+`classify(...)` algorithm and the rejection-error text live in
+`04-availability-precheck.md`.
+
+### Capability gate + version floor
+
+Agent selection is **capability-gated** on the runner advertising
+`agentArgument`: a runner whose `loopRunner` omits (or empties) that field
+exposes no agent surface, so the per-run selector, the probe, and any `{agent}`
+substitution **vanish entirely** and no agent argument is sent — byte-identical
+to today. Degradation is **silent, not an error**, keeping alternate (non-rauf)
+runners first-class. The gate condition is owned by
+`02-config-schema-and-gating.md`.
+
+Independently, the **version gate** floors at the runner version that ships the
+agent surface. For rauf that is **0.6.0** (`loopRunner.minRunnerVersion`): the
+`--agent` flag, the `agents` probe, and the preset agent registry are present in
+rauf source at 0.6.0. A successful gate therefore guarantees those surfaces
+exist before any run. See `## Version gating` and
+`05-runner-discovery-version-gate.md`.
+
+**This document — the `## Agent selection` section, the `## Per-stage agent
+applicability` table, and the `## validate is agent-agnostic` note — together
+with the augmented `loopRunner` schema block in
+`references/forge-config-schema.json` constitute the `forge-loop-runner-contract`
+expose, consumed by the `packaging-docs-ci` capstone as documentation input.**
+
+## Per-stage agent applicability
+
+Every forge stage that invokes the loop runner is classified here. Only
+`forge-5-loop` (execution) carries the coding-agent dimension; the two
+validation-only stages are agent-agnostic.
+
+| Stage | Runner verbs | Agent dimension |
+|-------|-------------|-----------------|
+| `forge-5-loop` | run / eventStream / status / version | **Full** — selector, probe, `--agent` |
+| `forge-4-backlog` | `validate` | **None** — agent-agnostic |
+| `forge-verify` | `validate` | **None** — agent-agnostic |
+
+- **`forge-5-loop`** is the executor: it drives the run, so it renders the run /
+  event-stream / status / version verbs (and `list`) and carries the full agent
+  surface — the Step 2d selector, the availability probe, and the rendered
+  `agentArgument`.
+- **`forge-4-backlog`** authors and then *validates* the backlog; its only runner
+  call is `validateCommand`. It also reads `versionCommand` for a graceful-degrade
+  check, but **passes no agent** and never runs `loop run`.
+- **`forge-verify`** (backlog mode) re-runs the same `validateCommand` to surface
+  validation findings. It carries no agent dimension. This is **contract
+  coverage** of forge-verify (it is classified here), with an explicit agnostic
+  note (below) — **not** a new agent-driven run in forge-verify.
+
+### `validate` is agent-agnostic
+
+The `validate` verb (`loopRunner.validateCommand`) checks a `backlog.json`
+against the backlog schema and spec references. **It does not run a coding agent
+and has no agent dimension.** No agent argument — `--agent`, the `{agent}` token,
+or any agent id — may **ever** be passed to backlog validation, in **any** stage
+(`forge-4-backlog`, `forge-verify`, or any future caller). Backlog validation is
+a pure, deterministic check; the coding agent is irrelevant to it. A contributor
+who later adds agent selection to a *new* stage MUST confirm that stage runs the
+*execution* surface (like `forge-5-loop`), not `validate` — agent selection
+belongs to execution only. If you find yourself adding `--agent` near a
+`validateCommand` render, that is a bug.
+
+## Version gating
+
+feature-forge requires a runner exposing `backlog validate` + backlog
+`schemaVersion`, and the unified exit-code/status contract it reads. The floor is
+now the **agent-surface floor**: the runner version that ships the `--agent`
+flag, the `agents` probe, and the preset agent registry. For rauf that is
+**0.6.0** (`loopRunner.minRunnerVersion`).
+`forge-5-loop` runs `{bin} version --json`, semver-compares the reported version
+against `minRunnerVersion`, and on a missing-or-too-old runner stops with
+`loopRunner.installHint` (the CLI install/upgrade command) — **before** invoking
+the loop. See `COMPATIBILITY.md` for the version matrix.
+
+> **Two different "installs."** `installHint` obtains/upgrades the runner **CLI
+> binary** (e.g. rauf's `install-binary.sh`). `setupHint` installs the runner's
+> **per-project artifacts** (rauf: `rauf install .`). A failing version gate is
+> always the former, never the latter.

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

@@ -0,0 +1,85 @@
+# forge-5-loop — Step 4b Result-Report Templates
+
+These are the five verbatim result-report output templates for **Step 4b** of
+`forge-5-loop/SKILL.md`. Pick **every** branch that applies (a run can be both
+blocked and needs-human) and render its report.
+
+**All items done.** Print the completion summary, then close with the **warm-acceptable
+variant** of the Stage Exit Protocol (single-sourced in
+`references/stage-exit-protocol.md`) — the `forge-5-loop → forge-6-docs` boundary is the
+one place where clearing before the next stage is optional:
+```
+Loop completed for {feature}. All {N} items implemented successfully.
+```
+
+**The loop is complete — this is the one boundary where clearing before the next stage is optional.**
+
+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 the next command** — in this warm session, or a fresh one if you prefer:
+
+   ```
+   /skill: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
+findings to the user — distinct from `forge-verify impl` (a clean-context audit that
+writes a findings doc). When Step 4a captured a `review_completed` event, add a line
+**above** "Next steps" so the pass's effect is visible and not mistaken for "nothing
+happened":
+```
+Runner review pass: {itemsCreated} fix item(s) created and implemented.
+  {summary}
+```
+Omit this line when no `review_completed` event was emitted (no review flag passed).
+The created items are already counted in the totals above.
+
+**Some items need a human:**
+```
+Loop completed for {feature}.
+  Completed:   {done}/{total}
+  Needs human: {needsHuman} items (set aside during the run)
+
+These items asked a question the loop couldn't answer:
+  - {id}: {title} — {reason}
+
+Resolve, then retry:
+  - Answer the question(s) above, then re-run `/skill:forge-5-loop {feature}`
+    (add --retry-blocked to pick the set-aside items back up).
+```
+
+**Some items blocked:**
+```
+Loop completed for {feature}.
+  Completed: {done}/{total}
+  Blocked:   {blocked} items
+
+Blocked items:
+  - {id}: {title}
+  - {id}: {title}
+
+Options:
+  - Re-run with --retry-blocked to retry blocked items
+  - Review blocked items manually: {bin} backlog show . {id} --backlog {backlogDir}
+  - Continue to docs if blocking items are non-critical
+```
+
+**Some items deferred (runner gave up after retries — "false blocks"):**
+```
+Loop completed for {feature}.
+  Completed: {done}/{total}
+  Deferred:  {deferred} items (no signal after retries — likely just need another pass)
+
+Re-run `/skill:forge-5-loop {feature}` to retry deferred items.
+```
+
+**Some items still pending (iteration limit reached):**
+```
+Loop completed for {feature}.
+  Completed: {done}/{total}
+  Pending:   {pending} items (iteration limit reached)
+  Blocked:   {blocked} items
+
+Re-run `/skill:forge-5-loop {feature}` to continue with remaining items.
+```