ai-forge-cli 2.0.3__tar.gz → 2.1.0__tar.gz

{ai_forge_cli-2.0.3 → ai_forge_cli-2.1.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 William James
+Copyright (c) 2026 Will Defina
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_forge_cli-2.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ai-forge-cli
+Version: 2.1.0
+Summary: Forge V2 schema runtime and workbench CLI
+Author: Will Defina
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GreyFlames07/forge
+Project-URL: Repository, https://github.com/GreyFlames07/forge
+Project-URL: Issues, https://github.com/GreyFlames07/forge/issues
+Project-URL: Documentation, https://github.com/GreyFlames07/forge
+Keywords: forge,software-architecture,schema,cli,agentic-development
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Forge V2
+
+Forge V2 is a schema runtime, workbench CLI, and skill/framework system for building software vertically while preserving a working bootstrap path throughout the build.
+
+## What is in this repo
+
+- `docs/forge-v2-schema.md` — the V2 schema contract
+- `docs/forge-v2-architecture.md` — the V2 architecture and workbench model
+- `frameworks/` — stage framework definitions
+- `skills/` — skill source files
+- `.agents/skills/` — installable agent skill folders
+- `src/cli/` — the Forge V2 CLI
+
+## Local development
+
+```bash
+uv venv --python 3.13 .venv
+uv pip install -e . pytest
+.venv/bin/pytest -q
+```
+
+## Install the CLI and skills locally
+
+```bash
+./scripts/install-skills.sh install
+```
+
+This links the packaged Forge skills into:
+
+- `~/.claude/skills` for Claude Code
+- `~/.codex/skills` for Codex
+- `~/.agents/skills` for agentskills.io-compatible clients such as VS Code Copilot and Cursor
+- `~/.copilot/skills` as an additional Copilot-local target when `~/.copilot/` already exists
+
+## Build distributions
+
+```bash
+uv build
+```
+
+This produces:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+## Release model
+
+- CI runs tests and a smoke build on `main` pushes and PRs
+- tagged releases `v*.*.*` build sdist and wheel
+- release workflow publishes artifacts to GitHub Releases and PyPI
+
+## Quick smoke test
+
+```bash
+./.venv/bin/forge init --root /tmp/forge-smoke --profile cli-tool --name "Smoke" --id smoke
+./.venv/bin/forge list --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge context core --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge graph --forge-dir /tmp/forge-smoke/forge --no-open
+```
+
+`forge init` vendors the Forge docs, frameworks, and project-local `.agents/skills/` into the initialized directory, then symlinks those project-local skills into the home scan directories above unless you pass `--no-vendor-assets` or `--no-link-skills`.
+
+## Public CLI vs workbench
+
+The public CLI is intentionally small:
+
+- `forge init`
+- `forge list`
+- `forge context`
+- `forge graph`
+
+`forge/workbench/` remains part of the framework, but it is an internal artifact model used by the stage skills. It stores build-planning and validation state for agent workflows; it is not a separate public command surface.

ai_forge_cli-2.1.0/README.md

@@ -0,0 +1,72 @@
+# Forge V2
+
+Forge V2 is a schema runtime, workbench CLI, and skill/framework system for building software vertically while preserving a working bootstrap path throughout the build.
+
+## What is in this repo
+
+- `docs/forge-v2-schema.md` — the V2 schema contract
+- `docs/forge-v2-architecture.md` — the V2 architecture and workbench model
+- `frameworks/` — stage framework definitions
+- `skills/` — skill source files
+- `.agents/skills/` — installable agent skill folders
+- `src/cli/` — the Forge V2 CLI
+
+## Local development
+
+```bash
+uv venv --python 3.13 .venv
+uv pip install -e . pytest
+.venv/bin/pytest -q
+```
+
+## Install the CLI and skills locally
+
+```bash
+./scripts/install-skills.sh install
+```
+
+This links the packaged Forge skills into:
+
+- `~/.claude/skills` for Claude Code
+- `~/.codex/skills` for Codex
+- `~/.agents/skills` for agentskills.io-compatible clients such as VS Code Copilot and Cursor
+- `~/.copilot/skills` as an additional Copilot-local target when `~/.copilot/` already exists
+
+## Build distributions
+
+```bash
+uv build
+```
+
+This produces:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+## Release model
+
+- CI runs tests and a smoke build on `main` pushes and PRs
+- tagged releases `v*.*.*` build sdist and wheel
+- release workflow publishes artifacts to GitHub Releases and PyPI
+
+## Quick smoke test
+
+```bash
+./.venv/bin/forge init --root /tmp/forge-smoke --profile cli-tool --name "Smoke" --id smoke
+./.venv/bin/forge list --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge context core --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge graph --forge-dir /tmp/forge-smoke/forge --no-open
+```
+
+`forge init` vendors the Forge docs, frameworks, and project-local `.agents/skills/` into the initialized directory, then symlinks those project-local skills into the home scan directories above unless you pass `--no-vendor-assets` or `--no-link-skills`.
+
+## Public CLI vs workbench
+
+The public CLI is intentionally small:
+
+- `forge init`
+- `forge list`
+- `forge context`
+- `forge graph`
+
+`forge/workbench/` remains part of the framework, but it is an internal artifact model used by the stage skills. It stores build-planning and validation state for agent workflows; it is not a separate public command surface.

ai_forge_cli-2.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-forge-cli"
+dynamic = ["version"]
+description = "Forge V2 schema runtime and workbench CLI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0"]
+authors = [
+  {name = "Will Defina"}
+]
+keywords = ["forge", "software-architecture", "schema", "cli", "agentic-development"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Operating System :: OS Independent",
+  "Environment :: Console",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Documentation",
+]
+
+[project.urls]
+Homepage = "https://github.com/GreyFlames07/forge"
+Repository = "https://github.com/GreyFlames07/forge"
+Issues = "https://github.com/GreyFlames07/forge/issues"
+Documentation = "https://github.com/GreyFlames07/forge"
+
+[project.scripts]
+forge = "cli.forge:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.setuptools.dynamic]
+version = {attr = "cli.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cli*"]
+
+[tool.setuptools.package-data]
+cli = [
+  "assets/docs/*.md",
+  "assets/frameworks/*/FRAMEWORK.md",
+  "assets/agents_skills/*/SKILL.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ai_forge_cli-2.1.0/src/ai_forge_cli.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ai-forge-cli
+Version: 2.1.0
+Summary: Forge V2 schema runtime and workbench CLI
+Author: Will Defina
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GreyFlames07/forge
+Project-URL: Repository, https://github.com/GreyFlames07/forge
+Project-URL: Issues, https://github.com/GreyFlames07/forge/issues
+Project-URL: Documentation, https://github.com/GreyFlames07/forge
+Keywords: forge,software-architecture,schema,cli,agentic-development
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Forge V2
+
+Forge V2 is a schema runtime, workbench CLI, and skill/framework system for building software vertically while preserving a working bootstrap path throughout the build.
+
+## What is in this repo
+
+- `docs/forge-v2-schema.md` — the V2 schema contract
+- `docs/forge-v2-architecture.md` — the V2 architecture and workbench model
+- `frameworks/` — stage framework definitions
+- `skills/` — skill source files
+- `.agents/skills/` — installable agent skill folders
+- `src/cli/` — the Forge V2 CLI
+
+## Local development
+
+```bash
+uv venv --python 3.13 .venv
+uv pip install -e . pytest
+.venv/bin/pytest -q
+```
+
+## Install the CLI and skills locally
+
+```bash
+./scripts/install-skills.sh install
+```
+
+This links the packaged Forge skills into:
+
+- `~/.claude/skills` for Claude Code
+- `~/.codex/skills` for Codex
+- `~/.agents/skills` for agentskills.io-compatible clients such as VS Code Copilot and Cursor
+- `~/.copilot/skills` as an additional Copilot-local target when `~/.copilot/` already exists
+
+## Build distributions
+
+```bash
+uv build
+```
+
+This produces:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+## Release model
+
+- CI runs tests and a smoke build on `main` pushes and PRs
+- tagged releases `v*.*.*` build sdist and wheel
+- release workflow publishes artifacts to GitHub Releases and PyPI
+
+## Quick smoke test
+
+```bash
+./.venv/bin/forge init --root /tmp/forge-smoke --profile cli-tool --name "Smoke" --id smoke
+./.venv/bin/forge list --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge context core --forge-dir /tmp/forge-smoke/forge
+./.venv/bin/forge graph --forge-dir /tmp/forge-smoke/forge --no-open
+```
+
+`forge init` vendors the Forge docs, frameworks, and project-local `.agents/skills/` into the initialized directory, then symlinks those project-local skills into the home scan directories above unless you pass `--no-vendor-assets` or `--no-link-skills`.
+
+## Public CLI vs workbench
+
+The public CLI is intentionally small:
+
+- `forge init`
+- `forge list`
+- `forge context`
+- `forge graph`
+
+`forge/workbench/` remains part of the framework, but it is an internal artifact model used by the stage skills. It stores build-planning and validation state for agent workflows; it is not a separate public command surface.

ai_forge_cli-2.1.0/src/ai_forge_cli.egg-info/SOURCES.txt

@@ -0,0 +1,38 @@
+LICENSE
+README.md
+pyproject.toml
+src/ai_forge_cli.egg-info/PKG-INFO
+src/ai_forge_cli.egg-info/SOURCES.txt
+src/ai_forge_cli.egg-info/dependency_links.txt
+src/ai_forge_cli.egg-info/entry_points.txt
+src/ai_forge_cli.egg-info/requires.txt
+src/ai_forge_cli.egg-info/top_level.txt
+src/cli/__init__.py
+src/cli/__main__.py
+src/cli/common.py
+src/cli/forge.py
+src/cli/schema.py
+src/cli/workbench.py
+src/cli/assets/agents_skills/forge-build/SKILL.md
+src/cli/assets/agents_skills/forge-cast/SKILL.md
+src/cli/assets/agents_skills/forge-discover/SKILL.md
+src/cli/assets/agents_skills/forge-plan/SKILL.md
+src/cli/assets/agents_skills/forge-review/SKILL.md
+src/cli/assets/agents_skills/forge-spec/SKILL.md
+src/cli/assets/agents_skills/forge-validate/SKILL.md
+src/cli/assets/docs/forge-v2-architecture.md
+src/cli/assets/docs/forge-v2-schema.md
+src/cli/assets/frameworks/cast/FRAMEWORK.md
+src/cli/assets/frameworks/discover/FRAMEWORK.md
+src/cli/assets/frameworks/plan/FRAMEWORK.md
+src/cli/assets/frameworks/review/FRAMEWORK.md
+src/cli/assets/frameworks/spec/FRAMEWORK.md
+src/cli/assets/frameworks/validate/FRAMEWORK.md
+src/cli/commands/__init__.py
+src/cli/commands/base.py
+src/cli/commands/context.py
+src/cli/commands/graph.py
+src/cli/commands/init.py
+src/cli/commands/list.py
+tests/test_cli.py
+tests/test_examples.py

ai_forge_cli-2.1.0/src/ai_forge_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyyaml>=6.0
+
+[dev]
+pytest>=8

ai_forge_cli-2.1.0/src/cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "2.1.0"

{ai_forge_cli-2.0.3 → ai_forge_cli-2.1.0}/src/cli/__main__.py

@@ -1,4 +1,5 @@
 from cli.forge import main
 
+
 if __name__ == "__main__":
     raise SystemExit(main())

ai_forge_cli-2.1.0/src/cli/assets/agents_skills/forge-build/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: forge-build
+description: >
+  Forge V2 build skill. Use when the schema is complete enough for the target slices, the plan exists,
+  and the user wants working implementation code and tests generated while preserving runnability. Acts
+  as an orchestrator: validates readiness, consults the plan, dispatches implementation work using
+  forge context, checks bootstrap continuously, and updates workbench status and validation evidence.
+---
+
+# forge-build
+
+Read before starting:
+
+- `docs/forge-v2-schema.md`
+- `docs/forge-v2-architecture.md`
+- `frameworks/build/FRAMEWORK.md`
+- `forge/workbench/discovery.md`
+- `forge/workbench/plan.yaml`
+
+## Purpose
+
+Implement the planned slices while keeping the system runnable.
+
+This stage is not a free-form code generator. It is a bootstrap-first implementation orchestrator.
+
+`forge/workbench/*` files are internal framework artifacts in V2. They are produced and consumed by the stage skills; they are not separate public CLI commands.
+
+## Non-negotiables
+
+1. Bootstrap first. No broad implementation before the bootstrap path exists.
+2. Run bootstrap as early as possible.
+3. Build against the running bootstrap when possible.
+4. Re-check startup, bootstrap, and affected flows after each material slice.
+5. If automation is insufficient, require operator verification instead of pretending coverage exists.
+6. Schema files are frozen during a build run. Do not silently edit schema truth to make implementation easier.
+
+## Inputs
+
+- schema under `forge/`
+- `forge/workbench/plan.yaml`
+- existing repo state
+- verification items
+
+## Workbench Outputs
+
+- `forge/workbench/status.yaml`
+- `forge/workbench/validation.md`
+
+## Source Control Outputs
+
+At each meaningful checkpoint, the build stage should also update source control state.
+
+Checkpoint examples:
+
+- bootstrap first becomes runnable
+- a planned slice lands
+- a meaningful runtime or contract change lands without breaking bootstrap
+
+Expected behavior:
+
+1. inspect git state
+2. summarize the checkpoint in plain language
+3. create a checkpoint commit when the human or repo policy allows it
+4. push or update the GitHub branch when a remote exists and credentials are available
+5. if push is not possible, stop at a clean local checkpoint and record the next action explicitly
+
+## Step 1 — Readiness Gate
+
+Before writing code:
+
+1. inspect the plan
+2. inspect the bootstrap definition
+3. use `forge list` and `forge context` to confirm the relevant schema objects and IDs
+4. stop if the schema is structurally ambiguous or incomplete
+
+If bootstrap is underspecified, route back to `forge-spec` or `forge-plan` rather than guessing.
+
+## Step 2 — Bootstrap Assessment
+
+Establish:
+
+- whether bootstrap already exists in runnable form
+- what commands or checks prove it
+- what operator verification is required
+
+If bootstrap does not exist yet:
+
+- implement the minimum bootstrap slice first
+- do not parallelize expansion work ahead of it
+
+## Step 3 — Execution Plan
+
+Work slice by slice from `forge/workbench/plan.yaml`.
+
+For each slice:
+
+1. load schema context through `forge context`
+2. identify touched units, operations, surfaces, flows, and stores
+3. implement the smallest complete version of that slice
+4. run the declared checks
+5. update workbench status
+6. update git/GitHub at the slice checkpoint when the change is meaningful
+
+## Step 4 — Subagent Dispatch
+
+When delegation is useful, subagents should receive:
+
+- the slice or target ID
+- the instruction to call `forge context <id>`
+- the architecture and layout rules implied by the repo and plan
+- the requirement to implement exactly what the schema declares
+
+Subagents should not be given giant inlined schema dumps when the CLI can provide context directly.
+
+## Step 5 — Failure Handling
+
+If a slice fails:
+
+1. identify whether the failure is implementation, architecture, or schema ambiguity
+2. retry implementation failures with specific feedback
+3. stop immediately on schema ambiguity and surface it to the human
+4. if bootstrap breaks, repair bootstrap before continuing
+
+## Step 6 — Checkpoint Source Control
+
+At each checkpoint:
+
+1. confirm bootstrap and the touched slice still work at the declared level
+2. review `git status`
+3. prepare a checkpoint summary tied to the slice or bootstrap milestone
+4. create a checkpoint commit if permitted
+5. push the branch or update the open GitHub branch if permitted and possible
+
+Do not batch many meaningful slice landings into one opaque commit when the framework can keep checkpoints intelligible.
+
+## Failure Routing
+
+- If bootstrap is missing or underspecified, stop and route back to `forge-plan` or `forge-spec`.
+- If implementation pressure reveals missing or conflicting contracts, stop and route back to `forge-spec` instead of mutating schema truth ad hoc.
+- If the current plan no longer reflects the real execution order, stop and route back to `forge-plan`.
+- If operator verification is required before expansion, stop after bootstrap hardening and hand off to `forge-validate` or the human operator.
+- If a GitHub update is required by the workflow but remote state, permissions, or branch policy block it, stop and surface that operational blocker instead of silently continuing.
+
+## Completion
+
+When a slice lands:
+
+1. record status in `forge/workbench/status.yaml`
+2. record validation evidence in `forge/workbench/validation.md`
+3. state whether bootstrap was preserved, expanded, or regressed
+4. state whether the checkpoint was committed locally, pushed to GitHub, or blocked operationally
+
+When all planned slices for the run are complete:
+
+1. summarize files written
+2. summarize bootstrap health
+3. recommend `forge-validate`
+
+## Key Constraints
+
+- Do not continue building through a broken bootstrap.
+- Do not claim a slice is done without running its declared checks.
+- Do not hide operator-required checks in prose; they must correspond to verification items.

ai_forge_cli-2.1.0/src/cli/assets/agents_skills/forge-cast/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: forge-cast
+description: >
+  Forge V2 casting skill for existing codebases. Use when a user has an implemented project and wants
+  to derive a draft Forge V2 schema from the code, config, tests, and contracts that already exist.
+  Produces draft V2 schema files plus a cast report that separates high-confidence evidence from open
+  uncertainty.
+---
+
+# forge-cast
+
+Read before starting:
+
+- `docs/forge-v2-schema.md`
+- `docs/forge-v2-architecture.md`
+- `frameworks/cast/FRAMEWORK.md`
+
+## Purpose
+
+Translate an existing codebase into a draft Forge V2 schema and workbench context.
+
+This stage should never invent requirements that the repo does not support.
+
+## Evidence Standard
+
+When signals disagree, prefer:
+
+1. executable code and typed schemas
+2. config and deployment artifacts
+3. tests
+4. machine-readable contracts
+5. repository docs
+6. naming heuristics
+
+Low-confidence conclusions belong in `forge/workbench/cast-report.md`, not as hard schema truth.
+
+## Output Artifacts
+
+| File | Contents |
+|------|----------|
+| `forge/system.yaml` | Draft system identity and posture |
+| `forge/verticals/*.yaml` | Capability slices inferred from repo seams |
+| `forge/units/*.yaml` | Runtime boundaries inferred from services, apps, workers, or CLIs |
+| `forge/types/*.yaml` | Canonical types inferred from code and contracts |
+| `forge/operations/*.yaml` | Business actions inferred from handlers, commands, jobs, or services |
+| `forge/surfaces/*.yaml` | Reachability bindings inferred from routes, queues, cron jobs, or commands |
+| `forge/stores/*.yaml` | Persistence backbones inferred from config and code |
+| `forge/flows/*.yaml` | Higher-confidence end-to-end journeys inferred from orchestration paths |
+| `forge/bootstrap.yaml` | Draft first working slice inferred from the most central runnable path |
+| `forge/verification/**/*` | Starter checks inferred from health routes, tests, or obvious workflows |
+| `forge/workbench/discovery.md` | Repo-level observations and rationale |
+| `forge/workbench/cast-report.md` | Uncertain candidates, gaps, and questions for human review |
+
+## Process
+
+### Step 1 — Assess the Repo
+
+Before writing anything:
+
+- identify the runtime profile
+- identify runnable entrypoints
+- identify exposed interfaces
+- identify persistent storage
+- identify the likeliest bootstrap path
+
+### Step 2 — Draft High-Confidence Schema
+
+Write only what is strongly supported:
+
+- system
+- units
+- obvious verticals
+- canonical operations
+- surfaces
+- stores
+- bootstrap
+
+### Step 3 — Record Uncertainty
+
+Anything supported only weakly should go to `forge/workbench/cast-report.md` with:
+
+- inferred object
+- evidence source
+- confidence level
+- question for the human
+
+### Step 4 — Hand Over
+
+Recommend the human review:
+
+- the bootstrap draft
+- operation boundaries
+- auth contexts
+- verification gaps
+
+Then route to `forge-spec` and `forge-review`.
+
+## Failure Routing
+
+- If the inferred bootstrap path is weak or contradictory, stop and route to `forge-discover` instead of pretending the repo already implies one clear path.
+- If the repo exposes operations or contracts ambiguously, draft only the high-confidence subset and route the rest to `forge-spec`.
+- If the human asks for implementation changes during cast, stop and hand off to `forge-build` only after the inferred schema is reviewed.
+
+## Key Constraints
+
+- no speculative requirements
+- no implementation changes
+- no fake certainty