xoai/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:

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] can run in parallel. Running sequentially on this platform." (On Tier 1, dispatch both.)

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:

# 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.
• MAY run parallelizable tasks concurrently on Tier 1 platforms.

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.