mindsystem-cc 3.22.1 → 4.0.1

package/mindsystem/workflows/adhoc.md

@@ -1,36 +1,10 @@
 <purpose>
-Execute small work items discovered during verification or debugging without the overhead of phase insertion.
-
-Provides "describe → quick plan → execute → verify → log" flow for work that's too small for a phase but needs tracking.
+Execute discovered work with knowledge-aware planning, subagent execution, and knowledge consolidation.
 </purpose>
 
-<scope_guard>
-**Maximum scope: 2 tasks**
-
-If work requires more than 2 tasks, REFUSE with:
-```
-This work requires [N] tasks (max: 2 for adhoc work).
-
-Use `/ms:insert-phase [current_phase] [description]` instead.
-```
-
-If work requires architectural changes, REFUSE with:
-```
-This work requires architectural changes.
-
-Use `/ms:insert-phase` for proper planning and context tracking.
-```
-</scope_guard>
-
-<required_reading>
-Read STATE.md before any operation to load project context.
-
-@~/.claude/mindsystem/templates/adhoc-summary.md
-</required_reading>
-
 <process>
 
-<step name="parse_arguments" priority="first">
+<step name="parse_and_validate" priority="first">
 Parse the work description from $ARGUMENTS:
 
 ```bash
@@ -45,9 +19,7 @@ description="$ARGUMENTS"
 ```
 
 Validate description is actionable (not vague like "fix stuff" or "make it work").
-</step>
 
-<step name="validate_project">
 Verify active Mindsystem project:
 
 ```bash
@@ -61,155 +33,119 @@ if [ ! -f .planning/STATE.md ]; then
 fi
 ```
 
-Load project context:
-- Current phase (for related_phase in adhoc artifacts)
-- Accumulated decisions (constraints on this work)
-- Blockers/concerns (things to watch for)
-</step>
-
-<step name="analyze_scope">
-Quick analysis of what tasks are needed:
-
-1. Identify files that need modification
-2. Determine discrete tasks required
-3. Check for architectural implications
-
-**Task estimation:**
-- Single file, simple change → 1 task
-- Multiple files, related change → 1-2 tasks
-- Multiple files, different concerns → likely >2 tasks
-
-**Architectural check:**
-- New patterns or abstractions → architectural
-- Changes to core interfaces → architectural
-- Cross-cutting concerns → architectural
+Read STATE.md for project context (current phase, accumulated decisions, blockers).
 
-**Decision point:**
+**Ticket detection:** Check `task_tracker` in config.json. If configured and `$ARGUMENTS` matches the ticket ID pattern, lazy-load `~/.claude/mindsystem/references/{type}-cli.md` and follow its **Ticket Detection** process. If no tracker configured or no match, proceed with `$ARGUMENTS` as free-text.
 
-If tasks > 2:
+```bash
+TRACKER_TYPE=$(jq -r '.task_tracker.type // empty' .planning/config.json 2>/dev/null)
+TRACKER_CLI=$(jq -r '.task_tracker.cli // empty' .planning/config.json 2>/dev/null)
 ```
-This work requires approximately [N] tasks:
-1. [task description]
-2. [task description]
-3. [task description]
-...
 
-Adhoc work is limited to 2 tasks maximum.
+**Todo detection:** If `$ARGUMENTS` matches a `.planning/todos/*.md` file path and the file exists, lazy-load `~/.claude/mindsystem/references/todo-file.md` and follow its **Todo Detection** process. Todo detection is independent of ticket detection — both can be inactive.
+</step>
 
