@garygentry/feature-forge 0.2.12 → 0.2.13

package/adapters/gemini/skills/forge-guide/references/stacks/python.md

@@ -0,0 +1,163 @@
+# Python Stack Profile
+
+Stack-specific guidance for Python projects (3.10+).
+
+## Stack Identity
+
+- **Language**: Python 3.10+ (required for modern type hint syntax: `X | Y` unions, `match` statements)
+- **Package management**: pip, uv, poetry, pdm, or pipenv (check for respective lock/config files)
+- **Type checking**: mypy, pyright, or pytype
+- **Linting**: ruff, flake8, pylint
+
+## Discovery Checklist
+
+When examining a Python project, check for:
+
+- **Project manifest**: `pyproject.toml` (modern), `setup.py`/`setup.cfg` (legacy), `requirements.txt` (minimal)
+- **Package manager**: `uv.lock` (uv), `poetry.lock` (poetry), `pdm.lock` (pdm), `Pipfile.lock` (pipenv)
+- **Monorepo**: `pants.toml` (Pants), `BUILD` files (Bazel), `nx.json` with Python plugins, or plain workspace structure
+- **Framework**: FastAPI, Django, Flask, Starlette, Litestar
+- **Database**: SQLAlchemy, Django ORM, Tortoise ORM, SQLModel
+- **Validation**: Pydantic, attrs, marshmallow
+- **Testing**: pytest (dominant), unittest
+- **Type checking**: `mypy.ini`, `pyrightconfig.json`, or `[tool.mypy]` / `[tool.pyright]` in `pyproject.toml`
+
+## Archetype Conventions
+
+### 00-core-definitions.md (Python)
+
+- **Data structures**: Use `dataclasses` for simple data containers, Pydantic `BaseModel` for validated/serializable models. Use `TypedDict` for dict-shaped data.
+- **Type aliases**: Use `type` statements (3.12+) or `TypeAlias` annotation
+- **Union types**: Use `X | Y` syntax (3.10+)
+- **Protocols**: Use `typing.Protocol` for structural subtyping (Python's equivalent of interfaces)
+- **Error/exception hierarchy**: Base exception class inheriting from `Exception` (or a more specific built-in); domain-specific subclasses with typed attributes
+- **Constants and enumerations**: Use `enum.Enum`, `enum.StrEnum`, or module-level constants with `Final` annotation
+- **Module exports**: Define `__all__` in `__init__.py` for explicit public API
+
+### 01-architecture-layout.md (Python)
+
+- **Project layout**: `src/` layout (recommended) or flat layout
+- **pyproject.toml**: `[project]` table with `name`, `dependencies`, `optional-dependencies`, `[project.scripts]` for CLI entry points
+- **Tool configuration**: `[tool.pytest.ini_options]`, `[tool.mypy]`, `[tool.ruff]` sections in `pyproject.toml`
+- **Module entry points**: `__init__.py` files with explicit `__all__` lists for re-exports
+- **Namespace packages**: When applicable, `py.typed` marker for PEP 561 compliance
+
+### Monorepo conventions (if applicable)
+
+- **Workspace structure**: `packages/` or `libs/` directories with individual `pyproject.toml` per package
+- **Internal dependencies**: Path dependencies in `pyproject.toml` or editable installs
+- **Build coordination**: Pants, Bazel, or Makefile-based orchestration
+
+## Spec Quality Rules
+
+- All Python code must be valid syntax with complete type annotations — not pseudocode
+- Use Google-style or NumPy-style docstrings consistently (match project convention)
+- Include `Args`, `Returns`, `Raises` sections in docstrings for every public function
+- Use `Protocol` classes to define interfaces/contracts
+- Include explicit import statements in all code examples
+- Use `async def` for asynchronous operations where applicable
+
+### Example: Well-Specified Function
+
+```python
+class SessionExpiredError(AuthError):
+    """Raised when a session token has expired.
+
+    Attributes:
+        expired_at: When the session expired.
+    """
+
+    def __init__(self, expired_at: datetime) -> None:
+        self.expired_at = expired_at
+        super().__init__(
+            code="SESSION_EXPIRED",
+            message=f"Session expired at {expired_at.isoformat()}",
+        )
+
+
+async def refresh_session_token(
+    current_token: str,
+    *,
+    max_age: timedelta = SESSION_DURATION,
+    refresh_threshold: timedelta = REFRESH_THRESHOLD,
+    signing_key: bytes,
+) -> str | None:
+    """Refresh a session token if it's within the refresh threshold.
+
+    Returns a new token with an extended expiry, or None if the session
+    is not eligible for refresh (valid but outside threshold).
+
+    Args:
+        current_token: The JWT string from the session cookie.
+        max_age: Maximum age of a token eligible for refresh.
+        refresh_threshold: How close to expiry before refresh is allowed.
+        signing_key: Secret key for signing the new token.
+
+    Returns:
+        New session token string, or None if refresh is not possible.
+
+    Raises:
+        SessionExpiredError: If the token has already expired.
+        TokenValidationError: If the token signature is invalid.
+    """
+    ...
+```
+
+## Verification Specifics
+
+- **Type checking**: `mypy .`, `mypy src/`, `pyright`, or `pyright src/`
+- **Linting**: `ruff check .` or `flake8`
+- **Formatting**: `ruff format --check .` or `black --check .`
+- **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
+- **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
+
+## Testing
+
+- **Framework**: pytest (with `conftest.py` for fixtures)
+- **Fixtures**: Define in `conftest.py` at appropriate scope (session, module, function)
+- **Mocking**: `unittest.mock.patch`, `monkeypatch` fixture, or `pytest-mock`
+- **Coverage**: `pytest-cov` with `--cov=src/` flag
+- **Test file location**: `tests/` directory mirroring `src/` structure, or co-located `test_*.py` files
+- **Async testing**: `pytest-asyncio` for async function tests
+- **Type testing**: Runtime checks with `isinstance()`, static checks with `reveal_type()`
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Web (async) | FastAPI, Starlette, Litestar |
+| Web (sync) | Django, Flask |
+| Database ORM | SQLAlchemy, Django ORM, SQLModel, Tortoise ORM |
+| Migrations | Alembic (SQLAlchemy), Django migrations |
+| Validation | Pydantic, attrs, marshmallow |
+| Task queues | Celery, Dramatiq, Huey, ARQ |
+| CLI | Click, Typer, argparse |
+| HTTP client | httpx, aiohttp, requests |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Python 3.12 with uv for package management
+- src/ layout with pyproject.toml
+
+## Backend
+- FastAPI for HTTP framework
+- SQLAlchemy 2.0 with PostgreSQL (async)
+- Pydantic v2 for validation and serialization
+
+## Testing
+- pytest with pytest-asyncio
+- Factory Boy for test fixtures
+- Coverage target: 90%
+
+## Conventions
+- Google-style docstrings
+- ruff for linting and formatting
+- mypy with --strict for type checking
+- __all__ exports in every __init__.py
+```

package/adapters/gemini/skills/forge-guide/references/stacks/rust.md

@@ -0,0 +1,151 @@
+# Rust Stack Profile
+
+Stack-specific guidance for Rust projects (stable channel).
+
+## Stack Identity
+
+- **Language**: Rust (stable channel, edition 2021 or later)
+- **Build system**: Cargo (`cargo build`, `cargo test`, `cargo run`)
+- **Package registry**: crates.io (dependencies declared in `Cargo.toml`)
+- **Philosophy**: Zero-cost abstractions, ownership model for memory safety, fearless concurrency
+
+## Discovery Checklist
+
+When examining a Rust project, check for:
+
+- **Project manifest**: `Cargo.toml` (package metadata, dependencies, features, workspace config)
+- **Dependency lock**: `Cargo.lock` (exact dependency versions for reproducible builds)
+- **Library entry**: `src/lib.rs` (library crate root)
+- **Binary entry**: `src/main.rs` (binary crate root), or `src/bin/` for multiple binaries
+- **Build script**: `build.rs` (compile-time code generation, native library linking)
+- **Cargo config**: `.cargo/config.toml` (target-specific settings, linker config, aliases)
+- **Workspace**: `[workspace]` table in root `Cargo.toml` with `members` list
+- **Framework**: Check `Cargo.toml` dependencies for actix-web, axum, rocket (web), clap (CLI), tokio (async)
+- **Async runtime**: tokio, async-std, smol
+- **Serialization**: serde, serde_json, serde_yaml
+
+## Archetype Conventions
+
+### 00-core-definitions.md (Rust)
+
+- **Structs**: Use `struct` types with derive macros (`#[derive(Debug, Clone, Serialize, Deserialize)]`). Document every public field with `///` doc comments.
+- **Enums**: Use for sum types / discriminated unions. Each variant documents its purpose. Exhaustive `match` for control flow.
+- **Traits**: Define shared behavior contracts. Keep focused (single responsibility). Use associated types for output types, generics for input types.
+- **Error types**: `thiserror::Error` for library errors (typed, specific), `anyhow::Error` for application errors (erased, convenient). Define `type Result<T> = std::result::Result<T, MyError>` aliases per module.
+- **Type aliases**: Use `type` for complex generic instantiations (e.g., `type DbPool = Pool<Postgres>`)
+- **Newtypes**: Single-field tuple structs for type safety (e.g., `struct UserId(Uuid)`)
+- **Constants**: `const` for compile-time values, `static` for global state (rarely needed), `lazy_static!` or `std::sync::LazyLock` for runtime-initialized globals
+
+### 01-architecture-layout.md (Rust)
+
+- **Single crate structure**:
+  - `src/lib.rs` — library root, declares modules with `mod` statements
+  - `src/main.rs` — binary entry point, imports from library crate
+  - `src/<module>.rs` or `src/<module>/mod.rs` — submodules
+  - `tests/` — integration tests (each file is a separate crate)
+  - `examples/` — runnable examples (`cargo run --example name`)
+  - `benches/` — benchmarks (`cargo bench`)
+- **Cargo workspace** (multi-crate):
+  - Root `Cargo.toml` with `[workspace]` and `members = ["crates/*"]`
+  - Shared dependencies via `[workspace.dependencies]` with `{ workspace = true }` in member crates
+  - Internal crate references as path dependencies
+- **Cargo.toml**: `[package]` (name, version, edition), `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, `[features]` for conditional compilation
+- **Module visibility**: `pub`, `pub(crate)`, `pub(super)` for fine-grained access control. Re-exports via `pub use` in parent modules.
+
+### NN-testing-strategy.md (Rust)
+
+- **Framework**: Built-in `#[test]` attribute (no external framework required)
+- **Unit tests**: `#[cfg(test)] mod tests { ... }` at bottom of each source file (white-box, access to private items)
+- **Integration tests**: `tests/` directory, each `.rs` file is a separate test crate (black-box, only public API)
+- **Test assertions**: `assert!`, `assert_eq!`, `assert_ne!` macros; custom messages as format string arguments
+- **Doc tests**: Code blocks in `///` doc comments run as tests with `cargo test`
+- **Examples**: `examples/` directory, verified to compile with `cargo test`, runnable with `cargo run --example`
+- **Test fixtures**: Builder pattern structs, helper functions in `tests/common/mod.rs`
+- **Async tests**: `#[tokio::test]` attribute for async test functions
+- **Property testing**: `proptest` or `quickcheck` crates for generative testing
+- **Snapshot testing**: `insta` crate for snapshot/approval testing
+
+## Spec Quality Rules
+
+- All Rust code must be valid syntax with complete type annotations — not pseudocode
+- Follow Rust idioms:
+  - `Result<T, E>` for fallible operations — never panic for expected failures
+  - `Option<T>` for nullable/optional values — never use sentinel values
+  - Ownership and borrowing: specify whether a function takes ownership (`T`), borrows (`&T`), or mutably borrows (`&mut T`). Note when `Clone` is required.
+  - Lifetime annotations when the compiler cannot infer them — document why a lifetime relationship exists
+  - Derive macros for common traits (`Debug`, `Clone`, `PartialEq`, `Eq`, `Hash`, `Serialize`, `Deserialize`)
+  - `impl` blocks for methods — group inherent methods and trait implementations separately
+  - Pattern matching with `match` for control flow over enums and `Result`/`Option`
+  - `?` operator for error propagation — avoid manual `match` on `Result` when `?` suffices
+- Document every public item with `///` doc comments including `# Examples` sections for non-trivial APIs
+- Use `#[must_use]` on functions whose return values should not be ignored
+- Include complete `use` statements in all code examples
+
+## Verification Specifics
+
+- **Type checking**: `cargo check` (fast compile without codegen — catches all type errors)
+- **Linting**: `cargo clippy` (idiomatic Rust lints, catches common mistakes)
+- **Testing**: `cargo test` (unit tests, integration tests, doc tests, examples)
+- **Documentation**: `cargo doc --no-deps` (ensures documentation compiles, catches broken links)
+- **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
+- **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
+
+## Testing
+
+- **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)
+- **Test command**: `cargo test` for all, `cargo test test_name` for specific, `cargo test --lib` for unit only
+- **Unit tests**: `#[cfg(test)] mod tests` at bottom of source files
+- **Integration tests**: `tests/` directory, each file is a separate crate
+- **Doc tests**: Code in `///` comments, verified by `cargo test --doc`
+- **Assertions**: `assert!`, `assert_eq!`, `assert_ne!` with optional format messages
+- **Async tests**: `#[tokio::test]` macro for async test functions
+- **Snapshot testing**: `insta` crate with `assert_snapshot!` / `assert_debug_snapshot!`
+- **Coverage**: `cargo llvm-cov` or `cargo tarpaulin`
+- **Benchmarks**: `criterion` crate or built-in `#[bench]` (nightly)
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Web (async) | axum, actix-web, rocket, warp |
+| Serialization | serde, serde_json, serde_yaml, toml |
+| Async runtime | tokio, async-std, smol |
+| Database | sqlx, diesel, sea-orm |
+| Migrations | sqlx-cli, diesel-cli, refinery |
+| CLI | clap, argh, structopt (legacy) |
+| Observability | tracing, tracing-subscriber, metrics |
+| HTTP client | reqwest, hyper, ureq (blocking) |
+| Middleware | tower, tower-http, actix middleware |
+| Error handling | thiserror (library), anyhow (application), eyre |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Rust stable (edition 2021)
+- Cargo workspace with crates/ directory
+
+## Backend
+- axum for HTTP framework
+- sqlx with PostgreSQL (compile-time query checking)
+- tokio as async runtime
+
+## Serialization & Validation
+- serde for serialization/deserialization
+- Custom validation via trait implementations
+
+## Testing
+- Built-in #[test] with assert macros
+- Integration tests in tests/ directory
+- insta for snapshot testing
+
+## Conventions
+- thiserror for library error types, anyhow in binary
+- tracing for structured logging
+- cargo clippy must pass with no warnings
+- All public APIs documented with /// and examples
+```

package/adapters/gemini/skills/forge-guide/references/stacks/typescript.md

@@ -0,0 +1,111 @@
+# TypeScript Stack Profile
+
+Stack-specific guidance for TypeScript projects (Node.js/Bun, monorepo or single-package).
+
+## Stack Identity
+
+- **Language**: TypeScript
+- **Runtime**: Node.js or Bun (check `package.json` `engines` field and lock files)
+- **Package management**: npm, pnpm, yarn, or bun (check for respective lock files)
+- **Common monorepo tools**: Turborepo (`turbo.json`), Nx (`nx.json`), Lerna (`lerna.json`)
+
+## Discovery Checklist
+
+When examining a TypeScript project, check for:
+
+- **Runtime**: Bun or Node.js (check `package.json` for which)
+- **Package management**: Check for `bun.lockb`, `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`
+- **Monorepo**: Check for `turbo.json` (Turborepo), `nx.json` (Nx), or `lerna.json` (Lerna)
+- **Framework**: Check existing packages for Hono, Express, Fastify, etc.
+- **Frontend**: Check for React, Vue, Svelte, etc.
+- **Routing**: Check for TanStack Router, React Router, Next.js, etc.
+- **Database**: Check for Drizzle, Prisma, TypeORM, etc.
+- **Validation**: Check for Zod, Yup, io-ts, etc.
+- **UI Components**: Check for shadcn/ui, Radix, MUI, etc.
+- **Styling**: Check for Tailwind (v3 or v4), CSS Modules, styled-components, etc.
+
+## Archetype Conventions
+
+### 00-core-definitions.md (TypeScript)
+
+- **Type aliases and union types**: Use `type` declarations for unions, intersections, utility types
+- **Core interfaces**: Define with `interface` keyword, JSDoc on every field
+- **Error class hierarchy**: Base error class extending `Error` with `code: string` property; domain-specific subclasses with typed properties
+- **Constants and enums**: Use `const` declarations and `as const` assertions; prefer string union types over `enum`
+- **Utility types**: Generic helpers like `Result<T, E>`, `Optional<T>`, etc.
+- **Barrel exports**: Export everything from `src/index.ts`
+
+### 01-architecture-layout.md (TypeScript)
+
+- **Package.json**: `name`, `exports` map (subpath exports like `.`, `./server`, `./client`, `./react`), `dependencies`, `devDependencies`, `scripts`
+- **tsconfig.json**: Key compiler options, extends root config
+- **Barrel export structure**: What each `index.ts` re-exports
+- **Build considerations**: Bundle vs unbundled, ESM vs CJS
+
+### Monorepo conventions
+
+- **Package naming**: `@repo/{name}` for shared packages, `@starter/{name}` for app-specific (adapt to project convention)
+- **Internal dependencies**: Reference as `@repo/{package}` in `package.json`
+- **Workspace protocol**: `"@repo/config": "workspace:*"` in pnpm, `"@repo/config": "*"` in bun
+
+## Spec Quality Rules
+
+- All TypeScript must be valid syntax — not pseudocode
+- Include complete interfaces with generics where applicable
+- Use discriminated unions for result types (e.g., `{ success: true; data: T } | { success: false; error: E }`)
+- Every interface field must have JSDoc explaining its purpose
+- Include explicit import paths in all code examples
+- Use `async/await` for asynchronous operations (not raw Promises)
+
+## Verification Specifics
+
+- **Type checking**: `bun run typecheck`, `tsc --noEmit`, or `npx tsc --noEmit`
+- **Barrel export validation**: Every `index.ts` re-exports what the spec says
+- **Cross-package type checks**: `bun run typecheck` (or equivalent) passes for both the feature package AND packages that depend on it
+- **Import path validation**: All import paths resolve correctly per the `exports` map in `package.json`
+
+## Testing
+
+- **Framework**: Vitest (most common in modern TS), Jest, or testing-library
+- **Test file location**: Co-located (`*.test.ts` next to source) or in `__tests__/` directories
+- **Fixture patterns**: Factory functions, test builders
+- **Type testing**: `expectTypeOf` from vitest for type-level assertions
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Backend | Hono, Express, Fastify, Koa |
+| Frontend | React, Vue, Svelte, Solid |
+| Routing | TanStack Router, React Router, Next.js App Router |
+| Database | Drizzle, Prisma, TypeORM, Kysely |
+| Validation | Zod, Valibot, Yup, io-ts |
+| UI Components | shadcn/ui, Radix, MUI, Mantine |
+| Styling | Tailwind CSS, CSS Modules, styled-components, vanilla-extract |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Bun 1.x for runtime and package management
+- Turborepo for monorepo orchestration
+
+## Backend
+- Hono for HTTP framework
+- Drizzle ORM with PostgreSQL
+- Zod for runtime validation
+
+## Frontend
+- React 19 with TanStack Router (SPA-first)
+- shadcn/ui component library
+- Tailwind CSS v4 with oklch color theming
+
+## Conventions
+- Barrel exports from index.ts in every package
+- Package naming: @repo/{name} for shared, @starter/{name} for app-specific
+- Vitest for testing
+```

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

