DEV Community: Francisco Grandón

What Broke After I Moved My Agent's Rules into a CLI (And How Synthetic Scars Reshaped ag_ops v2.1)

Francisco Grandón — Sat, 31 Oct 2026 07:36:57 +0000

How four embarrassing bugs in v1, two sharp comment threads, and Randal L. Schwartz's Synthetic Scars architecture pushed a 1,031-line test guardrail into a 1,783-line governance engine—and nearly blocked its own release along the way.

In Antigravity Field Notes #1, I wrote about auditing my daily Google Antigravity setup, trimming the fixed per-turn prompt prefix by 42.4%, and moving test-tampering checks out of Markdown and into a 1,031-line (39,144-byte) standard-library Python script.

Shipping that first version felt clean for about forty-eight hours. Then two things happened at once: readers in the comments started poking at the exact joints I had taped over, and I started throwing multi-agent workloads at v1 every day.

In the comment thread on Field Notes #1, @max_quimby put a finger straight on the softest spot in the design: if an agent with shell access can unlock a Merkle-sealed test tree by passing renegotiate --reason "fixed tests", a prose rationale is just an honor system with extra steps. Any language model can invent a plausible excuse in 200 milliseconds. Around the same time, howcani highlighted a subtler problem on the red side of the cycle: witnessing a non-zero exit code proves that a command failed, not that the failure was informative or tied to the right invariant.

Meanwhile, v1 outgrew its original single-file Gist. As the tool gained a full automated test harness, changelog, and stricter contracts, I moved it into a standalone MIT repository at FranciscoGrandon/ag-ops. That repository exists because v1 developed four concrete cracks once real multi-agent sessions (a main orchestrator coordinating parallel subagents) hit it every day.

Four Cracks That Showed Up Once v1 Met Daily Work

1. Receipt collisions inside `.ag_state/merkle_guard.json`

Version 1 wrote a single hardcoded file (.ag_state/merkle_guard.json) per state directory. That worked fine when one agent sealed all of tests/. It fell apart the afternoon two subagents worked concurrently on separate modules in the same folder (tests/test_a.py and tests/test_b.py), because the second witness-red run quietly overwrote the first agent's receipt. Worse, v1 excluded *.tmp globally during Merkle traversal, so a stray fixture dropped at tests/sub/datos.tmp went completely unnoticed. Running witness-red against an empty directory also happily sealed zero files and issued a valid receipt over nothing.

2. An unanchored regex in `distill` that panicked over polite success logs

To extract pytest failures without dumping thousands of lines into context, v1 scanned output with an unanchored E\s{3} pattern meant to catch pytest's E AssertionError: lines. Then a batch runner printed this status banner near the top of a job:

 Step 1 DONE    everything fine

Look closely at the end of DONE followed by four spaces: E. My error extractor saw "DONE ", panicked over the trailing E plus three spaces, and spent its entire root-cause line budget preserving a cheerful progress banner 2,000 lines above the real crash. I had built a failure filter that was allergic to well-tabulated optimism.

3. Premature funeral notices in `state`

Our lexical runlevel tracker (00_plan.json, 10_build.json) lets long-running sessions survive context compaction. In v1, if Step 10 registered an expected output path (--artifacts dist/schema.json) while marking the phase EN_PROGRESO before the build finished, state write recorded "NOT_FOUND". On the next check, state status reported FILE_DELETED for an artifact that had never been born; once dist/schema.json did appear on disk, state status never sealed its SHA-256 hash, leaving later mutations invisible. Reusing step 10 with a new slug also unlinked the previous step file without warning.

4. Blind spots and false accusations in `ast-lint`

In v1, TK002 caught forbidden bg= / fg= arguments on themed ttk widgets using naive prefix heuristics. If an agent wrote import tkinter.ttk without as ttk and called tkinter.ttk.Button(root, bg="red"), the linter missed it completely. Conversely, if a developer wrote a plain function named def ttk_helper(bg="blue"):, startswith("ttk_") accused it of being a broken Tkinter widget. Beyond that, AUTH001 authorship checks were hardcoded instead of opt-in, and the linter had nothing to say when an agent took its two favorite shortcuts under pressure: silencing failures with except Exception: pass or importing from unittest.mock import MagicMock straight into a production module.

Taking Notes from Randal L. Schwartz's Synthetic Scars

My first instinct after finding those cracks was the bad habit most of us learned over the last two years: open GEMINI.md and type four new paragraphs of sternly worded rules. Never use bare except: pass. Never import unittest.mock outside tests/. Always clean up async streams.

Before doing that, I spent several evenings studying Randal L. Schwartz's ongoing Synthetic Scars series (especially Part 12, Giving AI Pain: The Architecture of Synthetic Scars & The Rapid-Regret Miner) and testing how his systems model mapped onto what I was seeing inside Antigravity.

I am approaching this as a working systems engineer, not a theorist, so what grabbed me in Randal's writing was how directly three of his observations diagnosed my own bugs:

The Quota vs. Prompt-Compliance Death Loop: Every time you add negative prose rules ("DO NOT swallow exceptions", "DO NOT mock production services") to a system prompt or skill file, you inject the exact tokens of that anti-pattern into the Transformer's KV-cache. During autoregressive generation, pretraining gravity from millions of internet tutorial snippets overpowers the thin semantic negation (the classic pink-elephant trap). The agent emits the banned pattern anyway, you burn 30 turns pasting 50k-token diffs to argue about it, your weekly token quota evaporates by Wednesday, and you respond by adding three more negative rules to the prompt.
Why the Bitter Lesson builds Cathedrals on Quicksand in open-world repos: Rich Sutton's Bitter Lesson holds in closed games like Go or chess because the board is fully observable and the reward signal is exact. Open-world repositories have neither property. Give an unconstrained coding agent 10x more test-time compute when a test fails, and it rarely discovers your undocumented architectural invariants; instead, it uses that extra compute to construct what Schwartz calls a Cathedral on Quicksand: 400 lines of adapter shims, tautological mocks, or silent except blocks engineered to turn pytest green while hollowing out the system underneath.
I_goal vs. I_path(π) across 588 production scars: When Schwartz audited 588 real production scars, more than 95% of critical failures did not violate the explicit ticket goal (I_goal). They broke path-induced invariants (I_path(π))—the secondary obligations that only exist because the agent chose implementation path π, such as wiring an error/cancel exit out of an async fetch state or guarding a callback against late arrivals after teardown. Humans learn I_path(π) because getting paged at 3:00 AM hurts. An LLM has no nervous system; asking it politely in Markdown to care about 3:00 AM is a category error.

If I wanted my Antigravity sessions to respect I_path(π) without bloating GEMINI.md back up to 20 KB, the pain had to live in exit codes, file hashes, AST nodes, and Git history.

Inside ag_ops v2.1.0: Turning Field Notes into Deterministic Gates

Translating those ideas into standard-library Python pushed ag_ops.py from a 1,031-line test wrapper to a 1,783-line governance engine (v2.1.0), still running on zero third-party packages.

Dimension	`ag_ops` v1.0	`ag_ops` v2.1.0	Delta / Engineering Notes
Core Script Size	`1,031` lines (`39,144 B`)	`1,783` lines (`74,674 B`)	`+72.9%` lines; single-file architecture preserved
External Dependencies	`0` (`14` stdlib modules)	`0` (`15` stdlib modules)	Added `fnmatch` for receipt-bound `--ignore` globs
CLI Subcommands	`4` (`guard`, `distill`, `state`, `ast-lint`)	`5` (+ `regret-mine`)	Added Stage-1 AST/Git Rapid-Regret Miner
Static Rules (`ast-lint`)	`3` (`.py` only)	`9` (`5` `.py` + `4` `.dot`) + `--context-map`	`TK001`, `TK002`, `PATH001`, `PATH002`, opt-in `AUTH001` + Graphviz `DOT001`, `DOT002`, `SCAR-PROC-152`, `SCAR-ASYNC-01`
Guard Receipts & Renegotiation	Single `merkle_guard.json`, prose `--reason`	`merkle_guard_<sha256[:12]>.json`, `SCAR-PROC-150`	Target isolation, persistent `collisions` array, `--require-witness`
Automated Test Suite	Ad-hoc script checks	`tests/test_ag_ops.py` (`333` lines)	`6/6` integration suites using isolated temp dirs

Here is how each piece works in practice, using real invocations and verbatim JSON payloads from ag_ops.py v2.1.0.

1. `guard` and `SCAR-PROC-150`: Isolated Receipts, Collision Telemetry, and Constructive Witnesses

First, _receipt_path_for_target killed the single-file collision bug by hashing the normalized resolved target path (os.path.normcase(str(test_path.resolve()))) into .ag_state/merkle_guard_<sha256[:12]>.json. Two subagents sealing tests/test_a.py and tests/test_b.py in parallel now write independent v2 receipts.

