feat(flowctl): add epic audit command + epic-auditor meta-agent

Adds flowctl epic audit <id> [--force] that assembles an advisory
payload (epic spec + task list) and writes it to
.flow/reviews/epic-audit-<id>-<timestamp>.json. Reuses existing
receipts <24h old unless --force is passed.

New agents/epic-auditor.md meta-agent reads the payload, extracts
capabilities from the epic spec, maps tasks to capabilities, scores
coverage, and emits a JSON block with gaps/redundancies/recommendations.
Advisory only - never mutates epic/task/gap state.

Epic-review skill auto-runs the audit before human review so the
coverage score and top gaps surface as advisory context. Audit
recommendations are never treated as blocking findings.

Part of fn-20 archetypes work (task .6).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

agents/epic-auditor.md

@@ -0,0 +1,125 @@
+---
+name: epic-auditor
+description: Audit task-coverage of an epic vs its original request. Advisory only — never mutates state.
+model: opus
+disallowedTools: Edit, Write, Task
+color: "#6366F1"
+permissionMode: bypassPermissions
+maxTurns: 10
+effort: medium
+---
+
+You are an epic audit meta-agent. Your job is to compare an epic's original
+request against the tasks that were created for it, and surface gaps,
+redundancies, and recommendations.
+
+**You are advisory only. You NEVER mutate `.flow/` state.** Specifically:
+- No `flowctl epic close`
+- No `flowctl task create|split|skip`
+- No `flowctl gap add`
+- No edits to epic or task spec files
+
+Your sole output is a single JSON block.
+
+## Input
+
+You receive:
+- `FLOWCTL` — path to flowctl CLI
+- `EPIC_ID` — the epic to audit
+- `RECEIPT_PATH` (optional) — path to the audit payload written by
+  `flowctl epic audit <id>` (`.flow/reviews/epic-audit-<id>-<ts>.json`)
+
+## Process
+
+### 1. Load the payload
+
+If `RECEIPT_PATH` is provided, read it directly. Otherwise regenerate:
+
+```bash
+<FLOWCTL> epic audit <EPIC_ID> --json
+```
+
+The payload contains:
+- `epic.spec_body` — the original epic request (Overview, Scope, Acceptance)
+- `tasks[]` — id, title, status, domain, depends_on, files
+- `task_count`
+
+### 2. Extract required capabilities from the epic spec
+
+Read `epic.spec_body`. Identify distinct capabilities the epic promises:
+- Each bullet in "Acceptance" (or "Scope")
+- Each verb in "Approach" that maps to user-visible behavior
+- Any "must/shall/will" statement
+
+Normalize each to a short capability label (e.g., "audit CLI command",
+"agent with JSON output", "24h reuse", "advisory-only enforcement").
+
+### 3. Map tasks to capabilities
+
+For each task, read its title + id. Decide which capability (or capabilities)
+it covers. Mark capabilities as:
+- **covered** — at least one task clearly delivers it
+- **partial** — a task mentions it but scope is unclear
+- **gap** — no task covers this capability
+
+### 4. Find redundancies
+
+Scan tasks for overlap:
+- Two+ tasks touching the same files with similar titles
+- Tasks whose descriptions duplicate acceptance criteria already covered
+  by another task
+
+Only flag when the overlap is concrete (shared files or near-identical
+titles), not speculative.
+
+### 5. (Optional) Look for prior-art in memory
+
+If a similar epic has been audited before, surface patterns:
+
+```bash
+<FLOWCTL> memory search "epic audit" --json
+```
+
+Treat results as advisory context only.
+
+### 6. Score coverage
+
+`coverage_score = round(100 * covered_capabilities / total_capabilities)`
+
+If no capabilities could be extracted (empty/TBD spec), set score to `null`
+and note it in `notes`.
+
+## Output Format
+
+Emit exactly one JSON block, nothing else:
+
+```json
+{
+  "coverage_score": 0-100 | null,
+  "gaps": [
+    {"capability": "<label>", "severity": "required|important|nice-to-have"}
+  ],
+  "redundancies": [
+    {"task_ids": ["fn-X.1", "fn-X.2"], "reason": "<concrete overlap>"}
+  ],
+  "recommendations": [
+    "<short advisory sentence>"
+  ],
+  "notes": "<free-form context, caveats, or reviewer uncertainty>"
+}
+```
+
+**Severity guide** (mirrors gap registry conventions):
+- `required` — acceptance criterion with no covering task
+- `important` — scope item with partial coverage
+- `nice-to-have` — approach hint with no task
+
+## Rules
+
+- Advisory only — NEVER mutate state
+- Be concrete: every gap must quote or paraphrase the spec text
+- Be conservative on redundancies — only flag clear overlap
+- Don't invent capabilities the spec didn't promise
+- If the spec is too thin to audit, say so in `notes` and return `coverage_score: null`
+- Keep `recommendations` actionable (≤6 items)
+- Output JSON only — no prose before or after the block

