specflow-cc 1.6.2 → 1.6.3

package/README.md

@@ -305,7 +305,7 @@ Six months later, you can read the spec and understand not just *what* was built
 |---------|-------------|
 | `/sf:init` | Initialize project |
 | `/sf:new "task"` | Create specification |
-| `/sf:audit` | Audit spec (fresh context) |
+| `/sf:audit` | Audit spec or import external feedback |
 | `/sf:revise` | Revise based on audit feedback |
 | `/sf:run` | Implement specification |
 | `/sf:review` | Review implementation (fresh context) |
@@ -319,6 +319,13 @@ Six months later, you can read the spec and understand not just *what* was built
 /sf:quick "fix button color"    # Skip full workflow for trivial tasks
 ```
 
+**Audit options:**
+
+```bash
+/sf:audit                           # Audit active spec (fresh context)
+/sf:audit --import "[Critical] ..." # Import external feedback for review
+```
+
 **Revise options:**
 
 ```bash
@@ -328,6 +335,13 @@ Six months later, you can read the spec and understand not just *what* was built
 /sf:revise "custom..."  # Custom instructions
 ```
 
+**External feedback workflow:**
+
+```bash
+/sf:audit --import "[Critical] SQL injection; [Major] Add rate limiting"
+/sf:revise              # Critically evaluate each item (Apply/Skip/Defer)
+```
+
 ### Research & Clarification
 
 | Command | Description |

package/agents/impl-reviewer.md

@@ -148,6 +148,23 @@ For each created/modified file:
 - [ ] Logic flow is easy to follow
 - [ ] Future maintainers can understand without extensive context
 
+### 4.8 Implementation Reality Check (light)
+
+During code review, watch for signals that the specification itself may have been misdirected:
+
+**Trigger conditions:**
+- Implementation is significantly simpler/more complex than spec anticipated
+- Code solves a different problem than what spec described
+- Obvious better approach emerged during implementation but wasn't taken
+- Implementation contradicts PROJECT.md goals or patterns
+
+**If triggered:**
+- Do NOT block the review for this
+- Add **WARNING** (not Critical): "Implementation concern: {description}. Consider `/sf:discuss` before `/sf:done`"
+- Continue with normal review process
+
+**Note:** This is a safety net, not a primary check. Strategic issues should be caught earlier by `spec-auditor`.
+
 ## Step 5: Categorize Findings
 
 Organize into:
@@ -299,6 +316,7 @@ Options:
 - [ ] Architecture alignment verified
 - [ ] No unnecessary duplication
 - [ ] Cognitive load acceptable
+- [ ] Implementation reality check performed (strategic red flags)
 - [ ] Findings categorized
 - [ ] Review recorded in spec
 - [ ] STATE.md updated

package/agents/spec-auditor.md

@@ -48,6 +48,7 @@ You are intentionally given NO context about how the spec was created. This ensu
 6. **Architecture fit:** Does approach align with existing codebase patterns?
 7. **Non-duplication:** Does this avoid reinventing existing solutions?
 8. **Cognitive load:** Will this be easy for developers to understand and maintain?
+9. **Strategic fit:** Does this solve the RIGHT problem for the project's goals?
 
 ## Context Quality Curve
 
@@ -300,6 +301,64 @@ Set NEEDS_DECOMPOSITION if ANY of:
 - Missing Goal Analysis on medium/large spec → Warning
 - Partial Goal Analysis → Warning per missing subsection
 
+## Step 3.8: Strategic Sanity Check
+
+Evaluate whether the specification addresses the RIGHT problem, not just whether it's well-formed.
+
+### 3.8.1 Extract Assumptions
+
+Identify all implicit and explicit assumptions in the specification:
+
+1. **Problem assumptions:** What does the spec assume about the problem being solved?
+2. **Solution assumptions:** What does the spec assume about the chosen approach?
+3. **Context assumptions:** What does the spec assume about the environment/constraints?
+
+Document each assumption:
+```
+| # | Assumption | If wrong, impact |
+|---|------------|------------------|
+| A1 | {assumption} | {what breaks} |
+| A2 | {assumption} | {what breaks} |
+```
+
+### 3.8.2 Project Alignment Check
+
+Compare against PROJECT.md:
+
+- [ ] Task aligns with stated project goals
+- [ ] Approach fits project's architectural direction
+- [ ] Effort is proportional to expected value
+- [ ] No contradiction with existing constraints or decisions
+
+### 3.8.3 Alternative Solutions Check
+
+Consider whether obvious alternatives were evaluated:
+
+- [ ] Is there a simpler solution that achieves 80% of the value?
+- [ ] Is there an existing solution (in codebase or ecosystem) being ignored?
+- [ ] Are we solving the root cause or just a symptom?
+
+### 3.8.4 Red Flags Detection
+
+Watch for patterns that indicate strategic errors:
+
+| Red Flag | Detection | Action |
+|----------|-----------|--------|
+| Scope mismatch | Large effort for minor improvement | Warning |
+| Symptom treatment | Fixing output without addressing cause | Critical |
+| Reinventing wheel | Custom solution when standard exists | Warning |
+| Direction conflict | Contradicts recent project decisions | Critical |
+| Assumption fragility | Success depends on unverified assumptions | Warning |
+
+### 3.8.5 Strategic Verdict
+
+**If concerns found:**
+- Minor concerns → Add to **Recommendations** with prefix `[Strategic]`
+- Major concerns → Add **Critical** issue: "Strategic concern: {description}. Recommend `/sf:discuss` before proceeding."
+
+**If no concerns:**
+- Add to audit output: "Strategic fit: ✓ Aligned with project goals"
+
 ## Step 4: Generate Implementation Tasks (for large specs)
 
 If scope is large, generate the Implementation Tasks section:
@@ -566,7 +625,9 @@ Choose one:
 <success_criteria>
 - [ ] Specification fully read
 - [ ] PROJECT.md context loaded
-- [ ] All 8 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load)
+- [ ] All 9 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load, strategic fit)
+- [ ] Assumptions extracted and impact assessed
+- [ ] Project alignment verified
 - [ ] Issues categorized (critical vs recommendations)
 - [ ] Audit recorded in spec's Audit History
 - [ ] STATE.md updated

package/commands/sf/audit.md

@@ -1,6 +1,7 @@
 ---
 name: sf:audit
 description: Audit the active specification in a fresh context
+argument-hint: "[SPEC-XXX] [--import \"feedback\"]"
 allowed-tools:
   - Read
   - Write
@@ -8,10 +9,13 @@ allowed-tools:
   - Glob
   - Grep
   - Task
+  - AskUserQuestion
 ---
 
 <purpose>
 Audit the active specification using a fresh context subagent. The auditor evaluates clarity, completeness, testability, scope, and feasibility without bias from the creation process.
+
+Also supports importing external feedback (from code reviews, security audits, team discussions) for critical evaluation and selective application.
 </purpose>
 
 <context>
@@ -52,7 +56,7 @@ Exit.
 
 Read the active spec file: `.specflow/specs/SPEC-XXX.md`
 
-**If status is not 'draft' or 'revision_requested':**
+**If status is not 'draft', 'auditing', or 'revision_requested':**
 ```
 Specification SPEC-XXX is already audited (status: {status}).
 
