ai-fob 1.9.7 → 1.9.9

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

@@ -44,9 +44,10 @@ Use one result in frontmatter:
 
 - `pass`: every check passed.
 - `fail`: at least one executable check failed. These are potential code issues for a fix-builder.
-- `blocked`: no executable checks failed, but one or more checks could not be executed because of external, environmental, credential, or human-action constraints.
+- `blocked`: no executable checks failed, but one or more **terminal** checks could not be executed because of external, environmental, credential, or human-action constraints that prevent establishing core phase correctness.
+- `pass-with-followups`: no executable checks failed and no terminal blockers exist, but one or more **non-terminal** manual/operator/unsafe/external follow-up checks could not safely run.
 
-If both FAIL and BLOCKED checks exist, overall result is `fail`.
+If both FAIL and BLOCKED checks exist, overall result is `fail`. FAIL beats terminal blockers; terminal blockers beat `pass-with-followups`.
 
 ## Check rules
 
@@ -57,7 +58,10 @@ For every check:
 - Never mark a check PASS because the plan or build report claims it was done.
 - For `[HL]` checks, preserve the user's criterion text and verify independently.
 - If real test credentials are configured, do not mark auth-required browser checks BLOCKED merely because login is required; authenticate and report PASS/FAIL.
-- If placeholder credentials remain and auth is required, mark the auth-required browser check BLOCKED.
+- If placeholder credentials remain and auth is required, mark the auth-required browser check BLOCKED and classify whether that blocker is terminal or non-terminal.
+- For every BLOCKED check, include `severity: terminal` or `severity: non-terminal` in the evidence.
+- Terminal blockers prevent establishing core phase correctness or safe continuation.
+- Non-terminal blockers are manual/operator/unsafe/external follow-ups where core functionality has already been validated through other executable/source/browser evidence.
 
 ## Browser validation rules
 
@@ -111,9 +115,11 @@ phase: {PHASE_NUMBER}
 phase-name: {PHASE_NAME}
 type: build-validation-report
 cycle: {BUILD_VALIDATION_CYCLE}
-result: pass|fail|blocked
+result: pass|fail|blocked|pass-with-followups
 checks-passed: X/Y
 checks-blocked: Z/Y
+checks-blocked-terminal: A/Y
+checks-blocked-nonterminal: B/Y
 date: {current date}
 ---
 ```
@@ -135,10 +141,15 @@ Report structure:
 If no issues, write: None.
 
 ## Blocked Checks
-- {check name}: {blocked reason and required action}
+- {check name}: severity: {terminal|non-terminal}; {blocked reason}; substitute evidence: {evidence or none}; human follow-up: {required action}
 
 If none blocked, write: None.
 
+## Non-Terminal Follow-Ups
+- {check name}: {manual/operator/unsafe/external follow-up and substitute evidence}
+
+If none, write: None.
+
 ## Verified Checks
 - {check name}: {what passed and evidence}
 
@@ -148,7 +159,7 @@ If none blocked, write: None.
 After writing, final response should be concise:
 
 ```txt
