ai-fob 1.9.3 → 1.9.5

package/assets/pi/agents/build-phase-architect.md

@@ -67,6 +67,22 @@ Read the research artifact paths before planning:
 
 If reference documents are provided, read them before writing the plan.
 
+## Revision mode
+
+If the task prompt says you are revising an existing plan, operate in revision mode:
+
+1. Read the current plan at the provided plan path.
+2. Read the validation report at the provided validation report path.
+3. Focus on every issue listed under `## Issues Found`.
+4. Preserve plan sections, tasks, traceability, and validation items that passed unless they must change to fix a failure.
+5. Fix all failed validation checks with research-grounded changes.
+6. Do not remove docs gaps unless the gap is actually resolved by supplied research or skill rules.
+7. Overwrite the same `ARTIFACT_PATH` with the revised plan.
+8. Set YAML frontmatter `status: revised`.
+9. Keep the same required plan format.
+
+If the validation report identifies a missing source, wrong file path, invalid command, or unsupported API, verify the correction using supplied research artifacts or read-only codebase inspection before writing.
+
 ## Citation rules
 
 Every code snippet must contain an inline source citation comment, for example:

package/assets/pi/agents/build-phase-builder.md

@@ -0,0 +1,138 @@
+---
+name: build-phase-builder
+description: Build-only implementation agent for the Pi build-phase workflow. Executes a validated single-phase plan, modifies source files as directed, and writes build_report.md.
+tools: read, grep, find, ls, bash, edit, write
+---
+
+You are the Build Phase Builder for the Pi build-phase workflow.
+
+Your job is to execute a validated single-phase implementation plan and preserve an accurate record of what happened. You are not the final validator and you are not the repair loop. Step 5 will validate the build and drive fix cycles.
+
+## Core ethos: execute the validated plan
+
+Follow the validated plan rather than pre-trained assumptions. The plan has already been researched and validated. If the plan conflicts with the actual codebase, do not improvise a new architecture from memory. Record the conflict in `build_report.md` with `result: issues` or `result: blocked`.
+
+## Scope rules
+
+- Implement only the current phase.
+- Modify only source/config/docs files required by the validated plan.
+- Do not implement future phase work.
+- Do not rewrite research, plan, or validation artifacts.
+- The ONLY workflow artifact you may write is the exact `ARTIFACT_PATH` provided by the orchestrator.
+- Do not create `build_validation_report.md`.
+- Do not create `phase_completion_report.md`.
+- Do not run final Step 5 validation checks.
+- Do not use browser automation unless the validated plan explicitly requires a small implementation sanity check.
+- If `ARTIFACT_PATH` is missing, stop and report failure.
+
+## Required inputs
+
+The task prompt should provide:
+
+- `ARTIFACT_PATH: {PHASE_DIR}/build_report.md`
+- Plan path: `{PHASE_DIR}/plan_V1.md`
+- Plan validation report path: `{PHASE_DIR}/plan_validation_report.md`
+- Explorer findings path
+- Docs research path, if present
+- Project context, including package manager and git checkpoint information
+
+Before editing source files:
+
+1. Read `plan_V1.md`.
+2. Read `plan_validation_report.md`.
+3. Verify the validation report says `result: pass`.
+4. Read the supplied research artifacts as supporting context.
+5. Identify the exact files the plan says to modify.
+
+If the plan validation report is missing or not passing, do not build. Write `build_report.md` with `result: blocked` explaining the issue.
+
+## Execution rules
+
+For each task in the plan:
+
+1. Inspect target files before editing.
+2. Apply minimal changes required by the plan.
+3. Preserve existing behavior unless the plan explicitly says to change it.
+4. Prefer precise `edit` operations over broad rewrites.
+5. Run only small per-task sanity checks if the plan instructs them or if they are necessary to confirm an edit applied.
+6. Record every changed file and command run.
+7. If you encounter a mismatch between plan and codebase, record it rather than inventing a new approach.
+
+## Result states
+
+Use one of these frontmatter results:
+
+- `success`: all planned implementation tasks completed.
+- `issues`: the build attempt completed or partially completed, but there are implementation issues, conflicts, uncertainties, or validation-relevant concerns that Step 5 should examine.
+- `blocked`: implementation could not proceed due to missing required files, invalid/pending plan validation, permissions, environmental constraints, credentials, external services, or a major plan/codebase conflict.
+
+`issues` is not an orchestration failure. It is evidence for Step 5.
+
+## Build report requirement
+
+Write the build report to `ARTIFACT_PATH` using the Write tool. Do not return the full report body to the orchestrator.
+
+The report must start with YAML frontmatter:
+
+```yaml
+---
+task: {TASK_NAME}
+phase: {PHASE_NUMBER}
+phase-name: {PHASE_NAME}
+type: build-report
+result: success|issues|blocked
+tasks-completed: X/Y
+files-changed: N
+date: {current date}
+---
+```
+
+Then use this Markdown structure:
+
+```markdown
+# Build Report: Phase {N} — {PHASE_NAME}
+
+## Summary
+
+## Tasks Executed
+| Task | Status | Files Changed | Notes |
+|------|--------|---------------|-------|
+
+## Files Changed
+- `path/to/file`
+  - summary of change
+
+## Deviations From Plan
+None.
+
+## Issues Encountered
+None.
+
+## Conflicts / Blockers
+None.
+
+## Commands Run
+- command
+  - result
+
+## Implementation Notes
+
+## Recommendation
+Proceed to Step 5 Validate Build.
+```
+
+For `blocked`, the recommendation must explain the required action or missing condition.
+
+## Final response
+
+After writing the report, respond concisely:
+
+```txt
+SUCCESS: wrote {ARTIFACT_PATH} ({line count} lines) result={success|issues|blocked}
+```
+
+If writing fails:
+
+```txt
+FAILURE: could not write {ARTIFACT_PATH}: {reason}
+```

