@curdx/flow 2.0.21 → 2.1.0

package/skills/verify/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: verify
+description: Goal-backward verification — trace from every FR / AC / AD in the active spec to the code and tests, detect stubs and fake completions. The differentiator command. Optionally adds multi-source coverage audit with --strict.
+argument-hint: "[--strict]"
+context: fork
+agent: flow-verifier
+---
+
+# Goal-Backward Verification
+
+Verify the active `.flow/` spec using goal-backward analysis. This is the
+differentiator step — catches Claude's most common failure: claiming "done"
+while the code is a stub, a fake completion, or an untested AC.
+
+**Arguments**: `$ARGUMENTS` (optionally `--strict` for multi-source coverage audit).
+
+## Preflight
+
+- `.flow/` must exist and `.flow/.active-spec` must be non-empty.
+- `.flow/specs/<active>/requirements.md`, `design.md`, `tasks.md` must all exist.
+
+If any precondition fails, emit a clear error and stop.
+
+## What to verify
+
+Read the active spec's `requirements.md` (for FR-NN and AC-N.N),
+`design.md` (for AD-NN), `tasks.md` (for T-N.M with per-task Verify
+commands), and `.flow/STATE.md` (for D-NN decisions).
+
+For EACH assertion in the spec, walk goal-backward:
+
+1. Classify the assertion as **UI-facing** (uses words like "user sees",
+   "click", "render", or names a UI element) vs. **code-only** (schema,
+   API response, performance, error envelope, etc.).
+2. For **code-only**: grep the codebase for matching symbols, find the
+   implementing file + line, find a test that exercises it, run the test
+   (`npm test` or the declared `Verify` command), capture pass/fail.
+3. For **UI-facing**: browser verification via `mcp__chrome-devtools__*`
+   is required. `jsdom` / `happy-dom` unit tests are insufficient. If the
+   browser MCP isn't available, mark the AC **unverified — browser MCP
+   missing** and include a CRITICAL section in the report; do NOT
+   silently pass based on code reading alone.
+
+Also scan for **stub / fake-completion** patterns on FR-covered paths:
+
+- `throw new Error("not implemented")`, `// TODO:` on critical paths
+- `return null` / `return {}` where real output is expected
+- tests with only `it.skip(...)` or no assertions
+- code returning mocked fixtures instead of calling real collaborators
+
+Run the per-task `Verify` commands from `tasks.md` and record pass/fail.
+
+## --strict mode
+
+When `$ARGUMENTS` contains `--strict`, also apply the multi-source coverage
+audit at `@${CLAUDE_PLUGIN_ROOT}/gates/coverage-audit-gate.md`. Cross-check:
+
+- Every FR ↔ AC ↔ AD ↔ task ↔ test ↔ commit must reference each other.
+- Research conclusions: was the recommended library / approach actually used?
+- Every D-NN in `.flow/STATE.md` that references this spec is honored.
+
+## Deliverables
+
+Write `.flow/specs/<name>/verification-report.md` with:
+
+- Summary counts (FR / AC / AD coverage, stub count, failing Verify count)
+- Detailed Checklist (one section per FR / AC / AD with Evidence + Verdict)
+- Stub / fake findings with file paths
+- Verdict: `PASS` / `PARTIAL` / `MISSING`
+
+Exact format schema is in `agents/flow-verifier.md` Step 6 (loaded via the
+`agent: flow-verifier` frontmatter field — its system prompt governs).
+
+**Landing check**: your FIRST substantive action after gathering findings
+must be the `Write` tool call with the complete report. Do NOT preview the
+report as assistant text first; that doubles output tokens and risks
+truncating inside the Write call. After Write succeeds, respond with a
+≤ 5-line summary only.
+
+## Apply the gate
+
+Per `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md`:
+
+- Any `STUB` or `MISSING` finding on a non-deferred FR blocks completion.
+- Any failing Verify command blocks completion.
+- Waive only with an explicit D-NN decision logged in `.flow/STATE.md`.
+
+## Output to user (≤ 5 lines after Write succeeds)
+
+```
+✓ Verification complete: <spec-name>
+  FR coverage: N/M implemented (S stub, K missing)
+  AC coverage: N/M tested
+  Verdict: PASS | PARTIAL | MISSING
+  Report: .flow/specs/<name>/verification-report.md
+```
+
+Next: address findings, then re-run `/curdx-flow:verify`, or run `/curdx-flow:review`.