-SUCCESS: wrote {ARTIFACT_PATH} ({line count} lines) result={pass|fail|blocked} checks-passed=X/Y checks-blocked=Z/Y
+SUCCESS: wrote {ARTIFACT_PATH} ({line count} lines) result={pass|fail|blocked|pass-with-followups} checks-passed=X/Y checks-blocked=Z/Y checks-blocked-terminal=A/Y checks-blocked-nonterminal=B/Y
 ```
 
 If writing fails:

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

@@ -0,0 +1,601 @@
+---
+description: Orchestrate a full multi-phase feature build with Pi build-phase runner monitoring
+argument-hint: "<path to HL plan spec>"
+---
+
+# Build Feature
+
+Orchestrate a full multi-phase feature build by launching the Pi build-phase runner once and monitoring it from a distance.
+
+The key architecture: **the build-feature agent is an observer/monitor/doctor, not the direct phase controller**. The deterministic phase loop runs in `.pi/scripts/build-phase-runner.sh`; this prompt launches that script in the background, polls durable files on disk, diagnoses stalls, applies bounded interventions when a known recovery playbook matches, audits high-level success criteria, writes a durable learnings file, and presents a final feature-level report.
+
+Use careful, evidence-grounded reasoning for diagnosis and intervention decisions. Do not rewrite phase artifacts on behalf of phase agents.
+
+## Required skill
+
+Before reading or interpreting `STATE.md`, load and follow the `FOB-state-context` skill.
+
+## Arguments
+
+Raw arguments: `$ARGUMENTS`
+
+Parse into:
+
+- `HL_PLAN_PATH`: first argument
+
+If missing, stop with:
+
+```txt
+Usage: /build-feature <path to HL plan spec>
+```
+
+## Variables
+
+Derived in Step 0:
+
+- `HL_PLAN_PATH`: absolute path to high-level plan markdown file
+- `SPEC_DIR`: parent directory of `HL_PLAN_PATH`
+- `PROJECT_ROOT`: nearest ancestor containing `.pi/prompts/build-phase.md`
+- `TASK_NAME`: `task:` from HL plan YAML frontmatter
+- `TOTAL_PHASES`: `phases:` from HL plan YAML frontmatter
+- `LEARNINGS_FILE`: `{SPEC_DIR}/build-feature-learnings.md`
+- `RUNNER_SCRIPT`: `{PROJECT_ROOT}/.pi/scripts/build-phase-runner.sh`
+- `HL_CRITERIA`: map of phase number to original HL success criteria strings
+
+Monitoring state:
+
+- `BUILD_PID`: PID of backgrounded runner process
+- `BUILD_START_TIME`: epoch seconds when launched
+- `CURRENT_PHASE`: phase currently active from `STATE.md`
+- `CURRENT_STEP`: step currently active from `STATE.md`
+- `LAST_POLL_PHASE`: phase from previous poll
+- `LAST_POLL_STEP`: step from previous poll
+- `STALL_SUSPECTED`: false until one no-progress poll, true until confirmed/resolved
+- `INTERVENTION_COUNTS`: per-phase intervention counter, max 2
+- `VERIFIED_PHASES`: phases whose success criteria have already been audited
+- `POLL_NUMBER`: incremented each poll
+
+## Status vocabulary
+
+Use Claude-compatible feature-level status names in the final report:
+
+```txt
+completed -> all required phases reached status: complete; validation may be pass or pass-with-followups
+partial -> at least one phase completed, but the run stopped on blocked/failed/incomplete phase
+aborted -> monitor aborted due to unrecoverable stall, process failure, invalid setup, or manual stop
+```
+
+Use Pi phase-level statuses exactly as reported in `phase_completion_report.md`:
+
+```txt
+complete -> phase succeeded; runner may continue, including validation-result: pass-with-followups
+blocked -> terminal external/environment/human-action blocker; stop by default unless explicitly accepted
+failed/fail -> validation/build failure after internal recovery loops; stop
+missing/invalid report -> orchestration/artifact failure; stop
+```
+
+Blocked is not failed, but blocked must not be silently ignored. Non-terminal manual/operator follow-ups should be represented as `status: complete` plus `validation-result: pass-with-followups`, then recorded in Criteria Issues / follow-up summaries without stopping the feature.
+
+## Workflow
+
+### Step 0: Parse and validate inputs
+
+1. Parse `HL_PLAN_PATH` from `$ARGUMENTS`. Trim whitespace.
+2. Resolve it to an absolute path.
+3. Verify it exists and ends in `.md`.
+4. Read the HL plan.
+5. Parse YAML frontmatter between the first pair of `---` delimiters:
+   - `task:` -> `TASK_NAME`; if missing/empty, abort.
+   - `phases:` -> `TOTAL_PHASES`; if missing/not positive integer, abort.
+6. Set `SPEC_DIR` to the parent directory of `HL_PLAN_PATH`.
+7. Derive `PROJECT_ROOT` by walking upward from `SPEC_DIR` until finding `.pi/prompts/build-phase.md`. If not found, abort.
+8. Set `RUNNER_SCRIPT` to `{PROJECT_ROOT}/.pi/scripts/build-phase-runner.sh`; verify it exists and is executable.
+9. Set `LEARNINGS_FILE` to `{SPEC_DIR}/build-feature-learnings.md`.
+10. Load `FOB-state-context` before reading `STATE.md`.
+11. Extract original high-level success criteria per phase:
+    - Find phase sections such as `### Phase N: ...`.
+    - Within each phase section, find `**Success Criteria**:` or equivalent success criteria block.
+    - Extract checkbox items beginning `- [ ]` or `- [x]`.
+    - Store exact criterion text in `HL_CRITERIA[N]`.
+    - If no criteria are found for a phase, store an empty list and log a warning.
+
+### Step 1: Initialize durable learnings file
+
+If `LEARNINGS_FILE` does not exist, write:
+
+```markdown
+# Build Feature Learnings: {TASK_NAME}
+
+Spec: {HL_PLAN_PATH}
+Project Root: {PROJECT_ROOT}
+Total Phases: {TOTAL_PHASES}
+Started: {ISO-8601 timestamp}
+
+---
+```
+
+If it exists, append a restart section:
+
+```markdown
+
+---
+
+# Build Feature Restart: {TASK_NAME}
+
+Restarted: {ISO-8601 timestamp}
+Spec: {HL_PLAN_PATH}
+Project Root: {PROJECT_ROOT}
+Total Phases: {TOTAL_PHASES}
+
+---
+```
+
+Always read the current file first, append in memory, then write the full updated content.
+
+### Step 2: Pre-flight checks
+
+Run and log these checks before launch. Accumulate results and append one `## Pre-Flight Checks` section to `LEARNINGS_FILE`.
+
+#### 2.1 Lock file check
+
+Lock file:
+
+```txt
+{SPEC_DIR}/.build-phase.lock
+```
+
+If it exists:
+
+1. Read PID.
+2. If PID is running, abort with a clear message: another build is active.
+3. If PID is dead, remove the stale lock and log it.
+
+#### 2.2 Port check
+
+Check port 3000 for existing processes:
+
+```bash
+lsof -ti:3000 2>/dev/null
+```
+
+If occupied, kill those PIDs before launch and log the action. This matches current test-project behavior. Future versions may read the configured dev port from `testing-and-validation`.
+
+#### 2.3 Git status check
+
+Run from `PROJECT_ROOT`:
+
+```bash
+git status --porcelain 2>/dev/null || echo GIT_UNAVAILABLE
+```
+
+Log clean/dirty/unavailable. Do not abort on dirty state.
+
+#### 2.4 STATE.md check
+
+Read `{SPEC_DIR}/../STATE.md` if present, or the nearest `specs/STATE.md` according to `FOB-state-context` conventions.
+
+Log whether `TASK_NAME` exists and which phases are already marked `[x]`.
+
+#### 2.5 Runner sanity check
+
+Run:
+
+```bash
+bash -n "{RUNNER_SCRIPT}"
+```
+
+Abort if syntax check fails.
+
+#### 2.6 Write pre-flight section
+
+Append:
+
+```markdown
+## Pre-Flight Checks
+Timestamp: {ISO-8601 timestamp}
+
+- Lock file: {clean | stale lock removed PID | active lock abort}
+- Port 3000: {clean | killed PIDs}
+- Git status: {clean | N uncommitted changes | unavailable}
+- STATE.md: {task found, completed phases ... | task not found}
+- Runner syntax: {pass | fail}
+```
+
+### Step 3: Launch runner once
+
+1. Append to `LEARNINGS_FILE`:
+
+```markdown
+## Build Launch
+Started: {ISO-8601 timestamp}
+Phase spec: all ({TOTAL_PHASES} total phases)
+Runner: {RUNNER_SCRIPT}
+```
+
+2. Initialize monitoring state:
+   - `INTERVENTION_COUNTS = {}`
+   - `VERIFIED_PHASES = {}`
+   - `LAST_POLL_PHASE = null`
+   - `LAST_POLL_STEP = null`
+   - `STALL_SUSPECTED = false`
+   - `POLL_NUMBER = 0`
+
+3. Launch the runner using shell-level backgrounding in one Bash call:
+
+```bash
+cd "{PROJECT_ROOT}" && "{RUNNER_SCRIPT}" "{HL_PLAN_PATH}" all > /tmp/build-feature.log 2>&1 &
+echo $!
+```
+
+Important: use shell `&`. Do not attempt to keep the build loop inside the agent. Capture stdout PID as `BUILD_PID`.
+
+4. Append `Build PID: {BUILD_PID}` to `LEARNINGS_FILE`.
+5. Set `BUILD_START_TIME` using `date +%s`.
+6. Create freshness marker:
+
+```bash
+touch /tmp/build-feature-lastpoll
+```
+
+### Step 4: Monitoring loop
+
+Poll until the runner exits or the monitor aborts.
+
+Default polling interval: 15 minutes, matching Claude Code vocabulary. During initial testing, a user may ask for a shorter interval, but the prompt default is 15 minutes.
+
+Each poll:
+
+1. Sleep:
+
+```bash
+sleep 900
+```
+
+2. Increment `POLL_NUMBER`.
+3. Check runner process:
+
+```bash
+kill -0 {BUILD_PID} 2>/dev/null && echo ALIVE || echo EXITED
+```
+
+If exited, proceed to Step 7 Completion Assessment.
+
+4. Read `STATE.md` and determine:
+   - active phase with any step `[~]`
+   - active step number/name
+   - completed phases whose Step 1-6 are `[x]`
+   - between-phase state, if no `[~]` but next phase not started
+
+5. Detect phase transition:
+   - If `CURRENT_PHASE` differs from `LAST_POLL_PHASE` and `LAST_POLL_PHASE` is not null, log transition.
+   - Audit the just-completed phase using Step 6.
+   - Run between-phase cleanup (Step 5).
+   - Reset `STALL_SUSPECTED=false`.
+
+6. Check for new artifacts since last poll:
+
+```bash
+NEW_FILES=""
+for dir in $(find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase*_*" 2>/dev/null); do
+  FILES=$(find "$dir" -newer /tmp/build-feature-lastpoll -type f 2>/dev/null | head -5)
+  if [ -n "$FILES" ]; then
+    NEW_FILES="${NEW_FILES}${FILES}\n"
+  fi
+done
+if [ -n "$NEW_FILES" ]; then
+  echo "NEW_ARTIFACTS:"
+  echo -e "$NEW_FILES"
+else
+  echo "NO_NEW_ARTIFACTS"
+fi
+touch /tmp/build-feature-lastpoll
+```
+
+7. Tail runner log for context:
+
+```bash
+tail -80 /tmp/build-feature.log 2>/dev/null || true
+```
+
+8. Stall detection:
+   - Phase changed -> progress.
+   - Step changed -> progress.
+   - Same step but new artifacts -> progress.
+   - Same step and no new artifacts for one poll -> set `STALL_SUSPECTED=true`, log warning.
+   - Same step and no new artifacts for two consecutive polls -> confirmed stall; proceed to Step 8 Diagnosis and Intervention.
+
+9. Append poll section to `LEARNINGS_FILE`:
+
+```markdown
+### Poll {POLL_NUMBER} ({elapsed_minutes}m)
+- Process alive: yes
+- Current phase: Phase {CURRENT_PHASE}
+- Current step: Step {CURRENT_STEP} - {step_name}
+- Phases completed: {list}
+- New artifacts since last poll: {list or none}
+- Runner log tail: summarized / see /tmp/build-feature.log
+- Progress status: {progress | possible stall | confirmed stall}
+```
+
+10. Continue polling.
+
+### Step 5: Between-phase cleanup
+
+On phase transition only, while runner is still alive:
+
+1. Clear port 3000:
+
+```bash
+lsof -ti:3000 | xargs kill -9 2>/dev/null; echo "Port cleanup done"
+```
+
+2. Append:
+
+```markdown
+### Between-Phase Cleanup (Phase {LAST_POLL_PHASE} -> Phase {CURRENT_PHASE})
+- Port 3000: cleared
+```
+
+Do not remove `.build-phase.lock` during normal between-phase cleanup; the runner owns it.
+
+### Step 6: Success criteria verification for a phase
+
+Run this when a phase transition is observed and again during final completion assessment for any phases not already verified.
+
+For phase `N`:
+
+1. Resolve phase directory:
+
+```bash
+find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase{N}_*" 2>/dev/null | head -1
+```
+
+2. Read `{PHASE_DIR}/phase_completion_report.md`.
+3. Parse YAML frontmatter:
+   - `status:`
+   - `validation-result:`
+   - `checks-passed:`
+   - `checks-blocked:`
+   - `checks-blocked-terminal:` if present
+   - `checks-blocked-nonterminal:` if present
+   - `fix-cycles:`
+4. Find the report's `## HL Success Criteria Results` or `## HL Plan Success Criteria Results` section.
+5. Parse table rows into:
+   - criterion text
+   - result: `PASS`, `FAIL`, `BLOCKED`
+   - evidence
+6. Cross-reference against `HL_CRITERIA[N]` from the original HL plan:
+   - matching row with `PASS` -> `complete`
+   - matching row with `FAIL` -> `incomplete`
+   - matching row with `BLOCKED` -> `blocked` if terminal, or `follow-up` if the phase report/validation report classifies it as non-terminal
+   - no matching row -> `dropped`
+7. Flag extra report rows not present in original HL criteria as `extra`.
+8. Append:
+
+```markdown
+### Success Criteria Verification: Phase {N}
+Timestamp: {ISO-8601 timestamp}
+Source: phase_completion_report.md vs HL plan
+Phase status: {status}
+Validation result: {validation-result}
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion text} | {complete/incomplete/blocked/dropped} | {evidence} |
+
+Summary: {complete}/{total} criteria complete; {blocked} terminal blocked; {follow_up} non-terminal follow-up; {dropped} dropped; {extra} extra.
+```
+
+This verification is observational. Do not modify phase reports.
+
+### Step 7: Completion assessment
+
+When the runner exits:
+
+1. Try to collect exit code:
+
+```bash
+wait {BUILD_PID} 2>/dev/null; echo $?
+```
+
+If unavailable because process was already reaped, record `unknown`.
+
+2. Read final `STATE.md`.
+3. For each phase `1..TOTAL_PHASES`:
+   - resolve phase directory,
+   - read `phase_completion_report.md`,
+   - parse frontmatter status,
+   - count completed Step 1-6 markers,
+   - compute per-phase result.
+4. Audit success criteria for any phase not in `VERIFIED_PHASES` using Step 6.
+5. Compute:
+   - total phases attempted,
+   - total phases complete,
+   - blocked phases,
+   - failed phases,
+   - incomplete/missing-report phases,
+   - total criteria,
+   - criteria complete,
+   - criteria incomplete,
+   - criteria blocked,
+   - criteria non-terminal follow-up,
+   - criteria dropped,
+   - total interventions,
+   - total duration.
+6. Determine feature status:
+
+```txt
+all phases status complete and no monitor abort -> completed, even if some phases have validation-result pass-with-followups
+some phases complete but terminal blocked/failed/incomplete exist -> partial
+monitor aborted or unrecoverable stall/process issue -> aborted
+```
+
+7. Append to `LEARNINGS_FILE`:
+
+```markdown
+## Build Process Exited
+Timestamp: {ISO-8601 timestamp}
+Exit code: {code}
+Duration: {minutes}m
+
+### Per-Phase Results
+| Phase | Steps Completed | Status | Validation | Interventions |
+|-------|-----------------|--------|------------|---------------|
+| 1 | {count}/6 | {status} | {validation-result} | {count} |
+
+## Success Criteria Audit: Full Build
+Timestamp: {ISO-8601 timestamp}
+
+| Phase | Total Criteria | Complete | Incomplete | Blocked | Follow-Up | Dropped |
+|-------|----------------|----------|------------|---------|-----------|---------|
+| 1 | {total} | {complete} | {incomplete} | {blocked} | {follow_up} | {dropped} |
+| TOTAL | {total} | {complete} | {incomplete} | {blocked} | {follow_up} | {dropped} |
+```
+
+Proceed to Step 9 Final Report.
+
+### Step 8: Diagnosis and intervention
+
+Run only after confirmed stall: two consecutive polls with same phase/step and no new artifacts.
+
+#### 8.1 Diagnosis
+
+Collect:
+
+```bash
+echo "=== Main process ==="
+ps -o pid,ppid,stat,%cpu,command -p {BUILD_PID} 2>/dev/null || true
+
+echo "=== Child processes ==="
+pgrep -P {BUILD_PID} 2>/dev/null | xargs ps -o pid,ppid,stat,%cpu,command -p 2>/dev/null || true
+
+echo "=== Grandchild processes ==="
+for child in $(pgrep -P {BUILD_PID} 2>/dev/null); do
+  pgrep -P "$child" 2>/dev/null | xargs ps -o pid,ppid,stat,%cpu,command -p 2>/dev/null
+done 2>/dev/null || true
+
+echo "=== Dev server processes ==="
+pgrep -f 'dev\.sh|bun.*dev|next dev|vite' 2>/dev/null | while read pid; do
+  ps -o pid,%cpu,command -p "$pid" 2>/dev/null
+done
+
+echo "=== Port 3000 ==="
+lsof -ti:3000 2>/dev/null || echo PORT_FREE
+
+echo "=== Runner log tail ==="
+tail -120 /tmp/build-feature.log 2>/dev/null || true
+```
+
+Append full diagnosis to `LEARNINGS_FILE`.
+
+#### 8.2 Known Error Playbook: Dev Server Foreground Hang
+
+Match if all are true:
+
+1. `STUCK_STEP` is Step 5 Validate Build.
+2. Dev server processes exist, port 3000 is occupied, or Step 5 has had no artifacts for 30+ minutes.
+3. `INTERVENTION_COUNTS[STUCK_PHASE] < 2`.
+
+Fix:
+
+1. Kill port 3000 processes.
+2. Kill `dev.sh`, `bun dev`, `next dev`, and `vite` processes.
+3. Kill runner process tree: grandchildren, children, then main PID.
+4. Sleep 5.
+5. Remove stale lock: `{SPEC_DIR}/.build-phase.lock`.
+6. Increment `INTERVENTION_COUNTS[STUCK_PHASE]`.
+7. Append an `### Intervention` entry to `LEARNINGS_FILE`.
+8. Relaunch the runner with `all`:
+
+```bash
+cd "{PROJECT_ROOT}" && "{RUNNER_SCRIPT}" "{HL_PLAN_PATH}" all > /tmp/build-feature.log 2>&1 &
+echo $!
+```
+
+9. Update `BUILD_PID`, reset `STALL_SUSPECTED=false`, touch `/tmp/build-feature-lastpoll`, and return to Step 4.
+
+Why `all`: the runner iterates all phases, and `build-phase` resumes/skips completed work from `STATE.md` and artifacts.
+
+#### 8.3 Unknown stall
+
+If no playbook matches:
+
+1. Append `### Unrecognized Stall` to `LEARNINGS_FILE`.
+2. Kill runner process tree and port 3000 to avoid orphans.
+3. Mark feature status `aborted`.
+4. Proceed to Step 9 Final Report.
+
+### Step 9: Final Build Feature Report
+
+Present the final results using this exact vocabulary and structure.
+
+```markdown
+## Build Feature Report
+
+**Feature:** {TASK_NAME}
+**Spec:** {HL_PLAN_PATH}
+**Status:** {completed | partial | aborted}
+**Duration:** {total minutes}m
+**Phases:** {completed_count}/{TOTAL_PHASES}
+**Criteria:** {complete_count}/{total_criteria_count} verified complete{; follow_up_count follow-ups if any}
+
+### Phase Results
+| Phase | Name | Status | Duration | Interventions | Criteria |
+|-------|------|--------|----------|---------------|----------|
+| 1 | {phase_name} | {status} | {duration}m | {count} | {complete}/{total} |
+
+### Criteria Issues
+| Phase | Criterion | Status | Detail |
+|-------|-----------|--------|--------|
+| {N} | {criterion text} | {incomplete/blocked/follow-up/dropped} | {evidence or reason} |
+```
+
+Omit `### Criteria Issues` only if there are no incomplete, terminal blocked, non-terminal follow-up, or dropped criteria.
+
+Continue:
+
+```markdown
+### Interventions
+{total_count} total interventions applied.
+
+{If total_count > 0: list each intervention with phase number, step, error type, and outcome.}
+{If total_count == 0: No interventions were needed. All phases completed without monitor intervention.}
+
+### Learnings File
+Full build log saved to: {LEARNINGS_FILE}
+Runner log: /tmp/build-feature.log
+
+### Next Steps
+- {If completed and all criteria complete: All phases built successfully and all success criteria verified. Review STATE.md and phase completion reports for details.}
+- {If completed but criteria issues/follow-ups exist: All phases completed, but {count} success criteria need manual/operator follow-up or were not fully met. Review Criteria Issues and the learnings file.}
+- {If partial: Phases {list} completed. Phase {N} stopped with status {status}. Review the learnings file and phase completion report. To retry: /build-feature {HL_PLAN_PATH}}
+- {If aborted: Build aborted due to {reason}. See learnings file for diagnosis. After resolving the issue, retry with: /build-feature {HL_PLAN_PATH}}
+```
+
+### Step 10: Cleanup
+
+After final report, clean temporary monitor files unless the user asks to preserve them:
+
+```bash
+rm -f /tmp/build-feature-lastpoll
+```
+
+Do not delete `LEARNINGS_FILE`.
+
+Do not delete phase artifacts.
+
+If the build is still running because of an abort/intervention failure, kill the runner process tree and clear port 3000 before exiting.
+
+## Edge cases
+
+1. **Already-completed phases**: runner invokes `build-phase` for each selected phase; `build-phase` resume logic should detect complete artifacts/state and exit quickly.
+2. **Partial phases**: `build-phase` resumes from incomplete step according to `STATE.md` and artifact validity.
+3. **Non-terminal follow-ups**: runner continues when the phase report has `status: complete` and `validation-result: pass-with-followups`; monitor records follow-ups but can still report feature `completed`.
+4. **Blocked phase**: runner stops by default on `status: blocked`; monitor reports `partial` unless an explicit accepted-blocker policy is later added.
+5. **Accepted blockers**: future version may support explicit blocker override via prompt argument, HL metadata, or sidecar config. Do not silently continue through terminal blocked phases in v1.
+5. **Max interventions**: max 2 per phase. After that, abort.
+6. **Concurrent runs**: active `.build-phase.lock` aborts preflight.
+7. **Context compaction**: `build-feature-learnings.md` is the durable source of truth.
+8. **Build continues independently**: monitor is observer, not controller. The runner process owns the phase loop.
+9. **Restart uses `all`**: this is intentional because `build-phase` resume logic handles skipped/completed work.
+10. **No macOS `open`**: browser validation remains owned by `build-phase` and must use `agent-browser` through existing skills.

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

