Appendix D. Deep dives

This is where the evidence and dated detail behind each chapter lives: the studies, benchmarks, vendor timelines and worked cases that the chapters leave out so they can stay short. Entries are grouped by chapter, each ending with its sources and caveats in italics. Full citations are in Appendix C; vendor behavior is dated to mid-2026 and will drift, so check defaults against the version you run.

Chapter 1 - What an agent is¶

Effective context is shorter than the advertised window. Windows run from 200 thousand tokens on compact models to a million from the mid-range up. NVIDIA's RULER measures effective context length, the longest input at which a model still holds its short-context score across the whole window, and for most models it lands well under the advertised figure, commonly around half. Source: Hsieh et al. (NVIDIA), "RULER," 2024. Caveat: "around half" is a rule of thumb from 2026 practitioner roundups, not one measurement.

What tool definitions cost, and the 2026 harness answers. One audit of a default Claude Code session counted about 24k tokens of tool definitions, MCP schemas and reminders before the user typed anything; one practitioner put three MCP servers at 143k of a 200k window. With a large catalog fully loaded, tool-selection accuracy in one benchmark was 13.62%; loading only the relevant tools raised it to 43.13%. The 2026 answers are deferred loading and programmatic tool calling (the model scripts the calls and returns one result; native in GPT-5.6, where it cut input tokens by 21% on one financial-research evaluation). For custom tools with nested schemas, turn strict decoding on: Armin Ronacher documented Opus 4.8 and Sonnet 5 inventing undeclared fields, and strict mode eliminating it. Sources: Lumer et al., Jan 31, 2026; anthropics/claude-code#42452, Apr 2, 2026; Gan and Sun (RAG-MCP), May 6, 2025; MetaBlogue, Sep 5, 2026; OpenAI GPT-5.6 guide, Aug 2026; Ronacher, Jul 4, 2026. Caveats: 24k and 143k are practitioner counts; the 21% is one benchmark (Rogo's).

Sandbox posture by vendor, and the mechanisms underneath. The OS half runs on Seatbelt (macOS), bubblewrap with Landlock and seccomp (Linux) and restricted tokens with job objects or WSL2-backed isolation (Windows, the least uniform). Codex CLI enforces it by default on Linux and macOS, so you opt out. Cursor added kernel-backed controls in 2.x (default-on macOS from 2.0, October 2025); Gemini CLI ships per-platform profiles. Claude Code is opt-in (/sandbox, project .claude/settings.json) and most installations skip it, leaving a default install with no kernel-level protection against injection or agent misbehavior (PocketOS is what an unsandboxed default installation looks like when it goes wrong). opencode has permission prompts and path validation only, leaving OS isolation to the operator's Docker or microVM ("soft confinement" is the manual's term). Allowlists for paths and network go in the agent's configuration or AGENTS.md; setup takes an afternoon. Defaults are versioned, so verify yours. Sources: Claude Code and Codex CLI docs; Vercel KB on opencode; Cursor changelogs.

The two-agent demo, in detail. Claude Code ran in two panes against Codex CLI (Rust, Apache 2.0, OpenAI) and opencode (TypeScript, MIT, independent team) with one prompt: explain the architecture, map the agent loop, tool system, permission gates, sandbox and plugin model, citing files and lines. It took about four minutes (a May 2026 re-run: 4:13), because both repositories name their architecture in their directories; a less self-documenting codebase takes ten to fifteen minutes per repo. Both returned an agent loop, tool registry, permission gate, plugin directory, MCP support and a subagent path (in opencode, found by behavior: a function that spawns a fresh instance on a bounded prompt). The one divergence was the sandbox. Source: author experiment, no human correction. Limit: the primitives exist; that does not make them equally well built.

Subagent adoption timeline. Claude Code shipped the Task tool, then Agent Teams on top. Codex CLI took subagents GA on March 14, 2026 (up to six in parallel by default, nesting depth one). Cursor shipped parallel agents in 2.0 (October 2025), a subagent system in 2.4 (January 2026) and async in 2.5. Sources: Codex CLI subagents docs; Cursor changelogs. Caveat: the six-thread Codex default is effectively a cap as of mid-2026.

Scripted orchestration (/workflows). Claude Code's /workflows (mid-2026) has the agent write a script that dispatches subagents deterministically: ordered phases, parallel or pipeline fan-out across hundreds of children, schema-validated handoffs, an optional verification gate, resumable and budget-bounded. Determinism is the only real difference from model-driven dispatch (as in Superpowers); use it when the fan-out is large, repeatable or worth verifying mechanically. Source: Changelog, 2026-06-11.