-**Suggestion:** `/ms:insert-phase [current_phase] [description]`
-```
+<step name="load_knowledge">
+Read subsystems and match knowledge files to work description:
 
-If architectural:
+```bash
+# Read subsystems from config
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
 ```
-This work involves architectural changes:
-- [what makes it architectural]
 
-Adhoc work handles small, isolated fixes — not structural changes.
+Match keywords from work description against subsystem names. Read matching `.planning/knowledge/*.md` files (1-3 most relevant).
 
-**Suggestion:** `/ms:insert-phase [current_phase] [description]`
-```
-
-If ≤2 tasks and not architectural: PROCEED
+This knowledge informs both the exploration step (what to look for) and the plan (established patterns, pitfalls to avoid).
 </step>
 
-<step name="create_adhoc_directory">
-Ensure adhoc directory exists:
-
-```bash
-mkdir -p .planning/adhoc
-```
-</step>
+<step name="explore_codebase">
+Spawn Explore agents with search focuses derived from work description + loaded knowledge.
 
-<step name="create_lightweight_plan">
-Generate timestamp and slug:
+Count: 1 for simple/focused work, 2-3 for work touching multiple areas.
 
-```bash
-timestamp=$(date "+%Y-%m-%d")
-slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-50)
-plan_file=".planning/adhoc/${timestamp}-${slug}-PLAN.md"
-```
+Each agent receives:
+- Specific search focus (e.g., "find auth token refresh logic", "find API client interceptors")
+- Relevant knowledge context (patterns to look for, files known to be involved)
+- Thoroughness: "medium" for most work, "very thorough" for unfamiliar areas
+</step>
 
-Create minimal PLAN.md:
+<step name="present_and_clarify">
+Present exploration findings as a briefing with externalized assumptions, then cross the information asymmetry boundary with targeted questions.
 
-```markdown
-# Adhoc: [User's description]
+**Part 1 — Briefing (always):**
 
-**Subsystem:** [subsystem or "general"] | **Type:** execute
+Present a dense, specific summary:
+- What changes and why (files, purpose)
+- Claude's assumptions about expected behavior, scope boundaries, and approach — each marked with confidence: **high** / **medium** / **low** to focus user attention on uncertain areas
+- Patterns and constraints from knowledge files and exploration
 
-## Context
-[User's description of what needs to be done and why]
+**Part 2 — AskUserQuestion:**
 
-## Changes
+Governing principle: each question must save more context than it costs. A question that prevents a wrong assumption from reaching the executor saves an entire subagent context window.
 
-### 1. [Action-oriented name]
-**Files:** `[file paths]`
+- Q1 (always): Assumption validation — "Are these assumptions correct?" with options:
+  - Looks right
+  - Some corrections (let me clarify)
+  - Let me reframe the task
+- Additional questions (conditional): Only when exploration surfaced genuine behavioral ambiguity the user must resolve. Frame with implementation context discovered during exploration. Typically 1-2 for focused work, 3-4 for multi-area work.
 
-[What to do, what to avoid and WHY]
+**What NOT to ask** (Claude determines these from exploration):
+- Technical approach or patterns
+- Error handling strategy
+- Implementation details the user can't meaningfully influence
+- Only ask about: user intent, expected behavior, scope boundaries
 
-[### 2. if needed, same structure]
+**Fast path:** All assumptions high-confidence + no ambiguity → collapse to single validation question.
 
-## Verification
-- [How to verify the work is complete]
+**On corrections:** Absorb user feedback and proceed to planning. Do not re-present the full briefing.
+</step>
 
-## Must-Haves
-- [ ] [Observable outcome 1]
-- [ ] [Observable outcome 2]
-```
+<step name="spawn_plan_writer">
+Create per-execution subdirectory:
 
-Write to file:
 ```bash
-echo "Plan created: $plan_file"
-```
+timestamp=$(date "+%Y-%m-%d")
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-50)
+exec_dir=".planning/adhoc/${timestamp}-${slug}"
+mkdir -p "$exec_dir"
+```
+
+Assemble context payload for ms-adhoc-planner:
+- Work description
+- Exploration findings (from Explore agents)
+- Knowledge file contents (loaded in step 2)
+- User decisions (from clarification step)
+- STATE.md context (current phase, accumulated decisions)
+- Subsystem list from config.json
+- Output path: `${exec_dir}/adhoc-01-PLAN.md`
+- Ticket context when detected (per loaded ticket reference)
+- Todo context when detected (per loaded todo reference)
+
+Spawn ms-adhoc-planner via Task tool. Receive completion report with plan path.
 </step>
 
-<step name="execute_tasks">
-Execute each task inline (no subagent for small work).
-
-For each task:
-1. Read current file state (use Explore subagent if context gathering needed)
-2. Make changes
-3. Run verify command
-4. Track files modified
-
-**Deviation rules apply:**
-- Rule 1 (Bug): Auto-fix bugs found during execution
-- Rule 2 (Critical): Auto-fix security/data issues
-- Rule 3 (Blocking): Auto-fix missing dependencies, typos
-
-**Rule 4 (Architectural) triggers STOP:**
-If execution reveals architectural changes needed:
-```
-STOP: Architectural changes required
-
-During execution, discovered:
-- [what architectural change is needed]
-
-This exceeds adhoc scope.
+<step name="review_plan">
+Read the generated plan at `${exec_dir}/adhoc-01-PLAN.md`.
 
-Work completed so far:
-- [list completed tasks]
+Present a summary to the user:
+- Number of Changes sections
+- Key files affected
+- Must-Haves checklist
 
-**Next steps:**
-1. Commit partial work (if valuable)
-2. Use `/ms:insert-phase` for remaining work
-```
-
-Use AskUserQuestion to confirm how to proceed.
+Allow the user to approve, request edits, or abort. If edits requested, apply them directly to the plan file.
 </step>
 
-<step name="lightweight_verification">
-Verify the work is complete:
-
-1. Run verify commands from each task
-2. Check files exist/changed as expected
-3. Run relevant tests if specified in verify
+<step name="spawn_executor">
+Spawn ms-executor via Task tool.
 
-**Not required for adhoc:**
-- Full goal-backward verification
-- Cross-system integration checks
-- Regression test suite
+Provide in the prompt:
+- Plan path: `${exec_dir}/adhoc-01-PLAN.md`
+- SUMMARY output path: `${exec_dir}/adhoc-01-SUMMARY.md`
+- Instruction to use phase-style SUMMARY format (with key-decisions, patterns-established, key-files, mock_hints frontmatter fields) for consolidator compatibility
+- Ticket commit instructions when detected (per loaded ticket reference)
+- Todo commit instructions when detected (per loaded todo reference)
 
-Keep verification focused on the specific changes made.
+The executor reads the plan, executes tasks with atomic commits, creates SUMMARY.md, and returns completion report.
 </step>
 
 <step name="code_review">
@@ -219,195 +155,90 @@ Read code review agent from config:
 CODE_REVIEW=$(cat .planning/config.json 2>/dev/null | jq -r '.code_review.adhoc // .code_review.phase // empty')
 ```
 
-**If CODE_REVIEW = "skip":**
-Skip to create_adhoc_summary.
+**If CODE_REVIEW = "skip":** Skip to generate_patch.
 
-**If CODE_REVIEW = empty/null:**
-Use default: `CODE_REVIEW="ms-code-simplifier"`
+**If CODE_REVIEW = empty/null:** Use default: `CODE_REVIEW="ms-code-simplifier"`
 
-**Otherwise:**
-Use CODE_REVIEW value directly as agent name.
+**Otherwise:** Use CODE_REVIEW value directly as agent name.
 
-1. **Get modified files:**
+1. Get modified files from executor's commits:
    ```bash
-   git diff --name-only HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$'
+   ADHOC_COMMITS=$(git log --oneline --grep="(adhoc-" --format="%H")
+   CHANGED_FILES=$(git diff --name-only $(echo "$ADHOC_COMMITS" | tail -1)^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
    ```
 
-2. **Spawn code review agent with adhoc scope:**
-   ```
-   Task(
-     prompt="
-     <objective>
-     Review code modified in adhoc work.
-     Preserve all functionality. Improve clarity and consistency.
-     </objective>
-
-     <scope>
-     Files to analyze:
-     {MODIFIED_FILES}
-     </scope>
-
-     <output>
-     After review and simplifications, run static analysis and tests.
-     Report what was improved and verification results.
-     </output>
-     ",
-     subagent_type="{CODE_REVIEW}"
-   )
-   ```
+2. Spawn code review agent with adhoc scope.
 
-3. **Track review changes:**
-   - If changes made: Set `CODE_REVIEW_APPLIED=true`
-   - Reviewed files will be included in the adhoc commit
-   - Note in SUMMARY.md that code review was applied
+3. If changes made: commit with message `refactor(adhoc): code review pass`.
 </step>
 
-<step name="create_adhoc_summary">
-Create SUMMARY.md (see @~/.claude/mindsystem/templates/adhoc-summary.md for full template):
+<step name="generate_patch">
+Generate a patch file capturing all adhoc changes:
 
 ```bash
-summary_file=".planning/adhoc/${timestamp}-${slug}-SUMMARY.md"
-
-# Read subsystems for categorization
-jq -r '.subsystems[]' .planning/config.json 2>/dev/null
-```
-
-```markdown
----
-type: adhoc
-description: [description]
-completed: [ISO timestamp]
-duration: [X min]
-related_phase: [phase or "none"]
-subsystem: [select from config.json subsystems based on work performed]
-tags: [searchable keywords from work context]
-files_modified:
-  - [path/to/file1.ts]
-  - [path/to/file2.ts]
-commit: [hash - filled after commit]
-learnings:
-  - [optional: include only when work revealed non-obvious insights. Skip for routine fixes.]
----
-
-# Adhoc: [Description]
-
-**[Substantive one-liner describing what was done]**
-
-## What Was Done
-
-- [accomplishment 1]
-- [accomplishment 2]
-
-## Files Modified
-
-- `[path]`: [what changed]
-- `[path]`: [what changed]
-
-## Verification
-
-- [what was verified and result]
+ADHOC_COMMITS=$(git log --oneline --grep="(adhoc-" --format="%H")
+FIRST_COMMIT=$(echo "$ADHOC_COMMITS" | tail -1)
+LAST_COMMIT=$(echo "$ADHOC_COMMITS" | head -1)
+patch_file="${exec_dir}/adhoc-01-changes.patch"
+ms-tools generate-adhoc-patch "$FIRST_COMMIT" "$patch_file" --end "$LAST_COMMIT"
 ```
 
-Write to file.
+If no adhoc commits found or patch generation reports no changes, skip silently.
 </step>
 
-<step name="update_state">
-Update STATE.md with adhoc work entry:
-
-1. Read current STATE.md
-2. Find or create "### Recent Adhoc Work" under "## Accumulated Context"
-3. Add entry at top of list
-4. Keep last 5 entries (remove older ones from list, files remain in .planning/adhoc/)
-
-Format:
-```markdown
-### Recent Adhoc Work
-
-- [YYYY-MM-DD]: [description] (.planning/adhoc/[filename]-SUMMARY.md)
-```
-
-If section doesn't exist, add after "### Pending Todos" section:
-
-```markdown
-### Recent Adhoc Work
+<step name="consolidate_knowledge">
+Spawn ms-consolidator via Task tool.
 
-- [YYYY-MM-DD]: [description] (.planning/adhoc/[filename]-SUMMARY.md)
+Provide:
+- Phase directory: `${exec_dir}` (the per-execution subdirectory)
+- Phase identifier: "adhoc"
 
-*See `.planning/adhoc/` for full history*
-```
+The consolidator reads `adhoc-01-SUMMARY.md`, extracts knowledge (key-decisions, patterns-established, key-files), updates `.planning/knowledge/*.md` files, and deletes `adhoc-01-PLAN.md`.
 </step>
 
-<step name="git_commit">
-Single commit for all changes (including simplifications if applied):
+<step name="cleanup_and_report">
+**Finalize ticket (when detected):** Follow the **Finalization**, **Commit Message Suffix**, and **Report Additions** sections from the loaded ticket reference.
 
-```bash
-# Add all modified files (code + reviewed files)
-git add [code files modified]
-git add [reviewed files if CODE_REVIEW_APPLIED]
-git add "$plan_file"
-git add "$summary_file"
-git add .planning/STATE.md
-
-# Determine commit type
-# feat: new functionality
-# fix: bug fix, correction
-commit_type="fix"  # or "feat" based on nature of work
-
-# Include code review note if applied
-if [ "$CODE_REVIEW_APPLIED" = "true" ]; then
-  review_note="Includes code review pass."
-else
-  review_note=""
-fi
+**Finalize todo (when detected):** Follow the **Finalization**, **Commit Message Suffix**, and **Report Additions** sections from the loaded todo reference.
 
-git commit -m "$(cat <<'EOF'
-${commit_type}(adhoc): [description]
+**Commit knowledge updates:**
+```bash
+git add .planning/knowledge/*.md "${exec_dir}/adhoc-01-SUMMARY.md" .planning/STATE.md
+# Only include patch if it was generated
+[ -f "${exec_dir}/adhoc-01-changes.patch" ] && git add "${exec_dir}/adhoc-01-changes.patch"
+git commit -m "$(cat <<EOF
+docs(adhoc): consolidate knowledge from $description
 
-Files: [count] modified
-${review_note}
+Knowledge files updated, SUMMARY preserved.
 EOF
 )"
-
-# Capture commit hash
-commit_hash=$(git rev-parse --short HEAD)
 ```
 
-Update SUMMARY.md with commit hash in frontmatter.
-</step>
-
-<step name="generate_adhoc_patch">
-Generate patch file from the adhoc commit:
+**Update STATE.md** "Recent Adhoc Work" section:
+- Find or create "### Recent Adhoc Work" under "## Accumulated Context"
+- Add entry at top: `- [YYYY-MM-DD]: [description] ({exec_dir}/adhoc-01-SUMMARY.md)`
+- Keep last 5 entries (remove older ones from list)
 
+**Set last command:**
 ```bash
-patch_file=".planning/adhoc/${timestamp}-${slug}.patch"
-
-ms-tools generate-adhoc-patch "$commit_hash" "$patch_file"
+ms-tools set-last-command "ms:adhoc $ARGUMENTS"
 ```
 
-If patch generated (file exists and non-empty):
-- Update SUMMARY.md frontmatter to include `patch_file: [path]`
-
-If skipped (no implementation changes outside exclusions):
-- Leave patch_file field empty or omit from SUMMARY.md
-</step>
-
-<step name="completion">
-Report completion:
-
+**Report completion:**
 ```
 Adhoc work complete: [description]
 
 **Commit:** [hash]
-**Duration:** [X min]
 **Files modified:** [count]
+**Knowledge updated:** [list of knowledge files]
 
 Artifacts:
-- Plan: .planning/adhoc/[timestamp]-[slug]-PLAN.md
-- Summary: .planning/adhoc/[timestamp]-[slug]-SUMMARY.md
-- Patch: .planning/adhoc/[timestamp]-[slug].patch (if generated)
-
-STATE.md updated with adhoc entry.
+- Summary: {exec_dir}/adhoc-01-SUMMARY.md
+- Patch: {exec_dir}/adhoc-01-changes.patch
+- Knowledge: .planning/knowledge/[subsystem].md
+```
 
+```
 ---
 
 Continue with current work or check project status:
@@ -417,22 +248,3 @@ Continue with current work or check project status:
 </step>
 
 </process>
-
-<deviation_rules>
-Adhoc work uses the same deviation rules as plan execution:
-
-**Rule 1 - Bug in plan:** Auto-fix
-**Rule 2 - Missing critical:** Auto-fix
-**Rule 3 - Blocking issue:** Auto-fix
-**Rule 4 - Architectural change:** STOP and suggest /ms:insert-phase
-
-Rule 4 is strict for adhoc work — architectural changes exceed adhoc scope by definition.
-</deviation_rules>
-
-<output_artifacts>
-- `.planning/adhoc/{timestamp}-{slug}-PLAN.md` — lightweight plan
-- `.planning/adhoc/{timestamp}-{slug}-SUMMARY.md` — completion summary
-- `.planning/adhoc/{timestamp}-{slug}.patch` — implementation changes (if any)
-- Updated `.planning/STATE.md` — adhoc entry in accumulated context
-- Git commit with all changes
-</output_artifacts>

package/mindsystem/workflows/complete-milestone.md

@@ -192,6 +192,24 @@ cat .planning/phases/*-*/*-SUMMARY.md
    - Remove items that are no longer relevant
    - Add any requirements invalidated during this milestone
 
