agileflow 3.3.0 → 3.4.1

package/src/core/commands/status/undo.md

@@ -0,0 +1,191 @@
+---
+description: Undo the last status change for a story (rollback)
+argument-hint: "STORY=<US-ID>"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:status:undo - Rollback story status to previous value"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
+    - "{{RULES:file_preview}}"
+    - "MUST read bus/log.jsonl to find the last status change"
+    - "MUST show current vs previous status as diff"
+    - "MUST confirm with AskUserQuestion before applying"
+    - "MUST log revert event to bus/log.jsonl with type=status-reverted"
+  state_fields:
+    - story_id
+    - current_status
+    - previous_status
+---
+
+# /agileflow:status:undo
+
+Undo the last status change for a story by reading the bus event log to find the previous status.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js status:undo
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:status:undo STORY=<US-ID>`
+**Purpose**: Rollback a story's status to its previous value using bus log history
+
+### Flow
+1. Parse STORY parameter (required)
+2. Read bus/log.jsonl to find status change history for the story
+3. Read current status from status.json
+4. Show diff: current status vs previous status
+5. Confirm via AskUserQuestion
+6. Apply rollback to status.json
+7. Log status-reverted event to bus/log.jsonl
+
+### Critical Rules
+- **Bus log sourced**: Previous status comes from bus/log.jsonl history
+- **Diff preview**: Show current vs previous before applying
+- **Confirmation**: Never write without user approval
+- **Bus logging**: Append status-reverted event after rollback
+- **No history = no undo**: If no previous status event found, inform user
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| STORY | Yes | Story ID to revert (e.g., US-0042) |
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Validate Input
+
+If STORY not provided, list recently changed stories from bus log.
+
+### Step 2: Find Previous Status
+
+Read `docs/09-agents/bus/log.jsonl` and find status change events for the given story. Look for events with:
+- `type: "status"` and matching `story` field
+- `type: "assign"` (initial creation = "ready")
+- `type: "status-reverted"` (previous undos)
+
+Parse the log in reverse chronological order to find:
+1. **Current status event** (most recent)
+2. **Previous status event** (the one before that)
+
+If only one status event exists (the initial creation), inform the user:
+```
+No previous status found for US-0042.
+Current status "ready" is the original status from story creation.
+Nothing to undo.
+```
+
+### Step 3: Read Current State
+
+Read story from `docs/09-agents/status.json` to confirm the current status matches what the bus log says.
+
+### Step 4: Show Diff Preview
+
+```markdown
+## Status Undo: US-0042
+
+| | Status |
+|---|--------|
+| Current | in_progress |
+| Revert to | ready |
+
+Based on bus event from 2026-03-01T14:30:00Z:
+  "Story US-0042 status changed to in_progress"
+```
+
+### Step 5: Confirm Rollback
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Revert US-0042 from 'in_progress' back to 'ready'?",
+  "header": "Confirm undo",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, revert status (Recommended)", "description": "Change status from in_progress back to ready"},
+    {"label": "No, cancel", "description": "Keep current status"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 6: Apply Rollback
+
+On confirmation:
+
+1. **Update status.json** using Edit tool:
+   - Set story status to the previous value
+   - Update the `updated` timestamp
+
+2. **Validate JSON**:
+```bash
+node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
+```
+
+3. **Append to bus/log.jsonl**:
+```json
+{"ts":"<ISO>","type":"status-reverted","from":"USER","story":"<STORY>","from_status":"<current>","to_status":"<previous>","text":"Status reverted from <current> to <previous>"}
+```
+
+### Step 7: Confirm Success
+
+```
+US-0042 status reverted: in_progress -> ready
+```
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No status events in bus log | Check status.json only, inform "no history available" |
+| Story not found | Error: "Story {ID} not found in status.json" |
+| Current status doesn't match bus log | Warn user, show both, ask which to revert to |
+| Multiple rapid changes | Revert to the immediately previous status only |
+
+---
+
+## Example Usage
+
+```bash
+# Undo last status change
+/agileflow:status:undo STORY=US-0042
+
+# Typical flow: accidentally marked done, want to go back
+# Before: done -> After: in_progress
+```
+
+---
+
+## Rules
+
+- **Always preview**: Show current vs previous status before applying
+- **Always confirm**: Use AskUserQuestion before writes
+- **Always log**: Append status-reverted event to bus/log.jsonl
+- **Always validate**: Check JSON integrity after write
+- **One level**: Only undo one status change at a time (run again for more)
+- **Bus log is source of truth**: Previous status comes from event history
+
+---
+
+## Related Commands
+
+- `/agileflow:status` - Update story status
+- `/agileflow:story:view` - View story details
+- `/agileflow:story:edit` - Edit story fields
+- `/agileflow:board` - View kanban board

package/src/core/commands/status.md

@@ -1,5 +1,6 @@
 ---
 description: Update story status and progress
+phase: pre-story
 argument-hint: "STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]"
 compact_context:
   priority: high

package/src/core/commands/story/edit.md

@@ -0,0 +1,204 @@
+---
+description: Edit an existing story's fields (title, owner, estimate, status, priority)
+argument-hint: "STORY=<US-ID> [TITLE=<text>] [OWNER=<id>] [ESTIMATE=<time>] [STATUS=<status>] [PRIORITY=<P0-P3|high|medium|low>]"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:story:edit - Edit story fields with diff-preview-confirm"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
+    - "{{RULES:file_preview}}"
+    - "MUST read current story from status.json BEFORE proposing changes"
+    - "MUST show diff of old vs new values"
+    - "MUST confirm with AskUserQuestion before writing"
+    - "MUST log edit event to bus/log.jsonl"
+  state_fields:
+    - story_id
+    - fields_changed
+---
+
+# /agileflow:story:edit
+
+Edit an existing story's metadata fields with diff preview and confirmation.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js story:edit
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:story:edit STORY=<US-ID> [TITLE=...] [OWNER=...] [ESTIMATE=...] [STATUS=...] [PRIORITY=...]`
+**Purpose**: Edit story fields in status.json with diff-preview-confirm workflow
+
+### Flow
+1. Parse STORY parameter (required) and optional field overrides
+2. Read current story from status.json
+3. Show diff of proposed changes
+4. Confirm via AskUserQuestion
+5. Apply changes to status.json
+6. Log edit event to bus/log.jsonl
+
+### Critical Rules
+- **Diff preview**: Always show old vs new before writing
+- **Confirmation**: Never write without user approval
+- **Bus logging**: Always append story-edited event
+- **Validation**: Verify JSON integrity after write
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| STORY | Yes | Story ID (e.g., US-0042) |
+| TITLE | No | New story title |
+| OWNER | No | New owner (e.g., AG-API, AG-UI) |
+| ESTIMATE | No | New estimate (e.g., 2h, 1d) |
+| STATUS | No | New status (ready, in_progress, blocked, done) |
+| PRIORITY | No | New priority (P0, P1, P2, P3, high, medium, low) |
+
+At least one optional field must be provided (otherwise suggest `/agileflow:story:view`).
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Validate Input
+
+If STORY not provided:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which story would you like to edit?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter story ID", "description": "Provide a US-XXXX identifier"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 2: Read Current Story
+
+Read the story entry from `docs/09-agents/status.json`:
+
+```javascript
+const data = JSON.parse(fs.readFileSync('docs/09-agents/status.json', 'utf8'));
+const story = data.stories[storyId];
+```
+
+If story not found, show error: "Story {STORY} not found in status.json"
+
+### Step 3: Build Change Set
+
+Compare provided fields against current values. Skip fields that match current values (no-op).
+
+If no fields would change, inform user: "No changes detected. Current values match provided values."
+
+### Step 4: Show Diff Preview
+
+Display a clear diff of what will change:
+
+```markdown
+## Editing US-0042: Current Title
+
+| Field | Current | New |
+|-------|---------|-----|
+| title | "Login Form" | "Login Form with Validation" |
+| owner | AG-UI | AG-API |
+| estimate | 2h | 4h |
+
+Files modified:
+1. docs/09-agents/status.json (story entry update)
+2. docs/09-agents/bus/log.jsonl (edit event append)
+```
+
+### Step 5: Confirm Changes
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Apply these changes to US-0042?",
+  "header": "Confirm edit",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, apply changes (Recommended)", "description": "Update status.json and log edit event"},
+    {"label": "No, cancel", "description": "Discard changes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 6: Apply Changes
+
+On confirmation:
+
+1. **Update status.json** using Edit tool or jq:
+   - Update only the changed fields in the story entry
+   - Set `updated` timestamp to current ISO date
+
+2. **Validate JSON**:
+```bash
+node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
+```
+
+3. **Append to bus/log.jsonl**:
+```json
+{"ts":"<ISO>","type":"story-edited","from":"USER","story":"<STORY>","changes":{"field":"old_value->new_value"},"text":"Story edited: <changed fields>"}
+```
+
+### Step 7: Confirm Success
+
+```
+Story US-0042 updated:
+  title: "Login Form" -> "Login Form with Validation"
+  owner: AG-UI -> AG-API
+```
+
+---
+
+## Example Usage
+
+```bash
+# Edit title
+/agileflow:story:edit STORY=US-0042 TITLE="Updated Title"
+
+# Change owner and estimate
+/agileflow:story:edit STORY=US-0042 OWNER=AG-API ESTIMATE=4h
+
+# Change status
+/agileflow:story:edit STORY=US-0042 STATUS=blocked
+
+# Multiple fields at once
+/agileflow:story:edit STORY=US-0042 TITLE="New Title" OWNER=AG-UI PRIORITY=high
+```
+
+---
+
+## Rules
+
+- **Always preview**: Show diff before applying
+- **Always confirm**: Use AskUserQuestion before writes
+- **Always log**: Append edit event to bus/log.jsonl
+- **Always validate**: Check JSON integrity after write
+- **No silent changes**: Every change must be visible to the user
+
+---
+
+## Related Commands
+
+- `/agileflow:story:view` - View story details
+- `/agileflow:story:list` - List all stories
+- `/agileflow:story` - Create new story
+- `/agileflow:status` - Quick status update
+- `/agileflow:epic:edit` - Edit epic fields

package/src/core/commands/story/view.md

@@ -6,6 +6,8 @@ compact_context:
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:story:view - Views story with context-aware actions"
     - "MUST read story file and status.json entry"
+    - "MUST parse AC items and cross-reference with test files for verified/pending status"
+    - "MUST display AC Progress: X/Y verified with visual progress bar"
     - "MUST display full story: AC (with checkboxes), tests, dependencies, blockers"
     - "MUST offer CONTEXT-AWARE actions based on story status"
     - "STATUS=ready → Start work, validate, view research"
@@ -51,13 +53,15 @@ node .agileflow/scripts/obtain-context.js story:view
 
 ### Flow
 1. Read story file and status.json entry
-2. Display full story details (AC, tests, progress)
-3. Offer actions based on current status
-4. Execute selected action
+2. Parse AC items and cross-reference with test files
+3. Display full story details (AC progress, tests, dependencies)
+4. Offer actions based on current status
+5. Execute selected action
 
 ### Critical Rules
+- **AC progress**: Parse AC items, cross-reference with tests, show X/Y verified with progress bar
 - **Context-aware actions**: Different options based on story status
-- **Show everything**: AC, test status, dependencies, blockers
+- **Show everything**: AC progress, test status, dependencies, blockers
 - **Always offer next steps**: End with relevant AskUserQuestion
 <!-- COMPACT_SUMMARY_END -->
 
@@ -109,7 +113,22 @@ cat docs/09-agents/status.json | jq '.stories["<STORY>"]'
 cat docs/07-testing/test-cases/<STORY>.md
 ```
 
-### Step 3: Display Story Details
+### Step 3: Parse AC and Compute Progress
+
+Before displaying, count acceptance criteria completion:
+
+1. **Parse AC from status.json**: Read the `ac` array from the story entry (string list of AC items)
+2. **Parse AC from story file** (if exists): Look for Given/When/Then patterns or `- [ ]`/`- [x]` checkboxes
+3. **Cross-reference with tests**: Check `docs/07-testing/test-cases/<STORY>.md` and `__tests__/<STORY>.test.*` for matching test descriptions
+4. **Compute progress**: Count verified (has matching test OR `[x]` checkbox) vs total AC items
+5. **Build ac_status**: `{ total: N, verified: M, items: [{text, verified, test_match}] }`
+
+**Matching rules:**
+- AC is "verified" if: story file has `[x]` checkbox for it, OR a test file has a describe/it/test matching the AC text
+- Use fuzzy substring matching (lowercase, strip "given/when/then" prefixes)
+- If no test files found, fall back to checkbox status only
+
+### Step 4: Display Story Details
 
 ```markdown
 ## US-0042: User Login Form
@@ -124,11 +143,14 @@ cat docs/07-testing/test-cases/<STORY>.md
 
 ---
 
-### Acceptance Criteria
+### AC Progress: 1/3 verified
+
+[==========....................] 33%
 
 - [x] Given a user on the login page
       When they enter valid credentials
       Then they are redirected to dashboard
+      (matched: LoginForm.test.tsx > "redirects on valid credentials")
 
 - [ ] Given a user on the login page
       When they enter invalid credentials
@@ -143,7 +165,7 @@ cat docs/07-testing/test-cases/<STORY>.md
 ### Dependencies
 
 - US-0040: API authentication endpoint (done)
-- US-0041: Session management (ready) ⚠️ Not started yet
+- US-0041: Session management (ready) - Not started yet
 
 ---
 

package/src/core/commands/story-validate.md

@@ -1,5 +1,6 @@
 ---
 description: Validate story completeness before development
+phase: pre-story
 argument-hint: "STORY=<US-ID>"
 compact_context:
   priority: high

package/src/core/commands/story.md

@@ -1,5 +1,6 @@
 ---
 description: Create a user story with acceptance criteria
+phase: pre-story
 argument-hint: "EPIC=<EP-ID> STORY=<US-ID> TITLE=<text> OWNER=<id> [ESTIMATE=<pts>] [AC=<list>] [TDD=true]"
 compact_context:
   priority: high