aiblueprint-cli 1.4.99 → 1.4.101

package/agents-config/skills/apex/steps/step-08-run-tests.md

@@ -1,314 +1,27 @@
 ---
 name: step-08-run-tests
-description: Run tests in a loop - fix issues until all pass
-prev_step: steps/step-07-tests.md
-next_step: steps/step-05-examine.md
+description: Run focused APEX tests in a causal fix loop and stop or re-plan when attempts stop making progress.
+next_step: step-04-validate.md
 ---
 
-# Step 8: Run Tests (Fix Loop)
+# Step 8: Test loop
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## 1. Prepare the environment
 
-- 🛑 NEVER give up after first failure
-- 🛑 NEVER start services without permission (unless auto_mode)
-- 🛑 NEVER infinite loop on same failure (max 3 attempts)
-- ✅ ALWAYS loop until all tests pass
-- ✅ ALWAYS ask user when stuck (unless auto_mode)
-- ✅ ALWAYS clean up background processes
-- 📋 YOU ARE A TEST RUNNER, fixing until green
-- 💬 FOCUS on "Run → Fail → Fix → Repeat until green"
-- 🚫 FORBIDDEN to ignore configuration errors
+Follow project rules for services, ports, fixtures, devices, credentials, and cleanup. Reuse healthy managed services when required by local instructions. Do not launch unmanaged persistent processes.
 
-## EXECUTION PROTOCOLS:
+## 2. Run narrow to broad
 
-- 🎯 Check requirements before running
-- 💾 Log each test run (if save_mode)
-- 📖 Analyze failures before fixing
-- 🚫 FORBIDDEN to proceed with failing tests (without explicit skip)
+Start with the new or affected tests, then expand to the relevant suite. Capture command, environment, revision, exit status, and decisive output.
 
-## CONTEXT BOUNDARIES:
+## 3. Diagnose causally
 
-- Tests were created in step-07
-- Tests may require services (DB, server)
-- Failures may be code bugs or test bugs
-- Loop until all green or user decides to skip
+For every failure, classify whether it is introduced, pre-existing, unrelated, unavailable, or test-design error. Change code or tests only when evidence supports the cause.
 
-## YOUR TASK:
+## 4. Bound unproductive retries
 
-Run tests, fix any failures, and loop until ALL tests pass.
+Continue while each attempt produces new evidence or measurable progress. If two consecutive rounds reproduce the same blocker without new information, stop repeating the command, record the blocker, and re-plan or request the precise missing input.
 
