Release Notes

release v3.1.0 “The Industrialization of Intelligence”¶

Since v3.0.0, the repository has transitioned from content establishment to governed engineering and verifiable rigor. The focus of v3.1.0 is the elimination of “casual” engineering in favor of governed, verifiable standards.

🛠️ The Primary Shift: Prompt-as-Infrastructure¶

We’ve moved from monolithic consultant prompts to a Recursive Block Architecture, treating prompts as compiled artifacts rather than static text.

• The Compiler: prepare_prompt.py has been rewritten as a JIT compiler that recursively resolves _includes and merges shared blocks from ai_system_layers/3_prompts/blocks/.

• The Logic: This removes the “context window tax” of duplicating complex logic (like Heuer or WRC) across multiple consultants. We now maintain a Single Source of Truth (SSoT) for intelligence tradecraft and inject it into “thin skin” manifests.

• Verification: This architecture is backed by 117 TDD tests covering nested and circular dependency scenarios, ensuring structural stability.

🧠 The Intelligence Layer: From Heuristics to Tradecraft¶

By leveraging the new block architecture, we integrated formal intelligence analysis techniques into our system prompts.

• Heuer Intelligence Tradecraft: To counter “autoregressive momentum”—the tendency of AI to converge on the first plausible hypothesis—we use shared blocks to mandate the Analysis of Competing Hypotheses (ACH) and disconfirmation.

• The WRC Metric (Self-Discipline Trigger): We replaced “vibes-based” evaluation with the Weighted Response Confidence (WRC) metric, implemented as a core block. It forces the model to calculate confidence based on evidence, alignment, and probability, ensuring high confidence is earned, not hallucinated.

🏗️ The Governance Foundation: The Frontmatter Standard¶

We overhauled the repository’s metadata system, moving from a fragmented, directory-based approach to a Self-Describing Composable Block Standard.

• The “Why”: Documents now define themselves using additive blocks: Identity (who/what), Discovery (intent/tags/cost), and Lifecycle (version/birth/date).

• Enabling AI-Readability: By isolating the “Discovery block,” agents can parse a file’s intent and cost without reading the entire document, optimizing the attention budget.

• The Guardrail: This standard is enforced by the check_frontmatter.py validation engine, preventing metadata decay.

🛡️ Operational Guardrails: Hard Constraints¶

We introduced “Hard Constraints” to eliminate high-impact, avoidable errors in the agentic workflow.

• Scripts as Instructors (JIT Feedback): Validation scripts now provide Just-In-Time (JIT) instructions, telling the agent exactly how to fix a violation. This eliminates the “diagnostic loop” where agents waste tokens repeatedly reading files to guess the cause of an error.

• Script Suite Governance: As a consequence of the “Code as Docs” shift, the former script-test-doc triad has evolved into a script-test dyad. check_script_suite.py enforces this pairing, preventing the proliferation of “dark tools” (untested or undocumented utilities) while eliminating redundant prose.

• Safety Bans: To protect Git history and CI/CD integrity, we explicitly banned high-risk tools (sed, git reset) and the use of the --no-verify flag.

release v3.0.0 “The Agents Emerge”¶

Summary of Changes¶

v2.8.0 established prompt format as empirical science and operationalized the governance infrastructure. v3.0.0 extends the research program to the tools that built it — the AI coding agents themselves become the objects of study.

This release delivers a systematic comparative analysis of 7 open-source agent codebases (Qwen Code, Claude Code, OpenCode, OpenClaude, Aider, KiloCode, Superpowers) — their context management strategies, skill discovery mechanisms, and stability against LLM drift. The central finding challenges the repository’s own structure: agents are not another layer in the stack, they are the product that assembles all layers. This drove a reorganization — ai_system/ becomes ai_system_layers/ (clarifying that layers are components), and a new ai_agents/ directory appears at the repo root as the consumer of all layers.

Four strategic themes define v3.0.0:

1. Context Engineering Across 7 Agents — The first cross-agent empirical guide: ai_agents/context_management/ covers how every major open-source coding agent handles conversation history, compaction, and state management. The central insight: every agent uses a fundamentally different strategy — sliding windows, reactive compaction, async background summarization, multi-tier systems — and understanding these differences is essential for choosing the right tool. The comparison tables and decision guide help practitioners navigate this fragmented landscape without trial-and-error.

2. Agent Architecture Demystified — Three articles answer questions every practitioner has: How do subagents actually work? (Spoiler: not OS fork/exec — three real patterns: separate API calls, prompt role orchestration, HTTP process management.) What keeps agents stable when LLM outputs drift? (Hard guarantees like tool denial and circuit breakers, not soft techniques like tag conventions.) Why does Qwen Code use TypeScript, not Python? (Async I/O dominance and shell command architecture.) These are not opinions — they are extracted from source code evidence.

