agileflow 3.4.3 → 4.0.0-alpha.2

package/src/core/commands/audit.md

@@ -1,531 +0,0 @@
----
-description: Audit story completion - tests + acceptance criteria verification (GSD pattern)
-phase: post-impl
-argument-hint: "STORY=<US-ID>"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "STORY ID is REQUIRED - always ask if missing"
-    - "Run STEP 0 context activation before any other action"
-    - "Execute 4-step audit: tests, AC check, learnings, verdict"
-    - "Generate clear PASS/FAIL report with visual indicators"
-    - "On PASS, suggest marking story complete"
-  state_fields:
-    - story_id
-    - audit_result
-    - tests_passed
-    - ac_verified
----
-
-# Story Audit
-
-Verify story completion through the GSD (Get Stuff Done) audit cycle: run tests, check acceptance criteria, capture learnings, and provide clear PASS/FAIL verdict.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js audit
-```
-
-This gathers git status, stories/epics, session state, and registers for PreCompact.
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-
-## Compact Summary
-
-**Role**: Story Auditor - GSD verification cycle before completion
-
-**Critical Behavioral Rules**:
-1. ALWAYS run STEP 0 activation before any other action
-2. STORY ID is REQUIRED - ask user if not provided
-3. Execute 4-step audit: tests, AC check, learnings, verdict
-4. Generate clear PASS/FAIL report with visual indicators
-5. On PASS, suggest marking story complete
-
-**Workflow**:
-1. **Parse Story**: Get story ID from argument or ask user
-2. **Run Tests**: Execute test command from environment.json
-3. **Check AC**: Display acceptance criteria, ask user to verify each
-4. **Capture Learnings**: Prompt for insights and technical debt
-5. **Verdict**: PASS if tests pass AND all AC verified, otherwise FAIL
-6. **Next Steps**: Suggest marking complete (PASS) or fixing issues (FAIL)
-
-**Audit Result Values**:
-- `PASS`: Tests passing + All AC verified
-- `FAIL`: Tests failing OR Any AC unverified
-
-**Output Format Requirements**:
-- Display test results with counts and duration
-- Show each AC with checkbox status
-- Clear PASS/FAIL verdict with blocking issues if any
-- Actionable next steps
-
-**Integration**:
-- Uses: environment.json (test config), status.json (story/AC data)
-- Logs to: docs/09-agents/bus/log.jsonl (learnings)
-- Related: /agileflow:verify, /agileflow:story-validate, /agileflow:status
-
-**Tool Usage Examples**:
-
-Task Tracking:
-```xml
-<!-- Create tasks for multi-step workflow -->
-<invoke name="TaskCreate">
-<parameter name="subject">Parse story ID and load story data</parameter>
-<parameter name="description">Load story from status.json and verify it exists</parameter>
-<parameter name="activeForm">Loading story</parameter>
-</invoke>
-<!-- Then use TaskUpdate with taskId to mark in_progress/completed -->
-```
-
-AskUserQuestion (AC Verification):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Verify each acceptance criterion is met for US-0129:",
-  "header": "AC Check",
-  "multiSelect": true,
-  "options": [
-    {"label": "AC1: Create audit.md", "description": "File exists in commands/"},
-    {"label": "AC2: Accept story ID", "description": "Argument parsing works"},
-    {"label": "AC3: Run tests", "description": "Tests execute and report"},
-    {"label": "AC4: Check AC met", "description": "AC verification works"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Prompt
-
-ROLE: Story Auditor
-
-INPUTS
-STORY=<US-ID>   Required - story to audit
-
-TASK TRACKING
-**CRITICAL**: Immediately create tasks using TaskCreate tool:
-```
-1. Parse story ID and load story data
-2. Run project tests
-3. Verify acceptance criteria with user
-4. Capture learnings
-5. Generate audit verdict and next steps
-```
-
-ACTIONS
-
-### Step 1: Parse Story ID
-
-If STORY argument not provided, ask user:
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Which story would you like to audit?",
-  "header": "Story ID",
-  "multiSelect": false,
-  "options": [
-    {"label": "Enter story ID", "description": "e.g., US-0129"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-Load story from `docs/09-agents/status.json`:
-- Verify story exists
-- Get title, epic, acceptance_criteria array
-- Check current status (should be in_progress or ready)
-
-### Step 2: Run Tests
-
-Read `docs/00-meta/environment.json` for test configuration:
-- `test_command` - Command to run (e.g., "npm test")
-- `test_timeout_ms` - Maximum wait time
-
-Execute tests:
-```bash
-# Run with timeout, capture exit code
-timeout 120s npm test 2>&1
-EXIT_CODE=$?
-```
-
-Parse results:
-- Exit code 0 = PASSING
-- Exit code non-zero = FAILING
-- Extract pass/fail counts if possible (Jest/Pytest patterns)
-
-### Step 3: Verify Acceptance Criteria
-
-**3a. Run AC-to-Test Matcher (automated pre-check)**
-
-Before asking the user to verify AC manually, run the automated AC-to-test matcher:
-
-```bash
-node -e "
-const { matchACToTests } = require('./.agileflow/scripts/lib/ac-test-matcher');
-const result = matchACToTests('{{STORY_ID}}');
-console.log(JSON.stringify(result, null, 2));
-"
-```
-
-This returns matched/unmatched AC with confidence levels. Use the results to pre-populate the checklist.
-
-**3b. Display AC checklist with auto-matched items**
-
-Show each AC with auto-match status. High-confidence matches are pre-checked:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Verify acceptance criteria for {{STORY_ID}} ({{matched}}/{{total}} auto-matched to tests):",
-  "header": "AC Check",
-  "multiSelect": true,
-  "options": [
-    {"label": "AC1: {{AC_1}} [auto-verified]", "description": "Matched to {{test_file}} (high confidence)"},
-    {"label": "AC2: {{AC_2}} [auto-verified]", "description": "Matched to {{test_file}} (medium confidence)"},
-    {"label": "AC3: {{AC_3}} [needs manual check]", "description": "No matching tests found - verify manually"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-Auto-matched AC (high/medium confidence) should be pre-selected. Unmatched AC require manual verification.
-
-**3c. Write ac_status to status.json**
-
-After verification, write structured `ac_status` to the story in status.json:
-
-```json
-{
-  "ac_status": {
-    "0": "auto-verified",
-    "1": "auto-verified",
-    "2": "verified",
-    "3": "unverified"
-  },
-  "ac_coverage": 0.75
-}
-```
-
-Values: `auto-verified` (test match), `verified` (manual confirm), `likely-covered` (medium confidence), `unverified` (not confirmed)
-
-Calculate verification rate:
-- Count verified + auto-verified vs total AC
-- 100% = All verified
-- <100% = Partial
-
-### Step 4: Capture Learnings
-
-Prompt user for insights:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "What did you learn during this story? (Select or enter custom)",
-  "header": "Learnings",
-  "multiSelect": false,
-  "options": [
-    {"label": "Enter learnings", "description": "Share insights, patterns discovered, or improvements"},
-    {"label": "No learnings to capture", "description": "Skip this step"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-If learnings provided, log to `docs/09-agents/bus/log.jsonl`:
-```json
-{
-  "type": "audit_learnings",
-  "story": "US-0129",
-  "timestamp": "2026-01-19T12:00:00Z",
-  "learnings": "User's learnings text here",
-  "tests_passed": true,
-  "ac_verified": 7,
-  "ac_total": 7
-}
-```
-
-### Step 5: Generate Verdict
-
-**PASS Criteria**:
-- Tests passing (exit code 0)
-- All AC verified (100%)
-
-**FAIL Criteria**:
-- Tests failing (exit code non-zero)
-- OR any AC unverified (<100%)
-
----
-
-## Output Format
-
-### PASS Report
-
-```
-========================================
-      STORY AUDIT: US-0129
-========================================
-
-TESTS
-Command: npm test
-Result: PASSED (2,201 passed, 0 failed)
-Duration: 45.2s
-
-ACCEPTANCE CRITERIA
-[x] Create packages/cli/src/core/commands/audit.md
-[x] Accept story ID as argument
-[x] Run tests and report pass/fail
-[x] Check acceptance criteria met
-[x] Prompt for learnings to capture
-[x] Output: PASS/FAIL with recommended next action
-[x] On PASS, suggest marking story complete
-
-AC Verification: 7/7 (100%)
-
-========================================
-      AUDIT RESULT: PASS
-========================================
-Tests: PASSING
-AC: ALL VERIFIED (7/7)
-
-Learnings captured:
-- GSD audit pattern successfully integrated
-
-NEXT STEPS:
-1. Mark story complete: /agileflow:status US-0129 STATUS=done
-2. Review epic progress: /agileflow:epic EP-0022
-```
-
-### FAIL Report
-
-```
-========================================
-      STORY AUDIT: US-0129
-========================================
-
-TESTS
-Command: npm test
-Result: FAILED (40 passed, 3 failed)
-Duration: 12.8s
-
-ACCEPTANCE CRITERIA
-[x] Create packages/cli/src/core/commands/audit.md
-[x] Accept story ID as argument
-[x] Run tests and report pass/fail
-[ ] Check acceptance criteria met
-[ ] Prompt for learnings to capture
-[x] Output: PASS/FAIL with recommended next action
-[x] On PASS, suggest marking story complete
-
-AC Verification: 5/7 (71%)
-
-========================================
-      AUDIT RESULT: FAIL
-========================================
-Tests: FAILING (3 failed)
-AC: PARTIAL (5/7)
-
-BLOCKING ISSUES:
-- Test: audit.test.ts:42 - Expected PASS verdict
-- AC: "Check acceptance criteria met" - Not implemented
-- AC: "Prompt for learnings" - Missing
-
-NEXT STEPS:
-1. Fix failing tests
-2. Complete missing AC items
-3. Re-run: /agileflow:audit US-0129
-```
-
----
-
-## Post-Audit Actions
-
-### If PASS
-
-Offer to mark story complete with full context:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "[STORY] passed audit: [test_count] tests passing, [ac_count]/[ac_total] AC verified. What next?",
-  "header": "Complete",
-  "multiSelect": false,
-  "options": [
-    {"label": "Mark [STORY] complete (Recommended)", "description": "Update status to done - all AC verified, tests passing"},
-    {"label": "Run tests once more before completing", "description": "Re-run test suite to double-check [test_count] tests"},
-    {"label": "View [EPIC] progress", "description": "Check epic completion: [completed]/[total] stories done ([percent]%)"},
-    {"label": "Done without marking complete", "description": "Audit passed but don't update status yet"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-If "Mark complete":
-1. Update status.json: `status: "done"`, add `completed_at` timestamp
-2. Add audit summary to story
-3. Log completion to bus/log.jsonl
-
-### If FAIL
-
-Offer to help fix issues with specific context:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "[STORY] failed audit: [fail_count] tests failing, [unverified] AC unverified. How to proceed?",
-  "header": "Fix Issues",
-  "multiSelect": false,
-  "options": [
-    {"label": "Fix [fail_count] failing test(s) (Recommended)", "description": "Debug: [first_failing_test_name] and [fail_count-1] other(s)"},
-    {"label": "Implement [unverified] missing AC item(s)", "description": "AC not met: [first_unverified_ac_text]"},
-    {"label": "Re-run audit after manual fixes", "description": "I'll fix issues myself, then re-audit"},
-    {"label": "Done for now", "description": "Audit failed - [STORY] stays in_progress"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-## Error Handling
-
-### Story Not Found
-```
-Story US-9999 not found in status.json
-
-Available in_progress stories:
-- US-0129: Create /agileflow:audit command
-- US-0130: Add phase handoff summaries
-
-Run: /agileflow:audit US-0129
-```
-
-### No Test Configuration
-```
-No test configuration found.
-
-Run /agileflow:session:init to configure:
-- test_command
-- test_timeout_ms
-
-Or manually create docs/00-meta/environment.json
-```
-
-### Story Already Complete
-```
-Story US-0129 is already marked as 'done'
-
-To re-audit, first change status:
-/agileflow:status US-0129 STATUS=in_progress
-
-Then run audit again.
-```
-
----
-
-## Expected Output
-
-### Success - Story Passes Audit
-
-```
-========================================
-      STORY AUDIT: US-0129
-========================================
-
-TESTS
-Command: npm test
-Result: PASSED (2,201 passed, 0 failed)
-Duration: 45.2s
-
-ACCEPTANCE CRITERIA
-[x] Create packages/cli/src/core/commands/audit.md
-[x] Accept story ID as argument
-[x] Run tests and report pass/fail
-[x] Check acceptance criteria met
-[x] Prompt for learnings to capture
-[x] Output: PASS/FAIL with recommended next action
-[x] On PASS, suggest marking story complete
-
-AC Verification: 7/7 (100%)
-
-========================================
-      AUDIT RESULT: PASS
-========================================
-Tests: PASSING
-AC: ALL VERIFIED (7/7)
-
-Learnings captured:
-- GSD audit pattern successfully integrated
-
-NEXT STEPS:
-1. Mark story complete: /agileflow:status US-0129 STATUS=done
-2. Review epic progress: /agileflow:epic EP-0022
-```
-
-### Error - Story Fails Audit
-
-```
-========================================
-      STORY AUDIT: US-0129
-========================================
-
-TESTS
-Command: npm test
-Result: FAILED (40 passed, 3 failed)
-Duration: 12.8s
-
-ACCEPTANCE CRITERIA
-[x] Create packages/cli/src/core/commands/audit.md
-[x] Accept story ID as argument
-[x] Run tests and report pass/fail
-[ ] Check acceptance criteria met
-[ ] Prompt for learnings to capture
-[x] Output: PASS/FAIL with recommended next action
-[x] On PASS, suggest marking story complete
-
-AC Verification: 5/7 (71%)
-
-========================================
-      AUDIT RESULT: FAIL
-========================================
-Tests: FAILING (3 failed)
-AC: PARTIAL (5/7)
-
-BLOCKING ISSUES:
-- Test: audit.test.ts:42 - Expected PASS verdict
-- AC: "Check acceptance criteria met" - Not implemented
-- AC: "Prompt for learnings" - Missing
-
-NEXT STEPS:
-1. Fix failing tests
-2. Complete missing AC items
-3. Re-run: /agileflow:audit US-0129
-```
-
-### Error - Story Not Found
-
-```
-❌ Story US-9999 not found in status.json
-
-Available in_progress stories:
-- US-0129: Create /agileflow:audit command
-- US-0130: Add phase handoff summaries
-
-Run: /agileflow:audit US-0129
-```
-
----
-
-## Related Commands
-
-- `/agileflow:verify` - Run tests only (no AC check)
-- `/agileflow:story-validate` - Validate story structure before development
-- `/agileflow:status` - Update story status
-- `/agileflow:epic` - View epic progress