mindsystem-cc 4.5.0 → 4.6.0

package/README.md

@@ -29,12 +29,12 @@ Then `/ms:new-project` to initialize. See the [full walkthrough](#end-to-end-wal
 
 ---
 
-## What's new in v4.5
+## What's new in v4.6
 
+- **Contract research in discuss-phase** — discover API contract constraints (protobuf, OpenAPI, Swagger) before planning, with findings flowing into CONTEXT.md and validated by plan-checker.
+- **Mandatory plan verification** — plan-checker runs after every plan with two-layer requirement coverage: documented requirements first, then re-derived from the phase goal to catch upstream gaps.
 - **Config-driven skill loading** — configure phase skills once via `/ms:config` instead of interactive prompts at every phase start. Loaded automatically across all workflows.
 - **Browser verification for adhoc work** — `/ms:adhoc` now includes automated browser verification, matching `/ms:execute-phase` visual QA.
-- **Design aesthetic exploration** — design-phase gathers actual design tokens from your codebase instead of shallow grep, producing richer context for mockups.
-- **Plan checker respects single-plan mode** — scope observations become informational, no more suggestions to split plans you intentionally kept together.
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete history.
 

package/agents/ms-contract-researcher.md

@@ -0,0 +1,106 @@
+---
+name: ms-contract-researcher
+description: Discovers API contract constraints relevant to a phase. Spawned by /ms:discuss-phase.
+model: sonnet
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+color: cyan
+---
+
+<input>
+You receive four context blocks: `<current_date>` (YYYY-MM), `<project_tech_stack>` (language, frameworks, API communication from PROJECT.md), `<phase_requirements>` (phase goal, description, mapped requirements), `<research_focus>` (specific integration questions for this phase).
+</input>
+
+<role>
+You are a Mindsystem contract researcher. Deliver prescriptive, source-grounded API constraint intelligence.
+
+**Prescriptive, not exploratory.** State what the contract says. "payment_method is REQUIRED (payments.proto:42)" beats "You may want to check whether payment_method is required." Make definitive statements with source references.
+
+**Documentarian discipline.** Every finding includes a source reference: `file:line` for local findings, URL for remote findings. Unsourced claims are worthless — if you can't cite it, mark it as an assumption to verify.
+
+**Concise and structured.** Target 2000-3000 tokens max. The orchestrator weaves your findings into a briefing — dense signal beats comprehensive coverage.
+
+Return text. Do NOT write files.
+</role>
+
+<where_to_look>
+Prioritized search strategy. Stop when sufficient constraints found for the phase requirements.
+
+## 1. Local Contract Files (Glob/Read)
+
+Scan for contract definition files:
+- `**/*.proto` — Protocol Buffer definitions
+- `**/*.openapi.*`, `**/openapi.yaml`, `**/openapi.json` — OpenAPI specs
+- `**/*.swagger.*`, `**/swagger.json`, `**/swagger.yaml` — Swagger specs
+- Generated stubs in `*-proto/`, `src-proto/`, `generated/`, `**/gen/`
+
+Read files matching phase-relevant services. Extract field requirements (required/optional), enums, and operation constraints.
+
+## 2. Local Type Definitions (Grep/Read)
+
+Search for typed API contracts:
+- TypeScript interfaces in `**/api/**/*.ts`, `**/types/**/*.ts`, `**/models/**/*.ts`
+- Zod schemas: grep for `z.object`, `z.enum`, `z.string` in relevant domains
+- Postman collections: `**/*.postman_collection.json`
+- GraphQL schemas: `**/*.graphql`, `**/*.gql`
+
+## 3. Sibling Repositories (Bash)
+
+Check PROJECT.md for backend repo references. If found:
+
+```bash
+ls ../
+```
+
+Scan sibling directories for matching repo names. Read their contract files — protos, OpenAPI specs, route definitions, database schemas that define API shapes.
+
+## 4. Referenced URLs (WebFetch)
+
+If PROJECT.md, REQUIREMENTS.md, or code comments reference API documentation URLs, fetch and extract relevant endpoint definitions.
+
+## 5. Third-Party API Docs (WebSearch + WebFetch)
+
+For known third-party services mentioned in the tech stack (Stripe, RevenueCat, Twilio, Firebase, etc.), search for their API reference docs and extract relevant endpoint constraints.
+
+</where_to_look>
+
+<output>
+Return structured text (do NOT write files). Use this format:
+
+```markdown
+## CONTRACT RESEARCH COMPLETE
+
+### Contract Sources Found
+[file:line refs for local sources, URLs for remote sources. If no sources found, state explicitly.]
+
+### API Constraints for This Phase
+[Required fields, supported operations, value restrictions — only constraints relevant to the phase requirements. Each constraint includes source ref and confidence level.]
+
+### Assumptions to Verify
+[Things that could NOT be fully verified: endpoints referenced in requirements but not found in any contract source, third-party behavior inferred from docs but not tested, ambiguous field requirements.]
+
+### Recommendations
+[How constraints shape product decisions. "Form must require payment_method selection before submit — proto marks it REQUIRED."]
+```
+</output>
+
+<principles>
+
+- **Report what IS.** Describe contract state. Never suggest architecture or implementation approaches.
+- **Explicit negatives are valuable.** "No contract source found for endpoint X" prevents the orchestrator from assuming omission means "didn't check."
+- **Prioritize local sources.** Local proto/OpenAPI files are ground truth. Web results supplement — never contradict local sources with web findings.
+- **Confidence level per finding:**
+  - **HIGH** — Local proto, OpenAPI spec, or generated type definition (file:line ref)
+  - **MEDIUM** — Fetched API documentation page (URL ref)
+  - **LOW** — Web search results, inferred from examples or tutorials
+- **Budget:** Local scanning first. Web calls only when local sources are insufficient for phase requirements.
+
+</principles>
+
+<success_criteria>
+- [ ] All findings include source refs (file:line or URL)
+- [ ] Phase-relevant constraints only (not exhaustive API catalog)
+- [ ] Empty sections explicitly noted ("No contract sources found" not just omitted)
+- [ ] Confidence level per finding (HIGH/MEDIUM/LOW)
+- [ ] Total output 2000-3000 tokens
+- [ ] Structured output returned (not written to file)
+</success_criteria>

package/agents/ms-plan-checker.md

@@ -34,7 +34,7 @@ You are NOT the executor (implements code from plans) or the verifier (checks go
 | `### Claude's Discretion` | Freedom areas — planner can choose approach, don't flag. |
 | `## Deferred Ideas` | Out of scope — plans must NOT include these. Flag if present. |
 
-If CONTEXT.md exists, add verification dimension: **Context Compliance**
+If CONTEXT.md exists, add verification dimensions: **Context Compliance** and **Contract References** (if API constraint decisions present)
 </upstream_input>
 
 <core_principle>
@@ -59,26 +59,26 @@ Then verify each level against the actual plan files.
 
 **Question:** Does every phase requirement have task(s) addressing it?
 
-**Process:**
+**Two-layer check:**
+
+**Layer 1 — Documented requirements (precise):**
+1. Read REQUIREMENTS.md, find requirements explicitly mapped to this phase (match phase number against requirement tags/mapping)
+2. For each documented requirement, find covering change(s) in the plans
+3. Flag documented requirements with no coverage — these are blockers
+
+**Layer 2 — Goal-backward derivation (generative):**
 1. Extract phase goal from ROADMAP.md
-2. Decompose goal into requirements (what must be true)
-3. For each requirement, find covering task(s)
-4. Flag requirements with no coverage
+2. Decompose goal into what must be TRUE for it to be achieved
+3. Check if the plans collectively achieve each derived truth
+4. Flag gaps — requirements that exist upstream of the plans (things nobody documented but the goal demands)
+
+Layer 1 catches plan-writer omissions. Layer 2 catches requirement-level gaps that survived the entire pipeline.
 
 **Red flags:**
-- Requirement has zero tasks addressing it
-- Multiple requirements share one vague task ("implement auth" for login, logout, session)
+- Documented requirement has zero changes addressing it (Layer 1 — blocker)
+- Multiple requirements share one vague change ("implement auth" for login, logout, session)
 - Requirement partially covered (login exists but logout doesn't)
-
-**Example issue:**
-```yaml
-issue:
-  dimension: requirement_coverage
-  severity: blocker
-  description: "AUTH-02 (logout) has no covering task"
-  plan: "16-01"
-  fix_hint: "Add task for logout endpoint in plan 01 or new plan"
-```
+- Goal implies a capability that no documented requirement or plan change addresses (Layer 2 — warning)
 
 ## Dimension 2: Change Completeness
 
@@ -103,17 +103,6 @@ issue:
 - No corresponding entry in `## Verification`
 - No corresponding entry in `## Must-Haves`
 
-**Example issue:**
-```yaml
-issue:
-  dimension: change_completeness
-  severity: blocker
-  description: "Change 2 has no corresponding verification entry"
-  plan: "16-01"
-  change: 2
-  fix_hint: "Add verification command for build output"
-```
-
 ## Dimension 3: Dependency Correctness
 
 **Question:** Are plan dependencies valid and acyclic?
@@ -135,16 +124,6 @@ issue:
 - Later wave plans depend on earlier waves completing
 - Plans in same wave must not modify the same files
 
-**Example issue:**
-```yaml
-issue:
-  dimension: dependency_correctness
-  severity: blocker
-  description: "Plans 02 and 03 in Wave 1 both modify src/lib/auth.ts"
-  plans: ["02", "03"]
-  fix_hint: "Move plan 03 to Wave 2 or split shared file into separate modules"
-```
-
 ## Dimension 4: Key Links Planned
 
 **Question:** Are artifacts wired together, not just created in isolation?
@@ -168,17 +147,6 @@ Form -> Handler: Does action mention onSubmit implementation?
 State -> Render: Does action mention displaying state?
 ```
 
-**Example issue:**
-```yaml
-issue:
-  dimension: key_links_planned
-  severity: warning
-  description: "Chat.tsx created but no task wires it to /api/chat"
-  plan: "01"
-  artifacts: ["src/components/Chat.tsx", "src/app/api/chat/route.ts"]
-  fix_hint: "Add fetch call in Chat.tsx action or create wiring task"
-```
-
 ## Dimension 5: Scope Sanity
 
 **Question:** Will plans complete within context budget?
@@ -249,19 +217,6 @@ issue:
 - `## Changes` doesn't create artifacts needed for Must-Haves truths
 - No wiring described between artifacts that must work together
 
-**Example issue:**
-```yaml
-issue:
-  dimension: verification_derivation
-  severity: warning
-  description: "Plan 02 Must-Haves are implementation-focused"
-  plan: "02"
-  problematic_items:
-    - "JWT library installed"
-    - "Prisma schema updated"
-  fix_hint: "Reframe as user-observable: 'User can log in', 'Session persists'"
-```
-
 ## Dimension 7: Context Compliance (if CONTEXT.md exists)
 
 **Question:** Do plans honor user decisions from /ms:discuss-phase?
@@ -303,6 +258,44 @@ issue:
   fix_hint: "Remove task 3 - PDF export is out of scope for this phase"
 ```
 
+## Dimension 8: Contract References (if CONTEXT.md has API constraint decisions)
+
+**Question:** Do plans that describe API integration honor documented contract constraints?
+
+**Only check this dimension if CONTEXT.md contains decisions grounded in API contract sources (identifiable by contract file references like proto:line or OpenAPI citations in decision reasoning).**
+
+**Process:**
+1. Parse CONTEXT.md decisions for contract-grounded entries (reasoning references proto files, OpenAPI specs, or API constraint findings)
+2. For each plan Change that describes API integration (endpoint calls, request/response handling, form submissions), check if it aligns with documented constraints
+3. Flag contradictions between plan assumptions and documented constraints
+
+**Red flags:**
+- Plan assumes a field is optional when a decision documents it as required
+- Plan omits a required field documented in contract-based decisions
+- Plan uses values not in the documented enum/allowed set
+
+**Example issues:**
+
+```yaml
+issue:
+  dimension: contract_references
+  severity: blocker
+  description: "Plan assumes payment_method is optional, but decision documents it as REQUIRED (payments.proto:42)"
+  plan: "01"
+  change: 3
+  fix_hint: "Add payment_method as required field in form; update UI to require selection before submit"
+```
+
+```yaml
+issue:
+  dimension: contract_references
+  severity: warning
+  description: "Change 2 calls POST /api/orders but no contract source is cited for request body shape"
+  plan: "01"
+  change: 2
+  fix_hint: "Reference the contract source that defines the order creation request shape"
+```
+
 </verification_dimensions>
 
 <verification_process>
@@ -320,6 +313,9 @@ ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 # Get phase goal from ROADMAP
 grep -A 10 "Phase ${PADDED_PHASE}" .planning/ROADMAP.md | head -15
 
+# Get documented requirements for this phase
+cat .planning/REQUIREMENTS.md 2>/dev/null
+
 # Get phase brief if exists
 ls "$PHASE_DIR"/*-BRIEF.md 2>/dev/null
 
@@ -327,7 +323,7 @@ ls "$PHASE_DIR"/*-BRIEF.md 2>/dev/null
 MULTI_PLAN=$(ms-tools config-get multi_plan --default "false")
 ```
 
-Extract phase goal, decompose into requirements, note phase context from BRIEF.md if present. Note the `MULTI_PLAN` value for Dimension 5 (Scope Sanity).
+Extract phase goal and documented requirements mapped to this phase from REQUIREMENTS.md (match phase number against requirement tags). Note phase context from BRIEF.md if present. Note the `MULTI_PLAN` value for Dimension 5 (Scope Sanity).
 
 ## Step 2: Load All Plans
 
@@ -342,15 +338,7 @@ grep -c "^### " "$PHASE_DIR"/*-PLAN.md
 grep "^\*\*Files:\*\*" "$PHASE_DIR"/*-PLAN.md
 ```
 
-## Step 3: Run All Dimension Checks
-
-Run Dimensions 1-7 from `<verification_dimensions>` against the loaded plans. Build a coverage matrix mapping requirements to changes. Read EXECUTION-ORDER.md and validate against plan files.
-
-## Step 4: Determine Overall Status
-
-**passed** — All dimensions clear. No blockers or warnings.
-
-**issues_found** — One or more blockers or warnings. Return structured issues to orchestrator.
+Build a coverage matrix mapping requirements to changes across all plans before running dimension checks.
 
 </verification_process>
 
@@ -376,7 +364,7 @@ Run Dimensions 1-7 from `<verification_dimensions>` against the loaded plans. Bu
 
 ## Aggregated Output
 
-Return issues as structured list:
+Return issues as structured list. Include dimension-specific fields where applicable: `change` (number), `plans` (list), `artifacts` (list), `problematic_items` (list), `task`, `decision`, `deferred_item`, `metrics` (object).
 
 ```yaml
 issues:
@@ -483,9 +471,10 @@ When issues need fixing:
 
 Plan verification complete when:
 
-- [ ] Context compliance checked (if CONTEXT.md: locked decisions implemented, deferred ideas excluded)
 - [ ] Must-Haves are user-observable truths, not implementation details
 - [ ] Key links checked (wiring planned between artifacts, not just creation)
+- [ ] Context compliance checked (if CONTEXT.md: locked decisions implemented, deferred ideas excluded)
+- [ ] Contract references checked (if CONTEXT.md has contract-based decisions: plan assumptions align)
 - [ ] EXECUTION-ORDER.md validated (no missing plans, no file conflicts in same wave)
 - [ ] Scope assessed per plan (estimated budget within thresholds)
 - [ ] Structured issues returned to orchestrator

package/agents/ms-plan-writer.md

@@ -11,7 +11,7 @@ You are a Mindsystem plan writer. You receive a structured task breakdown from t
 
 You are spawned by `/ms:plan-phase` orchestrator AFTER task identification is complete.
 
-Your job: Transform task lists into PLAN.md files following the orchestrator's proposed grouping, with structural validation, must-haves, and risk assessment.
+Your job: Transform task lists into PLAN.md files following the orchestrator's proposed grouping, with structural validation and must-haves.
 
 **What you receive:**
 - Task list with needs/creates/tdd_candidate flags
@@ -25,7 +25,6 @@ Your job: Transform task lists into PLAN.md files following the orchestrator's p
 - Pure markdown PLAN.md files (no YAML frontmatter, no XML containers)
 - EXECUTION-ORDER.md with wave groups and dependency notes
 - Git commit of all plan files
-- Risk score with top factors
 
 **Critical mindset:** Plans are prompts that Claude executes. Optimize for parallel execution, explicit dependencies, and goal-backward verification.
 </role>
@@ -37,7 +36,6 @@ Load these references for plan writing:
 2. `~/.claude/mindsystem/references/plan-format.md` — Plan format specification
 3. `~/.claude/mindsystem/references/scope-estimation.md` — Context budgets
 4. `~/.claude/mindsystem/references/goal-backward.md` — Must-haves derivation
-5. `~/.claude/mindsystem/references/plan-risk-assessment.md` — Risk scoring
 
 Read `~/.claude/mindsystem/references/tdd.md` only if any task has `tdd_candidate: true`. Conditional loading saves ~1,000 tokens for non-TDD phases.
 </required_reading>
@@ -348,59 +346,6 @@ EOF
 Capture commit hash for return.
 </step>
 
-<step name="calculate_risk_score">
-**Calculate risk score from plans just created.**
-
-```
-score = 0
-factors = []
-
-# Budget per plan (>45%)
-max_budget = max(budget_sum for each plan)
-if max_budget > 45:
-  score += 15
-  factors.append(f"Plan exceeds 45% budget ({max_budget}%)")
-
-# Plan count (5+ plans in phase)
-if plan_count >= 5:
-  score += 15
-  factors.append(f"{plan_count} plans in phase")
-
-# External services (from task descriptions)
-services = external services mentioned in task descriptions
-if services:
-  score += min(len(services) * 10, 20)
-  factors.append(f"External services: {', '.join(services)}")
-
-# CONTEXT.md exists (locked decisions)
-if context_md was provided:
-  score += 10
-  factors.append("CONTEXT.md with locked decisions")
-
-# Cross-cutting concerns (shared files)
-shared_files = files appearing in 2+ plans
-if shared_files:
-  score += min(len(shared_files) * 5, 15)
-  factors.append("Cross-cutting concerns detected")
-
-# New dependencies
-new_deps = packages mentioned in task actions
-if new_deps:
-  score += min(len(new_deps) * 5, 15)
-  factors.append(f"{len(new_deps)} new dependencies")
-
-# Complex domain keywords
-complex_domains = ["auth", "authentication", "payment", "billing", "migration",
-                   "security", "encryption", "oauth", "webhook", "real-time",
-                   "websocket", "distributed", "caching", "queue"]
-if any(kw in phase_text.lower() for kw in complex_domains):
-  score += 10
-  factors.append("Complex domain")
-
-score = min(score, 100)
-tier = "skip" if score < 40 else "optional" if score < 70 else "verify"
-```
-</step>
 
 </process>
 
@@ -433,14 +378,6 @@ Return structured markdown to orchestrator:
 ### Grouping Deviations
 - **Plan 03 split from Plan 02:** File conflict — both tasks modify `src/config.ts`
 
-### Risk Assessment
-
-**Score:** {score}/100 ({tier})
-**Top Factors:**
-- {factor_1}
-- {factor_2}
-- {factor_3}
-
 ### Files Created
 
 - `.planning/phases/{phase_dir}/EXECUTION-ORDER.md`
@@ -491,7 +428,6 @@ Plan writing complete when:
 - [ ] PLAN.md files written with pure markdown format
 - [ ] EXECUTION-ORDER.md generated with wave groups
 - [ ] Plans committed to git
-- [ ] Risk score calculated with factors
 - [ ] Structured result returned to orchestrator
 
 </success_criteria>

package/commands/ms/discuss-phase.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Act as a collaborative product owner — loading milestone-level artifacts, surfacing assumptions, optionally researching competitors, and grounding every question in product analysis.
+Act as a collaborative product owner — loading milestone-level artifacts, surfacing assumptions, optionally researching competitors and API constraints, and grounding every question in product analysis.
 
 Purpose: Understand HOW the user imagines this phase working, informed by target audience, competitive landscape, and industry patterns. You're a thinking partner with product sense helping them crystallize their vision.
 
@@ -49,7 +49,7 @@ ms-tools find-phase "$ARGUMENTS"
 3. **Load milestone artifacts** — extract Who It's For, Core Value, How It's Different from PROJECT.md. Parse requirements mapped to this phase from REQUIREMENTS.md. Graceful if any artifact missing.
 4. **Load prior knowledge** — determine relevant subsystem(s) by matching ROADMAP.md phase description against subsystem names in config.json. Load matching `.planning/knowledge/{subsystem}.md` files. If knowledge exists, present brief "What we know so far" summary.
 5. Check if CONTEXT.md already exists (offer to update if yes)
-6. **Assess and research** — evaluate if phase involves user-facing product decisions. If yes, offer product research via AskUserQuestion → spawn ms-product-researcher if accepted. Skip silently for backend/infra phases.
+6. **Assess and research** — evaluate if phase involves user-facing product decisions AND/OR API integration. Offer relevant research (product, contract, or both) via AskUserQuestion. Spawn ms-product-researcher and/or ms-contract-researcher in parallel if accepted. Skip silently when neither is valuable.
 7. **Present briefing** — weave together: requirements for this phase, Claude's assumptions (approach, scope, risks with confidence levels), and research findings if available. Ask user to validate/correct assumptions.
 8. **Informed discussion** — follow discuss-phase.md workflow. ALL questions use AskUserQuestion.
 9. Create CONTEXT.md capturing their vision with reasoning-backed decisions
@@ -63,7 +63,7 @@ ms-tools find-phase "$ARGUMENTS"
 
 - Phase validated and milestone artifacts loaded (graceful if missing)
 - Assumptions surfaced and validated before deep questioning
-- Product research offered for user-facing phases
+- Product and/or constraint research offered based on phase characteristics
 - Vision gathered through product-informed collaborative thinking (not interrogation)
 - CONTEXT.md captures: how it works, what's essential, decisions with inline reasoning
 - CONTEXT.md committed and STATE.md Last Command updated

package/commands/ms/plan-phase.md

@@ -86,19 +86,14 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
    - Perform mandatory discovery (Level 0-3 as appropriate)
    - Scan project history via context scanner script (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
    - Break phase into tasks
-   - Determine plan grouping (single plan by default; multi-plan with user confirmation when enabled)
+   - Confirm task breakdown with user (single plan: confirm tasks; multi-plan: confirm tasks + grouping)
    - Discover relevant project skills, confirm with user
    - Hand off tasks + proposed grouping + confirmed skills to plan-writer subagent
    - Create PLAN.md file(s) with executable structure
 
 6. **Update last command:** `ms-tools set-last-command "ms:plan-phase $ARGUMENTS"`
 
-7. **Risk assessment**
-   - Calculate risk score from context already loaded (task count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains)
-   - Present score + top factors via AskUserQuestion
-   - Tier-based recommendation: Skip (0-39), Optional (40-69), Verify (70+)
-   - If user chooses verify: spawn ms-plan-checker, surface results
-   - If user chooses skip: proceed to next steps
+7. **Verify plans** — spawn ms-plan-checker to verify plans achieve phase goal. If issues found, present them and offer fix/execute-anyway/re-verify. Always runs — no skip option.
 </process>
 
 <success_criteria>
@@ -108,5 +103,6 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 - Must-Haves derived as markdown checklist of user-observable truths
 - Changes are specific enough for Claude to execute
 - EXECUTION-ORDER.md created with wave groups and dependencies
+- Plans verified by plan-checker (issues surfaced if any)
 - User knows next steps (execute plan or review/adjust)
   </success_criteria>

package/mindsystem/workflows/discuss-phase.md

@@ -125,11 +125,34 @@ Parse the requirements mapped to this phase from REQUIREMENTS.md and the phase d
 
 **Assess whether product research would add value:**
 
-Research is valuable when the phase involves user-facing product decisions where competitor context, UX patterns, or audience expectations would inform better choices. Examples: UI layouts, user flows, feature scope, interaction patterns.
+Product research is valuable when the phase involves user-facing product decisions where competitor context, UX patterns, or audience expectations would inform better choices. Examples: UI layouts, user flows, feature scope, interaction patterns.
 
-Research is NOT valuable for: backend infrastructure, data migrations, build tooling, refactoring, developer-facing work with no UX decisions.
+Product research is NOT valuable for: backend infrastructure, data migrations, build tooling, refactoring, developer-facing work with no UX decisions.
 
-**If research would add value:**
+**Assess whether constraint research would add value:**
+
+Constraint research is valuable when the phase integrates with an API the project doesn't fully control. Indicators (check PROJECT.md tech stack, ROADMAP.md phase description, REQUIREMENTS.md):
+- Tech stack includes proto/gRPC stubs, REST API client, third-party SDKs
+- Phase description mentions integration, API calls, backend sync, endpoints, webhooks
+- Requirements reference specific endpoints, data shapes, or backend operations
+- Project is frontend/client consuming a separate backend
+
+Constraint research is NOT valuable for: greenfield full-stack projects where you own the API, pure refactoring, internal tooling, backend-only work with no external API consumption.
+
+**Route based on assessment:**
+
+**Both product + constraint research valuable:**
+
+Use AskUserQuestion:
+- header: "Pre-discussion Research"
+- question: "This phase involves product decisions and API integration. Which research would help before we discuss?"
+- options:
+  - "Research both" — Investigate competitors/UX and API constraints (~45s)
+  - "Product research only" — Competitor and UX patterns (~30s)
+  - "Constraint research only" — API contract constraints (~20s)
+  - "Skip research" — Discuss based on what we know
+
+**Only product research valuable:**
 
 Use AskUserQuestion:
 - header: "Research"
@@ -138,9 +161,20 @@ Use AskUserQuestion:
   - "Research first" — Investigate competitors and UX patterns (~30s)
   - "Skip research" — Discuss based on what we know
 
-**If user selects "Research first":**
+**Only constraint research valuable:**
 
-Spawn ms-product-researcher subagent via Task tool:
+Use AskUserQuestion:
+- header: "Research"
+- question: "This phase integrates with an external API. Want me to research the contract constraints before we discuss?"
+- options:
+  - "Research contracts" — Investigate API constraints (~20s)
+  - "Skip research" — Discuss based on what we know
+
+**Neither valuable:** Continue silently.
+
+**Spawn research agents based on selection:**
+
+When product research selected, spawn ms-product-researcher via Task tool:
 
 ```
 <current_date>
@@ -160,9 +194,31 @@ Spawn ms-product-researcher subagent via Task tool:
 </research_focus>
 ```
 
+When constraint research selected, spawn ms-contract-researcher via Task tool:
+
+```
+<current_date>
+[Output of: date +%Y-%m]
+</current_date>
+
+<project_tech_stack>
+[Language, frameworks, API communication from PROJECT.md]
+</project_tech_stack>
+
+<phase_requirements>
+[Phase goal, description, mapped requirements from ROADMAP.md/REQUIREMENTS.md]
+</phase_requirements>
+
+<research_focus>
+[Specific integration questions for this phase — which endpoints, data shapes, operations?]
+</research_focus>
+```
+
+When both selected, spawn both agents via two Task calls in a single message (parallel).
+
 Store research findings for use in present_briefing and questioning steps.
 
-**If user selects "Skip research" or research not valuable:**
+**If user selects "Skip research" or neither research valuable:**
 Continue without research findings.
 </step>
 
@@ -183,6 +239,10 @@ Present a consolidated briefing that weaves together all loaded context.
 [If research findings available:]
 ### Industry Context
 [Key findings from product research — competitor patterns, UX conventions, audience expectations. Dense, prescriptive summary.]
+
+[If contract research findings available:]
+### API Constraints
+[Required fields, supported operations, value restrictions from contract research. Assumptions that could NOT be verified locally flagged for discussion.]
 ```
 
 Then use AskUserQuestion:
@@ -271,7 +331,7 @@ Populate template sections:
 - `<notes>`: Any other context gathered
 
 **Decision context (for downstream agents):**
-- `<decisions>`: Concrete choices made during discussion (locked). Include inline reasoning grounded in vision, audience, competitor patterns, or tradeoff analysis: `- [Decision] — [Why: reasoning]`
+- `<decisions>`: Concrete choices made during discussion (locked). Include inline reasoning grounded in vision, audience, competitor patterns, or tradeoff analysis: `- [Decision] — [Why: reasoning]`. When contract research produced findings, incorporate verified constraints as locked decisions with contract-based reasoning: `- [Decision] — Why: [contract source] marks [field] as REQUIRED at [file:line]`. Items from "Assumptions to Verify" go into `<notes>` as flagged open questions, not locked decisions.
 - `### Claude's Discretion`: Areas where user said "you decide" or didn't express preference
 - `<deferred>`: Ideas mentioned but explicitly out of scope
 

package/mindsystem/workflows/plan-phase.md

@@ -18,7 +18,7 @@ Decimal phases enable urgent work insertion without renumbering:
 1. .planning/ROADMAP.md
 2. .planning/PROJECT.md
 
-**Note:** Heavy references (phase-prompt.md, plan-format.md, scope-estimation.md, goal-backward.md, plan-risk-assessment.md) are loaded by the ms-plan-writer subagent, not main context. Lighter references (tdd.md) are loaded on demand during task breakdown.
+**Note:** Heavy references (phase-prompt.md, plan-format.md, scope-estimation.md, goal-backward.md) are loaded by the ms-plan-writer subagent, not main context. Lighter references (tdd.md) are loaded on demand during task breakdown.
 </required_reading>
 
 <purpose>
@@ -290,7 +290,15 @@ MULTI_PLAN=$(ms-tools config-get multi_plan --default "false")
 
 **If `false` (default) — single plan mode:**
 
-All tasks go into Plan 01, Wave 1. No dependency analysis, clustering, or budget estimation. No AskUserQuestion. Proceed directly to load_skills.
+All tasks go into Plan 01, Wave 1. No dependency analysis, clustering, or budget estimation.
+
+**Confirm task breakdown via AskUserQuestion:**
+- header: "Tasks Identified"
+- question: "Ready to write the plan with these tasks?"
+- Options: "Looks good, write the plan", "I want to adjust"
+
+**"Looks good, write the plan":** Proceed to load_skills.
+**"I want to adjust":** User describes changes in free-text. Apply adjustments, re-present tasks, and confirm again.
 
 **If `true` — multi-plan mode:**
 
@@ -437,7 +445,6 @@ The subagent handles:
 - Estimating scope (informational, for grouping rationale)
 - Writing PLAN.md files + EXECUTION-ORDER.md
 - Git commit
-- Calculating risk score
 </step>
 
 <step name="receive_results">
@@ -458,12 +465,6 @@ The ms-plan-writer returns structured markdown:
 | 1 | 01, 02 | None (parallel) |
 | 2 | 03 | Waits for 01, 02 |
 
-### Risk Assessment
-**Score:** 45/100 (optional)
-**Top Factors:**
-- CONTEXT.md with locked decisions
-- Complex domain (auth)
-
 ### Files Created
 - `.planning/phases/03-authentication/03-01-PLAN.md`
 - `.planning/phases/03-authentication/03-02-PLAN.md`
@@ -475,33 +476,14 @@ Extract:
 - `wave_count`: Number of waves
 - `wave_structure`: Wave-to-plan mapping
 - `grouping_rationale`: Optional table showing task weights and consolidation notes
-- `risk_score`: 0-100
-- `risk_tier`: "skip" | "optional" | "verify"
-- `risk_factors`: Top contributing factors
 - `plan_paths`: List of created PLAN.md files
 - `commit_hash`: Git commit reference
 </step>
 
-<step name="risk_decision">
-**Present risk score and handle user choice.**
-
-**Present via AskUserQuestion based on tier from subagent:**
-
-| Tier | Score | Default option | Message |
-|------|-------|----------------|---------|
-| Skip | 0-39 | "Skip verification" | "Low risk. Verification optional." |
-| Optional | 40-69 | "Verify plans" | "Moderate complexity. Verification recommended." |
-| Verify | 70-100 | "Verify plans (Recommended)" | "Higher complexity. Verification strongly recommended." |
-
-Include top risk factors for Optional/Verify tiers. Optional/Verify tiers also offer "Review plans manually".
-
-**Handle response:**
-
-**"Skip verification":**
-Continue to offer_next.
+<step name="verify_plans">
+**Always verify plans before offering next steps.**
 
-**"Verify plans":**
-Spawn ms-plan-checker:
+Spawn ms-plan-checker immediately after receiving plan-writer results:
 
 ```
 Task(
@@ -512,26 +494,25 @@ Verify plans for phase ${PHASE}.
 Phase directory: ${PHASE_DIR}
 
 1. Read .planning/ROADMAP.md for phase goal
-2. Read all *-PLAN.md files in ${PHASE_DIR}
-3. Read ${PHASE}-CONTEXT.md if exists (for dimension 7)
-4. Run all verification dimensions
-5. Return PASSED or ISSUES FOUND
+2. Read .planning/REQUIREMENTS.md for documented requirements mapped to this phase
+3. Read all *-PLAN.md files in ${PHASE_DIR}
+4. Read ${PHASE}-CONTEXT.md if exists (for dimensions 7 and 8)
+5. Run all verification dimensions
+6. Return PASSED or ISSUES FOUND
 """
 )
 ```
 
-If **PASSED:** Continue to offer_next with "Plans verified ✓"
+**If PASSED:** Continue to offer_next with "Plans verified" inline.
 
-If **ISSUES FOUND:** Present issues, then AskUserQuestion:
+**If ISSUES FOUND:** Present issues, then AskUserQuestion:
 - "Fix issues — I'll edit the plans"
 - "Execute anyway — proceed despite issues"
 - "Re-verify — check again after fixes"
 
-**"Review plans manually":**
-Show plan paths, wait for user response:
-- "looks good" / "proceed" → continue to offer_next
-- "run verification" → spawn ms-plan-checker
-- Describes changes → help edit plans
+**"Fix issues":** Help user edit plans, then re-spawn checker when user indicates fixes are complete.
+**"Execute anyway":** Continue to offer_next with warning note.
+**"Re-verify":** Re-spawn ms-plan-checker.
 </step>
 
 <step name="offer_next">
@@ -612,6 +593,6 @@ Phase planning complete when:
 - [ ] Task list + proposed grouping + skill context handed off to ms-plan-writer
 - [ ] PLAN files + EXECUTION-ORDER.md created (pure markdown, Must-Haves, follows proposed grouping)
 - [ ] Plans committed with maximized wave parallelism
-- [ ] Risk assessment presented and user decision captured (verify/skip)
+- [ ] Plans verified by plan-checker (issues surfaced if any)
 - [ ] User knows next steps and wave structure
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/mindsystem/references/plan-risk-assessment.md

@@ -1,258 +0,0 @@
-<plan_risk_assessment>
-Optional verification step for plan-phase workflow. Calculates risk score from already-loaded context and prompts user to verify or skip.
-
-<purpose>
-Provide lightweight risk assessment after plan creation to help users decide whether to run plan verification before execution.
-
-**Key principle:** All information is already in context from earlier workflow steps. No additional file reads or subagent spawns needed for scoring.
-</purpose>
-
-<skip_conditions>
-Skip risk assessment entirely when:
-- Zero plans created (error state)
-</skip_conditions>
-
-<risk_factors>
-
-## Factor Weights
-
-| Factor | Max Points | Source |
-|--------|-----------|--------|
-| Task count per plan (4+) | 15 | Plans just created |
-| Total plan count (5+) | 15 | Plans just created |
-| External services | 20 | user_setup in frontmatter |
-| CONTEXT.md exists | 10 | gather_phase_context step |
-| Cross-cutting concerns | 15 | Dependency graph analysis |
-| New dependencies | 15 | Task actions |
-| Complex domain keywords | 10 | Phase name/description |
-
-**Maximum score:** 100 points
-
-## Detection Logic
-
-**Task count per plan:**
-```
-max_tasks = max(task_count for each plan)
-if max_tasks >= 4:
-  score += 15
-  factors.append(f"Plan has {max_tasks} tasks")
-```
-
-**Total plan count:**
-```
-plan_count = number of PLAN.md files created
-if plan_count >= 5:
-  score += 15
-  factors.append(f"{plan_count} plans in phase")
-```
-
-**External services:**
-```
-services = extract from user_setup frontmatter
-# Common services: Stripe, SendGrid, Twilio, OpenAI, Supabase, Firebase, Auth0, etc.
-if services:
-  score += min(len(services) * 10, 20)
-  factors.append(f"External services: {', '.join(services)}")
-```
-
-**CONTEXT.md exists:**
-```
-if CONTEXT.md was loaded in gather_phase_context:
-  score += 10
-  factors.append("CONTEXT.md with locked decisions")
-```
-
-**Cross-cutting concerns:**
-```
-# Files that appear in multiple plans' files_modified
-shared_files = files appearing in 2+ plans
-if shared_files:
-  score += min(len(shared_files) * 5, 15)
-  factors.append("Cross-cutting concerns detected")
-```
-
-**New dependencies:**
-```
-# Count packages mentioned in task actions: "npm install X", "add X to package.json"
-new_deps = packages mentioned in task actions
-if new_deps:
-  score += min(len(new_deps) * 5, 15)
-  factors.append(f"{len(new_deps)} new dependencies")
-```
-
-**Complex domain keywords:**
-```
-complex_domains = ["auth", "authentication", "payment", "billing", "migration",
-                   "security", "encryption", "oauth", "webhook", "real-time",
-                   "websocket", "distributed", "caching", "queue"]
-
-phase_text = phase name + phase description (lowercase)
-if any(keyword in phase_text for keyword in complex_domains):
-  score += 10
-  factors.append("Complex domain (auth/payments/etc)")
-```
-
-</risk_factors>
-
-<thresholds>
-
-| Score | Tier | Recommendation |
-|-------|------|----------------|
-| 0-39 | skip | "Execute now" listed first |
-| 40-69 | optional | "Verify first" listed first |
-| 70-100 | verify | "Verify first (recommended)" listed first |
-
-**Threshold rationale:**
-- 0-39: Simple phases with few plans, no external services, no locked decisions
-- 40-69: Moderate complexity - verification helpful but not critical
-- 70-100: High complexity - multiple risk factors compound, verification strongly recommended
-
-</thresholds>
-
-<ask_user_question_formats>
-
-## Skip Tier (0-39)
-
-```
-header: "Plan Verification"
-question: "Risk Score: {score}/100 — Low risk
-
-Plans look straightforward. Verification optional."
-options:
-  - label: "Execute now"
-    description: "Skip verification, proceed to execution"
-  - label: "Verify anyway"
-    description: "Run plan checker before execution"
-```
-
-## Optional Tier (40-69)
-
-```
-header: "Plan Verification"
-question: "Risk Score: {score}/100 — Moderate complexity
-
-Top factors:
-- {factor_1}
-- {factor_2}
-
-Verification recommended but optional."
-options:
-  - label: "Verify first"
-    description: "Run plan checker before execution"
-  - label: "Execute now"
-    description: "Skip verification, proceed directly"
-  - label: "Review plans manually"
-    description: "I'll review plans myself first"
-```
-
-## Verify Tier (70-100)
-
-```
-header: "Plan Verification Recommended"
-question: "Risk Score: {score}/100 — Higher complexity
-
-Top factors:
-- {factor_1}
-- {factor_2}
-- {factor_3}
-
-Verification strongly recommended."
-options:
-  - label: "Verify first (Recommended)"
-    description: "Run plan checker before execution"
-  - label: "Execute anyway"
-    description: "Skip verification despite complexity"
-  - label: "Review plans manually"
-    description: "I'll review plans myself first"
-```
-
-</ask_user_question_formats>
-
-<checker_invocation>
-
-**When user chooses "Verify first":**
-
-Spawn ms-plan-checker subagent:
-
-```
-Task(
-  subagent_type: "ms-plan-checker"
-  description: "Verify phase {PHASE} plans"
-  prompt: """
-Verify plans for phase {PHASE}.
-Phase directory: {PHASE_DIR}
-
-1. Read .planning/ROADMAP.md for phase goal
-2. Read all *-PLAN.md files in {PHASE_DIR}
-3. Read {PHASE}-CONTEXT.md if exists (for dimension 7)
-4. Run all verification dimensions
-5. Return PASSED or ISSUES FOUND
-"""
-)
-```
-
-</checker_invocation>
-
-<result_handling>
-
-## If PASSED
-
-Continue to offer_next with verification status:
-
-```markdown
-Plans verified - All checks passed
-
-Phase {X} planned: {N} plan(s) in {M} wave(s)
-
-## Wave Structure
-...
-```
-
-## If ISSUES FOUND
-
-Present issues summary, then prompt:
-
-```
-header: "Verification Issues"
-question: "{blocker_count} blocker(s), {warning_count} warning(s) found.
-
-{issue_summary}
-
-How would you like to proceed?"
-options:
-  - label: "Fix issues"
-    description: "I'll edit the plans to address issues"
-  - label: "Execute anyway"
-    description: "Proceed despite issues"
-  - label: "Re-verify"
-    description: "Run checker again after fixes"
-```
-
-**If "Fix issues":** Return to editing - user will make changes and can re-run `/ms:plan-phase` or manually trigger verification.
-
-**If "Execute anyway":** Continue to offer_next with warning note.
-
-**If "Re-verify":** Re-spawn ms-plan-checker after user indicates fixes are complete.
-
-</result_handling>
-
-<manual_review_handling>
-
-**When user chooses "Review plans manually":**
-
-Show plan file paths and wait:
-
-```markdown
-## Plans to Review
-
-{list of plan paths}
-
-Review plans, then respond:
-- "looks good" or "proceed" → continue to next steps
-- "run verification" → spawn ms-plan-checker
-- describe changes → I'll help edit plans
-```
-
-</manual_review_handling>
-
-</plan_risk_assessment>