atomadic-forge 0.19.0__tar.gz → 0.50.0__tar.gz

atomadic_forge-0.50.0/.github/workflows/metrics-auto-regen.yml

@@ -0,0 +1,96 @@
+name: Metrics Auto-Regenerate
+
+# Single-source-of-truth pipeline. On every push to main, recomputes the
+# canonical forge_metrics.json artifact and pushes a follow-up commit if
+# the artifact drifted from what the source tree should produce.
+#
+# Together with metrics-drift.yml (CI gate on PRs), this means:
+#   - PRs are blocked on stale metrics.
+#   - Direct pushes to main self-heal automatically.
+#   - Public surfaces (atomadic.tech, shields.io endpoints proxied by
+#     the worker) always read live numbers from the same JSON.
+#
+# Lean theorem count requires the IP-protected mhed-codex repo. The
+# FORGE_MHED_CODEX_REPO secret (org-level) provides a deploy-key URL;
+# without it the lean_theorems block is preserved from the prior commit
+# (see surgical merge step below) so this workflow never destroys real
+# numbers when running without the IP repo attached.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/atomadic_forge/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "src/atomadic_forge/a1_at_functions/forge_metrics.py"
+      - "src/atomadic_forge/a3_og_features/forge_metrics_feature.py"
+
+permissions:
+  contents: write
+
+jobs:
+  regen:
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, 'chore(metrics): auto-regenerate') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package
+        run: pip install -e . --quiet
+      - name: Run pytest to count live passing
+        id: pytest
+        run: |
+          set +e
+          out=$(python -m pytest tests/ -q --no-header 2>&1 | tail -3)
+          echo "$out"
+          passed=$(echo "$out" | grep -oE '[0-9]+ passed' | head -1 | grep -oE '[0-9]+')
+          echo "passed=${passed:-0}" >> "$GITHUB_OUTPUT"
+      - name: Optionally clone IP-protected mhed-codex (preserves lean count)
+        if: ${{ env.MHED_CODEX_DEPLOY_KEY != '' }}
+        env:
+          MHED_CODEX_DEPLOY_KEY: ${{ secrets.MHED_CODEX_DEPLOY_KEY }}
+        run: |
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
+          echo "$MHED_CODEX_DEPLOY_KEY" > ~/.ssh/mhed_key && chmod 600 ~/.ssh/mhed_key
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/mhed_key -o StrictHostKeyChecking=no" \
+            git clone --depth 1 git@github.com:atomadictech/mhed-codex.git /tmp/mhed-codex
+          echo "FORGE_MHED_CODEX=/tmp/mhed-codex" >> "$GITHUB_ENV"
+      - name: Regenerate forge_metrics.json
+        run: |
+          # Save the previous lean_theorems block so we can preserve it
+          # when no mhed-codex is attached (avoid zeroing the public
+          # number on a routine source-only push).
+          python -c "import json; d=json.load(open('forge_metrics.json')); print(json.dumps(d.get('lean_theorems', {})))" > /tmp/prev_lean.json
+          forge metrics --apply --tests-passing ${{ steps.pytest.outputs.passed }}
+          # If no mhed-codex was attached this run, restore prior lean block.
+          if [ -z "${FORGE_MHED_CODEX:-}" ]; then
+            python <<'PY'
+          import json, pathlib
+          p = pathlib.Path("forge_metrics.json")
+          d = json.loads(p.read_text())
+          prev = json.loads(pathlib.Path("/tmp/prev_lean.json").read_text())
+          # Only restore if the freshly-computed block reports found=False
+          # (i.e. mhed-codex unavailable) AND the prior had a real count.
+          if not d.get("lean_theorems", {}).get("found") and prev.get("count"):
+              d["lean_theorems"] = prev
+              p.write_text(json.dumps(d, indent=2, sort_keys=True) + "\n")
+          PY
+          fi
+      - 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"
+            exit 0
+          fi
+          git add forge_metrics.json
+          git commit -m "chore(metrics): auto-regenerate forge_metrics.json [skip ci]"
+          git push origin main

atomadic_forge-0.50.0/.github/workflows/metrics-drift.yml

@@ -0,0 +1,61 @@
+name: Metrics Drift Gate
+
+# CI gate that keeps forge_metrics.json in sync with the live forge surface.
+# Any PR that changes TOOLS, CLI registry, source/test counts, or
+# pyproject.toml WITHOUT regenerating forge_metrics.json fails this check.
+#
+# Lean theorem count is recomputed only when the FORGE_MHED_CODEX repo is
+# accessible (CI env var). When not set, the lean_theorems block is
+# preserved from the in-tree forge_metrics.json so PRs that don't touch
+# mhed-codex don't get blocked here.
+#
+# Fix when this fails:  forge metrics --apply && git add forge_metrics.json
+
+on:
+  pull_request:
+    paths:
+      - "src/atomadic_forge/a0_qk_constants/schema_version_registry.py"
+      - "src/atomadic_forge/a1_at_functions/mcp_protocol.py"
+      - "src/atomadic_forge/a1_at_functions/forge_metrics.py"
+      - "src/atomadic_forge/a3_og_features/forge_metrics_feature.py"
+      - "src/atomadic_forge/a4_sy_orchestration/cli.py"
+      - "src/atomadic_forge/commands/**"
+      - "pyproject.toml"
+      - "forge_metrics.json"
+  push:
+    branches: [main]
+
+jobs:
+  metrics-drift:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package (editable)
+        run: pip install -e . --quiet
+      - name: Compute live metrics + diff vs. checked-in artifact
+        run: |
+          set -euo pipefail
+          # Save committed copy.
+          cp forge_metrics.json /tmp/forge_metrics.committed.json
+          # Recompute (Lean count zero in CI unless FORGE_MHED_CODEX is wired).
+          forge metrics --apply
+          # If the only delta is the timestamp, that's expected — strip it
+          # before diffing so we only fail on substantive drift.
+          jq 'del(.generated_at_utc)' /tmp/forge_metrics.committed.json > /tmp/a.json
+          jq 'del(.generated_at_utc)' forge_metrics.json > /tmp/b.json
+          # If FORGE_MHED_CODEX is not set, also ignore the lean_theorems
+          # block (will be 0 in CI but the committed artifact has the real
+          # count from the IP repo).
+          if [ -z "${FORGE_MHED_CODEX:-}" ]; then
+            jq 'del(.lean_theorems)' /tmp/a.json > /tmp/a2.json && mv /tmp/a2.json /tmp/a.json
+            jq 'del(.lean_theorems)' /tmp/b.json > /tmp/b2.json && mv /tmp/b2.json /tmp/b.json
+          fi
+          if ! diff -u /tmp/a.json /tmp/b.json; then
+            echo "::error::forge_metrics.json is stale. Run 'forge metrics --apply' and commit the result."
+            exit 1
+          fi
+          echo "metrics drift check: OK"

atomadic_forge-0.50.0/.github/workflows/publish-on-tag.yml