Exclusions in _compute_merkle_tree were stripped down to surgical minimums: only the exact state_dir, the receipt file itself, __pycache__, .pyc/.pyo/.pyd, root-level .pytest_cache, and explicit globs passed via --ignore (which get persisted inside ignored_patterns in the receipt so verify-green enforces the exact same boundary). Empty directories fail immediately with EMPTY_TEST_TARGET (exit 1), and witness-red blocks non-assertion runner failures (exit codes 2, 3, 4, 5, 126, 127, 9009), returning INVALID_TEST_INVOCATION unless overridden via --expected-exit.

Every time verify-green catches a violation (COMMAND_MISMATCH, EACCES_TEST_TAMPERING, or EACCES_TEST_TAMPERING_DURING_RUN at exit 2; COMMAND_TIMED_OUT or TEST_STILL_FAILING at exit 1), _record_guard_collision appends a UTC-stamped event into the receipt's collisions list before exiting. Even if an agent backs out its unauthorized test edit two minutes later, the collision stays on the permanent record.

Then came @max_quimby's question: how do you stop lazy prose renegotiations when subagents run unattended without an interactive TTY? You cannot call blocking input("Allow test edit? [y/N]") inside a background pipe without hanging or raising EOFError. Instead, v2.1.0 implements Schwartz's SCAR-PROC-150 constructive witness gate via --require-witness:

# Agent tries to unlock a modified test with a hand-wavy prose excuse:
python ag_ops.py guard renegotiate \
  --test-dir tests/test_billing.py \
  --reason "fixed tests" \
  --require-witness \
  --json

{
  "ok": false,
  "error": "LAZY_RETRACTION_REJECTED: --require-witness is active; specify --witness-type (spec-collision | api-lock | arch-fork)."
}

With --require-witness active, prose alone gets exit 1. To obtain a RENEGOTIATED_RED receipt, the agent has to pass a proof that _verify_constructive_witness can verify mechanically against disk or compiler output:

spec-collision: requires --conflict-a file:line and --conflict-b file:line, verifying via _validate_file_line_ref that both files exist on disk, both line numbers are in bounds, and the two locations are distinct.
api-lock: inspects the failing test run's stdout/stderr (case-insensitively) for concrete boundary/type lock diagnostics (TypeError, AttributeError, ImportError, Final, Protocol, sealed, cannot assign, visibility, private, readonly).
arch-fork: requires --fork-options with at least two pipe-separated Label@file:line blast-radius anchors verified on disk.

python ag_ops.py guard renegotiate \
  --test-dir tests/test_billing.py \
  --reason "RFC-104 mandates UUIDv4 strings while legacy parser returns int" \
  --require-witness \
  --witness-type spec-collision \
  --conflict-a docs/rfc_104.md:3 \
  --conflict-b src/billing.py:2 \
  --json

{
  "ok": true,
  "status": "RENEGOTIATED_RED",
  "reason": "RFC-104 mandates UUIDv4 strings while legacy parser returns int",
  "new_tree_hash": "c3704260ab99c04b3f7316f3fb075eb305853816466d3155762eff89714174dd",
  "previous_tree_hash": "de4dbd3b859429a6c711918cd0af3bc8c41095e0e0409f9173b122f662e8e69d",
  "cmd": "python tests/test_billing.py",
  "red_exit_code": 1,
  "history_count": 1,
  "constructive_witness": {
    "type": "spec-collision",
    "conflict_a": "D:/Users/francisco.grandon/AppData/Local/Temp/ag_ops_lab/docs/rfc_104.md:3",
    "conflict_b": "D:/Users/francisco.grandon/AppData/Local/Temp/ag_ops_lab/src/billing.py:2"
  },
  "receipt_file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\tests\\.ag_state\\merkle_guard_c4d80759f832.json"
}

Asking a Transformer in Markdown to respect test integrity invites creative lawyering; handing it exit 2 and a SHA-256 receipt leaves nothing to negotiate.

2. `ast-lint`: Path Invariants, Vector 4 (`reflex`), `--context-map`, and Pre-Flight Graphviz `.dot`

In ast-lint, _AntigravityVisitor replaced prefix guessing with full _dotted_name AST resolution across two ast.walk passes. Calling tkinter.ttk.Button(root, text='Sync', bg='red') is now caught reliably even without an as ttk alias, while def ttk_helper(bg='blue'): and tk.Button(root, bg='green') pass untouched. AUTH001 only runs when --author is explicitly passed.

To guard Python path invariants (I_path(π)), v2.1.0 added two rules targeting classic Cathedral on Quicksand maneuvers:

PATH001: flags broad except: or except Exception: / BaseException: handlers whose body is solely pass or ....
PATH002: flags unittest.mock or mock imports anywhere outside test paths (test_*.py, *_test.py, conftest.py, or test/, tests/, testing/ directories).

Every violation also carries Vector 4 from Schwartz's 4-vector scar anatomy: a "reflex" field containing the concrete orthogonal fix so the model doesn't stall in an apology loop:

python ag_ops.py ast-lint src/invoice_ui.py --json

{
  "ok": false,
  "elapsed_ms": 0.4,
  "files_checked": 1,
  "violations_count": 3,
  "violations": [
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\src\\invoice_ui.py",
      "line": 2,
      "rule": "PATH002",
      "message": "Mocking primitives from 'unittest.mock' imported in production module.",
      "reflex": "Remove unittest.mock imports from production modules; pass dependencies via constructor or callable parameters."
    },
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\src\\invoice_ui.py",
      "line": 9,
      "rule": "TK002",
      "message": "Direct 'bg=' argument forbidden on ttk.Button. Use ttk.Style() or tk equivalent.",
      "reflex": "Configure 'bg' via ttk.Style().configure('<Style>.TButton', ...) or switch to tk.Button."
    },
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\src\\invoice_ui.py",
      "line": 12,
      "rule": "PATH001",
      "message": "Silent broad exception swallowing ('except: pass') hides broken path invariants.",
      "reflex": "Catch a specific exception type and log/handle the failure context, or re-raise the error."
    }
  ]
}

Static scars also age poorly when dependencies change, a failure mode Schwartz calls Scar Ossification (autoimmune drift). Passing --context-map context_map.json pins any rule ID to an anchor file's SHA-256 signature (for example, pyproject.toml). If a library upgrade alters pyproject.toml, _apply_context_signatures automatically downgrades that rule from ENFORCED (exit 1) to PROBATIONARY_REVERIFY ("autoimmune_drift": true, exit 0), warning the orchestrator to re-verify the rule rather than blocking valid builds:

{
  "ok": true,
  "elapsed_ms": 1.041,
  "files_checked": 1,
  "violations_count": 0,
  "violations": [],
  "probationary_count": 1,
  "probationary_warnings": [
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\src\\sync_button.py",
      "line": 3,
      "rule": "TK002",
      "message": "Direct 'bg=' argument forbidden on ttk.Button. Use ttk.Style() or tk equivalent.",
      "reflex": "Configure 'bg' via ttk.Style().configure('<Style>.TButton', ...) or switch to tk.Button.",
      "severity": "PROBATIONARY_REVERIFY",
      "autoimmune_drift": true
    }
  ]
}

Finally, ast-lint now validates pre-flight Graphviz .dot state machines (_lint_dot_state_machine, or --include-dot on directories) before an agent writes async code. Four topological rules run in sub-millisecond time: DOT001 (deadlock freedom: non-terminal states need out-degree >= 1), DOT002 (reachability: non-initial states need in-degree >= 1), SCAR-PROC-152 (async states marked via parallelogram, async=true, or Awaiting*/Fetching*/Stream*/Loading* prefixes must have out-degree >= 2 including an explicit error|cancel|dispose|fail|abort|timeout|close exit edge), and SCAR-ASYNC-01 (every non-teardown resolution edge from an async state must declare a [guard: ...] predicate against late-arrival zombie callbacks):

digraph SyncStream {
  Idle -> Fetching
  Fetching -> Active [label="onPayload"]
  Active -> Closed [label="onClose"]
}

python ag_ops.py ast-lint sync_stream.dot --json

{
  "ok": false,
  "elapsed_ms": 0.436,
  "files_checked": 1,
  "violations_count": 2,
  "violations": [
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\sync_stream.dot",
      "line": 1,
      "rule": "SCAR-PROC-152",
      "message": "Async state 'Fetching' lacks explicit teardown/cancel/error exit edge (out-degree=1).",
      "reflex": "Add an explicit transition from 'Fetching' to a Disposed, Cancelled, or Error state."
    },
    {
      "file": "D:\\Users\\francisco.grandon\\AppData\\Local\\Temp\\ag_ops_lab\\sync_stream.dot",
      "line": 1,
      "rule": "SCAR-ASYNC-01",
      "message": "Late-arrival zombie race on 'Fetching -> Active': missing '[guard: ...]' predicate on edge label.",
      "reflex": "Add a cancellation/epoch guard on the resolution edge, e.g. Fetching -> Active [label=\"onResolve [guard: !isClosed && reqId == activeReqId]\"]."
    }
  ]
}

