mindsystem-cc 3.22.1 → 4.0.0

package/mindsystem/workflows/compound.md

@@ -0,0 +1,121 @@
+<purpose>
+Compound code changes into per-subsystem knowledge files on demand. Handles work done outside the Mindsystem pipeline — direct Claude Code sessions, manual edits, merged branches.
+</purpose>
+
+<process>
+
+<step name="parse_input" priority="first">
+Parse `$ARGUMENTS` to determine input mode:
+
+```bash
+# Validate active project
+if [ ! -f .planning/config.json ]; then
+  echo "ERROR: No active Mindsystem project found (.planning/config.json missing)"
+  echo ""
+  echo "Options:"
+  echo "- Initialize project: /ms:new-project"
+  exit 1
+fi
+```
+
+**Mode detection:**
+- If `$ARGUMENTS` empty: **description mode** — deduce from conversation context. Summarize what was discussed/changed in the current session.
+- If matches git SHA pattern (7-40 hex chars), contains `..`, or starts with `HEAD`: **git mode**
+- If matches existing file path (`test -e "$ARGUMENTS"`): **file mode**
+- Otherwise: **description mode** — treat `$ARGUMENTS` as free-text description
+</step>
+
+<step name="resolve_change_context">
+Gather lightweight change context based on input mode. Keep main context lean — only stats and summaries.
+
+**Git mode:**
+```bash
+# Stats only — full diff read by compounder
+git show --stat <ref>        # single commit
+git diff --stat <range>      # range
+```
+Capture the ref/range string for passing to compounder.
+
+**File mode:**
+```bash
+git log --oneline -5 -- <path>
+```
+Capture file path for passing to compounder.
+
+**Description mode (including no-args):**
+Spawn 1 Explore agent to find relevant code changes. If changes span multiple unrelated areas, spawn a second agent for the additional area. They return:
+- Which files changed or are relevant
+- Which subsystems are likely affected
+- Concise summary of changes
+
+Thoroughness: "medium".
+</step>
+
+<step name="determine_subsystems">
+Read config.json subsystems and match changes:
+
+```bash
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+```
+
+**Git/file mode:** Match file paths from diff stats against subsystem names via keyword matching.
+
+**Description mode:** Use Explore agent findings for subsystem matching.
+
+**Detect potential new subsystems:** Changes in file areas that don't match any existing subsystem.
+
+**First-run handling:** If no subsystems in config.json and no knowledge files exist, propose a subsystem name derived from the project domain.
+</step>
+
+<step name="confirm_with_user">
+Present findings and confirm before spawning compounder:
+
+- Affected subsystems list
+- Proposed new subsystems (if any)
+- Change summary (1-3 lines)
+
+AskUserQuestion: "Compound knowledge for these subsystems?" with options:
+- Confirm
+- Adjust (let me modify the list)
+- Cancel
+</step>
+
+<step name="spawn_compounder">
+Spawn ms-compounder via Task tool with:
+- Input mode (`git`, `file`, or `description`)
+- Change reference (git ref/range, file path, or description + exploration findings)
+- Confirmed affected subsystems list
+- Config.json subsystem vocabulary
+
+Agent reads changes, reads affected knowledge files, writes updates, returns report.
+</step>
+
+<step name="finalize">
+**Update config.json** (if new subsystems were confirmed in step 4):
+```bash
+# Add new subsystem to config.json
+jq '.subsystems += ["new-subsystem"]' .planning/config.json > tmp.$$.json && mv tmp.$$.json .planning/config.json
+```
+
+**Commit changes:**
+```bash
+git add .planning/knowledge/*.md
+# Only add config.json if modified
+git add .planning/config.json 2>/dev/null
+git commit -m "$(cat <<'EOF'
+docs: compound knowledge from <description>
+EOF
+)"
+```
+
+**Set last command:**
+```bash
+ms-tools set-last-command "ms:compound $ARGUMENTS"
+```
+
+**Report:** Subsystems updated, entries added/changed/removed, new subsystems created (if any).
+</step>
+
+All three finalize actions (commit, set-last-command, report) must execute — do not stop after the compounder returns.
+
+</process>