@@ -0,0 +1,104 @@
+name: Publish on tag
+
+# v0.50.0 — single tag → full publish chain.
+#
+# Pushing a v* tag fires this workflow, which:
+#   1. Verifies forge_metrics.json is current at the tag (no stale numbers
+#      shipping to PyPI / atomadic.tech / shields.io).
+#   2. Creates a GitHub Release using the matching CHANGELOG section.
+#      The GH-Release event triggers release.yml which builds + publishes
+#      to PyPI.
+#   3. Fires a `repository_dispatch` to atomadic-forge-cloudflare-workers
+#      so the MCP worker redeploys with the same version. Public
+#      surfaces (badges, metrics.json proxy, MCP endpoint) are then in
+#      lockstep with the PyPI release.
+#
+# Required secrets:
+#   GH_TOKEN — automatic (github.token)
+#   WORKER_DEPLOY_PAT — PAT with `repo` scope on the worker repo;
+#       grants permission to fire repository_dispatch. If unset, the
+#       cross-repo dispatch is skipped (worker can be redeployed
+#       manually via its own workflow_dispatch).
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish chain (metrics → GH Release → worker dispatch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: pip install -e . --quiet
+
+      - name: Verify forge_metrics.json is current at this tag
+        run: |
+          set -euo pipefail
+          # Save the in-tree artifact, recompute, diff (ignoring
+          # generated_at_utc and lean_theorems — Lean count requires
+          # the IP-protected mhed-codex repo, not present in CI).
+          cp forge_metrics.json /tmp/forge_metrics.committed.json
+          # Use the most recent passing test count from the suite.
+          set +e
+          ptout=$(python -m pytest tests/ -q --no-header 2>&1 | tail -3)
+          set -e
+          passed=$(echo "$ptout" | grep -oE '[0-9]+ passed' | head -1 | grep -oE '[0-9]+')
+          forge metrics --apply --tests-passing "${passed:-0}"
+          jq 'del(.generated_at_utc) | del(.lean_theorems) | del(.tests_passing)' \
+            /tmp/forge_metrics.committed.json > /tmp/a.json
+          jq 'del(.generated_at_utc) | del(.lean_theorems) | del(.tests_passing)' \
+            forge_metrics.json > /tmp/b.json
+          if ! diff -u /tmp/a.json /tmp/b.json; then
+            echo "::error::forge_metrics.json is stale at tag ${GITHUB_REF_NAME}. Re-run \`forge metrics --apply\` and re-tag."
+            exit 1
+          fi
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          changelog=$(sed -n "/^## .*${version}/,/^## /{/^## .*${version}/d;/^## /d;p}" CHANGELOG.md | head -100)
+          if [ -z "$changelog" ]; then
+            changelog="Release v${version}"
+          fi
+          echo "$changelog" > /tmp/release_notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "Atomadic Forge ${{ github.ref_name }}" \
+            --notes-file /tmp/release_notes.md
+
+      - name: Dispatch worker redeploy
+        if: ${{ secrets.WORKER_DEPLOY_PAT != '' }}
+        env:
+          PAT: ${{ secrets.WORKER_DEPLOY_PAT }}
+        run: |
+          curl -fsS -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${PAT}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/atomadictech/atomadic-forge-cloudflare-workers/dispatches \
+            -d "{\"event_type\":\"forge-released\",\"client_payload\":{\"version\":\"${{ steps.version.outputs.version }}\"}}"
+          echo "dispatched forge-released v${{ steps.version.outputs.version }} → worker repo"

atomadic_forge-0.50.0/.github/workflows/uptime.yml

@@ -0,0 +1,72 @@
+name: Uptime monitor
+
+# Runs every 30 minutes. Pings all Atomadic services and opens an
+# issue if any are down. Free uptime monitoring via GitHub Actions.
+
+on:
+  schedule:
+    - cron: '*/30 * * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check:
+    name: Health check
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - name: Ping all services
+        id: ping
+        run: |
+          failed=""
+          for entry in \
+            "forge.atomadic.tech|https://forge.atomadic.tech" \
+            "forge-mcp|https://forge.atomadic.tech/mcp" \
+            "chat.atomadic.tech|https://chat.atomadic.tech" \
+            "forge-auth|https://forge-auth.atomadic.tech" \
+          ; do
+            name="${entry%%|*}"
+            url="${entry##*|}"
+            status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$url" 2>/dev/null || echo "000")
+            # 200, 401, 405 are all "alive" responses for various endpoints
+            if [[ "$status" =~ ^(200|301|302|401|403|405)$ ]]; then
+              echo "OK  $status  $name"
+            else
+              echo "ERR $status  $name"
+              failed="$failed $name($status)"
+            fi
+          done
+
+          if [ -n "$failed" ]; then
+            echo "failed=$failed" >> "$GITHUB_OUTPUT"
+            echo "has_failure=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_failure=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open issue if services are down
+        if: steps.ping.outputs.has_failure == 'true'
+        uses: actions/checkout@v6
+
+      - name: Create or update issue
+        if: steps.ping.outputs.has_failure == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          title="Uptime alert: services down"
+          body="The following services are unreachable: ${{ steps.ping.outputs.failed }}
+
+          Detected at $(date -u +'%Y-%m-%d %H:%M UTC')
+
+          Run \`make uptime\` locally to verify."
+
+          # Check if an open uptime issue already exists
+          existing=$(gh issue list --label uptime --state open --json number -q '.[0].number' 2>/dev/null || true)
+          if [ -n "$existing" ]; then
+            gh issue comment "$existing" --body "$body"
+          else
+            gh issue create --title "$title" --body "$body" --label uptime
+          fi

{atomadic_forge-0.19.0 → atomadic_forge-0.50.0}/CHANGELOG.md

@@ -2,6 +2,294 @@
 
 ## Unreleased
 
+## v0.50.0 — 2026-05-07 — one tag publishes everywhere
+
+### feat: full single-tag publish chain (PyPI + worker + badges in lockstep)
+
+Pushing a single `vX.Y.Z` tag now drives the whole pipeline:
+
+1. `publish-on-tag.yml` verifies `forge_metrics.json` is current at the
+   tag (fail-loud if stale — no shipping wrong numbers to public surfaces).
+2. GitHub Release is created from the matching CHANGELOG section.
+3. `release.yml` builds + publishes to PyPI.
+4. `repository_dispatch` fires `forge-released` to the worker repo,
+   which redeploys via `wrangler deploy` with the matching version env.
+
+Public surfaces (atomadic.tech, shields.io badges, MCP endpoint, doctor
+response, package version banner) all reflect the same tag within ~30s.
+
+### feat: shields.io endpoint badges
+
+The Cloudflare Worker now serves shields.io v1 endpoint badges:
+
+```
+https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/<metric>
+```
+
+Available metrics: `mcp_tools`, `mcp_actions`, `cli_verbs`, `tests_passing`,
+`test_files`, `test_functions`, `source_files`, `source_lines`,
+`monadic_tiers`, `lean_theorems`, `package_version`.
+
+Each badge reads `forge_metrics.json` (5-min edge cache). Drop one in any
+README, docs site, or status page — the number updates without anyone
+editing the file.
+
+README header gained a row of live badges: tools, actions, CLI verbs,
+tests passing, source files, Lean4 theorem count. Static "100/100
+certify" badge retired in favor of dynamic numbers.
+
+### feat: auto-regen on every push to main
+
+`metrics-auto-regen.yml`: any push to `main` that touches source, tests,
+or `pyproject.toml` triggers a regeneration. If the artifact drifted, a
+follow-up `chore(metrics): auto-regenerate [skip ci]` commit is pushed
+back to main. Stale numbers self-heal — no human intervention.
+
+When the `MHED_CODEX_DEPLOY_KEY` org secret is configured, the
+auto-regen also clones the IP-protected mhed-codex over deploy-key
+SSH and refreshes the Lean theorem count. Without the secret, the prior
+lean count is preserved (never zeroed by a routine push).
+
+### chore: corrected misnamed metric units
+
+Earlier responses cited "1,493 passing" alongside "test_files: 96" and
+"124/124 passed" — three different units (full-suite passes, file count,
+targeted-subset passes). The artifact now carries all three explicitly:
+`test_files`, `test_functions`, `tests_passing`.
+
+## v0.49.0 — 2026-05-07 — single source of truth: `forge_metrics.json`
+
+### feat: canonical metrics artifact for every public surface
+
+Every public number Forge claims about itself — MCP tool count, action
+count, CLI verb count, source/test files, lines of code, and the count
+of formally-verified Lean4 theorems in the IP-protected mhed-codex
+moat — now lives in one canonical artifact: `forge_metrics.json` at the
+repo root, regenerated on every push by `forge metrics --apply`.
+
+Public surfaces (README, CHANGELOG badges, the welcome handshake, the
+Cloudflare Worker, shields.io endpoints, atomadic.tech site) read from
+this file. CI gate (`metrics-drift.yml`) fails any PR that lets the
+artifact drift out of sync with the live forge surface.
+
+**Live numbers (this commit):**
+- 10 MCP tools · 64 actions
+- 71 CLI verbs
+- 211 source files · ~40,110 LOC
+- 96 test files
+- **886 Lean4 theorems across 38 files** (mhed-codex moat)
+- monadic tiers = 5
+
+### feat(cli/mcp): `forge metrics` verb — print or write the artifact
+
+```
+forge metrics                  # print live metrics summary
+forge metrics --apply          # rewrite forge_metrics.json
+forge metrics --json           # machine-readable JSON to stdout
+forge metrics --self-cert      # also embed certify score (slower)
+```
+
+The verb composes a pure tier-a1 aggregator (`forge_metrics.py`) with
+the live MCP TOOLS dict and CLI registry. Source paths from the
+IP-protected mhed-codex repo are NEVER written into the public
+artifact — only aggregate counts. Path resolution is via the
+`FORGE_MHED_CODEX` env var; gitignore protects `mhed-codex/` from
+ever being checked in.
+
+### chore: corrected stale README numbers
+
+The "By the Numbers" table previously cited Lean4=624 (stale by 262)
+and source files=193 (stale by 18). Now derived live from
+`forge_metrics.json` and verified against the IP repo.
+
+## v0.48.0 — 2026-05-07 — flagship `transmute` + `loop` split out of plan (8→10 tools)
+
+### refactor(mcp): surface the flagship pipeline; reduce plan overload
+
+The v0.46.0 consolidation buried the flagship `auto` pipeline inside
+`plan(action='auto')` — semantically wrong (`plan` means *planning*, not
+*executing the absorption pipeline*) and bad for discoverability (agents
+reading `tools/list` couldn't see "auto" at all).
+
+**v0.48.0 splits two semantic clusters back out:**
+
+- **`transmute` (3 actions)** — the spaghetti→certified flagship:
+  `auto` (single-shot scout→cherry→assimilate→wire→certify) ·
+  `cherry` (produce cherry.json manifest) ·
+  `finalize` (materialize a cherry.json into a package).
+  This is the headline Forge capability and now appears at the top level
+  of `tools/list` again.
+
+- **`loop` (4 actions)** — LLM-driven iteration sessions:
+  `iterate` · `resume` · `evolve` · `evolve_step`.
+  Distinct from `plan` because these REQUIRE an external LLM client —
+  Forge has no embedded LLM. Splitting clarifies that contract.
+
+**`plan` (16 → 9 actions)** — now cleanly scoped to "orient + dev utilities":
+context, compose, policy, recipes, generate, apply, locate, commit, scaffold.
+
+**Backward compat:** every legacy name still works.
+`LEGACY_ENDPOINT_MAP` updated: `auto/cherry/finalize/transmute → transmute`,
+`iterate/evolve/loop → loop`. Schema bumps: `transmute → /v2`, `loop → /v2`,
+`plan → /v6` (action enum changed). Total tool count: **10**.
+
+### chore: schema registry & surface map updated
+
+`transmute` → `/v2`, `loop` → `/v2` restored in registry. `plan` schema bumped
+implicitly via action enum change.
+
+## v0.47.0 — 2026-05-07 — `create` exposed as MCP tool (7→8 tools)
+
+### feat(mcp): forge create now callable over MCP
+
+`create` was previously CLI-only. Exposes `create_from_intent` (intent + seed_repos → pip package)
+as a standalone MCP tool — runs the full Phase 1 pipeline (emergent_swarm cross-repo composition
+discovery → materialize top-N candidates → optional certify). Returns the create receipt with
+scan_summary, materialize report, and scan_report_path for re-runs without re-scanning.
+
+Schema: `atomadic-forge.create/v1`. Total tool count: **8**.
+
+## v0.46.0 — 2026-05-07 — MCP Surface Redesign: 66→7 tools, 64 actions
+
+### feat(mcp): complete tool surface consolidation with action-dispatch architecture
+
+Reduced the MCP tool count from **66 to 7** by consolidating related operations
+under action-dispatch. Each of the 66 original tool names redirects automatically
+via `LEGACY_ENDPOINT_MAP` — zero callers broken, zero migrations required.
+
+**Measured token savings: ~8,630 tokens per `tools/list` call (−51%)** vs the prior
+66-tool surface (`tools/list` payload dropped from 67.7 KB → 33.2 KB, measured
+on v0.23.0 vs v0.47.0 by dispatching the actual JSON-RPC call). Per-session
+savings depend on how many `tools/list` calls a client issues — typically
+~8.6K–26K tokens. The earlier draft of these notes claimed ~250K tokens/session
+and ~99 KB → ~25 KB; both were estimates that didn't survive measurement.
+Response-size caps across high-volume tools (smell_scan, wisdom_list, etc.)
+saved an additional ~189 KB per heavy round-trip — those numbers were
+verified directly and stand.
+
+**Final 7-tool surface (64 actions):**
+
+| Tool | Actions | Scope |
+|------|---------|-------|
+| `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, safety net |
+| `explore` | 9 | Codebase analysis & discovery: `recon` · `explain` · `call_graph` · `smell_scan` · `lineage` · `harvest` · `synergy` · `scan` · `swarm` |
+| `audit` | 14 | Quality gates & change safety: `certify` · `wire` · `enforce` · `validate` · `guard` · `composite` · `gate` · `health` · `check` · `score` · `tests` · `cna` · `rollback` · `diff` |
+| `plan` | 16 | Orient + plan + execute: `context` · `compose` · `policy` · `recipes` · `generate` · `apply` · `locate` · `commit` · `iterate` · `resume` · `evolve` · `evolve_step` · `auto` · `cherry` · `finalize` · `scaffold` |
+| `hive` | 13 | Multi-agent coordination: `register` · `list` · `deactivate` · `observe` · `propose` · `vote` · `needs_vote` · `result` · `recap` · `handoff_create` · `handoff_list` · `enhance_propose` · `enhance_list` |
+| `wisdom` | 5 | Institutional memory DB: `record` · `query` · `list` · `recall` · `promote` |
+| `nexus` | 7 | AAAA-Nexus auth primitives (via `op=`): `identity_verify` · `federation_mint` · `authorize_action` · `sys_trust_gate` · `contract_verify` · `lineage_record` · `ratchet_register` |
+
+Each tool uses `action=` dispatch; `nexus` uses `op=` to avoid collision with
+`authorize_action`'s pass-through `action` parameter.
+
+### perf: response-size caps across high-volume tools
+
+Default payload sizes reduced at the source so agents never receive multi-KB
+responses they didn't ask for:
+
+| Tool | Before | After | Mechanism |
+|------|--------|-------|-----------|
+| `emergent_scan` | 32 KB | 7.5 KB | `top_n` 25→10, optional `include_chains` |
+| `synergy_scan` | 14 KB | 5.7 KB | `top_n` 25→10, optional `include_details` |
+| `smell_scan` | 61 KB | 12 KB | `top_n_findings=20` cap, always emits `*_count` |
+| `wisdom_list` | 71 KB | ~5 KB | `limit=20` default, `limit=0` for full dump |
+| `wisdom_promote` | 46 KB | 5 KB | `include_bodies=false` default |
+
+Full detail always recoverable via the respective opt-in params.
+
+## v0.23.0 — 2026-05-07 — wisdom_promote body trim (46 KB → 5 KB)
+
+### perf(wisdom_promote): strip draft_markdown bodies from default response
+
+`wisdom_promote` response was 46 KB (3 drafts × full markdown). Default now
+returns metadata only — `body_chars`, `body_omitted: true` — at ~5 KB.
+
+- `include_bodies=true` restores full markdown in the response.
+- `write=true` also implicitly includes bodies (you're persisting them anyway).
+- Added `hint` field explaining the param when bodies are omitted.
+
+Response reduction: 46,352 → 4,759 bytes (90%).
+
+## v0.22.0 — 2026-05-07 — plan maintenance hints, CLI map completions, description fixes
+
+### feat(plan): inject maintenance_hints when repo already passes at 100/100
+
+When `certify=100` and `wire=PASS`, the `plan` tool now emits `maintenance_hints`
+— top-5 CC complexity hotspots from `smell_scan` — so agents always have an
+actionable next step even on a clean repo. Adds `maintenance_hint_count` field.
+No change to existing fields; no impact on repos with real actions to take.
+
+### fix(CLI map): complete _CLI_FALLBACKS for 15 previously missing tools
+
+`trust_gate_response` was incorrectly listed as "MCP-only" — the CLI is
+`forge trust-gate`. Added correct CLI equivalents (or intentional MCP-only
+annotations) for: `guard_install`, `tool_factory`, `iterate_start`,
+`iterate_continue`, `evolve_start`, `evolve_step`, `lineage`, `harvest`,
+and all 9 hive subtools.
+
+### fix(lineage): add CLI equivalent to description
+
+Description now notes `forge surface list/show/log` as the CLI counterpart,
+fixing the gap where agents had no way to discover the CLI equivalent.
+
+## v0.21.0 — 2026-05-07 — wisdom_list limit, commit_compose prefix fix
+
+### perf(wisdom_list): cap default response at 20 entries (71 KB → ~5 KB)
+
+New `limit` parameter (default 20) prevents `wisdom_list` from dumping the
+entire wisdom DB in one call. Always emits:
+
+- `total_count` — full entry count regardless of cap.
+- `returned_count` — entries actually returned.
+- `truncated: true` + `hint` string when the DB exceeds the limit.
+
+Pass `limit=0` to retrieve all entries. Mirrors the `top_n_findings` pattern
+added to `smell_scan` in v0.20.0.
+
+### fix(commit_compose): strip duplicate conventional-commit prefix from intent
+
+`commit_compose` now strips any leading `TYPE:` or `TYPE(scope):` prefix from
+`intent` before prepending the `commit_type` label. Prevents double-prefix
+subjects like `fix: fix(scope): add param` when callers pass a
+conventionally-formatted intent string.
+
+## v0.20.0 — 2026-05-07 — context_pack synthesis, synergy_scan fix, smell_scan token reduction
+
+### feat(context_pack): embed policy + workflow_recipe — replaces two extra tool calls
+
+`context_pack` now returns two new fields on every call:
+
+- **`policy`** — the full `[tool.forge.agent]` policy dict (`protected_files`,
+  `max_files_per_patch`, `require_human_review_for`). Agents no longer need a
+  separate `load_policy` call on first connect.
+- **`workflow_recipe`** — when `intent` is provided, `compose_tools` is run
+  automatically and the matched recipe (step-by-step tool sequence) is embedded.
+  Agents that pass `intent` get both grounding and a workflow plan in one call.
+
+`load_policy` and `compose_tools` remain available as standalone tools for
+targeted use. Their descriptions updated to note the context_pack embedding.
+
+Extracted `_build_policy` and `_build_workflow_recipe` helpers, keeping
+`emit_context_pack` CC below the 10-threshold flagged by smell_scan.
+
+### fix(synergy_scan): MCP returned 0 candidates vs 20 from CLI
+
+`_bound_synergy_scan` in `mcp_server.py` was passing `project_root` as
+`src_root` to `SynergyScan`. The scanner expects the `src/` directory, not the
+repo root. Fixed: now uses `root/"src"` when that directory exists, falling back
+to `root`. Result: 0 → 20 synergy candidates in MCP calls (parity with CLI).
+
+### perf(smell_scan): response slimmed from 61.6 KB to ~12 KB
+
+New `top_n_findings` parameter (default 20) caps the findings arrays returned
+while always emitting `*_count` summary fields so agents see the full totals:
+
+- `complexity_findings_count`, `long_function_findings_count`,
+  `duplication_findings_count` — always present regardless of cap.
+- Returned findings are sorted by worst score (highest CC / longest LOC).
+- `findings_capped_at` field indicates the cap in effect.
+- `top_n_findings: 0` disables the cap entirely for full reports.
+
 ## v0.19.0 — 2026-05-07 — MCP/CLI parity sweep: 8 tool fixes, call_graph overhaul, smell improvements
 
 ### fix(recon): MCP recon now returns prior_wisdom