Atomadic Forge

Use this when: you need to check, fix, verify, or safely change a repo. action='certify': 0-100 quality score (docs, tests, tier layout, import discipline). emit_receipt=true produces Forge Receipt v1 JSON. skip_tests=true for fast mode (~500ms). action='wire': finds every upward-import violation. suggest_repairs=true adds fix hints. action='enforce': apply mechanical fixes for wire violations (apply=false=dry-run). action='validate': validates a .forge sidecar TOML — required fields + types. action='guard': installs four enforcement layers (pre-commit hook, GHA workflow, pyproject contract, CONTRIBUTING block). apply=false returns planned writes. action='composite': single go/no-go verdict — wire+certify always, score_patch+preflight_change when diff/intent supplied; returns PASS/REFINE/FAIL. action='gate': deterministic hallucination detector for LLM responses — catches unresolved imports, syntax errors, stubs, false capability claims. action='health': Forge env diagnostic — version, Python, platform, optional deps. action='check': pre-edit guardrail — given intent + proposed_files, returns each file's tier, forbidden imports, affected tests, scope verdict. action='score': patch risk scorer — submit a unified diff, get architecture/test/public_API/release risk scores and needs_human_review. action='tests': minimum + full-confidence test set selection per intent. action='cna': Compose-Not-Add check — verify a proposed symbol is not duplicating an existing one (name + body-hash similarity). Returns PASS/REFINE/REJECT. action='rollback': structured undo plan — files to remove, caches to clean, docs to restore, tests to rerun, risk level. action='diff': compares two Forge manifests side-by-side. action='ast_scope': multi-repo AST blueprint + deterministic edit locks; attest_nexus=true mirrors locks to AAAA-Nexus lineage when a key is present, and otherwise returns a premium/x402 hint without failing. action='surface_gaps': find a1 entry points missing MCP or CLI cove…

Use this when: you have an INTENT (one-line description of a new package) plus one or more SEED REPOS to harvest from, and want a shippable pip-installable package as output. Runs the full Phase 1 pipeline: emergent_swarm cross-repo composition discovery -> materialize top-N candidates into a tier-organized package -> optional certify run on the new package. Returns the create receipt (intent, seed_repos, scan_summary, materialize report, scan_report_path). The scan_report_path lets callers re-run materialize with different selections without re-scanning.

Use this when: you need to understand, analyze, or discover patterns in a repo. action='recon' (default): maps every public symbol into the 5 monadic tiers. action='explain': plain-English orientation — one-liner, core flow, do_not_break. action='call_graph': AST BFS walk — callers/callees of a target symbol. action='call_graph_summary': whole-package portfolio — orphans, hotspots, max depth. action='smell_scan': CC monsters, long functions, dup bodies (smell_score 0-100). action='churn': file-level git churn — hotspot/stable files, avg/median commits. action='surface_gaps': find a1 entry points missing MCP or CLI wiring (the gap punch-list). action='capability_scout': search GitHub for repos matching capability queries. action='dead_code': find defined-but-unreferenced symbols (vulture synthesis). action='maintainability': compute Maintainability Index per module (radon MI). action='concept_bridge': convert harvest candidates below TAU_TRUST into synthesis plans. action='lineage': query the .atomadic-forge lineage log (mode=all/by_file/failed_for_area). action='harvest': cross-repo cherry-hunter — diffs target vs source repos, ranks graft candidates by trust-gated confidence (max-depth 23, no LLM). action='synergy': intra-repo scanner — finds CLI verbs / a3 features that compose well. action='scan': single-repo emergent compositions (top_n, include_chains). action='swarm': multi-repo portfolio emergent scan (N≤23) — cross-repo bonus. All actions: no LLM invoked.

Use this when: managing the multi-agent hive, coordinating consensus, or recording agent handoffs and enhancement proposals. Lifecycle: action='register' — declare an agent's lane (role, capabilities, write_lanes, subscribes_to), max-depth 23. action='list' — see all agents. action='deactivate' — graceful shutdown. action='observe' — pull events since cursors. Consensus: action='propose' — open a cross-agent proposal (returns consensus_id). action='vote' — cast a vote (approve|reject|refine|abstain). action='needs_vote' — proposals awaiting your vote. action='result' — current verdict; record=true freezes it. action='recap' — full lifecycle of one consensus. Session: action='handoff_create' — write a structured agent-to-agent transfer; axiom_guard_status must be PASS|QUARANTINE. action='handoff_list' — recent handoffs. action='enhance_propose' — record a tool/feature proposal for human review. action='enhance_list' — read prior proposals. All actions are pure: no LLM.