@@ -128,9 +128,10 @@ Step 5 Validate Build is valid when:
 - `{PHASE_DIR}/build_validation_report.md` exists.
 - `build_validation_report.md` has YAML frontmatter.
 - Frontmatter contains `type: build-validation-report`.
-- Frontmatter contains `result: pass` or `result: blocked`.
+- Frontmatter contains `result: pass`, `result: blocked`, or `result: pass-with-followups`.
 - Frontmatter contains `checks-passed:`.
 - Frontmatter contains `checks-blocked:`.
+- Frontmatter contains `checks-blocked-terminal:` and `checks-blocked-nonterminal:` when any checks are blocked.
 
 `result: fail` is not complete for Step 5. If a failed validation report exists, rerun Step 5/fix cycles.
 
@@ -1300,8 +1301,12 @@ If expected 4xx entries occur, include them as evidence and explain why they are
 - PASS: executed and satisfied with evidence.
 - FAIL: executed and not satisfied; potential code issue.
 - BLOCKED: could not execute due to external/environment/credential/human-action condition.
+- Every BLOCKED check must include `severity: terminal` or `severity: non-terminal` in evidence.
+- Use terminal severity when blocked validation prevents establishing core phase correctness or safe continuation.
+- Use non-terminal severity when core functionality is validated but a manual/operator/unsafe/external follow-up could not safely run, such as external account creation, provider dashboard row inspection, or temporary secret mutation.
 - If any FAIL exists, overall result is `fail`.
