aiblueprint-cli 1.4.99 → 1.4.101

package/agents-config/skills/apex/steps/step-03-execute.md

@@ -1,240 +1,60 @@
 ---
 name: step-03-execute
-description: Todo-driven implementation - execute the plan file by file
-prev_step: steps/step-02-plan.md
-next_step: steps/step-04-validate.md
+description: Execute the next APEX task units adaptively with bounded attempts, scope checks, checkpoints, and re-planning.
+next_step: step-04-validate.md
 ---
 
-# Step 3: Execute (Implementation)
+# Step 3: Execute
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+Implement the task graph, not a stale narrative plan.
 
-- 🛑 NEVER deviate from the approved plan
-- 🛑 NEVER add features not in the plan (scope creep)
-- 🛑 NEVER modify files without reading them first
-- ✅ ALWAYS follow the plan file-by-file
-- ✅ ALWAYS mark todos complete immediately after each task
-- ✅ ALWAYS read files BEFORE editing them
-- 📋 YOU ARE AN IMPLEMENTER following a plan, not a designer
-- 💬 FOCUS on executing the plan exactly as approved
-- 🚫 FORBIDDEN to add "improvements" not in the plan
+## 1. Re-read current state
 
-## EXECUTION PROTOCOLS:
+Before each task unit:
 
-- 🎯 Create todos from plan before starting
-- 💾 Mark todos complete immediately after each task
-- 📖 Read each file BEFORE modifying it
-- 🚫 FORBIDDEN to have multiple todos in_progress simultaneously
+- confirm dependencies are complete;
+- compare repository state with the last checkpoint;
+- inspect overlapping local changes;
+- confirm the unit's write boundary, side effects, validation, and evidence;
+- re-plan if an assumption or boundary is stale.
 
-## CONTEXT BOUNDARIES:
+## 2. Choose local or delegated execution
 
-- Plan from step-02 is approved and must be followed
-- Files to modify are known from the plan
-- Patterns to follow are documented from step-01
-- Don't add features - stick to the plan
-- **If context was cleared ("Execute and clear context"):** The plan file contains all APEX state variables in the "APEX Workflow Context" section. Read the plan file first and restore all variables before proceeding.
+Keep the unit local when it is on the immediate critical path, tightly coupled to current context, small, or likely to need rapid iteration. Delegate when it is self-contained and a separate context materially helps.
 
-## YOUR TASK:
+Delegated packets must include the task contract, exact boundaries, relevant project rules, dependencies, expected output, validation, and stop condition. A worker may report a newly discovered need but may not silently widen scope.
 
-Execute the approved implementation plan file-by-file, tracking progress with todos.
+## 3. Record the attempt
 
----
-
-<available_state>
-From previous steps:
-
-| Variable | Description |
-|----------|-------------|
-| `{task_description}` | What to implement |
-| `{task_id}` | Kebab-case identifier |
-| `{auto_mode}` | Skip confirmations |
-| `{save_mode}` | Save outputs to files |
-| `{output_dir}` | Path to output (if save_mode) |
-| Implementation plan | File-by-file changes from step-02 |
-| Patterns | How to implement from step-01 |
-</available_state>
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Initialize Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
+Every attempt has a stable task ID and incrementing attempt number. Record its starting revision, owner, intended paths, and status before mutation.
 
 ```bash
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "03" "execute" "in_progress"
+python3 "{skill_dir}/scripts/apex-state.py" event --root "$PWD" --run-id "{run_id}" --phase execute --task-id "{unit_id}" --status in_progress --message "Attempt started"
 ```
 
-Append logs to `{output_dir}/03-execute.md` as you work.
-
-### 2. Create Todos from Plan
+## 4. Implement in a tight loop
 
-Convert each file change from the plan into todos:
+1. Make the smallest coherent edit.
+2. Inspect the changed diff immediately.
+3. Run the shortest relevant feedback command.
+4. Fix introduced failures within scope.
+5. Repeat until the task's evidence contract is met or a re-plan trigger fires.
 
-```
-Plan entry:
-#### `src/auth/handler.ts`
-- Add `validateToken` function
-- Handle error case: expired token
-
-Becomes:
-- [ ] src/auth/handler.ts: Add validateToken function
-- [ ] src/auth/handler.ts: Handle expired token error
-```
+Do not opportunistically refactor unrelated code. Preserve user changes even when they complicate the implementation.
 
-Use TodoWrite to create the full list.
+## 5. Close or re-plan
 
-### 3. Execute File by File
+A task is complete only when its declared output exists, its write boundary is respected, relevant validation has a classified result, and required evidence is recorded.
 
-For each todo:
+If blocked, record the concrete condition, attempted alternatives, and exact input or authority needed. Continue with other independent unblocked units when useful.
 