Use this when: you need low-level AST inspection or repo-structure reads that are too fine-grained for explore or audit. action='body': extract the full source body of a named function or class. action='symbol': extract a named symbol (with its imports) from a source file. action='class_signals': detect class-level signals (abstract, dataclass, protocol, etc.). action='ast_scope_blueprint': build a multi-repo AST scope blueprint (node set + import graph) for deterministic edit planning. action='mint_ast_locks': mint time-bounded edit locks from an existing blueprint. action='add_node': add a node to an existing AST scope (returns updated blueprint). action='classify_repo_layout': detect how a repo is organized (monadic, src-layout, flat, poetry, etc.). action='fingerprint_repo': SHA-256 normalized-AST fingerprint per a1 module (idempotent content hash, not file hash). action='synthesis_plan': extract an actionable synthesis plan from harvest candidates below TAU_TRUST. action='swarm_repo_specs': build batch repo-spec list for multi-repo operations (input to emergent_swarm / harvest). All actions: no LLM invoked.

Use this when: driving an LLM-guided iteration session against the repo. Forge has no embedded LLM — these actions return prompts you feed to your own LLM, then the response comes back here for the next round. action='iterate': scaffold a package and emit the first LLM prompt; returns session_id for resume. action='resume': feed the LLM's response back; advances the session and returns either the next prompt or the final result. action='evolve': start a recursive multi-round session (rounds, max-depth 23 system cap, stop_on_regression). action='evolve_step': advance the active evolve round.

Use this when: calling LIVE AAAA-Nexus primitives. Requires ATOMADIC_MASTER_KEY or ATOMADIC_SUBSCRIPTION_KEY in env. op='identity_verify' — verify a DID/identity claim against Nexus. op='federation_mint' — mint a portable federation token (did, scope, ttl_secs). op='authorize_action' — gate whether subject can invoke action against resource. op='sys_trust_gate' — drift/hallucination check on a claim; returns PASS/FAIL. op='contract_verify' — verify a manifest hasn't drifted since subscription. op='lineage_record' — attest an intent+payload event to Nexus lineage. op='ratchet_register' — register a monotonic anti-replay stamp.

Use this when: you need to orient, plan, scaffold, or assemble a commit on a repo. action='context': first-call context bundle — repo purpose, architecture law, tier map, blockers, best next action, test commands, policy, workflow_recipe. action='compose': match a goal keyword to a named workflow recipe. action='policy': return the raw agent policy dict without full orientation. action='recipes': list the full recipe catalogue or fetch one named recipe. action='generate' (default): runs scout+wire+certify, emits ranked agent_plan/v1. action='apply': executes a saved plan (plan_id required). apply=False dry-runs. action='locate': returns insertion-point line range + preview (~1000-token saving). action='commit': assembles structured commit message (~10k-token saving). action='scaffold': generate a four-piece MCP tool scaffold (a1+a3 inserts, test block) without mutating files — forge eats forge. action='steersman': AST-lock decision pack tiny enough for a 1B semantic router. No LLM client inside forge for scaffold/compose/policy/recipes. v0.48.0: transmute pipeline (auto/cherry/finalize) moved to `transmute` tool; LLM loops (iterate/resume/evolve/evolve_step) moved to `loop` tool.

Use this when: absorbing a repo into a tier-organized package or running the full spaghetti→certified pipeline. This is the FLAGSHIP. action='auto' (default): single-shot pipeline — scout→cherry→assimilate→wire→certify→receipt. apply=False is a dry-run that returns the planned writes; apply=True actually materializes the package. action='cherry': produces a surgical cherry-pick manifest (cherry.json) before assimilation — pick=['all'] to take everything, or pass explicit qualnames to take a subset. action='finalize': materializes an existing cherry.json into a tier-organized package; lets you re-run with different selections without re-scanning. No LLM invoked for any action — pure deterministic absorption.

RECOMMENDED FIRST CALL when an agent connects to Forge in a new session. Runs scout + certify + wire on the current repo and returns one structured response: real numbers (score, violations, symbol count), top 3 strengths, top 3 priorities, the single most-useful next call, a rendered narrative, an agent_guidance block (briefing for talking to the human user in the agent's own voice), a capability_showcase (12 headline tools grouped by job), and a safety_net (concrete Forge guarantees). Optional run_tests=true upgrades the default fast structural certify snapshot into a full pytest-backed handshake. Optional since_receipt path emits a since-last-scan diff (score delta, violation delta) so returning agents see what changed. Also useful any time you want a one-shot situation report mid-session.

Use this when: interacting with the repo's institutional wisdom DB (.atomadic-forge/wisdom.jsonl). action='record' — append one lesson (insight, scope, tags, evidence, confidence). action='query' — relevance-rank entries by scope/tags/text; returns top_n with scores. action='list' — paginated dump of active entries (limit=20 by default; limit=0 for full; include_superseded=true for audit). action='recall' — top-N repo-scoped entries for a new agent (cheapest read path). action='promote' — cluster corroborated wisdom into draft recipe candidates. All actions are pure: no LLM.