atomadic-forge 0.81.0__tar.gz → 0.83.0__tar.gz

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/CHANGELOG.md

@@ -2,44 +2,61 @@
 
 ## Unreleased
 
+## v0.83.0 — 2026-05-08
+
+- feat(forge): v0.83 — JS/TS graft support; arm Atomadic with capability transfer
+
+
+## v0.82.0 — 2026-05-08
+
+- feat(forge): v0.82 — graft sibling-ref auto-import + 2 grafted helpers
+- docs: README + CHANGELOG + docs/ updated for v0.76–v0.81
+
+
 ## v0.81.0 — 2026-05-08
 
-- feat(forge): v0.81 — auto-wire signature coercion + recon cache
+- feat(forge): auto-wire signature coercion — `list[T]` CLI args now parsed correctly; `forge cosine-similarity --a 1.0,0.0 --b 1.0,0.0` resolves without manual casting
+- feat(forge): `run_recon(use_cache=True)` — skip AST walk on unchanged trees via `(file_count, max_mtime, total_bytes)` fingerprint; eliminates redundant recon passes in harvest pipelines
+- fix(forge): close last harvest-pipeline residual exposed by recon cache audit
 
 
 ## v0.80.0 — 2026-05-08
 
-- feat(forge): v0.80 Monadic Laws — MCB / AHLP / AIOM / IFWC-lite
+- feat(forge): `forge mcb-check` — flag unbounded `while` loops and recursion in tier-a1 atoms (Monadic Compute Bounding); advisory by default, `--fail-on-violations` to enforce
+- feat(forge): `forge aiom-check` — flag forbidden I/O imports (`requests`, `urllib`, `socket`, `subprocess`) in tier-a1 (Algebraic I/O Monad law); advisory by default
+- feat(forge): `forge fingerprint` — SHA-256 of every a1 module's normalised AST (AHLP); stable across whitespace, tamper-evident, deterministic
+- feat(forge): `forge fuzz <module>` — hypothesis property tests on any a1 callable carrying `__invariants__` (IFWC-lite); all four verbs ship advisory, opt-in `--fail-on-violations` to block CI
 
 
 ## v0.79.0 — 2026-05-08
 
-- feat(forge): replay — deterministic golden-recipe execution
-- fix(compat): replace datetime.UTC with timezone.utc for Python 3.10 compat
-- fix(ci): null-safe head_commit.message in metrics-auto-regen if condition
-- chore(metrics): sync forge_metrics.json after cli_verb_count method change
-- fix(surface): regenerate surface.json with package_version 0.78.0
-- fix(metrics): replace upward a4 import in _live_cli_verb_count with file scan
+- feat(forge): `forge replay <recipe>` — runs a golden recipe's `validation_gate` as subprocesses with zero LLM round-trips per step; recipes: `release_hardening`, `add_cli_command`, `fix_wire_violation`, `add_feature`, `publish_mcp`; auto-logs pass+fail (×80 tokens) to ledger as `replay/<recipe-name>`
+- feat(forge): `--dry-run`, `--keep-going`, `--list`, `--json` flags on `forge replay`
+- fix(compat): replace `datetime.UTC` with `timezone.utc` for Python 3.10 compatibility
+- fix(ci): null-safe `head_commit.message` in metrics-auto-regen `if` condition
+- chore(metrics): sync `forge_metrics.json` after `cli_verb_count` method change
+- fix(surface): regenerate `surface.json` with package_version 0.78.0
+- fix(metrics): replace upward a4 import in `_live_cli_verb_count` with file scan
 - chore(release): sync artifacts + doc anchors for v0.78.0
 
 
 ## v0.78.0 — 2026-05-08
 
-- feat(forge): token-savings auto-ledger across every enriched verb
+- feat(forge): token-savings auto-ledger — every verb that calls `enrich_response` appends to `<project>/.atomadic-forge/lifetime_savings.jsonl`; verbs covered: recon, certify, wire, verify, auto, emergent, synergy
+- feat(forge): `forge token-savings` — display lifetime total + per-tool breakdown from the JSONL ledger; file-backed, verifiable, auditable
 
 
 ## v0.77.0 — 2026-05-08
 
-- fix(forge): cherry-pick — collapse Class.method explosion (root-cause)
+- fix(forge): cherry-pick now folds method qualnames whose parent class is already selected, collapsing the 47-file class explosion observed during IndexStore absorption; root-cause fix in `cherry_pick._dedup_methods_under_class`
 - feat(doc-update): auto-update 6 previously missed doc files on release
 
 
 ## v0.76.0 — 2026-05-08
 
-- feat(forge): graft — surgical single-symbol cross-repo capability transfer
+- feat(forge): `forge graft --source-file <f> --symbol <name>` — extract one function or class from any Python source and land it in the target's correct tier; `--rename` flag for private-to-public conversion; auto-wires CLI + MCP via `auto-wire` integration; closes the gap between `transmute auto` (whole-repo) and single-symbol surgical absorption
 - fix(lint): clear 14 ruff violations blocking CI
-- release: v0.75.3
-- fix(forge): GAP-014 — harvest fail-loud on missing/empty sources
+- fix(forge): GAP-014 — harvest fail-loud on missing/empty sources
 
 
 ## v0.75.3 — 2026-05-08

