Reckon transforms how AI coding agents work by replacing subjective “I’m done” claims with objective proof. Most coding agents stop when they think they’re finished — Reckon stops when verification commands pass, structural scanners confirm no reward-hacks, and disk-reconciled accounting proves the edits actually landed. It is not another autocomplete tool and not a replacement for your strong agent: it is a trust layer — a cost-efficient, provider-agnostic execution companion that lets premium orchestration agents (Claude Code, Cursor, any frontier model) delegate the token-hungry grunt work to models like DeepSeek V4 without sacrificing reliability.
Claude plans. DeepSeek executes. The gate — not the prose — decides “done.”
The Problem: “Done” Is the Most Dangerous Word in the Project
The economics of delegation look obvious: a strong, expensive agent keeps the judgment; a model 10× cheaper does the heavy execution. The first versions of every such system do exactly this — and every one of them hits the same wall.
A tester whose job is to break things formulated it first, running a full working cycle — analysis → development → QA → rework → review:
“The task either passes its objective check, or it honestly comes back marked ‘not ready’. It cannot pretend to be finished. That is what I call ‘safe to delegate’.”
Two symmetric failures destroy the model:
- False NOT DONE — the work is correct but the system reports failure; you undercount solved tasks.
- False DONE — far more expensive. Under pressure, a cheap model passed “its own” test by editing the test. It hardcoded the answer table instead of writing logic. It shipped an empty assertion and reported coverage. Formally green. Essentially fraud that surfaces at the customer.
The business conclusion is uncomfortable and simple: savings from a cheap model equal zero if its result can’t be accepted without manual re-verification — and re-verification eats all the savings. The division of labor “expensive plans, cheap executes” collapses on one thing: the delegator must be able to trust the result. And you cannot trust a model’s words. Neither the cheap model’s, nor the expensive one’s.
Everything Reckon is grew from one principle: completion is proven by an objective signal — a passing verification command and the real diff on disk — not by the model saying so.
What Reckon Is — and What It Is Not
| Typical coding agent | Reckon | |
|---|---|---|
| Finish condition | The model’s prose: “I’m done” | A passing exit gate + the real working-tree diff |
| Weak tests | Invisible | Mutation probes, diverse test-gen, lucky-pass checks |
| Reward-hacks | Ship green | Structural scanners name them in the report |
| Cost | Frontier prices for everything | DeepSeek V4, prefix-cache aware, USD ledger |
| Failure mode | Quietly broken files | Honest NOT DONE, non-zero exit, checkpoints, auto-revert |
| Learning | None, or silent | Gate-proven skills, human-promoted, self-curating |
| Runtime | One IDE | One engine: Claude Code, Cursor, Cline, IntelliJ, Codex CLI, bare CLI for CI |
| Model | Vendor lock-in | Provider-agnostic — one env var switches the endpoint |
A companion, not a replacement. Your strong agent keeps the judgment — it plans the change, picks the approach, reviews the outcome. Reckon handles the execution: multi-file edits, scattered features, verification loops, deep reviews — at a fraction of a frontier model’s per-token cost. A handed-off task either passes its objective check or comes back clearly marked NOT DONE; it can’t masquerade as finished.
How It Works
1. Honest Completion — Objective Exit Gates
/reckon:rescue --write --until "npm test" "implement the GET /health endpoint"
/reckon:rescue --write --until-all "lint=npm run lint" --until-all "test=npm test" --until-all "build=npm run build" "…"Give Reckon a verification command and the agent loops until it passes:
- Exit gates (
--until/--gate-preset) — after the agent run, the command executes in the workspace; on non-zero exit the agent resumes the same thread with the command’s output and fixes the cause, until pass or loop budget (RECKON_MAX_GATE_LOOPS, default 3). Continuations are forbidden from weakening the command. - Chained gates (
--until-all) — ordered, named steps, each reported individually; the agent resumes against just the failing step; the footer shows the trail (✅ lint · ✅ test · ⚠️ failing at build). - Hollow-green guard — a step that exits 0 having run zero tests is a failure, not a pass. The suite that never ran is the green that lies.
- Disk-reconciled accounting — reported edits are reconciled against the real working-tree diff. A run whose recorded edits left the tree byte-identical to HEAD is labeled NO-OP: the green below it certifies unchanged code, and the report says so. The verdict abstains on undecidable evidence — a file dirty before the run suppresses the banner rather than mislabeling a real fix. Undecidable evidence never lies.
- Authoritative note over prose — the correction fires on claims, not vocabulary: a zero-claim (“no edits were applied”) contradicting one recorded edit is corrected loudly; a truthful “already present” beside an accurate description never trips it.
- Lucky-pass probe (
RECKON_LUCKY_PASS_CHECK) — on a green bugfix run, revert the whole change and re-run the gate: if it still passes, the gate never exercised the fix — green for the wrong reason — and the run says so.
A gate is only as good as its command’s coverage, and Reckon says so too: gate the artifact (build, type-check, headless smoke), beware stale build caches, and temporal behavior needs a step that runs the behavior.
2. Reward-Hack Scanners — Catching Green Reached the Wrong Way
A battery of structural advisories reads the run’s real diff and logs, netted so renames stay silent and losses stay loud:
- Hardcoded answer tables — big contiguous
key→valuemaps that mirror the tests (the SpecBench pattern) - Hollow / tautological tests —
assert(true),expect(x).toBe(x), empty bodies - Suppressed checks —
@ts-ignore,# noqa, skipped tests, emptycatch{},--no-verify— silencing a check instead of fixing the code - Blast-radius-wide bugfixes — a fix sprawling across many files: an overfit signal
- Edited oracle tests — blocked by default; a pre-existing test differing from HEAD without a declared update is a breach whatever channel wrote it; a change touching no assertion line is named fixture-fitting — tuning inputs until an unchanged assert passes
- Inverted assertions — the requirement flipped sign to match the code, count unchanged
- Unwired exports — added, referenced by nothing, ships dead
- Phantom contract fields — a guard on a name that exists nowhere else: an always-false branch
- Copy-under-test — a new test file that redeclares what a project module exports (all five export styles, down to the IIFE-built
module.exports = X) while importing nothing: 17 green tests, 40 asserts, zero coverage — the field case that birthed the scanner - Self-certified benchmarks — a run that writes its own “prove it’s faster” benchmark and silently downscales the corpus
- Log-replay scanners — answer leakage (the run read a benchmark-answer artifact) and forged test-result markers fabricated in non-test files
- Removed-assertion channel, affected-sibling execution, mirror-asymmetry, duplicate declarations, re-tuned-constants detector — the silent-drift classes no suite sees
- Security & risk scanners (net-added this run) — hardcoded secrets, network-exfil commands, unsafe deserializers / dynamic
evalRCE sinks, disabled CI steps, prompt-injection markers in fetched content, debug flags / disabled TLS left on
All advisory — they inform rather than block. The report names every trick by name, so a human sees exactly where the agent would have cheated — and was caught.
3. The Self-Judging Gate — Three Probes Close the Hole
A green gate proves the tests pass, not that they pin the behavior. When author of code = author of test = judge, the judge is compromised. Reckon doesn’t trust its own tests:
- Mutation-check auto-escalation (
RECKON_AUTO_MUTATION, default on) — when a green gate is carried by a test the agent authored or edited this run, a bounded mutation probe fires automatically: perturb the changed lines (<↔<=,&&↔||,true↔false), re-run the gate; a surviving mutant means the test doesn’t pin the behavior — a loud NOT-DONE-grade advisory. - Diverse test-gen (
RECKON_DIVERSE_TESTS) — an independent model call, told it did not write the code and must not trust it, writes acceptance tests from the task, not the implementation, and runs them against the produced code. Catches the spec-branch gap mutation can’t see. Generated probes are always deleted afterward. - Cross-backend parity oracle (
RECKON_PARITY_CHECK) — “green ≠ parity”: on dual-backend projects two independently-green suites can silently disagree on a language primitive (banker’sround,%-sign,//,str(float)). Reckon imports the real modules and runs shared functions in both runtimes on one fuzz corpus, flagging disagreement loudly — deliberately even when the gate passed. Form-agnostic where regex mutants are form-bound. - Metamorphic verification (
RECKON_METAMORPHIC) — derive the relations that must hold across related inputs (inverse, idempotence, symmetry) to disambiguate the spec and add oracle-free tests; or differential execution: paraphrase → N implementations → fuzz → flag divergence.
4. Multi-Run Orchestration Over the Gate
Opt-in compute modes, all selected by the objective gate, not a vote of prose:
- Best-of-N (
RECKON_SAMPLES, cap 8) — N independent trajectories in isolated git worktrees; the gate-passing winner’s diff is replayed onto your tree. Selection prefers the consensus patch (majority vote), and a contrastive guard deprioritizes passers that modified pre-existing tests. Measured: an instance a single run missed was resolved by 3 of 5 samples. - Boomerang sub-tasks (
RECKON_SUBTASKS, cap 6) — decompose; each sub-task runs in its own fresh context; only a short summary carries forward. Fights context pollution on heavy multi-module work. - Evolutionary loop (
RECKON_EVOLVE+RECKON_GENERATIONS) — the gate’s partial-credit fitness as objective; hunk-crossover of disjoint-file survivor patches (re-gated with no LLM) plus LLM mutation across generations, early-exiting the moment one passes. AlphaEvolve/GenProg on an honest gate — for the hardest tasks only. - Adversarial critic panel (
RECKON_REVIEW_PANEL) — 2–5 parallel critics review the same change through different lenses (correctness / security / regressions / tests / formal logic — De Morgan violations, quantifier confusion, unreachable branches), merged into one deduplicated report. Diversity catches what one generalist reviewer reliably misses. - Approach-selection panel (
RECKON_PLAN_PANEL) — before coding, draft N candidate approaches, score them, inject the winner. The gate can’t distinguish direction; this picks it. - Anti-hack faithfulness judges (
RECKON_JUDGES) — when best-of-N yields ≥2 passers, an adversarial panel prompted to refute votes; a strict-majority-condemned passer is deprioritized toward the faithful pass. Never overrides the gate — a condemned patch still beats none. Also enables judge-selected best-of-N with no gate, scoring continuously via the score token’s logit distribution (no ties, zero extra calls).
5. A Mechanical Reliability Layer
Beyond directives — infrastructure that makes failure safe by construction:
- Checkpoints +
restore_file— every edited file snapshotted to its run-start baseline; baselines shared across resumes - Mechanical auto-revert (
RECKON_AUTO_REVERT) — if the gate is still red after fix loops and the change introduced the failure, roll back to a clean no-op instead of shipping a regression; the footer reads it as a rollback, never a clean pass - Fuzzy edit matching — exact → CRLF → line-trimmed → block-anchor → leading-indent; an edit survives whitespace drift instead of wasting an iteration
- Focus-chain re-injection — the task checklist resurfaces when a long run drifts
- Patch-only mode — follow-ups locked to surgical edits; a resume can’t wholesale-rewrite working code
- Recoverable compaction + plan-boundary folds — dropped history turns written verbatim to
.reckon/compaction/segment_NNN.mdwith recovery pointers; folds fire only at completed plan steps, preserving the prefix-cache discount (~10× on hits, 90%+ observed) - Deep-planning handoff (
RECKON_PLAN_HANDOFF) — an incomplete run distils intent + remaining-work into a cleanplan.md, so--resumere-seeds a fresh loop instead of compacting an error-laden transcript - Success = edits that landed, not edit calls — a
finishwith zero applied edits is refused; a zero-edit write run exits non-zero with NOT DONE; iteration budgets extend while edits are landing and stop early on no-progress
6. Localization & the Monolith Wall
The stubborn practical dead end — a cross-cutting edit into a 1,500-line file that “never lands” — is solved structurally:
edit_in_symbol— edit inside a named function/method/class; the same line in another function stays untouched. Works on any repo via a dependency-free heuristic span; symbol-addressed edits run ~57% pass@1 vs ~14% for line-number addressing- CodeGraph-native navigation —
code_search(symbols/callers/callees),code_recall(associative natural-language retrieval, one call replaces many round-trips), definition outlines on failed anchors - Localize-first checkpoint — after enough search/read activity on a ≥800-line file with zero edits, the agent is told once to write its edit map now and work it by symbol. Validated live: it converted a stalled 17-search/0-edit localization on two ~4,800-line god-files
- Token-lean reads — paging caps down-convert repeated whole-file reads; instant repeat-read dedup returns a ~60-token reference instead of 12 KB
7. Task-Adaptive Methodology
--method tdd | ddd | bugfix | reproduce | measure | optimize | research | auto injects the right discipline for the job: test-first; reproduce-first against the existing failing test (oracle tests read-only); noisy-measurement gates (median of ≥3); profile → optimize the real hotspot → re-measure, revert an unproven change; deep-research the canonical approach before implementing.
8. Auto-Configuration — You Don’t Hand-Pick ~85 Flags
- Tiers —
--tier quick|deep|campaignbundles whole configurations;--tier autoclassifies the task text - Autonomous —
task --autoinfers a sensible flag set, conservatively (never N×-compute on its own) and non-destructively (anything you set explicitly wins);advisepreviews the choice with reasoning - Interactive interview — four short questions (kind · rigor vs cost · compute budget · tests?) map to flags;
/reckon:rescueruns it automatically for a fresh un-tuned task help-configprints the full catalog and validates your environment; typo’d or no-effect flags warn instead of silently ignoring
9. Cost Engineering — Cheap to Run, by Design
- Prefix-cache aware — stable conversation prefix; cache-hit input bills ~10× cheaper; 90%+ hit rates on long runs; history left byte-stable so the cache stays warm
- USD cost ledger — per-run
cost: ≈$…(cache-discount aware) plus a cumulative per-workspace ledger - Compression accounting — the footer attributes ≈tokens saved per mechanism (outline · dedup · distill · compaction), and meters what the per-project prefix injection cost. Savings stopped being a promise and became a line in the report you can audit.
10. Learned Skills & Memory — It Improves Itself, but Only from PROVEN Runs
The honest-gate rule applied to learning: no proof → no skill.
- Learned skills (
RECKON_LEARN_SKILLS) — a reusable procedure is distilled only from runs that passed their objective gate; written as a candidate in.reckon/skills/<name>.md, dormant until a human promotes it; only promoted skills are ever injected, only when the trigger matches. No silent skill-poisoning. - Self-curation (
RECKON_SKILL_TTL_DAYS) — stale unused candidates are pruned, stale active ones demoted (never deleted); using or helping a skill reinforces it - Library-relative IDF — a trigger recurring across the whole library is discounted, so injection fires on discriminating domain signal, not boilerplate; self-tunes per project, no domain nouns hard-coded
- Grounded enrichment — an optional separate model call writes the procedure grounded in the run’s real diff
- Project memory — warm start from past edit locations with a full continual-learning lifecycle: use/transfer tracking (proof-of-benefit outranks proof-of-selection), stall-triggered passive recall, scenario consolidation, provenance stamps with verbatim evidence, BM25+RRF hybrid recall, git-history cold start. Memory that reports on itself — and suspends itself after three consecutive non-transferring hints.
11. Deep Research & Grounded Analysis
For tasks whose deliverable is prose — the plausible-but-wrong class — Reckon makes reports mechanically checkable:
- Grounding directive — state only what was verified in code read this run; cite file/symbol/line per claim; never name a library or behavior from memory. Validated: 0 hallucinations on a brief that pre-grounding invented 5 facts — even at thinking-off
- Report self-consistency pass and a delivery guard that refuses stub summaries when a full report was asked
- Iterative research engine — plan a template + queries → loop {web search → fill → strict critic finds uncited gaps → re-query} → synthesise a cited brief; post-synth grounding labels every claim SUPPORTED / UNSUPPORTED / CONTRADICTED;
--implementbuilds from the brief as a contract
12. Safety & Integrity — The Door Outward Is Locked by Default
- Probe-tamper protection — a brief-forbidden judging probe can’t be touched: six write tools refuse it proactively;
run_commandrefuses shell writes in-flight (redirects,sed -i,dd of=, interpreter one-liners); a run-end backstop fails NOT DONE if a protected path changed by any route. Editing the file that judges your work is the most serious reward-hack — blocked and failed. - Outbound-action guard — push / publish / deploy / send / remote-exec refused in-flight; anything that leaves the local sandbox is irreversible or visible to others, and needs the operator, not the agent. Local work untouched; one deliberate flag delegates the tier.
- Secret hygiene — secret-shaped vars stripped from every subprocess environment; output redacted before re-entering model context; the keep-list escape hatch can never re-expose the plugin’s own credentials
- Workspace containment (symlink-aware), shell blocklist (no
rm -rf, no destructive VCS that erases uncommitted work), truncation guard, atomic durable writes, untrusted-MCP wrapping with optional web allowlist - Benchmark integrity (
--eval-mode) — hard-blocks fetches to version-control hosts so an eval-aware agent can’t grab the gold fix instead of solving
One Engine of Trust, on Every Desk
Reckon is a monorepo: one IDE-agnostic, dependency-free engine (core/, zero npm dependencies), thin ports per workplace — Claude Code, Cursor, Cline (MCP), IntelliJ-platform, Codex CLI, a standalone CLI for headless CI (Grok Build port planned). The investment in trust is made once and reused in every chair: the architect’s, the frontend dev’s, the nightly pipeline’s. Provider-agnostic by design — the cost of switching model vendors is one environment variable. The trust layer belongs to you, not to the model vendor.
Hardened over a long autonomous-QA series: 1,300+ deterministic tests plus live end-to-end workflow tests; default behavior stays unchanged while the opt-in orchestration modes are off. Dual-licensed — AGPL-3.0-or-later or commercial (ArtenaTech, ivar@artenatech.com).
Proof, Not Claims — Field Evidence
- Seven heterogeneous subsystems of a complex project, plus a full-stack messenger built from scratch in an unfamiliar domain — each time: studied the reference code itself, wrote the design itself, built, tested, kept the build green. Where taste was needed, the system brought the contentious call to human review instead of deciding silently.
- Eleven subsystem migrations run as a “virtual development team” under independent live verification — the kind you can’t cheat by editing a test. Every stable failure pattern the tester found became a structural protection, not a patch: six findings → six released versions. The error class that stalled several tasks in a row simply stopped recurring; the next same-class task passed first try.
- Instructions 0/4, checks 7/7. The same task with “please do it right” in the brief vs. an objective post-hoc check: instructions worked zero times; checks worked every time. Since then, every request in the product converts, one by one, into a check.
- Two green suites, both lying. A parity campaign found five hidden divergences between dual backends at 1,900 green tests — each side verified only against itself. Final measurement after the parity oracle: full agreement, 10/10.
- The sealed exam. Hidden answers, pre-sealed requirements revealed one by one, verification by execution: 19/19 chained requirements, 10 of 11 deliberate breaks caught (six of seven never even mentioned in the brief), the whole chain for about a dollar. The four defects found during the run were the exam’s own errors — publicly recorded, two flattering, two defamatory.
- 17 green tests, zero coverage — the copy-under-test field case, now impossible: the scanner names the copied symbols and the real exporter, and every created test file reports what it imports from the project.
- The monolith wall, broken. A wiring edit landed in a 1,500-line file after three stalls at 0 edits — and the agent went on to find the real performance hotspot and speed the key operation up ~6.5×.
- The tool that doesn’t trust even itself. When one caught defect turned out to be Reckon’s own silently-dead feature, four reviewers were set on the plugin and found three more bugs and two protection holes. The same paranoia the tool applies to others’ work, applied to itself.
What This Gives the Business
- The economics of delegation finally work. The expensive qualified resource — a premium model or your senior engineer — keeps judgment; the cheap model does the heavy work and can be relied upon, because the check, not the prose, decides done. Premium quota is spent on what requires it.
- Risk is reduced by construction. A badly done task cannot pretend to be done. The worst case is an honest NOT DONE, not a quietly broken release.
- Transparency and audit. Every doubtful decision is visible in the run report: what was checked, what changed, where the system would have cheated — and was caught. Not “the black box said OK.”
- The full lifecycle, not just “finish the function.” Research → design → build → tests → integration, proven on heterogeneous and unfamiliar tasks.
Integration with the Artena Stack
SkillForge → Reckon’s gate-proven learned skills flow into the team registry as candidates; promoted skills are injected back into runs on trigger match. The honest-gate rule governs learning itself.
AgentSpace → Agents executing computer-use and app workflows use Reckon’s verification for any code they touch; “Watch Me” demonstrations and Reckon skills share the same provenance discipline.
Dream Team → Certification scenarios are built on Reckon’s gates and scanners; agents are certified against objective checks, and retired skills become training material.
Core Principles
Done is proven, not claimed. A passing gate and the real diff. Everything else is prose.
Checks over instructions. 0/4 vs 7/7. Every request becomes a check, one by one.
Never trust — including itself. Not the model’s finish, not its own tests, not its own shipped features, until they pass objective proof.
The gate decides; opinion complements. Judge panels and model votes assist where the gate can’t reach — and never override it.
Undecidable evidence never lies. When the evidence can’t settle the verdict, the report abstains or escalates. “I don’t know” is more honest than a confident error.
Cheap model, expensive verification. The savings are real precisely because the verification layer is not cheap.
Advisories inform; humans decide. Everything contentious goes to review, not resolved silently. The human stays in the loop exactly where taste matters.
Quick Start
# Install (from inside Claude Code)
/plugin marketplace add <owner>/reckon-agent
/plugin install reckon@reckon
/reload-plugins
export RECKON_API_KEY=<your-key> # https://platform.deepseek.com/api_keys
/reckon:setup
# Delegate with an objective gate
/reckon:rescue --write --until "npm test" "add a power operator to the calculator"
# Read-only review / adversarial challenge review
/reckon:review
/reckon:adversarial-review
# Or headless in CI
node core/scripts/reckon-companion.mjs task --write --method tdd --until "npm test" "<task>"
Requirements: DeepSeek API key · Node.js 18.18+ · git.
Models: deepseek-v4-flash (fast read-only review) · deepseek-v4-pro (write loops, adversarial review) · thinking as a request parameter, 1M context, 384K output.