package/mindsystem/workflows/doctor-fixes.md

@@ -56,7 +56,7 @@ git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
 git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
 git add .planning/debug/*.md 2>/dev/null
 git add .planning/debug/resolved/*.md 2>/dev/null
-git add .planning/todos/pending/*.md 2>/dev/null
+git add .planning/todos/*.md 2>/dev/null
 git add .planning/todos/done/*.md 2>/dev/null
 ```
 

package/mindsystem/workflows/plan-phase.md

@@ -51,7 +51,7 @@ PLAN.md IS the prompt that Claude executes. Plans are grouped into execution wav
 Read `.planning/STATE.md` and parse:
 - Current position (which phase we're planning)
 - Accumulated decisions (constraints on this phase)
-- Pending todos (candidates for inclusion)
+- Pending todos from `.planning/todos/` (candidates for inclusion)
 - Blockers/concerns (things this phase may address)
 - Brief alignment status
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.22.1",
+  "version": "4.0.0",
   "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/fixtures/scan-context/.planning/adhoc/20260225-refactor-api/adhoc-01-SUMMARY.md

@@ -0,0 +1,39 @@
+---
+phase: adhoc
+plan: "01"
+subsystem: api
+tags: [rest, endpoints, refactor]
+
+key-decisions:
+  - "Consolidated duplicate route handlers into shared utility"
+  - "Adopted consistent error response format across endpoints"
+
+patterns-established:
+  - "Shared route handler pattern for CRUD operations"
+
+key-files:
+  created:
+    - src/lib/route-utils.ts
+  modified:
+    - src/api/users/route.ts
+    - src/api/products/route.ts
+
+duration: 15min
+completed: 2026-02-25
+---
+
+# Adhoc Plan 01: Refactor API Route Handlers Summary
+
+**Consolidated duplicate CRUD logic into shared route utilities**
+
+## Performance
+- **Duration:** 15min
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Extracted shared CRUD handler from duplicate code in user and product routes
+- Standardized error response format
+
+## Decisions Made
+- Used generic handler factory pattern over middleware approach for type safety

package/scripts/fixtures/scan-context/.planning/todos/{pending/add-logout.md → add-logout.md}

@@ -1,8 +1,8 @@
 ---
 title: Add logout endpoint
 subsystem: auth
-priority: medium
-phase_origin: "05-auth"
+priority: 3
+estimate: S
 ---
 
 # Add Logout Endpoint

package/scripts/fixtures/scan-context/.planning/todos/done/setup-db.md

@@ -1,8 +1,8 @@
 ---
 title: Set up database migrations
 subsystem: database
-priority: high
-phase_origin: "02-infra"
+priority: 2
+estimate: M
 ---
 
 # Set Up Database Migrations

package/scripts/fixtures/scan-context/expected-output.json

@@ -24,7 +24,7 @@
     },
     "adhoc_summaries": {
       "dir": "<FIXTURE>/.planning/adhoc",
-      "scanned": 1,
+      "scanned": 2,
       "skipped": null
     },
     "completed_todos": {
@@ -33,7 +33,7 @@
       "skipped": null
     },
     "pending_todos": {
-      "dir": "<FIXTURE>/.planning/todos/pending",
+      "dir": "<FIXTURE>/.planning/todos",
       "scanned": 1,
       "skipped": null
     },
@@ -199,6 +199,20 @@
         "jwt",
         "tokens"
       ]
+    },
+    {
+      "path": "<FIXTURE>/.planning/adhoc/20260225-refactor-api/adhoc-01-SUMMARY.md",
+      "subsystem": "api",
+      "learnings": [
+        "Consolidated duplicate route handlers into shared utility",
+        "Adopted consistent error response format across endpoints"
+      ],
+      "related_phase": "",
+      "tags": [
+        "rest",
+        "endpoints",
+        "refactor"
+      ]
     }
   ],
   "completed_todos": [
@@ -206,17 +220,17 @@
       "path": "<FIXTURE>/.planning/todos/done/setup-db.md",
       "title": "Set up database migrations",
       "subsystem": "database",
-      "priority": "high",
-      "phase_origin": "02-infra"
+      "priority": 2,
+      "estimate": "M"
     }
   ],
   "pending_todos": [
     {
-      "path": "<FIXTURE>/.planning/todos/pending/add-logout.md",
+      "path": "<FIXTURE>/.planning/todos/add-logout.md",
       "title": "Add logout endpoint",
       "subsystem": "auth",
-      "priority": "medium",
-      "phase_origin": "05-auth"
+      "priority": 3,
+      "estimate": "S"
     }
   ],
   "knowledge_files": [

package/scripts/ms-tools.py

@@ -798,16 +798,23 @@ def cmd_gather_milestone_stats(args: argparse.Namespace) -> None:
             phase_plans = 0
             phase_complete = 0
 
-            for plan in sorted(d.glob("*-PLAN.md")):
+            # Discover plans from both PLAN.md and SUMMARY.md files
+            # (PLAN.md may be cleaned up after execution)
+            plan_bases: set[str] = set()
+            for plan in d.glob("*-PLAN.md"):
+                plan_bases.add(plan.name.replace("-PLAN.md", ""))
+            for summary in d.glob("*-SUMMARY.md"):
+                plan_bases.add(summary.name.replace("-SUMMARY.md", ""))
+
+            for plan_base in sorted(plan_bases):
                 plan_count += 1
                 phase_plans += 1
-                plan_base = plan.name.replace("-PLAN.md", "")
                 summary = d / f"{plan_base}-SUMMARY.md"
                 if summary.is_file():
                     complete += 1
                     phase_complete += 1
                 else:
-                    incomplete_list.append(f"  {dirname}/{plan.name}")
+                    incomplete_list.append(f"  {dirname}/{plan_base}-PLAN.md")
 
             phase_details.append(f"- Phase {phase_num}: {phase_name} ({phase_complete}/{phase_plans} plans)")
 
@@ -1021,30 +1028,33 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
 
 
 def cmd_generate_adhoc_patch(args: argparse.Namespace) -> None:
-    """Generate a patch file from an adhoc commit.
+    """Generate a patch file from an adhoc commit or commit range.
 
     Contract:
-        Args: commit (str) — commit hash, output (str) — output file path
+        Args: commit (str) — start commit hash, output (str) — output file path,
+              end (str, optional) — end commit hash for range diffs
         Output: text — patch generation status and file path
         Exit codes: 0 = success (or no changes), 1 = commit not found
         Side effects: writes .patch file to output path
     """
     commit_hash = args.commit
+    end_commit = getattr(args, "end", None) or commit_hash
     output_path = args.output
 
     git_root = find_git_root()
     import os
     os.chdir(git_root)
 
-    # Verify commit exists
-    try:
-        run_git("rev-parse", commit_hash)
-    except subprocess.CalledProcessError:
-        print(f"Error: Commit {commit_hash} not found", file=sys.stderr)
-        sys.exit(1)
+    # Verify commits exist
+    for ref in {commit_hash, end_commit}:
+        try:
+            run_git("rev-parse", ref)
+        except subprocess.CalledProcessError:
+            print(f"Error: Commit {ref} not found", file=sys.stderr)
+            sys.exit(1)
 
     exclude_args = build_exclude_pathspecs()
-    diff_args = ["diff", f"{commit_hash}^", commit_hash, "--", "."] + exclude_args
+    diff_args = ["diff", f"{commit_hash}^", end_commit, "--", "."] + exclude_args
 
     result = subprocess.run(
         ["git"] + diff_args,
@@ -1230,7 +1240,7 @@ def _scan_artifact_subsystem_values(planning: Path) -> list[str]:
         ("adhoc", "*-SUMMARY.md"),
         ("debug", "*.md"),
         ("debug/resolved", "*.md"),
-        ("todos/pending", "*.md"),
+        ("todos", "*.md"),
         ("todos/done", "*.md"),
     ]
     for subdir, pattern in scan_globs:
@@ -1352,7 +1362,7 @@ def cmd_scan_artifact_subsystems(args: argparse.Namespace) -> None:
         ("Adhoc SUMMARYs", "adhoc", "*-SUMMARY.md"),
         ("Debug docs", "debug", "*.md"),
         ("Debug resolved", "debug/resolved", "*.md"),
-        ("Pending Todos", "todos/pending", "*.md"),
+        ("Pending Todos", "todos", "*.md"),
         ("Done Todos", "todos/done", "*.md"),
     ]
 
@@ -1769,7 +1779,7 @@ def _scan_adhoc_summaries(
         source_info["skipped"] = "directory not found"
         return [], source_info
 
-    summary_files = sorted(adhoc_dir.glob("*-SUMMARY.md"))
+    summary_files = sorted(adhoc_dir.glob("**/*-SUMMARY.md"))
     if not summary_files:
         source_info["skipped"] = "no adhoc SUMMARY.md files found"
         return [], source_info