3. Code as Primary Documentation — The ecosystem adopts a principle that follows directly from context engineering: every source file must open with a contract docstring in its language’s native format. When agents are your primary code consumers, every token of documentation competes with code for their attention budget. Code with outdated docstrings fails at import time. Prose docs that contradict code pass CI silently. The contract docstring — “what does a future agent need to read first to work safely in this file?” — is the only documentation layer that stays correct by construction.

4. Skills Discovery and Prompt Brittleness — Analysis of Superpowers v5.0.7’s skill system across 5 agent platforms reveals three failure modes (context limits, instruction drift, hallucination/skipping) and empirically-derived countermeasures (HARD-GATE tags, rationalization tables, two-stage review). This is not theoretical — these are countermeasures that survived contact with real agent sessions.

Architecture Decisions¶

• ADR-26045: AI-Native Development — Code as Primary Documentation — Accepted: Every source file in the ecosystem must open with a contract docstring answering: “What does a future agent need to read first to work safely in this file?” This is not a coding style preference — it is a consequence of context engineering. Agents are stateless, context-constrained, and read code as fluently as prose. Redundant documentation that paraphrases code is a context window tax. Code structure + contract docstrings + test suites provide CI-verified, co-located, refactoring-safe documentation.

• ADR-26046: External Product Repos as Research Directories — Proposed: Governs how external product source code is cloned and tracked for comparative research. Defines a centralized path registry with relocation safety — when a research directory moves, the registry and all consumer files update atomically. This prevents the silent breakage that occurs when external repos change paths.

Accepted ADRs (Promoted in This Release)¶

Open RFCs (Proposed ADRs)¶

New proposed ADRs introduced in this release:

Carry-over proposed ADRs (open for review and comment):

New Features and Articles Added¶

• Agent Research Program (7 codebases analyzed):

  The core deliverable — a systematic study of how open-source AI coding agents manage context, discover skills, and maintain stability:

  • Context Management Overview — pattern taxonomy: full history, sliding window, reactive compaction, async summarization, tiered systems

  • Context Management Comparison — side-by-side tables across 7 agents: trigger mechanisms, compaction strategies, state preservation, decision guide

  • Individual agent deep dives: Qwen Code (autocompact buffer + /compress), Claude Code (5-tier system), OpenCode (reactive compaction), OpenClaude (5-tier system), Aider (async background summarization), KiloCode (OpenCode fork)

  • How Subagents Work — debunks OS fork/exec myth, documents three real patterns

  • Stability Against LLM Drift — hard guarantees vs soft techniques

  • Skill Discovery Across Platforms — Superpowers v5.0.7 analysis across 5 platforms

  • Prompt Brittleness in Skills — three failure modes with empirically-derived countermeasures

• manage_external_repos.py — External Research Repo Management (19 tests, 85% coverage):

  CLI tool for cloning, updating, and listing external research repositories. Supports setup, update, list, register, unregister, and relocate commands. The relocate command is the key safety feature: when a research directory moves, it updates the registry and consumer files atomically.

• Commit Message Format Enhancement:

  Sub-bullet format now supported in commit body validation ( — <lowercase_verb> <detail>). Enables richer changelog entries while maintaining the structured format that generate_changelog.py parses.

• ADR Conditional Validation and Index Duplicate Detection:

  ADR validator now enforces conditional sections: rejected ADRs must have Rejection Rationale, superseded ADRs must have Supersession Rationale, deprecated ADRs must have Deprecation Rationale (minimum 3 words — prevents empty/TBD sections). The index builder detects duplicate ADR entries and reports their location.

• Qwen JSON Export Converter (41 tests, 93% coverage):

  Converts Qwen chat export JSON to evidence source artifacts with thread reconstruction and auto-ID from git history. Enables capturing research sessions directly from Qwen conversations — the JSONL session log format used by Qwen Code is a separate research track.

Updates in Existing Files¶

• KV Cache Internals — Technical Accuracy Review: The what_kv_cache_actually_contains.ipynb document received a comprehensive technical accuracy pass: fixed GQA weight matrix dimensions, FLOP count consistency, FlashAttention complexity claims, SwiGLU FFN FLOP counts, autoregressive complexity notation, bandwidth ratios, and arXiv source citations.

• Consultant Prompt Consolidation: Hybrid consultant prompts consolidated under canonical names. Unused variants deleted. Consultants README added as usage guide and catalog.

