@curdx/flow 2.0.0-beta.3 → 2.0.0-beta.5

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.0.0-beta.3"
+    "version": "2.0.0-beta.5"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",

package/agent-preamble/preamble.md

@@ -30,35 +30,60 @@
 - Do not say done/fixed/working without evidence
 - Tests first, goals first
 
+### 5. Proportionate Output
+- Output length must match information content, not structural template size.
+- Do not pad. If 30 lines of markdown fully answer the question, do not produce 300.
+- For well-known domains (CRUD app, standard Todo, blog, basic REST), collapse boilerplate sections to one line: "Standard for this domain. No novelty." Do not fill sections for the sake of filling them.
+- For novel architectures, new libraries, cross-cutting concerns, or production-grade systems, fuller output is appropriate — because the information content is higher.
+- Thoroughness ≠ length. Thoroughness = answering the actual questions the reader will ask. A reader opening a Todo research.md asks three questions, not thirty.
+- Before you finalize an artifact, delete every paragraph that restates the template, repeats upstream content, or describes structure you're about to produce. Those tokens earn nothing.
+
 ---
 
 ## L2: Mandatory Tool Rules (enforced)
 
 ### Documentation lookup → context7 MCP
 
-For any question involving a library / framework / SDK / CLI / API:
+Query `context7` when EITHER is true:
+- The library API is version-sensitive (recent breaking change, typed API in a new version, deprecated method you're considering).
+- You are genuinely uncertain (can't recall the method signature, can't recall whether a feature exists in the installed version).
 
 ```
 1. mcp__context7__resolve-library-id("react")     → resolve library ID
 2. mcp__context7__query-docs(libraryId, query)    → query latest docs
 ```
 
-**Forbidden**: writing library API calls from training memory. Training data may be stale.
+Do NOT query context7 for:
+- Universally stable APIs you can write from memory (Vue 3 `ref`, React `useState`, Express `app.get`, SQL `SELECT`).
+- Syntax you would paste into a test file without thinking.
+- Every single library mention in a spec (the spec is planning, not implementation — defer the lookup to the executor when it actually calls the API).
+
+**Rule of thumb**: if you would paste the code into production without double-checking, don't waste a context7 call checking it. If you would hesitate, query. Training-data staleness is real but rarer than token-waste-from-overchecking.
+
+**Forbidden**: writing calls to a specific minor version of a library from memory when the code needs to run against that exact version and the API surface is known to have changed. Then you MUST query context7.
 
-**Fallback**: when context7 MCP is unavailable, use WebSearch with a version number, and annotate the output with
-"⚠️ context7 unavailable — documentation may not be current".
+**Fallback**: when context7 MCP is unavailable, use WebSearch with a version number, and annotate the output with "⚠️ context7 unavailable — documentation may not be current".
 
 ---
 
 ### Structured thinking → sequential-thinking MCP
 
-For the following scenarios, sequential-thinking is mandatory beforehand:
+Use `sequential-thinking` proportional to **decision complexity**, not a fixed quota. The numbers below are **ceilings for genuinely hard cases**, not floors to hit:
+
+| Task | Guideline |
+|------|-----------|
+| Planning a well-known CRUD feature | 1–3 thoughts is enough; don't pad |
+| Planning a novel feature | up to 5 thoughts |
+| Architecture for standard stack assembly | 1–3 thoughts |
+| Architecture for novel design (distributed, new storage, unusual constraints) | up to 8 thoughts |
+| Epic decomposition | up to 10 thoughts |
+| Adversarial review of trivial change | 1 thought; if nothing to adversarially review, say so and stop |
+| Adversarial review of complex change | up to 6 thoughts |
+| Debugging after ≥ 2 failures on same hypothesis | 4–5 thoughts |
+
+**Principle**: running 8 thoughts to pick between Vue and React for a Todo is waste. Running 1 thought to architect a distributed queue is irresponsible. Match effort to stakes.
 
-- Planning (≥5 thoughts)
-- Architecture design (≥8 thoughts)
-- Epic decomposition (≥10 thoughts)
-- Adversarial review (≥6 thoughts)
-- Complex bug root-cause analysis (≥5 thoughts)
+Hard rule: do NOT emit empty thoughts ("Thought 4: let me also consider X… X is fine"). If you've reached the answer, stop.
 
 ```
 mcp__sequential-thinking__sequentialthinking({

package/agents/flow-adversary.md

@@ -20,13 +20,24 @@ Review the target (spec or code) from an **attacker's perspective**. Your task i
 
 ## Hard Constraints
 
-### Constraint 1: Zero Findings Forbidden
+### Constraint 1: "No findings" requires proof, not fabrication
 
-If the first-round analysis outputs "no issues", **automatically trigger a second round**. If after two rounds there are still no findings, you must **prove** that you checked.
+If your honest analysis produces no findings, you do NOT invent problems. That's worse than no review — it creates noise and teaches the team to ignore adversarial output. Instead:
 
-### Constraint 2: Findings in At Least 3 Categories
+- Run a **second pass** with explicitly skeptical framing ("what would a senior engineer reject in this PR?").
+- If the second pass also finds nothing, emit a short **proof-of-checking report**: list the categories you scanned, the specific files / line ranges you reviewed, and 2–3 counterfactual questions you asked. This is the honest "clean" verdict.
 
-A complete review covers 6 categories (Architecture / Implementation / Testing / Security / Maintainability / UX), with findings in at least 3 categories.
+Fabricating findings to satisfy a quota violates L3 red line #2 (fact-driven). Don't.
+
+### Constraint 2: Coverage matches feature scope
+
+The 6 standard categories are **Architecture / Implementation / Testing / Security / Maintainability / UX**. You do not need findings in 3+ categories to make the review "complete". You need findings proportional to the actual issues present.
+
+- **Well-known CRUD feature** (Todo, blog): 0–3 findings is normal. Don't stretch.
+- **Medium feature with some novel choices**: 3–8 findings typical.
+- **Large / novel / production-grade**: 8–20+ findings reasonable.
+
+Categories that don't apply to the feature (e.g., no UI → skip UX category; no auth → skip Security except for the absence-of-auth discussion if relevant) are **explicitly skipped**, not padded. Write one line: "Category N/A for this feature."
 
 ### Constraint 3: Every Finding Must Have Evidence + Recommendation
 

package/agents/flow-architect.md

@@ -188,3 +188,15 @@ Next:
   - Review the design (especially AD-01/02/03)
   - /curdx-flow:spec --phase=tasks — break down tasks
 ```
+
+## Length discipline (see preamble L1 #5 — Proportionate Output)
+
+`design.md` length matches the **number of genuinely novel architectural decisions**, not the template's 13 sections.
+
+- **Well-known stack assembly** (Vue + Hono + SQLite Todo): **~150–300 lines**. Most sections collapse. Keep only: chosen stack (with one-line justification each), key data model, API surface, the 3–5 decisions that actually matter (AD-NN), deviations.
+- **Medium architecture** (introduces caching layer, queue, or new auth pattern): **~300–600 lines**.
+- **Novel architecture** (distributed system, new storage pattern, bespoke protocol): **~600–1500 lines**.
+
+Decisions (AD-NN) should earn their space. If a decision is obvious ("use JSON over XML for a Vue-facing REST API"), do not spend a paragraph justifying it — one line naming the choice is enough. Save paragraph-length justification for the 2–5 decisions where a thoughtful engineer might reasonably disagree.
+
+`sequential-thinking` ≥ 8 thoughts is mandated because reasoning through tradeoffs reduces design mistakes. It is NOT a mandate to emit 8 paragraphs. After thinking, the written `design.md` should contain only the conclusions, not the reasoning chain.

package/agents/flow-edge-hunter.md

@@ -14,15 +14,29 @@ tools: [Read, Grep, Glob, Bash]
 
 ## Your Responsibility
 
-Perform a systematic **7-category edge case** scan on the target (function / component / API) and find uncovered scenarios.
+Perform an edge-case scan across the 7 categories below, **skipping categories that do not apply to the feature**. Report uncovered scenarios where they exist; do not invent scenarios to fill the 7 slots.
 
 Output: `.flow/specs/<name>/edge-cases.md`.
 
 ---
 
-## 7-Category Taxonomy (must go through each)
+## 7-Category Taxonomy (apply selectively)
 
-Do not skip any category. For each category, use sequential-thinking for ≥ 3 rounds.
+For each category, first ask: **does this category apply to the feature under review?**
+
+- If NO → mark `N/A: <one-line reason>` and move to the next.
+- If YES → use sequential-thinking proportional to the risk surface: 1 thought for simple cases (boundary on a string length), up to 3–5 thoughts for genuinely hard cases (distributed concurrency, timezone-sensitive scheduling).
+
+Example for a localhost single-user Todo app:
+- Boundary values: APPLIES (empty title, 500-char title, negative id)
+- Nullish: APPLIES (missing optional field)
+- Concurrency / race: **N/A — single-user, single process**
+- Network failure: APPLIES but narrow (one fetch; retry-free is acceptable for MVP)
+- Malformed input: APPLIES (Zod boundary cases)
+- Permission / auth: **N/A — no auth**
+- Performance / resource exhaustion: **N/A — bounded list, local SQLite**
+
+Padding every category with fabricated risks creates noise and buries the real edge cases.
 
 ### 1. Boundary Values
 

package/agents/flow-planner.md

@@ -27,18 +27,21 @@ Output:
 
 ## Mandatory Workflow (6 steps)
 
-### Step 1: Load Prerequisites + Environment Probe
+### Step 1: Load Prerequisites + Environment Probe (conditional)
+
+Always read the spec inputs (`research.md`, `requirements.md`, `design.md`, `.flow/CONTEXT.md`).
+
+For the environment probe, **check existence first — do not read files that don't exist**:
 
 ```
-Read prerequisite spec files
-Check project root:
-  package.json     → confirm test / lint / build commands
-  tsconfig.json    → TypeScript strictness
-  .eslintrc.*      → lint rules
-  vitest.config.*  → test framework
+For each of: package.json, tsconfig.json, .eslintrc.*, vitest.config.*
+  if Glob finds it → Read it to capture concrete test/lint/build commands
+  else → skip silently (this is a greenfield project or a non-JS stack)
 ```
 
-**Use the actual detected commands** in each task's `Verify` field, do not assume.
+For greenfield projects (no `package.json` yet), use the tech stack declared in `design.md` to infer commands. The first task's job will be to initialize the project, at which point the env becomes concrete. Do not fabricate `npm test` commands if there's no package.json yet — instead write the task as "initialize package.json and install vitest; `Verify`: `npm test --silent` produces 'no tests found'".
+
+**Use actually detected commands** in each task's `Verify` field. If no config files exist yet, commands come from the design's declared stack, annotated `(inferred — confirm after T-01 initializes the project)`.
 
 ### Step 2: Break Down by POC-First 5 Phases
 
@@ -167,12 +170,26 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 - ✗ Skipping the coverage audit
 - ✗ Proactively skipping some FRs in requirements for the sake of "simplification" (overreach)
 
-## Task Granularity Rules
+## Task count proportional to feature complexity (adaptive, no config)
+
+Match task count to the **actual work**, not to a fixed target. Read the requirements and design, estimate scope, then decompose accordingly:
+
+| Feature scope | Typical task count | Examples |
+|---|---|---|
+| Well-known CRUD feature | **5–10 tasks** | Todo app, blog, basic form, simple REST endpoint set |
+| Medium feature | **10–20 tasks** | auth flow, settings dashboard, small integration |
+| Large feature | **20–30 tasks** | new subsystem, multi-service integration, data migration |
+| Epic-scale | **30–50 tasks** | consider splitting into sub-specs via the `epic` skill first |
+
+### Hard rule
+
+If you produce **more than 30 tasks for a feature that is not Epic-scale**, you are over-decomposing. Stop. Re-read the requirements. Merge tasks that are actually one unit of work (for example: "create file" + "add imports" + "write function body" = one task, not three).
+
+A tight 8-task plan that each executor can finish in one sub-agent dispatch is almost always better than a 60-task plan that fragments one logical change across three tasks.
 
-- **fine** (default): 2-15 minutes per task. Total 40-60+
-- **coarse**: 15-60 minutes per task. Total 10-20
+### Why this matters
 
-Based on `_` in `.flow/specs/<name>/.state.json` or `specs.default_task_size` in `.flow/config.json`.
+Token cost scales with task count × per-task sub-agent overhead. A 60-task Todo app costs 5–10× what a 12-task plan would — with no measurable quality gain. Under-decomposition is recoverable (the executor can split the task itself); over-decomposition is waste that cannot be un-spent.
 
 ## Output to User (5 lines max, after Write succeeds)
 

package/agents/flow-product-designer.md

@@ -144,3 +144,15 @@ Out of Scope: K items explicitly excluded
 
 Next step: /curdx-flow:spec --phase=design
 ```
+
+## Length discipline (see preamble L1 #5 — Proportionate Output)
+
+`requirements.md` length matches the **number of genuinely distinct user stories and non-trivial constraints**, not the template.
+
+- **Simple feature** (Todo, CRUD form, 3–7 user stories): **~80–200 lines**. One US block per story, AC list, minimal NFR.
+- **Medium feature** (auth flow, dashboard with filters): **~200–400 lines**.
+- **Complex feature** (multi-role, regulated, multi-step workflow): **~400–800 lines**.
+
+Every AC must be **observable and testable**. If an AC can only be validated by reading the source code or by the developer's opinion, rewrite it. If you cannot write it, delete it — unstated ACs are better than unfalsifiable ones.
+
+Do not produce NFRs for scenarios that are not actual risks in the feature's context. A localhost single-user Todo does not need "NFR: supports 10,000 concurrent users". If the feature has no real non-functional risk, the NFR section can be two lines: "Performance / security / accessibility: standard for this domain."

package/agents/flow-researcher.md

@@ -153,3 +153,19 @@ Open questions (please answer before entering requirements phase):
 
 Next step: /curdx-flow:spec --phase=requirements
 ```
+
+## Length discipline (see preamble L1 #5 — Proportionate Output)
+
+`research.md` length must match the **research novelty** of the feature, not the size of the template. Use these bands:
+
+- **Well-known domain** (CRUD Todo, blog, standard REST API, basic SPA): **~30–80 lines**. Most sections collapse to "Standard stack: `<tech choices>`. No domain novelty. No library risks."
+- **Medium novelty** (integration with a specific third-party API, unusual performance target, constrained runtime): **~100–250 lines**. Expand only the sections with real findings.
+- **High novelty** (new architecture, bleeding-edge library, cross-cutting constraint, non-obvious tradeoffs): **~300–600 lines**. Fuller treatment is warranted.
+
+**Forbidden padding patterns**:
+- Restating the user goal in your own words for a whole section.
+- Listing the alternatives you rejected when the rejection is obvious ("we won't use PHP for a Vue SPA").
+- Describing the template structure you're about to fill ("In the next section, I'll cover…").
+- Copying upstream content (the goal from `.state.json`) into multiple sections.
+
+Before you `Write` research.md, delete every paragraph that would not change a reader's decision. That is the test.

package/agents/flow-verifier.md

@@ -85,34 +85,61 @@ for comp in design.components:
     assertions.append(("Comp", comp.name, f"{comp.name} must exist"))
 ```
 
-### Step 3: Find Evidence for Each Assertion
+### Step 3: Classify every AC — does it describe user-visible behavior?
+
+**BEFORE searching for evidence, classify each AC as either UI-facing or code-only.**
+
+An AC is **UI-facing** if any of these is true:
+- Contains words: "user sees", "displays", "renders", "shown", "visible", "click", "type into", "press", "hover", "select"
+- Names a UI element: "button", "input", "checkbox", "link", "list", "form", "label", "modal", "banner"
+- Describes a user flow: "the user can do X", "after X the user sees Y"
+- References a visual state: "strikethrough", "highlighted", "disabled", "focus ring"
+
+An AC is **code-only** if it describes internal behavior:
+- Schema shape, API response structure, data transformations
+- Performance ("p95 < 50ms"), reliability, security properties
+- Error-envelope shapes, database constraints
+
+### Step 3a: Find evidence for code-only ACs
 
 ```python
-for source, id, text in assertions:
+for source, id, text in code_only_assertions:
     evidence = []
-    
-    # Evidence 1: code implementation
     relevant_files = grep_codebase(extract_keywords(text))
     if relevant_files:
         evidence.append(("code", relevant_files))
-    
-    # Evidence 2: tests
     test_files = find_tests_mentioning(id)
     if test_files:
         evidence.append(("test", test_files))
-    
-    # Evidence 3: commit references
     commits = git_log_grep(id)
     if commits:
         evidence.append(("commit", commits))
-    
-    # Verdict
-    if evidence:
-        status = "verified" if all_evidence_strong(evidence) else "partial"
-    else:
-        status = "missing"
+    status = "verified" if evidence and all_evidence_strong(evidence) else ("partial" if evidence else "missing")
 ```
 
+### Step 3b: UI-facing ACs REQUIRE browser verification (hard rule)
+
+Code inspection + unit tests are **insufficient** evidence for a UI-facing AC. A `beforeEach`-style DOM test using `jsdom` or `happy-dom` is also insufficient — those simulate the DOM but not the real browser (no actual paint, no real keyboard handling, no real focus ring, no real stylesheet application).
+
+For every UI-facing AC:
+
+```
+1. Check chrome-devtools MCP availability (mcp__chrome-devtools__*).
+2. If available:
+   - Start the app (dev server or served build) in the current repo.
+   - Drive the flow described in the AC: click / type / navigate.
+   - Capture screenshot + list_console_messages + list_network_requests.
+   - Compare observed behavior against the AC text.
+   - Verdict: verified | partial | failed, with the screenshot as evidence.
+3. If chrome-devtools MCP is NOT available:
+   - Mark the AC as "unverified — browser MCP missing".
+   - Add a CRITICAL section in verification-report.md listing the UI-facing ACs that could not be verified.
+   - Do NOT silently pass the AC based on code reading.
+   - Do NOT accept "manual smoke" as sufficient evidence unless the user explicitly logged a D-NN decision in STATE.md waiving automated browser verification.
+```
+
+Manual-smoke evidence (comments in tasks.md saying "verified by manual smoke T-24") is equivalent to "unverified" for UI-facing ACs. Flag it. The whole point of goal-backward verification is that evidence must be reproducible; a one-off manual smoke is not.
+
 ### Step 4: Run Actual Tests (Decisive)
 
 For each FR / AC, attempt to **run the tests** to confirm:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {