pb-build

pb-build

Execute the spec task-by-task. The spec is the source of truth.

Workflow

1. Load spec and resolve tasks

• Resolve <spec-dir> from actual directory names under specs/. Never guess.
• Parse ### Task X.Y: blocks (4 fields, schema in docs/contract.md), build the dependency graph from DependsOn (cycle → stop), and execute in dependency order. Independent tasks may run in parallel subagents; same-file tasks must not.

2. Per task — strict TDD loop

1. Red: write the failing test first (unit + property tests where applicable; for bug fixes the reproducer IS the red test) → verify it fails. If you wrote code before the test, delete it and start over.
2. Green: minimum implementation → verify pass.
3. Refactor: clean up → suite still green.
4. Verify layers: per the project testing principle, add integration/E2E/fuzz coverage the task's test matrix calls for — boundary and exception paths included. No production code without a failing test first; no completion claims without fresh evidence (run the command, paste output, check exit code — "should pass" is a lie).

3. Mutation testing — selective and scope-bounded

Mutation testing is very slow. Do NOT run it unconditionally:

• Run it when the task touches core logic with subtle correctness risk (parsers, state machines, gas/crypto/boundary math, concurrency), or when the spec's TDD & Mutation Testing Strategy marks it required.
• Scope it strictly: mutate only the files changed by this task — pb-spec mutate --against <base> or the project's diff-based script. Never whole-repo runs. Prefer targeted selection (e.g. mutmut path filters) to shrink the run further.
• Skip it for infra, config, docs, trivial getters/setters, and UI code.
• Surviving mutants on changed code are test failures: strengthen assertions until they are killed — or record a justified exemption in the task.

4. Failures and handoff

• Per-task failure retry: 1st → retry with the error as hint; 2nd → root-cause analysis before retrying; 3rd → emit a Build Blocked / DCR packet (3 fields: Reason / Requested Change / Impact) and stop, hand off to /pb-refine.
• After each task: flip its Status: to 🟢 DONE in tasks.md and append a one-line result (task, commits, verdict) to the spec's progress notes.
• All tasks done → run the full suite once, emit a handoff summary (what shipped, evidence, next steps). On session resume, trust files over memory.

Constraints

• Never improvise beyond the spec: ambiguity or defect → DCR packet, not silent "improvement".
• The only permitted edits under specs/ are bookkeeping: flipping task Status: markers and

appending progress notes. Any design/content change goes through a DCR packet instead.

• Never commit/push unless explicitly asked.
• Incremental tests after each task; full suite only at the end.
• Match AGENTS.md conventions.