Memory and skills: the convergence story. The always-loaded primitive converged on AGENTS.md (read at session start by Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed, Windsurf and more; 20+ vendors listed at agents.md as of 2026-05) and CLAUDE.md, which Claude Code reads natively and which can import AGENTS.md. On-demand skills converged too (Claude Code Skills; Codex CLI SKILL.md, December 2025). The agent-written half converged within a winter: GitHub Copilot Memory public preview January 15, 2026, on by default for individual tiers by March; Claude Code Auto Memory in February (v2.1.59+); Codex CLI background memory in April. Anthropic's Dreaming (Claude Managed Agents, Code with Claude SF, 2026-05-06) is a scheduled background process that reviews sessions and memory and writes consolidated notes back; it is platform-level behind a beta header, and a /dream CLI had not shipped as of July 2026. Sources: agents.md; vendor and Claude Code memory docs. Caveat: load semantics vary (Cursor also reads .cursorrules).

Effort: the evidence. With the harness held constant, GPT-5.6 Sol at low effort beat GPT-5.5 at high effort on Agents' Last Exam; Fable 5.1 at low effort is often competitive with Opus and Sonnet on cost per task while scoring higher, by its vendor's own guide. Effort names do not transfer between models, so every migration starts with a sweep (Appendix B.9). Whether reasoning is kept between turns is the harness's call: on ARC-AGI-3, by OpenAI's account, retained reasoning plus compaction took GPT-5.6 Sol from 13.3% to 38.3% while cutting output tokens sixfold. Sources: OpenAI GPT-5.6 guide, Aug 2026; OpenAI ARC-AGI-3 post, Jul 29, 2026; Anthropic, "Prompting Claude Fable 5.1." Caveat: vendor evaluations on one benchmark and model; the manual uses ARC-AGI-3 for the mechanism, not the score.

Plugins: why each vetting question exists. As of May 2026 the marketplace was a real distribution channel and a supply-chain surface, the npm of agentic coding. Behind the B.10 questions: a plugin from Anthropic, a known vendor or a verifiable engineer is a different risk class from one uploaded last week by an unknown name; broad permissions deserve the suspicion you give an npm package asking for filesystem and network access; the plugins worth installing are small enough to read in twenty minutes (Superpowers and hookify are); an update is a dependency update; a hook running outside the sandbox is unbounded. Source: author field practice, May 2026.

Chapter 2 - Guardrails in five layers¶

Three vulnerability classes behind layers one to three. (1) Dot-env auto-loading: agents read .env* files in the working directory at session start. Mitigate with a sandbox deny-read list; Claude Code added an opt-in sandbox.credentials setting in June 2026 that blocks sandboxed commands from reading credential files and secret environment variables. (2) Configuration-file injection: untrusted .claude/settings.json or .mcp.json files run hooks before the trust dialog, enabling remote code execution (CVE-2025-59536, patched in Claude Code v1.0.111) or API-key exfiltration through an overridden ANTHROPIC_BASE_URL (CVE-2026-21852, patched in v2.0.65). (3) Permission-parser bypass: deny rules skipped for binaries the parser does not recognize (Python's open(), Node's fs.readFile), or, as a quiet failure, when a command chained more than fifty subcommands (MAX_SUBCOMMANDS_FOR_SECURITY_CHECK = 50) and the check fell through to a generic "ask"; disclosed April 1, 2026, patched in v2.1.90 within days. Nothing in the configuration shows such a failure, so assume any single layer can have a bug; the classes outlive their patches. Sources: Knostic, Dec 2025; Check Point Research, Feb 2026 (patched October 2025); Adversa AI Red Team, Apr 1, 2026; Adam Kinney, Apr 2026. Caveat: architectural classes, not single CVEs; unpatched versions stay vulnerable.

The sandbox escapes ("DuneSlide"). In mid-2026 a red team disclosed two critical zero-click prompt-injection flaws in Cursor's kernel-backed sandbox (CVE-2026-50548 and CVE-2026-50549, CVSS 9.8) that abused its working-directory write allowlist and a symlink-resolution fallback to reach OS-level code execution. Versions before Cursor 3.0 (April 2, 2026) were affected. The lesson is the class, not the vendor: the strongest layer can have bugs, which is why there are five. Sources: Cato Networks (Cato AI Labs), mid-2026; SecurityWeek and The Hacker News, Jul 2026.