-- If no FAIL and at least one BLOCKED exists, overall result is `blocked`.
+- If no FAIL and at least one terminal BLOCKED exists, overall result is `blocked`.
+- If no FAIL, no terminal BLOCKED checks, and at least one non-terminal BLOCKED exists, overall result is `pass-with-followups`.
 - If all PASS, overall result is `pass`.
 
 ## Validation Parameters
@@ -1317,12 +1322,14 @@ If expected 4xx entries occur, include them as evidence and explain why they are
 Write `{PHASE_DIR}/build_validation_report.md` with frontmatter including:
 - `type: build-validation-report`
 - `cycle: {BUILD_VALIDATION_CYCLE}`
-- `result: pass|fail|blocked`
+- `result: pass|fail|blocked|pass-with-followups`
 - `checks-passed: X/{BUILD_CHECK_COUNT}`
 - `checks-blocked: Z/{BUILD_CHECK_COUNT}`
+- `checks-blocked-terminal: A/{BUILD_CHECK_COUNT}`
+- `checks-blocked-nonterminal: B/{BUILD_CHECK_COUNT}`
 
 Final response format:
-SUCCESS: wrote {PHASE_DIR}/build_validation_report.md ({line count} lines) result={pass|fail|blocked} checks-passed=X/{BUILD_CHECK_COUNT} checks-blocked=Z/{BUILD_CHECK_COUNT}
+SUCCESS: wrote {PHASE_DIR}/build_validation_report.md ({line count} lines) result={pass|fail|blocked|pass-with-followups} checks-passed=X/{BUILD_CHECK_COUNT} checks-blocked=Z/{BUILD_CHECK_COUNT} checks-blocked-terminal=A/{BUILD_CHECK_COUNT} checks-blocked-nonterminal=B/{BUILD_CHECK_COUNT}
 ```
 
 ### 5.7 Spawn build validator and read result
@@ -1334,13 +1341,15 @@ Read `{PHASE_DIR}/build_validation_report.md` and extract:
 - `result`
 - `checks-passed`
 - `checks-blocked`
+- `checks-blocked-terminal`
+- `checks-blocked-nonterminal`
 - `cycle`
 
 If the report is missing or invalid, treat as orchestration failure and stop with Step 5 incomplete.
 
 ### 5.8 Handle validation result
 
-If `result: pass`, continue to Step 5.13 cleanup/complete.
+If `result: pass` or `result: pass-with-followups`, continue to Step 5.13 cleanup/complete.
 
 If `result: blocked`:
 
@@ -1401,6 +1410,7 @@ After the fix-builder returns:
 After each re-validation:
 
 - `pass` -> cleanup/complete.
+- `pass-with-followups` -> cleanup/complete.
 - `blocked` with no FAIL items -> cleanup/complete.
 - `fail` -> repeat Step 5.9 until max cycles.
 
@@ -1440,7 +1450,7 @@ Clean up the dev server if started. Reset or leave Step 5 as `[ ]` so a future r
 
 ### 5.13 Mark Step 5 complete
 
-Only after final result is `pass` or genuine `blocked`, update `STATE.md`:
+Only after final result is `pass`, `pass-with-followups`, or genuine terminal `blocked`, update `STATE.md`:
 
 ```txt
 Step 5 - Validate Build: [~] -> [x]
