agileflow 3.3.0 → 3.4.1

package/src/core/commands/ads/track.md

@@ -0,0 +1,288 @@
+---
+description: Ads performance tracker — ingest performance CSVs, establish baselines, detect winners and anomalies, output KPI dashboard with trend analysis
+argument-hint: "<performance-data> [PERIOD=7d] [BASELINE=auto]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:track - Performance tracking and winner detection"
+    - "Ingest CSV/pasted performance data, establish baselines, detect anomalies"
+    - "Winner detection: statistical significance, cost efficiency, trend direction"
+    - "Delegate to ads-performance-tracker agent for analysis"
+    - "State persisted in docs/08-project/ads-tracking/"
+  state_fields:
+    - period
+    - baseline
+    - campaigns_tracked
+    - winners
+    - anomalies
+---
+
+# /agileflow:ads:track
+
+Ingest ad performance data (CSVs or pasted), establish baselines, detect winners and anomalies, and output a KPI dashboard with trend analysis and actionable recommendations.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:track <performance-data>                                # Analyze performance data
+/agileflow:ads:track <csv-file> PERIOD=30d                             # 30-day trend analysis
+/agileflow:ads:track <data> BASELINE=last-report                       # Compare against last saved baseline
+/agileflow:ads:track compare <old-csv> <new-csv>                       # Period-over-period comparison
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| performance-data | CSV, pasted text, or file path | Required | Performance metrics to analyze |
+| PERIOD | 1d, 7d, 14d, 30d, 90d | 7d | Analysis period |
+| BASELINE | auto, last-report, or specific date | auto | Baseline for comparison |
+| FORMAT | dashboard, csv, both | dashboard | Output format |
+
+---
+
+## Data Formats Accepted
+
+### CSV Export (preferred)
+```csv
+Campaign,Ad Set,Ad,Impressions,Clicks,CTR,CPC,Spend,Conversions,CVR,CPA,ROAS,Date
+Brand - Search,Brand Terms,Ad 1,15234,1843,12.1%,$0.45,$829,234,12.7%,$3.54,8.2,2026-02-28
+```
+
+### Pasted Table
+```
+Campaign         | Spend  | Clicks | CPA    | ROAS
+Brand Search     | $829   | 1,843  | $3.54  | 8.2x
+Non-Brand Search | $2,341 | 987    | $15.20 | 2.1x
+Meta Prospecting | $1,560 | 2,104  | $28.40 | 1.4x
+```
+
+### Platform-Specific Exports
+- Google Ads: Campaign/Ad Group/Keyword reports
+- Meta Ads Manager: Campaign/Ad Set/Ad performance export
+- LinkedIn: Campaign Manager CSV export
+- TikTok: Business Center export
+
+---
+
+## Analysis Framework
+
+### STEP 1: Parse & Normalize Data
+
+Delegate to the `ads-performance-tracker` agent:
+
+```xml
+<invoke name="Agent">
+<parameter name="description">Analyze ad performance data</parameter>
+<parameter name="prompt">TASK: Analyze ad performance data and generate KPI dashboard.
+
+PERFORMANCE DATA:
+{data}
+
+PERIOD: {period}
+BASELINE: {baseline}
+
+Follow the full analysis framework in your instructions.
+
+OUTPUT: Complete KPI dashboard with winner detection, anomaly alerts, and recommendations.</parameter>
+<parameter name="subagent_type">ads-performance-tracker</parameter>
+</invoke>
+```
+
+### STEP 2: Establish Baselines
+
+If this is the first analysis or BASELINE=auto:
+- Calculate median and mean for each metric across all campaigns
+- Set thresholds at 1 standard deviation from mean
+- Save baseline to `docs/08-project/ads-tracking/baseline-{YYYYMMDD}.json`
+
+If BASELINE=last-report:
+- Load the most recent baseline from `docs/08-project/ads-tracking/`
+- Compare current metrics against saved baseline
+
+### STEP 3: Winner Detection
+
+Apply statistical winner detection:
+
+| Metric | Winner Threshold | Confidence Requirement |
+|--------|-----------------|----------------------|
+| CPC | < 0.7x median CPC | 100+ clicks |
+| CTR | > 1.5x median CTR | 1000+ impressions |
+| CVR | > 1.5x median CVR | 50+ clicks |
+| CPA | < 0.7x median CPA | 20+ conversions |
+| ROAS | > 1.5x median ROAS | $500+ spend |
+
+**Winner Classification:**
+| Class | Criteria | Action |
+|-------|----------|--------|
+| **Strong Winner** | Beats threshold on 3+ metrics | Scale 20%/week |
+| **Emerging Winner** | Beats threshold on 1-2 metrics | Continue monitoring |
+| **Stable Performer** | Within 1 SD of median on all metrics | Maintain |
+| **Underperformer** | Below median on 2+ metrics | Optimize or pause |
+| **Kill** | CPA > 3x target OR ROAS < 0.5x target | Pause immediately |
+
+### STEP 4: Anomaly Detection
+
+Flag anomalies when:
+- **Spend spike**: Daily spend > 2x average (possible budget cap issue)
+- **CTR drop**: CTR drops > 30% day-over-day (ad fatigue, audience saturation)
+- **CPC surge**: CPC increases > 50% week-over-week (competition, quality score)
+- **Conversion drop**: Conversions drop > 40% with stable traffic (tracking break, landing page issue)
+- **ROAS collapse**: ROAS drops below 1:1 (unprofitable, needs immediate action)
+
+### STEP 5: Trend Analysis
+
+For each campaign, calculate:
+- **7-day rolling average** for CPC, CTR, CVR, CPA
+- **Trend direction**: Improving, Stable, Declining
+- **Velocity**: Rate of change (slow, moderate, rapid)
+- **Projected trajectory**: If trend continues, estimated metrics in 7/14/30 days
+
+---
+
+## Output Format
+
+```markdown
+# Ads Performance Dashboard
+
+**Generated**: {YYYY-MM-DD}
+**Period**: {start_date} to {end_date} ({N} days)
+**Platforms**: {platforms}
+**Total Spend**: ${total_spend}
+**Baseline**: {baseline_source}
+
+---
+
+## Executive Summary
+
+| Metric | Current | Baseline | Change | Trend |
+|--------|---------|----------|--------|-------|
+| Total Spend | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
+| Avg CPC | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
+| Avg CTR | {current}% | {baseline}% | {+/-}% | {→/↑/↓} |
+| Total Conversions | {current} | {baseline} | {+/-}% | {→/↑/↓} |
+| Avg CPA | ${current} | ${baseline} | {+/-}% | {→/↑/↓} |
+| Blended ROAS | {current}x | {baseline}x | {+/-}% | {→/↑/↓} |
+
+---
+
+## Winner Detection
+
+### Strong Winners (scale these)
+| Campaign | CPC | CTR | CVR | CPA | ROAS | Action |
+|----------|-----|-----|-----|-----|------|--------|
+| {name} | ${cpc} ✅ | {ctr}% ✅ | {cvr}% ✅ | ${cpa} ✅ | {roas}x | Scale 20%/wk |
+
+### Emerging Winners (monitor closely)
+| Campaign | CPC | CTR | CVR | CPA | ROAS | Action |
+|----------|-----|-----|-----|-----|------|--------|
+| {name} | ${cpc} | {ctr}% ✅ | {cvr}% | ${cpa} | {roas}x | Continue 7d |
+
+### Kill List (pause immediately)
+| Campaign | Issue | CPA vs Target | Spend Wasted | Action |
+|----------|-------|--------------|-------------|--------|
+| {name} | CPA 3.2x target | ${cpa} vs ${target} | ${wasted} | **PAUSE NOW** |
+
+---
+
+## Anomaly Alerts
+
+| Alert | Campaign | Metric | Expected | Actual | Severity |
+|-------|----------|--------|----------|--------|----------|
+| ⚠️ | {name} | CPC | ${expected} | ${actual} | HIGH |
+| 🔴 | {name} | Conversions | {expected} | {actual} | CRITICAL |
+
+---
+
+## Campaign Performance
+
+### {Campaign Name}
+
+| Metric | Value | vs Baseline | Trend (7d) |
+|--------|-------|-------------|------------|
+| Spend | ${spend} | {+/-}% | {→/↑/↓} |
+| Impressions | {impr} | {+/-}% | {→/↑/↓} |
+| Clicks | {clicks} | {+/-}% | {→/↑/↓} |
+| CTR | {ctr}% | {+/-}% | {→/↑/↓} |
+| CPC | ${cpc} | {+/-}% | {→/↑/↓} |
+| Conversions | {conv} | {+/-}% | {→/↑/↓} |
+| CVR | {cvr}% | {+/-}% | {→/↑/↓} |
+| CPA | ${cpa} | {+/-}% | {→/↑/↓} |
+| ROAS | {roas}x | {+/-}% | {→/↑/↓} |
+
+**Classification**: {Strong Winner / Emerging / Stable / Underperformer / Kill}
+
+---
+
+## Budget Reallocation Recommendation
+
+| Campaign | Current Budget | Recommended | Change | Reason |
+|----------|---------------|-------------|--------|--------|
+| {winner} | ${current} | ${recommended} | +20% | Strong winner, scale |
+| {loser} | ${current} | ${recommended} | -100% | 3x kill rule |
+
+**Estimated Impact**: Reallocating ${amount} from underperformers to winners = estimated {X}% CPA reduction
+
+---
+
+## Recommendations
+
+### Immediate (this session)
+1. **Pause {campaign}** — CPA ${X} exceeds 3x target (${target})
+2. **Scale {campaign}** — Strong winner, increase budget 20%
+
+### This Week
+3. **Refresh creative for {campaign}** — CTR declining 15% WoW (ad fatigue)
+4. **Check tracking for {campaign}** — Conversions dropped 40% with stable clicks
+
+### This Month
+5. **Test new angles** — Run /agileflow:ads:generate + /agileflow:ads:test-plan
+6. **Platform diversification** — {platform} ROAS declining, test {other_platform}
+```
+
+Save dashboard to `docs/08-project/ads-tracking/dashboard-{YYYYMMDD}.md`.
+Save baseline to `docs/08-project/ads-tracking/baseline-{YYYYMMDD}.json`.
+
+---
+
+## Present Results
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Performance dashboard generated. {winners} winners, {kills} to kill, {anomalies} anomalies. Total spend: ${spend}, blended ROAS: {roas}x.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Pause kill-list campaigns now (Recommended)", "description": "Stop wasting ${wasted_amount}/mo on {kill_count} underperforming campaigns"},
+    {"label": "Generate replacement ad copy", "description": "Run /agileflow:ads:generate for fatigued campaigns"},
+    {"label": "Create test plan for winners", "description": "Run /agileflow:ads:test-plan to scale winning angles"},
+    {"label": "Run full ads audit", "description": "Run /agileflow:ads:audit for comprehensive 190-check analysis"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:track` - Performance tracking with winner detection
+
+**Input**: Performance CSV/data from ad platforms
+
+**Analysis**: Baselines, winner detection (5 classes), anomaly alerts, trend analysis, budget reallocation
+
+**Key Rules**: 3x Kill Rule for CPA, 20% max scaling per week, 100+ clicks for CPC confidence
+
+**Output**: KPI dashboard + baseline JSON + recommendations
+
+**Usage**: `/agileflow:ads:track <data> [PERIOD=7d] [BASELINE=auto]`
+
+**Files**: `docs/08-project/ads-tracking/dashboard-{YYYYMMDD}.md`, `baseline-{YYYYMMDD}.json`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads/youtube.md

@@ -0,0 +1,124 @@
+---
+description: YouTube Ads audit for video campaign types, ad formats, targeting strategy, bidding optimization, and creative effectiveness
+argument-hint: "<account-data>"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:youtube - YouTube Ads audit"
+    - "Inline command - check video formats, campaign types, targeting"
+    - "YouTube runs through Google Ads platform"
+  state_fields:
+    - youtube_score
+---
+
+# /agileflow:ads:youtube
+
+Run an inline audit on YouTube advertising campaigns (managed through Google Ads) focusing on video-specific optimization.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:youtube <account-data>                 # YouTube Ads audit
+```
+
+---
+
+## The 8 Checks
+
+| # | Check | Severity | Pass Criteria |
+|---|-------|----------|---------------|
+| YT-1 | Campaign type alignment | HIGH | Correct campaign type for objective |
+| YT-2 | Video format coverage | HIGH | Multiple formats tested (skippable, bumper, shorts) |
+| YT-3 | Targeting strategy | HIGH | Audience targeting refined beyond demographics |
+| YT-4 | Bidding strategy | HIGH | CPV/CPM/tCPA based on objective |
+| YT-5 | Creative hook in 5 seconds | CRITICAL | First 5 seconds grab attention (before skip) |
+| YT-6 | Companion banner | MEDIUM | Companion banner uploaded for desktop |
+| YT-7 | Frequency capping | HIGH | Frequency cap set (3-5 per week recommended) |
+| YT-8 | Conversion tracking | CRITICAL | YouTube conversions tracked in Google Ads |
+
+---
+
+## Process
+
+### STEP 1: Apply All 8 Checks
+
+Review the account data against each check. For YouTube specifically:
+
+**Campaign types**:
+| Type | Best For | Format |
+|------|---------|--------|
+| Video Reach | Awareness | Bumper (6s) + In-stream |
+| Video Views | Consideration | Skippable in-stream + in-feed |
+| Video Action | Conversions | Skippable in-stream with CTA |
+| Shorts Ads | Awareness + young demo | Vertical 60s max |
+| Demand Gen | Full-funnel | YouTube + Discover + Gmail |
+
+**Creative best practices**:
+- First 5 seconds: Brand + hook (many viewers skip at 5s)
+- CTA overlay throughout (not just at end)
+- Mobile-first: 70%+ YouTube watching is mobile
+- Captions/subtitles: Many watch without sound
+- 15-30 seconds optimal for action campaigns
+- Shorts: Vertical 9:16, authentic style
+
+**Targeting options**:
+- Custom Intent: Based on Google search behavior
+- Affinity: Interest-based broad reach
+- In-Market: Active purchase intent
+- Remarketing: Website visitors, video viewers
+- Customer Match: Upload customer lists
+- Topic/placement: Specific channels/videos
+
+### STEP 2: Score
+
+```
+YouTube Score = 100 - sum(severity_deductions)
+```
+
+Deductions: CRITICAL (-15), HIGH (-8), MEDIUM (-4), LOW (-2)
+
+### STEP 3: Output
+
+```markdown
+## YouTube Ads Audit
+
+**YouTube Score**: {X}/100
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| YT-1 Campaign types | PASS/FAIL | {types in use} |
+| YT-2 Video formats | PASS/FAIL | {formats tested} |
+| YT-3 Targeting | PASS/FAIL | {targeting methods} |
+| YT-4 Bidding | PASS/FAIL | {strategies used} |
+| YT-5 5-second hook | PASS/FAIL | {creative analysis} |
+| YT-6 Companion banner | PASS/FAIL | {banner status} |
+| YT-7 Frequency cap | PASS/FAIL | {cap settings} |
+| YT-8 Conversion tracking | PASS/FAIL | {tracking status} |
+
+### Key Recommendations
+1. {Top priority fix}
+2. {Second priority}
+3. {Third priority}
+
+### YouTube-Specific Tips
+- Video Action campaigns drive most conversions (skippable in-stream with CTA)
+- Custom Intent audiences (based on search) are YouTube's secret weapon
+- Always create Shorts versions of successful long-form ads
+- Test bumper ads (6s) for remarketing - cheap and high frequency
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:youtube` - YouTube Ads audit
+
+**Checks**: 8 (inline, no separate agent)
+
+**Key**: 5-second hook, campaign types, Custom Intent targeting, frequency caps
+
+**Quick Usage**: `/agileflow:ads:youtube <account-data>`
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/ads.md

@@ -0,0 +1,140 @@
+---
+description: Paid advertising audit & planning toolkit - multi-platform account audits, campaign planning, budget optimization, and competitive intelligence
+argument-hint: "[subcommand] [account-data]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads - Paid advertising router"
+    - "Route to the appropriate sub-command based on user intent"
+    - "If no sub-command specified, show the quick reference guide"
+  state_fields:
+    - subcommand
+    - platforms
+---
+
+# /agileflow:ads
+
+Paid advertising audit & planning toolkit for multi-platform account optimization. Routes to specialized sub-commands.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:audit <account-data>                    # Full multi-platform audit (6 parallel analyzers)
+/agileflow:ads:health <data+url>                        # Unified marketing health scorecard (ads+SEO+landing)
+/agileflow:ads:generate <product-description>           # Bulk ad copy generation (40+ variants)
+/agileflow:ads:test-plan                                # CPC-first test planning with decision criteria
+/agileflow:ads:track <performance-csv>                  # Performance tracking with winner detection
+/agileflow:ads:plan                                     # Campaign planning with industry templates
+/agileflow:ads:google <account-data>                    # Google Ads deep-dive (74 checks)
+/agileflow:ads:meta <account-data>                      # Meta/Facebook audit (46 checks)
+/agileflow:ads:creative <account-data>                  # Cross-platform creative review (21 checks)
+/agileflow:ads:budget <account-data>                    # Budget allocation & bidding strategy
+/agileflow:ads:landing <URL>                            # Landing page optimization
+/agileflow:ads:competitor <industry>                    # Competitive intelligence
+/agileflow:ads:linkedin <account-data>                  # LinkedIn audit (9 checks)
+/agileflow:ads:tiktok <account-data>                    # TikTok audit (8 checks)
+/agileflow:ads:microsoft <account-data>                 # Microsoft Ads audit (7 checks)
+/agileflow:ads:youtube <account-data>                   # YouTube audit
+```
+
+---
+
+## Sub-Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| **audit** | Full multi-platform audit with Ads Health Score | Starting point for any account |
+| **health** | Unified marketing scorecard (ads+SEO+landing+tracking) | Executive overview of full marketing funnel |
+| **generate** | Bulk ad copy generation (40+ variants) | Creating new ad creative at scale |
+| **test-plan** | CPC-first test planning with decision criteria | Structuring A/B tests with winner/kill rules |
+| **track** | Performance tracking with winner detection | Ongoing campaign monitoring and optimization |
+| **plan** | Campaign planning with industry templates | New campaigns or restructuring |
+| **google** | Google Ads deep-dive (74 checks) | Google-specific optimization |
+| **meta** | Meta/Facebook audit (46 checks) | Meta-specific optimization |
+| **creative** | Cross-platform creative quality | Creative strategy improvement |
+| **budget** | Budget & bidding strategy | Spend optimization |
+| **landing** | Landing page optimization | Conversion rate improvement |
+| **competitor** | Competitive intelligence | Market positioning |
+| **linkedin** | LinkedIn Ads audit | LinkedIn-specific optimization |
+| **tiktok** | TikTok Ads audit | TikTok-specific optimization |
+| **microsoft** | Microsoft Ads audit | Microsoft-specific optimization |
+| **youtube** | YouTube Ads audit | Video campaign optimization |
+
+---
+
+## Account Data Formats
+
+The ads commands accept account data in several formats:
+
+1. **Pasted text** - Copy/paste from ad platform exports (CSV, tables)
+2. **File path** - Point to exported CSV/JSON files
+3. **Structured description** - Describe your account setup in plain text
+4. **Screenshots** - Describe what you see in platform dashboards
+
+For best results, include:
+- Campaign names, types, and objectives
+- Budget and spend data
+- Conversion tracking setup
+- Targeting settings
+- Ad creative details
+- Performance metrics (CPA, ROAS, CTR, CVR)
+
+---
+
+## Routing Logic
+
+If the user provides data without a sub-command, determine intent:
+
+1. **"audit my ads"** -> `/agileflow:ads:audit`
+2. **"health check" / "marketing score" / "full scorecard"** -> `/agileflow:ads:health`
+3. **"generate ad copy" / "write ads" / "bulk ads" / "ad variants"** -> `/agileflow:ads:generate`
+4. **"test plan" / "A/B test" / "split test" / "CPC test"** -> `/agileflow:ads:test-plan`
+5. **"track performance" / "dashboard" / "winners" / "KPIs"** -> `/agileflow:ads:track`
+6. **"plan a campaign"** -> `/agileflow:ads:plan`
+7. **"check my Google Ads"** -> `/agileflow:ads:google`
+8. **"Meta" / "Facebook ads"** -> `/agileflow:ads:meta`
+9. **"creative review"** -> `/agileflow:ads:creative`
+10. **"budget" / "spend" / "bidding"** -> `/agileflow:ads:budget`
+11. **"landing page"** -> `/agileflow:ads:landing`
+12. **"competitor" / "competitive"** -> `/agileflow:ads:competitor`
+13. **"LinkedIn"** -> `/agileflow:ads:linkedin`
+14. **"TikTok"** -> `/agileflow:ads:tiktok`
+15. **"Microsoft" / "Bing"** -> `/agileflow:ads:microsoft`
+16. **"YouTube" / "video ads"** -> `/agileflow:ads:youtube`
+17. **Unclear** -> Show the quick reference and ask which analysis they want
+
+---
+
+## If No Sub-Command Specified
+
+Show the quick reference table above and ask:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which advertising analysis would you like to run?",
+  "header": "Ads Analysis",
+  "multiSelect": false,
+  "options": [
+    {"label": "Full multi-platform audit (Recommended)", "description": "Comprehensive 6-analyzer audit with Ads Health Score 0-100"},
+    {"label": "Marketing health scorecard", "description": "Unified score across ads + SEO + landing pages + tracking"},
+    {"label": "Generate ad copy (40+ variants)", "description": "Bulk ad copy from product description with ICP angles + platform CSV"},
+    {"label": "Create A/B test plan", "description": "CPC-first testing with budget allocation and winner/kill rules"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads` - Paid advertising audit & planning router
+
+**Sub-commands**: audit, health, generate, test-plan, track, plan, google, meta, creative, budget, landing, competitor, linkedin, tiktok, microsoft, youtube
+
+**Quick start**: `/agileflow:ads:audit <account-data>` for full analysis
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/assign.md

@@ -1,5 +1,6 @@
 ---
 description: Assign or reassign a story to an owner
+phase: pre-story
 argument-hint: "STORY=<US-ID> NEW_OWNER=<id> [NEW_STATUS=<status>] [NOTE=<text>]"
 compact_context:
   priority: high

package/src/core/commands/audit.md

@@ -1,5 +1,6 @@
 ---
 description: Audit story completion - tests + acceptance criteria verification (GSD pattern)
+phase: post-impl
 argument-hint: "STORY=<US-ID>"
 compact_context:
   priority: high
@@ -162,25 +163,61 @@ Parse results:
 
 ### Step 3: Verify Acceptance Criteria
 
-Display each AC from status.json and ask user to verify:
+**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 each acceptance criterion is met for {{STORY_ID}}:",
+  "question": "Verify acceptance criteria for {{STORY_ID}} ({{matched}}/{{total}} auto-matched to tests):",
   "header": "AC Check",
   "multiSelect": true,
   "options": [
-    {"label": "{{AC_1}}", "description": "Mark if complete"},
-    {"label": "{{AC_2}}", "description": "Mark if complete"},
-    {"label": "{{AC_3}}", "description": "Mark if complete"}
+    {"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 selected (verified) vs total AC
+- Count verified + auto-verified vs total AC
 - 100% = All verified
 - <100% = Partial