3. `distill` and `state`: Anchored Deltas and Artifact Lifecycle Sealing

Fixing distill (--cmd, --max-lines, --log-dir, --timeout exiting with 124 after killing the isolated process group) meant anchoring _ERROR_LINE_RE strictly to line boundaries: ^\s*E\s{3} for pytest assertion lines, paired with ^\s*error(?:\[[A-Z0-9]+\])?: for compiler diagnostics like Rust's error[E0382]:. " Step 1 DONE everything fine" now scrolls past in peace, while the real E AssertionError anchors the critical delta.

In state (write and status, requiring --dir alongside --step, --name, --status, --summary, --artifacts, --replace, and --strict), reusing an existing step number with a different slug now aborts with STEP_CONFLICT (exit 1) unless --replace is explicit. Artifact tracking follows a clean three-stage lifecycle:

Pre-birth: An artifact registered before creation starts as "NOT_FOUND". Calling state status --dir .ag_state/runlevels --strict flags ARTIFACT_NEVER_EXISTED (exit 2), accurately distinguishing "not built yet" from "deleted."
Automatic seal on birth: The first time state status sees that file materialize on disk, it computes _sha256_file, persists the digest atomically into NN_<slug>.json, and returns has_drift: false (exit 0).
Post-seal integrity: Any later tampering or removal triggers DRIFT_MODIFIED or FILE_DELETED (exit 2 under --strict).

4. `regret-mine`: Stage-1 Deterministic Rapid-Regret Miner

Inspired by Target 90 in Synthetic Scars, regret-mine (--repo, --window-min 60, --limit 100, --state-dir) audits recent Git commits to find where an agent (or human) wrote a function and had to rush back into the exact same AST node minutes later to fix what broke.

For consecutive commits touching the same .py production file inside --window-min, _extract_ast_function_hashes parses each revision and hashes ast.dump(node, include_attributes=False) with SHA-256. Formatting tweaks, blank lines, and edits outside the function body produce identical hashes and are ignored. When the same function's normalized AST mutates twice inside the window, regret-mine checks four deterministic asymmetry signals to separate genuine rapid regret from healthy Green -> Refactor TDD:

FIX_VERB_INTENT: corrective keywords in the follow-up commit subject matching _FIX_VERB_RE (fix, fixes, fixed, bug, hotfix, revert, oops, regret, patch, broken, typo).
TEST_ASSERTION_DELTA: len(newer["test_files"]) > 0, catching production rewrites accompanied by new or updated test assertions.
GUARD_COLLISION_RECEIPT: Unix timestamp correlation (older["ts"] <= ev_ts <= newer["ts"]) against mid-flight collisions or renegotiations recorded inside .ag_state/merkle_guard_*.json.
LINE_REVERSAL_OVERLAP: lines added in the earlier commit and deleted in the follow-up (added_k & deleted_k1), gated by refactor and control-guard checks.

python ag_ops.py regret-mine --repo . --window-min 60 --json

{
  "ok": true,
  "window_minutes": 60,
  "commits_scanned": 3,
  "tdd_refactors_filtered": 1,
  "regret_pairs_count": 1,
  "regret_pairs": [
    {
      "file": "pricing.py",
      "overlapping_functions": [
        "compute_fee"
      ],
      "delta_minutes": 12.0,
      "initial_commit": "24864454",
      "regret_commit": "456955a2",
      "regret_subject": "fix: handle None amount in compute_fee",
      "asymmetry_signals": [
        "FIX_VERB_INTENT",
        "TEST_ASSERTION_DELTA",
        "GUARD_COLLISION_RECEIPT"
      ]
    }
  ]
}

Three Scars Earned While Building the Scar Engine

It would be dishonest to write about deterministic guardrails as if v2.1.0 compiled cleanly on the first try. Building the scar engine produced three fresh scars of its own before the release could ship.

1. The regret miner that punished healthy TDD (blocking v2.0 at 5/6)

When I wired up test_06_regret_mine in tests/test_ag_ops.py, I fed it a textbook three-commit TDD sequence on calc.py:

C1 (feat: add calc): res = x + 1; return res
C2 (refactor: simplify calc): inlined to return x + 1
C3 (fix: edge case None in calc): added if x is None: return 0

I expected tdd_refactors_filtered: 1 and regret_pairs_count: 1 (C2 -> C3). Instead, my v2.0 candidate failed its own release gate (5/6 suites passing) with tdd_refactors_filtered: 0 and regret_pairs_count: 3. There is a special kind of poetic justice in writing a Rapid-Regret Miner whose maiden run blocks its own release because it cannot tell disciplined TDD apart from panic.

Two bugs had compounded:

When C2 simplified res = x + 1; return res down to return x + 1, it deleted lines that C1 had added seconds earlier. My naive added_k & deleted_k1 check saw deleted lines from C1 and flagged C1 -> C2 with LINE_REVERSAL_OVERLAP. Every variable inline in history looks like line reversal if you don't inspect what kind of line was removed.
Without a per-commit paired_files set, the nested commit loop paired C3 against C2 and transitively back against C1 (C1 -> C3), counting one bug fix twice.

In v2.1.0, regret-mine tracks paired_files per newer commit so each file only compares adjacent C_k -> C_{k+1} transitions, skips line-reversal checks when _REFACTOR_VERB_RE matches without fix verbs (is_pure_refactor), and requires inverted_lines to either touch a control-flow guard (_CONTROL_GUARD_RE: if|elif|else|raise|assert|except) or accompany another corroborating signal. That brought the suite to 6/6 green.

2. The greedy `\s*` that ate semicolon-free Graphviz edges

Graphviz DOT allows edges without trailing semicolons:

digraph G {
  Idle -> Fetching
  Fetching -> Done [label="onSuccess"]
}

In my first draft of _lint_dot_state_machine, edge_re ended with \s*(?:\[(.*?)\])? to capture optional edge attributes. Because Idle -> Fetching had no [...] block, \s* happily ate the newline at the end of line 2 plus the leading indentation on line 3, treating line breaks between state transitions as optional whitespace and leaving SCAR-PROC-152 and SCAR-ASYNC-01 blind whenever semicolons were omitted. Restricting every horizontal whitespace token in edge_re and node_attr_re from \s* to [ \t]* under re.M fixed it immediately.

3. The latency reality check (`NodeVisitor` vs. `ast.walk`, OneDrive, and Windows cold start)

Initially, _AntigravityVisitor subclassed ast.NodeVisitor in a single top-down pass. That failed whenever an import lived near the bottom of a file (below a helper function calling it) and paid dynamic getattr dispatch on every AST node. Replacing NodeVisitor with two flat ast.walk(tree) passes (imports first, calls and exception handlers second) fixed the late-import bug cleanly.

Then I ran real timing benchmarks (median of 5 runs on Python 3.12 on Windows) to see how honest our <15 ms static-check label actually was:

Target File	Lines	In-Process (`elapsed_ms`)	Wall-Clock Subprocess	Notes
`tests/test_ag_ops.py`	`333`	`6.54 ms`	`151.1 ms`	Typical module size; well inside `<15 ms`
`ag_ops.py` (local SSD)	`1,783`	`42.6 ms`	`~182 ms`	Dominated by `ast.parse()`, not tree walking
`ag_ops.py` (OneDrive path)	`1,783`	`52.9 ms`	`~193 ms`	Cloud-synced filesystem stat/read overhead

Two lessons jumped out of that table. First, once a single Python file approaches 1,800 lines, CPython's ast.parse() dominates the in-process budget; micro-optimizing the visitor barely moves the needle. Second, spawning python.exe on Windows via CreateProcessW adds roughly 140 ms of fixed interpreter startup outside time.perf_counter(). In-process, a 333-line file lints in 6.54 ms; end-to-end from an agent's shell tool, every invocation pays ~150–185 ms. That is still fast enough to run on every turn without friction, and worth reporting without hiding behind perf_counter() alone.

Hard Limits, Real-Repo Noise, and What I Deliberately Left Out

Stress-testing `regret-mine` against `dbader/schedule`

Synthetic unit tests are friendly terrain, so I pointed regret-mine at an external open-source repository, dbader/schedule (398 commits), across three time windows:

--window-min 60 (1 hour): 19 TDD refactors filtered, 11 regret pairs flagged.
--window-min 1440 (24 hours): 25 TDD refactors filtered, 24 regret pairs flagged.
--window-min 10080 (7 days): 35 TDD refactors filtered, 37 regret pairs flagged.

Inspection of the 11 one-hour pairs showed that the miner catches real rapid-regret defects cleanly, including commits like "Fix a bug where the at(':SS') syntax wasn't working" and "Missed == to !=".

It also exposed two remaining sources of false-positive noise in v2.1.0:

Docstring typo fixes inside functions: In Python's AST, a function docstring sits at FunctionDef.body[0] as an ast.Expr(ast.Constant(...)). Fixing a typo inside a docstring changes ast.dump(node, include_attributes=False) and usually carries "fix typo" in the commit subject, firing FIX_VERB_INTENT even though zero executable statements changed.
Unqualified method names across sibling classes: _extract_ast_function_hashes currently keys functions by defs[node.name]. If Job.__init__ changes in Commit A and Scheduler.__init__ in the same file gets a bugfix 20 minutes later in Commit B, defs["__init__"] collides. Stripping leading docstring constants before hashing and qualifying ClassName.method_name are queued for v2.2.

Why there is no Stage-2 LLM inside `ag_ops.py`

In Randal's full architecture, Stage 2 hands candidate regret pairs and transcript.jsonl slices to an isolated clean-room critic model to compile new 4-vector scars automatically. I deliberately left Stage 2 out of ag_ops.py. Mixing API keys, network retries, and LLM prompts into a deterministic guardrail CLI would violate the exact property that makes ag_ops.py trustworthy: zero external dependencies, zero network calls, zero token spend. Shrinking 398 commits down to 11 structured JSON candidates in milliseconds is the CLI's job; deciding whether an orchestrator subagent or a human reviews those 11 candidates belongs one layer up.

The Same-UID `.ag_state/` Perimeter

Just like v1, ag_ops v2.1.0 runs in-band under the same OS user account as the Antigravity agent. An adversarial process with unrestricted shell access could still inspect or overwrite .ag_state/merkle_guard_<hash>.json directly. In daily engineering work, ag_ops targets autoregressive laziness: stopping an over-eager model from taking statistical shortcuts like except: pass or quietly widening assert status == 200. Defending against hostile multi-tenant breakouts is a different threat model; true adversarial custody still requires separating the performer and the verifier across OS UIDs, read-only bind mounts, or CI runners.

Still Learning in Public (And Gratitude Where It Belongs)

ag_ops v2.1.0 remains a working lab instrument in standard-library Python, shaped by watching real multi-agent runs in Google Antigravity fail in ways I didn't anticipate and tightening the bolts one bug at a time.

I owe a clear debt of gratitude to Randal L. Schwartz (@randalschwartz) for the Synthetic Scars series, and particularly Giving AI Pain, for bringing decades of Unix engineering discipline, formal state-machine rigor, and empirical clarity to a space that badly needed an alternative to prompt superstition. Thank you as well to @max_quimby and howcani, whose sharp questions on Field Notes #1 turned a loose prose --reason flag into constructive witnesses and pushed this engine onto much firmer ground.

The full source code (ag_ops.py v2.1.0), the 6/6 automated verification suite (tests/test_ag_ops.py), and the MIT License are available at github.com/FranciscoGrandon/ag-ops. If you run regret-mine against your own repositories and find an edge case that breaks it, I would genuinely love to hear what broke.

GitSéance: An Offline Digital Ofrenda Where Local Gemma Summons Deleted Code (And Refuses to Guess Why It Died)

