buildanything 2.0.0 → 2.1.2

package/protocols/state-schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$comment": "Schema version migration table: schema_version 1 = Stages 1-3; schema_version 2 = Stage 4 (adds backward_routing_count, backward_routing_count_by_target_phase, in_flight_backward_edge, mode_transitions); schema_version 3 = Stage 5 (adds lrr_cycle_state); schema_version 4 = Stage 6 (adds current_sprint_context_hash). --- Runtime validation rules (not encodable in JSON Schema, require code): Rule 5 — step prefix must match current phase number; Rule 6 — mode/autonomous consistency (mode==='autonomous' iff autonomous===true); Rule 7 — iOS fields gating (app_name, bundle_id, xcodeproj_path, ios_features, phase_progress.phase_minus_1 exist iff project_type==='ios'); Rule 10 — pending/in-progress disjoint (in_progress_task.task_id not in pending_tasks or completed_tasks); Rule 11 — resume_point.phase/step must not be ahead of top-level phase/step; Rule 12 — timestamps monotonic (session_last_saved >= session_started).",
+  "$comment": "Schema version migration table: schema_version 1 = Stages 1-3; schema_version 2 = Stage 4 (adds backward_routing_count, backward_routing_count_by_target_phase, in_flight_backward_edge, mode_transitions); schema_version 3 = Stage 5 (adds lrr_cycle_state); schema_version 4 = Stage 6 (adds current_sprint_context_hash), schema_version 5 = Stage 7 (adds feature_delegation_plan_path, current_wave, completed_features, feature_acceptance, feature_briefs). --- Runtime validation rules (not encodable in JSON Schema, require code): Rule 5 — step prefix must match current phase number; Rule 6 — mode/autonomous consistency (mode==='autonomous' iff autonomous===true); Rule 7 — iOS fields gating (app_name, bundle_id, xcodeproj_path, ios_features, phase_progress.phase_minus_1 exist iff project_type==='ios'); Rule 10 — pending/in-progress disjoint (in_progress_task.task_id not in pending_tasks or completed_tasks); Rule 11 — resume_point.phase/step must not be ahead of top-level phase/step; Rule 12 — timestamps monotonic (session_last_saved >= session_started).",
   "title": ".build-state.json",
   "description": "Typed source of truth for BuildAnything build state. Validated by the PreToolUse schema lint hook (W2-2). additionalProperties: false enforces fail-closed per A8 SSOT rule.",
   "type": "object",
@@ -229,8 +229,8 @@
     "schema_version": {
       "type": "integer",
       "minimum": 1,
-      "maximum": 4,
-      "description": "Currently 1 (Stages 1-3). Bumped to 2 at Stage 4, 3 at Stage 5, 4 at Stage 6."
+      "maximum": 5,
+      "description": "Currently 5 (Stage 7). Bumped to 2 at Stage 4, 3 at Stage 5, 4 at Stage 6, 5 at Stage 7."
     },
     "project_type": {
       "type": "string",
@@ -349,6 +349,11 @@
       "items": { "$ref": "#/$defs/blocker" },
       "description": "Open blockers. Omitted when empty."
     },
+    "decisions_pruned_at_phase0": {
+      "type": "boolean",
+      "default": false,
+      "description": "Set to true after Phase 0 archives stale decision rows from previous builds"
+    },
     "decisions_next_id": {
       "type": "object",
       "additionalProperties": { "type": "integer", "minimum": 0 },
@@ -383,6 +388,36 @@
     "current_sprint_context_hash": {
       "type": "string",
       "description": "Stage 6+ (schema_version >= 4). Hash of sprint-scoped shared context; triggers re-render only on sprint boundary."
+    },
+
+    "feature_delegation_plan_path": {
+      "type": "string",
+      "$comment": "Stage 7+ (schema_version >= 5). Populated at Phase 4 Step 4.1 by product-owner agent.",
+      "description": "Stage 7+ (schema_version >= 5). Path to feature-delegation-plan.json written by Product Owner in Phase 4 Step 4.1."
+    },
+    "current_wave": {
+      "type": "integer",
+      "minimum": 1,
+      "$comment": "Stage 7+ (schema_version >= 5). Initialized to 1 at Step 4.1; incremented by orchestrator at Step 4.4.",
+      "description": "Stage 7+ (schema_version >= 5). Current wave number in the feature-delegation plan."
+    },
+    "completed_features": {
+      "type": "array",
+      "items": { "type": "string" },
+      "$comment": "Stage 7+ (schema_version >= 5). Append-only. Set by orchestrator after product-owner ACCEPTED verdict.",
+      "description": "Stage 7+ (schema_version >= 5). Feature names accepted by Product Owner."
+    },
+    "feature_acceptance": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "enum": ["ACCEPTED", "NEEDS_REVISION", "PENDING"] },
+      "$comment": "Stage 7+ (schema_version >= 5). Written by orchestrator after each product-owner acceptance dispatch (Step 4.3).",
+      "description": "Stage 7+ (schema_version >= 5). Product Owner acceptance verdict per feature."
+    },
+    "feature_briefs": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "$comment": "Stage 7+ (schema_version >= 5). Written by orchestrator after each briefing-officer dispatch (Step 4.2.a).",
+      "description": "Stage 7+ (schema_version >= 5). Map of feature name to feature brief file path (docs/plans/feature-briefs/{feature}.md)."
     }
   }
 }

package/protocols/state-schema.md

@@ -16,6 +16,7 @@
 | 2 | Stage 4 | `backward_routing_count` (newly typed), `backward_routing_count_by_target_phase`, `in_flight_backward_edge`, `mode_transitions[]` | A7 forward-reject on `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`; A3 stale-edge decrement on `--resume` |
 | 3 | Stage 5 | `lrr_cycle_state` (object; interior fields loose-typed pending Stage 5 iteration — see "Fields added at v3" below) | `BUILDANYTHING_SDK_LRR=false` reverts to markdown aggregator; `lrr_cycle_state` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
 | 4 | Stage 6 | `current_sprint_context_hash` | `BUILDANYTHING_SDK_SPRINT_CONTEXT=false` (web) and/or `BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS=false` (iOS parity gate) reverts Phase 4 to per-task refs re-send; `current_sprint_context_hash` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
+| 5 | Stage 7 | `feature_delegation_plan_path`, `current_wave`, `completed_features`, `feature_acceptance`, `feature_briefs` | Feature-level fields are additive and optional; a Stage 6 runtime reading a Stage 7 state file with `schema_version` downgraded to `4` will ignore these fields without data loss on the read path |
 
 **A7 forward-reject rule.** When `bin/buildanything-runtime.ts` reads `.build-state.json` at session start, if `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`, the runtime refuses to proceed and emits a clear error pointing to the compat matrix (`docs/migration/sdk-host-compat.md`). This is the A7 defense against silent schema drift — an old runtime must never silently ignore fields a newer runtime persisted. See **Task 4.5.2** for the runtime implementation (out of scope for this prose-only update).
 
@@ -23,7 +24,7 @@
 
 ```jsonc
 {
-  "schema_version": 1,
+  "schema_version": 5,
   "project_type": "ios",
   "phase": 6,
   "step": "6.4",
@@ -53,7 +54,7 @@
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `schema_version` | integer | yes | Currently `2` (Stage 4); see version table above. Bumped on each Shape-B migration stage. |
+| `schema_version` | integer | yes | Currently `5`; see version table above. Bumped on each Shape-B migration stage. |
 | `project_type` | enum | yes | `"ios"` or `"web"`. Drives mode-branch routing. |
 | `phase` | integer | yes | Current phase, one of `-1, 0, 1, 2, 3, 4, 5, 6, 7`. |
 | `step` | string | yes | Dotted step identifier within the phase (e.g., `"5.3b"`, `"6.4"`). |
@@ -80,6 +81,11 @@
 | `resume_point` | object | yes | `{phase, step, autonomous, completed_summary, git_branch}`. Snapshot used by Phase-0 resume logic. |
 | `verification` | object | yes | `{last_verify_result, last_verify_timestamp}`. `last_verify_result` is one of `"PRODUCTION_READY"`, `"NEEDS_WORK"`, `"BLOCKED"`, or `null`. |
 | `blockers` | array | no | Open blockers. Each: `{id, description, surfaced_at, type}`. Type is `"build"`, `"design"`, `"dep"`, or `"external"`. |
+| `decisions_pruned_at_phase0` | boolean | no | Default `false`. Set to `true` after Phase 0 archives stale decision rows. |
+
+### Decision Log Pruning (Phase 0)
+
+At Phase 0, if `docs/plans/decisions.jsonl` exists and contains rows from a previous `session_id`, archive them: copy the file to `docs/plans/decisions.jsonl.prev`, then filter `decisions.jsonl` to retain only rows matching the current `session_id`. Set `decisions_pruned_at_phase0: true`. This prevents unbounded growth across builds while preserving history in the `.prev` file. The LRR Aggregator's star rule only needs current-build decisions for backward routing.
 
 ### Fields added at v2 (Stage 4)
 
@@ -118,6 +124,22 @@ These fields are present only when `schema_version >= 4`. They support the Shape
 
 **SSOT note.** Kiro-owned `protocols/state-schema.json` is authoritative: `properties.current_sprint_context_hash` (string) is already declared, `schema_version.maximum` is already `4`, and the top-level `$comment` migration table already lists Stage 6. This prose mirrors that shape; any future interior fields (should the sprint-context module persist more than a hash) will be documented by tightening this entry alongside a JSON Schema update.
 
+### Fields added at v5 (Stage 7)
+
+These fields are present only when `schema_version >= 5`. They support the three-tier feature delegation architecture in Phase 4 — Product Owner planning, Briefing Officer per-feature briefs, and wave-based execution with acceptance gates.
+
+| Field | Type | Required | Added in | Notes |
+|---|---|---|---|---|
+| `feature_delegation_plan_path` | string | no | v5 | Path to `docs/plans/feature-delegation-plan.json`. Set at Step 4.1. |
+| `current_wave` | integer | no | v5 | Current wave being executed (1-indexed). Set at Step 4.1, incremented at Step 4.4. |
+| `completed_features` | string[] | no | v5 | Feature names that have been ACCEPTED by the Product Owner. |
+| `feature_acceptance` | object | no | v5 | Map of feature name → verdict (`ACCEPTED`, `NEEDS_REVISION`, `IN_PROGRESS`). |
+| `feature_briefs` | object | no | v5 | Map of feature name → path to feature brief file (`docs/plans/feature-briefs/{feature}.md`). |
+
+**v5 migration concern — none in wild.** As of this task, Stage 7 has not shipped. No `.build-state.json` files with `schema_version: 5` exist outside development probes. The runtime will be bumped to `5` as part of Stage 7 activation, not here.
+
+**v5 rollback semantics.** All five fields are additive and optional. A Stage 6 runtime reading a Stage 7 state file with `schema_version` downgraded to `4` will ignore these fields without data loss on the read path. Phase 4 simply reverts to the flat per-task execution model without feature-level delegation.
+
 ## Rendering contract
 
 `.build-state.md` is regenerated from `.build-state.json` on every state change by the orchestrator's state-save routine. It is a view, not a source. The rendering is deterministic: same JSON in → same markdown out.
@@ -152,6 +174,10 @@ Direct writes to `.build-state.json` are prohibited — a partial write leaves u
 
 This section is the authoritative write contract. Other protocol/command files that say "write to `.build-state.json`" mean "via this protocol."
 
+### Compaction Safety Net
+
+The PreCompact hook is a prompt-level reminder (type: "prompt"), not a hard command. As defense-in-depth, the `session-start` hook reads `.build-state.json` on every session start and rebuilds TodoWrite from it. If compaction fires without the orchestrator saving state first, the session-start recovery path restores from the last checkpoint. This is a safety net, not a substitute for the orchestrator honoring compaction checkpoints.
+
 ## Validation rules
 
 A well-formed `.build-state.json` must satisfy:
@@ -170,3 +196,7 @@ A well-formed `.build-state.json` must satisfy:
 12. **Timestamps monotonic** — `session_last_saved >= session_started`.
 
 The Wave 2 `PreToolUse` schema lint hook (W2-2) validates every Write|Edit to `.build-state.json` against these rules and denies writes that fail.
+
+## Consumers — non-orchestrator readers of state
+
+- **Step 7.1.5 Completion Report** (`commands/build.md`) reads `backward_routing_count`, `backward_routing_count_by_target_phase`, and `mode_transitions[]` to surface end-of-build quality signals. See `commands/build.md` Step 7.1.5 for the report template.

package/protocols/verify.md

@@ -47,6 +47,27 @@ The agent runs these checks in order, stopping on the first FAIL:
 ONE AGENT, ONE PASS: The orchestrator spawns exactly ONE agent for the entire verification. This is a single Agent tool call, not 6 separate agents. The agent runs each check as a sequential shell command and evaluates the result before proceeding.
 </HARD-GATE>
 
+**Scope macros** (the caller selects which subset of the 7 checks to run):
+
+| Scope | Checks included |
+|-------|-----------------|
+| `full` | All 7 checks (default) |
+| `build` | Check 1 only |
+| `types` | Check 2 only |
+| `lint` | Check 3 only |
+| `test` | Check 4 only |
+| `security` | Check 5 only |
+| `diff` | Check 6 only |
+| `behavioral` | Check 7 only |
+| `static` | Checks 1, 2, 3, 6 (build, types, lint, diff — no test/security/behavioral) |
+| `ci` | Checks 1, 2, 3, 4 (build, types, lint, test — no security/diff/behavioral) |
+
+The `static` macro is the standard Phase 6 post-metric-loop scope — the metric loop owns behavioral evaluation, so Phase 6 verify skips checks 4 (test), 5 (security), and 7 (behavioral).
+
+The `ci` macro is for CI pipeline integration — it runs the four deterministic, automatable checks and skips security (often handled by separate CI tooling), diff review (no uncommitted changes in CI), and behavioral (requires a running app).
+
+If no scope is specified, default to `full`.
+
 ## Step 2b — Test stub detector
 
 After running the Test check in Step 2, AND after running it as PASS, the orchestrator MUST run the test-stub detector. The detector greps every test file in the project's test directory and fails the verification if any file matches a stub pattern.
@@ -105,10 +126,15 @@ exit $EXIT
 
 ## Step 3: Handle Result
 
-**On PASS:** Log `VERIFY: PASS (7/7)` to `docs/plans/.build-state.md`. Proceed to next phase.
+**On PASS:** Return `VERIFY: PASS (N/N)` to the caller via stdout. State persistence is the orchestrator's responsibility (`.build-state.json.verification` is Reality Checker's field, not the gate's). Proceed to next phase.
 
 **On FAIL:** Read the failure reason and spawn a targeted fix agent:
 
+**Fix-agent dispatch mode (SDK-gated — matches `commands/build.md:946`):**
+
+- **`BUILDANYTHING_SDK=on` (default):** dispatch the fix agent through `claude-agent-sdk` with `maxTurns: 15`. This is a hard safety rail preventing runaway remediation loops. If a fix exceeds 15 turns, the orchestrator flags to user (interactive mode) or logs a warning and fails the verify (autonomous mode) — do NOT let the subagent churn indefinitely.
+- **`BUILDANYTHING_SDK=off`:** fall back to Agent tool dispatch with a self-reported 15-tool-call cap (surfaced via `tool_calls_used` in the agent's return). Same enforcement policy as SDK mode.
+
 | Failed Check | Fix Strategy |
 |-------------|-------------|
 | Build / Type-Check / Lint | Run the Build-Fix Protocol (`protocols/build-fix.md`). It isolates the first error, fixes it, rebuilds, detects cascade resolution, and reverts bad fixes automatically. |
@@ -119,6 +145,8 @@ exit $EXIT
 
 After the fix agent completes, re-run verification from Step 2.
 
+**Token accounting (Stage 3 G3):** each fix-agent dispatch emits a cost line to `docs/plans/build-log.md` via `src/orchestrator/hooks/token-accounting-emitter.ts`. Under `BUILDANYTHING_SDK=on`, the emitter subscribes to SDK `usage` messages automatically. Under markdown fallback, the orchestrator writes the line using the subagent's self-reported token count. Verify's fix loop is a known cost hotspot and must be attributed to the parent phase.
+
 <HARD-GATE>
 MAX 3 FIX ATTEMPTS: If verification fails 3 times on the same phase:
 - **Interactive mode:** present the failure history to the user. Ask for direction.