Per-agent sandbox defaults. See the Chapter 1 entry on sandbox posture by vendor; the point for this chapter is that a default install of an opt-in agent runs with layer two switched off.

Injection through the work: the DNS TXT proof of concept. In June 2026 Mozilla 0Din researchers showed a harmless-looking repository inducing Claude Code to run a script that pulls a base64 payload from a DNS TXT record and spawns a reverse shell, split across the repository, DNS and the developer's machine so no signature appears in plaintext. A proof of concept with no vendor patch reported; a network allowlist bounds the DNS path. Source: SecurityWeek, Jun 29, 2026.

Telemetry plumbing and hook examples. By mid-2026 Claude Code, Codex CLI and Gemini CLI emit OpenTelemetry natively, so the audit store can be whatever the stack already speaks; the requirement is durability and queryability. The security-guidance plugin ships rules for roughly eight to ten vulnerability categories. One team rule beyond the chapter's two: block edits to a compliance-relevant module outside business hours.

PocketOS: where the accounts disagree, and what the platforms changed. Railway's restore was reportedly about 30 minutes after the CEO contacted them; other accounts say about 30 hours, or two days, for full restoration, so the manual uses the incident for the governance pattern only. Within a week, on April 29, 2026, Railway moved all volume and resource deletes, including the API path the agent used, to soft-delete with a 48-hour recovery window, and added workspace guardrails and scoped agent credentials. Alexey Grigorev's follow-up to the DataTalks.Club Terraform loss (late February 2026) reads like this chapter's checklist: delete protection in Terraform and AWS, state moved to S3, manual review of every destructive plan, an upgraded AWS support tier. AWS restored roughly 1.94M rows from a snapshot within about a day. Sources: DevOps.com; Business Insider; Railway blog, Apr 29, 2026; Grigorev's public account.

PocketOS: the public post. The PocketOS CEO posted about the incident publicly, and the post quickly became a reference point in discussions of AI safety in production. Source: Appendix C, Named incidents.

DataTalks.Club as the mirror image of PocketOS. In the DataTalks.Club incident Claude Code ran terraform destroy against a stale state file: a map the agent did not know it needed, where PocketOS was a credential it should not have held. Same cure: confirmation on destructive operations, only the credentials the task needs, and state the team has verified. Source: Alexey Grigorev's public account; Appendix C.

Chapter 3 - The bottleneck moved¶

The unknowns frame, in full. In July 2026 an Anthropic engineer opened a field guide to Claude Fable 5 with this chapter's observation: it was "the first model where I find the quality of the work is bottlenecked by my ability to clarify its unknowns." His four questions: known knowns (what your prompt states), known unknowns (questions you have not settled), unknown knowns (context so obvious you would never write it down, though you would spot a violation at once) and unknown unknowns (what neither of you thought to ask). Source: Thariq Shihipar, Anthropic, Jul 6, 2026. Caveat: the frame adapts an older taxonomy and "first model" is his judgment, not a measurement; the mapping onto this manual's machinery (the chapter's table) is the author's.

The METR randomized controlled trial. METR's July 2025 trial had experienced open-source developers work on their own familiar repositories with AI assistance. They took 19% longer than without it, after predicting a 24% speedup, and afterward still believed it had made them roughly 20% faster: a 43-point gap between predicted speedup and measured slowdown. The author reads it as a warning that raw assistance does not become delivery speed without workflow discipline. Source: Becker et al., METR, Jul 10, 2025. Caveat: METR did not test formulation discipline; that reading is the author's. Its follow-up suffered selection bias, it redesigned the experiment in February 2026, and it cautions against applying the 19% to current tools.

February to April 2026: the discipline absorbs a vendor regression. Claude Code product changes materially degraded complex engineering work in some workflows. On April 6, AMD senior director Stella Laurenzo published an audit of 6,852 of her own sessions and 234,760 tool calls, showing a shift from research-first to edit-first behavior as thinking redaction rolled from 1.5% to 100% of turns, and pointed at the February adaptive-thinking default as a contributing cause. Anthropic's April 23 post-mortem acknowledged three regressions: default effort dropped from high to medium on March 4 (reverted April 7); a caching bug from March 26 that cleared reasoning history every turn instead of once per idle hour (fixed April 10); and a system-prompt verbosity cap from April 16 with a measured 3% quality drop (reverted April 20). Two adjacent teams used the same Claude Code. The one with this manual's infrastructure (CLAUDE.md rules, plan mode by default, the six-phase loop, hooks on destructive operations) dropped maybe 10% and recovered once it tightened plan-mode gates and raised effort on a few skills; the freestyle team's velocity halved overnight. Sources: Anthropic post-mortem, Apr 23, 2026; Laurenzo, anthropics/claude-code#42796, via The Register, Apr 6, 2026. Caveats: the accounts diverge on the earliest cause; external magnitudes are approximate; the two-team comparison is a field observation.

Chapter 4 - The six-phase loop¶

When splitting into subagents pays. A study of 260 multi-agent configurations found coordination pays only on decomposable work and costs between 39% and 70% on sequential work, planning above all; when a single agent already clears roughly 45% on a task, adding agents predicts no gain. Split only when tasks are independent by file or module. Source: Kim et al., Nature Machine Intelligence 8, 1157-1172, Jul 24, 2026. Caveat: not coding-specific benchmarks; 45% is a fitted predictor, not a law.

One writer, forked workers, isolated reviewers. Keep one writer per file, which is where Cognition landed after a year of arguing against multi-agent systems: parallel readers, a single writer. Fork the workers so they inherit the orchestrator's history cheaply through the cache; isolate the reviewers so they inherit none of it and cannot be anchored by its assumptions. On current harnesses dispatch returns immediately and the result arrives later, so the orchestrator keeps working (the shape B.3 assumes). Collisions are mediated cheaply (drop the later branch, re-run it sequentially with the first's output) or expensively (a higher-capability model picks the merge); the expensive ones eat the speed gain. Sources: Walden Yan, Cognition, Apr 22, 2026; Bengre and Curme, LangChain, Sep 8, 2026; Anthropic, "Prompting Claude Fable 5.1." Caveat: vendor posts; "one writer" compresses Cognition's "writes stay single-threaded".