-**3.1 Mark In Progress**
-- Only ONE todo in_progress at a time
-
-**3.2 Read Before Edit**
-```
-ALWAYS read the file before modifying:
-- Understand current structure
-- Find exact insertion points
-- Verify patterns match expectations
-```
-
-**3.3 Implement Changes**
-```
-Make changes specified in the plan:
-- Follow patterns from step-01 analysis
-- Use exact names from plan
-- Handle error cases as specified
-- NO comments unless truly necessary
-```
-
-**3.4 Mark Complete Immediately**
-- Mark todo complete RIGHT AFTER finishing
-- Don't batch completions
-
-**3.5 Log Progress (if save_mode)**
-```markdown
-### ✓ src/auth/handler.ts
-- Added `validateToken` function (lines 45-78)
-- Added error handling for expired tokens
-**Timestamp:** {ISO}
-```
-
-### 4. Handle Blockers
-
-**If `{auto_mode}` = true:**
-→ Make reasonable decision and continue
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Blocker"
-    question: "Encountered an issue. How should we proceed?"
-    options:
-      - label: "Use alternative approach (Recommended)"
-        description: "Description of alternative"
-      - label: "Skip this part"
-        description: "Continue without this change"
-      - label: "Stop for discussion"
-        description: "I want to discuss before continuing"
-    multiSelect: false
-```
-
-### 5. Verify Implementation
-
-After completing all todos:
+After completion:
 
 ```bash
-pnpm run typecheck && pnpm run lint --fix
-```
-
-Fix any errors immediately.
-
-### 6. Implementation Summary
-
-```
-**Implementation Complete**
-
-**Files Modified:**
-- `src/auth/handler.ts` - Added validateToken, error handling
-- `src/api/auth/route.ts` - Integrated token validation
-
-**New Files:**
-- `src/types/auth.ts` - Auth type definitions
-
-**Todos:** {X}/{Y} complete
+python3 "{skill_dir}/scripts/apex-state.py" event --root "$PWD" --run-id "{run_id}" --phase execute --task-id "{unit_id}" --status complete --message "Task output and evidence recorded"
+python3 "{skill_dir}/scripts/apex-state.py" checkpoint --root "$PWD" --run-id "{run_id}" --phase execute --message "Task checkpoint"
 ```
 
-**If `{auto_mode}` = true:**
-→ Proceed to validation
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Execute"
-    question: "Implementation complete. Ready to validate?"
-    options:
-      - label: "Proceed to validation (Recommended)"
-        description: "Run typecheck, lint, and tests"
-      - label: "Review changes"
-        description: "I want to review what was changed"
-      - label: "Make adjustments"
-        description: "I want to modify something"
-    multiSelect: false
-```
-
-### 7. Complete Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Append to `{output_dir}/03-execute.md`:
-```markdown
----
-## Step Complete
-**Status:** ✓ Complete
-**Files modified:** {count}
-**Todos completed:** {count}
-**Next:** step-04-validate.md
-**Timestamp:** {ISO timestamp}
-```
-
----
-
-## SUCCESS METRICS:
-
-✅ All plan items implemented
-✅ All todos marked complete
-✅ No scope creep - only plan items
-✅ Files read before modification
-✅ Typecheck and lint pass
-✅ Progress logged (if save_mode)
-
-## FAILURE MODES:
-
-❌ Adding features not in the plan
-❌ Modifying files without reading first
-❌ Not updating todos as you work
-❌ Multiple todos in_progress simultaneously
-❌ Ignoring type or lint errors
-❌ **CRITICAL**: Not using AskUserQuestion for blockers
-
-## EXECUTION PROTOCOLS:
-
-- Follow the plan EXACTLY
-- Read before write
-- One file at a time
-- Update todos in real-time
-- Fix errors immediately
-
----
-
-## NEXT STEP:
-
-After implementation complete, load `./step-04-validate.md`
+## Completion
 
-<critical>
-Remember: Execution is about following the plan - don't redesign or add features!
-</critical>
+Proceed to `step-04-validate.md` when all required graph nodes are complete or explicitly blocked with no remaining meaningful in-scope work.

package/agents-config/skills/apex/steps/step-04-validate.md

@@ -1,272 +1,68 @@
 ---
 name: step-04-validate
-description: Self-check - run tests, verify AC, audit implementation quality
-prev_step: steps/step-03-execute.md
-next_step: steps/step-05-examine.md
+description: Integrate the APEX diff and classify relevant validation without confusing regressions, baseline noise, or unavailable checks.
 ---
 
-# Step 4: Validate (Self-Check)
+# Step 4: Integrate and validate
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+Validation is evidence collection, not a ritual command list.
 