Repository Structure Changes¶

release v2.8.0 “The Prompt Physics”¶

Summary of Changes¶

v2.7.0 settled the ecosystem’s strategic direction: context engineering over multi-agent orchestration. v2.8.0 turns that principle into empirical engineering. The release delivers a three-article series on prompt format — with real measurements, plots, and reproducible code — backed by three new analyses grounding every claim in reviewed evidence. The central finding challenges a common assumption: token cost is not a property of the format alone. It is a function of format, serializer, and tokenizer together, and the relative ranking of YAML vs. JSON can flip depending on which Python library you use to generate the YAML.

Alongside the research, this release closes the governance infrastructure loop: all configs migrated to JSON, the frontmatter validator deployed and enforced at commit time. The two threads — empirical prompt research and governance automation — serve the same goal from the ecosystem roadmap: build the evidence base and the tooling foundation before writing the first production application.

Three strategic themes define v2.8.0:

1. Prompt Format as Engineering Science — The Format as Architecture series answers a question that most practitioners answer by intuition: which format should a system prompt use? The answer is not a preference — it has a mechanistic explanation rooted in BPE tokenizer architecture and transformer attention. JSON is optimal for development artifacts (validation, tooling). YAML is optimal for runtime instructions (low structural noise). XML provides scope isolation where injection resistance matters. The series includes token measurements across four formats on a production prompt, validated across three tokenizers (cl100k_base, o200k_base, Qwen-72B).

2. Two-Stage Consultant Workflow — The prompt engineering toolchain gains a structured two-phase workflow. ai_brainstorming_colleague.json (v0.2.0) is the first stage: unconstrained ideation, architectural discussion, “what-if” scenarios. When a direction needs formal validation, it hands off explicitly to ai_systems_consultant.json or devops_consultant.json — the strict reviewers with WRC scoring and SVA compliance. The brainstorming colleague enforces this boundary itself: when it detects validation-intent keywords, it executes the handoff protocol rather than attempting a review it is not designed for. This prevents the common failure mode of asking an exploratory tool for production-grade architectural judgement.