@@ -1473,9 +1483,11 @@ Artifacts:
 - fix_report_cycle*.md ({count or none})
 
 Build Validation:
-- Result: {pass|blocked}
+- Result: {pass|pass-with-followups|blocked}
 - Checks passed: {X/Y}
 - Checks blocked: {Z/Y}
+- Terminal blockers: {A/Y}
+- Non-terminal follow-ups: {B/Y}
 - Cycles: {BUILD_VALIDATION_CYCLE}
 - Fix cycles: {count}
 - Browser checks: {yes/no}
@@ -1486,7 +1498,7 @@ Step 5 complete. Continuing to Step 6 Finalize & Report.
 
 ## Step 6: Finalize & Report
 
-Run this step after Step 5 completes with final result `pass` or genuine `blocked`, or directly after Step 0 when `RESUME_FROM = 6`.
+Run this step after Step 5 completes with final result `pass`, `pass-with-followups`, or genuine terminal `blocked`, or directly after Step 0 when `RESUME_FROM = 6`.
 
 Step 6 is main/orchestrator-owned. Do not spawn a reporting sub-agent.
 
@@ -1554,6 +1566,8 @@ From `build_validation_report.md`:
 - Validation result.
 - Checks passed.
 - Checks blocked.
+- Terminal blocked count.
+- Non-terminal blocked/follow-up count.
 - Checks table.
 - Issues found.
 - Blocked checks.