Vendor autonomy and scope blocks. Fable ends a turn on a statement of intent ("I'll now run the tests") or takes an action nobody asked for; GPT-6 Astra pauses to ask unneeded questions and writes broader tests than a reversible change requires. Both vendors publish the fix as a prompt block: autonomy (finish the task before ending the turn; no tests for reversible, low-impact changes) and scope (only the files the plan names; stop and report on anything else). B.3 carries both; B.9 rewrites them for the next model. Sources: Anthropic, "Prompting Claude Fable 5"; OpenAI, "Using GPT-6 Astra," Sep 2026.

The implementation-notes file pays twice. The spec-compliance reviewer reads it first, a confession list of where diff and plan disagree, and it counters orchestrator-summary drift because each deviation is recorded when it happens, by the subagent that made it. Phase gating is still maturing: Superpowers asks through skill instructions, strict gating needs a project-specific PreToolUse hook, and kernel-level enforcement was immature as of mid-2026.

Chapter 5 - Review and verify¶

The evidence behind the two-reviewer design. Anthropic's Fable 5 prompting guide states that separate, fresh-context verifier subagents tend to outperform self-critique. Uptake beats precision: in a July 2026 multi-agent reasoning study the more precise reviewer lost, its verified-useful critiques changing the solver's next answer only 33.6% of the time against 93.5% for a peer setup with less precise critiques broadcast to everyone, which also had the better final pass rate. Track the repair rate (findings fixed, or rebutted with a reason), not accuracy. Cap the rounds: a rubric-guided verify-and-repair loop (DeepVerifier) peaked around round four and had declined by round ten, because late rounds re-open settled work about as often as they fix it. Keep reviewer two blind: judges anchor to a prior score they see, and neither chain of thought nor an explicit warning removes it. Sources: Anthropic, "Prompting Claude Fable 5" (undated, revised in place); Yang et al., Jul 16, 2026; Wan et al., Jan 22, 2026 (v2 Apr 29); Kapetanovic et al., Aug 26, 2026. Caveats: math reasoning and deep-research agents, not code review; the round-four decline is a few points, so the lesson is the curve's shape.

