buildanything 1.8.0 → 2.1.1

package/protocols/agent-prompt-authoring.md

@@ -0,0 +1,165 @@
+# Agent Prompt Authoring Standard
+
+You are producing text that will become another agent's prompt. Task briefs, finding reports, routing rows, fix specs, critic verdicts — when your output is read by a downstream agent and shapes its behavior, the quality of your text is the quality of that next dispatch's input.
+
+This protocol defines how to write that text well.
+
+## Who this applies to
+
+- `briefing-officer` — writes per-task briefs read by implementers
+- `product-feedback-synthesizer` — writes routing rows read by Phase 5.5 fix dispatches
+- `product-reality-auditor` — writes findings.json read by the synthesizer
+- `design-critic` — writes findings that drive metric-loop fix prompts
+- `product-owner` — writes feature-delegation plans read by briefing officers
+- `code-architect` — writes implementation blueprints read by sprint planner + implementers
+- LRR chapter judges — write verdicts read by the aggregator for backward routing
+
+If your output is consumed by a human, this protocol does not apply — write for humans normally.
+
+## The single rule
+
+The receiving agent has not seen this conversation. It cannot ask follow-up questions. It will read your output and act. If a smart colleague reading the same text would be confused, the receiving agent will be too.
+
+## Standards
+
+### 1. Ground in quotes, not paraphrase
+
+When your output references a source artifact (product-spec, page-spec, decisions.jsonl, findings.json, architecture.md), quote the source verbatim and carry the source location as a trailing reference. Paraphrase reintroduces the drift the graph layer was built to prevent.
+
+- Weak: `User has 3 attempts to enter a code per the spec`
+- Good: `User has 3 verification attempts before lockout (from product-spec.md L142)`
+
+If the graph returns the field directly, copy it character-for-character. ID-to-label resolution and list-filtering are the only allowed transformations.
+
+When the source field is negative by design (DNA `Don'ts`, banned phrases, system invariants), quote it verbatim — do not rewrite to positive framing. Standard 1 (verbatim) wins over Standard 2 (positive) when the source itself is intentionally negative.
+
+### 2. Tell the receiver what to do, not what not to do
+
+Positive prescriptions are unambiguous. Negative prescriptions force the receiver to enumerate the negative space and pick something from it — that's where drift happens.
+
+- Weak: `Don't use generic colors`
+- Good: `Use locked DNA palette: primary #0F172A, accent #F59E0B`
+
+- Weak: `Don't skip error handling`
+- Good: `On 4xx response, render the error toast component with the API body's message field`
+
+Negative framing is justified for actual invariants the receiver would otherwise rationalize around — see Standard 5 for when to escalate.
+
+### 3. Add the why for non-obvious constraints
+
+Without motivation, the receiver cannot judge edge cases. A stated reason lets it reason about whether the rule applies in a borderline situation.
+
+- Weak: `Use the manifest entry`
+- Good: `Use the manifest entry — this slot is HARD-GATE; rebuilding it from scratch will fail Phase 5 brand audit`
+
+- Weak: `Cap retries at 3`
+- Good: `Cap retries at 3 — backend rate-limits at 5 req/sec per user (from architecture.md L88)`
+
+### 4. Wrap structured inputs in XML tags
+
+When you slot a complex artifact into your output (wireframe, acceptance criteria, persona constraints, API contract), wrap it. The receiver parses the boundary unambiguously.
+
+```
+<wireframe>
+[verbatim ASCII from page-specs/checkout.md L20-45]
+</wireframe>
+
+<acceptance_criteria>
+- Form renders all required fields per layout
+- Submitting valid input calls POST /api/checkout once
+</acceptance_criteria>
+```
+
+This matters most when your output contains long-form quoted content (>10 lines). Short inline values do not need tags.
+
+### 5. Reserve HARD-GATE language for actual invariants
+
+`MUST`, `STOP`, `do NOT` lose force when overused. Reserve them for rules where violation breaks the pipeline. Soft preferences dressed up as hard gates dilute the genuine ones.
+
+Use HARD-GATE language for:
+- Pipeline-breaking failures (graph-call failure → STOP, no silent fallback)
+- Race-condition triggers (writer-owner violations corrupt files)
+- Audit-blocking decisions (manifest `hard_gate: true` slots)
+- Drift-introducing transformations on graph fields (verbatim slotting)
+
+Use normal prescriptive language for everything else: "Use", "Include", "Quote", "Reference". A rule stated once with rationale is stronger than the same rule stated three times in escalating caps.
+
+If you find yourself repeating a rule, the rule is fragile — fix it once at the source instead.
+
+## Worked example — task brief block
+
+### Weak brief
+
+```
+### Task 4.1: Build checkout
+- Agent: engineering-frontend-developer
+- Context:
+  - Build the checkout flow per the spec
+  - Make sure errors are handled
+  - Use good design
+- Acceptance: works
+```
+
+Violations: pointer-not-content (Standard 1), vague verb "handled" (Standard 2), uninstantiated "good design" (Standard 2), no testable criteria.
+
+### Improved brief
+
+```
+### Task 4.1: Build checkout payment-method form
+- Agent: engineering-frontend-developer
+- Skills: react-best-practices, shadcn-composition
+- Context:
+  <wireframe>
+  [verbatim ASCII from page-specs/checkout.md L20-45]
+  </wireframe>
+  - Components: shadcn Form.field, shadcn Input.text, shadcn Button.primary
+  - Tokens: colors.primary, spacing.lg
+  - API: POST /api/checkout, body {payment_method_id: string, amount_cents: number}, returns 200 {order_id} or 4xx {error: string}
+  - Error states:
+    - 402 → toast "Payment declined. Try a different card." (from product-spec.md L142)
+    - 422 → inline field error "Invalid card number" (from product-spec.md L145)
+  - Business rules: amount_cents minimum 50 (from product-spec.md L156)
+  - Persona: [Buyer] complete checkout in 3 fields max (from product-spec.md L167)
+- Acceptance:
+  - Form renders all fields specified in wireframe
+  - Submitting valid payment_method_id calls POST /api/checkout once
+  - 402 response shows toast within 200ms
+  - 422 response shows inline error tied to the offending field
+```
+
+Why this works: wireframe quoted verbatim, components carry library + variant, every constraint has a source ref, acceptance criteria are testable.
+
+## Worked example — synthesizer routing row
+
+### Weak finding
+
+```json
+{
+  "finding_id": "f-042",
+  "description": "Checkout has issues with persona requirements",
+  "target_phase": 1
+}
+```
+
+### Improved finding
+
+```json
+{
+  "finding_id": "f-042",
+  "source": "product-reality",
+  "feature_id": "checkout",
+  "target_phase": 1,
+  "target_task_or_step": "1.6",
+  "description": "Buyer persona constraint at product-spec.md L167 requires 3-field checkout, but spec also requires billing_address (5 fields) and shipping_address (5 fields). Constraint and required fields are mutually exclusive — spec needs disambiguation before Phase 4 can proceed.",
+  "evidence_path": "evidence/product-reality/checkout/findings.json#f-042"
+}
+```
+
+Why this works: contradiction stated concretely with line refs, evidence pointer is reachable, routing decision (`target_phase: 1`) is justified by the description text rather than asserted.
+
+## When you are tempted to break these rules
+
+- **"It's faster to summarize than to quote"** — the time you save now is paid with interest by the implementer who has to re-read the source to recover what you summarized away.
+- **"The receiver will figure it out"** — the receiver has no conversation history. It will guess, and the guess will be plausible-looking but wrong.
+- **"Adding the source ref is noisy"** — Phase 5 auditors and reviewers use source refs to spot-check. Without them, every claim is unverifiable.
+- **"This rule is critical, I should repeat it for emphasis"** — repetition signals fragility. State it once with the why; if the rule actually breaks the pipeline, escalate to HARD-GATE language at the rule's source instead of restating in every dispatch.