@@ -1573,13 +1587,14 @@ Use:
 
 ```yaml
 status: complete|blocked|failed
-validation-result: pass|blocked|fail
+validation-result: pass|pass-with-followups|blocked|fail
 ```
 
 Rules:
 
 - `status: complete` when `build_validation_report.md` has `result: pass`.
-- `status: blocked` when `build_validation_report.md` has `result: blocked`.
+- `status: complete` when `build_validation_report.md` has `result: pass-with-followups`; preserve non-terminal follow-ups in report sections/frontmatter.
+- `status: blocked` when `build_validation_report.md` has `result: blocked` due to terminal blockers.
 - `status: failed` when `build_validation_report.md` has `result: fail`.
 
 Normally Step 6 should not run after failed Step 5. If a failed report is present, report it defensively and do not claim completion.
@@ -1597,9 +1612,12 @@ phase: {PHASE_NUMBER}
 phase-name: {PHASE_NAME}
 type: phase-report
 status: complete|blocked|failed
-validation-result: pass|blocked|fail
+validation-result: pass|pass-with-followups|blocked|fail
 checks-passed: X/Y
 checks-blocked: Z/Y
+checks-blocked-terminal: A/Y
+checks-blocked-nonterminal: B/Y
+manual-followups: B
 fix-cycles: N
 date: {current date}
 pre-phase-sha: {PRE_PHASE_SHA}
