mindsystem-cc 3.18.0 → 3.18.1

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.18.0",
+  "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"

package/scripts/scan-planning-context.py

@@ -343,6 +343,7 @@ def scan_debug_docs(
         results.append(
             {
                 "path": str(path),
+                "slug": path.stem,
                 "subsystem": fm.get("subsystem", ""),
                 "root_cause": fm.get("root_cause", ""),
                 "resolution": fm.get("resolution", ""),
@@ -552,6 +553,145 @@ def aggregate_from_summaries(
     }
 
 
+# ---------------------------------------------------------------------------
+# Markdown formatting
+# ---------------------------------------------------------------------------
+
+
+def format_markdown(output: dict[str, Any]) -> str:
+    """Format scanner output as readable markdown for LLM consumption."""
+    sections: list[str] = []
+    agg = output.get("aggregated", {})
+
+    # --- Established Patterns ---
+    patterns = agg.get("patterns_established", [])
+    if patterns:
+        lines = ["### Established Patterns"]
+        lines.extend(f"- {p}" for p in patterns)
+        sections.append("\n".join(lines))
+
+    # --- Tech Stack ---
+    tech = agg.get("tech_stack_added", [])
+    if tech:
+        sections.append(f"### Tech Stack\n{', '.join(tech)}")
+
+    # --- Key Decisions ---
+    decisions = agg.get("key_decisions", [])
+    if decisions:
+        lines = ["### Key Decisions"]
+        lines.extend(f"- {d}" for d in decisions)
+        sections.append("\n".join(lines))
+
+    # --- Key Files ---
+    created = agg.get("key_files_created", [])
+    modified = agg.get("key_files_modified", [])
+    if created or modified:
+        lines = ["### Key Files"]
+        if created:
+            lines.append("**Created:**")
+            lines.extend(f"- `{f}`" for f in created)
+        if modified:
+            lines.append("**Modified:**")
+            lines.extend(f"- `{f}`" for f in modified)
+        sections.append("\n".join(lines))
+
+    # --- Debug Learnings ---
+    debug = output.get("debug_learnings", [])
+    if debug:
+        lines = ["### Debug Learnings"]
+        for d in debug:
+            slug = d.get("slug", "unknown")
+            sub = d.get("subsystem", "")
+            rc = d.get("root_cause", "")
+            res = d.get("resolution", "")
+            lines.append(f"- **{slug}** ({sub}): {rc} — Fix: {res}")
+        sections.append("\n".join(lines))
+
+    # --- Adhoc Learnings ---
+    adhoc_entries = [
+        a for a in output.get("adhoc_learnings", []) if a.get("learnings")
+    ]
+    if adhoc_entries:
+        lines = ["### Adhoc Learnings"]
+        for a in adhoc_entries:
+            sub = a.get("subsystem", "")
+            path = a.get("path", "")
+            label = sub or Path(path).stem if path else "unknown"
+            lines.append(f"- **{label}**")
+            for learning in a["learnings"]:
+                lines.append(f"  - {learning}")
+        sections.append("\n".join(lines))
+
+    # --- Summaries ---
+    summaries = output.get("summaries", [])
+    needs_read = [
+        s
+        for s in summaries
+        if s.get("relevance") == "HIGH" and s.get("has_readiness_warnings")
+    ]
+    other_relevant = [
+        s
+        for s in summaries
+        if s.get("relevance") in ("HIGH", "MEDIUM")
+        and not s.get("has_readiness_warnings")
+    ]
+
+    if needs_read:
+        lines = ["### Summaries Needing Full Read"]
+        for s in needs_read:
+            lines.append(f"- `{s['path']}`")
+        sections.append("\n".join(lines))
+
+    if other_relevant:
+        lines = ["### Other Relevant Summaries"]
+        for s in other_relevant:
+            lines.append(f"- `{s['path']}` [{s.get('relevance', '')}]")
+        sections.append("\n".join(lines))
+
+    # --- Knowledge Files ---
+    matched_knowledge = [
+        k for k in output.get("knowledge_files", []) if k.get("matched")
+    ]
+    if matched_knowledge:
+        lines = ["### Knowledge Files to Read"]
+        for k in matched_knowledge:
+            lines.append(f"- `{k['path']}`")
+        sections.append("\n".join(lines))
+
+    # --- Pending Todos ---
+    todos = output.get("pending_todos", [])
+    if todos:
+        lines = ["### Pending Todos"]
+        for t in todos:
+            title = t.get("title", "untitled")
+            priority = t.get("priority", "")
+            sub = t.get("subsystem", "")
+            path = t.get("path", "")
+            lines.append(f"- **{title}** [{priority}] ({sub}) — `{path}`")
+        sections.append("\n".join(lines))
+
+    # --- Scanner Info ---
+    sources = output.get("sources", {})
+    parse_errors = sources.get("parse_errors", [])
+    info_lines = ["### Scanner Info"]
+    for name, src in sources.items():
+        if name == "parse_errors" or not isinstance(src, dict):
+            continue
+        scanned = src.get("scanned", 0)
+        skipped = src.get("skipped")
+        if skipped:
+            info_lines.append(f"- {name}: skipped ({skipped})")
+        else:
+            info_lines.append(f"- {name}: {scanned} scanned")
+    if parse_errors:
+        info_lines.append("**Parse errors:**")
+        for err in parse_errors:
+            info_lines.append(f"- `{err.get('path', '')}`: {err.get('error', '')}")
+    sections.append("\n".join(info_lines))
+
+    return "\n\n".join(sections)
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -583,6 +723,11 @@ def build_parser() -> argparse.ArgumentParser:
         default="",
         help="Comma-separated keywords for tag matching",
     )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output raw JSON (default: formatted markdown)",
+    )
     return parser
 
 
@@ -604,40 +749,42 @@ def main() -> None:
 
     planning = find_planning_dir()
     if planning is None:
-        # No .planning/ directory — output valid JSON with all sources skipped
-        output: dict[str, Any] = {
-            "success": True,
-            "target": {
-                "phase": phase,
-                "phase_name": phase_name,
-                "subsystems": subsystems,
-                "keywords": keywords,
-            },
-            "sources": {
-                "summaries": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "debug_docs": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "adhoc_summaries": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "completed_todos": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "pending_todos": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "knowledge_files": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
-                "parse_errors": [],
-            },
-            "summaries": [],
-            "debug_learnings": [],
-            "adhoc_learnings": [],
-            "completed_todos": [],
-            "pending_todos": [],
-            "knowledge_files": [],
-            "aggregated": {
-                "tech_stack_added": [],
-                "patterns_established": [],
-                "key_files_created": [],
-                "key_files_modified": [],
-                "key_decisions": [],
-            },
-        }
-        json.dump(output, sys.stdout, indent=2, cls=_SafeEncoder)
-        sys.stdout.write("\n")
+        if args.json:
+            output: dict[str, Any] = {
+                "success": True,
+                "target": {
+                    "phase": phase,
+                    "phase_name": phase_name,
+                    "subsystems": subsystems,
+                    "keywords": keywords,
+                },
+                "sources": {
+                    "summaries": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "debug_docs": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "adhoc_summaries": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "completed_todos": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "pending_todos": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "knowledge_files": {"dir": "", "scanned": 0, "skipped": ".planning/ not found"},
+                    "parse_errors": [],
+                },
+                "summaries": [],
+                "debug_learnings": [],
+                "adhoc_learnings": [],
+                "completed_todos": [],
+                "pending_todos": [],
+                "knowledge_files": [],
+                "aggregated": {
+                    "tech_stack_added": [],
+                    "patterns_established": [],
+                    "key_files_created": [],
+                    "key_files_modified": [],
+                    "key_decisions": [],
+                },
+            }
+            json.dump(output, sys.stdout, indent=2, cls=_SafeEncoder)
+            sys.stdout.write("\n")
+        else:
+            print("No .planning/ directory found. No prior context available.")
         return
 
     parse_errors: list[dict[str, str]] = []
@@ -681,8 +828,11 @@ def main() -> None:
         "aggregated": aggregated,
     }
 
-    json.dump(output, sys.stdout, indent=2, cls=_SafeEncoder)
-    sys.stdout.write("\n")
+    if args.json:
+        json.dump(output, sys.stdout, indent=2, cls=_SafeEncoder)
+        sys.stdout.write("\n")
+    else:
+        print(format_markdown(output))
 
 
 if __name__ == "__main__":