-- 🛑 NEVER claim checks pass when they don't
-- 🛑 NEVER skip any validation step
-- ✅ ALWAYS run typecheck, lint, and tests
-- ✅ ALWAYS verify each acceptance criterion
-- ✅ ALWAYS fix failures before proceeding
-- 📋 YOU ARE A VALIDATOR, not an implementer
-- 💬 FOCUS on "Does it work correctly?"
-- 🚫 FORBIDDEN to proceed with failing checks
+## 1. Review the integrated scope
 
-## EXECUTION PROTOCOLS:
+Inspect current Git status, staged and unstaged diffs, untracked files, generated artifacts, and the task graph. Confirm:
 
-- 🎯 Run all validation commands
-- 💾 Log results to output (if save_mode)
-- 📖 Check each AC against implementation
-- 🚫 FORBIDDEN to mark complete with failures
+- every intended change maps to an acceptance criterion;
+- no unrelated user change was absorbed or overwritten;
+- no task exceeded its write boundary without a recorded re-plan;
+- dependencies and generated outputs are consistent;
+- formatting did not create unrelated churn.
 
-## CONTEXT BOUNDARIES:
+## 2. Discover relevant checks
 
-- Implementation from step-03 (or step-03-execute-teams) is complete
-- Tests may or may not pass yet
-- Type errors may exist
-- Focus is on verification, not new implementation
-- **If `{teams_mode}` = true:** The agent team is still alive. Do NOT shutdown or dismiss teammates. Team shutdown happens in step-09-finish only.
+Read project instructions, package scripts, CI configuration, and nearby tests. Select checks from the changed surface and risk:
 
-## YOUR TASK:
+- syntax, formatting, lint, and types;
+- targeted unit, integration, contract, or end-to-end tests;
+- build, packaging, schema, migration, or generated-code validation;
+- runtime, provider, or public-artifact checks when required.
 
-Validate the implementation by running checks, verifying acceptance criteria, and ensuring quality.
+Do not invent a command because another ecosystem commonly uses it.
 
----
-
-<available_state>
-From previous steps:
-
-| Variable | Description |
-|----------|-------------|
-| `{task_description}` | What was implemented |
-| `{task_id}` | Kebab-case identifier |
-| `{acceptance_criteria}` | Success criteria |
-| `{auto_mode}` | Skip confirmations |
-| `{save_mode}` | Save outputs to files |
-| `{test_mode}` | Include test steps |
-| `{examine_mode}` | Auto-proceed to review |
-| `{output_dir}` | Path to output (if save_mode) |
-| Implementation | Completed in step-03 |
-</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}" "04" "validate" "in_progress"
-```
-
-Append results to `{output_dir}/04-validate.md` as you work.
-
-### 2. Discover Available Commands
-
-Check `package.json` for exact command names:
-```bash
-cat package.json | grep -A 20 '"scripts"'
-```
-
-Look for: `typecheck`, `lint`, `test`, `build`, `format`
-
-### 3. Run Validation Suite
+## 3. Establish baseline when needed
 
-**3.1 Typecheck**
-```bash
-pnpm run typecheck  # or npm run typecheck
-```
-
-**MUST PASS.** If fails:
-1. Read error messages
-2. Fix type issues
-3. Re-run until passing
-
-**3.2 Lint**
-```bash
-pnpm run lint
-```
-
-**MUST PASS.** If fails:
-1. Try auto-fix: `pnpm run lint --fix`
-2. Manually fix remaining
-3. Re-run until passing
-
-**3.3 Tests**
-```bash
-pnpm run test -- --filter={affected-area}
-```
-
-**MUST PASS.** If fails:
-1. Identify failing test
-2. Determine if code bug or test bug
-3. Fix the root cause
-4. Re-run until passing
-
-**If `{save_mode}` = true:** Log each result
+When a broad check fails and causality is unclear, compare against the pre-task revision or use targeted diagnostics that preserve user changes. Classify each result:
 
-### 4. Self-Audit Checklist
+| Status | Meaning |
+|---|---|
+| PASS | Check ran and passed on the current intended state |
+| FAIL_INTRODUCED | Current APEX changes caused the failure |
+| FAIL_PREEXISTING | Failure is reproduced outside the intended change or predates it |
+| FAIL_UNRELATED | Failure belongs to unrelated local changes or an out-of-scope area |
+| UNAVAILABLE | Required service, dependency, credential, command, or environment is absent |
+| NOT_RUN | Check was intentionally omitted with a concrete reason |
 
-Verify each item:
+Never turn `UNAVAILABLE`, `NOT_RUN`, or an unproven baseline inference into PASS.
 
-**Tasks Complete:**
-- [ ] All todos from step-03 marked complete
-- [ ] No tasks skipped without reason
-- [ ] Any blocked tasks have explanation
+## 4. Resolve introduced failures
 
-**Tests Passing:**
-- [ ] All existing tests pass
-- [ ] New tests written for new functionality
-- [ ] No skipped tests without reason
+Fix `FAIL_INTRODUCED` within scope and re-run every invalidated check. Do not repair pre-existing or unrelated failures unless the user expands scope.
 
-**Acceptance Criteria:**
-- [ ] Each AC demonstrably met
-- [ ] Can explain how implementation satisfies AC
-- [ ] Edge cases considered
+If a failure exposes a flawed plan or interface, record a re-plan event and return to execution.
 
-**Patterns Followed:**
-- [ ] Code follows existing patterns
-- [ ] Error handling consistent
-- [ ] Naming conventions match
+## 5. Record validation ledger
 
-### 5. Format Code
+For each check, record command/tool, environment, timestamp, revision, exit status, concise result, classification, and artifact path when useful.
 
-If format command available:
 ```bash