@@ -1634,6 +1652,8 @@ Required sections:
 
 ## Blocked Items / Human Action Required
 
+## Non-Terminal Follow-Ups
+
 ## Fix Cycles
 
 ## Files Changed
@@ -1654,7 +1674,8 @@ Important report rules:
 - Extract HL success criteria results from `[HL]` rows in `build_validation_report.md` Checks table.
 - Do not guess HL results by semantic matching when `[HL]` rows exist.
 - Include explicit human action for blocked `[HL]` criteria.
-- Distinguish validation blockers from code failures.
+- Distinguish terminal blockers, non-terminal manual/operator follow-ups, and code failures.
+- For `pass-with-followups`, keep `status: complete` but list follow-ups clearly in `## Non-Terminal Follow-Ups` and `## Blocked Items / Human Action Required`.
 - Always include `## Impacts on Future Phases` because future phase runs consume prior phase reports.
 
 ### 6.6 Verify report
@@ -1696,9 +1717,11 @@ BUILD PHASE {N} — COMPLETE
 Spec: {SPEC_DIR_BASENAME} ({TASK_NAME})
 Phase: {N} — {PHASE_NAME}
 Status: {complete|blocked|failed}
-Validation Result: {pass|blocked|fail}
+Validation Result: {pass|pass-with-followups|blocked|fail}
 Checks Passed: {X/Y}
 Checks Blocked: {Z/Y}
