atomadic-forge 0.54.0__tar.gz → 0.56.0__tar.gz

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/.github/workflows/metrics-auto-regen.yml

@@ -89,14 +89,16 @@ jobs:
               p.write_text(json.dumps(d, indent=2, sort_keys=True) + "\n")
           PY
           fi
+      - name: Auto-update docs from metrics
+        run: forge doc-update || true
       - name: Commit if drifted
         run: |
           git config user.name  "atomadic-bot"
           git config user.email "bot@atomadic.tech"
-          if git diff --quiet -- forge_metrics.json; then
-            echo "metrics already current — no commit"
+          if git diff --quiet -- forge_metrics.json README.md CHANGELOG.md; then
+            echo "metrics and docs already current — no commit"
             exit 0
           fi
-          git add forge_metrics.json
-          git commit -m "chore(metrics): auto-regenerate forge_metrics.json [skip ci]"
+          git add forge_metrics.json README.md CHANGELOG.md
+          git commit -m "chore(metrics): auto-regenerate metrics + docs [skip ci]"
           git push origin main

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/.github/workflows/publish-on-tag.yml

@@ -63,6 +63,7 @@ jobs:
           passed=$(echo "${ptout:-}" | grep -oE '[0-9]+ passed' | head -1 | grep -oE '[0-9]+' || echo 0)
           echo "pytest passed count: ${passed:-0}"
           forge metrics --apply --tests-passing "${passed:-0}" || true
+          forge doc-update || true
           v=$(jq -r .package_version forge_metrics.json 2>/dev/null || echo "?")
           echo "forge_metrics.json regenerated at tag time (version: $v)"
           exit 0  # always succeed — never block the release

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/CHANGELOG.md

@@ -2,6 +2,184 @@
 
 ## Unreleased
 