+   **Deferred triage** (runs while REQUIREMENTS.md and CONTEXT.md files are still available):
+
+   a. Read REQUIREMENTS.md `## v2 Requirements` section
+   b. Scan phase CONTEXT.md files for `<deferred>` sections:
+      ```bash
+      grep -l "<deferred>" .planning/phases/*/*-CONTEXT.md 2>/dev/null
+      ```
+      Read each matching file's `<deferred>` section.
+   c. Collect all deferred items into a combined list (deduplicate by description similarity)
+   d. If no deferred items found: skip silently
+   e. If deferred items exist, present as batch decision gate via AskUserQuestion:
+      - Show all items grouped by source (v2 requirements vs phase deferred ideas)
+      - Options: "Defer all", "Triage individually", "Discard all"
+      - If "Triage individually": for each item, options are Keep (→ Deferred), Exclude (→ Out of Scope), Discard
+      - If "Defer all": add all to PROJECT.md `## Deferred` section
+   f. Update PROJECT.md `## Deferred` and/or `## Out of Scope` sections accordingly
+   g. If a Deferred section already exists (from previous milestones), merge — don't replace
+
 4. **Business context review:**
    - Who It's For — has understanding of audience evolved?
    - Core Problem — still the right framing?
@@ -289,6 +307,7 @@ Initial user testing showed demand for shape tools.
 - [ ] "What This Is" reviewed and updated if needed
 - [ ] Core Value verified as still correct
 - [ ] All shipped requirements added to Validated
+- [ ] Deferred items triaged (v2 requirements + CONTEXT.md deferred ideas)
 - [ ] Business context reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] Out of Scope reasoning audited
 - [ ] Technical Context updated with current state
@@ -587,6 +606,7 @@ Milestone completion is successful when (ordered by skip risk):
 
 - [ ] PROJECT.md full evolution review completed (What This Is, Core Value, business context, Validated, Key Decisions, Technical Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
+- [ ] Deferred items triaged (v2 requirements + CONTEXT.md deferred ideas)
 - [ ] Key Decisions updated with outcomes
 - [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] Roadmap archive created (milestones/{slug}/ROADMAP.md)