-pnpm run format
-```
-
-### 6. Final Verification
-
-Re-run all checks:
-```bash
-pnpm run typecheck && pnpm run lint
-```
-
-Both MUST pass.
-
-### 7. Present Validation Results
-
-```
-**Validation Complete**
-
-**Typecheck:** ✓ Passed
-**Lint:** ✓ Passed
-**Tests:** ✓ {X}/{X} passing
-**Format:** ✓ Applied
-
-**Acceptance Criteria:**
-- [✓] AC1: Verified by [how]
-- [✓] AC2: Verified by [how]
-
-**Files Modified:** {list}
-
-**Summary:** All checks passing, ready for next step.
-```
-
-### 8. Determine Next Step
-
-**Decision tree:**
-
-```
-IF {test_mode} = true:
-    → Load step-07-tests.md (test analysis and creation)
-
-ELSE IF {examine_mode} = true:
-    → Load step-05-examine.md (adversarial review)
-
-ELSE IF {verify_mode} = true:
-    → Load step-10-verify.md (feature verification)
-
-ELSE IF {auto_mode} = false:
-    → Ask user:
-```
-
-```yaml
-questions:
-  - header: "Next"
-    question: "Validation complete. What would you like to do?"
-    options:
-      - label: "Run adversarial review"
-        description: "Deep review for security, logic, and quality"
-      - label: "Verify feature"
-        description: "Launch app and test feature works"
-      - label: "Complete workflow"
-        description: "Skip review and finalize"
-      - label: "Add tests"
-        description: "Create additional tests first"
-    multiSelect: false
-```
-
-```
-ELSE:
-    → Complete workflow (show final summary)
+python3 "{skill_dir}/scripts/apex-state.py" event --root "$PWD" --run-id "{run_id}" --phase validate --status complete --message "Validation ledger classified"
+python3 "{skill_dir}/scripts/apex-state.py" checkpoint --root "$PWD" --run-id "{run_id}" --phase validate --message "Integrated validation checkpoint"
 ```
 
-### 9. Complete Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Append to `{output_dir}/04-validate.md`:
-```markdown
----
-## Step Complete
-**Status:** ✓ Complete
-**Typecheck:** ✓
-**Lint:** ✓
-**Tests:** ✓
-**Next:** {next step based on flags}
-**Timestamp:** {ISO timestamp}
-```
-
----
-
-## SUCCESS METRICS:
-
-✅ Typecheck passes
-✅ Lint passes
-✅ All tests pass
-✅ All AC verified
-✅ Code formatted
-✅ User informed of status
-
-## FAILURE MODES:
-
-❌ Claiming checks pass when they don't
-❌ Not running all validation commands
-❌ Skipping tests for modified code
-❌ Missing AC verification
-❌ Proceeding with failures
-❌ **CRITICAL**: Not using AskUserQuestion for next step
-
-## VALIDATION PROTOCOLS:
-
-- Run EVERY validation command
-- Fix failures IMMEDIATELY
-- Don't proceed until all green
-- Verify EACH acceptance criterion
-- Document all results
-
----
-
-## NEXT STEP:
-
-Based on flags (check in order):
-- **If test_mode:** Load `./step-07-tests.md`
-- **If examine_mode OR user requests:** 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
+## Routing
 
-<critical>
-Remember: NEVER proceed with failing checks - fix everything first!
-If teams_mode is active: NEVER shutdown teammates - they stay alive until step-09-finish!
-</critical>
+- If `{test_authoring}=on`, load `step-07-tests.md` when new tests remain to be authored.
+- If `{test_authoring}=off`, do not author new tests; report material coverage gaps precisely.
+- If `{test_authoring}=risk-based`, load `step-07-tests.md` only for an evidence-backed material gap.
+- Load `step-05-examine.md` for adversarial or risk-required review.
+- Load `step-10-verify.md` when runtime proof is required and review requirements are already satisfied.
+- Otherwise continue to `step-09-finish.md`.