package/protocols/architecture-schema.md

@@ -0,0 +1,178 @@
+# architecture.md Anchor Convention
+
+## Purpose
+
+Phase 2.3's architecture synthesizer emits `docs/plans/architecture.md` with **stable section anchors** so that Phase 5.1 implementer agents can receive content-addressed **refs** (file path + anchor name) instead of pasted content slices. This document defines the required top-level sections, the anchor naming convention, the minimum subsection anchors each top-level section must provide, the exact ref format Phase 5.1 prompts inject, and the synthesizer's output contract. Introduced in Wave 1 (W1-4) to close the capdotai Phase 5 regression where the orchestrator loaded a 43KB architecture doc into its own context 48 times to slice it — violating the "dispatcher not doer" HARD-GATE at `commands/build.md:24` and burning ~528K tokens on slicing alone.
+
+## Required top-level sections
+
+The synthesized `architecture.md` MUST contain these top-level headings, in this order:
+
+- `# Overview`
+- `# Frontend`
+- `# Backend`
+- `# Data Model`
+- `# Security`
+- `# Infrastructure`
+- `# Scope`
+- `# Out of Scope`
+
+For iOS builds, `# Frontend` MAY be titled `# App` and `# Backend` MAY be omitted if the app is fully on-device (the `refs.json` index reflects whatever headings exist). For web builds, all eight headings are required.
+
+## Anchor naming rules
+
+- Anchors are **kebab-case** within a section — lowercase, hyphen-separated, no spaces.
+- Subsections use a **nested anchor** of the form `parent/child`. For example, `frontend/checkout` refers to a `## Checkout` subsection under `# Frontend`.
+- Anchors must be **stable across synthesizer reruns**. A rerun of the synthesizer on the same inputs must produce the same anchors, so that refs cached in `refs.json` or in implementer prompts do not break.
+- Anchors are **referenced via `architecture.md#parent/child`** in prompt bodies and in `refs.json`. The `#` separator is a plain markdown fragment — no special escaping.
+- Deeper nesting (`parent/child/grandchild`) is allowed but discouraged. Prefer two levels.
+- Anchor names MUST NOT include spaces, uppercase letters, punctuation other than `-` and `/`, or numeric prefixes like `1-frontend`.
+
+## Required subsection anchors (minimum)
+
+Every synthesized `architecture.md` MUST provide at least these subsection anchors under the named top-level section. Additional subsections are allowed; fewer is a synthesizer failure.
+
+### Under `# Frontend`
+
+- `frontend/layout` — page hierarchy, routing, navigation structure. MUST state whether the product exposes a public, unauthenticated, content-indexable surface (yes / no / partial) — downstream SEO skill loading keys off this answer. MUST include a navigation map listing every route with its nav element (sidebar item, tab, breadcrumb, direct URL only).
+- `frontend/components` — core component list and responsibilities.
+- `frontend/state` — state management approach (stores, context, local state boundaries).
+- `frontend/styling` — design tokens, CSS/styling approach.
+
+### Under `# Backend`
+
+- `backend/services` — service boundaries and responsibilities.
+- `backend/api` — API contracts (routes, request/response shapes). Each endpoint heading MUST include feature attribution annotations: `**POST /api/orders** (provides: order-placement)` or `**GET /api/inventory/{id}** (provides: inventory) (consumes: order-placement)`. Use the feature's kebab-case name from `product-spec.md`. `provides` = the feature that implements this endpoint; `consumes` = features that call it. These annotations are parsed by the graph indexer to emit `feature_provides_endpoint` / `feature_consumes_endpoint` edges — without them, the Product Owner cannot group features by API dependency.
+- `backend/persistence` — data layer, ORM choice, query patterns.
+
+### Under `# Data Model`
+
+- `data-model/entities` — entities and their relationships.
+- `data-model/migrations` — migration strategy (omit only if no persistence layer exists).
+
+### Under `# Security`
+
+- `security/auth` — authentication and authorization model.
+- `security/input-validation` — boundary validation rules.
+- `security/secrets` — secret storage and rotation.
+
+### Under `# Infrastructure`
+
+- `infrastructure/deployment` — deployment target (Vercel, AWS, self-hosted, TestFlight), CI/CD approach, environment strategy (dev/staging/prod).
+- `infrastructure/caching` — caching strategy (CDN, in-memory, database query cache), cache invalidation approach, what's cached and for how long. Stub with "N/A — no caching layer needed" if the product doesn't warrant it.
+- `infrastructure/background-jobs` — async processing model (email sending, webhook handling, scheduled tasks, queue system). Stub with "N/A — no background processing needed" if all operations are synchronous.
+- `infrastructure/env-vars` — required environment variables and secrets for each environment (dev/staging/prod). List every key the app needs to run, which service it authenticates with, and whether it's a secret or a config value. Format: `STRIPE_SECRET_KEY — Stripe payment processing — secret — required`.
+
+## Ref format used by implementer prompts
+
+Phase 5.1 implementer prompts inject a `ARCHITECTURE REFS:` block in place of pasted architecture content. The block is parsed by the implementer agent, which uses the `Read` tool to fetch refs on demand.
+
+```
+ARCHITECTURE REFS:
+  - architecture.md#frontend/checkout (primary)
+  - architecture.md#data-model/orders (secondary — read if touching order creation)
+  - architecture.md#security/auth (read if touching /api/checkout)
+```
+
+Rules:
+
+- `(primary)` — the implementer MUST Read this ref before starting work.
+- `(secondary — read if touching X)` — conditional; the implementer reads only if the task description overlaps with the hint.
+- Refs are one per line, bullet-prefixed `-`, with two-space indent.
+- File paths are relative to the repo root. Anchors are kebab-case per the rules above.
+
+The orchestrator NEVER pastes section content into the implementer prompt. It emits only refs. If the implementer needs more context, it Reads additional refs or opens the full `architecture.md`.
+
+## Phase 2.3 synthesizer output contract
+
+The Phase 2.3 architecture synthesizer MUST produce one artifact:
+
+1. `docs/plans/architecture.md` — the human-readable architecture doc, containing:
+   - All eight required top-level headings (or the iOS-adjusted set).
+   - All required subsection anchors for each top-level section present.
+   - Prose content under each subsection sufficient for an implementer to ground their work.
+
+The synthesizer does NOT write `refs.json`. The Phase 2.2 Refs Indexer owns that file (see below).
+
+The synthesizer MUST fail loudly (emit a BLOCKED verdict) if it cannot produce all required subsection anchors — e.g., if the architecture is too thin to have a meaningful `security/auth` section, the synthesizer stubs the anchor with a one-line "N/A — {reason}" rather than omitting it.
+
+## refs.json — the live downstream docs index
+
+`refs.json` is the live downstream docs index. It covers every anchor in:
+
+- `design-doc.md` (THE PRD)
+- `architecture.md`
+- `sprint-tasks.md`
+- `visual-design-spec.md` (if exists)
+- `quality-targets.json` (via flat key anchors)
+
+Writer: Phase 2.2 Refs Indexer step (dispatched as INTERNAL inline role-string). Consumers: Phase 3+ agents via the Briefing Officer per-task context map (no full pastes). Phase 1 raw research files are NOT in `refs.json` — they are spent after Phase 2 hybrid routing distributes them to architects.
+
+The Phase 2.2 Refs Indexer (INTERNAL inline role-string dispatched by the orchestrator) is the sole writer of `refs.json`. It runs after the architecture synthesizer and Sprint Breakdown steps, reads the live docs (`design-doc.md`, `architecture.md`, `sprint-tasks.md`, `visual-design-spec.md` if exists, `quality-targets.json`), and emits the multi-doc anchor index.
+
+See `commands/build.md` Phase 2.2 Step 2.3 Refs Indexer dispatch for the exact generation prompt.
+
+## refs.json example
+
+```json
+{
+  "schema_version": "2.0",
+  "generated_at": "2026-04-13T10:00:00Z",
+  "generated_by": "Phase 2.2 Refs Indexer",
+  "anchors": [
+    {
+      "file_path": "docs/plans/design-doc.md",
+      "anchor": "#persona",
+      "topic": "primary user persona + JTBD",
+      "line_start": 12,
+      "line_end": 38
+    },
+    {
+      "file_path": "docs/plans/architecture.md",
+      "anchor": "#frontend/checkout",
+      "topic": "checkout flow component tree",
+      "line_start": 102,
+      "line_end": 145
+    },
+    {
+      "file_path": "docs/plans/architecture.md",
+      "anchor": "#data-model/orders",
+      "topic": "Orders entity, status enum, relations to users and items",
+      "line_start": 302,
+      "line_end": 358
+    },
+    {
+      "file_path": "docs/plans/sprint-tasks.md",
+      "anchor": "#sprint-1-task-3",
+      "topic": "wire checkout form to /api/checkout",
+      "line_start": 88,
+      "line_end": 104
+    }
+  ]
+}
+```
+
+Fields:
+
+- `schema_version` (string) — currently `"2.0"`. Bumped from `1` when the index was extended from architecture-only to the multi-doc scope above.
+- `generated_at` (ISO 8601) — Refs Indexer run timestamp.
+- `generated_by` (string) — `"Phase 2.2 Refs Indexer"`.
+- `anchors` (array) — one entry per anchor across all indexed files. Each: `{file_path, anchor, topic, line_start, line_end}`.
+  - `file_path` — repo-relative path of the file the anchor lives in. Required. Tells consumers which document to `Read`.
+  - `anchor` — the markdown fragment, including the leading `#` (e.g. `#frontend/checkout`, `#persona`). For `quality-targets.json` entries, the anchor is the flat key name.
+  - `topic` — one-sentence summary used by the Briefing Officer to pick refs without reading the file.
+  - `line_start`, `line_end` — optional but recommended. Allow consumers to `Read` just the section instead of the whole file.
+
+## Validation
+
+A synthesized `architecture.md` plus `refs.json` pair is well-formed iff:
+
+1. All required top-level headings exist in `architecture.md` (grep `^# {Heading}$` for each).
+2. All required subsection anchors resolve to real `## Heading` lines under the correct parent. (A heading `## Checkout` under `# Frontend` resolves the anchor `frontend/checkout`.)
+3. `refs.json` parses as valid JSON against the shape above.
+4. Every architecture-scoped entry in `refs.json.anchors[]` (those with `file_path` ending in `architecture.md`) resolves to a real heading in `architecture.md` at the claimed `line_start`.
+5. Every required anchor from this document appears in `refs.json.anchors` with the correct `file_path`.
+6. No `(file_path, anchor)` pair appears twice in `refs.json.anchors`.
+7. `schema_version` is `"2.0"` and `generated_by` is `"Phase 2.2 Refs Indexer"`.
+
+The Wave 1 `buildanything:verify` protocol runs these checks after Phase 2.3 completes. A failure flips the Phase 2 verdict to `NEEDS_WORK` and re-dispatches the Refs Indexer (or the synthesizer, if the missing anchors indicate `architecture.md` itself is incomplete) with a directive listing the missing anchors.