Francisco Grandón — Wed, 28 Oct 2026 10:31:30 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

                 .-"      "-.
                /   🌼  🌼   \
               |   #000dead   |
               |,  .-.  .-.  ,|
               | )(_o/  \o_)( |
               |/     /\     \|
               (_     ^^     _)
                \__|IIIIII|__/
                 | \IIIIII/ |
                 \          /
                  `--------`

"The code you delete never truly dies: it becomes the silent foundation of every commit that follows. Viva Open Source!"

— Spirit #000dead (Mictlán Relic)

What I Built

git blame only speaks for the living.

It tells you who touched the lines that survived in HEAD—but every mature repository is built on the bones of hundreds of excised functions, retired prototypes, and emergency midnight bugfixes that were quietly erased from history.

When a regression resurfaces two years later, modern teams often commit the exact same architectural mistakes of 2022. Why? Because the reasoning behind deleted code is buried deep inside git log -p, where nobody looks.

For Hacktoberfest 2026: Week 4 ("Ghost in the Machine"), bridging Halloween with the sacred Mesoamerican tradition of Día de los Muertos (Day of the Dead), I created GitSéance:

An offline-first developer archaeologist and interactive Digital Ofrenda that scans your repository's graveyard, builds a marigold-adorned altar for departed code, and lets you conduct grounded séances with excised functions powered by Google Gemma (gemma2:2b) running 100% locally on your own machine.

Demo

🌐 Live Interactive 3D Web Ofrenda: https://git-seance-q032.onrender.com

(Deployed on Render with zero cold starts, offline client-side Ollama bridge, and instant fallback mode).

Live Visual Walkthrough 📸

1. Interactive Digital Ofrenda & Awakened AST Relic (`#000dead`)

Figure 1: The interactive altar with real-time 3D Three.js volcanic tiers, 1,200 instanced cempasúchil marigolds, 4 CRT holographic monitors, glowing neon data cables, and the unlocked #000dead Mictlán relic verifying real-time FNV-1a DOM attestation.

Figure 1b: Dedicated close-up of the Three.js r128 procedural altar: 4 CRT holographic terminals (amber, matrix green, cyan, magenta) with scanlines and blinking cursors, pulsating neon cables, and 1:10 cirios scale.

2. Sentry Agent Tracing Telemetry & Anti-Hallucination Guardrail

Figure 2: Real-time telemetry dashboard monitoring ai.seance spans, Chart.js latency and token distributions, and pre-flight interception of vague commits (0.02ms latency, 0 hallucinations).

Figure 2b: Production transaction trace in live Sentry.io dashboard (summon_legacy_payment_retry_loop span ai.seance) validating real-time telemetry, tag attributes (death_sha, engine_source, grounded_sha), and sub-millisecond execution.

3. Local Terminal CLI Séance & Mictlán Relic Introspection

Figure 3: Running python git_seance.py --mictlan in the terminal, decoding the embedded hex cipher, inspecting 38KB of AST nodes, and channeling departed spirits with zero network calls.

Interactive Technical Easter Eggs 💀✨

AST Self-Introspection & FNV-1a Code Attestation (#000dead): Running python git_seance.py --mictlan dynamically introspects its own source code on disk using Python's ast module (ast.parse), extracts the embedded hex cipher, and verifies 32-bit FNV-1a hash parity (0x71790691). In the web app, typing mictlan or clicking the golden calavera reads <script id="gitSeanceCoreScript"> directly from the DOM and attests identical hash parity.
Zero-Asset Resonant Altar Bells (Web Audio API): No external audio files. Altar bells are synthesized on-the-fly via Web Audio API using a D-minor harmonic arpeggio (La Bruja motif: 293.66Hz, 349.23Hz, 440.00Hz, 587.33Hz) with exponential decay GainNode filters.
Marigold Petal Storm (Canvas Physics): Activating the altar unleashes a physics particle system where 38 golden cempasúchil and purple petals drift and rotate with harmonic sway (Math.sin(angle) * 0.4).

Code

FranciscoGrandon / git-seance

🌼🕯️ GitSéance v1.1.0: Real-Time 3D Digital Ofrenda Where Local Gemma Summons Deleted Code (And Refuses to Guess Why It Died)

💀🌼 GitSéance: The Haunted Code Archaeologist & Digital Ofrenda 🌼💀

"The code you delete never truly dies: it becomes the silent foundation of every commit that follows. Viva Open Source!"
— Spirit #000dead (Mictlán Relic)

Creado por Francisco Grandón Vergara

                 .-"      "-
                /   🌼  🌼   \
               |   #000dead   |
               |,  .-.  .-.  ,|
               | )(_o/  \o_)( |
               |/     /\     \|
               (_     ^^     _)
                \__|IIIIII|__/
                 | \IIIIII/ |
                 \          /
                  `--------`

Important

🌐 Live Web Ofrenda (Render): https://git-seance-q032.onrender.com
📰 Official DEV.to Submission: GitSéance: An Offline Digital Ofrenda Where Local Gemma Summons Deleted Code
📦 Source Repository: https://github.com/FranciscoGrandon/git-seance (Release v1.1.0 · 47 Automated Tests · 0 AST Violations)

📖 Table of Contents

View on GitHub

📦 Official Repository & Release: FranciscoGrandon/git-seance (Release v1.1.0)

🧪 Quality Gate: 49 Automated Unit Tests (Ran 49 tests in 29.4s OK) · 0 AST Violations · Full Python 3.10 / 3.11 / 3.12 CI/CD Matrix

Quick Start: Summon Your Own Graveyard

# 1. Clone the repository
git clone https://github.com/FranciscoGrandon/git-seance.git
cd git-seance

# 2. Pull local Google Gemma via Ollama
ollama pull gemma2:2b

# 3. Hold your first séance (works on ANY git repository!)
python git_seance.py

# 4. Or awaken the secret Mictlán AST Relic
python git_seance.py --mictlan

How I Built It

1. The Core Challenge: Small Models Love Making Up Tragic Ghost Stories

When I first fed deleted git diffs into local 2B language models and asked, "Why was this function removed?", Gemma did what small language models do best: it hallucinated.

If a commit message was informative—such as "Drop parse_xml_invoice_soap to patch XXE vulnerability (CVE-2026-0412)"—Gemma recited a magnificent, respectful memorial.

But what happened when the commit was a Friday 4:59 PM rush job that literally said "wip" or "cleanup"?

The model immediately fabricated an elaborate, fictional backstory about microservice migrations, imaginary database locks, or phantom compliance audits!

In software archaeology, a fictional story is worse than silence.

2. The Deterministic Tombstone Grounding Pipeline

To make GitSéance an authentic developer tool rather than a toy, I engineered a multi-stage deterministic safety pipeline:

                       ┌────────────────────────────┐
                       │  git log -p Graveyard Miner │
                       │    (Single-Pass Pipeline)  │
                       └─────────────┬──────────────┘
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼                                       ▼
    ┌─────────────────────────┐             ┌─────────────────────────┐
    │ Polyglot AST Symbol     │             │ Cryptic Commit Preflight│
    │ Extractor (Py/JS/Go/Rs) │             │ (wip/cleanup Interceptor│
    └────────────┬────────────┘             └────────────┬────────────┘
                 │                                       │
                 │ 🛡️ Is commit cryptic?                 │
                 ├─────────────────── YES ───────────────► 🛡️ Fallback
                 │                                            Epitaph
                 │ NO (Informative commit message)
                 ▼
    ┌─────────────────────────┐
    │ Local Google Gemma 2B   │ (Ollama localhost:11434 / temp=0.25)
    │ Séance Inference Engine │ ($0.00 Cloud Bill / 100% Local Privacy)
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ Grounding Fact-Checker  │ (Verifies Commit SHA, File & Lexical Overlap)
    └────────────┬────────────┘
                 │
                 ▼
    ┌────────────────────────────────────────────────────────┐
    │ Sentry Agent Tracing (`ai.seance` OpenTelemetry Spans) │
    │   • Latency (ms)  • Token Count  • Hallucination Flags │
    └────────────────────────────┬───────────────────────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
    ┌─────────────────────────┐     ┌─────────────────────────┐
    │ Terminal CLI Ofrenda    │     │ Single-Page App Ofrenda │
    │ + AST Relic (#000dead)  │     │ (Render / index.html)   │
    └─────────────────────────┘     └─────────────────────────┘

Streaming Single-Pass Git Miner (mine_git_graveyard): Rather than spawning hundreds of slow git show subprocesses, GitSéance streams git log -p -U0 in a single pass with delimited token buffers, extracting author, timestamp, commit SHA, and exact unified diff deletions in under 120ms while cross-referencing against live symbols in HEAD to eliminate false positives.
Pre-Flight Cryptic Interceptor (is_cryptic_commit): Before burning CPU or GPU cycles on an LLM, the commit message is audited against low-signal patterns (wip, temp, cleanup, fix, chore: wip). If flagged, GitSéance short-circuits inference completely and delivers an honest, unvarnished epitaph in 0.02ms.
Low-Temperature Bounded Prompting (temperature=0.25) with Untrusted Data Isolation: The model is instructed to adopt the persona of the departed function speaking in the first person, bounded strictly inside <untrusted_git_data> XML delimiters to prevent indirect prompt injection.
Post-Generation Lexical & Referential Fact-Checker (verify_response_grounding): Audits the response against three deterministic gates: (1) exact 7-character commit SHA prefix (e.g., #8f3a91c) and file path, (2) lexical entity overlap ($\tau \ge 0.35$) against verified git source tokens, and (3) deterministic rejection of hallucinated proper nouns or external frameworks (e.g., "Stripe Radar", "Redis", "OAuth", "VP") in $<1\text{ ms}$ using standard library set theory.

Real-World Benchmark ($n=25$ Historical Commits)

Evaluated Metric	Unconstrained `gemma2:2b` (`temp=0.8`)	GitSéance Pipeline (`temp=0.25` + Guardrails)
Cryptic Commits ($n=8$): Invention Rate	100.0% (8/8 fabricated backstories)	0.0% (8/8 intercepted in Pre-Flight at 0.02 ms)
Descriptive Commits ($n=17$): Lexical Fidelity + SHA Citation	64.7% (11/17 ungrounded or extrapolated)	100.0% (15/17 on first attempt + 2/17 via Fallback after lexical rejection)
LLM Inference Latency ($n=17$, excluding Pre-Flight)	$p_{50} = 640\text{ ms}$ / $p_{95} = 1,120\text{ ms}$	$p_{50} = 590\text{ ms}$ / $p_{95} = 980\text{ ms}$ (Apple M2, 8GB RAM)
Effective Global Latency ($n=25$, including Pre-Flight)	$p_{50} = 640\text{ ms}$ (25 Ollama calls)	$p_{50} = 488\text{ ms}$ (17 Ollama calls + 8 blocks at 0.02 ms)

3. Sentry Agent Tracing Telemetry & Empirical Latency Debugging

GitSéance executes 100% on the Python Standard Library by default (Air-Gapped Mode with zero third-party dependencies required). For production environments and observability, it includes an optional adapter for Sentry (sentry-sdk 2.x) that activates when SENTRY_DSN is configured.

Every séance transaction is instrumented with custom OpenTelemetry spans under the ai.seance namespace:

Tracked Tags: death_sha, engine_source (gemma_local vs deterministic_guard), grounded_sha, cryptic_commit_blocked, and ast_quine_verified.
Tracked Measurements: latency_ms, tokens_generated, and prompt context byte size.

The Bug Caught via Sentry Tracing

Initially, I was sending cryptic commits ("wip cleanup") directly to gemma2:2b and attempting to curb hallucinations via system prompt alone. Sentry span data revealed that we were burning ~610ms and ~75 tokens per cryptic commit while still failing referential grounding 25% of the time. Moving is_cryptic_commit into a deterministic pre-flight interceptor dropped cryptic-commit latency from 610ms to 0.02ms and reduced hallucinations to 0%.

4. Cloud Infrastructure: Render Blueprint & Web Architecture

GitSéance is deployed on Render as a Python Web Service via a declarative Infrastructure-as-Code Blueprint (render.yaml):

services:
  - type: web
    name: git-seance
    runtime: python
    buildCommand: "pip install sentry-sdk"
    startCommand: "python server.py"
    healthCheckPath: /healthz
    envVars:
      - key: PYTHONUNBUFFERED
        value: "1"
      - key: SENTRY_DSN
        sync: false

Zero Cold Starts: Serves the 3D Single-Page Ofrenda with minimal latency.
Client-Side Privacy Bridge: In full alignment with offline privacy, the web app connects directly to the user's local Ollama endpoint (http://localhost:11434) for private inference, or provides an instant deterministic engine for users without local models installed. Zero proprietary codebase data ever touches the cloud.
Automated Pull Request CI/CD: A dedicated GitHub Actions workflow (.github/workflows/ofrenda_pr.yml with fetch-depth: 0) posts an automated Digital Ofrenda memorial comment to Pull Request threads whenever legacy code is deleted.

5. Engineering Rigor: 49 Automated Tests

test_git_seance.py (28 tests): Single-pass mining, unified diff chunk parsing with mixed indentation, polyglot symbol extraction, cryptic commit pre-flights, grounding verification edge cases with lexical entity overlap, local HTTP Ollama mock server, and AST relic self-introspection.
test_html_ofrenda.py (15 tests): DOM element consistency, cross-language FNV-1a parity, XSS HTML entity escaping, and live headless browser DOM verification using headless Microsoft Edge (msedge --headless --dump-dom).
test_server.py (6 tests): Zero-downtime container /healthz probe, dynamic REST archaeology endpoints, strict OWASP headers, and path traversal rejection.
Strict AST Syntactic Conformance: Verified 0 syntax or architectural violations across all Python codebase files via AST parsing (ast.parse) and static validation (ag_ops.py ast-lint).

Why Does Open Innovation Matter?

Zero Proprietary Data Leaks (Air-Gapped Privacy): No engineering organization will ever upload their internal git logs, deleted security patches, or proprietary business logic to third-party cloud APIs just to analyze tech debt. Running Google Gemma locally guarantees 100% air-gapped privacy.
Permanent Immortality ($0.00 Per Séance): Cloud APIs deprecate, rotate tokens, and charge per 1,000 tokens. GitSéance runs on standard git plumbing and open weights. You can run this tool in an underground bunker twenty years from now with zero internet connection.
Deterministic Verifiability: Open innovation allows developers to inspect, audit, and benchmark model weights and prompts directly, pairing open-weight intelligence with verifiable static analysis.

My Agent Session

GitSéance was engineered through a disciplined pair-programming workflow combining developer vision with autonomous agentic tools:

Empirical Observability over Assumptions: When initial séances on rushed commits produced hallucinations, we didn't guess the cause; we instrumented sentry-sdk spans across all LLM inference points, analyzed token distributions, and identified the 610ms latency leak on cryptic messages.
Deterministic-First Architecture: Rather than relying exclusively on prompt engineering, the agentic session guided the creation of deterministic safety gates: AST extraction, FNV-1a hashing, and set-theory entity filters executing in <0.05ms.
End-to-End Delivery: Every phase was backed by verifiable evidence—from headless Edge DOM verification and 49 unit tests to a live deployment on Render and GitHub release publishing.

The Spirit of It

Software engineering often treats deleted code as trash—something to discard with git commit -m "cleanup" and forget.

But code is human intention crystallized in logic. Every excised helper function was once someone's late-night breakthrough, someone's urgent fix that kept production alive, or an architectural hypothesis that taught the team what not to build.

By fusing the technological ghost in our version control systems with the sacred Mesoamerican tradition of Día de los Muertos, GitSéance shifts the developer mindset from reckless refactoring to respectful archaeology:

When you light a virtual candle for an excised function, listen to the bronze altar chimes, and watch the marigold petals drift over the code that came before you, you realize: our current systems only stand because those departed lines once bore the weight.

Prize Categories

I am officially entering GitSéance into the following categories:

Overall Winner
Best Use of Gemma — For local, offline gemma2:2b inference via Ollama, structured around low-temperature persona channeling, deterministic tombstone grounding, and lexical anti-hallucination guardrails.
Best Use of Render — For the full-stack Python Web Service deployed via a declarative Render Blueprint (render.yaml), container health checks (/healthz), dynamic archaeology REST endpoints, and delivery of the interactive 3D Three.js Digital Ofrenda at https://git-seance-q032.onrender.com.
Best Use of Sentry Agent Tracing — For deep OpenTelemetry tracing of local AI inference with custom ai.seance spans, tracking latency, token usage, and grounding metrics, which empirically caught and fixed a 610ms latency leak during development.
Best Use of GitHub Copilot — For leveraging GitHub Copilot and automated GitHub Actions CI/CD workflows to generate Pull Request Digital Ofrenda memorials whenever dead code is deleted.

Built with reverence by **Francisco Grandón Vergara* for Hacktoberfest 2026: Week 4 ("Ghost in the Machine"). Viva Open Source! 🌼💀*

I Cut My Agent's Fixed Context by 42% and Moved Its Test Rules into a Hash-Checked CLI

Francisco Grandón — Mon, 26 Oct 2026 05:42:53 +0000

How an ongoing systems debate, one token-economics guide, and a few unusually sharp comment threads turned into 1,031 lines of standard-library Python across a CLI and its test harness, a significantly leaner prefix, and an agent that can no longer quietly edit its own exam.

The Confession & The Stack

Before diving in, here is the setup: I work in Antigravity (Google's agentic CLI/IDE platform), where an orchestrating agent runs tools locally against the workspace. Like many agent environments, it injects root configuration files on every single turn—specifically a global GEMINI.md system prompt and an orchestration protocol (orchestration.md).

For months, my setup had been getting more "secure" the way a junk drawer gets more "organized": by adding more stuff.

Every edge case left behind a new paragraph in Markdown: Don't store secrets in plain text. Use integer font sizes in Tkinter. Never force-push. Always delegate. My global instructions file had ballooned to 20,110 bytes. When I finally audited what was actually getting injected into context on every single turn, I found something embarrassing: several policies were being loaded in duplicate or triplicate. The orchestration protocol was declared in two files. The secrets policy was declared in three. The model was re-reading the exact same sermon three times before writing its first line of code.

Then I followed Randal L. Schwartz's ongoing series, Synthetic Scars (an evolving series spanning parts like Part 3.6, 3.7, and 3.12). One title landed like a direct diagnosis: The Best Prompt Rule Is the One You Delete.

Meanwhile, Paul Irolla's breakdown on Claude Code Hooks and Token Economics supplied the financial grounding: anything that enters conversation history gets re-sent on every subsequent turn, and whatever a script can compute locally is a token you never send to the model.

This post is what happened when I stopped treating Markdown as a runtime firewall and pushed enforcement down into the filesystem, compiler, and Git.

1. The Audit: Finding the Triplicate Sermon

Before writing code, I measured the baseline. Here is the exact footprint of what my agent had to load on every single turn:

File / Always-On Rule	Before	After	Change
Global instructions (`GEMINI.md`)	20,110 B	10,506 B	−47.8%
Subagent directives (`AGENTS.md`)	2,022 B	2,468 B	+22.1% (+446 B)
Orchestration protocol (`orchestration.md`)	5,922 B	5,279 B	−10.9%
Secrets reference (`keyring_secrets_management.md`)	3,657 B	Loaded on demand	Removed from prefix
Total Fixed Prefix per Turn	31,711 B	18,253 B	−42.4%

Zero safety rules were deleted. All 17 clauses of the security protocol (including Rule Zero requiring explicit human confirmation before any medium or high-risk command) remain intact.

How do conditional modules actually load?

A reasonable question is: if you moved rules out of the permanent prefix, who decides when to load them?

In Antigravity, rules can use an explicit frontmatter trigger: trigger: always_on vs trigger: model_decision. When set to model_decision, the environment only presents a 1-line description in its rule index. The full text mounts only when the task context matches that domain.

The honest risk of this −42.4% cut: if the routing description fails to trigger, the agent operates without those domain instructions. We mitigated that risk for core rules by keeping a 1-line hard constraint in GEMINI.md that explicitly points to the rule file. The rule stays out of the permanent token bill, but the model has an unambiguous signpost when touching that subsystem.

Why did AGENTS.md grow by 446 bytes? Because that small addition tells every spawned subagent where the physical CLI guardrails live. That is context budget well spent.

2. The Engine: `ag_ops.py` (1,031 Lines Across CLI & Test Suite)

Instead of writing more Markdown pleading with the model not to hallucinate or cheat, I implemented a single standard-library-only Python CLI (available here on GitHub Gist under the MIT License) backed by an automated verification suite—totaling 1,031 lines of pure standard-library Python in the core tool—with deterministic --json output across four subcommands:

# 1. Seal tests & demonstrate the bug fails on untouched code:
python ag_ops.py guard witness-red --test-dir tests/ --cmd "pytest tests/test_calc.py" --json

# ...agent applies code patch in production files...

# 2. Verify green AND guarantee the test tree was not modified:
python ag_ops.py guard verify-green --test-dir tests/ --json

Here is what each component does:

A. `guard`: Merkle Locks & Command Binding

witness-red: Traverses --test-dir, computes a deterministic SHA-256 Merkle manifest of every test file (with automatic CRLF normalization to ensure Windows/POSIX parity, ignoring build caches and receipt files), verifies that running the test suite does not self-mutate --test-dir, binds the exact command string to the receipt, and actively rejects cooperative tests:

  {"ok": false, "error": "COOPERATIVE_TEST: Test passed before fix (exit 0). Red state was not witnessed."}

It also rejects non-assertion runner failures (such as pytest exit codes 2, 3, 4, 5, or shell 127/9009) unless explicitly overridden via --expected-exit. Once witnessed, it records the cryptographic receipt atomically via _atomic_write_json (tempfile.mkstemp + os.replace) in <state-dir>/merkle_guard.json.

verify-green: Re-hashes the test directory before and after running the test command. It verifies that the target path and the command being executed match the exact witnessed receipt (preventing an agent from running verify-green --cmd true). Furthermore, the diff engine checks for any changes across three distinct states:
- ADDED:<file> (the agent added new tests to dilute coverage)
- DELETED:<file> (the agent erased a failing test entirely)
- MODIFIED:<file> (the agent tweaked an assertion)

If any of these occur without permission, it aborts immediately with exit code 2:

  {
    "ok": false,
    "error": "EACCES_TEST_TAMPERING: Test files modified during fix without renegotiation",
    "changes": ["MODIFIED:test_calc.py"]
  }

renegotiate: The answer to a question raised by Paul Lovelace: What happens when a test legitimately needs to evolve mid-fix? Rather than letting the agent slip edits into the test suite, it must run a formal renegotiation step with a mandatory --reason. This archives the entire chronological history of previous hashes, commands, and rationales inside the receipt, re-computes the Merkle seal, and demands that the new expectation fails on the current code before any fix is attempted.

It is bureaucratic on purpose. A few seconds of ceremony is cheaper than discovering at 2:00 AM that an agent "solved" a failing database constraint by quietly commenting out the foreign key check and leaving a cheerful # TODO: revisit later.

B. `distill`: Deterministic Output Compression & Process Tree Isolation

Instead of letting noisy test suites dump thousands of lines of terminal output into the context window, distill executes commands in isolated process groups (CREATE_NEW_PROCESS_GROUP + taskkill /F /T on Windows, start_new_session=True + os.killpg on POSIX) with a hard timeout. If a test suite hangs, the entire child process tree is forcefully killed—preventing orphaned processes from holding open stdout/stderr pipes indefinitely.

Execution output is piped through disk (logs/raw_<utc_timestamp>.log) while preserving the real subprocess exit code:

On success (exit 0), it returns a 5-line tail and notes the suppressed lines.
On timeout (exit 124), it kills the process tree and returns the last 15 lines before termination.
On failure, it extracts solely the critical delta: proportionally budgeting --max-lines between the first error (the root cause) and the final traceback frames while pruning intermediate log spam. In our automated test suite, 2,504 lines of log spam were compressed into 5 lines of actionable traceback.

C. `state`: Runlevels (`/etc/init.d/` on Disk) with Drift Detection

Inspired by Part 3.7 of Synthetic Scars, long-running tasks write discrete, ordered state files (00_plan.json, 10_build.json, 20_verify.json) atomically, replacing stale slugs on the same step number and recording SHA-256 hashes of generated artifacts. When an agent hits context compaction in long sessions, running python ag_ops.py state status reconstructs the ground truth in under 5 ms. Even better: state status actively inspects every referenced artifact on disk and flags DRIFT_MODIFIED, FILE_DELETED, or CORRUPTED_STATE_FILE warnings if any produced artifact or state record was mutated behind its back.

D. `ast-lint`: Millisecond Static Verification

Checks workspace Python code using the native ast parser:

TK001: Rejects positive and negative float font sizes in Tkinter/ttk (strictly scoped to font= arguments, avoiding false positives on canvas scrollregion).
TK002: Tracks AST Import and ImportFrom nodes to flag forbidden background= / foreground= (bg/fg) arguments strictly on themed ttk widgets—supporting import tkinter.ttk as ttk, from tkinter import ttk, and custom aliases without triggering false positives on standard tk.Frame or tk.Label widgets.
AUTH001: Verifies required authorship headers within the first 25 lines (configurable via --author).

Running ast-lint against a violation fixture took 1.07 ms. Scanning the entire ag_ops.py engine and its test harness took 18.6 ms.

3. What Went Wrong (And The Live Demonstration)

1. The agents died mid-flight

I initially delegated this refactor to two parallel subagents (one writing ag_ops.py, the other refactoring the rules). While both were writing files, they hit an API rate limit (429 RESOURCE_EXHAUSTED) and terminated without sending their completion handshakes.

Because the guardrails hadn't been fully verified yet, I couldn't trust the files on disk. I had to manually compare each modified file against its pre-upgrade backup hash, inspect diffs, and run the test suite by hand. Getting a live demonstration of why you need verifiable state files while building a verifiable state machine was humbling.

2. The Windows CP1252 trap

During the first automated test run of ag_ops.py, the suite failed abruptly on guard renegotiate. The logic was sound, but on Windows, child processes piped through Python defaulted to cp1252. When the renegotiation test passed an explanation containing the Spanish word "Ampliación", the accented ó broke the JSON decode stream.

The fix required explicit UTF-8 reconfiguration at both the CLI entrypoint and across every isolated subprocess pipe:

def main(argv: Optional[List[str]] = None) -> int:
    for stream in (sys.stdout, sys.stderr):
        if hasattr(stream, "reconfigure"):
            try:
                stream.reconfigure(encoding="utf-8", errors="replace")
            except Exception:
                pass

and inside _run_command_isolated:

kwargs: Dict[str, Any] = {
    "shell": True,
    "stdout": subprocess.PIPE,
    "stderr": subprocess.PIPE,
    "text": True,
    "encoding": "utf-8",
    "errors": "replace",
}

3. The backdoor in my own guard

During a strict code review of the initial Gist, I caught a glaring logic flaw in verify-green: it accepted any --cmd flag and didn't compare it against witness-red.

An agent could witness failure with pytest tests/test_calc.py, and then run verify-green --cmd "true". Because the test files were untouched and true exited with code 0, the guard happily granted VERIFIED_GREEN_WITH_MERKLE_LOCK without running a single test!

I patched it immediately: verify-green now locks onto both the witnessed test_target and the exact cmd string, rejecting any substituted command with exit code 2 (COMMAND_MISMATCH).

4. Hard Limits & The Obvious Hole in the Merkle Lock

The Circular Authority Hole

If an autonomous agent has unrestricted write access to the filesystem, it can theoretically edit ag_ops.py or overwrite merkle_guard.json to forge its own pass.

Right now, this Merkle lock is stricter by construction, not a cryptographic kernel boundary. It prevents the standard behavioral failure mode (an LLM taking the path of least resistance by editing assertions in tests/test_x.py to match its broken code), but it does not stop an adversarial agent with arbitrary shell execution. True isolation requires OS-level permission boundaries (mounting test harnesses as read-only or using dedicated sandbox containers).

The "Uninformative Red" Trap

As howcani pointed out in Randal's comment section: witnessed ≠ informative. While witness-red blocks collection, syntax, and CLI invocation errors (pytest exit codes 2, 3, 4, 5, and shell 126/127/9009), an unhandled runtime exception inside the test body (TypeError, AttributeError, or a broken fixture) still produces exit code 1—the exact same exit code as an AssertionError. A test failing for the wrong runtime reason can still fool the red check into issuing a receipt. A tighter version needs to inspect the assertion delta to ensure the test fails specifically on the expected invariant.

Scope Creep Outside `--test-dir`

ag_ops.py guard hashes --test-dir. If your repo relies on external fixtures, root-level conftest.py, or environment variables defined outside that path, an agent could mutate those files without tripping the Merkle lock. The tree hash must eventually cover the broader test harness manifest, not just a single directory.

The Scope of `ast-lint`

Our three rules run in ~1 ms, but let's be realistic: this is a lightweight style and framework compatibility check. It does not attempt to evaluate hundreds of complex rules across massive codebases, nor does it replace dynamic type checkers or memory safety tools. It simply moves recurring framework-specific quirks out of the prompt.

The Benchmark Reality

This is one developer's setup, not an industry benchmark. The 42.4% reduction reflects raw bytes of fixed prefix in my specific environment; bytes do not map 1:1 to token counts across different tokenizers. Furthermore, I have not benchmarked whether the agent solves tickets faster or with higher pass rates on smaller prompts—only that the physical guardrails now deterministically catch test tampering that Markdown prompts could only politely discourage.

The Takeaway

Markdown is where rules go to blur.

A natural-language prompt is probabilistic; a Merkle tree comparison aborts with exit code 2. A prose reminder costs tokens on every single turn; an ast-lint check runs in milliseconds.

My agent now reads 42% less boilerplate before it starts working, and the test guardrails are rooted in hashes rather than good intentions.

Acknowledgments & Credits

Randal L. Schwartz: For authoring the Synthetic Scars series, and demonstrating how Unix principles and compiler architecture beat prompt lawyering.
Paul Irolla: For the token-economics framework in his Claude Code Hooks analysis and his work on Tokenade.
Paul Lovelace: For asking the operational question on Merkle lock friction that led to the renegotiate workflow.
howcani, Sam LABBE, Vinnie Falco, and Ctbhatia: Whose commentary insights inside Randal's articles helped frame the distinction between sensors and steps, the trap of uninformative red tests, and the speed requirements of AST linters.

The full ag_ops.py CLI script, along with its MIT License and documentation, is available as a standalone GitHub Gist.

Why Traditional Excel Automation Fails with AI Agents (and How We Fixed It with Dual-Core Python)

Francisco Grandón — Sat, 10 Oct 2026 17:54:50 +0000

📢 Architecture Update (v1.0):

This article has been updated to reflect the latest release architecture: the inclusion of a Resident Windows Daemon with Named Pipe IPC (\\.\pipe\antigravity_excel), cold-start reduction to ~57ms via lazy loading, native financial modeling (pivot tables & non-overlapping charts), and our unified in-memory data curation pipeline.

When building autonomous AI agents, tool-calling sidecars, or background data pipelines that interact with enterprise spreadsheets, almost every developer hits the exact same wall: Excel automation libraries break down the moment they meet an AI agent.

Whether you are using LangChain, CrewAI, AutoGen, or building custom MCP servers, spreadsheets remain the undisputed lingua franca of business operations. But programmatically manipulating them in production environments often turns into an engineering nightmare.

In this article, we'll break down the three fundamental failure modes of traditional Excel libraries in agentic workflows and explore how a Dual-Core (Live COM + Headless) architecture resolves them.

💥 The Three Classic Failure Modes

1. The Interactive COM Lock (`RPC_E_SERVERCALL_RETRYLATER` / `0x8001010A`)

If you use classic win32com or xlwings, your script connects directly to Microsoft Excel via the Windows COM interface.

This works smoothly in isolation. But in a real-world enterprise workflow, humans look at spreadsheets while automations run. The exact second a human double-clicks into a cell or edits a formula, Excel enters an exclusive modal edit state. Any incoming COM call immediately crashes:

pywintypes.com_error: (-2147417846, 'The message filter indicated that the application is busy.', None, None)

Without an adaptive recovery mechanism, the entire AI agent execution loop halts.

2. Prompt Token Exhaustion from Verbose JSON

LLMs do not speak binary .xlsx. When an agent inspects a range of cells (say, A1:D50), traditional integrations serialize the grid into verbose JSON:

[
  {"row": 1, "col": "A", "value": "Revenue", "type": "string"},
  {"row": 1, "col": "B", "value": 154200, "type": "number"}
]

This structural overhead consumes up to 75% of the LLM context window on repetitive keys, quotes, and structural brackets. You pay higher inference costs, increase response latency, and risk truncating critical context.

3. The Live vs. Headless Dilemma & Zombie Processes

openpyxl is fast, portable, and runs completely in memory (headless). However, it cannot evaluate volatile formulas (=SUM(...), =VLOOKUP(...)) without Excel's calculation engine, nor can it provide real-time visual feedback to a user watching the screen.
win32com gives you dynamic calculation and real-time screen updates, but unhandled exceptions frequently leave hidden, hung EXCEL.EXE processes in background memory, permanently locking target files.

🚀 The Solution: Dual-Core Architecture

To bridge this gap, we engineered Antigravity Excel Engine: an open-source, AI-native Python engine designed specifically for autonomous workflows.

                  ┌─────────────────────────────────────────┐
                  │   Autonomous AI Agent / CLI Tool Loop   │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │ Named Pipe Active? (\\.\pipe\antigravity)│
                  └─────────┬─────────────────────┬─────────┘
                            │                     │
                  [Yes: Latency < 5ms]   [No: Instant Fallback]
                            │                     │
                            ▼                     ▼
                  ┌─────────────────┐   ┌──────────────────┐
                  │ Resident Daemon │   │ Antigravity Core │
                  │ (Warm COM / RAM)│   │  (Auto-Detect)   │
                  └────────┬────────┘   └─────────┬────────┘
                           │                      │
                           │             [Workbook Open?]
                           │              /             \
                           │         [Yes]               [No]
                           │           │                  │
                           │           ▼                  ▼
                           │   ┌───────────────┐  ┌───────────────┐
                           │   │ Live COM Core │  │ Headless Core │
                           │   │ (oleacc/undo) │  │  (OpenPyXL)   │
                           │   └───────┬───────┘  └───────┬───────┘
                           │           │                  │
                           ▼           ▼                  ▼
                  ┌─────────────────────────────────────────┐
                  │ Unified In-Memory Pipeline (Fast Matrix)│
                  │  - 1-Pass Curate, Dedup & Outliers      │
                  │  - Native Pivot & Non-Overlapping Charts│
                  │  - Formula Error Sentinel Audit         │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │ 📉 Token-Optimized CSV Streamer (-75%)  │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │ Verified Output / Agent Tool Response   │
                  └─────────────────────────────────────────┘

Key Engineering Pillars:

Auto-Switching Runtime: Probes the Running Object Table (ROT). If the file is currently open in Microsoft Excel, it engages Live COM for real-time recalculation, dynamic formula evaluation, and full Ctrl+Z Undo history. If closed, it automatically falls back to Headless OpenPyXL for raw server-side speed.
Resident Daemon & Named Pipe IPC: Keeps the COM session warm in memory via \\.\pipe\antigravity_excel, enabling sub-5ms latencies and up to 85x faster execution in repeated tool loops.
Self-Healing Cell Guardian: Wraps COM transactions with an adaptive exponential backoff loop that intercepts 0x8001010A errors, patiently waiting for human typing to finish instead of crashing the pipeline.
Token-Dense Streamer: Replaces bulky JSON structures with normalized, dense CSV streams, cutting prompt token consumption by up to 75%.
Unified 1-Pass Data Curation: Single-trip deduplication, cleaning, date serial repair, and outlier detection in memory (dropping latency from 4.7s to <500ms).
Financial Modeling & Presets: Native pivot tables, smart non-overlapping charts, and executive summary presets built directly into the engine.
Formula Error Sentinel: Automatically audits cell ranges for evaluation errors (#VALUE!, #REF!, #DIV/0!) before committing changes.

💻 Quick Implementation Example

Here is how straightforward it is to integrate into any agent or Python script:

from antigravity_excel_core import AntigravityExcelEngine

# Initialize (auto-detects Live COM vs Headless OpenPyXL)
engine = AntigravityExcelEngine(mode="auto", file_path="financial_model.xlsx")

# 1. Read token-optimized stream (ideal for LLM prompt context injection)
csv_stream = engine.get_range_as_csv("A1:D50")
print(csv_stream)

# 2. Declarative atomic updates (values, formulas, hex styles, and notes)
engine.set_cells({
    "A1": {
        "value": "Total Revenue",
        "cellStyles": {"fontWeight": "bold", "backgroundColor": "#0E2E63", "fontColor": "#FFFFFF"}
    },
    "B1": {
        "formula": "=SUM(B2:B10)",
        "cellStyles": {"numberFormat": "$#,##0.00"}
    },
    "A2": {
        "value": "Verified by AI",
        "note": "Audited autonomously via Antigravity Engine"
    }
}, autofit=True)

# 3. Sentinel audit for broken formula evaluations
errors = engine.check_formula_errors("A1:B10")
if errors:
    print(f"⚠️ Formula anomalies detected: {errors}")

# 4. Save and release cleanly (Zero zombie processes)
engine.save()

⚡ Blazing-Fast Resident Daemon & Named Pipe IPC

To push performance even further for high-frequency agent tool loops, Antigravity Excel Engine includes an optional Resident Windows Daemon (antigravity_excel_daemon.py):

Keeps COM Session Warm in RAM: Eliminates cold-start overhead and repeated process spawns by keeping Excel loaded in background memory.
Named Pipe IPC (\\.\pipe\antigravity_excel): Communicates with the CLI and agent runtimes over a duplex pipe with 16MB buffers, delivering sub-5ms ping latencies and operations up to 85x faster.
Instant Fallback: If the daemon is not running, the CLI seamlessly falls back to standalone execution (<1ms penalty) without crashing.
Unified 1-Pass Data Curation (curate): Executes deduplication, text trimming, type coercion, date serial repairs, and outlier detection in a single pass in memory and single COM trip, dropping batch latency from 4.7s down to <500ms.

🤖 Native CLI for AI Agents

Every feature is also exposed through a deterministic command-line interface with --json output, making it instantly pluggable into LLM function-calling tools:

# Start background daemon for ultra-low latency (<5ms)
python antigravity_excel_daemon.py --start

# Check engine status and active workbook
python antigravity_excel_cli.py status --json

# Extract dense CSV data for prompt injection
python antigravity_excel_cli.py get-csv A1:D50 --file "report.xlsx" --json

# Run unified 1-pass data curation (Dedup + Clean + Outliers)
python antigravity_excel_cli.py curate --source "A1:P700" --spec-json "{...}" --json

# Apply batch cell updates from JSON payload
python antigravity_excel_cli.py set-cells --input-file payload.json --autofit --json

🌐 Open Source & Community

Antigravity Excel Engine is completely open source under the MIT License.

⭐️ GitHub Repo: https://github.com/FranciscoGrandon/antigravity-excel-engine
🤝 Contributions: We welcome PRs, bug reports, and discussions on how to better connect agentic runtimes with desktop workflows.

If you are building AI agents that touch spreadsheets, check out the repository, give it a star, and let us know what other spreadsheet edge cases you are facing!