@@ -60,6 +64,133 @@ Use `/sf:run` to implement or `/sf:status` to see current state.
 ```
 Exit.
 
+## Step 3.5: Check for --import Flag
+
+Parse arguments for `--import "feedback text"` pattern.
+
+**If --import flag present:** Go to Step 4-IMPORT
+**Otherwise:** Continue to Step 4 (internal audit)
+
+---
+
+## Step 4-IMPORT: Import External Feedback
+
+### 4.1 Parse External Feedback
+
+Extract the feedback text from the `--import` argument.
+
+**Expected formats in feedback:**
+- `[Critical]` or `[CRITICAL]` — blocking issues
+- `[Major]` or `[Recommend]` — should fix
+- `[Minor]` or `[Optional]` — nice to have
+- Numbered lists (1. 2. 3.)
+- Bullet points (- or *)
+
+If no severity markers found, treat all items as `[Major]`.
+
+### 4.2 Structure the Feedback
+
+Parse items into structured format:
+
+```
+Critical Issues:
+1. {item}
+2. {item}
+
+Major Issues:
+3. {item}
+4. {item}
+
+Minor Issues:
+5. {item}
+```
+
+### 4.3 Get Next Audit Version
+
+```bash
+AUDIT_COUNT=$(grep -c "### Audit v" .specflow/specs/SPEC-XXX.md 2>/dev/null || echo 0)
+EXTERNAL_COUNT=$(grep -c "### External Audit" .specflow/specs/SPEC-XXX.md 2>/dev/null || echo 0)
+NEXT_VERSION=$((AUDIT_COUNT + EXTERNAL_COUNT + 1))
+```
+
+### 4.4 Append to Audit History
+
+Append to the spec's `## Audit History` section:
+
+```markdown
+### External Audit v{N} ({date} {time})
+**Source:** External review
+**Status:** PENDING_REVIEW
+
+**Critical Issues:**
+1. {parsed critical item}
+2. {parsed critical item}
+
+**Major Issues:**
+3. {parsed major item}
+
+**Minor Issues:**
+4. {parsed minor item}
+
+---
+*Imported feedback requires review before application.*
+*Use `/sf:revise` to critically evaluate and selectively apply.*
+```
+
+### 4.5 Update Spec Status
+
+In spec frontmatter, set: `status: revision_requested`
+
+### 4.6 Update STATE.md
+
+Update STATE.md:
+- Status → "external_review"
+- Next Step → "/sf:revise"
+- Add decision: "Imported external feedback for SPEC-XXX"
+
+### 4.7 Display Import Result
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EXTERNAL FEEDBACK IMPORTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Specification:** SPEC-XXX
+**Source:** External review
+
+### Imported Items
+
+**Critical:** {count} items
+**Major:** {count} items
+**Minor:** {count} items
+
+### Preview
+
+{Show first 2-3 items as preview}
+
+---
+
+📄 File: .specflow/specs/SPEC-XXX.md
+
+---
+
+## Next Step
+
+`/sf:revise` — critically review and selectively apply
+
+Options:
+• `/sf:revise` — interactive review (recommended)
+• `/sf:revise all` — apply all items
+• `/sf:revise 1,2,5` — apply specific items
+• `/sf:discuss SPEC-XXX` — discuss items before deciding
+
+<sub>External feedback should be critically evaluated, not blindly applied.</sub>
+```
+
+Exit.
+
+---
+
 ## Step 4: Determine Model Profile
 
 Check `.specflow/config.json` for model profile setting:

package/commands/sf/help.md

@@ -128,6 +128,8 @@ Read the command file and extract:
 ```
 /sf:audit                  # Audit active specification
 /sf:audit SPEC-003         # Audit specific specification