@@ -23,6 +23,7 @@ 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`)
+- `smokeCommand`: `null` (optional end-to-end smoke that boots the wired app and drives one request; set it to enable impl-verify's runnability check `CHECK-I21` — distinct from `testCommand`)
 - `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)

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

@@ -29,7 +29,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 - **Small modes (prd ~15, tech ~15): single verifier.** Use the host's subagent mechanism once with
   `the forge-verifier custom agent`, passing the feature name and mode. It runs all
   checks and returns findings.
-- **Large modes (specs ~38, backlog ~25, impl ~20): parallel dimensioned fan-out.**
+- **Large modes (specs ~38, backlog ~25, impl ~22): parallel dimensioned fan-out.**
   Split the mode's checklist into **dimension groups** and dispatch **one
   `forge-verifier` per group, in parallel — a single message with multiple subagent
   calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
@@ -41,7 +41,8 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
   - **backlog:** (1) item scoping & acceptance criteria, (2) dependency/ordering sanity,
     (3) spec coverage & traceability, (4) schema/enum correctness.
   - **impl:** (1) requirement coverage vs specs, (2) integration correctness,
-    (3) testing, (4) code-quality/conventions.
+    (3) testing, (4) code-quality/conventions, (5) runnability (owns CHECK-I21/I22 —
+    the smoke command and the non-test-caller heuristic).
 
   In each parallel instance's prompt, pass: the feature, the mode, the **dimension
   label**, the **exact CHECK-IDs it owns**, and a note that **it is one of several
@@ -161,7 +162,7 @@ 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: ~9 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: ~22 checks, epic: ~9 checks), you likely skipped checks — go back and complete them.
 
 **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.
 

package/adapters/gemini/skills/forge-verify/references/pipeline-state-schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "currentStage": {
+      "type": "string",
+      "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "epicChangeRequests": {
+      "type": "array",
+      "description": "Epic-level change requests raised by a member stage (forge-1-prd/forge-2-tech) when the epic DECOMPOSITION itself must change — distinct from the same-feature `notes` parking lot. Read by forge-0-epic edit mode (which applies them) and by forge-session stage-exit (which routes the exit on `blocksCurrent`). Absent/empty for standalone features. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "rationale", "blocksCurrent", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["add-feature", "redep", "move-boundary", "split"],
+            "description": "The decomposition change. add-feature/redep map 1:1 onto edit-mode mutators; move-boundary/split are composite (applied guided-manual in v1)."
+          },
+          "target": {
+            "type": "string",
+            "description": "The sibling feature to add, or the feature/boundary affected."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the epic must change; seeds the edit-mode charter/prompt when applied."
+          },
+          "blocksCurrent": {
+            "type": "boolean",
+            "description": "true → the current feature's next stage would build on a soon-to-change decomposition (pause-now: reconcile before proceeding). false → a peer/downstream change (finish-then-edit). Drives stage-exit routing."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech"],
+            "description": "The stage that detected the epic-level concern."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "applied", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → applied|dismissed. Only forge-0-epic edit mode flips open→applied/dismissed; recording stages only create open entries; navigator/verify only read."
+          }
+        }
+      }
+    },
+    "deferredDecisions": {
+      "type": "array",
+      "description": "Same-feature decisions deliberately postponed to a LATER stage of THIS feature — a structured alternative to burying them in the free-text `notes` string. Distinct from `notes` (unstructured scratch) and from `epicChangeRequests[]` (the epic DECOMPOSITION must change). Use this when a stage would otherwise be tempted to solicit a decision that properly belongs to a downstream stage (e.g. forge-1-prd deferring the concrete cache backend to forge-2-tech): record it here instead of asking now (see the deferred-decisions rule in `references/stage-exit-protocol.md`), and the target stage addresses it. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["question", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "The decision being deferred, phrased as a concrete question for the target stage to answer."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why it is deferred rather than decided now (e.g. depends on information the target stage produces)."
+          },
+          "targetStage": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs"],
+            "description": "The stage that should resolve this decision. Omit when unknown/any-later-stage."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog"],
+            "description": "The stage that deferred the decision."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → addressed|dismissed. The target stage flips open→addressed when it resolves the decision (or dismissed if it no longer applies); recording stages only create open entries."
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." }
+      }
+    }
+  }
+}