3. Governance Infrastructure Operational — ADR-26042: Common Frontmatter Standard and ADR-26036: Config File Location and Naming Conventions / ADR-26054: JSON as Governance Config Format move from specified to enforced. check_frontmatter.py (work in progress) validates document frontmatter at commit time against the composable schema. All governance configs are migrated from YAML to JSON. The .vadocs/ configuration system is complete: conf.json hub → types/*.conf.json spokes → pyproject.toml entry point for all tools.

Architecture Decisions¶

• ADR-26054: JSON as Governance Config Format — Config Serialization: Governance configs use JSON (not YAML, not TOML) because JSON Schema is the de-facto standard for machine-validated structured configuration with mature tooling in Python (jsonschema library) and across the broader ecosystem. YAML was rejected despite its readability advantage because schema tooling for YAML is fragmented and no dominant standard exists. TOML has no schema standard at all. Document frontmatter stays YAML (MyST-native, human-authored) — JSON governs only machine-read governance configs in .vadocs/. A JSON Schema companion conf.schema.json validates the hub config structure.

• ADR-26044: Skills as Progressive Disclosure Units — Skills Architecture: ADR-26044 formally defines a skill as a self-contained instruction block injected into the agent’s context on demand. Skills are not subagents — they carry no separate LLM calls, no state, no negotiation. They are loaded when needed (progressive disclosure) and expire when the conversation ends. This definition sharpens the boundary introduced in ADR-26038: managing what the agent sees (context budget) is the primary engineering constraint, and skills are the mechanism for doing so without spawning multiple agents. The sv- namespace in Claude Code demonstrates the pattern in practice: six consultant prompts loaded as skills via symlinks to their JSON sources in ai_system/3_prompts/consultants/. The two validation-focused skills (sv-ai-systems-consultant-hybrid, sv-devops-consultant) use WRC scoring — Weighted Response Confidence, a 0–1 metric composed of empirical benchmark evidence (35%), enterprise production adoption (25%), and predicted performance on the target stack (40%); currently defined inside the prompt, pending a governing ADR (tracked in techdebt.md TD-006) — and SVA compliance (ADR-26037: Smallest Viable Architecture Constraint Framework) as their output standard — making formal architectural review available on demand without context pollution between exploration and validation phases.

• ADR-26036: Config File Location and Naming Conventions and ADR-26042: Common Frontmatter Standard — Now Operational: Both ADRs were proposed in v2.7.0. This release marks their operational transition: .vadocs/ contains all governance configs in JSON (ADR-26036), and check_frontmatter.py enforces the composable frontmatter schema (ADR-26042) at commit time. Promotion to accepted awaits ecosystem-wide validation in the next release cycle.

Accepted ADRs (Promoted in This Release)¶

No ADRs were promoted in this release. v2.8.0 is a research and operationalization cycle: the prompt engineering series builds the empirical foundation; the governance tooling enforces v2.7.0 decisions. Promotion of ADR-26042: Common Frontmatter Standard, ADR-26036: Config File Location and Naming Conventions, and ADR-26054: JSON as Governance Config Format to accepted requires validation across the full ecosystem, which begins next cycle.

Open RFCs (Proposed ADRs)¶

New proposed ADRs introduced in this release:

Carry-over proposed ADRs (open for review and comment):

New Features and Articles Added¶

• Prompt Engineering Series (3 articles + 3 analyses):

  The core deliverable of this release — an empirically grounded series on how prompt format affects LLM behavior:

  • Format as Architecture: Signal-to-Noise in Prompt Delivery — qualitative format comparison, training-distribution effects, the two-audience principle (compiler vs. runtime model), security analysis, and the decision framework. Central claim: structural tokens (brackets, quotes, commas) are not ignored — the model processes each one to determine it is irrelevant, incurring compute cost and receiving a lower but non-zero attention weight. Their presence dilutes the share of attention available to instructional content. The more structural noise in the prompt, the harder the model has to work to extract the actual signal. For the technical mechanics see A-26016: Causal Masking and Attention Mechanics — Implications for Prompt Format.

  • Token Economics of Prompt Delivery — the empirical companion: BPE tokenizer mechanics (space+word merging, indentation cost, punctuation merging), measured token costs across four formats on a production prompt, cross-tokenizer validation (cl100k_base, o200k_base, Qwen-72B).

  • Appendix: YAML Serializer Variance — the unexpected finding: PyYAML and yq produce semantically equivalent YAML from the same JSON source yet differ by 100+ tokens on a 150-line production prompt, and the YAML Literal vs. Pretty JSON ranking flips depending on the serializer. Token cost is f(format, serializer, tokenizer) — three variables, not one. Validated across 5 prompt files.

  Three analyses ground the series in reviewed evidence:

  • A-26016: Causal Masking and Attention Mechanics — Implications for Prompt Format — grounds the “attention anchors” and “reasoning capacity” claims in transformer architecture

  • A-26017: YAML Serializer Variance — Token Economics of Format Choice — verifies the three-variable finding with independent measurements across serializers

  • A-26018: XML Tags as Scope Boundaries — Prompt Architecture and Injection Resistance — covers the hybrid YAML+XML pattern and the JSON-list injection boundary technique

• check_frontmatter.py — Frontmatter Enforcement (work in progress; 67 tests, 97% coverage on implemented scope): Validates document frontmatter against the composable schema from ADR-26042: Common Frontmatter Standard. Resolves the hub-spoke config chain dynamically — one validator, all document types. Two pre-commit hooks: check-frontmatter (validates on stage) and test-check-frontmatter (runs the test suite on script/config changes). Architecture analysis A-26015: Frontmatter Validator Architecture evaluated three approaches; Approach C (module+CLI) selected.

Updates in Existing Files¶

• ai_brainstorming_colleague.json (v0.2.0): Refocused as the first stage of a two-stage workflow. Removed stack-specific defaults. Added interaction_rules (technical language, no filler, falsifiable claims only) and handoff_target: ai_systems_consultant_hybrid. Overhauled output structure with Critical Diagnosis and Root Cause Analysis steps. When it detects validation-intent keywords, it executes the handoff protocol instead of attempting formal review.

• Governance Config Migration (.vadocs/): All configs migrated from YAML to JSON. Deleted: conf.yaml, adr_config.yaml, architecture.config.yaml, evidence.config.yaml. New layout: conf.json + conf.schema.json (hub) → types/adr.conf.json, types/evidence.conf.json (spokes). New shared modules: git.py (repo root detection, staged files) and paths.py (convention-based config discovery via get_config_path()). pyproject.toml gains [tool.vadocs] entry point.

Existing Files Moved or Renamed¶

release v2.7.0 “The Context Engineering Pivot”¶

Summary of Changes¶

v2.6.0 explored an ambitious vision — agents as operating systems that discover and compose skills at runtime. That research produced valuable insights (4 analyses, 11 source artifacts, 7 ADRs), but the key finding was simpler than the vision: what matters is not how many agents you have, but what each agent sees. v2.7.0 distills this into a strategic pivot — context enginee... [truncated]