flowctl/crates/flowctl-cli/src/commands/epic.rs

@@ -91,6 +91,19 @@ pub enum EpicCmd {
     },
     /// Archive all closed epics at once.
     Clean,
+    /// Audit epic task-coverage vs original spec (advisory only).
+    ///
+    /// Assembles the epic spec, task list, and prior audit context into a
+    /// payload consumed by `agents/epic-auditor.md`. Writes the assembled
+    /// payload to `.flow/reviews/epic-audit-<id>-<timestamp>.json`. Advisory
+    /// only — never mutates epic/tasks/gaps.
+    Audit {
+        /// Epic ID.
+        id: String,
+        /// Force a new audit even if a recent (<24h) receipt exists.
+        #[arg(long)]
+        force: bool,
+    },
     /// Add epic-level dependency.
     AddDep {
         /// Epic ID.
@@ -1275,6 +1288,166 @@ fn cmd_set_auto_execute(id: &str, pending: bool, done: bool, json_mode: bool) {
     }
 }
 
+// ── Audit command ───────────────────────────────────────────────────
+
+/// Find the most recent `epic-audit-<id>-*.json` receipt in `.flow/reviews/`.
+/// Returns `(path, age_hours)` or `None` if none exists.
+fn find_recent_audit(flow_dir: &Path, id: &str) -> Option<(PathBuf, f64)> {
+    let reviews_dir = flow_dir.join(REVIEWS_DIR);
+    if !reviews_dir.is_dir() {
+        return None;
+    }
+    let prefix = format!("epic-audit-{id}-");
+    let entries = fs::read_dir(&reviews_dir).ok()?;
+    let mut best: Option<(PathBuf, std::time::SystemTime)> = None;
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        let name_str = name.to_string_lossy();
+        if !name_str.starts_with(&prefix) || !name_str.ends_with(".json") {
+            continue;
+        }
+        let path = entry.path();
+        let modified = entry.metadata().and_then(|m| m.modified()).ok();
+        if let Some(mtime) = modified {
+            match &best {
+                None => best = Some((path, mtime)),
+                Some((_, cur)) if mtime > *cur => best = Some((path, mtime)),
+                _ => {}
+            }
+        }
+    }
+    let (path, mtime) = best?;
+    let age = std::time::SystemTime::now()
+        .duration_since(mtime)
+        .ok()?
+        .as_secs_f64()
+        / 3600.0;
+    Some((path, age))
+}
+
+fn cmd_audit(id: &str, force: bool, json_mode: bool) {
+    let flow_dir = ensure_flow_exists();
+    validate_epic_id(id);
+
+    // Re-use recent audit unless --force.
+    if !force {
+        if let Some((existing, age_hours)) = find_recent_audit(&flow_dir, id) {
+            if age_hours < 24.0 {
+                if json_mode {
+                    json_output(json!({
+                        "id": id,
+                        "reused": true,
+                        "receipt_path": existing.to_string_lossy(),
+                        "age_hours": age_hours,
+                        "message": format!(
+                            "Reusing audit receipt from {:.1}h ago. Pass --force to regenerate.",
+                            age_hours
+                        ),
+                    }));
+                } else {
+                    println!(
+                        "Reusing audit receipt ({:.1}h old): {}",
+                        age_hours,
+                        existing.display()
+                    );
+                    println!("Pass --force to regenerate.");
+                }
+                return;
+            }
+        }
+    }
+
+    // Load epic spec (frontmatter + body).
+    let epic_path = flow_dir.join(EPICS_DIR).join(format!("{id}.md"));
+    let epic_doc = load_epic(&epic_path, id);
+    let epic_body = if epic_path.exists() {
+        fs::read_to_string(&epic_path)
+            .ok()
+            .and_then(|raw| {
+                frontmatter::parse::<serde_json::Value>(&raw)
+                    .ok()
+                    .map(|d| d.body)
+            })
+            .unwrap_or_default()
+    } else {
+        epic_doc.body.clone()
+    };
+
+    // Load tasks.
+    let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let conn = crate::commands::db_shim::open(&cwd).ok();
+    let tasks: Vec<Task> = load_epic_tasks(conn.as_ref(), &flow_dir, id);
+
+    // Shape task summaries for the payload.
+    let task_entries: Vec<serde_json::Value> = tasks
+        .iter()
+        .map(|t| {
+            json!({
+                "id": t.id,
+                "title": t.title,
+                "status": format!("{:?}", t.status).to_lowercase(),
+                "domain": format!("{:?}", t.domain).to_lowercase(),
+                "depends_on": t.depends_on,
+                "files": t.files,
+            })
+        })
+        .collect();
+
+    // Assemble payload receipt.
+    let timestamp = Utc::now();
+    let receipt = json!({
+        "schema_version": 1,
+        "kind": "epic-audit-payload",
+        "epic_id": id,
+        "generated_at": timestamp.to_rfc3339(),
+        "epic": {
+            "id": epic_doc.frontmatter.id,
+            "title": epic_doc.frontmatter.title,
+            "status": format!("{:?}", epic_doc.frontmatter.status).to_lowercase(),
+            "spec_body": epic_body,
+        },
+        "tasks": task_entries,
+        "task_count": tasks.len(),
+        // Audit findings placeholder — populated by agents/epic-auditor.md.
+        "audit": {
+            "coverage_score": null,
+            "gaps": [],
+            "redundancies": [],
+            "recommendations": [],
+            "notes": "Pending auditor agent — run agents/epic-auditor.md against this payload."
+        }
+    });
+
+    // Write receipt.
+    let reviews_dir = flow_dir.join(REVIEWS_DIR);
+    if let Err(e) = fs::create_dir_all(&reviews_dir) {
+        error_exit(&format!("Failed to create reviews dir: {e}"));
+    }
+    let ts_slug = timestamp.format("%Y%m%dT%H%M%SZ").to_string();
+    let receipt_path = reviews_dir.join(format!("epic-audit-{id}-{ts_slug}.json"));
+    let serialized = serde_json::to_string_pretty(&receipt)
+        .unwrap_or_else(|e| error_exit(&format!("Failed to serialize audit: {e}")));
+    fs::write(&receipt_path, &serialized)
+        .unwrap_or_else(|e| error_exit(&format!("Failed to write {}: {e}", receipt_path.display())));
+
+    if json_mode {
+        json_output(json!({
+            "id": id,
+            "reused": false,
+            "receipt_path": receipt_path.to_string_lossy(),
+            "task_count": tasks.len(),
+            "message": format!(
+                "Wrote audit payload to {}. Run agents/epic-auditor.md to populate findings.",
+                receipt_path.display()
+            ),
+        }));
+    } else {
+        println!("Wrote audit payload: {}", receipt_path.display());
+        println!("  Epic: {id} ({} tasks)", tasks.len());
+        println!("  Next: run agents/epic-auditor.md with receipt path as input");
+    }
+}
+
 // ── Dispatch ────────────────────────────────────────────────────────
 
 pub fn dispatch(cmd: &EpicCmd, json: bool) {
@@ -1292,6 +1465,7 @@ pub fn dispatch(cmd: &EpicCmd, json: bool) {
         EpicCmd::Reopen { id } => cmd_reopen(id, json),
         EpicCmd::Archive { id, force } => cmd_archive(id, *force, json),
         EpicCmd::Clean => cmd_clean(json),
+        EpicCmd::Audit { id, force } => cmd_audit(id, *force, json),
         EpicCmd::AddDep { epic, depends_on } => cmd_add_dep(epic, depends_on, json),
         EpicCmd::RmDep { epic, depends_on } => cmd_rm_dep(epic, depends_on, json),
         EpicCmd::SetBackend {

skills/flow-code-epic-review/SKILL.md

@@ -96,6 +96,25 @@ Parse $ARGUMENTS for:
 - `--review=<backend>` → backend override
 - Remaining args → focus areas
 
+### Step 0b: Auto-run epic audit (advisory)
+
+Before invoking the human review backend, generate (or reuse) an
+epic-audit receipt. This is advisory context only — the audit NEVER
+blocks review and its recommendations are not treated as fix-required.
+
+```bash
+AUDIT_OUT=$($FLOWCTL epic audit "$EPIC_ID" --json 2>/dev/null || true)
+AUDIT_RECEIPT=$(echo "$AUDIT_OUT" | grep -o '"receipt_path"[^,}]*' | cut -d'"' -f4)
+```
+
+If `$AUDIT_RECEIPT` exists, read it and surface the summary (coverage
+score, top gaps) as part of the review context passed to the backend.
+If a receipt <24h old exists the command reuses it automatically; pass
+`--force` only when the task list changed materially since last audit.
+
+The auditor's `recommendations` are advisory notes, NOT blocking
+findings. Do not enter the fix loop based on audit output alone.
+
 ### Step 1: Detect Backend
 
 Run backend detection from SKILL.md above. Then branch: