build-loop

<!-- sage-metadata cost-tier: sonnet activation: auto tags: [execution, orchestration, build, loop] inputs: [plan, codebase-context, constitution] outputs: [implementation, test-suite, updated-plan] requires: [implement, tdd, coding-principles, quality-review, spec-review, verify-completion, scope-guard] --> # Build Loop Execute the plan, task by task, with quality gates between each one. This is the main execution engine for BUILD and ARCHITECT modes. **Core Principle:** Autonomous but supervised. The agent works through tasks independently, but pauses at checkpoints and escalates when stuck. A beginner should be able to say "go" and watch tasks get completed, knowing they'll be asked before anything surprising happens. ## When to Use After a plan is approved. The user says "go", "start building", "implement", or approves the plan at the checkpoint. ## Process ### Step 1: Read the Plan Load `.sage/work/<active-feature>/plan.md`. Parse: - Total task count - Which tasks are already done (checked boxes `- [x]`) - Which tasks are blocked (dependencies not met) - Which task is next (first unchecked, unblocked task) If ALL tasks are done → skip to Final Review. If NO plan exists → error: "No approved plan found. Run the plan skill first." ### Step 2: Show Status and Start **Sage:** Plan: [feature name] Tasks: [total] tasks in plan. Next: Task [N] — [task name]. Starting Task [N]. I'll commit after each task and check quality. Say "pause" anytime to stop between tasks. ### Step 3: Execute Task For the current task: 0. **Load coding principles** — read `sage/core/capabilities/execution/coding-principles/SKILL.md`. Apply the 7 universal principles to every line written during this task. Announce: "Loading coding principles for implementation." 1. **Read** the task spec from the plan (files, action, test, verify) 2. **Implement** using TDD (`tdd` skill): - Write failing test - Verify it fails for the right reason (on resume, a test the prior session already recorded as written-and-failing is not re-watched — `tdd` § "Inherited red") - Write minimal code to pass - Verify it passes - Refactor if needed 3. **Self-review** using the implement skill's checklist 4. **Commit** with semantic message — on the initiative branch (git-discipline: created at the workflow's Branch Setup step; commits never land on the default branch unless the user declined branching there) The `scope-guard` skill monitors throughout — flags if implementation drifts beyond the task spec. ### Step 4: Run Quality Gates The **deterministic script gates run after EVERY task. This is NOT optional.** Do not skip them because: - "The change was small" - "I already verified during implementation" - "The tests pass, so gates aren't needed" - "This is just a refactor" Script gates run. Every task. No exceptions. After each task, run the quality gate sub-workflow: Gate 1: spec-review → Does implementation match the task spec? Gate 2: constitution → Does it violate any project principles? Gate 3: quality-review → Clean code, security, maintainability? Gate 4: hallucination → All imports, APIs, versions real and correct? Gate 5: verification → Tests pass? Feature works as expected? The judgment gates (1–3) reach their independent verdict via one combined reviewer by default (`gate_review`); the script gates (1-script, 4, 5) run `--quiet`. See `sage/core/workflows/sub-workflows/quality-gates.workflow.md`. **On a RESUMED cycle's close-out** (this session started from `manifest.py resume`), follow the resume close-out economy (`sage/core/workflows/_shared/cycle-protocol.md` § "Resume close-out economy"): run the deterministic script gates per remaining task for fast failure, but **defer the adversarial sub-agent review to ONE combined review over the whole cycle diff at close-out** — the first session already reviewed everything it built; re-running per-task adversarial dispatches over a small delta is the cost the profile targeted. On a first-session build, run the full per-task sequence below. **If gates pass:** Move to next task. Plan checkboxes updated in bulk at the completion checkpoint (Rule 7). **If a gate fails:** - **Minor issue (1 gate, fixable):** Fix it, re-run that gate, continue. - **Major issue (multiple gates, design problem):** Stop and report. When changing approach, log it in the initiative's scratch notes: Append to `.sage/work/[initiative]/scratch.md`: ``` approach-[N]: [what was tried] — [why it failed] ``` If scratch.md has 3+ approaches for the same task, this is a `gotcha` trigger — the sage-self-learning skill MUST store the finding with WHEN/CHECK/BECAUSE format before continuing. **Sage:** Task [N] failed quality gates: Gate 3: Security — SQL injection risk in [file] Gate 5: Verification — test_user_create fails [1] Fix and continue [2] Discuss the approach - **Repeated failure (3x on same gate):** Escalate to human: **Sage:** Task [N] has failed Gate [X] three times. The task spec may be ambiguous or contradictory. Issue: [specific problem] [1] Revise the task spec and retry [2] Skip this task and continue with others [3] Pause and discuss the approach ### Step 5: Inter-Task Checkpoint After every task (or every 3 tasks for long plans), show brief progress: **Sage:** Task [N] complete. Continuing to Task [N+1] — [name]. Say "pause" to stop. **Batch the bookkeeping** (`batch_bookkeeping`, default `true`): defer memory writes and non-essential prose to the completion/session-break checkpoint rather than emitting them per task — and when that checkpoint arrives, apply ALL of it with **one command**, not incremental edits: ```bash python3 sage/runtime/tools/manifest.py close-out <manifest.md> \ --summary "..." --next-step "..." --decision "..." --complete-task N ``` `gate_state` and `updated:` are mechanical (the sync hook and every advance/sync/close-out write own them — never hand-edit either). Keep the one-line progress note above; everything else waits for the close-out command. The manifest bridge at an `[N]`/context-budget break is NOT bookkeeping and is never deferred (`cycle-protocol.md` § Session-break contract) — write it with the same one command. **On a resume close-out, two more of the economy's levers apply here** (see `cycle-protocol.md` § Resume close-out economy): with `resume_memory: skip` (default) the memory store/search is skipped — the brief already carries the context and L2 measured its value at this horizon as null; and with `resume_test_cadence: lean` (default) each step's GREEN runs the targeted test, with the full suite run once at close-out (Gate 5) rather than per task. For tasks marked `[P]` (parallelizable), note: "Tasks [N] and [M] are marked parallel-safe. Running sequentially — concurrent dispatch happens ONLY through `--subagents --parallel` lanes (subagent-execution sub-workflow), never ad-hoc from the inline loop: lanes bring the scheduler, worktrees, caps, and single-writer bookkeeping that ad-hoc concurrency lacks." ### Step 6: Final Review After all tasks complete: 1. Run full quality gates on the COMPLETE implementation (integration check) 2. Verify all tests pass together (not just individually) 3. Check for any TODO/FIXME markers that shouldn't be there Present the result: **Sage:** Implementation complete. Feature: [name] Tests: [count] passing Commits: [count] Quality: All 5 gates passed on final review. [A] Approve — accept the work; branch stays unmerged [M] Merge to [default] — user-gated merge per git-discipline [R] Revise — needs changes [P] PR — create a pull request 🔒 **MANDATORY CHECKPOINT:** Wait for human decision. [M] is the ONLY merge path — [A] never merges. Omit [M] when not a git repository or no initiative branch exists. ### Step 7: Wrap Up Based on human's choice: - **Merge ([M] only):** apply the merge protocol from `sage/core/capabilities/execution/git-discipline/SKILL.md` — preconditions, the merge itself, conflict handling, and the deletion offer all live there; do not restate them here. Omit [M] when not a git repository or no initiative branch exists. - **PR:** Create a pull request with the spec as description - **Keep working:** Note what needs to change, update plan - **Discard:** Revert and clean up Update the initiative's decisions.md (`.sage/work/[initiative]/decisions.md`) if significant — cross-initiative decisions go to the global `.sage/decisions.md`: ```markdown # Progress Mode: idle Feature: [YYYYMMDD-slug] (completed) Phase: done Next: "Tell me what to build next" Updated: <timestamp> ``` ## Fallbacks | Situation | Action | |-----------|--------| | Implementation fails to compile | Run `systematic-debug`, fix, retry | | Test can't be written (untestable design) | Flag to human, suggest interface simplification | | Task is larger than expected | Report: "Task [N] is bigger than planned. Split into [A] and [B]?" | | Discovered bug in existing code | Report: "Found unrelated bug in [X]. Note for later or fix now?" | | Context window getting full | Commit current work, save state, suggest new session | | All tasks done but integration broken | Create an "integration fix" task, add to plan, execute | ## Rules **MUST (violation = lost work or broken trust):** - MUST NOT skip quality gates. They are mandatory, not suggestions. Consolidating the adversarial review into one combined dispatch on resume close-out is not skipping — the deterministic script gates still run every task and the whole-change independent review still happens; what stops is re-reviewing, from scratch, work a prior session already reviewed. - MUST NOT implement multiple tasks without committing between them. - MUST NOT continue past a mandatory checkpoint without human approval. - MUST update plan checkboxes in bulk at the completion checkpoint (Rule 7). - MUST commit current work immediately if the user says "pause" or "stop." **SHOULD (violation = suboptimal experience):** - SHOULD show progress between tasks — the user should never wonder what's happening. - SHOULD proactively save and suggest a new session if context is getting full. - SHOULD present brief inter-task status every 1-3 tasks, not after every line of code. **MAY (context-dependent):** - MAY skip the final review (step 6) if the plan had only 1-2 tasks, since per-task review already covered everything. - MUST NOT run tasks concurrently from this loop — `[P]` is honored only by the `--parallel` lane machinery (opt-in, code-scheduled). ## Failure Modes - **Plan file is missing or corrupted:** Ask the user if a plan exists. If a spec exists, offer to regenerate the plan from it. If neither exists, suggest starting with elicitation. - **Context window fills before all tasks complete:** Commit current work, write a session bridge note, save the plan with current progress, and suggest a new session. Never lose work to context limits. - **Task produces unexpected scope:** If a task turns out to be much larger than planned, STOP. Report to the user: "Task N is bigger than expected. Split into subtasks?" Don't silently expand scope. - **Gate fails repeatedly on the same task:** After 2 failed attempts, stop and report: "Gate [X] keeps failing on task [N]. The issue is [description]. Should I try a different approach or skip this gate with your approval?" - **User goes silent mid-loop:** After completing a task that requires approval, wait. Don't proceed to the next task. The checkpoint exists for human verification.