package/protocols/cleanup.md

@@ -52,3 +52,7 @@ After the cleanup agent finishes, spot-check that acceptance criteria still hold
 - Scope is sacred. Only files from the implementation changeset. Zero exceptions.
 - This runs AFTER implementation, BEFORE the metric loop.
 - If cleanup breaks acceptance criteria, revert and skip. Never block the metric loop on a cleanup failure.
+
+### Build Log Rotation
+
+At Phase 0, if `docs/plans/build-log.md` exceeds 500 lines, archive it to `docs/plans/build-log.prev.md` and start a fresh log. The archived log preserves full history for debugging. The 500-line threshold keeps the active log within a reasonable context budget for agents that read it.

package/protocols/decision-log.md

@@ -0,0 +1,135 @@
+# Decision Log Protocol
+
+This is the append-only decision log that captures rejected alternatives alongside the chosen approach, with a natural-language revisit criterion for each rejection. It feeds two loops: the learnings pipeline at Step 6.0.1 (cross-run PITFALL capture) and the Phase 0 resume handler (preserving the *why* across build sessions). Without this log the build remembers *what* it chose but forgets *what it rejected and under what conditions to reconsider*.
+
+## Schema
+
+Rows live in `docs/plans/decisions.jsonl`, one JSON object per line, append-only. NEVER rewrite or truncate this file.
+
+```json
+{
+  "decision_id": "D-<phase>-<seq>",
+  "phase": "2.2",
+  "timestamp": "<ISO8601>",
+  "decision": "chose SQLite over Postgres for initial persistence",
+  "chosen_approach": "SQLite with single-file .db in project root",
+  "rejected_alternatives": [
+    {
+      "approach": "Postgres via Supabase",
+      "reason": "adds infra setup to Phase 0 prereqs; overkill for single-user app",
+      "revisit_criterion": "multi-user access OR >10k rows OR concurrent writes"
+    }
+  ],
+  "decided_by": "<agent-role-string>",
+  "ref": "architecture.md#backend/persistence",
+  "status": "open"
+}
+```
+
+`decided_by` is a free-form string naming the agent role that authored the decision (e.g., `architect`, `implementer`, `design-brand-guardian`, `ux-architect`, `human`, `design-critic`). The orchestrator does not validate against a fixed enum — the set of writing agents changes as new phases ship, and a brittle whitelist would force a schema migration every time. The LRR Aggregator matches on the string value directly against its known-agent registry; unknown values fall through to the legacy classification path in Step 4.
+
+Findings in LRR chapter verdicts may reference a decision row via the `related_decision_id` field, which the LRR Aggregator uses for backward routing (see `protocols/launch-readiness.md` Aggregator Step 3). The `related_decision_id` lives on the **finding** object inside a chapter verdict, not on the decision row itself — it is the pointer from a finding back to the decision that authored the choice being violated.
+
+The `status` field takes one of three values:
+
+- `open` — decision stands, revisit criterion has not fired
+- `triggered` — Reality Checker matched the revisit criterion against current evidence this build
+- `resolved` — a later decision row supersedes this one; the log still shows both
+
+## Hard Field Constraints
+
+- Max **3 rejected alternatives** per decision row
+- Max **2 sentences** per `reason` field
+- Max **1 sentence** per `revisit_criterion` (natural language assertion)
+- Max **5 decision rows per phase** (typical 2-3)
+- Total per build: **15-25 rows max, ~500-1000 tokens worst case**
+- File path: `docs/plans/decisions.jsonl` — append-only, NEVER rewrite or truncate
+
+A row that exceeds any of these limits is a bug in the writing agent, not a permission to raise the limit. Split one decision into two rows before relaxing the constraints.
+
+## Natural-Language `revisit_criterion` Format
+
+The criterion is a one-sentence assertion the Reality Checker can semantically match against build evidence. Write it as the condition under which the rejected alternative would become correct. Do NOT write it as a metric threshold tied to a Phase 6 vocabulary that may not exist yet.
+
+Examples:
+
+- `"multi-user access OR >10k rows OR concurrent writes"`
+- `"user requests server-side rendering"`
+- `"bundle size exceeds 500KB gzipped"`
+- `"first-paint latency regresses below 2s on 4G"`
+
+If you cannot write the criterion in one sentence, the rejection is probably not yet crisp enough to log — revisit the decision first, log it second.
+
+## Author Assignment
+
+Author = the agent that made the call. The orchestrator NEVER writes decision rows itself.
+
+| Phase | Writer | Example decisions |
+|-------|--------|-------------------|
+| 1 (Brainstorm) | Brainstorm synthesis agent | Tech stack, data model, scope boundary |
+| 2.2 (Architecture) | Architecture synthesizer | API contract, service boundary, persistence, auth model |
+| 3 (Design) | [DEFERRED — currently no author until Phase 3 changes ship] | Visual direction kill rationales |
+| 4 (Build) | Implementer — ONLY if deviating from planned task | Deviation rationale |
+
+Phases 0, 6, 7 do not write decisions.
+
+## Readers
+
+Three consumers, each reads a bounded slice:
+
+1. **Phase 0 Resume Handler (on `--resume`)** — reads the top 5 most recent rows sorted by `decision_id` desc, filtered to the current phase and upstream phases. Injects short fields + `ref` anchor into rehydration context alongside `architecture.md`. Never reads all rows.
+
+2. **Step 6.0 Reality Checker (Dissent Log Revisit Pass)** — reads all rows where `status == "open"` and `revisit_criterion` is non-empty. Semantically evaluates each criterion against the current build's evidence manifest. For any triggered row, emits a structural finding of the form `"revisit-criterion-triggered: D-N-M — [criterion]"` in `specific_findings[]` and contributes to `combined_verdict` (triggered → at minimum NEEDS WORK).
+
+3. **Step 6.0.1 Learnings Harvester** — reads the Reality Checker's triggered findings and appends one PITFALL row per trigger to `learnings.jsonl` with `provenance.decision_id` back-referencing the source row. This is the cross-run PITFALL capture path, distinct from the in-run metric-loop post-hoc harvest.
+
+## Subagents Never Write Directly
+
+Subagents return `deviation_row` objects in their structured result. The orchestrator forwards each row through the `scribe_decision` MCP tool — the single writer for `docs/plans/decisions.jsonl`. The MCP owns `decision_id` allocation (`D-{phase}-<seq>`), stamps `timestamp` and `status: "open"`, validates against `decisions.schema.json`, and atomically appends the line. The orchestrator MUST NOT Write or Edit this file directly; subagents MUST NOT either. Specialist agents still author the row fields to preserve original language — they just don't touch the file.
+
+## Worked Examples
+
+**Phase 2.2 architecture — persistence layer (cross-domain deviation):**
+
+```json
+{
+  "decision_id": "D-2-03",
+  "phase": "2.2",
+  "timestamp": "2026-04-13T16:05:41Z",
+  "decision": "chose SQLite over Postgres for initial persistence",
+  "chosen_approach": "SQLite with single-file .db in project root, migrations via drizzle-kit",
+  "rejected_alternatives": [
+    {
+      "approach": "Postgres via Supabase",
+      "reason": "adds infra setup to Phase 0 prereqs; overkill for single-user app.",
+      "revisit_criterion": "multi-user access OR >10k rows OR concurrent writes"
+    },
+    {
+      "approach": "JSON file on disk",
+      "reason": "no query layer, no migrations, no referential integrity.",
+      "revisit_criterion": "schema stabilizes AND row count stays under 500"
+    }
+  ],
+  "decided_by": "architect",
+  "ref": "architecture.md#backend/persistence",
+  "status": "open"
+}
+```
+
+## Token Budget
+
+| Item | Budget |
+|------|--------|
+| decisions.jsonl on disk per build | 500-1000 tokens worst case |
+| Reality Checker read (Step 6.0) | ~200 tokens |
+| Resume handler read (Phase 0) | ~300 tokens |
+| Learnings harvester read (Step 6.0.1) | ~200 tokens |
+| **Total per build** | **~1.2-1.7K tokens** |
+
+## Ref Field Convention
+
+Every row carries a `ref` anchor (e.g., `architecture.md#backend/persistence` or `visual-design-spec.md#<anchor>`) that downstream readers use to widen context without pasting prose. The resume handler passes the row's short fields *plus* the ref — the resumed agent reads the anchor via its own Read tool if it needs the full context. This matches the existing `refs.json` pattern in `commands/build.md` (primary/secondary anchors handed to implementers instead of pasted content), and keeps rehydration token cost bounded to ~300 tokens for the top 5 rows regardless of how much architectural prose sits behind each anchor.
+
+### Malformed Row Handling
+
+When reading `decisions.jsonl` or `learnings.jsonl`, consumers MUST skip malformed rows (invalid JSON) with a warning logged to `build-log.md` rather than crashing. Shape: `"WARN: skipped malformed row at line N in [file]: [parse error]"`. This prevents a single corrupt append from blocking the entire LRR Aggregator or Learnings Loader.