ai-fob 1.9.8 → 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

@@ -60,7 +60,7 @@ Monitoring state:
 Use Claude-compatible feature-level status names in the final report:
 
 ```txt
-completed -> all required phases reached status: complete and criteria audit is acceptable
+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
 ```
@@ -68,13 +68,13 @@ aborted -> monitor aborted due to unrecoverable stall, process failure, invalid
 Use Pi phase-level statuses exactly as reported in `phase_completion_report.md`:
 
 ```txt
-complete -> phase succeeded; runner may continue
-blocked -> external/environment/human-action blocker; stop by default unless explicitly accepted
+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.
+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
 
@@ -356,6 +356,8 @@ find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase{N}_*" 2>/dev/null | head -1
    - `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:
@@ -365,7 +367,7 @@ find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase{N}_*" 2>/dev/null | head -1
 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`
+   - 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:
@@ -381,7 +383,7 @@ Validation result: {validation-result}
 |---|-----------|--------|----------|
 | 1 | {criterion text} | {complete/incomplete/blocked/dropped} | {evidence} |
 
-Summary: {complete}/{total} criteria complete; {blocked} blocked; {dropped} dropped; {extra} extra.
+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.
@@ -416,14 +418,15 @@ If unavailable because process was already reaped, record `unknown`.
    - criteria complete,
    - criteria incomplete,
    - criteria blocked,
+   - criteria non-terminal follow-up,
    - criteria dropped,
    - total interventions,
    - total duration.
 6. Determine feature status:
 
 ```txt
-all phases complete and no monitor abort -> completed
-some phases complete but blocked/failed/incomplete exist -> partial
+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
 ```
 
@@ -443,10 +446,10 @@ Duration: {minutes}m
 ## Success Criteria Audit: Full Build
 Timestamp: {ISO-8601 timestamp}
 
-| Phase | Total Criteria | Complete | Incomplete | Blocked | Dropped |
-|-------|----------------|----------|------------|---------|---------|
-| 1 | {total} | {complete} | {incomplete} | {blocked} | {dropped} |
-| TOTAL | {total} | {complete} | {incomplete} | {blocked} | {dropped} |
+| 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.
@@ -534,7 +537,7 @@ Present the final results using this exact vocabulary and structure.
 **Status:** {completed | partial | aborted}
 **Duration:** {total minutes}m
 **Phases:** {completed_count}/{TOTAL_PHASES}
-**Criteria:** {complete_count}/{total_criteria_count} verified complete
+**Criteria:** {complete_count}/{total_criteria_count} verified complete{; follow_up_count follow-ups if any}
 
 ### Phase Results
 | Phase | Name | Status | Duration | Interventions | Criteria |
@@ -544,10 +547,10 @@ Present the final results using this exact vocabulary and structure.
 ### Criteria Issues
 | Phase | Criterion | Status | Detail |
 |-------|-----------|--------|--------|
-| {N} | {criterion text} | {incomplete/blocked/dropped} | {evidence or reason} |
+| {N} | {criterion text} | {incomplete/blocked/follow-up/dropped} | {evidence or reason} |
 ```
 
-Omit `### Criteria Issues` only if there are no incomplete, blocked, or dropped criteria.
+Omit `### Criteria Issues` only if there are no incomplete, terminal blocked, non-terminal follow-up, or dropped criteria.
 
 Continue:
 
@@ -564,7 +567,7 @@ 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 exist: All phases completed, but {count} success criteria were not fully met. Review Criteria Issues and the learnings file.}
+- {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}}
 ```
@@ -587,8 +590,9 @@ If the build is still running because of an abort/intervention failure, kill the
 
 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. **Blocked phase**: runner stops by default; monitor reports `partial` unless an explicit accepted-blocker policy is later added.
-4. **Accepted blockers**: future version may support explicit blocker override via prompt argument, HL metadata, or sidecar config. Do not silently continue through blocked phases in v1.
+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.

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.8",
+  "version": "1.9.9",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",

package/package.json

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