+/sf:audit --import "[Critical] No error handling; [Major] Add logging"
+/sf:audit --import "Security review: 1. SQL injection in search 2. XSS in comments"
 ```
 ```
 
@@ -209,7 +211,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 |--------------|-----------------------------------------|
 | /sf:init     | Initialize project, analyze codebase    |
 | /sf:new      | Create specification from task          |
-| /sf:audit    | Audit specification (fresh context)     |
+| /sf:audit    | Audit spec or import external feedback  |
 | /sf:revise   | Revise spec based on audit feedback     |
 | /sf:run      | Execute specification                   |
 | /sf:review   | Review implementation (fresh context)   |

package/commands/sf/revise.md

@@ -63,16 +63,29 @@ Exit.
 
 ## Step 4: Extract Latest Audit
 
-Find the most recent "Audit v[N]" section in Audit History.
+Find the most recent audit section in Audit History. Can be:
+- `### Audit v[N]` — internal audit
+- `### External Audit v[N]` — imported external feedback
 
 **If no audit exists:**
 ```
 Specification SPEC-XXX has no audit history.
 
-Run `/sf:audit` first to get feedback.
+Run `/sf:audit` first to get feedback,
+or `/sf:audit --import "feedback"` to import external review.
 ```
 Exit.
 
+**Determine audit type:**
+```bash
+LATEST_AUDIT=$(grep -E "^### (External )?Audit v[0-9]+" .specflow/specs/SPEC-XXX.md | tail -1)
+if echo "$LATEST_AUDIT" | grep -q "External"; then
+    AUDIT_TYPE="external"
+else
+    AUDIT_TYPE="internal"
+fi
+```
+
 ## Step 5: Parse Arguments
 
 | Argument | Action |
@@ -84,7 +97,9 @@ Exit.
 
 ### If Interactive Mode (no arguments):
 
-Display audit comments:
+Display audit comments with context about source:
+
+**For internal audit:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -111,6 +126,57 @@ Use AskUserQuestion with options:
 - "Fix critical only (1, 2)" → treat as "1,2"
 - "Custom selection" → ask for numbers or description
 
+**For external audit (requires critical evaluation):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REVIEW EXTERNAL FEEDBACK: SPEC-XXX
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  External feedback requires critical evaluation.
+    Not all suggestions may be applicable or correct.
+
+External Audit (v{N}) items:
+
+**Critical:**
+1. [Issue 1]
+2. [Issue 2]
+
+**Major:**
+3. [Issue 3]
+4. [Issue 4]
+
+**Minor:**
+5. [Issue 5]
+
+---
+
+How to proceed?
+```
+
+Use AskUserQuestion with options:
+- "Review each item" → interactive per-item evaluation (recommended)
+- "Apply all" → apply everything (use with caution)
+- "Apply critical only" → treat as critical items
+- "Select specific" → ask for numbers
+
+**If "Review each item" selected:**
+
+For each item, use AskUserQuestion:
+```
+Item {N}: {issue description}
+
+Evaluate this feedback:
+```
+
+Options:
+- "Apply" — implement this change
+- "Skip" — not applicable, with reason
+- "Discuss" — need clarification
+- "Defer" — valid but out of scope
+
+Record each decision in Response section.
+
 ## Step 6: Determine Model Profile
 
 Check `.specflow/config.json` for model profile setting:
@@ -163,6 +229,8 @@ The agent will:
 
 ## Step 9: Display Result
 
+**For internal audit:**
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  REVISION COMPLETE
@@ -194,6 +262,50 @@ The agent will:
 <sub>/clear recommended → auditor needs fresh context</sub>
 ```
 
+**For external audit:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EXTERNAL FEEDBACK REVIEWED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Specification:** SPEC-XXX
+**External Audit:** v{N} → Response v{N}
+
+### Decisions Summary
+
+| # | Item | Decision | Reason |
+|---|------|----------|--------|
+| 1 | {short description} | ✓ Applied | — |
+| 2 | {short description} | ✗ Skipped | {reason} |
+| 3 | {short description} | ⏸ Deferred | Out of scope |
+| 4 | {short description} | ? Discuss | Needs clarification |
+
+**Applied:** {count} | **Skipped:** {count} | **Deferred:** {count}
+
+{If any items marked "Discuss":}
+### Needs Discussion
+
+Items {N, M} require clarification before deciding.
+
+---
+
+📄 File: .specflow/specs/SPEC-XXX.md
+
+---
+
+## Next Steps
+
+{If items need discussion:}
+`/sf:discuss SPEC-XXX` — clarify items {N, M}
+
+{If all decided:}
+`/sf:audit` — re-audit with applied changes
+
+{If deferred items exist:}
+<sub>Deferred items saved to `.specflow/todos/` for future consideration.</sub>
+```
+
 </workflow>
 
 <fallback>
@@ -223,7 +335,7 @@ RESPONSE_COUNT=$(grep -c "### Response v" .specflow/specs/SPEC-XXX.md 2>/dev/nul
 NEXT_VERSION=$((RESPONSE_COUNT + 1))
 ```
 
-Append to Audit History:
+**For internal audit, append:**
 
 ```markdown
 ### Response v{N} ({date} {time})
@@ -234,6 +346,23 @@ Append to Audit History:
 2. [✓/✗] {Item} — {what was done}
 ```
 
+**For external audit, append:**
+
+```markdown
+### Response v{N} ({date} {time})
+**Source:** External Audit v{M}
+**Review Type:** {interactive | bulk}
+
+**Decisions:**
+| # | Item | Decision | Reason |
+|---|------|----------|--------|
+| 1 | {description} | Applied | — |
+| 2 | {description} | Skipped | {reason} |
+| 3 | {description} | Deferred | {reason} |
+
+**Summary:** Applied {X}/{Y} items, Skipped {Z}, Deferred {W}
+```
+
 ### Update Status
 
 In spec frontmatter: `status: auditing`

package/commands/sf/status.md

@@ -70,6 +70,7 @@ Based on current status:
 | idle | `/sf:new "task"` — create specification |
 | drafting | `/sf:audit` — audit specification |
 | revision_requested | `/sf:revise` — fix issues |
+| external_review | `/sf:revise` — review external feedback |
 | audited | `/sf:run` — implement |
 | running | Continue implementation or `/sf:review` |
 | reviewing | `/sf:fix` or `/sf:done` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"

package/templates/spec.md

@@ -1,7 +1,7 @@
 ---
 id: SPEC-XXX
 type: feature | refactor | bugfix
-status: draft | audited | running | review | done
+status: draft | auditing | revision_requested | audited | running | review | done
 priority: high | medium | low
 complexity: small | medium | large
 created: YYYY-MM-DD

package/templates/state.md

@@ -5,8 +5,8 @@
 ## Current Position
 
 - **Active Specification:** [none | SPEC-XXX]
-- **Status:** [idle | drafting | auditing | running | reviewing]
-- **Next Step:** [/sf:new | /sf:audit | /sf:run | /sf:review | /sf:done]
+- **Status:** [idle | drafting | auditing | revision_requested | external_review | running | reviewing]
+- **Next Step:** [/sf:new | /sf:audit | /sf:revise | /sf:run | /sf:review | /sf:done]
 
 ## Queue