Implementation Loop

1. Task Execution Loop

Work the tasks in dependency order. Mark a task completed only after each of these holds, in this order:

• Completion signal checked first. If any part of the unit's completion depends on out-of-repo state (a console setting, DNS record, CMS object, live-system rows), that part has no git-derived completion signal: decide it from the observed state of the deliverable, never from a clean tree or a tracker write. Mark it complete only when that state is already satisfied; execute only when it is observably unsatisfied and re-applying is safe or the user has authorized it; otherwise ask or block. If the unit's entire completion signal is repository-derived and that work is already present and matches the plan's intent (files exist with the expected capability, or the unit's Verification criteria are already satisfied by the current code), the work has likely shipped on a prior branch or session. Verify it matches, mark the task complete, and move on. Do not silently reimplement.
• Evidence chosen before behavior changes. Find the existing tests for the files you will change (Test Discovery, below). Choose the evidence strategy for this task before changing behavior: use an existing failing test, update or strengthen an existing test, add a new failing test, add characterization coverage, or record a deliberate no-test exception with replacement verification. For behavior-bearing changes, default to test-first or characterization-first when the current code and its tests make that practical, even if the plan has no Execution note. When the evidence strategy calls for pre-implementation proof, create/update/strengthen the test or characterization coverage now and verify the expected failure or baseline capture before changing production code.
• Built to the plan. Implement following existing conventions and the unit's Patterns to follow. Add, update, or remove any remaining tests needed to match implementation changes.
• Nothing that worked is broken. Run System-Wide Test Check (below). Run tests after changes. If two fixes for the same failing check have not worked, stop patching: name the assumption both fixes relied on and check it, so the next change targets the root cause. When that assumption came from the plan and correcting it stays within the agreed scope, correct it and note what changed; report a blocker only when correcting it would change a settled decision, need authority the run lacks, or need input only the user can give.
• Evidence recorded. Assess testing coverage: did this task change behavior? If yes, were existing tests inspected and were tests written, updated, strengthened, or deliberately left unchanged with a reason? If no tests were added or changed, is the justification deliberate (e.g., pure config, no behavioral change, manual-only surface) and paired with replacement verification? Record verification evidence for the task: behavior-change signal, existing tests inspected, tests added/changed/used unchanged, red failure or characterization observed when applicable, verification run, and any exception reason.

Then mark the task completed in the task tracker and decide whether to commit it (Incremental Commits, below).

When the selected engine is cross-model execution, this loop still decides unit order, the evidence strategy, inspection of what actually changed, authoritative verification, and incremental canonical commits; the worker's authoring follows the serial external-unit protocol in references/cross-model-execution.md. A detached worker process finishing proves only that authoring finished; do not mark the task complete until the controller records the host-owned canonical commit. A unit whose workspace was preserved, or whose restoration is blocked, stops this loop before any fallback, retry, or next unit.

Build what was asked. The plan's units and scope, or the request itself when there is no plan, define what gets built. Add a mechanism neither asked for, such as a guard, retry, fallback, validation layer, option, mode, abstraction, or support on another interface, only when an existing contract requires it or one of these holds:

• Leaving it out lets harm land before anyone catches it. Trace that the failure can actually happen here; something that notices the failure counts, while an instruction asking a person to avoid it, or to clean up by hand afterward, does not.
• Adding it later would be expensive, because it concerns stored data or its format, a public or shared interface, money, or security.

Give a mechanism that passes its smallest form. One that fails is not built: report it with the task's outcome as considered and not built, with one line on why. When you cannot tell, build it. An item the plan already lists as a non-goal stays unbuilt unless implementation turns up evidence the plan did not have; then build it and say what that evidence was. Never narrow requested behavior to fit a safeguard by delaying, gating, capping, or skipping part of what was asked. When a needed safeguard truly conflicts with requested behavior, check whether the plan or request already specified the design that carries the risk. If it did, that trade-off is decided: build it as specified and report the risk. Only a conflict the plan and request leave open is the requester's decision; stop before building either side and ask, or return it as a blocker.