package/commands/debug.md

@@ -1,199 +0,0 @@
----
-name: debug
-description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger.
-argument-hint: "\"<bug description>\""
-allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
----
-
-# Flow Debug — Systematic Debugging
-
-@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
-
-Dispatches the `flow-debugger` agent to perform systematic 4-phase debugging.
-
-## When to use
-
-- Clearly defined bug (with error message / reproduction steps)
-- Tests suddenly failing
-- Weird production behavior
-- Tasks repeatedly failed by flow-executor
-
-## When not to use
-
-- Still in coding phase → use the normal flow-executor flow
-- Question needs investigation → use `/curdx-flow:fast` with a prompt like "spike: verify X with minimal tests"
-- Performance issue needing benchmarks → performance tuning is not debug
-
-## Step 1: Parse bug description
-
-```bash
-BUG_DESC="$ARGUMENTS"
-[ -z "$BUG_DESC" ] && { echo "Usage: /curdx-flow:debug \"<bug description>\""; exit 1; }
-```
-
-## Step 2: Collect prerequisites (main agent, no dispatch)
-
-Before dispatching the debugger, the main agent (you) collects first:
-
-```bash
-# 1. Recent commit history (bug may be introduced by a new commit)
-git log --oneline -20
-
-# 2. Current modifications (uncommitted)
-git status
-git diff --stat
-
-# 3. If there is an active spec, read it
-ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
-```
-
-## Step 3: Dispatch flow-debugger
-
-```
-Task:
-  subagent_type: general-purpose
-  description: "Debug: $BUG_DESC"
-  prompt: |
-    You are the flow-debugger agent. Full definition:
-    ${CLAUDE_PLUGIN_ROOT}/agents/flow-debugger.md
-    
-    Methodology knowledge base:
-    ${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
-    
-    Bug description:
-    $BUG_DESC
-    
-    Workspace:
-    $(pwd)
-    
-    Prerequisites:
-    - Recent commits: $(git log --oneline -10)
-    - Current diff: $(git status --short)
-    - Active spec: $ACTIVE
-    - Spec directory (if any): .flow/specs/$ACTIVE/
-    
-    Mandatory 4 phases:
-    
-    Phase 1: Root-cause investigation
-      - Read the error carefully (stack trace + message + location)
-      - Build a minimal reproduction
-      - Check recent changes
-      - Trace the data flow
-      - **By the end of Phase 1 you must state the root cause in one sentence; "maybe it's..." is not allowed**
-    
-    Phase 2: Pattern analysis
-      - Find working examples
-      - Pinpoint the difference
-      - Decide isolated case vs systemic
-    
-    Phase 3: Hypothesis & testing
-      - Single hypothesis
-      - Minimal test (verify in memory, don't commit)
-      - If confirmed, enter Phase 4; if disproved → return to Phase 1
-    
-    Phase 4: Implement the fix
-      - Write a failing test
-      - Test actually fails (commit: test(scope): red - ...)
-      - Fix the root cause (not the symptom)
-      - Test passes (commit: fix(scope): green - ...)
-      - Full regression test passes
-      - Sweep for other isolated cases identified in Phase 2 and fix together
-    
-    **3-failure guard**:
-    If Phase 4 has tried 3 different approaches and all failed, **stop**.
-    Do not try a 4th. Report back to me:
-      - The 3 approaches tried
-      - Why each failed
-      - Possible root issue (architecture / dependency / data)
-      - Recommend user intervention
-    
-    Forbidden:
-    - Prayer-driven programming (retry 10 times)
-    - "Maybe it's..." as a root cause
-    - A fix without a failing test
-    - Bypassing the root cause (adding null check / try-catch to mask it)
-    - Fixing multiple things at once (adds variables)
-    
-    Output to me a brief:
-    - Phase 1 root-cause statement
-    - Phase 2 pattern-analysis conclusion
-    - Phase 3 hypothesis + verification
-    - Phase 4 fix commits
-    - Learnings (suggestions to append to .progress.md)
-```
-
-## Step 4: Report to user
-
-```
-✓ Debug complete
-
-Root cause: <Phase 1 conclusion>
-Pattern: <Phase 2 conclusion>
-
-Fix commits:
-  - <hash>: test - failing test
-  - <hash>: fix - root-cause fix
-  - <hash>: (additional) fixed N similar issues
-
-Verification:
-  - Failing test now PASS ✓
-  - Full test suite has no regressions ✓
-
-📝 Learnings (can be appended to .progress.md):
-  - <lesson 1>
-  - <lesson 2>
-
-Next steps:
-  - Review commits
-  - If the active spec has .progress.md, consider appending learnings
-```
-
-## Special case: 3 failures
-
-If the debugger reports 3 failures:
-
-```
-⚠ Systematic debugging failed (3 attempts)
-
-Attempts:
-  1. <method 1>: <why failed>
-  2. <method 2>: <why failed>
-  3. <method 3>: <why failed>
-
-Possible root issues:
-  - Wrong architectural assumption
-  - Dependency version / compatibility
-  - Data-layer issue
-
-Suggestions:
-  - Review the debugger's detailed report analysis
-  - Ask Claude directly: "from an architect's and debugger's perspective, what architectural issue does this bug hint at?"
-  - Or temporarily @ts-ignore / skip test and record as tech debt in STATE.md
-```
-
-## Forbidden
-
-- ✗ Omitting the bug description
-- ✗ Expecting "one-shot fix" (debug is a process, not an event)
-- ✗ Skipping the debugger and editing code yourself (loses the systematic methodology)
-- ✗ Accepting "maybe it's..." as a root cause
-
-## Relationship to other commands
-
-- `/curdx-flow:debug`: for **existing bugs**
-- `/curdx-flow:implement`: may encounter bugs, but flow-executor retries 5 times itself before considering `/curdx-flow:debug`
-- `/curdx-flow:verify`: finding a "false implementation" counts as a bug, can spawn `/curdx-flow:debug`
-
-## Typical scenarios
-
-```
-Scenario 1: Test suddenly failing
-  You: "npm test keeps failing a specific test lately but I can't tell why"
-  /curdx-flow:debug "login test in auth.test.ts fails in CI but passes locally"
-
-Scenario 2: Production bug
-  /curdx-flow:debug "production environment returns 500 for some API, stack trace: ..."
-
-Scenario 3: Bug introduced by refactor
-  /curdx-flow:debug "login broken after refactor of auth module; pre-refactor version works"
-```

