Applied Volume. Production SDD for Qwen Code CLI

This directory is the second, applied volume of the textbook. The first volume in book/ teaches the basic SDD cycle on AgentClinic: constitution, feature specification, plan, verifiable facts, implementation, review, and replanning. The second volume transfers the same cycle into production scenarios: legacy traces, validators, multi-agent checks, Spec CI, metrics, model budgets, and limited auto-remediation.

Version: v1.0 — verified 2026-05-20. See CHANGELOG.md for revision history.

The material is not designed for a first introduction to SDD. Before reading, you need to understand requirements.md, plan.md, validation.md, QWEN.md, feature boundaries, negative requirements, and fact-based verification. If these terms have not yet become part of your working vocabulary, complete the first volume first.

The main rule of the second volume: the first pass should leave one small verifiable trace, not introduce all production terminology at once. In each chapter, first close the educational minimum: one artifact, one command, or one blocker for capstone/. The main graded case is high_memory_usage; rules for transferring local cases into the main one are described in Part 0.

Quick Start

1. Open Part 0 and take the main case high_memory_usage.
2. Create an empty capstone/.
3. In chapters 1–3, fill in genealogy.md, a poisoned/fixed pair, and constitution.md.
4. In chapters 4–11, complete only the "Minimal Educational Scenario" section and runnable commands from [examples/](examples/); if a chapter uses a different case (autoscale_200pct, node_not_ready, appointment_latency / appointment_latency_spike, cdn_error_budget_burn), write one transfer line — which principle from that case protects the main high_memory_usage.
5. In chapter 12, check the package against antipatterns.
6. In chapter 13, assemble the final capstone/README.md and verify that it can be understood without chat history.

Minimal check of examples, including expected blockers:

bash book2/examples/smoke_all.sh

How to Read the Chapters

Chapters 1–12 should be read at the same pace. At the beginning of each chapter, first find the short "Before Reading" block: it answers what the chapter takes from the first volume, which local case it launches, what gets transferred to capstone/, and what belongs to the full track.

Then keep five questions in mind:

1. Foundation from the first volume. Which AgentClinic idea is being extended.
2. Minimal educational scenario. What to do by hand or run locally.
3. Control fact. What proves the chapter has been completed.
4. **How this gets into capstone/.** Which line or file remains after the chapter.
5. Full track. What will only be needed when deploying to a real production repository.

If a chapter feels dense, don't read it linearly. First complete the minimal scenario, then return to "Key Ideas," and only after that look at calibrations, [project script], and [conceptual interface]. A term that doesn't help fill the current capstone/ file can be skipped until the second pass.

The editorial rule of the second volume: on the first pass, a new chapter should add no more than one new mandatory term to your working vocabulary. If you encounter five more names, but they aren't needed for the current capstone/ file, treat them as reference material and return to them after the minimal scenario.

Practical test for a chapter: after the minimal scenario, the reader should be able to write one line in one capstone/ file. If two new mechanisms need to be understood at once for this, one of them belongs to the second pass or the full track.

Status Labels and Commands

Chapters use the same confidence levels as the first volume:

• Standard — fixed behavior of a tool or established practice.
• Recommendation — practice that works in most cases but allows adaptation.
• Frontier — approach is in use, but the form depends on the team, models, and infrastructure.

Command blocks are divided into three types:

• [runnable] — works locally in [book2/examples/](examples/) without external dependencies.
• [project script] — interface of a script that needs to be implemented in your own project.
• [conceptual interface] — form of a future orchestrator, policy gate, MCP layer, or CI integration.

For educational completion, only [runnable] blocks and manual artifacts are needed. Everything else belongs to the full track.

End-to-End Route

Mandatory Artifacts for First Pass

Track only these files. Other terms can be read later, once the main package already reads as a single case.

• genealogy.md — where the requirement came from.
• poisoned-spec.md / fixed-spec.md — which defect was found and how it was fixed.
• constitution.md — which actions are forbidden to the agent or permitted with limitations.
• validation.md — which facts were actually verified.
• judgment.md — what verdict was rendered and on what evidence.
• budget-note.md — what happens when the cheap tier refuses.
• goodhart-note.md — which metric may start lying and which guard metric constrains it.
• readiness.md — why the contour is admitted, blocked, or sent to semi-manual mode.
• antipattern-audit.md — three risks in the form blocker / owner / next_check after completing chapter 12.
• capstone/README.md — final assembly of the package for one case.

Chapter 6 adds a short Shadow notes block to capstone/README.md (or, if you use QWEN.md in your educational repository, there). This is not a separate file in the main list.

Other names (scorebook, metric_network, decision_hash, precedents.md) belong to the full track unless they directly help fill one of the files above.

Each chapter must provide a minimal final fragment for one of these files. If after a chapter you have only general understanding but no line, command, or blocker for capstone/, the chapter is not yet closed at the educational level.

Cross-map of "which chapter writes which capstone/ file":

Before self-grading, open [examples/templates/capstone-dossier.md](examples/templates/capstone-dossier.md). This is a completed benchmark of the minimal package for high_memory_usage: it shows how short a good first pass can be.

Chapter Map

The full AgentClinic domain map is in Appendix A. Qwen Code command compatibility is described in Appendix B. Checklists are collected in Appendix C.

Why the Case Changes from Chapter to Chapter

The main graded case is high_memory_usage. But chapters 1–10 take different incidents because not every one equally well demonstrates the mechanism being studied: somewhere a priority conflict is easier to see in another domain, somewhere a mutation history is needed that high_memory_usage doesn't have. One case for the entire volume would turn every template into a formality.

The transfer rule is simple: after the chapter, write one line — which principle from that case protects your high_memory_usage.

If a chapter case doesn't transfer in one line — the chapter has been read but not closed.

Parts

1. AgentClinic-production Lab
2. Recovering Specifications from Legacy
3. Diagnosing Specification Defects
4. Project Constitution: First Rule Referendum
5. LLM Duel: Verifier vs Implementor in Formal Claims
6. Mutation Testing of Specifications
7. Shadow Specification Selection
8. Specification CI: Specification as Executable Artifact
9. File Arbitration of Disputed Change: Roles, Verdicts, and Precedents
10. Model Routing and Token Budgets
11. Protecting Metrics from Goodhart: Guard Metrics and Emergency Mode
12. Integration with Real API: From Specification to Deploy
13. Production SDD Antipatterns: Diagnostic Map of Applied Cycle
14. Practical Exam: Assemble Production SDD Contour

Accompanying Documents

• Applied Volume Glossary — definitions of second volume terms.
• Applied Volume Changelog — revision history of the text.
• Instructor Note — workshop formats and typical errors.
• Bridges to First Volume — prerequisites and AgentClinic domain map.
• Qwen Code Compatibility — built-in commands, custom commands, and project scripts.
• Applied SDD Checklists — checks for Spec CI, arbitration, metrics, and production readiness.
• Threshold Calibration — "Low / Default / High" tables, threshold shift exercises, and review signals for chapters 5, 6, 9, 10, 11. Not needed on first pass.
• Runnable Examples — local smoke runs and templates.

What Counts as Success

By the end of the applied volume, the result should not be a set of beautiful rules but a reproducible contour:

• disputed requirements have provenance and uncertainty level;
• dangerous automations are constrained by constitution, guardrails, and rollback conditions;
• validation.md checks happy path, negative path, counterexamples, drift, and Goodhart traps;
• CI or its runnable analog blocks uncovered requirements and weak payload contracts;
• agent decisions leave evidence suitable for review by another human or another model;
• final capstone/ shows one path from legacy trace to production-ready solution with explicit blockers and fix plan.