When the work replaces a function, type, or module whose callers are all in this repository, update those callers and remove the old version in the same change instead of keeping it as a wrapper or alias. An interface used outside this repository, or one the plan says to keep, is an existing contract and keeps working.

Batch independent reads within a task: the plan's referenced files, pattern searches, and test discovery don't depend on one another — request them all in one response rather than one per turn. Only the write-and-verify steps are inherently sequential.

For a parallel wave, the loop pauses after every canonical result so the host can integrate it. Inspect the actual result rather than its declared scope, re-run the independence judgment against the advancing tree, and recompute readiness from committed prerequisites. Affected dependents remain queued. An unaffected sibling may continue only after any failed apply or verification has been restored exactly and the prior integration lock released. Re-dispatch a stale or colliding result on the new base, resolve it explicitly, or finish it serially. Never treat a conflict-free apply as proof that the results are compatible. Repeated collision or broad edits disable further parallel waves for the run.

When a unit carries an Execution note, honor its intent rather than matching a fixed vocabulary. For notes that ask for proof-first work, write or identify the relevant failing test before implementation for that unit. For notes that ask for characterization, capture existing behavior before changing it. For notes that point away from unit coverage, run the named replacement verification and record why ordinary tests were not the right proof. For units without an Execution note, make the same decision from code and test discovery: upgrade to proof-first or characterization-first when behavior changes and there is a practical place to test it; proceed pragmatically only when the task is non-behavioral or the exception is deliberate.

Guardrails for execution evidence:

• Do not write the test and implementation in the same step when working proof-first
• Do not skip verifying that a new or changed test fails for the expected reason before implementing the fix or feature
• Do not over-implement beyond the current behavior slice when working proof-first
• Do not add a duplicate regression test when an existing test is the right home; update or strengthen that test instead, then observe the failure before changing code
• A new or changed test must fail when the behavior it names breaks, and keep passing when only the implementation changes. It fails that bar when its expected value comes from the code under test, when a mock or fixture supplies the result the code should produce, or when it asserts calls between internal parts instead of what the code returns, stores, or sends across its boundary
• Do not add a production export, flag, wrapper, or hook that only tests use when the real entry point can drive the behavior; test through that entry point instead
• Skip proof-first discipline for trivial renames, pure configuration, pure styling, generated artifacts, and manual-only surfaces, but record the reason and replacement verification while continuing execution

Test Discovery — Before implementing changes to a file, find its existing test files (search for test/spec files that import, reference, or share naming patterns with the implementation file). When a plan specifies test scenarios or test files, start there, then check for additional test coverage the plan may not have enumerated. Changes to implementation files should be accompanied by corresponding test updates — new tests for new behavior, modified tests for changed behavior, removed or updated tests for deleted behavior.

Evidence Strategy — Test discovery decides where proof belongs:

Test Scenario Completeness — Tests prove the behavior the unit builds. Before writing tests for a feature-bearing unit, make any vague plan scenario concrete (e.g., "validates correctly" becomes named inputs and expected outcomes) from the unit's Goal and Approach. A scenario category the plan left out is not a gap to fill: do not add scenarios for failure handling, validation, or edge cases the unit does not build, and do not build handling so that such a scenario can exist. Draw from these categories where the unit has them: happy path; edge cases in inputs the unit really receives; error paths for failure handling the unit builds; integration across a layer the unit changes, exercised without mocks.

System-Wide Test Check — Before marking a task done, trace what the change touches beyond its own files: callbacks, middleware, observers, and hooks up to two levels out, and any other interface that already exposes the behavior you changed. Read the actual code, not docs. What already worked through those paths must still work, so run or update the tests that cover them. A leaf change that touches none of them passes at once.

1. Incremental Commits

After completing each task, decide whether to commit. Never commit while its tests fail. Heuristic: "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."

If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.