----
-
-<available_state>
-From previous steps:
-
-| Variable | Description |
-|----------|-------------|
-| `{task_description}` | What was implemented |
-| `{task_id}` | Kebab-case identifier |
-| `{auto_mode}` | Auto-start servers, auto-retry |
-| `{examine_mode}` | Auto-proceed to review after |
-| `{save_mode}` | Save outputs to files |
-| `{output_dir}` | Path to output (if save_mode) |
-| Tests created | From step-07 |
-| Test command | Discovered in step-07 |
-</available_state>
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Initialize Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-```bash
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "08" "run-tests" "in_progress"
-```
-
-Append logs to `{output_dir}/08-run-tests.md` as you work.
-
-### 2. Check Requirements
-
-**Identify required services:**
-```bash
-cat package.json | grep -A 10 '"scripts"'
-```
-
-Common: Database, dev server, Redis
-
-**Check if running:**
-```bash
-curl -s http://localhost:3000 > /dev/null 2>&1 && echo "Server running"
-```
-
-### 3. Handle Missing Services
-
-**If `{auto_mode}` = true:**
-→ Start services automatically:
-```bash
-pnpm run dev &
-sleep 5
-```
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Services"
-    question: "Tests require services that aren't running. How proceed?"
-    options:
-      - label: "I'll start manually"
-        description: "Give me a moment to start them"
-      - label: "Start automatically"
-        description: "Try to start services automatically"
-      - label: "Skip tests needing services"
-        description: "Only run tests that don't need services"
-      - label: "Skip test step"
-        description: "Continue without running tests"
-    multiSelect: false
-```
-
-### 4. Run Test Loop
-
-**CRITICAL: Loop until all pass**
-
-```
-max_attempts = 10
-attempt = 0
-
-WHILE attempt < max_attempts:
-    attempt += 1
-
-    1. Run tests
-    2. If all pass → EXIT (success)
-    3. If failure:
-       a. Analyze failure
-       b. Determine: code bug or test bug?
-       c. Fix the issue
-       d. CONTINUE LOOP
-    4. If same failure 3x → ASK USER
-```
-
-**Run tests:**
-```bash
-pnpm run test 2>&1
-```
-
-**Log each run:**
-```
-**Run #{attempt}:**
-- Total: 5, Passed: 3, Failed: 2
-- Fixing: {description}
-```
-
-### 5. Handle Failures
-
-For each failing test:
-
-```
-**Analyzing:**
-Test: "creates user with valid data"
-File: src/auth/register.test.ts:25
-Error: Expected 201, got 500
-Stack: TypeError: Cannot read 'email' of undefined
-
-**Diagnosis:** Code bug - null handling
-**Fix:** Add null check in handler
-```
-
-**Fix location:**
-| Error Type | Fix |
-|------------|-----|
-| Assertion failed | Usually code bug |
-| TypeError in code | Code bug |
-| TypeError in test | Test bug |
-| Timeout | async/await issue |
-| Import error | Missing dep |
-
-### 6. Handle Stuck (3x same failure)
-
-**If `{auto_mode}` = true:**
-→ Try different approach once, then continue
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Stuck"
-    question: "Test keeps failing. How proceed?"
-    options:
-      - label: "I'll debug manually"
-        description: "Let me investigate"
-      - label: "Skip this test"
-        description: "Mark as skip, continue others"
-      - label: "Delete test"
-        description: "Remove this test entirely"
-      - label: "Keep trying"
-        description: "Try more approaches"
-    multiSelect: false
-```
-
-### 7. Handle Config Errors
-
-| Error | Solution |
-|-------|----------|
-| Cannot find module | Check imports, pnpm install |
-| Connection refused | DB/server not running |
-| Timeout | Increase timeout, check async |
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Config"
-    question: "Configuration issue detected. How proceed?"
-    options:
-      - label: "I'll fix manually"
-        description: "Let me handle config"
-      - label: "Try automatic fix"
-        description: "Attempt suggested fix"
-      - label: "Skip tests"
-        description: "Continue without tests"
-    multiSelect: false
-```
-
-### 8. Success - All Passing
-
-```
-**✓ All Tests Passing**
-
-**Results:**
-- Total: {count}
-- Passed: {count}
-- Failed: 0
-
-**Attempts:** {count}
-
-**Tests:**
-- src/auth/register.test.ts - 3 tests
-- src/utils/validation.test.ts - 2 tests
-```
-
-### 9. Complete Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Append to `{output_dir}/08-run-tests.md`:
-```markdown
----
-## Step Complete
-**Status:** ✓ Complete
-**Tests passed:** {count}
-**Attempts:** {count}
-**Next:** {next step}
-**Timestamp:** {ISO timestamp}
-```
-
-### 10. Determine Next Step
-
-**If `{examine_mode}` = true:**
-→ Load step-05-examine.md
-
-**If `{verify_mode}` = true:**
-→ Load step-10-verify.md
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Next"
-    question: "All tests passing. What next?"
-    options:
-      - label: "Run adversarial review"
-        description: "Deep review for security/logic"
-      - label: "Verify feature"
-        description: "Launch app and test feature works"
-      - label: "Complete workflow"
-        description: "Finalize and show summary"
-    multiSelect: false
-```
-
-**Else:**
-→ Complete workflow
-
----
-
-## SUCCESS METRICS:
-
-✅ All tests passing
-✅ No stuck failures without user decision
-✅ Config issues resolved
-✅ Services cleaned up
-✅ Clear summary
-
-## FAILURE MODES:
-
-❌ Giving up after first failure
-❌ Infinite loop on same failure
-❌ Starting services without permission
-❌ Not cleaning up background processes
-❌ Ignoring config errors
-❌ **CRITICAL**: Not using AskUserQuestion when stuck
-
-## RUN PROTOCOLS:
-
-- Loop until green
-- Analyze before fixing
-- Ask user when stuck (3x)
-- Clean up services
-- Clear summary at end
-
----
-
-## NEXT STEP:
-
-Based on flags (check in order):
-- **If examine_mode:** Load `./step-05-examine.md`
-- **If verify_mode:** Load `./step-10-verify.md` to verify feature
-- **If pr_mode:** Load `./step-09-finish.md` to create pull request
-- **Otherwise:** Workflow complete - show summary
+## 5. Clean up and return
 
-<critical>
-Remember: Loop until ALL tests pass - don't give up after first failure!
-</critical>
+Clean up task-owned fixtures and processes. Return to `step-04-validate.md` so the integrated ledger reflects the latest code and tests.