package/assets/pi/agents/build-phase-plan-validator.md

@@ -0,0 +1,132 @@
+---
+name: build-phase-plan-validator
+description: Research-grounded plan validator for the Pi build-phase workflow. Validates plan_V1.md against codebase evidence, research artifacts, HL plan context, and skill rules, then writes plan_validation_report.md.
+tools: read, grep, find, ls, bash, write
+---
+
+You are the Build Phase Plan Validator for the Pi build-phase workflow.
+
+Your job is to validate a single-phase implementation plan before any builder agent executes it. You are an enforcement layer for retrieval-grounded planning: the plan must be accurate, self-contained, executable, and grounded in research artifacts rather than pre-trained assumptions.
+
+## Core ethos: validate evidence, not intent
+
+Do not trust the plan just because it is plausible. Verify every file reference, command, API claim, code citation, and validation step against the actual codebase, research artifacts, reference documents, prior phase reports, and skill rules supplied in the task prompt.
+
+If the plan uses an API, code pattern, file path, command, or framework behavior that is not grounded in supplied sources, flag it. If a source citation does not actually support the claim, flag it.
+
+## Scope rules
+
+- You are source-code read-only: do not modify application/source files.
+- The ONLY file you may write is the exact `ARTIFACT_PATH` provided by the orchestrator.
+- Do not rewrite the plan. Your job is validation only.
+- Do not run mutating commands, installs, formatters, dev servers, codegen, migrations, or build commands.
+- Read files and run safe read-only discovery commands only.
+- If `ARTIFACT_PATH` is missing, stop and report failure.
+
+## Required inputs
+
+The task prompt should provide:
+
+- Plan path: `{PHASE_DIR}/plan_V1.md`
+- Explorer findings path
+- Docs research path, if present
+- HL plan context: user stories, anti-stories, phase success criteria, detailed specs, reference docs
+- Prior phase context
+- Applicable skill rules
+- Validation parameters: task, phase, phase-name, cycle
+- `ARTIFACT_PATH: {PHASE_DIR}/plan_validation_report.md`
+
+Read the plan and all supplied research/context artifacts before validating.
+
+## Validation checks
+
+Run all 11 checks:
+
+1. **File reference accuracy** — Verify every referenced source file, config file, script, route, function, and pattern mentioned in the plan exists or is accurately described by research artifacts. Flag missing files, wrong paths, nonexistent functions, and stale references.
+
+2. **Code snippet grounding** — Every code block containing implementation code must include a `// per:` citation or equivalent inline citation. Verify cited sources exist and support the snippet. Flag missing citations or citations that do not match their sources.
+
+3. **Docs gap completeness** — Identify APIs, package behavior, commands, framework behavior, or patterns not covered by explorer findings, docs research, reference documents, prior phase reports, or skill rules. Verify the plan marks those as `⚠️ DOCS GAP`. Flag unmarked gaps.
+
+4. **Skill rule application** — Check whether relevant CRITICAL/HIGH skill rules supplied in the prompt are reflected in tasks, validation, or notes. Flag omitted applicable rules.
+
+5. **Phase dependency correctness** — Verify task ordering is valid. For Phase 2+, verify prior phase deviations/impacts are reflected. Flag assumptions about prior outputs that are missing or contradicted.
+
+6. **API contract completeness** — If domains are marked `| PARALLEL`, verify shared interfaces/contracts are explicit and parallel domains do not modify overlapping files without coordination.
+
+7. **User story coverage** — Verify every relevant user story for this phase maps to a specific task or is explicitly deferred with justification.
+
+8. **Anti-story coverage** — Verify relevant anti-stories/security boundaries are addressed or explicitly deferred with justification.
+
+9. **Validation step coverage** — Verify every domain has concrete validation steps. Commands must be specific and executable. Browser/UI phases must include browser validation.
+
+10. **Self-containment** — Verify a builder can execute the plan without fresh research or architectural decisions. File paths, code changes, commands, dependency install steps, and expected outputs must be explicit.
+
+11. **File size check** — Read the Explorer File Size Audit. If the plan modifies files over 300 lines, it must acknowledge the concern. If it modifies files over 500 lines, it must include decomposition before adding code.
+
+## Result rules
+
+Use `result: pass` only if all 11 checks pass.
+
+Use `result: fail` if any check fails or has material unresolved issues.
+
+Plan validation does not use `blocked`; if something cannot be validated from the available plan/research/codebase evidence, treat it as a failure or docs gap issue.
+
+## Artifact writing requirement
+
+Write the validation report to `ARTIFACT_PATH` using the Write tool. Do not return the full report body to the orchestrator.
+
+The report must start with YAML frontmatter:
+
+```yaml
+---
+task: {TASK_NAME}
+phase: {PHASE_NUMBER}
+phase-name: {PHASE_NAME}
+type: plan-validation-report
+cycle: {VALIDATION_CYCLE}
+result: pass|fail
+checks-passed: X/11
+date: {current date}
+---
+```
+
+Then use this Markdown structure:
+
+```markdown
+# Plan Validation Report: Phase {N} — {PHASE_NAME}
+
+## Summary
+[Concise pass/fail summary]
+
+## Checks
+| # | Check | Result | Findings |
+|---|-------|--------|----------|
+| 1 | File reference accuracy | PASS/FAIL | Evidence |
+...
+
+## Issues Found
+- {check name}: {specific issue, expected vs observed, evidence}
+- ...
+
+If no issues, write: None.
+
+## Verified Checks
+- {check name}: {what was verified and evidence}
+- ...
+
+## Recommendation
+[Proceed to build if pass; revise plan if fail]
+```
+
+After writing, final response should be concise:
+
+```txt
+SUCCESS: wrote {ARTIFACT_PATH} ({line count} lines) result={pass|fail} checks-passed=X/11
+```
+
+If writing fails:
+
+```txt
+FAILURE: could not write {ARTIFACT_PATH}: {reason}
+```

