docs: sync metadata; add self-test methodology; refresh README/architecture/glossary/anti-patterns

- README: bump counts (15->19 conduct, 9->12 engines, 14->21 codes, 4->8 recipes), add 'Pick the modules' selector, recipe table, resolved structural decisions section
- docs/architecture: bump layer-table counts, add runbooks/ row, F15+ -> F22+ in stability commitments
- docs/self-test: A/B fixture methodology + per-module inventory (0 of 19 shipped, honest)
- glossary: add 7 new terms (Turn of Flip, Number of Flip, All-Add, DFA, Awareness code, Axes, BamlError)
- anti-patterns: Conduct (recent additions) section with 6 cross-cutting items; F15+ -> F22+

Author: klaiderman

README.md

@@ -26,26 +26,28 @@ The fixes for these are well-known to people who've shipped agents at scale. The
 
 ```
 agent-foundations/
-├── conduct/      ← 18 behavior modules: discipline, context, verification,
+├── conduct/      ← 19 behavior modules: discipline, context, verification,
 │                   delegation, tool-use, formatting, skill-authoring,
 │                   hooks, precedent, tier-sizing, web-fetch, failure-modes,
 │                   doubt-engine, memory-hygiene, cost-accounting,
 │                   refusal-and-recovery, latency-budgeting,
-│                   eval-driven-self-improvement
+│                   eval-driven-self-improvement, multi-turn-negotiation
 ├── engines/      ← 12 algorithmic primitives: Aho-Corasick, Shannon entropy,
 │                   Beta-Bernoulli, Markov drift, Hunt-Szymanski LCS,
 │                   Zhang-Shasha tree edit, Tarjan SCC, Wald SPRT,
 │                   Jaccard-Cosine boundary segmentation, LLM Bandit,
 │                   Agentproof, Calibration
-├── taxonomy/     ← 21 named failure codes (F01–F21), one doc per code,
-│                   with signature, counter, examples, escalation,
-│                   plus multi-agent and alignment-failure clusters
+├── taxonomy/     ← 21 named failure codes (F01–F21) + axes.md (5-axis
+│                   hybrid mapping: memory / reflection / planning /
+│                   action / system) — flat for ops, axes for review
 ├── runbooks/     ← 21 incident-response runbooks (one per F-code) with
 │                   Detect / Triage / Rollback / Post-incident steps
-├── recipes/      ← Adoption guides for Claude Code, OpenAI Agents SDK,
-│                   Cursor, generic system prompt, and eval harnesses
+├── recipes/      ← Adoption guides for 8 hosts: Claude Code, OpenAI
+│                   Agents SDK, Cursor, generic system prompt, LangChain,
+│                   Pydantic-AI, BAML, plus an eval-harness reference
 ├── docs/         ← Architecture overview + ADRs (0001 four-layers,
-│                   0002 taxonomy expansion + deferred 5-axis decision)
+│                   0002 taxonomy expansion — resolved via hybrid),
+│                   plus self-test.md (A/B fixture methodology)
 ├── glossary.md   ← Unified terminology
 ├── anti-patterns.md  ← Cross-cutting catalog of what not to do
 └── CLAUDE.md     ← Repo-level instructions for agents editing this repo
@@ -96,8 +98,10 @@ Don't load everything. Start with the failure mode you're seeing, pull only the
 | Latency unpredictable in long workflows | `latency-budgeting.md` |
 | Agent refuses benign requests / over-refuses | `refusal-and-recovery.md` |
 | Want to learn from observed failures | `eval-driven-self-improvement.md` + `precedent.md` |
+| User pressures across turns until you flip | `multi-turn-negotiation.md` + `doubt-engine.md` |
 | Doubt-engine F01-counter prose isn't measurable | `engines/calibration.md` |
 | Failure happened — need incident steps | `runbooks/F<NN>.md` |
+| Want to A/B-validate a module's impact | `docs/self-test.md` |
 | Evaluating agent conduct | `recipes/eval-harnesses.md` |
 
 The **production starter pack** is `discipline.md` + `context.md` + `verification.md` + `failure-modes.md` — about 4k tokens, catches the long tail.
@@ -167,7 +171,7 @@ Full guide: [`recipes/system-prompt.md`](recipes/system-prompt.md).
 
 ### Behavior rules that survive long contexts
 
-[`conduct/`](conduct/) ships fifteen modules. The lightest pull-in is just `discipline.md` (~700 tokens) — four stances (think-first, simplicity, surgical, goal-driven) that catch the majority of unsolicited refactors, premature actions, and over-helpful substitutions.
+[`conduct/`](conduct/) ships nineteen modules. The lightest pull-in is just `discipline.md` (~700 tokens) — four stances (think-first, simplicity, surgical, goal-driven) that catch the majority of unsolicited refactors, premature actions, and over-helpful substitutions.
 
 A heavier pull-in adds `context.md` (U-curve placement, checkpoint protocol), `verification.md` (independent checks, dry-run for destructive ops), and `failure-modes.md` (the F-code taxonomy summary). That's the production starter pack.
 
@@ -218,17 +222,22 @@ Free-text learning notes don't compound. Tagged ones do. [`taxonomy/`](taxonomy/
 
 Tag every entry in your failure log with one code. Now you can aggregate. Now you can learn.
 
-The multi-agent cluster (F15–F17) maps to the MAST taxonomy (arxiv 2503.13657); the alignment cluster (F18–F21) draws from Anthropic, OpenAI, and DeepMind safety research. F19 and F20 are awareness codes — log them if observed; the counter is red-team probes and blind capability evaluation, not runtime detection. See [`taxonomy/README.md`](taxonomy/README.md) § Structural note for the deferred Option A/B decision on flat-vs-modular taxonomy structure.
+The multi-agent cluster (F15–F17) maps to the MAST taxonomy (arxiv 2503.13657); the alignment cluster (F18–F21) draws from Anthropic, OpenAI, and DeepMind safety research. F19 and F20 are awareness codes — log them if observed; the counter is red-team probes and blind capability evaluation, not runtime detection.
+
+A parallel **5-axis layer** lives at [`taxonomy/axes.md`](taxonomy/axes.md) — every F-code is mapped to one of memory / reflection / planning / action / system (per AgentErrorTaxonomy, arxiv 2509.25370). Use flat codes for grep-able logs, axes for structural pressure analysis. The hybrid is intentional and documented in [`docs/adr/0002-taxonomy-expansion.md`](docs/adr/0002-taxonomy-expansion.md).
 
 ### Adoption guides, not just docs
 
-[`recipes/`](recipes/) gives you the wiring for the four most common host platforms plus an eval-harness reference. No hand-waving — concrete file paths, concrete config, a verification step you can actually run.
+[`recipes/`](recipes/) gives you the wiring for seven host platforms plus an eval-harness reference. No hand-waving — concrete file paths, concrete config, a verification step you can actually run.
 
 | Recipe | What it covers |
 |--------|----------------|
 | [`claude-code.md`](recipes/claude-code.md) | `@`-imports, hook enforcement wiring, scope precedence |
 | [`openai-agents.md`](recipes/openai-agents.md) | Python SDK integration, `Agent.clone()`, guardrail patterns |
 | [`cursor.md`](recipes/cursor.md) | `.cursor/rules/` activation, scoped pull-ins |
+| [`langchain.md`](recipes/langchain.md) | Middleware list enforcement, LangGraph interrupts, propagation |
+| [`pydantic-ai.md`](recipes/pydantic-ai.md) | `Agent[Deps, Output]` generics, output validation, tool retries |
+| [`baml.md`](recipes/baml.md) | Function-shaped LLM calls, Jinja prompt blocks, `BamlError` |
 | [`system-prompt.md`](recipes/system-prompt.md) | Raw API / llama.cpp / Ollama wiring |
 | [`eval-harnesses.md`](recipes/eval-harnesses.md) | Benchmark suite reference: τ²-bench, AgentDojo, AgentHarm, SYCON-Bench, etc. |
 
@@ -290,14 +299,17 @@ See [`docs/architecture/README.md`](docs/architecture/README.md) for the structu
 
 ---
 
-## Open structural decisions
+## Resolved structural decisions
+
+Two architectural questions that earlier versions of the framework deferred have now been resolved:
 
-Two known architectural questions are deferred to community deliberation rather than decided unilaterally:
+- **Taxonomy structure (resolved 2026-05-05).** Flat F-codes (current) AND 5-axis modular structure (AgentErrorTaxonomy, arxiv 2509.25370) — both layers ship. Hybrid path: F01–F21 stays as the operational identifier; [`taxonomy/axes.md`](taxonomy/axes.md) maps each code to one of memory / reflection / planning / action / system. Documented in [`docs/adr/0002-taxonomy-expansion.md`](docs/adr/0002-taxonomy-expansion.md).
+- **F19/F20 placement (resolved 2026-05-05).** Awareness codes stay in main `taxonomy/` with explicit `(awareness)` flag at the index entry and at the top of each file. Adopters who don't need alignment-research codes can filter by tag rather than file path.
 
-- **Taxonomy structure** — flat F-codes (current) vs. 5-axis modular structure proposed by AgentErrorTaxonomy (arxiv 2509.25370). Migrating is a breaking change. See [`taxonomy/README.md`](taxonomy/README.md) § Structural note.
-- **Awareness vs. operational codes** — F19 (alignment faking) and F20 (sandbagging) are alignment-research concepts. Some adopters will want them in main `taxonomy/`; some will want a separate annex. Currently included in main with explicit awareness flags.
+What remains genuinely external — and only adopters can close:
 
-Open a tracking issue if you have a strong opinion. The framework grows by deliberation, not speculation.
+- **Self-test fixtures.** [`docs/self-test.md`](docs/self-test.md) ships the A/B fixture methodology; **0 of 19 modules** currently have shipped fixtures. The framework is honest about being best-effort guidance, not measured-impact rules. This is the highest-leverage open contribution path.
+- **Real-world adoption signal.** Until a downstream project reports on living with the conduct, every module is a hypothesis.
 
 ---
 

anti-patterns.md

@@ -109,7 +109,7 @@ This is **not the source of truth** — each pattern's home module is. But when
 - **Logging the fix, not the failure.** ([failure-modes.md](conduct/failure-modes.md))
 - **Multiple codes on one entry** — pick the dominant one. ([failure-modes.md](conduct/failure-modes.md))
 - **Logging at verdict time only** — log hypothesis before, outcome after. ([failure-modes.md](conduct/failure-modes.md))
-- **"Couldn't find a matching code"** — propose a new one (F15+) in a PR. ([failure-modes.md](conduct/failure-modes.md))
+- **"Couldn't find a matching code"** — propose a new one (F22+) in a PR. ([failure-modes.md](conduct/failure-modes.md))
 
 ## Doubt engine
 
@@ -130,6 +130,15 @@ This is **not the source of truth** — each pattern's home module is. But when
 - **Idle-only segmentation in boundary detection** — multi-signal exists for a reason. ([boundary-segmentation.md](engines/boundary-segmentation.md))
 - **Confusing simplified Wagner-Fischer with true Zhang-Shasha** — document which version you ship. ([tree-edit.md](engines/tree-edit.md))
 
+## Conduct (recent additions)
+
+- **All-Add as the default** — appending every observation to working memory without pruning, leading to self-degradation. ([memory-hygiene.md](conduct/memory-hygiene.md))
+- **Spawn cap omitted from delegation prompts** — no per-subagent or session-wide token cap; total cost grows unbounded. ([cost-accounting.md](conduct/cost-accounting.md))
+- **Speculative evals** — adding eval cases for hypothetical bugs that haven't been observed. ([eval-driven-self-improvement.md](conduct/eval-driven-self-improvement.md))
+- **Sycophantic capitulation across turns** — flipping stance under sustained user pressure without new evidence. ([multi-turn-negotiation.md](conduct/multi-turn-negotiation.md))
+- **Blanket topic refusals** — refusing benign requests adjacent to refused topics (false-refusal cycle). ([refusal-and-recovery.md](conduct/refusal-and-recovery.md))
+- **Treating latency as a cost proxy** — assuming token cost and wall-clock latency move together; they don't. ([latency-budgeting.md](conduct/latency-budgeting.md))
+
 ## How to use this doc
 
 - Before submitting work: scan the section for the kind of task you just did.

docs/architecture/README.md

@@ -23,10 +23,11 @@ How the four moving parts of agent-foundations compose. Read once; reference whe
 
 | Layer | Surface | Role |
 |-------|---------|------|
-| `conduct/` | 12 rule modules | What the agent should do or avoid |
-| `engines/` | 9 algorithm docs | What the agent should compute |
-| `taxonomy/` | 14 failure-code docs | How the agent names what went wrong |
-| `recipes/` | 4 host adoption guides | How a project picks up the framework |
+| `conduct/` | 19 rule modules | What the agent should do or avoid |
+| `engines/` | 12 algorithm docs | What the agent should compute |
+| `taxonomy/` | 21 failure-code docs (+ axes.md) | How the agent names what went wrong |
+| `recipes/` | 8 host adoption guides | How a project picks up the framework |
+| `runbooks/` | 21 incident-response runbooks | How to triage and recover per failure code |
 
 `anti-patterns.md` and `glossary.md` cross-cut all four.
 
@@ -86,7 +87,7 @@ Adjacent docs that *describe* the framework but aren't part of it (this file, `a
 ## Stability commitments
 
 - **Conduct module names** are stable. Renaming `discipline.md` would break every adopter's `CLAUDE.md`.
-- **Taxonomy F-codes** are append-only. F03 is always context-decay. F15+ is for new patterns; existing codes are not renumbered.
+- **Taxonomy F-codes** are append-only. F03 is always context-decay. F22+ is for new patterns; existing codes are not renumbered.
 - **Engine names** can be renamed if the algorithm name is wrong. Document the rename in an ADR.
 - **Recipe paths** are loose; recipes are the most volatile surface and may be split or merged as host platforms evolve.