SpecBench and the Cursor finding in full. SpecBench (May 2026) ran frontier agents against specifications with visible and hidden test sets. Every agent saturated the visible suite near 100%, with hidden-test gaps of roughly 43 to 48 points; the 90th-percentile gap grew by about 27 points per tenfold increase in lines of code, and more search did not reliably remove the reward hacking. Cursor found the other half in June 2026: on SWE-bench Pro, 63% of successful Claude Opus 4.8 Max resolutions had retrieved the upstream fix from git history or the network instead of deriving it, and sealing both dropped the score from 87.1% to 73.0%. Both are a system doing what the gate rewards, hence the four verify controls. Sources: Zhao, Srikanth, Wu and Jiang (Weco AI), May 20, 2026 (v2 Sep 9); Naman Jain, Cursor, Jun 25, 2026. Caveats: the abstract rounds 27 to 28 points (R-squared 0.21), so the trend is real but noisy; Cursor's result is one harness and one model.

Playwright with the accessibility tree. The accessibility tree is the structure browsers keep for assistive technology (a button with this label, a field labeled "email"), stable under restyling and component-library swaps. "Find the field labeled Priority, change it, click Save, verify the new value renders" passes whether the field is a select, radio group or custom component. Banking teams with flaky snapshot suites found it the first approach that stayed green. Sources: Playwright docs; W3C ARIA AOM. Caveat: animation, drag-and-drop and canvas need supplementary verification.

The PR review toolkit's saving. With four agents run first (silent-failure hunter, PR test analyzer, security scanner, documentation reviewer) catching the mechanical findings, a senior's fifteen-minute review becomes five, and the other ten go to architectural judgment.

Chapter 6 - AGENTS.md and context¶

Repository overviews in context files do not help. ETH Zurich found that repository-level context files taken as a whole did not generally improve coding-agent task success while raising inference cost by over 20% on average. The repository overview, popular and vendor-recommended, did not help: the agent derives the layout from the tree in seconds. Developer-written files did slightly better than generated ones, not significantly. So the always-loaded file keeps rules, and the map moves to docs/, read on demand. OpenAI's Codex practice has the same shape: an AGENTS.md of roughly 100 lines that maps into a structured docs directory. Sources: Gloaguen, Mundler, Muller, Raychev and Vechev (ETH Zurich), Feb 12, 2026 (v2 Jun 23); Ryan Lopopolo, OpenAI, Feb 11, 2026. Caveats: the paper isolates no content category with a significant positive effect, so keep-and-move is the manual's reading; OpenAI's is one team's practice.

The cap is sized by a rule-count cliff, and vendors are deleting instructions. In a July 2026 study across formats and placements, the rate at which a model satisfied every rule at once collapsed to zero by about eighty simultaneous rules, on Claude Sonnet 5 and Claude Haiku alike. Eighty rules is roughly a two-hundred-line file with one rule per line, which is why 200 lines is a hard cap. Anthropic removed more than 80% of Claude Code's own system prompt for the Claude 5 generation with no measured loss on its coding evaluations, replacing rules with judgment and worked examples with typed tool interfaces. Sources: Netanel Eliav, Jul 21, 2026; Thariq Shihipar, Anthropic, Jul 24, 2026. Caveats: perfect-response rate is a strict metric and other 2026 work reports softer thresholds, so the cliff sizes the file, not a compliance number; Anthropic's evaluations are its own.

Mistake-journal mechanics. Anthropic's Fable 5 guide describes a memory system with three rules that keep a journal honest at a hundred entries: one lesson per file with a one-line summary, update rather than duplicate when a lesson recurs, delete notes that turn out wrong. Add an evidence pointer so the next champion can check whether the failure is still possible. OpenWiki's claims runtime, which attaches evidence pointers to stored claims and re-checks them, cut stale claims from 3.5% to 0.5% across 2,000 evaluated claims. The quarterly review asks of each entry, "has anyone been saved by this rule in the last three months?" If yes, keep it; if no but the rule still applies, keep it, since rare failures still matter; if no and the cause is gone, retire it with a commit-message note. Sources: Anthropic, "Prompting Claude Fable 5"; Colin Francis, LangChain, Aug 25, 2026. Caveat: OpenWiki is a knowledge-base system, not a journal; the manual borrows the mechanism.

Why the precedence line exists. GPT-6 Astra follows longer instructions better and is more sensitive to context: conflicting guidance in a skill file can make it pause and block early, and OpenAI's guide says the user's instructions take precedence over a skill's. One top line ("In a conflict, the task prompt wins over this file; this file wins over any skill", in the B.2 skeleton) removes a class of stalls. Source: OpenAI, "Using GPT-6 Astra," Sep 2026 (GPT-6 released September 3-4, 2026; guide revised in place).