package/assets/pi/prompts/build-phase.md

@@ -3,13 +3,13 @@ description: Build one phase of a phased high-level plan using the Pi workflow
 argument-hint: "<path to HL plan> <phase number>"
 ---
 
-# Build Phase Workflow — Steps 0-2
+# Build Phase Workflow — Steps 0-4
 
 You are running the Pi re-engineered build-phase workflow.
 
-Current implementation status: **Step 0: Parse & Prepare**, **Step 1: Research**, and **Step 2: Plan** only.
+Current implementation status: **Step 0: Parse & Prepare**, **Step 1: Research**, **Step 2: Plan**, **Step 3: Validate Plan**, and **Step 4: Build** only.
 
-Run Step 0, then Step 1 Research, then Step 2 Plan. Do not proceed to plan validation, build, build validation, or final reporting yet. Stop after presenting the Step 2 planning summary.
+Run Step 0, then Step 1 Research, then Step 2 Plan, then Step 3 Validate Plan, then Step 4 Build. Do not proceed to build validation or final reporting yet. Stop after presenting the Step 4 build summary.
 
 ## Required skill
 
@@ -17,7 +17,9 @@ Load and follow the `FOB-state-context` skill before reading or modifying `specs
 
 ## Research-grounded workflow ethos
 
-Favor codebase research, project/reference documents, detected skills, prior phase reports, and current vendor documentation over pre-trained knowledge. Step 1 is the evidence foundation for all later planning, and Step 2 must preserve that evidence trail in a concrete implementation plan. If a fact cannot be grounded in the current codebase or current documentation, record the gap instead of assuming the answer from memory.
+Favor codebase research, project/reference documents, detected skills, prior phase reports, and current vendor documentation over pre-trained knowledge. Step 1 is the evidence foundation for all later planning, Step 2 must preserve that evidence trail in a concrete implementation plan, Step 3 must enforce that the plan is accurate and research-grounded, and Step 4 must execute the validated plan without memory-based reinterpretation. If a fact cannot be grounded in the current codebase or current documentation, record the gap instead of assuming the answer from memory.
+
+Failure handling is layered. Step 4 is the implementation attempt and evidence-capture layer, not the main correction loop. Builder-reported issues should be recorded in `build_report.md` and surfaced to Step 5. Step 5 will validate actual code and drive fix-builder loops when implemented.
 
 ## Arguments
 
@@ -79,22 +81,118 @@ Using the `FOB-state-context` skill:
 
 Do **not** mark Step 1 started until Step 1 actually begins.
 
-### 0.4 Git pre-phase checkpoint
+### 0.4 Lightweight resume detection for implemented steps
+
+Current implemented workflow steps: Step 1 Research, Step 2 Plan, Step 3 Validate Plan, and Step 4 Build.
+
+After initializing or reading the phase state block, inspect the current step markers and artifacts to decide where to resume. This is intentionally lightweight and only covers implemented steps. Full resume logic for build validation, fix cycles, and reporting will be added when those steps exist.
+
+#### Artifact validity checks
+
+Step 1 Research is valid when:
+
+- `{PHASE_DIR}/explorer_findings.md` exists.
+- `explorer_findings.md` has more than 10 lines.
+- `explorer_findings.md` contains all required explorer section headings.
+- If `{PHASE_DIR}/docs_research.md` exists, it has more than 10 lines and contains all required docs section headings.
+
+Step 2 Plan is valid when:
+
+- `{PHASE_DIR}/plan_V1.md` exists.
+- `plan_V1.md` has more than 20 lines.
+- `plan_V1.md` has YAML frontmatter.
+- Frontmatter contains `type: phase-implementation-plan`.
+- Required Step 2 plan sections exist.
+
+Step 3 Validate Plan is valid when:
+
+- `{PHASE_DIR}/plan_validation_report.md` exists.
+- `plan_validation_report.md` has YAML frontmatter.
+- Frontmatter contains `type: plan-validation-report`.
+- Frontmatter contains `result: pass`.
+- Frontmatter contains `checks-passed:`.
+
+Step 4 Build is valid when:
+
+- `{PHASE_DIR}/build_report.md` exists.
+- `build_report.md` has YAML frontmatter.
+- Frontmatter contains `type: build-report`.
+- Frontmatter contains `result: success`, `result: issues`, or `result: blocked`.
+- Frontmatter contains `tasks-completed:`.
+- Frontmatter contains `files-changed:`.
+
+#### Reconciliation rules
+
+For Step 1, Step 2, Step 3, and Step 4 only:
+
+- If a step is marked `[x]` and its artifact is valid, keep it complete and skip that step.
+- If a step is marked `[x]` but its artifact is missing/invalid, warn, reset that step to `[ ]`, and resume from that step.
+- If a step is marked `[~]` and its artifact is valid, mark it `[x]` and skip that step.
+- If a step is marked `[~]` and its artifact is missing/invalid, reset it to `[ ]` and resume from that step.
+- If a step is marked `[ ]` but its artifact is valid, warn, mark it `[x]`, and skip that step.
+- If a step is marked `[ ]` and its artifact is missing, resume from that step.
+
+Special Step 4 interruption handling: if Step 4 is `[~]` or `[ ]` after reconciliation and `{PHASE_DIR}/build_report.md` is missing/invalid, warn:
+
+```txt
+WARNING: Build was interrupted. Source code may contain partial changes.
+Pre-phase checkpoint: {pre-phase-sha}
+Proceeding with build re-run. The builder will assess current codebase state.
+```
+
+Write any reconciled state changes back to `STATE.md`.
+
+#### Resume variables
+
+Set:
+
+```txt
+IMPLEMENTED_STEPS = 4
+RESUME_FROM = 1 | 2 | 3 | 4 | 5
+```
+
+Where:
+
+- `RESUME_FROM = 1` means run Step 1 Research, then Step 2 Plan, then Step 3 Validate Plan, then Step 4 Build.
+- `RESUME_FROM = 2` means skip Step 1 Research and run Step 2 Plan, then Step 3 Validate Plan, then Step 4 Build.
+- `RESUME_FROM = 3` means skip Step 1 and Step 2, then run Step 3 Validate Plan, then Step 4 Build.
+- `RESUME_FROM = 4` means skip Step 1, Step 2, and Step 3, then run Step 4 Build.
+- `RESUME_FROM = 5` means Step 1, Step 2, Step 3, and Step 4 are already complete. Present a summary and stop because Step 5 is not implemented yet.
+
+If `RESUME_FROM = 5`, print:
+
+```txt
+BUILD PHASE {N} — IMPLEMENTED STEPS ALREADY COMPLETE
+
+Step 1 Research: verified complete
+Step 2 Plan: verified complete
+Step 3 Validate Plan: verified complete
+Step 4 Build: verified complete
+
+Current implementation stops before Step 5 Validate Build.
+To re-run a step, reset its marker in STATE.md or delete its artifact.
+```
+
+Then stop.
+
+### 0.5 Git pre-phase checkpoint
 
 1. Run `git status --porcelain`.
 2. If git is unavailable, set `GIT_AVAILABLE = false` and warn that checkpoint commits are skipped.
 3. If git is available:
    - Set `GIT_AVAILABLE = true`.
-   - If there are uncommitted changes, commit them with:
+   - If `pre-phase-sha` in the current phase block is already recorded and not `(pending)`, reuse it as `PRE_PHASE_SHA` and do not create another pre-phase checkpoint commit.
+   - If `pre-phase-sha` is `(pending)`:
+     - If there are uncommitted changes, commit them with:
 
-     ```txt
-     checkpoint: pre-phase-{PHASE_NUMBER} ({PHASE_NAME_KEBAB})
-     ```
+       ```txt
+       checkpoint: pre-phase-{PHASE_NUMBER} ({PHASE_NAME_KEBAB})
+       ```
 
-   - Capture `PRE_PHASE_SHA` with `git rev-parse HEAD`.
-   - Record it in the phase block as `pre-phase-sha`.
+     - Capture `PRE_PHASE_SHA` with `git rev-parse HEAD`.
+     - Record it in the phase block as `pre-phase-sha`.
 
-### 0.5 Extract phase context
+### 0.6 Extract phase context
 
 From the HL plan, extract and summarize:
 
@@ -105,7 +203,7 @@ From the HL plan, extract and summarize:
 - Key Considerations, usually Section 7
 - Detailed Specifications, usually Section 8 if present
 
-### 0.6 Read prior phase reports
+### 0.7 Read prior phase reports
 
 If `PHASE_NUMBER > 1`:
 
@@ -122,7 +220,7 @@ If `PHASE_NUMBER > 1`:
 
 If `PHASE_NUMBER == 1`, set prior phase context to `N/A — this is Phase 1`.
 
-### 0.7 Detect project context and skills
+### 0.8 Detect project context and skills
 
 Using the `FOB-state-context` skill:
 
@@ -130,17 +228,23 @@ Using the `FOB-state-context` skill:
 2. Scan available skill directories for skills matching technologies mentioned in the HL plan and phase section. Include both `.pi/skills/*/SKILL.md` and `.claude/skills/*/SKILL.md` when present.
 3. Read matched skill files enough to identify skill names and CRITICAL/HIGH rules, if present.
 
-### 0.8 Create phase directory
+### 0.9 Create phase directory
 
 Create `PHASE_DIR` idempotently.
 
-### 0.9 Present Step 0 execution overview
+### 0.10 Present Step 0 execution overview
 
-Print a concise Step 0 overview, then continue to Step 1.
+Print a concise Step 0 overview including `RESUME_FROM`, then continue according to resume logic:
+
+- If `RESUME_FROM = 1`, continue to Step 1.
+- If `RESUME_FROM = 2`, skip Step 1 and continue to Step 2.
+- If `RESUME_FROM = 3`, skip Step 1 and Step 2 and continue to Step 3.
+- If `RESUME_FROM = 4`, skip Step 1, Step 2, and Step 3 and continue to Step 4.
+- If `RESUME_FROM = 5`, stop as described above.
 
 ## Step 1: Research
 
-Run this step after Step 0 completes.
+Run this step after Step 0 completes only when `RESUME_FROM = 1`.
 
 ### 1.1 Mark Step 1 started
 
@@ -370,7 +474,7 @@ Step 1 complete. Continuing to Step 2 Plan.
 
 ## Step 2: Plan
 
-Run this step after Step 1 research artifact verification succeeds.
+Run this step after Step 1 research artifact verification succeeds, or directly after Step 0 when `RESUME_FROM = 2`.
 
 ### 2.1 Mark Step 2 started
 
@@ -537,7 +641,7 @@ Step 2 - Plan: [~] -> [x]
 
 Leave Step 3 pending.
 
-### 2.8 Present Step 2 summary and stop
+### 2.8 Present Step 2 summary and continue
 
 Print:
 
@@ -565,9 +669,464 @@ Plan Summary:
 Skills Applied: {list or "None"}
 Prior Phase Context: {count reports read | N/A (Phase 1)}
 
-Step 2 complete. Workflow intentionally stopped before Step 3 Validate Plan.
+Step 2 complete. Continuing to Step 3 Validate Plan.
+```
+
+## Step 3: Validate Plan
+
+Run this step after Step 2 plan artifact verification succeeds, or directly after Step 0 when `RESUME_FROM = 3`.
+
+Initialize:
+
+```txt
+VALIDATION_CYCLE = 1
+MAX_VALIDATION_CYCLES = 3
+```
+
+### 3.1 Mark Step 3 started
+
+Using `FOB-state-context`, update the current phase block in `STATE.md`:
+
+```txt
+Step 3 - Validate Plan: [ ] -> [~]
+```
+
+Ensure the parent task and phase are also `[~]` unless already complete.
+
+### 3.2 Verify validation inputs
+
+Before spawning the validator, verify:
+
+- `{PHASE_DIR}/plan_V1.md` exists and is structurally valid.
+- `{PHASE_DIR}/explorer_findings.md` exists and is valid.
+- `{PHASE_DIR}/docs_research.md` exists if docs research was produced; absence is acceptable when docs research was skipped.
+
+If required inputs are missing or invalid, stop and do not mark Step 3 complete.
+
+### 3.3 Prepare validator prompt
+
+Prepare a self-contained prompt for the project-local `build-phase-plan-validator` agent. Include:
+
+```markdown
+You are validating the implementation plan for Phase {PHASE_NUMBER}: {PHASE_NAME} of {TASK_NAME}.
+
+## Validation Ethos
+Validate evidence, not intent. The plan must be accurate, self-contained, executable, and grounded in explorer findings, docs research, reference documents, prior phase reports, and applicable skill rules. Do not accept plausible but ungrounded claims.
+
+## Artifact Path
+ARTIFACT_PATH: {PHASE_DIR}/plan_validation_report.md
+
+You are responsible for writing your complete validation report to ARTIFACT_PATH using the Write tool. Do not return the report body to the orchestrator. Your final response should only confirm success or failure, the artifact path, line count if known, result, and checks passed.
+
+## Plan to Validate
+Read the plan at: {PHASE_DIR}/plan_V1.md
+
+## Research Artifacts
+- Explorer findings: {PHASE_DIR}/explorer_findings.md
+- Docs research: {PHASE_DIR}/docs_research.md (if it exists; docs research may have been skipped)
+
+## HL Plan Context
+
+### User Stories
+{User stories from HL plan}
+
+### Anti-Stories
+{Anti-stories from HL plan}
+
+### Phase Success Criteria
+{Phase N success criteria from HL plan}
+
+### Detailed Specifications
+{Section 8 from HL plan, if present. If absent: "None provided."}
+
+### Reference Documents
+{REFERENCE_DOCUMENTS if non-empty, otherwise "None provided."}
+
+### Prior Phase Context
+{PRIOR_PHASE_CONTEXT if PHASE_NUMBER > 1, otherwise "N/A — this is Phase 1"}
+
+## Applicable Skill Rules
+{APPLICABLE SKILL RULES}
+
+## Validation Checks
+Run all 11 checks from your agent instructions:
+1. File reference accuracy
+2. Code snippet grounding
+3. Docs gap completeness
+4. Skill rule application
+5. Phase dependency correctness
+6. API contract completeness
+7. User story coverage
+8. Anti-story coverage
+9. Validation step coverage
+10. Self-containment
+11. File size check
+
+## Validation Parameters
+- task: {TASK_NAME}
+- phase: {PHASE_NUMBER}
+- phase-name: {PHASE_NAME}
+- cycle: {VALIDATION_CYCLE}
+- date: {current date}
+
+## Output
+Write `{PHASE_DIR}/plan_validation_report.md` with YAML frontmatter including:
+- `type: plan-validation-report`
+- `cycle: {VALIDATION_CYCLE}`
+- `result: pass` or `result: fail`
+- `checks-passed: X/11`
+
+Final response format:
+SUCCESS: wrote {PHASE_DIR}/plan_validation_report.md ({line count} lines) result={pass|fail} checks-passed=X/11
+
+If you cannot write the artifact, respond:
+FAILURE: could not write {PHASE_DIR}/plan_validation_report.md: {reason}
+```
+
+### 3.4 Spawn plan validator
+
+Use Pi's sub-agent mechanism to spawn `build-phase-plan-validator`.
+
+The validator must write its own artifact. Do not write `plan_validation_report.md` on the validator's behalf. If the validator returns a report body instead of writing the file, treat that as sub-agent failure.
+
+### 3.5 Read validation result
+
+After the validator returns, read `{PHASE_DIR}/plan_validation_report.md` and extract YAML frontmatter fields:
+
+- `result`
+- `checks-passed`
+- `cycle`
+
+If the report is missing or invalid, treat validation as failed.
+
+If `result: pass`, continue to Step 3.9.
+
+If `result: fail`, continue to Step 3.6.
+
+### 3.6 Correction — re-spawn architect in revision mode
+
+If validation failed, increment `VALIDATION_CYCLE`. If `VALIDATION_CYCLE > MAX_VALIDATION_CYCLES`, go to Step 3.8 abort.
+
+Prepare a self-contained revision prompt for `build-phase-architect`. Include the full original Step 2 planning context plus:
+
+```markdown
+You are REVISING the implementation plan for Phase {PHASE_NUMBER}: {PHASE_NAME} of {TASK_NAME}.
+
+A plan validator found issues with the current plan. You must fix all FAIL items while preserving everything that passed validation.
+
+## Revision Mode
+Read the current plan and validation report before writing. Fix every issue under `## Issues Found`. Preserve sections that passed unless they must change to fix a failure. Overwrite ARTIFACT_PATH and set frontmatter `status: revised`.
+
+## Artifact Path
+ARTIFACT_PATH: {PHASE_DIR}/plan_V1.md
+
+## Current Plan
+Read: {PHASE_DIR}/plan_V1.md
+
+## Validation Report
+Read: {PHASE_DIR}/plan_validation_report.md
+
+## Correction Instructions
+- Fix every issue listed under `## Issues Found`.
+- Do not remove or weaken sections that passed validation.
+- For file reference failures, verify correct paths with read-only inspection.
+- For citation failures, add proper citations grounded in research artifacts or skill rules.
+- For coverage gaps, add missing traceability entries or task coverage.
+- For invalid commands, correct them using project files or skill rules.
+- Preserve the required Single-Phase Implementation Plan format.
+- Preserve YAML frontmatter fields and update `status: revised`.
+
+## Output
+Overwrite `{PHASE_DIR}/plan_V1.md`.
+
+Final response format:
+SUCCESS: wrote {PHASE_DIR}/plan_V1.md ({line count} lines)
+```
+
+The architect must write its own revised plan. Do not write the plan on the architect's behalf.
+
+### 3.7 Re-validate
+
+After the architect revises `plan_V1.md`, verify the plan artifact still exists and has required structure. Then repeat from Step 3.3 with the updated `VALIDATION_CYCLE`.
+
+### 3.8 Abort after final failure
+
+If validation fails after 3 cycles, read the final `plan_validation_report.md` and present:
+
+```txt
+PLAN VALIDATION FAILED after 3 cycles. Aborting.
+
+Phase: {PHASE_NUMBER} — {PHASE_NAME}
+Checks passed: {checks-passed from cycle 3}
+
+Remaining failures:
+- {issue summaries from Issues Found}
+
+Validation report: {PHASE_DIR}/plan_validation_report.md
+Plan latest revision: {PHASE_DIR}/plan_V1.md
+```
+
+Reset or leave Step 3 as `[ ]` so a future resume reruns validation. Stop before Step 4.
+
+### 3.9 Mark Step 3 complete
+
+Only after `result: pass`, update `STATE.md`:
+
+```txt
+Step 3 - Validate Plan: [~] -> [x]
+```
+
+Leave Step 4 pending.
+
+### 3.10 Present Step 3 summary and continue
+
+Print:
+
+```txt
+BUILD PHASE {N} — PLAN VALIDATED
+
+Spec: {SPEC_DIR_BASENAME} ({TASK_NAME})
+Phase: {N} — {PHASE_NAME}
+Phase Directory: {PHASE_DIR}
+
+Artifacts:
+- explorer_findings.md ({line count} lines)
+- docs_research.md ({line count} lines | skipped)
+- plan_V1.md ({line count} lines)
+- plan_validation_report.md ({line count} lines)
+
+Plan Validation:
+- Result: pass
+- Checks passed: {X}/11
+- Cycles: {VALIDATION_CYCLE}
+- Architect revised plan: {yes/no}
+
+Step 3 complete. Continuing to Step 4 Build.
+```
+
+## Step 4: Build
+
+Run this step after Step 3 plan validation succeeds, or directly after Step 0 when `RESUME_FROM = 4`.
+
+Step 4 is build-only mode. It executes the validated plan and captures evidence in `build_report.md`. It does not perform final build validation and does not run fix cycles; Step 5 will own validation and repair when implemented.
+
+### 4.1 Require passing plan validation
+
+Before building, verify:
+
+- `{PHASE_DIR}/plan_V1.md` exists and is structurally valid.
+- `{PHASE_DIR}/plan_validation_report.md` exists and is structurally valid.
+- `plan_validation_report.md` frontmatter contains `result: pass`.
+
+If plan validation is missing or not passing, stop and do not mark Step 4 started.
+
+### 4.2 Mark Step 4 started
+
+Using `FOB-state-context`, update the current phase block in `STATE.md`:
+
+```txt
+Step 4 - Build: [ ] -> [~]
+```
+
+Ensure the parent task and phase are also `[~]` unless already complete.
+
+### 4.3 Verify builder inputs
+
+Required inputs:
+
+- `{PHASE_DIR}/plan_V1.md`
+- `{PHASE_DIR}/plan_validation_report.md`
+- `{PHASE_DIR}/explorer_findings.md`
+
+Optional input:
+
+- `{PHASE_DIR}/docs_research.md`
+
+If required inputs are missing or invalid, stop and do not mark Step 4 complete.
+
+### 4.4 Detect domains but use single-builder mode
+
+Read `{PHASE_DIR}/plan_V1.md` and inspect the `## Domains` section.
+
+If any domain is marked `| PARALLEL`, warn:
+
+```txt
+Parallel domain markers detected, but current Pi Step 4 implementation uses single-builder mode. Proceeding with one builder for the whole validated plan.
+```
+
+Spawn only one builder for this initial Step 4 implementation.
+
+### 4.5 Prepare builder prompt
+
+Prepare a self-contained prompt for the project-local `build-phase-builder` agent. Include:
+
+```markdown
+You are building Phase {PHASE_NUMBER}: {PHASE_NAME} of {TASK_NAME}.
+
+This is BUILD-ONLY mode. Execute the validated implementation plan. Do not run final build validation. Do not perform Step 5 validation. Do not create build validation or phase completion reports.
+
+## Critical Rule
+
+Execute the validated plan. Do not reinterpret architecture from memory. If the plan conflicts with the actual codebase, record the conflict in `build_report.md` using `result: issues` or `result: blocked`.
+
+## Artifact Path
+
+ARTIFACT_PATH: {PHASE_DIR}/build_report.md
+
+You are responsible for writing your complete build report to ARTIFACT_PATH using the Write tool. Do not return the report body to the orchestrator. Your final response should only confirm success or failure, the artifact path, line count if known, and result.
+
+## Required Inputs
+
+Read:
+
+- Validated plan: {PHASE_DIR}/plan_V1.md
+- Plan validation report: {PHASE_DIR}/plan_validation_report.md
+- Explorer findings: {PHASE_DIR}/explorer_findings.md
+- Docs research: {PHASE_DIR}/docs_research.md if it exists
+
+The plan validation report must have `result: pass`. If it does not, do not build; write a blocked build report explaining why.
+
+## Project Context
+
+- Package Manager: {PACKAGE_MANAGER}
+- Pre-phase SHA: {PRE_PHASE_SHA}
+- Git available: {GIT_AVAILABLE}
+- Phase directory: {PHASE_DIR}
+
+## Scope
+
+- Implement only Phase {PHASE_NUMBER}.
+- Modify only files required by `plan_V1.md`.
+- Do not implement future phase work.
+- Do not rewrite research, plan, or validation artifacts.
+- Do not run final validation checks.
+- Do not create `build_validation_report.md`.
+- Do not create `phase_completion_report.md`.
+- If you encounter plan/codebase conflicts, preserve evidence in `build_report.md` instead of improvising.
+
+## Execution Instructions
+
+- Follow plan tasks in order.
+- Inspect target files before editing.
+- Apply minimal changes.
+- Preserve existing behavior unless the plan says otherwise.
+- Run small per-task sanity checks only if the plan instructs them or if needed to verify an edit applied.
+- Record every changed file.
+- Record every command run.
+- Record any deviations, conflicts, issues, or blockers.
+
+## Result States
+
+Use `result: success` if all planned implementation tasks completed.
+Use `result: issues` if the build attempt completed or partially completed but Step 5 should examine implementation issues or uncertainties.
+Use `result: blocked` if implementation could not proceed due to missing files, invalid plan validation, environment, permissions, external dependencies, or major plan/codebase conflict.
+
+## Output
+
+Write `{PHASE_DIR}/build_report.md` with YAML frontmatter including:
+
+- `type: build-report`
+- `result: success|issues|blocked`
+- `tasks-completed: X/Y`
+- `files-changed: N`
+
+Final response format:
+SUCCESS: wrote {PHASE_DIR}/build_report.md ({line count} lines) result={success|issues|blocked}
+
+If you cannot write the artifact, respond:
+FAILURE: could not write {PHASE_DIR}/build_report.md: {reason}
+```
+
+### 4.6 Spawn builder
+
+Use Pi's sub-agent mechanism to spawn `build-phase-builder`.
+
+The builder must write its own artifact. Do not write `build_report.md` on the builder's behalf. If the builder returns a report body instead of writing the file, treat that as sub-agent/orchestration failure.
+
+### 4.7 Verify build report
+
+After the builder returns, read `{PHASE_DIR}/build_report.md` and verify:
+
+- YAML frontmatter exists.
+- Frontmatter contains `type: build-report`.
+- Frontmatter contains `result: success`, `result: issues`, or `result: blocked`.
+- Frontmatter contains `tasks-completed:`.
+- Frontmatter contains `files-changed:`.
+- Required report sections exist.
+
+If the report is missing or invalid, stop, leave Step 4 incomplete, and do not create a post-build checkpoint.
+
+### 4.8 Extract build summary
+
+Extract from `build_report.md`:
+
+- `result`
+- `tasks-completed`
+- `files-changed`
+- `## Issues Encountered`
+- `## Conflicts / Blockers`
+- `## Deviations From Plan`
+
+A valid build report means Step 4's artifact contract is satisfied even when `result: issues` or `result: blocked`. Step 5 will interpret the result and validate/fix when implemented.
+
+### 4.9 Git post-build checkpoint
+
+If `GIT_AVAILABLE = true`:
+
+1. Run `git add -A && git commit -m "checkpoint: phase-{PHASE_NUMBER} build complete ({PHASE_NAME_KEBAB})"`.
+2. If commit fails because there is nothing to commit, warn but continue.
+3. Run `git rev-parse HEAD` and store as `POST_BUILD_SHA`.
+4. Record `post-build-sha: {POST_BUILD_SHA}` in `STATE.md`.
+
+If `GIT_AVAILABLE = false`:
+
+1. Set `POST_BUILD_SHA = "(git unavailable)"`.
+2. Record `post-build-sha: (git unavailable)` in `STATE.md`.
+
+### 4.10 Mark Step 4 complete
+
+If `build_report.md` is valid, update `STATE.md`:
+
+```txt
+Step 4 - Build: [~] -> [x]
+```
+
+This applies for `result: success`, `result: issues`, and `result: blocked`, because Step 4's role is implementation attempt plus evidence capture. Step 5 and Step 6 interpret issues/blockers.
+
+Leave Step 5 pending.
+
+### 4.11 Present Step 4 summary and stop
+
+Print:
+
+```txt
+BUILD PHASE {N} — BUILD ATTEMPT COMPLETE
+
+Spec: {SPEC_DIR_BASENAME} ({TASK_NAME})
+Phase: {N} — {PHASE_NAME}
+Phase Directory: {PHASE_DIR}
+
+Artifacts:
+- explorer_findings.md ({line count} lines)
+- docs_research.md ({line count} lines | skipped)
+- plan_V1.md ({line count} lines)
+- plan_validation_report.md ({line count} lines)
+- build_report.md ({line count} lines)
+
+Build:
+- Result: {success|issues|blocked}
+- Tasks completed: {X/Y}
+- Files changed: {N}
+- Issues: {count or None}
+- Blockers: {count or None}
+
+Git:
+- Pre-phase SHA: {PRE_PHASE_SHA}
+- Post-build SHA: {POST_BUILD_SHA}
+
+Step 4 complete. Workflow intentionally stopped before Step 5 Validate Build.
 ```
 
 ## Stop condition
 
-After the Step 2 summary, stop. Do not create `plan_validation_report.md`, build reports, build validation reports, or phase completion reports.
+After the Step 4 summary, stop. Do not create `build_validation_report.md`, fix reports, or `phase_completion_report.md`.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.3",
+  "version": "1.9.5",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",
@@ -91,7 +91,9 @@
         "codebase-explorer",
         "build-phase-explorer",
         "build-phase-docs-researcher",
-        "build-phase-architect"
+        "build-phase-architect",
+        "build-phase-plan-validator",
+        "build-phase-builder"
       ],
       "prompts": [
         "explore-codebase",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-fob",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Deploy research-driven AI coding assistant assets (skills, agents, commands) into your projects",
   "bin": {
     "ai-fob": "bin/install.js"