package/agents-config/skills/apex/steps/step-09-finish.md

@@ -1,223 +1,59 @@
 ---
 name: step-09-finish
-description: Finish APEX workflow and create pull request
-previous_step: step-08-run-tests.md (or step-04-validate.md if no tests)
+description: Complete an APEX run with scope review, proof-boundary reporting, and only the delivery actions authorized by the user.
 ---
 
-# Step 9: Finish & Create PR
+# Step 9: Handoff
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+Do not edit implementation code here. Return to the relevant phase if the completion audit finds a defect.
 
-- 🛑 NEVER push without user confirmation (unless auto_mode)
-- 🛑 NEVER create PR if there are uncommitted changes
-- ✅ ALWAYS verify all changes are committed
-- ✅ ALWAYS push to remote before creating PR
-- 📋 YOU ARE A FINISHER, completing the workflow
-- 💬 FOCUS on PR creation and workflow summary
-- 🚫 FORBIDDEN to make code changes in this step
+## 1. Audit completion
 
-## EXECUTION PROTOCOLS:
+Confirm:
 
-- 🎯 Verify git status before any push/PR operations
-- 💾 Save PR details to output file if save_mode enabled
-- 📖 Provide clear workflow summary
-- 🚫 FORBIDDEN to proceed with uncommitted changes
+- every acceptance criterion has current evidence at the required level;
+- all introduced failures are resolved;
+- review requirements and confirmed findings are closed;
+- current Git diff matches the intended task scope;
+- unrelated staged, unstaged, deleted, and untracked paths remain untouched;
+- run state lists every unavailable check, blocker, and residual risk honestly.
 
-## CONTEXT BOUNDARIES:
+Do not call a blocked, unverified, or partially validated task complete.
 
-- Variables available: `{task_id}`, `{task_description}`, `{branch_name}`, `{pr_mode}`, `{auto_mode}`, `{save_mode}`, `{teams_mode}`, `{output_dir}`
-- Previous steps completed: analyze, plan, execute, validate (+ optional: tests, examine)
-- All implementation should be done at this point
+## 2. Report proof boundaries
 
-## YOUR TASK:
+Separate claims explicitly:
 
-Finalize the APEX workflow by committing remaining changes, pushing to remote, and creating a pull request.
+| Layer | Example evidence | Claim boundary |
+|---|---|---|
+| Local/static | Diff, typecheck, lint, tests, local runtime | What the inspected local state proves |
+| Provider | Authoritative provider/API read-back | What provider configuration or state proves |
+| Public artifact/deployment | Re-downloaded artifact, public URL, deployment revision | What an unauthenticated external consumer can obtain |
+| Authenticated live | Controlled signed-in flow, send/receipt, persistent read-back | What was observed through the real protected surface |
 
----
-
-## EXECUTION SEQUENCE:
-
-### 0. Shutdown Agent Team (if teams_mode)
-
-<critical>
-This is the ONLY step where team shutdown should happen.
-All previous steps (validate, examine, resolve) keep the team alive.
-</critical>
-
-**If `{teams_mode}` = true:**
-
-1. Send shutdown_request to each teammate:
-```
-SendMessage:
-  type: "shutdown_request"
-  recipient: "impl-{name}"
-  content: "APEX workflow complete. Shutting down team."
-```
-
-2. Wait for all teammates to confirm shutdown.
-
-3. Delete the team:
-```
-TeamDelete
-```
-
-→ This cleans up team files and task directories.
-
-### 1. Verify Git Status
-
-```bash
-git status
-```
-
-**If uncommitted changes exist:**
-→ Commit them with message: `feat({task_id}): {task_description}`
-
-**If working tree is clean:**
-→ Continue to step 2
-
-### 2. Check Commits to Push
-
-```bash
-git log origin/{branch_name}..HEAD --oneline 2>/dev/null || git log --oneline -5
-```
-
-Display commits that will be included in PR.
-
-### 3. Confirm Push (if not auto_mode)
-
-**If `{auto_mode}` = true:**
-→ Auto-push to remote
-
-**If `{auto_mode}` = false:**
-Use AskUserQuestion:
-```yaml
-questions:
-  - header: "Push"
-    question: "Ready to push {branch_name} and create PR?"
-    options:
-      - label: "Push and create PR (Recommended)"
-        description: "Push commits to remote and open pull request"
-      - label: "Push only"
-        description: "Push to remote without creating PR"
-      - label: "Review commits first"
-        description: "Show me the full diff before pushing"
-      - label: "Cancel"
-        description: "Don't push or create PR"
-    multiSelect: false
-```
-
-### 4. Push to Remote
-
-```bash
-git push -u origin {branch_name}
-```
-
-**If push fails:**
-→ Display error and ask user how to proceed
-→ Common fixes: pull --rebase, force push (with warning)
-
-### 5. Create Pull Request (if pr_mode)
+Use `NOT RUN`, `UNAVAILABLE`, `NOT PROVEN`, or `BLOCKED` where appropriate. Do not let a stronger-sounding summary erase those boundaries.
 
-**If `{pr_mode}` = true:**
+## 3. Perform only requested delivery actions
 
-Generate PR content:
-- **Title:** `feat({task_id}): {task_description}`
-- **Body:** Summary of changes from the workflow
+Implementation permission does not by itself request a commit, push, pull request, merge, deploy, release, provider mutation, or external message.
 
-```bash
-gh pr create --title "feat({task_id}): {task_description}" --body "$(cat <<'EOF'
-## Summary
-
-{Brief description of what was implemented}
-
-## Changes
-
-{List of key changes made}
-
-## Testing
-
-{How the changes were validated}
-
----
+When a delivery action is in scope:
 
-_Generated by APEX workflow_
-EOF
-)"
-```
-
-**Capture PR URL:**
-```bash
-gh pr view --json url -q '.url'
-```
-→ Store as `{pr_url}`
+1. Review the exact paths and diff that belong to the task.
+2. Stage only those paths unless the user explicitly requested the entire reviewed tree.
+3. Scan the staged diff for secrets and scope drift.
+4. Commit using the repository convention.
+5. Push only the intended branch.
+6. Create or update the requested pull request with actual validation and proof boundaries.
+7. Read back the remote branch, pull request, deployment, provider state, or public artifact needed to support the delivery claim.
 
-### 6. Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-```bash
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "09" "finish" "in_progress"
-```
+Never force push, merge, release, deploy, or communicate externally without the corresponding authority.
 
-Append to `{output_dir}/09-finish.md`: branch, PR URL, commits, timestamp.
+## 4. Close run state
 
 ```bash
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "09" "finish" "complete"
+python3 "{skill_dir}/scripts/apex-state.py" event --root "$PWD" --run-id "{run_id}" --phase handoff --status complete --message "Completion audit and authorized handoff finished"
+python3 "{skill_dir}/scripts/apex-state.py" checkpoint --root "$PWD" --run-id "{run_id}" --phase handoff --message "APEX run complete"
 ```
 
-### 7. Final Summary
-
-Display workflow completion summary:
-
-```
-═══════════════════════════════════════════════════════
-  APEX WORKFLOW COMPLETE
-═══════════════════════════════════════════════════════
-
-  Task: {task_description}
-  ID: {task_id}
-
-  ✓ Analysis complete
-  ✓ Plan created and approved
-  ✓ Implementation done
-  ✓ Validation passed
-  {if test_mode: "✓ Tests passing"}
-  {if examine_mode: "✓ Review findings resolved"}
-  ✓ Changes pushed to {branch_name}
-  {if pr_mode: "✓ PR created: {pr_url}"}
-
-═══════════════════════════════════════════════════════
-```
-
----
-
-## SUCCESS METRICS:
-
-✅ Agent team shut down gracefully via SendMessage shutdown_request (if teams_mode)
-✅ TeamDelete called to clean up team resources (if teams_mode)
-✅ All changes committed
-✅ Branch pushed to remote
-✅ PR created with proper title and description (if pr_mode)
-✅ PR URL captured and displayed
-✅ Output saved (if save_mode)
-✅ Clear completion summary provided
-
-## FAILURE MODES:
-
-❌ Creating PR with uncommitted changes
-❌ Pushing without user confirmation (when not auto_mode)
-❌ Force pushing without explicit user request
-❌ Not displaying PR URL after creation
-❌ **CRITICAL**: Using plain text prompts instead of AskUserQuestion
-
----
-
-## WORKFLOW COMPLETE
-
-This is the final step of the APEX workflow. No next step to load.
-
-<critical>
-Remember: This step handles git operations, PR creation, AND team shutdown (if teams_mode).
-All code changes should have been completed in earlier steps.
-Team shutdown MUST happen here - step 0 of execution sequence - before git operations.
-</critical>
+Present the outcome, changed files, validation ledger, review disposition, proof boundaries, delivery read-back, and any remaining local changes.