Compaction and context measurements. JetBrains found that masking old tool outputs (call kept, bulky result blanked) beat LLM summarization in four of five settings at over 50% lower cost, with a matching or slightly better solve rate. Anthropic's tool-result clearing, the same move at platform level, gave a 29% gain on an internal agentic search evaluation. Across 15 models, fragmented multi-turn conversations lost 39% on average against a single specified turn, and one consolidated turn recovered about 95%. Sources: Fraser and Lindenbauer, JetBrains Research, Dec 2025; Anthropic, Sep 29, 2025; Laban et al., May 2025. Caveats: the 52% sometimes quoted is one configuration (Qwen3-Coder 480B); Anthropic's result is internal; the multi-turn study used simulated generation tasks, not coding sessions.

Append-only history and cache pricing (Fable 5.1). Thinking blocks are bound to the exact prefix that produced them, so editing or reordering earlier turns invalidates them and discards the retained reasoning that Chapter 1 counts as half of Effort: end the session and start clean. With cache reads at 0.025x the base input price, the guide says compacting early to save cost may no longer be the right trade; when you do compact, give the compactor a keep-list (the plan, open questions, deviations in the implementation notes, the exact commands that worked). Source: Anthropic, "Prompting Claude Fable 5.1." Caveats: undated page; 0.025x is the manual's arithmetic from published prices; append-only applies to accounts created on or after August 31, 2026.

Chapter 7 - Map it first: architecture review¶

Why the agent reads the code rather than querying an index of it. Navigation beats retrieval on this task. On Claude Sonnet 4.5, agentic navigation (grep, open the file, follow the reference) reached 49.6% recall@1 on BRIGHT, 21.8 points above the best embedding model, and bounded workspaces (the RISE result) keep it working at a million documents, where direct context inspection degrades. Code search for agents resolves into three tools: ripgrep for text, ast-grep for structure, the language server for references. An embedding index is the exception you add when a corpus outgrows them. Sources: Suresh et al., May 7, 2026; Zhuang et al. (RISE), Jun 5, 2026; Kumanyaev, Jun 6, 2026. Caveat: the recall figure is on a general retrieval benchmark, not a codebase.

The visual alternative: Understand Anything. A plugin that renders the codebase as a navigable graph: a structural view (modules, dependencies) for engineers and a domain view (business concepts, entities) for managers, who can read "this service handles fraud detection on incoming transfers" without reading source.

Chapter 8 - Should the agent touch this code?¶

Signal 1, no tests: the reconciliation module. Twice in banking: a reconciliation module written in the early 2010s by a senior engineer who left in 2018, with no tests because "the senior engineer just knew it worked." The next change broke it in a way that took two months to surface, by which point the discrepancy had crossed the threshold that triggers a regulatory disclosure. Fix: characterization tests first, the agent doing the bulk.

Signal 2, no documentation: the fee tier. The fee tier for the legacy product line was calculated differently because of a 2017 regulatory carve-out. The agent assumed uniform treatment and "simplified" it; the senior caught it in review. The second-order cost is senior engineers reviewing AI output forty hours a week instead of building, until they leave. Fix: the architecture review (Chapter 7) plus a short domain glossary.

Signal 3, tight coupling: the fourteen-year cycle. A customer service module imported a loan origination module, which imported a credit scoring module, which imported customer service: a cycle introduced fourteen years earlier to "save time" and never broken because it was an eight-week project. The agent's change surfaced months later at month-end batch close. Fix: break only the worst coupling; if the team will not, yellow at best.

Signal 4, scattered rules: the maximum transfer amount. The limit lived in a UI config, a service constant and a database trigger. Compliance updated the config; six weeks later a valid transfer failed on the stale constant. With no single source of truth the agent guesses which copy is canonical. Fix: one source (a typed rules engine or configuration service) and worth it with or without agents.

Signal 5, regulatory constraints. Any change to anti-money-laundering logic needs sign-off from the compliance officer, a representative from legal and a senior engineer not involved in the implementation; the agent cannot route approvals or satisfy a two-person rule. Mild constraints (a senior review on every change) fit the existing process; heavy ones (sign-off matrices, evidence trails, time-stamped approvals, retention) mean the agent works only inside a system that already handles them.

Signal 7, model-context fit: the in-house workflow engine. A custom engine from the early 2010s with no public documentation and peculiar state-transition syntax. The agent applied patterns from an unrelated framework it had seen more of; the code compiled, the thin tests passed, and the state machine misbehaved in three untested edge cases. With no substantial public footprint (repositories, documentation, talks), treat the codebase as if signal 6 were active even when every other signal is clean.