@@ -1785,6 +1795,12 @@ def _scan_adhoc_summaries(
         learnings = fm.get("learnings", []) or []
         if isinstance(learnings, str):
             learnings = [learnings]
+        # Fallback: extract from key-decisions if learnings absent (phase-style SUMMARY)
+        if not learnings:
+            key_decisions = fm.get("key-decisions", []) or []
+            if isinstance(key_decisions, str):
+                key_decisions = [key_decisions]
+            learnings = key_decisions
 
         results.append({
             "path": str(path),
@@ -1802,8 +1818,8 @@ def _scan_todos(
     subdir: str,
     parse_errors: list[dict[str, str]],
 ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
-    """Scan todo files (done/ or pending/) for metadata."""
-    todo_dir = planning / "todos" / subdir
+    """Scan todo files (done/ or root todos/) for metadata."""
+    todo_dir = planning / "todos" / subdir if subdir else planning / "todos"
     source_info: dict[str, Any] = {"dir": str(todo_dir), "scanned": 0, "skipped": None}
 
     if not todo_dir.is_dir():
@@ -1812,7 +1828,8 @@ def _scan_todos(
 
     md_files = sorted(todo_dir.glob("*.md"))
     if not md_files:
-        source_info["skipped"] = f"no .md files in {subdir}/"
+        label = f"{subdir}/" if subdir else "todos/"
+        source_info["skipped"] = f"no .md files in {label}"
         return [], source_info
 
     results: list[dict[str, Any]] = []
@@ -1828,7 +1845,7 @@ def _scan_todos(
             "title": fm.get("title", path.stem),
             "subsystem": fm.get("subsystem", ""),
             "priority": fm.get("priority", ""),
-            "phase_origin": fm.get("phase_origin", ""),
+            "estimate": fm.get("estimate", ""),
         })
 
     return results, source_info
@@ -2003,9 +2020,10 @@ def _format_markdown(output: dict[str, Any]) -> str:
         for t in todos:
             title = t.get("title", "untitled")
             priority = t.get("priority", "")
+            estimate = t.get("estimate", "")
             sub = t.get("subsystem", "")
             path = t.get("path", "")
-            lines.append(f"- **{title}** [{priority}] ({sub}) — `{path}`")
+            lines.append(f"- **{title}** [P{priority}|{estimate}] ({sub}) — `{path}`")
         sections.append("\n".join(lines))
 
     sources = output.get("sources", {})
@@ -2080,7 +2098,7 @@ def cmd_scan_planning_context(args: argparse.Namespace) -> None:
     debug_learnings, debug_src = _scan_debug_docs(planning, parse_errors)
     adhoc_learnings, adhoc_src = _scan_adhoc_summaries(planning, parse_errors)
     completed_todos, completed_src = _scan_todos(planning, "done", parse_errors)
-    pending_todos, pending_src = _scan_todos(planning, "pending", parse_errors)
+    pending_todos, pending_src = _scan_todos(planning, "", parse_errors)
     knowledge_files, knowledge_src = _scan_knowledge_files(planning, subsystems)
 
     aggregated = _aggregate_from_summaries(summaries)
@@ -2798,9 +2816,10 @@ def build_parser() -> argparse.ArgumentParser:
     p.set_defaults(func=cmd_generate_phase_patch)
 
     # --- generate-adhoc-patch ---
-    p = subparsers.add_parser("generate-adhoc-patch", help="Generate patch from an adhoc commit")
-    p.add_argument("commit", help="Commit hash")
+    p = subparsers.add_parser("generate-adhoc-patch", help="Generate patch from an adhoc commit or range")
+    p.add_argument("commit", help="Start commit hash")
     p.add_argument("output", help="Output path for the patch file")
+    p.add_argument("--end", default=None, help="End commit hash for range diffs (default: same as commit)")
     p.set_defaults(func=cmd_generate_adhoc_patch)
 
     # --- archive-milestone-phases ---

package/scripts/test_ms_tools.py

@@ -41,6 +41,7 @@ _detect_versioned_milestone_dirs = _mod._detect_versioned_milestone_dirs
 _parse_milestone_name_mapping = _mod._parse_milestone_name_mapping
 _SafeEncoder = _mod._SafeEncoder
 cmd_set_last_command = _mod.cmd_set_last_command
+cmd_gather_milestone_stats = _mod.cmd_gather_milestone_stats
 
 # ---------------------------------------------------------------------------
 # Fixtures
@@ -480,7 +481,7 @@ def _build_scan_output(planning: Path) -> dict:
     debug_learnings, debug_src = _scan_debug_docs(planning, parse_errors)
     adhoc_learnings, adhoc_src = _scan_adhoc_summaries(planning, parse_errors)
     completed_todos, completed_src = _scan_todos(planning, "done", parse_errors)
-    pending_todos, pending_src = _scan_todos(planning, "pending", parse_errors)
+    pending_todos, pending_src = _scan_todos(planning, "", parse_errors)
     knowledge_files, knowledge_src = _scan_knowledge_files(planning, subsystems)
 
     aggregated = _aggregate_from_summaries(summaries)
@@ -594,10 +595,14 @@ class TestScanIntegrationTargeted:
 
     def test_adhoc_learnings_collected(self):
         output = _build_scan_output(FIXTURE_PLANNING)
-        assert len(output["adhoc_learnings"]) == 1
-        adhoc = output["adhoc_learnings"][0]
-        assert adhoc["subsystem"] == "auth"
-        assert len(adhoc["learnings"]) == 2
+        assert len(output["adhoc_learnings"]) == 2
+        # Flat file (old format with learnings field)
+        auth_adhoc = next(a for a in output["adhoc_learnings"] if a["subsystem"] == "auth")
+        assert len(auth_adhoc["learnings"]) == 2
+        # Subdirectory file (phase-style with key-decisions fallback)
+        api_adhoc = next(a for a in output["adhoc_learnings"] if a["subsystem"] == "api")
+        assert len(api_adhoc["learnings"]) == 2
+        assert "duplicate route handlers" in api_adhoc["learnings"][0].lower()
 
     def test_pending_todos_collected(self):
         output = _build_scan_output(FIXTURE_PLANNING)
@@ -932,6 +937,80 @@ class TestSetLastCommand:
         assert "Last Command: ms:verify-work 10 | 2026-02-24 14:30" in text
 
 
+class TestCmdGatherMilestoneStats:
+    """Tests for gather-milestone-stats command."""
+
+    def _patch_git_root(self, tmp_path):
+        return mock.patch.object(_mod, "find_git_root", return_value=tmp_path)
+
+    def _patch_run_git(self):
+        return mock.patch.object(_mod, "run_git", return_value="")
+
+    def _make_phase(self, tmp_path, name, plans=None, summaries=None):
+        """Create a phase dir with optional PLAN.md and SUMMARY.md files."""
+        phase_dir = tmp_path / ".planning" / "phases" / name
+        phase_dir.mkdir(parents=True, exist_ok=True)
+        for p in (plans or []):
+            (phase_dir / p).write_text("# Plan")
+        for s in (summaries or []):
+            (phase_dir / s).write_text("# Summary")
+        return phase_dir
+
+    def test_both_plan_and_summary(self, tmp_path, capsys):
+        self._make_phase(tmp_path, "01-auth",
+                         plans=["01-01-PLAN.md"], summaries=["01-01-SUMMARY.md"])
+        args = argparse.Namespace(start_phase=1, end_phase=1)
+        with self._patch_git_root(tmp_path), self._patch_run_git():
+            cmd_gather_milestone_stats(args)
+        out = capsys.readouterr().out
+        assert "Plans: 1 total, 1 complete" in out
+        assert "Status: READY" in out
+
+    def test_summary_only_no_plan(self, tmp_path, capsys):
+        """PLAN.md cleaned up after execution — SUMMARY.md alone counts."""
+        self._make_phase(tmp_path, "09-persistence",
+                         summaries=["09-01-SUMMARY.md", "09-02-SUMMARY.md"])
+        args = argparse.Namespace(start_phase=9, end_phase=9)
+        with self._patch_git_root(tmp_path), self._patch_run_git():
+            cmd_gather_milestone_stats(args)
+        out = capsys.readouterr().out
+        assert "Plans: 2 total, 2 complete" in out
+        assert "Status: READY" in out
+
+    def test_plan_only_no_summary_is_incomplete(self, tmp_path, capsys):
+        self._make_phase(tmp_path, "03-setup",
+                         plans=["03-01-PLAN.md"])
+        args = argparse.Namespace(start_phase=3, end_phase=3)
+        with self._patch_git_root(tmp_path), self._patch_run_git():
+            cmd_gather_milestone_stats(args)
+        out = capsys.readouterr().out
+        assert "Plans: 1 total, 0 complete" in out
+        assert "Status: NOT READY" in out
+
+    def test_multi_phase_mixed(self, tmp_path, capsys):
+        """Multiple phases: some with PLANs, some with only SUMMARYs."""
+        self._make_phase(tmp_path, "09-persistence",
+                         summaries=["09-01-SUMMARY.md", "09-02-SUMMARY.md"])
+        self._make_phase(tmp_path, "10-transactions",
+                         plans=["10-01-PLAN.md"],
+                         summaries=["10-01-SUMMARY.md"])
+        args = argparse.Namespace(start_phase=9, end_phase=10)
+        with self._patch_git_root(tmp_path), self._patch_run_git():
+            cmd_gather_milestone_stats(args)
+        out = capsys.readouterr().out
+        assert "Plans: 3 total, 3 complete" in out
+        assert "Status: READY" in out
+
+    def test_no_plans_or_summaries(self, tmp_path, capsys):
+        self._make_phase(tmp_path, "01-auth")
+        args = argparse.Namespace(start_phase=1, end_phase=1)
+        with self._patch_git_root(tmp_path), self._patch_run_git():
+            cmd_gather_milestone_stats(args)
+        out = capsys.readouterr().out
+        assert "Plans: 0 total, 0 complete" in out
+        assert "Status: NOT READY" in out
+
+
 # ===================================================================
 # Part 4: UAT File Management Tests
 # ===================================================================

package/skills/senior-review/SKILL.md

@@ -211,6 +211,3 @@ verdict: "clean | minor_issues | needs_refactoring | structural_concerns"
 - User has opportunity to provide context before changes
 - YAML summary block included for orchestrator parsing
 
-## Full Compiled Document
-
-For the complete guide with all principles expanded: `AGENTS.md`