buildanything 1.8.0 → 2.0.0

package/protocols/architecture-schema.md

@@ -0,0 +1,171 @@
+# 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`
+- `# MVP 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.
+- `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).
+- `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.
+
+## 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/decision-log.md

@@ -0,0 +1,131 @@
+# 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 MVP 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 MVP",
+      "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 MVP 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 MVP.",
+      "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.

package/protocols/ios-context.md

@@ -4,7 +4,7 @@ _Loaded by every iOS implementation agent when `project_type=ios`. Not loaded in
 
 ## Credits
 - Core rules derived from **twostraws/SwiftAgents** (Paul Hudson) — MIT-style open guide.
-- HIG baseline + iOS 26 platform awareness adapted from **johnrogers/claude-swift-engineering** skills (`ios-hig`, `ios-26-platform`).
+- HIG baseline + iOS 26 platform awareness adapted from **johnrogers/claude-swift-engineering** skills (granular `hig-foundations` + `hig-components-*` family, `ios-26-platform`).
 - Tool-preference hierarchy and post-training-cutoff watch-terms **paraphrased** from Apple's Xcode 26 `AgentSystemPromptAddition` template (Apple copyright — paraphrased, never quoted).
 
 ---
@@ -114,7 +114,7 @@ Glass applies to navigation chrome only, never content; gate iOS 26 APIs behind
 
 ## 8. HIG Compliance Baseline
 
-HIG compliance — see `skills/ios/ios-hig/` for full reference.
+HIG compliance — start with `skills/ios/hig-foundations/`; granular `skills/ios/hig-components-*` skills (content, controls, dialogs, layout, menus, search, status, system) cover specific component categories, and `hig-inputs`, `hig-patterns`, `hig-platforms`, `hig-project-context`, `hig-technologies` cover the remaining HIG surface area.
 Non-negotiables: 44pt touch targets, Dynamic Type support, dark mode parity, VoiceOver labels, Reduce Motion respect.
 Permission requests must be contextual with purpose strings; haptics rare and meaningful only.
 
@@ -129,7 +129,7 @@ Permission requests must be contextual with purpose strings; haptics rare and me
 - Documentation comments on public API.
 - **Never commit secrets.** API keys go in `.xcconfig` (gitignored) or the keychain.
 - **Localization:** if the project uses `Localizable.xcstrings`, add user-facing strings as **symbol keys** (e.g. `helloWorld`) with `extractionState: "manual"`, accessed via generated symbols: `Text(.helloWorld)`. Offer to translate new keys into all supported languages.
-- **PrivacyInfo.xcprivacy ownership:** the `ios-info-plist-hardening` skill (Phase 4 Foundation) owns creating `PrivacyInfo.xcprivacy` — NOT Phase 7 Ship. Any required-reason API declarations, tracking domains, and collected-data-type entries must land in Phase 4 alongside Info.plist hardening.
+- **PrivacyInfo.xcprivacy ownership:** the `ios-info-plist-hardening` skill (Phase 4 Step 4.0 Scaffold) owns creating `PrivacyInfo.xcprivacy` — NOT Phase 7 Ship. Any required-reason API declarations, tracking domains, and collected-data-type entries must land in Phase 4 alongside Info.plist hardening.
 
 ---
 
@@ -164,7 +164,7 @@ When MCP servers are available, **always prefer them** over generic file or shel
 
 ## iOS Feature Flag Schema
 
-These flags gate Phase 5 skill loading and Phase 4 entitlement generation. Orchestrator resolves them at the end of Phase 2 (see `commands/build.md` → Phase 2 "Feature Flag Resolution") and persists them to `docs/plans/.build-state.md` under an `ios_features:` key.
+These flags gate Phase 4 per-task skill loading and Phase 4 Step 4.0 entitlement generation. Orchestrator resolves them at the end of Phase 2 (see `commands/build.md` → Phase 2 "Feature Flag Resolution") and persists them to `docs/plans/.build-state.md` under an `ios_features:` key.
 
 ```yaml
 ios_features:
@@ -186,7 +186,7 @@ ios_features:
   appleWatch: bool
 ```
 
-**Read contract:** Phase 4 (`ios-entitlements-generator`) and Phase 5 (skill loader) MUST read this block from `.build-state.md` before acting. A skill gated by flag `X` is loaded only when `ios_features.X == true`. Unset flags default to `false`.
+**Read contract:** Phase 4 Step 4.0 (`ios-entitlements-generator`) and Phase 4 per-task flow (skill loader) MUST read this block from `.build-state.md` before acting. A skill gated by flag `X` is loaded only when `ios_features.X == true`. Unset flags default to `false`.
 
 ---
 
@@ -206,18 +206,17 @@ _Per-phase skill bundle — orchestrator loads the relevant subset based on curr
 
 ### Phase 3 — Design
 - `agents/ios-swift-ui-design.md` — visual intake (mockups → SwiftUI plan)
-- `skills/ios/ios-hig/` — HIG compliance reference
+- `skills/ios/hig-foundations/` + granular `hig-*` skills — HIG compliance (see agent shortlists for per-agent selection)
 - `skills/ios/swiftui-design-principles/` — 10-rule visual polish
 - `skills/ios/swiftui-liquid-glass/` — iOS 26 glass decision tree
-- `skills/ios/writing-for-interfaces/` — microcopy (if not yet ported, TBD)
 
-### Phase 4 — Foundation
+### Phase 4 — Build (Step 4.0 Scaffold)
 - `skills/ios/ios-entitlements-generator/` (stub)
 - `skills/ios/ios-info-plist-hardening/` (stub)
 
-### Phase 5 — Build
+### Phase 4 — Build (Step 4.1+ per-task flow)
 - `skills/ios/swiftui-pro/` (every UI write)
-- `skills/ios/swift-concurrency/` (async/actor/Sendable)
+- `skills/ios/swift-concurrency-6-2/` (async/actor/Sendable — Swift 6.2 single-threaded default)
 - `skills/ios/swiftdata-pro/` (@Model/@Query usage)
 - `skills/ios/swift-accessibility/` (every UI write — a11y first-draft)
 - `skills/ios/swift-security-expert/` (Keychain/Crypto/auth)
@@ -225,7 +224,7 @@ _Per-phase skill bundle — orchestrator loads the relevant subset based on curr
 - AI feature: `agents/ios-foundation-models-specialist.md`
 - IAP feature: `agents/ios-storekit-specialist.md`
 
-### Phase 6 — Harden
+### Phase 5 — Audit
 _Dispatches to `/verify` + `/ux-review` + `/fix` iOS twins in sequence. Each twin has its own skill bundle inline in its command file._
 
 ### Phase 7 — Ship (optional)