mindsystem-cc 3.17.1 → 3.18.1

package/mindsystem/templates/research.md

@@ -72,7 +72,7 @@ src/
 **When to use:** [conditions]
 **Example:**
 ```typescript
-// [code example from Context7/official docs]
+// [code example from official docs]
 ```
 
 ### Pattern 2: [Pattern Name]
@@ -131,19 +131,19 @@ Verified patterns from official sources:
 
 ### [Common Operation 1]
 ```typescript
-// Source: [Context7/official docs URL]
+// Source: [official docs URL]
 [code]
 ```
 
 ### [Common Operation 2]
 ```typescript
-// Source: [Context7/official docs URL]
+// Source: [official docs URL]
 [code]
 ```
 
 ### [Common Operation 3]
 ```typescript
-// Source: [Context7/official docs URL]
+// Source: [official docs URL]
 [code]
 ```
 </code_examples>
@@ -185,7 +185,7 @@ Things that couldn't be fully resolved:
 ## Sources
 
 ### Primary (HIGH confidence)
-- [Context7 library ID] - [topics fetched]
+- [ms-lookup docs library] - [topics fetched]
 - [Official docs URL] - [what was checked]
 
 ### Secondary (MEDIUM confidence)
@@ -479,10 +479,10 @@ function useVehicleControls(rigidBodyRef) {
 - Pitfalls: Performance, physics, feel
 
 **Confidence breakdown:**
-- Standard stack: HIGH - verified with Context7, widely used
+- Standard stack: HIGH - verified with ms-lookup docs, widely used
 - Architecture: HIGH - from official examples
 - Pitfalls: HIGH - documented in discourse, verified in docs
-- Code examples: HIGH - from Context7/official sources
+- Code examples: HIGH - from ms-lookup docs/official sources
 
 **Research date:** 2026-01-20
 **Valid until:** 2026-02-20 (30 days - R3F ecosystem stable)

package/mindsystem/templates/roadmap.md

@@ -123,7 +123,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **Initial planning (v1.0):**
 - Phase count derived from actual work (not a target number)
 - Each phase delivers something coherent
-- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Phases can have 1+ plans (split if budget exceeds 45% or multiple subsystems)
 - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
 - No time estimates (this isn't enterprise PM)
 - Progress table updated by execute workflow

package/mindsystem/templates/verification-report.md

@@ -180,7 +180,7 @@ None — all verifiable items checked programmatically.
 **Fix plan generation:**
 - Only generate if gaps_found
 - Group related fixes into single plans
-- Keep to 2-3 tasks per plan
+- Budget-based grouping (weights within 45%)
 - Include verification task in each plan
 
 ---

package/mindsystem/workflows/complete-milestone.md

@@ -1,8 +1,6 @@
 <purpose>
 
-Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
-
-This is the ritual that separates "development" from "shipped."
+Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, archives ROADMAP.md and REQUIREMENTS.md, and tags the release in git.
 
 </purpose>
 
@@ -22,25 +20,14 @@ This is the ritual that separates "development" from "shipped."
 
 When a milestone completes, this workflow:
 
-1. Cleans up raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER deleted)
-2. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
-3. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
-4. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
-5. Archives milestone context to `.planning/milestones/v[X.Y]/CONTEXT.md`
-6. Archives research files to `.planning/milestones/v[X.Y]/research/` (if exists)
-7. Updates ROADMAP.md to replace milestone details with one-line summary
-8. Deletes REQUIREMENTS.md (fresh one created for next milestone)
-9. Performs full PROJECT.md evolution review
-10. Routes to `/ms:new-milestone` for next milestone
-
-Knowledge files in `.planning/knowledge/` persist across milestones (maintained by phase-level consolidation in execute-phase).
-
-**Context Efficiency:**
-
-- Completed milestones: One line each (~50 tokens)
-- Full details: In archive files (loaded only when needed)
-- Result: ROADMAP.md stays constant size forever
-- Result: REQUIREMENTS.md is always milestone-scoped (not cumulative)
+1. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
+2. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
+3. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+4. Archives milestone files via script (audit, context, research — whichever exist)
+5. Consolidates phase summaries, deletes artifacts, moves phase dirs via script
+6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+7. Performs full PROJECT.md evolution review
+8. Routes to `/ms:new-milestone` for next milestone
 
 **Archive Format:**
 
@@ -49,6 +36,10 @@ Knowledge files in `.planning/knowledge/` persist across milestones (maintained
 - Full phase details from roadmap
 - Milestone summary (decisions, issues, technical debt)
 
+**PHASE-SUMMARIES** consolidates all `*-SUMMARY.md` files from phase directories, organized by phase and plan, before artifacts are deleted.
+
+**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`) moved from `.planning/phases/`.
+
 **REQUIREMENTS archive** contains:
 - All v1 requirements marked complete with outcomes
 - Traceability table with final status
@@ -60,32 +51,10 @@ Knowledge files in `.planning/knowledge/` persist across milestones (maintained
 
 <step name="verify_readiness">
 
-Check if milestone is truly complete:
+Read roadmap to determine milestone phase range (`PHASE_START`, `PHASE_END`) for the stats script:
 
 ```bash
 cat .planning/ROADMAP.md
-ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
-```
-
-**Questions to ask:**
-
-- Which phases belong to this milestone?
-- Are all those phases complete (all plans have summaries)?
-- Has the work been tested/validated?
-- Is this ready to ship/tag?
-
-Present:
-
-```
-Milestone: [Name from user, e.g., "v1.0 MVP"]
-
-Appears to include:
-- Phase 1: Foundation (2/2 plans complete)
-- Phase 2: Authentication (2/2 plans complete)
-- Phase 3: Core Features (3/3 plans complete)
-- Phase 4: Polish (1/1 plan complete)
-
-Total: 4 phases, 8 plans, all complete
 ```
 
 <config-check>
@@ -96,74 +65,30 @@ cat .planning/config.json 2>/dev/null
 
 </config-check>
 
-```
-⚡ Auto-approved: Milestone scope verification
-
-[Show breakdown summary without prompting]
-
-Proceeding to stats gathering...
-```
-
-Proceed directly to cleanup_artifacts step.
-
-</step>
-
-<step name="cleanup_artifacts">
-
-Delete remaining raw artifacts from phase directories. Knowledge files are already current from phase-level consolidation in execute-phase — no consolidation or learnings extraction needed.
+Run the stats script to get readiness status and git statistics:
 
 ```bash
-~/.claude/mindsystem/scripts/cleanup-phase-artifacts.sh $PHASE_START $PHASE_END
+~/.claude/mindsystem/scripts/gather-milestone-stats.sh $PHASE_START $PHASE_END
 ```
 
-Knowledge files in `.planning/knowledge/` persist (they ARE the milestone's knowledge output).
-
-**Present cleanup summary:**
-
-```
-Raw artifacts cleaned from phase directories
-Knowledge files persist in .planning/knowledge/
-```
-
-Continue to gather_stats step.
-
-</step>
+The script outputs:
+- **Readiness:** Phase/plan counts, completeness, list of incomplete plans
+- **Git Stats:** Commit range, timeline, diff stats
 
-<step name="gather_stats">
+If status is NOT READY, stop and report which plans are incomplete.
 
-Calculate milestone statistics:
+If status is READY, present the combined output:
 
-```bash
-# Count phases and plans in milestone
-# (user specified or detected from roadmap)
-
-# Find git range
-git log --oneline --grep="feat(" | head -20
-
-# Count files modified in range
-git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
-
-# Count LOC (adapt to language)
-find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
-
-# Calculate timeline
-git log --format="%ai" FIRST_COMMIT | tail -1  # Start date
-git log --format="%ai" LAST_COMMIT | head -1   # End date
 ```
+⚡ Auto-approved: Milestone scope verification
 
-Present summary:
-
-```
-Milestone Stats:
-- Phases: [X-Y]
-- Plans: [Z] total
-- Tasks: [N] total (estimated from phase summaries)
-- Files modified: [M]
-- Lines of code: [LOC] [language]
-- Timeline: [Days] days ([Start] → [End])
-- Git range: feat(XX-XX) → feat(YY-YY)
+Milestone: [Name from ROADMAP.md]
+[Script readiness output — phases, plans, completeness]
+[Script git stats — range, timeline, changes]
 ```
 
+Proceed directly to extract_accomplishments step.
+
 </step>
 
 <step name="extract_accomplishments">
@@ -378,52 +303,6 @@ Initial user testing showed demand for shape tools.
 
 </step>
 
-<step name="reorganize_roadmap">
-
-Update `.planning/ROADMAP.md` to group completed milestone phases.
-
-Add milestone headers and collapse completed work:
-
-```markdown
-# Roadmap: [Project Name]
-
-## Milestones
-
-- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
-- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
-
-## Phases
-
-<details>
-<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
-
-- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
-- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
-- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
-- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
-
-</details>
-
-### 🚧 v[Next] [Name] (In Progress / Planned)
-
-- [ ] Phase 5: [Name] ([N] plans)
-- [ ] Phase 6: [Name] ([N] plans)
-
-## Progress
-
-| Phase             | Milestone | Plans Complete | Status      | Completed  |
-| ----------------- | --------- | -------------- | ----------- | ---------- |
-| 1. Foundation     | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
-| 2. Authentication | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
-| 3. Core Features  | v1.0      | 3/3            | Complete    | YYYY-MM-DD |
-| 4. Polish         | v1.0      | 1/1            | Complete    | YYYY-MM-DD |
-| 5. Security Audit | v1.1      | 0/1            | Not started | -          |
-| 6. Hardening      | v1.1      | 0/2            | Not started | -          |
-```
-
-</step>
-
 <step name="archive_milestone">
 
 Extract completed milestone details and create archive file.
@@ -478,7 +357,7 @@ Extract completed milestone details and create archive file.
    ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
-**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+**Note:** Phase directories are moved to `milestones/v[X.Y]/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
 
 </step>
 
@@ -545,55 +424,43 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 </step>
 
-<step name="archive_audit">
+<step name="archive_milestone_files">
 
-Move the milestone audit file to the archive (if it exists):
+Archive optional milestone files (audit, context, research) to the milestone directory:
 
 ```bash
-# Move audit to milestone folder (if exists)
-[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/v[X.Y]/MILESTONE-AUDIT.md
+~/.claude/mindsystem/scripts/archive-milestone-files.sh v[X.Y]
 ```
 
-Confirm:
-```
-✅ Audit archived to milestones/v[X.Y]/MILESTONE-AUDIT.md
-```
-
-(Skip silently if no audit file exists — audit is optional)
+The script moves whichever files exist and reports what was archived. Files that don't exist are skipped silently.
 
 </step>
 
-<step name="archive_context">
+<step name="archive_and_cleanup_phases">
 
-Archive the milestone context file (if it exists):
+Consolidate phase summaries, delete raw artifacts, and move phase directories to the milestone archive. This runs after all steps that read summaries (extract_accomplishments, evolve_project_full_review) and after archive_milestone creates the milestone directory.
 
 ```bash
-[ -f .planning/MILESTONE-CONTEXT.md ] && mv .planning/MILESTONE-CONTEXT.md .planning/milestones/v[X.Y]/CONTEXT.md
-```
-
-If archived:
-```
-✅ Context archived to milestones/v[X.Y]/CONTEXT.md
+~/.claude/mindsystem/scripts/archive-milestone-phases.sh $PHASE_START $PHASE_END v[X.Y]
 ```
 
-(Skip silently if no context file exists)
-
-</step>
-
-<step name="archive_research">
-
-Archive research files to milestone (if research directory exists):
+Verify archive:
 
 ```bash
-[ -d .planning/research ] && mv .planning/research .planning/milestones/v[X.Y]/research
+ls .planning/milestones/v[X.Y]/PHASE-SUMMARIES.md
+ls .planning/milestones/v[X.Y]/phases/
 ```
 
-If archived:
+Present:
+
 ```
-✅ Research archived to milestones/v[X.Y]/research/
+✅ Phase summaries consolidated to milestones/v[X.Y]/PHASE-SUMMARIES.md
+✅ Raw artifacts deleted from phase directories
+✅ Phase directories moved to milestones/v[X.Y]/phases/
+✅ .planning/phases/ clean for next milestone
 ```
 
-(Skip silently if no research directory exists)
+Knowledge files in `.planning/knowledge/` persist (they ARE the milestone's knowledge output).
 
 </step>
 
@@ -686,12 +553,15 @@ chore: complete v[X.Y] milestone
 Archived to milestones/v[X.Y]/:
 - ROADMAP.md
 - REQUIREMENTS.md
+- PHASE-SUMMARIES.md (consolidated from phase directories)
+- phases/ (phase directories moved from .planning/phases/)
 - MILESTONE-AUDIT.md (if audit was run)
 - CONTEXT.md (if milestone context existed)
 - research/ (if research existed)
 
 Cleaned:
-- Raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- Raw phase artifacts deleted (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- Phase directories moved to milestone archive
 - Knowledge files persist in .planning/knowledge/
 
 Deleted (fresh for next milestone):
@@ -752,62 +622,17 @@ Tag: v[X.Y]
 
 </process>
 
-<milestone_naming>
-
-**Version conventions:**
-- **v1.0** — Initial MVP
-- **v1.1, v1.2, v1.3** — Minor updates, new features, fixes
-- **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction
-
-**Name conventions:**
-- v1.0 MVP
-- v1.1 Security
-- v1.2 Performance
-- v2.0 Redesign
-- v2.0 iOS Launch
-
-Keep names short (1-2 words describing the focus).
-
-</milestone_naming>
-
-<what_qualifies>
-
-**Create milestones for:**
-- Initial release (v1.0)
-- Public releases
-- Major feature sets shipped
-- Before archiving planning
-
-**Don't create milestones for:**
-- Every phase completion (too granular)
-- Work in progress (wait until shipped)
-- Internal dev iterations (unless truly shipped internally)
-
-If uncertain, ask: "Is this deployed/usable/shipped in some form?"
-If yes → milestone. If no → keep working.
-
-</what_qualifies>
-
 <success_criteria>
 
-Milestone completion is successful when:
+Milestone completion is successful when (ordered by skip risk):
 
-- [ ] Raw artifacts cleaned from phase directories (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
-- [ ] Knowledge files persist in .planning/knowledge/
-- [ ] MILESTONES.md entry created with stats and accomplishments
-- [ ] PROJECT.md full evolution review completed
+- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, Requirements, Key Decisions, Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
-- [ ] ROADMAP.md reorganized with milestone grouping
-- [ ] Milestone directory created (milestones/v[X.Y]/)
+- [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
 - [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
-- [ ] Research archived to milestone (milestones/v[X.Y]/research/) if .planning/research/ existed
 - [ ] REQUIREMENTS.md deleted (fresh for next milestone)
 - [ ] STATE.md updated with fresh project reference
-- [ ] Git tag created (v[X.Y])
-- [ ] Milestone commit made (includes archive files and deletion)
-- [ ] Context archive created if MILESTONE-CONTEXT.md existed
-- [ ] User knows next steps (starting with /ms:new-milestone)
 
 </success_criteria>

package/mindsystem/workflows/discuss-phase.md

@@ -133,10 +133,10 @@ Based on their response, use AskUserQuestion:
 
 **3. Sharpen the core:**
 
-Use AskUserQuestion:
+Use AskUserQuestion with multiSelect: true:
 - header: "Essential"
-- question: "What's the most important part of this phase?"
-- options: Key aspects they've mentioned + "All equally important" + "Something else"
+- question: "What's most important to nail in this phase? Select all that apply."
+- options: Key aspects they've mentioned
 
 **4. Capture specifics (optional):**
 

package/mindsystem/workflows/execute-plan.md

@@ -38,7 +38,7 @@ Parse plan sections:
 
 **If plan references CONTEXT.md:** The CONTEXT.md file provides the user's vision for this phase — how they imagine it working, what's essential, and what's out of scope. Honor this context throughout execution.
 
-**If plan references DESIGN.md:** The DESIGN.md provides visual/UX specifications — exact colors (hex), spacing (px), component states, and layouts. Use exact values from the spec, implement all component states, match wireframe layouts, include DESIGN.md verification criteria in task verification.
+**If plan references DESIGN.md:** The DESIGN.md provides visual/UX specifications — Design Tokens table (hex colors, px spacing, font weights), inline wireframe annotations, per-screen States tables, Behavior notes, and Hints. Use exact token values, match wireframe layouts, implement all states. Derive verification criteria from token values, states, and behavior specs.
 
 **If `**Type:** tdd`:** Read `~/.claude/mindsystem/references/tdd-execution.md` for RED-GREEN-REFACTOR execution flow.
 </step>

package/mindsystem/workflows/plan-phase.md

@@ -283,49 +283,15 @@ uv run ~/.claude/mindsystem/scripts/scan-planning-context.py \
   ${SUBSYSTEM:+--subsystem "${SUBSYSTEM}"}
 ```
 
-**3. Parse JSON output.** Check `success` field. If the script fails or returns non-JSON, fall back to manual scanning (read SUMMARY frontmatter with sed as before). The scanner handles missing directories gracefully — check `sources.*.skipped` for skip reasons.
+The scanner outputs formatted markdown with sections for patterns, learnings,
+summaries, knowledge files, and pending todos. Each section is omitted if empty.
+If the script fails, fall back to manual scanning.
 
-**4. Present established patterns to user:**
+**3. Conditionally read full summaries** — from "Summaries Needing Full Read" section, read each file. For "Other Relevant Summaries", read full body only if frontmatter context isn't sufficient (judgment).
 
-From `aggregated.patterns_established`, display:
+**4. Read knowledge files** — from "Knowledge Files to Read" section, read each file.
 
-```
-### Established Patterns to Maintain
-- [Pattern: description] (from phase XX)
-```
-
-If empty, skip.
-
-**5. Conditionally read full summaries.**
-
-Read full SUMMARY.md body ONLY for summaries where:
-- `relevance` is HIGH AND `has_readiness_warnings` is true
-- OR frontmatter alone doesn't provide enough context for task breakdown (use judgment)
-
-Extract from full reads: "Next Phase Readiness" warnings, "Issues Encountered", detailed accomplishments.
-
-Summaries scored MEDIUM or HIGH without readiness warnings → frontmatter data in JSON is sufficient (tech stack, patterns, key files, decisions already aggregated).
-
-**6. Present matched learnings:**
-
-**From `debug_learnings`** — present as warnings:
-
-```
-### Previous Debug Sessions in This Area
-- **{slug}** ({subsystem}): {root_cause} — Fix: {resolution}
-```
-
-**From `adhoc_learnings`** — extract entries with non-empty `learnings` arrays for handoff context.
-
-If neither source has matches, skip.
-
-**7. Read knowledge files:**
-
-For each entry in `knowledge_files` where `matched` is true, read the full file. Knowledge files are prose (no frontmatter) so the LLM must read them to extract decisions, architecture, pitfalls.
-
-**8. Assess pending todos:**
-
-From `pending_todos` frontmatter in JSON, assess each todo's relevance. Read full body only for todos matching current phase subsystem/tags.
+**5. Assess pending todos** — from "Pending Todos" section, assess relevance. Read full body for relevant ones.
 
 **From STATE.md:** Decisions → constrain approach. Pending todos → candidates. Blockers → may need to address.
 
@@ -337,13 +303,13 @@ From `pending_todos` frontmatter in JSON, assess each todo's relevance. Read ful
 
 **Track for handoff to ms-plan-writer:**
 - Which summaries were selected (for @context references)
-- Tech stack available (from `aggregated.tech_stack_added`)
-- Established patterns (from `aggregated.patterns_established`)
-- Key files to reference (from `aggregated.key_files_created` + `key_files_modified`)
-- Applicable decisions (from `aggregated.key_decisions` + full summary reads)
+- Tech stack available (from formatted output)
+- Established patterns (from formatted output)
+- Key files to reference (from formatted output)
+- Applicable decisions (from formatted output + full summary reads)
 - Todos being addressed (from pending todos)
 - Concerns being verified (from "Next Phase Readiness" in full reads)
-- Matched learnings (from `debug_learnings`, `adhoc_learnings`, patterns, knowledge files)
+- Matched learnings (from formatted output + knowledge files)
 </step>
 
 <step name="gather_phase_context">
@@ -376,10 +342,10 @@ cat .planning/phases/XX-name/${PHASE}-DESIGN.md 2>/dev/null
 **If CONTEXT.md exists:** Honor vision, prioritize essential, respect boundaries, incorporate specifics. Track that CONTEXT.md exists for risk scoring.
 
 **If DESIGN.md exists:**
-- Tasks reference specific screens/components from design
-- Verification criteria include design verification items
+- Tasks reference specific screens from design (wireframe + states + behavior + hints)
+- Verification criteria inferred from States tables, Behavior notes, and token values
 - Must-Haves include design-specified observable behaviors
-- Task actions specify exact values (colors, spacing) from design
+- Task actions specify exact values (colors, spacing) from Design Tokens table
 
 **If none exist:** Suggest /ms:research-phase for niche domains, /ms:discuss-phase for simpler domains, or proceed with roadmap only.
 </step>
@@ -517,7 +483,7 @@ Task(
 The subagent handles:
 - Building dependency graph from needs/creates
 - Assigning wave numbers
-- Grouping tasks into plans (2-3 changes per plan)
+- Grouping tasks into plans (budget-based, ~45% cost target)
 - Deriving Must-Haves (goal-backward)
 - Estimating scope, splitting if needed
 - Writing PLAN.md files + EXECUTION-ORDER.md
@@ -559,6 +525,7 @@ Extract:
 - `plan_count`: Number of plans created
 - `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
@@ -636,6 +603,11 @@ Wave 1 (parallel): {plan-01}, {plan-02}
 Wave 2: {plan-03}
 ...
 
+{If grouping_rationale present, insert here:}
+
+## Grouping Notes
+{grouping_rationale table from plan-writer}
+
 ---
 
 ## Next Up
@@ -690,7 +662,7 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] PLAN file(s) created with pure markdown format
 - [ ] EXECUTION-ORDER.md created with wave groups
 - [ ] Each plan: Must-Haves section with observable truths
-- [ ] Each plan: 2-3 changes (~50% context)
+- [ ] Each plan: budget-based grouping (target 25-45%, consolidate under 10%)
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git
 - [ ] Risk assessment presented (score + top factors)

package/mindsystem/workflows/verify-phase.md

@@ -532,7 +532,7 @@ Group related gaps into fix plans:
 ```
 
 3. **Keep plans focused:**
-   - 2-3 tasks per plan
+   - Budget-based grouping (weights within 45%)
    - Single concern per plan
    - Include verification task
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.17.1",
+  "version": "3.18.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"