+## v0.56.0 — 2026-05-08 — Zero-token automation: auto-wire, doc-drift, lean preservation
+
+### Added
+
+**`apply_wire_stubs` — direct MCP+CLI injection** (zero copy-paste wiring)
+
+`wire_stubs_gen.apply_wire_stubs()` injects a new MCP handler, both explore and
+audit dispatch elifs, updated enum lists, a CLI command, and a test skeleton
+directly into the correct files. No manual copy-paste required.
+
+- `forge wire-stubs <module> <function> --apply [--dry-run]`
+- MCP: `audit(action='wire_stubs')` with `apply=true`
+
+**`forge auto-wire` — batch auto-wiring of all surface gaps**
+
+One command: `surface-gaps` → `apply_wire_stubs` for every unwired a1 entry
+point, with full dry-run support.
+
+- `forge auto-wire [--top-n N] [--dry-run] [--tools explore,audit]`
+- MCP: `audit(action='auto_wire')`
+
+**`forge doc-update` — zero-LLM-token documentation regeneration**
+
+Reads `forge_metrics.json` + live MCP/CLI source, rewrites bounded sections in
+README, CHANGELOG, WHITEPAPER, IDE_INTEGRATION, and AGENTS_GUIDE.
+
+- `forge doc-update [--sections readme,changelog,extended_docs] [--dry-run]`
+- MCP: `audit(action='doc_update')`
+- Integrated into `metrics-auto-regen.yml` and `publish-on-tag.yml`
+- Schema: `atomadic-forge.doc_auto_update/v1`
+
+**`forge doc-drift` — CI-gateable doc staleness detector**
+
+Scans docs for stale MCP tool/action/test counts vs live `forge_metrics.json`.
+Exits 1 when drift is found — suitable as a pre-push or CI gate.
+
+- `forge doc-drift [--json]`
+- MCP: `audit(action='doc_drift')`
+
+### Fixed
+
+**`forge_metrics.py` — lean_theorems preservation**
+
+`forge metrics --apply` no longer zeroes the lean_theorems count when the proof
+corpus is unavailable. Prior count is preserved whenever `found=False` but the
+existing `forge_metrics.json` has `count > 0`. Same preservation for
+`tests_passing` across local runs.
+
+**16-item documentation discrepancy audit resolved**
+
+- WHITEPAPER: 5× "46 MCP tools" → "10 MCP tools dispatching 79 actions"
+- `docs/IDE_INTEGRATION.md`: "66 tools" → "10 tools dispatching 79 actions"
+- `docs/MCP_TOOLS.md`: created (fixed broken README link)
+- README, AGENTS_GUIDE: pipeline terminology `scout→assimilate` → `recon→cherry→wire`
+- AGENTS.md: removed non-existent `launch/forge/GOLDEN_PATH-20260428.md` path
+- `docs/RECEIPT.md`: `forge_version: "0.2.2"` → `"0.56.0"`
+- `docs/FORMALIZATION.md`: `post-v0.14` → `post-v0.55.0`
+- `tests/README.md`: created with tier map, fixture conventions, run commands
+
+### Metrics
+
+| Metric | v0.55.x → v0.56.0 |
+|--------|-------------------|
+| MCP actions | 76 → **79** |
+| CLI verbs | 80 → **83** |
+| Source files | 221 → **222** |
+| Tests | 1,465 → **1,560** |
+| Certify score | 100/100 |
+| Wire violations | 0 |
+
+## v0.55.0 — 2026-05-08 — Auto-wire pipeline, doc-update automation
+
+### Added
+
+**`apply_wire_stubs` — direct MCP+CLI injection** (zero copy-paste wiring)
+
+`wire_stubs_gen.apply_wire_stubs()` injects a new MCP handler, both explore and
+audit dispatch elifs, updated enum lists, a CLI command, and a test skeleton
+directly into the correct files — no manual copy-paste required.
+
+- `forge wire-stubs <module> <function> --apply`
+- `forge wire-stubs <module> <function> --dry-run`
+
+**`forge auto-wire` — batch auto-wiring of all surface gaps**
+
+New CLI command that runs `surface-gaps` then calls `apply_wire_stubs` for
+every unwired a1 entry point in one shot.
+
+- `forge auto-wire [--top-n N] [--dry-run] [--tools explore,audit]`
+- MCP: `audit(action='auto_wire')`
+
+**`doc_auto_update` — zero-LLM-token documentation regeneration**
+
+New `a1_at_functions/doc_auto_update.py` reads `forge_metrics.json` and live
+MCP/CLI source, then rewrites bounded sections in README.md and CHANGELOG.md
+programmatically — no LLM needed.
+
+- `forge doc-update [--sections readme,changelog] [--dry-run]`
+- MCP: `audit(action='doc_update')`
+- Integrated into `metrics-auto-regen.yml` and `publish-on-tag.yml` CI pipelines
+- Schema: `atomadic-forge.doc_auto_update/v1`
+
+
+## v0.54.0 — 2026-05-07 — Synthesis pipeline: gap analysis, TAU_TRUST bridge, auto-wiring tools
+
+### Added
+
+**`surface_gaps` — a1 MCP/CLI coverage gap finder** (pipeline gap analysis)
+
+New `a1_at_functions/surface_gaps.py` with `find_surface_gaps()`. AST-walks the
+a1 tier and compares entry points against registered MCP actions and CLI verbs,
+returning a list of functions with no MCP coverage, no CLI coverage, or both.
+
+- `forge surface-gaps`
+- MCP: `explore(action='surface_gaps')`, `audit(action='surface_gaps')`
+- Schema: `atomadic-forge.surface_gaps/v1`
+
+**`wire_stubs` — auto-wiring scaffold generator** (pipeline gap analysis)
+
+New `a1_at_functions/wire_stubs.py` with `generate_wire_stubs()`. Given a module
+path and function name, emits a ready-to-paste MCP handler block, a CLI stub
+entry, and a test skeleton — removing the manual plumbing step for every new
+a1 function.
+
+- `forge wire-stubs <module> <function>`
+- MCP: `audit(action='wire_stubs')`
+- Schema: `atomadic-forge.wire_stubs/v1`
+
+**`capability_scout` — GitHub harvest target search** (pipeline gap analysis)
+
+New `a1_at_functions/capability_scout.py` with `search_capability_repos()`.
+Accepts one or more freeform query strings and returns ranked GitHub repositories
+suitable as harvest candidates, enriched with star count, last-push date, and
+primary language.
+
+- `forge capability-scout --queries "q1,q2"`
+- MCP: `explore(action='capability_scout')`
+- Schema: `atomadic-forge.capability_scout/v1`
+
+**`dead_code` — AST-walk dead symbol detector** (vulture synthesis)
+
+New `a1_at_functions/dead_code.py` with `detect_dead_symbols()`. Walks the
+package AST using vulture and returns symbols that are defined but never
+referenced, grouped by tier with confidence scores.
+
+- `forge dead-code`
+- MCP: `explore(action='dead_code')`, `audit(action='dead_code')`
+- Schema: `atomadic-forge.dead_code/v1`
+
+**`maintainability` — Maintainability Index per module** (radon synthesis)
+
+New `a1_at_functions/maintainability.py` with `compute_maintainability()`.
+Runs radon MI analysis across every source module and returns per-file grades
+(A/B/C/D) with raw MI score, ranked from least to most maintainable.
+
+- `forge maintainability`
+- MCP: `explore(action='maintainability')`, `audit(action='maintainability')`
+- Schema: `atomadic-forge.maintainability/v1`
+
+**`concept_bridge` — TAU_TRUST harvest bridge** (TAU_TRUST bridge)
+
+New `a1_at_functions/concept_bridge.py` with `bridge_harvest_concepts()`.
+Reads a `harvest.json` produced by `forge harvest`, filters candidates whose
+trust score falls below TAU_TRUST (1820/1823), and converts each into an
+actionable synthesis plan with a recommended absorb sequence and preflight
+checklist.
+
+- `forge concept-bridge --harvest-json path/to/harvest.json`
+- MCP: `explore(action='concept_bridge')`, `audit(action='concept_bridge')`
+- Schema: `atomadic-forge.concept_bridge/v1`
+
+### metrics
+
+- CLI verbs: 80 (+6)
+- MCP actions: 76 (+10)
+- Tests: 1465 (+42 over v0.53.0)
+- Source files: 221 (+6)
+
 ## v0.53.0 — 2026-05-07 — Harvest synthesis: call-graph-summary, git churn, token budget
 
 ### feat(synthesis): three new a1 capabilities absorbed from harvest pipeline

{atomadic_forge-0.54.0/src/atomadic_forge.egg-info → atomadic_forge-0.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.54.0
+Version: 0.56.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1
@@ -121,7 +121,7 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 
 | Command | What it does |
 |---------|-------------|
-| `forge auto` | **Flagship.** scout -> cherry -> assimilate -> wire -> certify -> receipt |
+| `forge auto` | **Flagship.** recon → cherry → wire → certify → receipt |
 | `forge recon` | Scan a repo — classify every symbol, show tier distribution |
 | `forge wire` | Detect upward-import violations |
 | `forge certify` | Architecture score (0-100): docs, tests, tier layout, imports |
@@ -141,6 +141,12 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge cna-check` | Compose-Not-Add — flag duplicates before writing |
 | `forge trust-gate` | LLM response hallucination detector |
 | `forge preflight` | Pre-edit guardrail: tier + import + scope check |
+| `forge surface-gaps` | Find a1 entry points missing MCP or CLI coverage |
+| `forge wire-stubs <module> <function>` | Generate MCP handler + CLI stub + test skeleton for any unwired a1 function |
+| `forge capability-scout --queries "q1,q2"` | Search GitHub for harvest target repos |
+| `forge dead-code` | AST-walk dead symbol detector (vulture synthesis) |
+| `forge maintainability` | Maintainability Index per module (radon MI: A/B/C/D ranking) |
+| `forge concept-bridge --harvest-json path/to/harvest.json` | Convert harvest candidates below TAU_TRUST into actionable synthesis plans |
 
 ### Composition & Multi-Repo
 
@@ -160,11 +166,11 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge plan` | Bounded execution plan with risk + rollback |
 | `forge chat` | Terminal copilot over forge docs |
 
-**74 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**83 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 65 Actions
+## MCP Server — 10 Tools, 79 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -179,13 +185,13 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 66 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
+**10 tools, 76 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
 
 | Tool | Actions | What it does |
 |------|---------|-------------|
 | `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, capability tour |
-| `explore` | 11 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn |
-| `audit` | 14 | Quality gates, change safety, trust |
+| `explore` | 16 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
+| `audit` | 22 | Quality gates, change safety, trust |
 | `plan` | 9 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
 | `loop` | 4 | LLM iteration loops — iterate/resume/evolve/evolve_step |
@@ -206,11 +212,12 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | Metric | Value |
 |--------|-------|
-| MCP tools | **10 tools · 66 actions** |
-| CLI verbs | **74** |
-| Source files | **211** (~40,195 LOC) |
-| Tests | **1,423 passing** across **97 test files** |
-| Lean4 formal proofs | **872 theorems** across 30 files (mathematically verified core logic — IP-protected formal verification moat) |
+
+| MCP tools | **10 tools · 79 actions** |
+| CLI verbs | **83** |
+| Source files | **222** (~43K LOC) |
+| Tests | **1476 passing** across **105 test files** |
+| Lean4 formal proofs | not yet active |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |
 | Infrastructure cost | **$5/mo** |
@@ -227,7 +234,7 @@ Forge eats its own cooking. Every CI run scores itself.
 |------|-------|-------------|
 | **Free** | $0 | OSS, 25 calls/day, read-only tools |
 | **One-Time Refactor** | ~~$149~~ **$99** | We run `auto` on your repo -> PR targeting 100/100. One revision included. |
-| **Starter** | $79/mo | All 10 tools (66 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (76 actions), 5k calls/mo, signed receipts, custom recipes |
 | **Pro** | $249/mo | + notarization, compliance attestations, cross-repo telemetry |
 | **Founding Member** | $999/yr | Everything. Forever. First 25 only. |
 | **Enterprise** | Custom | BSL commercial license, SSO, self-host, SLA |

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/README.md

@@ -89,7 +89,7 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 
 | Command | What it does |
 |---------|-------------|
-| `forge auto` | **Flagship.** scout -> cherry -> assimilate -> wire -> certify -> receipt |
+| `forge auto` | **Flagship.** recon → cherry → wire → certify → receipt |
 | `forge recon` | Scan a repo — classify every symbol, show tier distribution |
 | `forge wire` | Detect upward-import violations |
 | `forge certify` | Architecture score (0-100): docs, tests, tier layout, imports |
@@ -109,6 +109,12 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge cna-check` | Compose-Not-Add — flag duplicates before writing |
 | `forge trust-gate` | LLM response hallucination detector |
 | `forge preflight` | Pre-edit guardrail: tier + import + scope check |
+| `forge surface-gaps` | Find a1 entry points missing MCP or CLI coverage |
+| `forge wire-stubs <module> <function>` | Generate MCP handler + CLI stub + test skeleton for any unwired a1 function |
+| `forge capability-scout --queries "q1,q2"` | Search GitHub for harvest target repos |
+| `forge dead-code` | AST-walk dead symbol detector (vulture synthesis) |
+| `forge maintainability` | Maintainability Index per module (radon MI: A/B/C/D ranking) |
+| `forge concept-bridge --harvest-json path/to/harvest.json` | Convert harvest candidates below TAU_TRUST into actionable synthesis plans |
 
 ### Composition & Multi-Repo
 
@@ -128,11 +134,11 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge plan` | Bounded execution plan with risk + rollback |
 | `forge chat` | Terminal copilot over forge docs |
 
-**74 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**83 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 65 Actions
+## MCP Server — 10 Tools, 79 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -147,13 +153,13 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 66 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
+**10 tools, 76 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
 
 | Tool | Actions | What it does |
 |------|---------|-------------|
 | `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, capability tour |
-| `explore` | 11 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn |
-| `audit` | 14 | Quality gates, change safety, trust |
+| `explore` | 16 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
+| `audit` | 22 | Quality gates, change safety, trust |
 | `plan` | 9 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
 | `loop` | 4 | LLM iteration loops — iterate/resume/evolve/evolve_step |
@@ -174,11 +180,12 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | Metric | Value |
 |--------|-------|
-| MCP tools | **10 tools · 66 actions** |
-| CLI verbs | **74** |
-| Source files | **211** (~40,195 LOC) |
-| Tests | **1,423 passing** across **97 test files** |
-| Lean4 formal proofs | **872 theorems** across 30 files (mathematically verified core logic — IP-protected formal verification moat) |
+
+| MCP tools | **10 tools · 79 actions** |
+| CLI verbs | **83** |
+| Source files | **222** (~43K LOC) |
+| Tests | **1476 passing** across **105 test files** |
+| Lean4 formal proofs | not yet active |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |
 | Infrastructure cost | **$5/mo** |
@@ -195,7 +202,7 @@ Forge eats its own cooking. Every CI run scores itself.
 |------|-------|-------------|
 | **Free** | $0 | OSS, 25 calls/day, read-only tools |
 | **One-Time Refactor** | ~~$149~~ **$99** | We run `auto` on your repo -> PR targeting 100/100. One revision included. |
-| **Starter** | $79/mo | All 10 tools (66 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (76 actions), 5k calls/mo, signed receipts, custom recipes |
 | **Pro** | $249/mo | + notarization, compliance attestations, cross-repo telemetry |
 | **Founding Member** | $999/yr | Everything. Forever. First 25 only. |
 | **Enterprise** | Custom | BSL commercial license, SSO, self-host, SLA |

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/docs/AGENTS_GUIDE.md

@@ -20,8 +20,8 @@ report on it:**
 
 | MCP tool | Use this when |
 |---|---|
-| **`auto`** | Use this when: you want forge to absorb any source repo into a tier-disciplined output package in one call (scout → cherry → assimilate → wire → certify). |
-| **`cherry`** | Use this when: you want a cherry-pick manifest of symbols from a scouted repo before assimilating — surgical control over what gets imported. |
+| **`auto`** | Use this when: you want forge to absorb any source repo into a tier-disciplined output package in one call (recon → cherry → wire → certify). |
+| **`cherry`** | Use this when: you want a cherry-pick manifest of symbols from a recon'd repo before applying — surgical control over what gets imported. |
 | **`finalize`** | Use this when: you have a cherry-pick manifest and want to materialize it into a tier-organized output package, then wire and certify. |
 | **`iterate`** *(CLI only today; MCP in Round 3)* | Use this when: you have an intent string and want forge to drive an LLM loop until certify >= target_score. The MCP exposure is being refactored so the **calling agent drives its own LLM** — forge supplies analytical certainty between turns instead of holding an LLM client internally. Use `forge iterate` from the CLI today. |
 | **`evolve`** *(CLI only today; MCP in Round 3)* | Use this when: you want recursive iterate that treats prior output as seed catalog. Same Round-3 refactor as `iterate`. Use `forge evolve` from the CLI today. |
@@ -35,7 +35,7 @@ report on it:**
 - `on_conflict` — `rename` (default) | `first` | `last` | `fail`
 
 `cherry(target, *, names=None, pick_all=False, only_tier=None)`
-- `target` — repo that was previously scouted
+- `target` — repo that was previously recon'd
 - `names` — explicit list of qualnames to cherry-pick; omit for `pick_all`
 - `pick_all=True` — cherry-pick every scouted symbol
 - `only_tier` — restrict to one tier (e.g. `"a1_at_functions"`)
@@ -332,6 +332,12 @@ agent tool-selection can route by trigger phrase. Quick reference:
 | You want to recall what prior agents learned about this repo | `wisdom recall` (or read `prior_wisdom` from `recon`) |
 | You want to record a lesson for future agents | `wisdom record` |
 | You're emitting or verifying the canonical tool/recipe surface | `surface emit` / `surface check` / `surface diff` |
+| You want to find a1 functions not yet wired to MCP or CLI | `surface_gaps` — `explore(action='surface_gaps')` or `audit(action='surface_gaps')` |
+| You want to auto-generate MCP handler + CLI stub + test for an unwired function | `wire_stubs` — `audit(action='wire_stubs')` |
+| You want to find GitHub repos suitable as harvest targets | `capability_scout` — `explore(action='capability_scout')` |
+| You want to identify symbols defined but never referenced | `dead_code` — `explore(action='dead_code')` or `audit(action='dead_code')` |
+| You want Maintainability Index grades per module (A/B/C/D) | `maintainability` — `explore(action='maintainability')` or `audit(action='maintainability')` |
+| You want to convert low-trust harvest candidates into synthesis plans | `concept_bridge` — `explore(action='concept_bridge')` or `audit(action='concept_bridge')` |
 
 ---
 
@@ -385,6 +391,12 @@ in a loop:
 | **`call_graph`** | callers / callees up to `max_depth` hops (BFS, AST-based) | Before mutating a target symbol; closes Forge's call-graph gap vs Code Pathfinder / Moderne. |
 | **`call_graph_summary`** (`explore(action='call_graph_summary')`) | whole-package call-graph portfolio: `orphans` (unreachable symbols), `hotspots` ranked by fan-in, `max_depth`; schema `atomadic-forge.call_graph_summary/v1` | When you need a portfolio view of the entire package's call topology — which symbols are islands, which are load-bearing. CLI: `forge call-graph-summary --project <root> [--package NAME] [--top-n N] [--json]`. |
 | **`churn`** (`explore(action='churn')`) | file-level git commit frequency: `hotspot_files`, `stable_files`, `avg_commits`, `median_commits`, `date_range`; schema `atomadic-forge.git_churn/v1` | When you want to know which files change most often (high review priority) and which are stable (safe to refactor). CLI: `forge churn --project <root> [--since '6 months ago'] [--top-n N] [--all-files] [--json]`. |
+| **`surface_gaps`** (`explore(action='surface_gaps')` or `audit(action='surface_gaps')`) | list of a1 entry points with no MCP coverage, no CLI coverage, or both; schema `atomadic-forge.surface_gaps/v1` | Before a release cycle — find functions that are live but inaccessible through agent or CLI surfaces. Feeds directly into `wire_stubs`. CLI: `forge surface-gaps [--project <root>] [--json]`. |
+| **`wire_stubs`** (`audit(action='wire_stubs')`) | ready-to-paste MCP handler block, CLI stub entry, and pytest skeleton for the named function; schema `atomadic-forge.wire_stubs/v1` | When `surface_gaps` reveals an unwired a1 function and you want the scaffolding generated rather than hand-authored. CLI: `forge wire-stubs <module> <function> [--apply] [--json]`. |
+| **`capability_scout`** (`explore(action='capability_scout')`) | ranked GitHub repositories suitable as `forge harvest` candidates, enriched with star count, last-push date, and primary language; schema `atomadic-forge.capability_scout/v1` | When you need harvest target repos for a capability gap and don't have candidates yet. CLI: `forge capability-scout --queries "q1,q2" [--top-n N] [--json]`. |
+| **`dead_code`** (`explore(action='dead_code')` or `audit(action='dead_code')`) | symbols defined but never referenced, grouped by tier with confidence scores; schema `atomadic-forge.dead_code/v1` | When `certify` is green but you suspect the codebase has accumulated unreachable symbols. CLI: `forge dead-code [--project <root>] [--min-confidence N] [--json]`. |
+| **`maintainability`** (`explore(action='maintainability')` or `audit(action='maintainability')`) | per-module radon MI scores with letter grades (A/B/C/D), ranked lowest to highest; schema `atomadic-forge.maintainability/v1` | When `smell_scan` flags complexity issues and you want a module-level MI ranking to prioritize refactoring. CLI: `forge maintainability [--project <root>] [--min-grade B] [--json]`. |
+| **`concept_bridge`** (`explore(action='concept_bridge')` or `audit(action='concept_bridge')`) | actionable synthesis plans for each harvest candidate below TAU_TRUST (1820/1823), with recommended absorb sequence and preflight checklist; schema `atomadic-forge.concept_bridge/v1` | After `forge harvest` — convert low-trust candidates into ready-to-execute synthesis plans instead of discarding them. CLI: `forge concept-bridge --harvest-json path/to/harvest.json [--json]`. |
 | **`smell_scan`** | cyclomatic-complexity / long-function / duplicate-body findings + `smell_score` | When `certify` is green but maintainability is still suspect. |
 | **`wisdom_record` / `wisdom_query` / `wisdom_list` / `wisdom_recall`** (since v0.13.1) | append entry / relevance-rank / full DB read / top-N repo-scoped recall against `.atomadic-forge/wisdom.jsonl` | Agents inherit prior lessons (`wisdom_recall`); record new ones after accepted fixes (`wisdom_record`). The 4-tool MCP surface that lets Cognition wire `WISDOM_RECORD` as a cycle action verb. |
 | **`surface`** | emit / check / diff the canonical `surface.json` artifact | CI gate (`check`) and consumer bootstrap (`emit`); zero hand-maintained tool maps. |

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.53.0.
+All verbs available in the `forge` CLI as of 0.54.0.
 
 > For the structured per-verb reference (with options, examples, and
 > output samples), see [02-commands.md](02-commands.md). This page is
@@ -494,7 +494,7 @@ Prints the installed Forge version and exits 0. Hardened in v0.3.0
 
 ```bash
 $ forge --version
-atomadic-forge 0.53.0
+atomadic-forge 0.54.0
 ```
 
 ### `.forge` sidecars — Lane D W8
@@ -808,6 +808,106 @@ forge churn --project <root> [--since '6 months ago'] [--top-n N] [--all-files]
 
 Schema: `atomadic-forge.git_churn/v1`. MCP: `explore(action='churn')`. a1 source: `a1_at_functions/git_churn.py` → `compute_git_churn()`.
 
+### `forge surface-gaps`
+
+AST-walks the a1 tier and compares every public entry point against the
+registered MCP action list and CLI verb list. Returns functions that have no
+MCP coverage, no CLI coverage, or both — the precise gap list that feeds
+`forge wire-stubs`.
+
+```bash
+forge surface-gaps
+forge surface-gaps --json
+forge surface-gaps --project src/my_pkg --json | jq '.gaps[] | select(.missing_cli)'
+```
+
+Schema: `atomadic-forge.surface_gaps/v1`. MCP: `explore(action='surface_gaps')`,
+`audit(action='surface_gaps')`. a1 source: `a1_at_functions/surface_gaps.py` →
+`find_surface_gaps()`.
+
+### `forge wire-stubs <module> <function>`
+
+Generates the three scaffolding artifacts needed to wire any unwired a1 function
+into the full Forge surface: an MCP handler block, a CLI stub entry, and a
+pytest skeleton. Output is printed to stdout (pipe to `--apply` to insert in
+place).
+
+```bash
+forge wire-stubs a1_at_functions.my_module my_function
+forge wire-stubs a1_at_functions.my_module my_function --apply
+forge wire-stubs a1_at_functions.my_module my_function --json
+```
+
+Schema: `atomadic-forge.wire_stubs/v1`. MCP: `audit(action='wire_stubs')`. a1
+source: `a1_at_functions/wire_stubs.py` → `generate_wire_stubs()`.
+
+### `forge capability-scout --queries "q1,q2"`
+
+Searches GitHub for repositories suitable as `forge harvest` candidates. Accepts
+one or more comma-separated freeform query strings and returns a ranked list
+enriched with star count, last-push date, primary language, and a
+harvest-readiness score.
+
+```bash
+forge capability-scout --queries "async task queue python"
+forge capability-scout --queries "markdown parser,rst converter" --top-n 10 --json
+```
+
+Schema: `atomadic-forge.capability_scout/v1`. MCP:
+`explore(action='capability_scout')`. a1 source:
+`a1_at_functions/capability_scout.py` → `search_capability_repos()`.
+
+### `forge dead-code`
+
+AST-walks the package using vulture synthesis and returns every symbol that is
+defined but never referenced, grouped by tier with per-symbol confidence scores.
+High-confidence dead symbols are safe to remove; lower confidence items are
+flagged for human review.
+
+```bash
+forge dead-code
+forge dead-code --project src/atomadic_forge --min-confidence 80 --json
+```
+
+Schema: `atomadic-forge.dead_code/v1`. MCP: `explore(action='dead_code')`,
+`audit(action='dead_code')`. a1 source: `a1_at_functions/dead_code.py` →
+`detect_dead_symbols()`.
+
+### `forge maintainability`
+
+Runs radon Maintainability Index analysis across every source module and returns
+per-file MI scores with letter grades: A (MI ≥ 20), B (MI ≥ 10), C (MI ≥ 0),
+D (MI < 0). Output is ranked from lowest to highest MI so the worst offenders
+surface first.
+
+```bash
+forge maintainability
+forge maintainability --project src/atomadic_forge --json
+forge maintainability --min-grade B --json | jq '.modules[] | select(.grade == "D")'
+```
+
+Schema: `atomadic-forge.maintainability/v1`. MCP:
+`explore(action='maintainability')`, `audit(action='maintainability')`. a1
+source: `a1_at_functions/maintainability.py` → `compute_maintainability()`.
+
+### `forge concept-bridge --harvest-json path/to/harvest.json`
+
+Reads a `harvest.json` produced by `forge harvest`, filters candidates whose
+trust score falls below TAU_TRUST (1820/1823 ≈ 0.9984), and converts each into
+an actionable synthesis plan. Each plan includes a recommended absorb sequence,
+tier placement, and preflight checklist — bridging the gap between a raw harvest
+scan and a ready-to-execute `forge auto` call.
+
+```bash
+forge harvest ./target-repo --json > harvest.json
+forge concept-bridge --harvest-json harvest.json
+forge concept-bridge --harvest-json harvest.json --json > synthesis_plans.json
+```
+
+Schema: `atomadic-forge.concept_bridge/v1`. MCP:
+`explore(action='concept_bridge')`, `audit(action='concept_bridge')`. a1 source:
+`a1_at_functions/concept_bridge.py` → `bridge_harvest_concepts()`.
+
 ## LLM provider matrix
 
 | Provider | Cost | Env var | Default model | Notes |

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/docs/FORMALIZATION.md

@@ -39,7 +39,7 @@ Forge certify scores out of **100** in two layers:
 JS / TS packages cap at **60/100** today: they earn the four
 structural axes, but the +25 runtime-import smoke and +30 behavioural
 pytest are Python-only. Wiring `npm test` / Vitest into the
-behavioural axis is on the post-v0.14 roadmap.
+behavioural axis is on the post-v0.55.0 roadmap.
 
 ---
 
@@ -131,7 +131,7 @@ runtime dependency makes the package unusable.
 
 **Why JS/TS does not get this gate yet.** AAM §5.4 (Threats to
 Validity) explicitly flags polyglot runtime gating as a roadmap
-item (post-v0.14): the equivalent for JS would be an `npm test`
+item (post-v0.55.0): the equivalent for JS would be an `npm test`
 invocation, which requires a Node toolchain we do not yet bundle.
 
 **Citation.** AAM §5.1 (Core Pipeline Pseudocode); AAM §5.4 (Threats

{atomadic_forge-0.54.0 → atomadic_forge-0.56.0}/docs/IDE_INTEGRATION.md

@@ -16,7 +16,7 @@ See `vscode-extension/README.md` for settings + usage.
 
 ## 2. MCP server (works with any MCP-aware assistant)
 
-Forge ships a fully-typed MCP server with **66 tools** spanning recon, wire, certify, plan, enforce, emergent, synergy, wisdom, lineage, hive coordination, and AAAA-Nexus trust gates.  Any of these clients can attach:
+Forge ships a fully-typed MCP server with **10 tools dispatching 79 actions** spanning recon, wire, certify, plan, enforce, emergent, synergy, wisdom, lineage, hive coordination, and AAAA-Nexus trust gates.  Any of these clients can attach:
 
 - **Claude Code** (Anthropic CLI) — `claude mcp add atomadic-forge -- forge mcp serve --project ${workspaceFolder}`
 - **Cursor** — Settings → MCP Servers → add the same command above
@@ -80,4 +80,4 @@ All three were updated in v0.18.0 to use the current CLI argument shape (positio
 
 ## Agent instructions
 
-The full 66-tool catalog with use-case guidance lives in `skills/FORGE-AGENT-INSTRUCTIONS.md`.  Point any AI assistant at it (or include it as a system prompt) for tier-aware behaviour out of the gate.
+The full tool catalog with use-case guidance lives in `skills/FORGE-AGENT-INSTRUCTIONS.md`.  Point any AI assistant at it (or include it as a system prompt) for tier-aware behaviour out of the gate.