package/commands/verify.md

@@ -1,142 +0,0 @@
----
-name: verify
-description: Goal-backward verification — trace from every FR / AC / AD in the spec to the code and tests, detect stubs and fake completions. The differentiator command. Optionally adds multi-source coverage audit with --strict.
-argument-hint: "[--strict]"
-allowed-tools: [Read, Bash, Task, Grep, Glob]
----
-
-# Goal-Backward Verification
-
-This is the **differentiator command**: it scans the implementation against the spec's own requirements and catches the most common Claude failure mode — claiming "done" while actual code is a stub or fake completion.
-
-## Flags
-
-| Flag | Default | Purpose |
-|------|---------|---------|
-| `--strict` | off | Also run multi-source coverage audit (FR / AC / AD / Research conclusions / D-NN decisions) — replaces v1's `/audit` command. |
-
-## Preflight
-
-```bash
-[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project."; exit 1; }
-
-SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$SPEC_NAME" ] && { echo "✗ No active spec. Run /curdx-flow:start first."; exit 1; }
-
-SPEC_DIR=".flow/specs/$SPEC_NAME"
-for f in requirements.md design.md tasks.md; do
-  [ ! -f "$SPEC_DIR/$f" ] && {
-    echo "✗ $SPEC_DIR/$f missing. Run /curdx-flow:spec first.";
-    exit 1;
-  }
-done
-
-FLAG_STRICT=$(echo "$ARGUMENTS" | grep -q -- '--strict' && echo 1 || echo 0)
-```
-
-## Workflow
-
-### Step 1: Dispatch `flow-verifier`
-
-Delegate to the `flow-verifier` agent with:
-- `requirements.md` (source of FR-NN, AC-N.N, US-NN)
-- `design.md` (source of AD-NN)
-- `tasks.md` (source of T-N.M and their Verify commands)
-- Repository root (to scan code + tests)
-
-The agent performs goal-backward tracing:
-1. For each **FR-NN**: search for code that implements it. Classify as `IMPLEMENTED` / `STUB` / `MISSING` / `UNCERTAIN`.
-2. For each **AC-N.N**: search for a test that exercises it. Classify as `TESTED` / `UNTESTED`.
-3. For each **AD-NN**: check that the design decision is reflected in code structure / interfaces.
-4. Detect suspicious patterns:
-   - `throw new Error("not implemented")` / `TODO` / `NotImplementedError`
-   - `return null` / `return {}` in places that should produce real output
-   - test files with only `it.skip(...)` or no assertions
-   - code that returns mocked fixtures instead of calling real collaborators
-
-### Step 2: Run the Verify commands from `tasks.md`
-
-For every task listed in `tasks.md`, run its declared `Verify:` command and record pass/fail. This is the most objective check — if the task said `npm test -- auth.spec.ts`, run exactly that.
-
-### Step 3: (Strict only) Multi-source coverage audit
-
-If `--strict`:
-- Cross-check every FR / AC / AD / decision against the implementation
-- Cross-check every research conclusion: was the recommended library / approach actually used?
-- Cross-check every D-NN decision in `.flow/STATE.md` that references this spec
-
-### Step 4: Produce `verification-report.md`
-
-**Landing check**: sub-agent responses can be truncated by the model's output-length limit. After dispatching `flow-verifier`, verify the report actually landed:
-
-```bash
-REPORT=".flow/specs/$SPEC_NAME/verification-report.md"
-if [ ! -f "$REPORT" ] || [ "$(wc -c < "$REPORT" 2>/dev/null | tr -d ' ')" -lt 300 ]; then
-  echo "⚠ Report missing or truncated. Re-dispatching flow-verifier with a terse 'write the report now' prompt."
-  # Re-dispatch pattern:
-  #   "Your only job right now is to Write the verification-report.md using the
-  #    findings you already gathered. Do not re-scan. Do not narrate. Write
-  #    the file and stop."
-fi
-```
-
-Write to `.flow/specs/$SPEC_NAME/verification-report.md`:
-
-```markdown
-# Verification Report — <spec-name>
-
-**Generated**: <ISO8601>
-**Mode**: strict | normal
-
-## Summary
-- FR coverage:  N/M implemented (K stubs, L missing)
-- AC coverage:  N/M tested
-- AD coverage:  N/M reflected
-- Verify commands: N/M passing
-
-## Findings
-
-### Missing implementations
-- FR-02: <description>. No matching code found in <paths searched>.
-
-### Stubs / fake completions
-- FR-05: Implemented in `src/auth.ts:42` but body is `throw new Error("not implemented")`.
-
-### Untested acceptance criteria
-- AC-1.3: No test asserts token refresh after 15 min expiry.
-
-### Failing Verify commands
-- T-2.1: `npm test auth.spec.ts` → 3 failed
-
-## Verdict
-- [ ] PASS — all items covered and passing
-- [X] PARTIAL — <n> findings must be addressed before shipping
-- [ ] MISSING — substantive implementation gaps
-```
-
-### Step 5: Apply `verification-gate`
-
-Hard rule from `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md`:
-- Any `STUB` or `MISSING` finding on a non-deferred FR blocks completion.
-- Any failing Verify command blocks completion.
-- Waive only with an explicit user D-NN decision logged to `.flow/STATE.md`.
-
-## Reporting
-
-```
-✓ Verification complete
-  FR coverage: 8/10 implemented (1 stub, 1 missing)
-  AC coverage: 9/12 tested
-  Verify commands: 14/15 passing
-  Verdict: PARTIAL
-
-Findings written to: .flow/specs/<name>/verification-report.md
-
-Next: address findings, then re-run /curdx-flow:verify, or run /curdx-flow:review.
-```
-
-## References
-
-- `flow-verifier` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-verifier.md`
-- `verification-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md`
-- `coverage-audit-gate` (used in strict mode): `@${CLAUDE_PLUGIN_ROOT}/gates/coverage-audit-gate.md`