Message convention: match project commit conventions already in context; else match the recent log pattern; else conventional commits (type(scope): description). User override wins.

Preserve the full resolved message as data through the selected engine's canonical commit owner. If that owner cannot accept the full message, stop and report the blocker rather than truncate it or bypass the owner's protocol. Cross-model commits follow the controller integration contract in references/cross-model-execution.md.

For native host-owned Git commits, write the full resolved message to a file outside the repo with your file-write tool. Pass that file to Git so the shell never interprets message text.

Native Git commit workflow:

# 1. Verify tests pass (use project's test command)
# Examples: bin/rails test, npm test, pytest, go test, etc.

# 2. Stage only files related to this logical unit (not `git add .`)
git add <files related to this logical unit>

# 3. Commit with the resolved message, limited to those same paths
git commit -F <message-file> -- <files related to this logical unit>

Note: Incremental commits add no plugin-generated attribution. The final Phase 4 handoff passes branding:on so ce-commit-push-pr can add generic Compound Engineering branding to the PR.

Workers: worker commits follow the No canonical commits rule in references/execution-strategy.md; only the orchestrator makes canonical commits.

1. Simplify as You Go

After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.

Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.

If **ce-simplify-code** is available, invoke it with mode:pipeline at phase boundaries (especially before Phase 3 when the accumulated cluster has >=30 substantive changed code lines — count human-authored code, not total diff lines, so a mostly test-fixture/config/generated/mechanical cluster does not trigger the check). Otherwise, review the changed files yourself for reuse and consolidation opportunities. When invoking it, pass each test the evidence record names as proving the work (a red-before-fix test, characterization coverage, or an existing test used unchanged) as proof-test:<path>, so the simplification leaves that test untouched.

When the plan carries session-settled:-labeled KTDs or Key Decisions, pass the plan path as context for which structures must stay as they are, not as the simplification scope, with the one-line constraint that labeled entries are settled decisions the simplification must preserve (e.g., deliberate duplication stays duplicated).

1. UI Verification (if applicable)

For UI work built from a Figma design, read references/agents/figma-design-sync.md and dispatch a generic subagent seeded with that local prompt to compare the implementation against the design. Do not dispatch a standalone agent by type/name. Apply the reported fixes that hold up against the project's conventions, then compare again until it reports a match or only differences you judge intentional.

For other user-visible UI changes, check the changed UI in a browser at desktop and mobile widths when browser tooling is available. If none is available, review the layout code for overflow and responsive breakage and record that browser verification was unavailable.

1. Track Progress
2. Add a task when requested work turns out larger than expected; a mechanism nobody asked for goes through Build what was asked first
3. When the plan defines U-IDs for Implementation Units, or the plan or origin document carries stable R-IDs (and optionally A/F/AE IDs), reference them in blockers, deferred-work notes, task summaries, and final verification — not routine status updates. U-IDs anchor units across plan edits; R/A/F/AE anchor product intent across the brainstorm-plan handoff. Use the IDs the plan supplies and do not invent ones it does not. This preserves traceability without burying signal under noise.
4. Plan IDs stay out of written files. U-, R-, A-, F-, AE-, and KTD-IDs mean something only to a reader who has the plan open. Keep them out of the files the work writes, including code, comments, docs, scripts, and skills. Where an ID would go, write what the requirement or decision says instead: # allowlist read-only tools, not # (R7).

Settled decisions during implementation

A KTD or Product Contract Key Decision carrying a session-settled: annotation (classes user-directed / user-approved) records a decision the user already made; it is not yours to improve. A product decision's label arrives through the Key Decision whose Governs R… links name your unit's Rs, not through a KTD. This scopes to labeled entries only: details the plan leaves open remain your judgment, and a real defect discovered inside a settled approach is still reported at full strength; the label never suppresses defect evidence. If implementation reveals a labeled decision is unworkable to the point of invalidating it (infeasible, wrong-thing, destructive), that is a genuine blocker: report it rather than silently working around or "fixing" the decision.