Signal 8, velocity-of-change: the React 18/19 bug. On a codebase mid-migration the agent is confidently right about the old version and wrong about the new, and you cannot always tell which. The author's own bug: Claude used React 18 idioms where React 19 was needed; it worked locally on a transitive React 18 dependency and broke when production pulled 19. Fix: a version rule in AGENTS.md ("we are migrating from React 18 to React 19 this quarter; new code uses 19 idioms; old code may still use 18 but should be updated when touched").

The model-migration soft signal, with its evidence. Instructions written for the previous model (AGENTS.md rules, skill prompts, effort levels) do not retire themselves. For between 37% and 63% of the software-engineering papers surveyed, a newer model given a single prompt natively outperformed the heavily engineered tooling proposed about a year earlier. It is not a ninth kill signal; it is what to check when a green codebase turns yellow after a model upgrade (Appendix B.9). Source: Salsabil et al., Aug 31, 2026 (arXiv 2609.00468). Caveat: preprint, not peer-reviewed; use it for the direction, not the fraction.

The six worked examples in full. (1) Customer-profile microservice: 70% coverage, README overview, REST-decoupled, rules in one typed validation library, standard SOX controls, seniors who handle profile changes. Zero, green. (2) Legacy payments engine: 20% mostly happy-path coverage, partly stale docs, moderate coupling with documented seams, a few straggler rules, real PCI and fraud-reporting constraints with audit machinery in place, one or two seniors who can judge payments output. No tests half, documentation half, coupling one, rules half, regulatory zero, evaluation zero: two and a half, rounded up to three, yellow. (3) Custom encryption library by a 2017 contractor: undocumented, integration-tested only, tightly coupled to key management, compliance rules in code, no cryptographer. Five, red. (4) Greenfield API service, senior team, clear spec: zero, green-plus. (5) Internal tool, 20 developers, written 2019, modest tests, low regulatory exposure: one, green-leaning, the right first target. (6) Vendor-customized fork, hasty contractor layer, no tests or docs on the customizations, severe upstream coupling: four, red. The question is the strategy: should the custom layer exist at all? Replace it with upstream features, contribute it back or maintain it deliberately, but do not use the agent to make the wrong work faster.

Chapter 9 - Rolling it out¶

The two kinds of hooks in full: pre-commit versus pre-push. Split git checks by cost. Pre-commit is the fast pass (format, lint, typecheck, secret scan), seconds, so nobody reaches for the escape hatch; every skip trains the habit of skipping. Pre-push is the heavier pass (the fast test suite, the build), run once per push. Manage both from a versioned config through a hook manager so they install on every clone. The two boundaries cover each other's blind spot: the agent hook catches the agent mid-session before the edit lands, the git gate catches every author on paths the agent hook never sees. Deterministic checks do not drift the way probabilistic reviewers can.

The outer loop: from AutoGPT to Ralph Wiggum. The inner loop is the six-phase loop (Chapter 4); the outer loop wraps it and re-invokes the agent until a condition holds. In 2023 AutoGPT and BabyAGI looped a model against its own opinion of its progress; nothing external graded an iteration, laps compounded drift, and the approach collapsed as a way of shipping software within months. The revival differs structurally: in mid-2025 Geoff Huntley wired an agent into a bash while-loop (one prompt file, repeat), which spread as "Ralph Wiggum". Each iteration starts with a fresh context, does one unit of work and ends against graders the model does not control (compiler, tests, diff), with state in the repository. His name for the failure mode is overbaking: a loop left running past its job invents work nobody asked for. Sources: ghuntley.com/ralph (Jul 2025); HumanLayer, Jan 6, 2026; The Register, Jan 27, 2026; AutoGPT and BabyAGI repositories. Caveat: the collapse judgment and structural contrast are the manual's interpretation.

