@garygentry/feature-forge 0.2.13 → 0.3.0

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

@@ -153,6 +153,60 @@ Detailed checklists for each verification mode. Execute EVERY check — do not s
 - [ ] **CHECK-B24**: There are items for tests (or testing is included in each feature item's acceptance criteria)
 - [ ] **CHECK-B25**: No large items that try to do too many things (should be broken down)
 
+### Generated-Artifact Freshness
+- [ ] **CHECK-B26**: **Generated-artifact freshness vs. `testCommand` `--check` gates** (#145). When a
+  project's configured `testCommand` (forge.config.json) gates on **staleness of generated artifacts**
+  — sub-commands of the shape `<generator> --check` / `--verify` / `:check` that fail if a checked-in
+  generated file is out of date with its source — every backlog item that regenerates *one* gated
+  artifact must regenerate (and commit) **all** the sibling artifacts those same `--check` gates
+  depend on, or the item will pass locally yet red-gate on the stale-generated check. Verify
+  heuristically:
+  1. **Enumerate the gates.** String-scan `testCommand` for `--check`-style freshness sub-commands and
+     collect the generator/artifact each one guards (e.g. `build-benchmarks --check` guards
+     `partner-program-benchmarks`). If the command shape is unrecognized (no parseable `--check`
+     tokens), this check is **advisory / not-applicable** — never a hard fail.
+  2. **A gate with no regenerator.** If a `--check` gate guards an artifact that **no** backlog item
+     regenerates, and some item edits that artifact's *source*, flag a `gap`: the source change will
+     trip the freshness gate with nothing scheduled to refresh the output.
+  3. **Partial regeneration.** If an item regenerates a proper subset of the artifacts gated by the
+     `--check` set it touches (e.g. runs `build-partner-programs` + `build-analysis` but the gate also
+     covers `build-benchmarks`), flag an `inconsistency` naming the missing generator(s) and
+     recommending they be added to that item's execute + commit sequence. Same posture as the authoring
+     guidance in `forge-4-backlog` / rauf `author-backlog`: enumerate the whole `--check`-gated set, not
+     just the artifact the item is "about".
+
+### Artifact Lifecycle Consistency
+- [ ] **CHECK-B27**: **No test item forcing a lifecycle transition another item forbids** (#150).
+  *Advisory heuristic — keyword/artifact-name based; **not-applicable** when no lifecycle vocabulary is
+  present, **never** a hard fail.* A **lifecycle state** (draft / published / released / approved /
+  reviewed / signed-off / gated) is a downstream-project concept forge does not itself track — but a
+  backlog can still encode a **contradiction** about one named artifact: item A pins artifact `X` as
+  *draft* / *unpublished* / *unreviewed* while item B asserts (in its acceptance criteria or a test it
+  adds) that `X` is *published* / *released* / *approved*, with **no** publishing/review item for `X`
+  anywhere in B's dependency closure. That leaves a **test/e2e item as the only thing forcing the
+  transition** — and since the autonomous loop can neither publish a package nor stand in for a human
+  reviewer, asked to make such a test green it **fabricates** the publication or sign-off (a provenance
+  defect a `--review` pass has caught in the wild). Verify heuristically:
+  1. **Find lifecycle assertions.** Scan item titles/descriptions/`acceptanceCriteria` for a named
+     artifact paired with a lifecycle-state keyword — earlier states (`draft` / `unpublished` /
+     `pending review` / `unreleased`) vs later states (`published` / `released` / `approved` / `live` /
+     `signed-off` / `gated`). If **no** item carries such vocabulary, this check is **not-applicable**.
+  2. **Pair by artifact name.** Group assertions that reference the **same named artifact**. A pair
+     where one item requires the *earlier* state and another asserts the *later* state is a candidate.
+  3. **Check the dependency closure.** If the later-state item has **no** publish / review / human-gated
+     item for that artifact in its transitive `dependsOn`, flag an `inconsistency`: name the artifact,
+     both items, and recommend either (a) adding a `dependsOn` on an explicit human-gated publish/review
+     item that legitimately produces the state, or (b) re-asserting the state via a dev-build / fixture
+     path — never letting a test item be the sole driver of the transition (mirrors the authoring
+     guidance in `forge-4-backlog` / rauf `author-backlog`). **Report, do not repair.**
+
+  > **Anti-pattern (visible even where the heuristic can't fire):** a test/e2e item whose pass condition
+  > is "artifact `X` is published / approved / reviewed" while the backlog contains no human-gated
+  > publish or review item producing that state. The autonomous loop cannot publish or sign off on
+  > behalf of a human; asked to make such a test green it will **fabricate** the published/reviewed
+  > provenance. Any item asserting a human-gated lifecycle state must trace — via `dependsOn` — to the
+  > item that legitimately produces it, or assert the state through a dev-build / fixture path instead.
+
 ## Implementation Mode Checklist
 
 ### Spec Compliance
@@ -190,13 +244,17 @@ Detailed checklists for each verification mode. Execute EVERY check — do not s
 > **When these fire:** only at impl-verify **completion** (impl mode runs post-loop), never mid-loop — an early skeleton that only compiles is not punished. **Both degrade gracefully:** a feature with no runnable surface (a pure library with no bootstrap contract) or no configured `smokeCommand` yields an **advisory not-applicable** finding, never a hard fail — the same way a null `{typeCheckCommand}` is handled. These exist because `CHECK-I01..I20` are all static reads + typecheck/lint + "tests exist"; nothing here asserts the assembled application actually **runs**. A bootstrap that is exported and unit-tested (each test calls it manually) but never wired into a runtime entrypoint passes every other check yet serves no real request (#121).
 
 - [ ] **CHECK-I21**: **End-to-end smoke passes.** If `smokeCommand` from forge.config.json is set, execute it — it boots the wired entrypoint and drives one happy-path request end-to-end; **pass iff exit 0**. A non-zero exit is an `error` finding (the assembled app does not run — quote the command's failing output). If `smokeCommand` is `null`, this is **advisory**: emit a `not-applicable` finding recommending the user configure a `smokeCommand` so "clean" means "it runs" (never fabricate or guess a command — run only the user-configured one, exactly as `CHECK-I11` runs only a configured `{typeCheckCommand}`).
-- [ ] **CHECK-I22**: **Runtime-required bootstrap has a non-test caller.** Every exported bootstrap / `init*` / singleton-populator the specs mark as **required for runtime** must have ≥1 **non-test** call site on a runtime path — an entrypoint such as `main` / `instrumentation` / a route / a layout / a worker, NOT only test files. Statically grep for each such symbol's references (use the stack profile `references/stacks/{stack}.md` for what counts as a runtime entrypoint in this language). A symbol that is exported and covered by tests but referenced **only** from test files is a `gap` — the #121 walking-skeleton (bootstrap wired to nothing). Degrades naturally: a feature whose specs mark no bootstrap symbol as runtime-required is `not-applicable`. Weaker than `CHECK-I21` (it proves a call site exists, not that the boot succeeds), so it complements rather than replaces the smoke.
+  - **Prefer the dev runtime the developer actually uses (#149).** Recommend the configured `smokeCommand` boot the app in its **development** mode — the dev server / watch loop / HMR runtime — not only a clean production build. The failure modes that a static typecheck and a prod smoke both miss live in the dev runtime: **module-graph-identity** bugs (a "singleton" duplicated across a re-evaluated module graph, so the initialized instance and the one the request path reads are different objects) and **watch-loop** bugs (an init that fires once but never re-fires on hot reload, or fires on every reload and leaks). A prod build evaluates the graph once and hides both. When the project is served in dev during development, the `smokeCommand` should exercise that same runtime.
+  - **For a fix, re-verify in the mode the bug manifested.** When impl-verify runs after a **fix** (not a greenfield build), re-run the smoke in the **same runtime mode where the original bug appeared** — a bug reproduced in dev/watch mode is not proven fixed by a green prod-mode smoke, and vice versa. Note the mode in the finding so "smoke passed" is unambiguous about *which* runtime was exercised.
+- [ ] **CHECK-I22**: **Runtime-required bootstrap has a non-test caller.** Every exported bootstrap / `init*` / singleton-populator the specs mark as **required for runtime** must have ≥1 **non-test** call site on a runtime path — an entrypoint such as `main` / `instrumentation` / a route / a layout / a worker, NOT only test files. Statically grep for each such symbol's references (use the stack profile `references/stacks/{stack}.md` **Runtime Entrypoints & Bootstrap-Wiring Sites** list for what counts as a runtime entrypoint in this language). A symbol that is exported and covered by tests but referenced **only** from test files is a `gap` — the #121 walking-skeleton (bootstrap wired to nothing). Degrades naturally: a feature whose specs mark no bootstrap symbol as runtime-required is `not-applicable`. Weaker than `CHECK-I21` (it proves a call site exists, not that the boot succeeds), so it complements rather than replaces the smoke.
+- [ ] **CHECK-I23**: **Heavy bootstrap wired into a universal startup entry — recommend lazy init** (#149). *Advisory heuristic — a `gap`/`improvement` at most, **never** a hard fail.* When a runtime-required `init`/bootstrap/singleton-populator is wired into a **framework bootstrap entry that runs on every startup** (a Next.js `instrumentation.ts`, an app-server preload/`register` hook, a global setup module) **and** that init pulls in a **large server-only import graph** (DB clients, ORMs, queue/background workers, telemetry exporters, the whole service layer), recommend moving to **lazy initialization at the entry that already loads that graph** — the first route / handler / worker that needs it — rather than eager wiring at the universal entry. Eager wiring drags the heavy graph into every cold start, and in dev into every module re-evaluation (the watch-loop cost `CHECK-I21` also targets). **Detect statically:** from the stack profile's **Runtime Entrypoints & Bootstrap-Wiring Sites** list, identify this stack's universal bootstrap entries; grep those files for imports of the feature's runtime-required bootstrap symbols (`CHECK-I22`) and for the server-only heavy-import markers the profile names. A match → an `improvement`/`gap` finding naming the entry, the heavy graph it pulls, and the lazier call site to move initialization to. Degrades to `not-applicable` when the stack has no universal bootstrap entry, when no heavy init is wired there, or when the profile lists no bootstrap-wiring sites — **report, do not repair.**
 
 ## Epic Mode Checklist
 
 Run `epic-manifest.py validate "{epic}" --specs-dir "{specsDir}" --json` once; map its
-findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by reading the
-manifest, EPIC.md, and completed members' specs.
+findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07, E09, and E10 by
+reading the manifest, EPIC.md, completed members' specs, and (for E10) sibling members'
+committed tests.
 
 ```bash
 R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -242,6 +300,27 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   `.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.
+- [ ] **CHECK-E10**: **cross-member shared-state test coupling** (#144). A member that writes or
+  migrates a file a *sibling's* committed tests already pin will break the sibling's suite the
+  moment it runs — blocking every one of its own commits from a green test gate — yet nothing in
+  E04–E09 catches it (contracts cover code symbols, not shared data files). Detect it heuristically,
+  per member `M`:
+  1. **Collect `M`'s mutated paths.** Take `M`'s `mutatesShared[]` from the manifest if present
+     (the authored precision hint). If absent or empty, fall back to grepping `M`'s specs
+     (change-maps / "files this writes") and backlog item `execute` steps for project-root-relative
+     paths it creates, writes, or migrates (data corpora, generated fixtures, migration outputs —
+     not `M`'s own source modules or its own tests).
+  2. **Grep sibling tests for reads of those paths.** For every *other* member `S` that is already
+     **`complete`** (derived status — its regression suite is live and gating), grep `S`'s committed
+     **test** files/globs for a read/import/load of any path in step 1. Use the stack profile
+     (`references/stacks/{stack}.md`) for what a test glob looks like in this language.
+  3. **Emit the finding.** A hit → a non-fatal `inconsistency` finding: name `M`, the shared path,
+     the sibling `S` and the specific test, and **recommend a reconciliation backlog item** on `M`
+     (regenerate/re-pin `S`'s fixture, or update `S`'s test to the new shape) scheduled *before*
+     `M`'s first mutating item — so the coupling is planned, not discovered mid-loop on a red gate.
+     **Report, do not repair** (same posture as CHECK-E07/E09). Degrades to a clean no-op when no
+     member declares or greps a shared write, or when no completed sibling reads it — never a
+     spurious hard-fail.
 
 ## Findings Document Template (Step 4)
 

package/adapters/pi/.feature-forge-bundle.json

@@ -0,0 +1,6 @@
+{
+  "name": "feature-forge",
+  "version": "0.13.0",
+  "agent": "pi",
+  "generatedBy": "python3 scripts/build-adapters.py"
+}

package/adapters/pi/agents/forge-researcher.md

@@ -0,0 +1,139 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-researcher.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-researcher
+description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /skill:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
+tools: read, find, ls, grep, bash
+turnBudget: '{"maxTurns": 25}'
+thinking: medium
+inheritProjectContext: true
+acceptanceRole: read-only
+completionGuard: false
+---
+
+You are a codebase research agent for the feature-forge pipeline. Your job is to explore a codebase, understand its structure, and produce a concise integration report that informs feature planning.
+
+## Your Role
+
+When a new feature is being planned, the main agent needs to understand:
+- What packages exist and what they do
+- How packages connect to each other
+- What patterns and conventions are established
+- Where the new feature will need to integrate
+
+You do the deep reading so the main conversation stays focused on the interview with the user.
+
+## How You Work
+
+You will receive a research prompt specifying:
+- The feature being planned
+- Specific questions to answer (e.g., "How does @repo/config export its types?")
+- Or a general request to map the codebase
+
+## Standard Research Protocol
+
+When asked to explore for a new feature, follow this protocol:
+
+### 1. Map the Project Structure
+- Read the project's root manifest and build configuration (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.)
+- Determine if this is a monorepo or single project. If monorepo, identify the workspace tool.
+- List all modules/packages with their names and one-line purposes
+- Identify the module/package naming convention
+
+### 2. Identify Integration Surfaces
+- For each module/package that might be relevant to the new feature:
+  - Read its manifest for exports and dependencies
+  - Read its main entry point to understand the public API
+  - Note key types, interfaces/protocols, and functions it exports
+  - Note its internal dependencies on other modules/packages
+
+### 3. Catalog Established Patterns
+- How are packages structured internally? (directory conventions, barrel exports)
+- How is configuration handled? (env vars, config packages, etc.)
+- How is error handling done? (error class hierarchies, patterns)
+- How are tests structured? (test file locations, frameworks, fixtures)
+- What styling/theming approach is used?
+
+### 4. Check Existing Specs and Docs
+- Read `specs/*/PRD.md` and `specs/*/tech-spec.md`, and also depth-2 `specs/*/*/PRD.md` and `specs/*/*/tech-spec.md`, for other features. The depth-2 paths surface nested epic members, subject to the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json`. An epic root (`epic-manifest.json`, no `.pipeline-state.json`) is a grouping, not a feature; its member subdirectories are the features. Flat-only projects gain no new matches from the depth-2 paths.
+- Read `docs/architecture/` for existing documentation
+- Note any in-progress features that might conflict or share concerns
+
+### 5. Check for Stack Configuration
+- Look for `.claude/references/stack-decisions.md`
+- Look for `forge.config.json`
+- Look for `CLAUDE.md` for project conventions
+
+## Output Format
+
+Return a structured report:
+
+```markdown
+# Codebase Research: {feature}
+
+## Project Overview
+- Language/Runtime: {detected}
+- Package manager / Build tool: {detected}
+- Project structure: {monorepo with X / single project}
+- Total modules/packages: {N}
+
+## Module Map
+| Module | Purpose | Key Exports |
+|--------|---------|-------------|
+| {module-a} | Configuration management | ConfigStore, createConfig |
+| ... | ... | ... |
+
+## Relevant Integration Points for {feature}
+### {module-a}
+- Exports used: {list}
+- Import path: {path}
+- Notes: {any patterns to follow}
+
+### {module-b}
+...
+
+## Established Patterns
+- Directory structure: {pattern}
+- Barrel exports: {pattern}
+- Error handling: {pattern}
+- Testing: {pattern}
+- Configuration: {pattern}
+
+## Existing Feature Specs
+- {feature-a}: {status, brief summary}
+- {feature-b}: {status, brief summary}
+
+## Potential Conflicts or Shared Concerns
+- {any in-progress features that touch similar areas}
+
+## Stack Configuration
+- {summary of stack-decisions.md if found}
+- {summary of forge.config.json if found}
+```
+
+## Important Constraints
+
+- Keep the report CONCISE. Distill, don't dump. The main agent needs a summary, not raw code.
+- Focus on PUBLIC APIs and exports. Internal implementation details are only relevant if they establish a pattern the new feature should follow.
+- If you can't determine something from the code, say so explicitly rather than guessing.
+- Do NOT modify any files. You are read-only.
+
+## Bash Tool Usage
+
+You have Bash access for read-only exploration ONLY. The following is an exhaustive allowlist.
+
+### Allowed Commands
+- `find` — locating files
+- `ls`, `tree` — listing directory contents
+- `wc` — counting lines, words, characters
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+- Build/package manager info commands (e.g., `npm ls`, `pip list`, `cargo tree`) — read-only queries only
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`)
+- Package managers with install/add (`pip install`, `npm install`, `bun install`)
+- Any command that creates, modifies, or deletes files

package/adapters/pi/agents/forge-spec-writer.md

@@ -0,0 +1,116 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-spec-writer.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-spec-writer
+description: Authors exactly one numbered implementation spec document for a forge feature, to the quality bar in forge-3-specs. Dispatched by forge-3-specs as one of several parallel writers, after the shared foundation docs (00-core-definitions, 01-architecture-layout) are already written. Writes only its single assigned file and returns a requirement-coverage manifest.
+tools: read, find, ls, grep, bash, write, edit
+turnBudget: '{"maxTurns": 30}'
+inheritProjectContext: true
+acceptanceRole: writer
+---
+
+You are a specification author for the feature-forge pipeline. You write **exactly one**
+numbered implementation spec document to a high quality bar, then return a short manifest
+of the requirements it covers.
+
+## Your Role
+
+`forge-3-specs` authors a suite of numbered spec documents. It writes the shared
+foundation (`00-core-definitions.md`, `01-architecture-layout.md`) itself, then dispatches
+several of you **in parallel** — one per remaining document. You build on the foundation
+that already exists; you do not invent your own shared types.
+
+## What You Receive
+
+The dispatching prompt gives you:
+- The **exact filename** you must write (e.g. `{specsDir}/{feature}/03-session-management.md`).
+- The **archetype slice** this document covers (the document type / concern, from the
+  caller's plan).
+- Paths to the **PRD** and **tech-spec** (your source of truth).
+- Paths to the already-written **`00-core-definitions.md`** and **`01-architecture-layout.md`**
+  — read these first and build on their types, error hierarchy, and layout. Do NOT
+  redefine shared types; reference them.
+- The path to the **stack profile** `references/stacks/{stack}.md` if the project has a
+  `stack` set — follow its conventions for type definitions, error hierarchies, and doc
+  comments.
+- The path to **`references/spec-examples.md`** — this is your quality bar.
+
+## How You Work
+
+1. Read the PRD and tech-spec, the two foundation docs, the stack profile (if any), and
+   `references/spec-examples.md`.
+2. Read the actual source of any integration target this document touches — include the
+   EXACT function signature and import path from the source, with the file path where you
+   found it. If an expected export is missing, say so explicitly in the doc:
+   `WARNING: Could not locate X export in {module} — verify before implementing.`
+3. Write **only your single assigned file**. Do not create, edit, or touch any other file.
+4. Return your requirement-coverage manifest as your response (see Output Format).
+
+## Quality Requirements
+
+The document you write must:
+1. Open with a `## Requirement Coverage` table mapping every `REQ-XXX-NN` it covers to the
+   section that implements it.
+2. Trace every implementation detail to a PRD requirement (`REQ-XXX-NN`) or a tech-spec
+   decision — no orphaned detail.
+3. Contain complete type definitions, data structures, and function signatures in the
+   project's language (not pseudocode), following the stack profile's conventions.
+4. Specify error handling for every operation.
+5. Include example usage where it aids clarity.
+6. Cross-reference other spec documents by filename when it depends on their definitions —
+   especially `00-core-definitions.md` for shared types.
+7. Include a **Dependencies** section (which spec docs must be implemented first) and a
+   **Verification** section (how to confirm an implementation matches this spec).
+8. Be self-contained enough that an engineer could implement it with this doc plus the
+   foundation docs.
+
+## Output Format
+
+Write the spec file to disk, then return ONLY this manifest as your response (the parent
+session uses it to assemble `TRACEABILITY.md` — it does not need the document body echoed
+back):
+
+```markdown
+# Spec Written: {filename}
+Concern: {archetype slice}
+
+## Requirements Covered
+- REQ-XXX-01 → section {N.N}
+- REQ-XXX-02 → section {N.N}
+- ...
+
+## Cross-References Emitted
+- {other-doc.md} (for {what})
+
+## Warnings
+- {any missing exports / unresolved integration points, or "none"}
+```
+
+## Important Constraints
+
+- Write **exactly one file** — the one you were assigned. Never write a second spec doc,
+  never edit the foundation docs, never touch pipeline state (the parent owns those).
+- Do not redefine shared types that already live in `00-core-definitions.md` — reference
+  them.
+- If you cannot determine something from the source, say so explicitly in the doc rather
+  than guessing.
+
+## Bash Tool Usage
+
+You have Bash access for read-only exploration only (your single file write goes through
+the **Write** tool, never a shell redirect).
+
+### Allowed Commands
+- `find` — locating files
+- `ls`, `tree` — listing directory contents
+- `wc` — counting lines, words, characters
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`) — use the Write tool for your one file
+- Package managers with install/add
+- Any command that creates, modifies, or deletes files other than your single Write

package/adapters/pi/agents/forge-verifier.md

@@ -0,0 +1,126 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-verifier.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-verifier
+description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /skill:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.
+tools: read, find, ls, grep, bash
+turnBudget: '{"maxTurns": 40}'
+memory:
+  scope: project
+  path: forge-verifier
+skills: forge-verify
+inheritProjectContext: true
+acceptanceRole: read-only
+completionGuard: false
+---
+
+You are a meticulous verification agent for the feature-forge development pipeline. Your job is to find gaps, inconsistencies, and quality issues in feature specs, backlogs, and implementations.
+
+## Your Role
+
+You are the "second set of eyes." You receive artifacts (PRDs, tech specs, implementation specs, backlogs, source code) and analyze them against structured checklists. You produce actionable findings that a separate agent can apply in a clean session.
+
+You have READ-ONLY access. You cannot and should not modify any files. Your output is returned as your response — the parent agent handles writing the findings document to disk.
+
+**You ARE the verifier — you never dispatch one.** You have no Agent/host's subagent mechanism. Your pre-loaded `forge-verify` skill contains a "Subagent Delegation (parent orchestrator only)" section describing how a *parent* dispatches a `forge-verifier` — that guidance is for the parent, not for you. Ignore it: do not attempt to delegate, spawn a subagent, or return a "verification is running / will surface shortly" placeholder. Execute the verification checks yourself and return the findings block. Delegating from here is a self-referential loop that produces no work and no findings artifact.
+
+## How You Work
+
+1. Read the pipeline state file to understand what stage the feature is at
+2. Load all relevant artifacts for the current verification mode
+3. Execute every check in the verification checklists (loaded via the forge-verify skill)
+4. Return structured findings as your response in the Output Format specified below
+5. Generate a fix plan suitable for a fresh agent to execute
+
+## Scoped / Parallel Operation
+
+You may be dispatched in one of three ways. The parent's prompt tells you which:
+
+1. **Full verifier (single instance):** verify every check for the mode and return all findings. This is the default for small modes (prd, tech).
+2. **Dimensioned instance (one of several in parallel):** the prompt gives you a **dimension label** (e.g. "cross-reference & traceability") and an **exact set of CHECK-IDs you own**. Verify ONLY those checks; ignore the rest (another instance owns them). Return findings for your slice. Your `Checks Executed: N of M` line counts only your assigned slice. **Treat `MEMORY.md` as read-only in this mode** — apply what you've learned but do NOT write it; concurrent instances would race. Memory consolidation happens only on full-verifier runs.
+3. **Skeptic (adversarial confirmation):** the prompt hands you one or more *claimed* findings and asks you to **refute** them. Try hard to prove each wrong from the artifacts. Return a verdict per finding (CONFIRMED / REFUTED + why). **Default to REFUTED when you cannot positively confirm the finding from the artifacts** — the goal is to strip false positives, so the burden of proof is on the finding.
+
+## Context Pressure Management
+
+For large spec suites (>8 documents), process verification in phases: load shared types and architecture specs first for cross-reference and type consistency checks, then load subsystem specs in batches for domain-specific checks. (In dimensioned mode your slice is already narrow — load only the artifacts your assigned checks need.)
+
+## Using Your Memory
+
+You have persistent memory in your `MEMORY.md` file. Use it to track:
+
+- **Recurring patterns**: If you keep finding the same type of gap across features, note it. Over time you'll learn this project's blind spots.
+- **Project conventions**: As you review more specs, capture conventions that should be consistent (naming patterns, error handling approaches, test strategies).
+- **False positives to avoid**: If you've flagged something before and the user said it was intentional, note it so you don't flag it again.
+
+At the end of each verification pass, update your memory with any new patterns you've observed. Keep `MEMORY.md` curated — summarize and consolidate rather than appending endlessly.
+
+## Verification Quality Standards
+
+- Every finding must be specific enough that a fresh agent can act on it without conversational context
+- Severity must be accurate: `gap` (missing coverage), `inconsistency` (contradictory), `improvement` (not wrong but better exists), `error` (factually incorrect)
+- Include exact file paths and section references
+- Include a concrete suggested fix, not just a description of the problem
+- If you find zero issues, say so honestly — but also note in your memory that this feature had a clean verification, which is unusual for complex features
+
+## Output Format
+
+Return your findings as your final response using exactly this markdown structure. The parent agent will write it to `.verification/VERIFY-{mode}-{date}.md`:
+
+```markdown
+# Verification Report: {feature} ({mode})
+Date: {YYYY-MM-DD}
+Pipeline Stage: {currentStage}
+Artifacts Reviewed: {list of files}
+Checks Executed: {N} of {M} ({X} pass, {Y} fail, {Z} not-applicable)
+
+## Summary
+- Total findings: {N}
+- Gaps: {N}
+- Inconsistencies: {N}
+- Improvements: {N}
+- Errors: {N}
+
+## Findings
+
+### V-001: {Short title}
+- **Severity:** gap | inconsistency | improvement | error
+- **Location:** {filename}, section {N.N}
+- **Issue:** {Detailed description}
+- **Suggested fix:** {Specific, actionable fix}
+- **References:** {Other files/sections involved}
+- **Checklist:** {CHECK-XXX IDs}
+
+## Fix Execution Plan
+
+### User Decisions Required
+{List or "None — all fixes can be applied directly."}
+
+### Execution Steps
+#### Step {N}: {Short title}
+- **Files:** {paths}
+- **Addresses:** {V-NNN IDs}
+- **Action:** {Exact change description}
+- **Depends on:** {Step N or "none"}
+```
+
+## Bash Tool Usage
+
+You have Bash access for read-only operations ONLY. The following is an exhaustive allowlist.
+
+### Allowed Commands
+- `python`, `python3` — for running validation scripts under the plugin root resolved by the portable resolver (`scripts/forge-root.sh`; see `references/portable-root.md`)
+- `wc` — counting lines, words, characters
+- `find` — locating files (read-only)
+- `ls`, `tree` — listing directory contents
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+- Type-check commands from forge.config.json (e.g., `bun run typecheck`, `mypy`, `go vet`)
+- Test commands from forge.config.json (e.g., `bun test`, `pytest`, `cargo test`)
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`)
+- Package managers (`pip install`, `npm install`, `bun install`, `cargo install`)
+- Any command that creates, modifies, or deletes files

package/adapters/pi/extensions/ask-user-question/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/adapters/pi/extensions/ask-user-question/README.md

@@ -0,0 +1,91 @@
+# @juicesharp/rpiv-ask-user-question
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-ask-user-question.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<div align="center">
+  <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question">
+    <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/cover.png" alt="rpiv-ask-user-question cover: a tabbed terminal questionnaire asking Which real development task are we planning right now?, with numbered options — Bug fix, New feature, Refactor — each under a one-line description, and a footer of key hints" width="50%">
+  </a>
+</div>
+
+Let the model ask you instead of guessing. This extension gives [Pi Agent](https://github.com/badlogic/pi-mono) one tool — `ask_user_question` — that opens a terminal dialog of up to four questions with written-out options, and hands your choices back as structured data. Install it if you would rather spend fifteen seconds picking than an hour undoing a wrong assumption.
+
+## Install
+
+```sh
+pi install npm:@juicesharp/rpiv-ask-user-question
+```
+
+Restart your Pi session.
+
+## Quick start
+
+Nothing to set up — the tool is live as soon as Pi restarts. Hand the model a task with a real decision buried in it:
+
+> Add caching to the API client.
+
+Rather than picking a strategy on your behalf, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `↑`/`↓`, choose with `Enter`, press `n` to attach a note, or land on the `Type something.` row to answer in your own words. `Esc` abandons the questionnaire entirely.
+
+![Single question in the dialog: the tab strip reads Feature Type, Design Tab, Testing, Release, Submit; the question Which real development task are we planning right now? sits above four numbered options — Bug fix (Recommended), New feature, Refactor, Perf tuning — each with a one-line description, followed by the appended Type something. row](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/single-question.jpg)
+
+When the model asks several things at once, `Tab` moves between them and a Submit tab reviews everything before it goes back:
+
+![Submit tab of a four-question dialog: a Review your answers list showing Feature Type set to Bug fix and Testing set to Unit tests plus Integration tests, a warning naming Design Tab and Release as still unanswered, and a picker offering Submit answers or Cancel](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/submit-tab.jpg)
+
+## What you get
+
+- **Typed options instead of a wall of prose** — each question carries 2-4 authored choices, and every choice comes with a description of what it means or what it costs you.
+- **You can always answer in your own words** — a `Type something.` row is appended to every question, single- or multi-select, and widens to the full pane while you type.
+- **Compare real artifacts, not just labels** — an option can carry a markdown `preview` (ASCII mockup, code, diagram, config) that renders in a bordered box beside the option list.
+- **One interruption, not five** — up to four questions arrive in a single tabbed dialog, and the Submit tab lists your answers and names anything still blank before you commit.
+- **Notes on any answer** — `n` opens a note editor on any question tab; the note travels back to the model alongside the choice without marking the question answered.
+- **Read the transcript behind the dialog** — `Ctrl+]` collapses the overlay so you can scroll the conversation, then brings it back with your answers intact.
+- **Works outside the terminal too** — in RPC and ACP hosts such as the VS Code pendant or Zed the questionnaire walks through the host's native dialogs, and in non-interactive runs the tool is removed from the model's tool list instead of failing every call.
+
+## Configuration
+
+Optional. Settings live in `~/.config/rpiv-ask-user-question/config.json`; the file is read, never written.
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog. Accepts Pi keybinding ids such as `alt+o`; `"off"` disables the shortcut. | `"ctrl+]"` |
+| `guidance.promptSnippet` | One-line description of the tool in the system prompt — tune how eagerly the model asks. | built-in snippet |
+| `guidance.promptGuidelines` | Usage guidelines given to the model, as a list of strings. | 4 built-in guidelines |
+
+```json
+{ "collapseKey": "alt+o" }
+```
+
+Malformed JSON falls back to the defaults with a warning; an individual unusable value is silently dropped back to its default. Never an error.
+
+## Reference
+
+- [Tool schema](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/tool-schema.md) — parameters, limits, reserved labels, validation errors, the result envelope, and the `rpiv:ask-user:prompt` event.
+- [Keyboard and layout](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/keyboard.md) — every key, the rows the dialog appends, notes, collapse mode, and how previews and overflow adapt to terminal size.
+- [Configuration](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/configuration.md) — file lookup and `XDG_CONFIG_HOME`, the `collapseKey` grammar, the `guidance.*` prompt overrides, and how invalid values are handled.
+- [Hosts and runtime behavior](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/hosts.md) — terminal vs RPC vs non-interactive, what degrades in each, and the load-failure envelopes.
+- [Localization](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/localization.md) — the nine shipped languages, how the locale is chosen, and how to add one.
+
+## Requirements
+
+- Node.js 22 or newer.
+- Pi Agent, with an interactive terminal or an RPC/ACP host. Non-interactive runs never see the tool.
+- A terminal at least 100 columns wide for side-by-side previews; narrower terminals stack the preview under the options.
+
+No native dependencies, no compiler, no API keys — the extension makes no model calls of its own.
+
+## Troubleshooting
+
+**The model says the questionnaire UI failed to load and asks its questions as chat text.** The dialog's modules were replaced on disk while Pi was running, usually by a package-manager install touching the store. Repair the install if it is broken, then restart Pi; the failure is not recoverable inside the running process.
+
+**`Ctrl+]` does nothing.** On keyboard layouts where `]` sits on the shifted layer (Latin American among them) the default is unreachable. Set `collapseKey` to something you can type, for example `"alt+o"`.
+
+## Related
+
+- [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) — optional; installing it renders the dialog chrome in your language and adds `/languages`.
+- [`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) — the umbrella package whose workflow skills use `ask_user_question` as their developer checkpoint. `/rpiv-setup` offers to install this extension.
+
+## License
+
+MIT — see [LICENSE](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/LICENSE).