+Terminal Blockers: {A/Y}
+Non-Terminal Follow-Ups: {B/Y}
 Fix Cycles: {N}
 
 Artifacts:

package/assets/pi/skills/testing-and-validation/SKILL.md

@@ -106,6 +106,45 @@ Examples of acceptable expected 4xx responses:
 
 Validators must record these entries as expected evidence rather than hiding them.
 
+## Blocked Check Severity
+
+Every blocked validation check must be classified as either **terminal** or **non-terminal**.
+
+### Terminal blocked
+
+Use terminal blocked when the agent cannot establish the phase's core correctness, or when continuing may make later phases invalid.
+
+Examples:
+
+- the app or required dev server cannot start
+- required environment variables are missing for core functionality
+- no usable auth path exists for an auth-dependent phase
+- database/service unavailable for core validation
+- a core user story cannot be executed or source-verified
+- validation infrastructure failure prevents meaningful assessment
+
+### Non-terminal blocked
+
+Use non-terminal blocked when core functionality has already been validated by executable/source/browser checks, but an additional manual, operator-only, destructive, unsafe, or external-provider check could not safely run.
+
+Examples:
+
+- dashboard-only database row inspection
+- creating external provider accounts without explicit approval
+- mutating production-like secrets or provider configuration
+- forcing rare failure states that require unsafe environment changes
+- manual provider-console verification
+- external billing/provider configuration checks
+
+For every BLOCKED check, validators must document:
+
+- `severity: terminal` or `severity: non-terminal`
+- the blocked reason
+- any executable substitute evidence that was available
+- the recommended human/operator follow-up
+
+If no FAIL checks exist and all blocked checks are non-terminal, the overall validation result should be `pass-with-followups`, not `blocked`.
+
 ## For Agents Consuming This Skill
 
 1. Use the exact configured commands. Do not improvise substitutes from memory.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.7",
+  "version": "1.9.9",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",
@@ -99,7 +99,8 @@
       ],
       "prompts": [
         "explore-codebase",
-        "build-phase"
+        "build-phase",
+        "build-feature"
       ],
       "extensions": [
         "pinned-response",

package/package.json

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