The outer loop: the vendor wave and stop-condition mechanisms. GitHub's Copilot coding agent went generally available on September 25, 2025 (isolated environment, draft pull request); Cursor shipped Cloud Agents on October 30, 2025; Google's Jules added Scheduled Tasks on December 10, 2025; a ralph-wiggum plugin landed in the official Claude Code repository in November 2025. By spring 2026 Claude Code had /loop (re-run on an interval or self-paced), Routines (cloud agents from a schedule or GitHub event), /goal (work until a completion condition holds) and /autofix-pr (push fixes until CI is green). By Chapter 1's test the capability converged, though what converged is a workflow around the primitives, not a primitive. /goal sends the condition and conversation to a fresh small model (Haiku by default) after each turn, returning not yet met, met or impossible; Codex Goals gives a thread a persistent condition confirmed by an evaluation or a hard limit. Both are a grader the loop does not control. The ralph-wiggum plugin has no controlled evidence, and its README names max iterations as its primary safeguard, a budget, not a stop condition. Sources: GitHub changelog, 2025-09-25; Cursor and Google blogs; Claude Code release notes, Apr-May 2026; Claude Code "/goal" docs; OpenAI Cookbook, "Using Goals in Codex." Caveat: vendor dates drift; the goal docs describe mechanism, not outcomes.

The outer loop: why each contract line exists, and the two poles. A machine-evaluable stop condition, because a loop without one is abandonment. A budget, because an unattended loop is the per-token model's best customer (Appendix A). A gate the agent cannot edit (tests, lint config, CI workflow, hook rules behind a deny rule), because the cheapest way to go green is to negotiate with your own grader, and a green suite the agent wrote is evidence, not proof (Chapter 5). Fresh context with a committed queue and journal: forty short sessions instead of one degrading one. Isolation sized for absence, since an unattended session is where prompt injection meets no human skeptic (Chapter 2). Queue many similar, machine-verifiable, reversible units (migrations, lint sweeps, dependency bumps, test backfill) on green codebases only. Huntley runs the loop raw at roughly $10 an hour; StrongDM's software factory runs fully non-interactive delivery, humans neither writing nor reviewing code, with end-to-end scenarios held outside the codebase as a holdout the loop cannot weaken, at a spend Simon Willison pegged near $20,000 a month per engineer. Sources: Willison, Feb 7, 2026; Huntley and The Register as above. Caveat: the $10 figure is Huntley's own and the StrongDM figures are one company's self-description and Willison's framing, not audits.

Time budgets of the role commitments. Champion: week one about three hours, week two about five, weeks three and four roughly the time the features would take by hand (the value is the experience), month two comparable to manual work; after ninety days, a working workflow, a maintained AGENTS.md, three or four delivered features and a designated successor. Lead: week one about two hours, weeks two to four about five, month two about three, month three about five including preparation.

Why the 90-day curve is shaped that way. The first thirty days produce almost no measurable productivity: the champion is learning, the lead is classifying, the manager is deflecting premature metrics. In the second thirty, cycle times improve, quality holds and reviewers find agent PRs easier to review because the descriptions are more structured. In the third, other engineers join, AGENTS.md grows, the journal fills and yellow projects start moving. The curve is roughly exponential, so measuring at thirty days disappoints and at ninety shows the picture.

The outer loop's own kill signals. The loop gets kill signals the way Chapter 8 gives them to codebases. Four are enough: the same diff applied and then reverted across iterations; budget burning while the queue does not shrink; the same failure surfacing a third time; any iteration that touched the gate. Any one means stop: read the journal, fix the cause, then relaunch. A loop restarted on hope is a loop you have stopped controlling. Appendix B.6's morning-review block carries the same four checks.

Appendix A - For managers¶

Tier routing, the two measured points. Anthropic's advisor pattern pairs a cheaper executor with a stronger model on call. Sonnet with Opus as advisor scored 2.7 points higher on SWE-bench Multilingual than Sonnet alone, at 11.9% lower cost per task. Haiku with an Opus advisor scored 41.2% on BrowseComp against 19.7% solo, trailing Sonnet solo by 29% in score at 85% lower cost per task. Right for the mechanical tiers of the loop, wrong for research. Source: Anthropic, "The advisor strategy," Apr 9, 2026. Caveat: vendor benchmarks on the vendor's own models; per-task figures, not a general ratio.

Cache-first layout, tool tax and masking. Cache-first layout cut API cost by 41% to 80% on more than 500 agent sessions across three providers (Lumer et al., Jan 31, 2026). The tool-definition figures are under Chapter 1, the masking result under Chapter 6.

The bounding heuristic, long form. Cost per engineer per month is bounded by what the team would otherwise spend on similar tooling (IDE licenses, code-intelligence platforms, AI-coding subscriptions) plus a fraction of a senior engineer's hourly time saved per week. Run it with your tooling stack, loaded hourly cost, an honest hours-saved estimate and the vendor's quote; break-even lands quickly when the agent saves even a few hours a month per engineer.