{atomadic_forge-0.81.0/src/atomadic_forge.egg-info → atomadic_forge-0.83.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.81.0
+Version: 0.83.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
@@ -67,6 +67,8 @@ AI agents write code **10x faster** than humans can review it. Pattern violation
 
 **Forge fixes that.**
 
+---
+
 > 🎯 **300+ public OSS Python repositories absorbed end-to-end.** fastapi
 > (98k★), scrapy (61k★), django-rest-framework (30k★), pytest (13.8k★),
 > langgraph (31k★), openai-agents-python (26k★), cookiecutter (25k★),
@@ -77,9 +79,11 @@ AI agents write code **10x faster** than humans can review it. Pattern violation
 > wire-clean, scaffold-complete, deterministic. Wire-PASS holds across
 > the entire 300-seed corpus. Receipts in [`HARVEST_LEDGER.md`](HARVEST_LEDGER.md).
 
-- **Catches architectural violations AI agents leave behind.** Deterministic tier-law enforcement — no LLM in the loop, no hallucinations.
-- **Saves 40-60% on LLM tokens.** Structured code = smaller context windows = fewer tokens per turn.
-- **One command: spaghetti -> certified architecture.** Python, JavaScript, TypeScript, **Rust, Go, Swift, Kotlin** — full pipeline (recon, wire, certify, scaffold, evolve) on every language.
+- **Catches architectural violations AI agents leave behind.** Deterministic tier-law enforcement — no LLM in the loop, no hallucinations. Four monadic laws (MCB, AIOM, AHLP, IFWC) shipped as advisory AST scanners; promote to `--fail-on-violations` when ready.
+- **Verifiable token savings.** Every Forge verb auto-appends to a file-backed JSONL ledger at `<project>/.atomadic-forge/lifetime_savings.jsonl`. `forge token-savings` prints the running total and per-tool breakdown. Auditable line-by-line — not a marketing claim.
+- **Surgical capability grafting.** `forge graft --source-file X --symbol Y` extracts a single function or class from any Python source, lands it in the right tier, and auto-wires CLI + MCP. Sibling references resolve automatically. Closes the gap between whole-repo `transmute auto` and one-shot surgical absorption.
+- **Deterministic recipe replay.** `forge replay <recipe>` runs a golden command chain (release hardening, add-cli-command, fix-wire-violation, add-feature, publish-mcp) as subprocesses — zero LLM round-trips per step.
+- **One command: spaghetti -> certified architecture.** Python, JavaScript, TypeScript, **Rust, Go, Swift, Kotlin** — full pipeline (recon, wire, certify, scaffold, evolve) on every language. Recon cache short-circuits the AST walk on unchanged trees via tree fingerprint.
 - **Bring your own LLM.** Built-in presets for OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Groq, Together, Fireworks, xAI, Mistral, Perplexity, Cerebras, Hyperbolic, AAAA-Nexus, and Ollama — plus `forge config provider add` for any custom OpenAI-compatible endpoint.  See [docs/PROVIDERS.md](docs/PROVIDERS.md).
 - **IDE-native.** VS Code extension (`vscode-extension/`), MCP server for Claude Code / Cursor / Cowork / Windsurf, four ready-to-use Claude Code skills.  See [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md).
 
@@ -157,6 +161,17 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `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 |
+| `forge token-savings` | Lifetime token-savings total + per-tool breakdown from `.atomadic-forge/lifetime_savings.jsonl` |
+| `forge replay <recipe>` | Run a golden recipe's validation gate as subprocesses — zero LLM round-trips; flags: `--dry-run`, `--keep-going`, `--list`, `--json` |
+
+### Monadic Law Verbs (advisory; `--fail-on-violations` to enforce)
+
+| Command | What it does |
+|---------|-------------|
+| `forge mcb-check` | Flag unbounded `while` loops and recursion in tier-a1 atoms (Monadic Compute Bounding) |
+| `forge aiom-check` | Flag forbidden I/O imports (`requests`, `urllib`, `socket`, `subprocess`) in tier-a1 (Algebraic I/O Monad) |
+| `forge fingerprint` | SHA-256 of every a1 module's normalised AST — tamper-evident, stable across whitespace (AHLP) |
+| `forge fuzz <module>` | Hypothesis property tests on any a1 callable carrying `__invariants__` (IFWC-lite) |
 
 ### Composition & Multi-Repo
 
@@ -166,6 +181,7 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge emergent scan` | Cross-domain composition discovery |
 | `forge recon-swarm` | Walk N repos, unified report |
 | `forge harvest` | Cross-repo capability gap finder |
+| `forge graft --source-file <f> --symbol <name>` | Extract one function/class from any Python source and land it in the target's correct tier; `--rename` for private→public; auto-wires CLI + MCP |
 
 ### Planning & LLM Loops
 
@@ -176,7 +192,7 @@ 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 |
 
-**59 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**79 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
@@ -195,7 +211,7 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 112 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, 116 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 |
 |------|---------|-------------|
@@ -224,9 +240,9 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 |--------|-------|
 
 | MCP tools | **10 tools · 116 actions** |
-| CLI verbs | **59** |
-| Source files | **243** (~48K LOC) |
-| Tests | **1616 passing** across **120 test files** |
+| CLI verbs | **79** |
+| Source files | **246** (~49K LOC) |
+| Tests | **1625 passing** across **121 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/README.md

@@ -35,6 +35,8 @@ AI agents write code **10x faster** than humans can review it. Pattern violation
 
 **Forge fixes that.**
 
+---
+
 > 🎯 **300+ public OSS Python repositories absorbed end-to-end.** fastapi
 > (98k★), scrapy (61k★), django-rest-framework (30k★), pytest (13.8k★),
 > langgraph (31k★), openai-agents-python (26k★), cookiecutter (25k★),
@@ -45,9 +47,11 @@ AI agents write code **10x faster** than humans can review it. Pattern violation
 > wire-clean, scaffold-complete, deterministic. Wire-PASS holds across
 > the entire 300-seed corpus. Receipts in [`HARVEST_LEDGER.md`](HARVEST_LEDGER.md).
 
-- **Catches architectural violations AI agents leave behind.** Deterministic tier-law enforcement — no LLM in the loop, no hallucinations.
-- **Saves 40-60% on LLM tokens.** Structured code = smaller context windows = fewer tokens per turn.
-- **One command: spaghetti -> certified architecture.** Python, JavaScript, TypeScript, **Rust, Go, Swift, Kotlin** — full pipeline (recon, wire, certify, scaffold, evolve) on every language.
+- **Catches architectural violations AI agents leave behind.** Deterministic tier-law enforcement — no LLM in the loop, no hallucinations. Four monadic laws (MCB, AIOM, AHLP, IFWC) shipped as advisory AST scanners; promote to `--fail-on-violations` when ready.
+- **Verifiable token savings.** Every Forge verb auto-appends to a file-backed JSONL ledger at `<project>/.atomadic-forge/lifetime_savings.jsonl`. `forge token-savings` prints the running total and per-tool breakdown. Auditable line-by-line — not a marketing claim.
+- **Surgical capability grafting.** `forge graft --source-file X --symbol Y` extracts a single function or class from any Python source, lands it in the right tier, and auto-wires CLI + MCP. Sibling references resolve automatically. Closes the gap between whole-repo `transmute auto` and one-shot surgical absorption.
+- **Deterministic recipe replay.** `forge replay <recipe>` runs a golden command chain (release hardening, add-cli-command, fix-wire-violation, add-feature, publish-mcp) as subprocesses — zero LLM round-trips per step.
+- **One command: spaghetti -> certified architecture.** Python, JavaScript, TypeScript, **Rust, Go, Swift, Kotlin** — full pipeline (recon, wire, certify, scaffold, evolve) on every language. Recon cache short-circuits the AST walk on unchanged trees via tree fingerprint.
 - **Bring your own LLM.** Built-in presets for OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Groq, Together, Fireworks, xAI, Mistral, Perplexity, Cerebras, Hyperbolic, AAAA-Nexus, and Ollama — plus `forge config provider add` for any custom OpenAI-compatible endpoint.  See [docs/PROVIDERS.md](docs/PROVIDERS.md).
 - **IDE-native.** VS Code extension (`vscode-extension/`), MCP server for Claude Code / Cursor / Cowork / Windsurf, four ready-to-use Claude Code skills.  See [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md).
 
@@ -125,6 +129,17 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `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 |
+| `forge token-savings` | Lifetime token-savings total + per-tool breakdown from `.atomadic-forge/lifetime_savings.jsonl` |
+| `forge replay <recipe>` | Run a golden recipe's validation gate as subprocesses — zero LLM round-trips; flags: `--dry-run`, `--keep-going`, `--list`, `--json` |
+
+### Monadic Law Verbs (advisory; `--fail-on-violations` to enforce)
+
+| Command | What it does |
+|---------|-------------|
+| `forge mcb-check` | Flag unbounded `while` loops and recursion in tier-a1 atoms (Monadic Compute Bounding) |
+| `forge aiom-check` | Flag forbidden I/O imports (`requests`, `urllib`, `socket`, `subprocess`) in tier-a1 (Algebraic I/O Monad) |
+| `forge fingerprint` | SHA-256 of every a1 module's normalised AST — tamper-evident, stable across whitespace (AHLP) |
+| `forge fuzz <module>` | Hypothesis property tests on any a1 callable carrying `__invariants__` (IFWC-lite) |
 
 ### Composition & Multi-Repo
 
@@ -134,6 +149,7 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge emergent scan` | Cross-domain composition discovery |
 | `forge recon-swarm` | Walk N repos, unified report |
 | `forge harvest` | Cross-repo capability gap finder |
+| `forge graft --source-file <f> --symbol <name>` | Extract one function/class from any Python source and land it in the target's correct tier; `--rename` for private→public; auto-wires CLI + MCP |
 
 ### Planning & LLM Loops
 
@@ -144,7 +160,7 @@ 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 |
 
-**59 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**79 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
@@ -163,7 +179,7 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 112 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, 116 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 |
 |------|---------|-------------|
@@ -192,9 +208,9 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 |--------|-------|
 
 | MCP tools | **10 tools · 116 actions** |
-| CLI verbs | **59** |
-| Source files | **243** (~48K LOC) |
-| Tests | **1616 passing** across **120 test files** |
+| CLI verbs | **79** |
+| Source files | **246** (~49K LOC) |
+| Tests | **1625 passing** across **121 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/docs/02-commands.md

@@ -1371,6 +1371,117 @@ Both append-only, content-addressed, supersession-aware on read.
 
 ---
 
+---
+
+## Cross-repo surgery
+
+### forge graft (v0.76)
+
+Surgical single-symbol cross-repo capability transfer.
+
+```bash
+forge graft \
+  --source-file <path.py> \
+  --symbol <name> \
+  [--rename <new_name>] \
+  [--tier a1_at_functions] \
+  [--target .] \
+  [--package atomadic_forge] \
+  [--overwrite] \
+  [--dry-run] \
+  [--auto-wire | --no-auto-wire] \
+  [--json]
+```
+
+Pipeline: `graft_extract.extract_symbol` (a1) extracts the symbol slice →
+module is rendered with a `SCHEMA_VERSION_GRAFT_<NAME>` marker → written to the
+correct tier directory → wire-violations check → optional auto-wire to surface
+the result as a CLI verb and MCP action. On wire-violation the write is rolled
+back automatically from the pre-write backup.
+
+---
+
+## Token ledger
+
+### forge token-savings (v0.78)
+
+Display the lifetime token-savings ledger. Every enriched Forge verb
+auto-appends an entry to `.atomadic-forge/lifetime_savings.jsonl`.
+
+```bash
+forge token-savings [--project .] [--json]
+```
+
+Returns lifetime total, entry count, first/last timestamps, and a `by_tool`
+breakdown.
+
+---
+
+## Golden-path replay
+
+### forge replay (v0.79)
+
+Deterministic golden-recipe execution. Runs a pre-defined recipe end-to-end and
+logs ~80 tokens saved per successful step to the lifetime ledger.
+
+```bash
+forge replay <recipe-name> [--list] [--dry-run] [--keep-going] \
+             [--project .] [--json]
+```
+
+**Options:**
+- `--list` — list all available recipes
+- `--dry-run` — show steps without executing
+- `--keep-going` — continue past a failing step
+
+**Built-in recipes:** `release_hardening`, `add_cli_command`,
+`fix_wire_violation`, `add_feature`, `publish_mcp`.
+
+---
+
+## Monadic law scanners (v0.80)
+
+Four advisory AST scanners for tier-a1 conformance. All CLI-only; no MCP
+actions yet.
+
+### forge mcb-check
+
+Flag unbounded `while` loops and uncapped recursion in tier-a1 modules.
+
+```bash
+forge mcb-check [--package atomadic_forge] [--fail-on-violations] [--json]
+```
+
+### forge aiom-check
+
+Flag forbidden I/O imports (`requests`, `urllib`, `http`, `socket`, `smtplib`,
+`ftplib`, `telnetlib`, `subprocess`, `multiprocessing`, `httpx`, `aiohttp`) in
+tier-a1 modules.
+
+```bash
+forge aiom-check [--package atomadic_forge] [--fail-on-violations] [--json]
+```
+
+### forge fingerprint
+
+SHA-256 of every a1 module's normalized AST. Stable across whitespace/comment
+changes, sensitive to logic changes.
+
+```bash
+forge fingerprint [--package atomadic_forge] [--json]
+```
+
+### forge fuzz
+
+Hypothesis property fuzzing on a1 callables annotated with `__invariants__`
+(`"args": {param: strategy_name}` and `"post": "lambda r, **kwargs: bool"`).
+
+```bash
+forge fuzz <module> [--max-examples 100] [--project .] [--json]
+```
+
+---
+
 ## Global options
 
 All commands support:

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/docs/05-faq.md

@@ -424,6 +424,38 @@ absorb:
 
 ## Advanced questions
 
+### What is the token-savings ledger and what does `forge token-savings` show?
+
+Every enriched Forge verb (recon, certify, context-pack, replay steps, and
+others) appends an entry to `.atomadic-forge/lifetime_savings.jsonl` recording
+approximately how many tokens the structured output saved compared to raw prose.
+`forge token-savings` reads that file and returns the lifetime total, entry
+count, first/last timestamps, and a per-tool breakdown. The ledger is
+append-only and project-local; commit it if you want the metric to persist
+across clones. Added in v0.78.
+
+```bash
+forge token-savings --project . --json
+```
+
+---
+
+### What does `forge graft` do and when should I use it instead of `forge auto`?
+
+`forge graft` transfers a single named symbol — one function or class — from a
+source file into the current project's tier tree. Use it when you want exactly
+one capability from an external module without absorbing the entire repo. The
+pipeline: extracts the symbol's complete slice, renders a new module with a
+`SCHEMA_VERSION_GRAFT_<NAME>` marker, places it in the correct tier directory,
+runs a wire check, and optionally auto-wires the result as a CLI verb and MCP
+action. If the wire check fails the write is rolled back automatically.
+
+Use `forge auto` (or `forge cherry` + `forge finalize`) when you want to absorb
+multiple symbols or an entire repo. Use `forge graft` for surgical one-symbol
+transfers. Added in v0.76.
+
+---
+
 ### Can I customize the tier classification?
 
 Not yet, but the scout report logs the rationale per symbol. You can override manually by moving files after absorption.

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/docs/COMMANDS.md

@@ -1,11 +1,38 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.78.0
+All verbs available in the `forge` CLI as of 0.81.0
 
 > For the structured per-verb reference (with options, examples, and
 > output samples), see [02-commands.md](02-commands.md). This page is
 > the legacy summary kept for backward compatibility.
 
+## Cross-repo surgery
+
+### `forge graft --source-file <path.py> --symbol <name>` (v0.76)
+
+Surgical single-symbol cross-repo capability transfer. Extracts one symbol's
+complete slice (using `graft_extract.extract_symbol` at a1), renders it into a
+tier-correct module stamped with a `SCHEMA_VERSION_GRAFT_<NAME>` marker, writes
+it to the target package, runs a wire-violations check, and optionally
+auto-wires the result into the CLI and MCP surfaces. Rolls back to a backup on
+wire failure.
+
+```bash
+forge graft \
+  --source-file path/to/source.py \
+  --symbol my_function \
+  [--rename new_name] \
+  [--tier a1_at_functions] \
+  [--target .] \
+  [--package atomadic_forge] \
+  [--overwrite] \
+  [--dry-run] \
+  [--auto-wire | --no-auto-wire] \
+  [--json]
+```
+
+---
+
 ## Pipeline / absorption
 
 ### `forge auto SOURCE OUTPUT`
@@ -212,6 +239,75 @@ The sidecar drift band is populated today (Lane D W11):
 Reserved (Lane D W20): `F0105` `compose_with` mismatch, `F0107`
 `proves:` clause unverified.
 
+## Token ledger
+
+### `forge token-savings [--project .] [--json]` (v0.78)
+
+Displays the lifetime token-savings ledger accumulated across all enriched Forge
+verbs. Every verb that produces enriched output auto-appends an entry to
+`.atomadic-forge/lifetime_savings.jsonl`. The command reads that file and
+returns the lifetime total, entry count, first/last timestamps, and a
+`by_tool` breakdown.
+
+```bash
+forge token-savings --project . --json
+```
+
+---
+
+## Golden-path replay
+
+### `forge replay <recipe-name> [OPTIONS]` (v0.79)
+
+Deterministic golden-recipe execution. Runs a named recipe step-by-step and
+logs approximately 80 tokens saved per successful step to the lifetime ledger.
+
+```bash
+forge replay release_hardening [--list] [--dry-run] [--keep-going] \
+             [--project .] [--json]
+```
+
+**Options:**
+- `--list` — list all available recipes instead of running one
+- `--dry-run` — show steps without executing
+- `--keep-going` — continue past a failing step
+
+**Built-in recipes:** `release_hardening`, `add_cli_command`,
+`fix_wire_violation`, `add_feature`, `publish_mcp`.
+
+---
+
+## Monadic law scanners (v0.80)
+
+Four advisory AST-scanner verbs. All are CLI-only; MCP actions are not yet
+exposed.
+
+### `forge mcb-check [--package atomadic_forge] [--fail-on-violations] [--json]`
+
+Flags unbounded `while` loops and uncapped recursion inside tier-a1 modules.
+Advisory by default; exits non-zero with `--fail-on-violations`.
+
+### `forge aiom-check [--package atomadic_forge] [--fail-on-violations] [--json]`
+
+Flags forbidden I/O imports inside tier-a1 modules. Blocked import families:
+`requests`, `urllib`, `http`, `socket`, `smtplib`, `ftplib`, `telnetlib`,
+`subprocess`, `multiprocessing`, `httpx`, `aiohttp`.
+
+### `forge fingerprint [--package atomadic_forge] [--json]`
+
+SHA-256 fingerprint of every a1 module's normalized AST. Stable across
+whitespace and comment changes; sensitive to logic changes. Use to detect
+silent behavioral drift.
+
+### `forge fuzz <module> [--max-examples 100] [--project .] [--json]`
+
+Hypothesis-driven property fuzzing on any a1 callable that carries an
+`__invariants__` dict with `"args": {param: strategy_name}` and
+`"post": "lambda r, **kwargs: bool"` keys. Runs up to `--max-examples`
+generated cases and reports counterexamples.
+
+---
+
 ## Agent integration (MCP)
 
 ### `forge mcp serve`

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/docs/MCP_TOOLS.md

@@ -98,7 +98,7 @@ No LLM is invoked — all analysis is deterministic.
 | `dead_code` | Identify unreachable or unused symbols. |
 | `maintainability` | Maintainability index per file/module. |
 | `concept_bridge` | Cross-domain concept linkage detection. |
-| `auto_wire` | Deterministically wire generated surface stubs. |
+| `auto_wire` | Deterministically wire generated surface stubs. CLI stubs produced by auto-wire coerce `list[float]`/`list[int]`/`list[str]` arguments from comma-separated strings (v0.81). |
 | `doc_update` | Regenerate public docs from metrics. |
 | `doc_drift` | Detect public-doc metric drift. |
 
@@ -239,5 +239,24 @@ All tools except `nexus` and `welcome` use `action=<name>` for dispatch:
 
 ---
 
+---
+
+## CLI-only verbs (no MCP action yet)
+
+The following verbs added in v0.76–v0.80 are available on the CLI but do not
+yet have corresponding MCP actions:
+
+| CLI verb | Version | What it does |
+|----------|---------|-------------|
+| `forge graft` | v0.76 | Single-symbol cross-repo capability transfer |
+| `forge token-savings` | v0.78 | Display lifetime token-savings ledger |
+| `forge replay` | v0.79 | Deterministic golden-recipe execution |
+| `forge mcb-check` | v0.80 | Flag unbounded loops/recursion in tier-a1 |
+| `forge aiom-check` | v0.80 | Flag forbidden I/O imports in tier-a1 |
+| `forge fingerprint` | v0.80 | SHA-256 normalized-AST fingerprint per a1 module |
+| `forge fuzz` | v0.80 | Hypothesis property fuzzing on `__invariants__`-annotated a1 callables |
+
+---
+
 *Numbers sourced from `forge_metrics.json` (canonical, regenerated on every push).*
 *Full CLI reference: [docs/02-commands.md](02-commands.md)*

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.81.0"
+version = "0.83.0"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

atomadic_forge-0.83.0/src/atomadic_forge/a1_at_functions/closest_match.py

@@ -0,0 +1,24 @@
+"""Grafted from string_distance.py (lines 30–45) by `forge graft`."""
+from __future__ import annotations
+
+from .levenshtein_distance import levenshtein_distance
+
+SCHEMA_VERSION_GRAFT_CLOSEST_MATCH = "atomadic-forge.graft.closest_match/v1"
+
+def closest_match(query: str, candidates: list[str]) -> str:
+    """Return the candidate string with the smallest Levenshtein distance.
+
+    Empty candidates list returns the query itself. Ties resolve to
+    the first candidate by input order (deterministic).
+    """
+    if not candidates:
+        return query
+    best = candidates[0]
+    best_d = levenshtein_distance(query, best)
+    for cand in candidates[1:]:
+        d = levenshtein_distance(query, cand)
+        if d < best_d:
+            best = cand
+            best_d = d
+    return best
+

{atomadic_forge-0.81.0 → atomadic_forge-0.83.0}/src/atomadic_forge/a1_at_functions/graft_extract.py

@@ -27,6 +27,10 @@ class GraftExtract:
     * ``imports_needed`` — the set of bare module names the symbol's body
       references. Caller resolves these against the source file's import
       table to build the new module's import block.
+    * ``sibling_refs`` (v0.81.1) — names referenced by the symbol's body
+      that are top-level defs in the SAME donor file but live outside
+      this slice. The caller emits relative imports (``from .<name>
+      import <name>``) for them so multi-symbol grafts compose cleanly.
     * ``start_line`` / ``end_line`` — 1-based line numbers in the source
       file (for diagnostics and lineage).
     """
@@ -36,6 +40,7 @@ class GraftExtract:
     imports_needed: frozenset[str]
     start_line: int
     end_line: int
+    sibling_refs: frozenset[str] = frozenset()
 
 
 def _walk_imports_used(node: ast.AST) -> set[str]:
@@ -144,6 +149,17 @@ def extract_symbol(source_file: Path, symbol_name: str) -> GraftExtract:
     table = _import_table(tree)
     imports_needed = frozenset(name for name in used if name in table)
 
+    # v0.81.1 — sibling-reference detection. Names the body references
+    # that are top-level defs in the SAME donor file but NOT in this
+    # slice. The renderer uses these to emit `from .<name> import <name>`
+    # relative imports so multi-symbol grafts compose without manual fix.
+    sibling_top_defs: set[str] = {
+        n.name for n in tree.body
+        if isinstance(n, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
+        and n.name != symbol_name
+    }
+    sibling_refs = frozenset(used & sibling_top_defs)
+
     if isinstance(target, ast.AsyncFunctionDef):
         kind = "async_function"
     elif isinstance(target, ast.FunctionDef):
@@ -158,6 +174,7 @@ def extract_symbol(source_file: Path, symbol_name: str) -> GraftExtract:
         imports_needed=imports_needed,
         start_line=start,
         end_line=end,
+        sibling_refs=sibling_refs,
     )
 
 
@@ -205,6 +222,14 @@ def render_grafted_module(
     if needed_imports:
         parts.extend(needed_imports)
         parts.append("")
+    # v0.81.1 — emit relative imports for sibling top-level defs the
+    # body references. Caller is responsible for grafting those
+    # siblings to the same destination tier (default lands them
+    # alongside this module so the relative import resolves).
+    if extract.sibling_refs:
+        for sib in sorted(extract.sibling_refs):
+            parts.append(f"from .{sib} import {sib}")
+        parts.append("")
     # Surface-gap-discoverable: emit a SCHEMA_VERSION_GRAFT_<NAME>
     # constant so the existing entry-point walker recognizes the grafted
     # symbol as a wireable a1 function. Without this, auto-wire skips