@massu/core 0.1.2 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/commands/_shared-preamble.md +76 -0
  2. package/commands/massu-audit-deps.md +211 -0
  3. package/commands/massu-changelog.md +174 -0
  4. package/commands/massu-cleanup.md +315 -0
  5. package/commands/massu-commit.md +481 -0
  6. package/commands/massu-create-plan.md +752 -0
  7. package/commands/massu-dead-code.md +131 -0
  8. package/commands/massu-debug.md +484 -0
  9. package/commands/massu-deploy.md +91 -0
  10. package/commands/massu-deps.md +374 -0
  11. package/commands/massu-doc-gen.md +279 -0
  12. package/commands/massu-docs.md +364 -0
  13. package/commands/massu-estimate.md +313 -0
  14. package/commands/massu-golden-path.md +973 -0
  15. package/commands/massu-guide.md +167 -0
  16. package/commands/massu-hotfix.md +480 -0
  17. package/commands/massu-loop-playwright.md +837 -0
  18. package/commands/massu-loop.md +775 -0
  19. package/commands/massu-new-feature.md +511 -0
  20. package/commands/massu-parity.md +214 -0
  21. package/commands/massu-plan.md +456 -0
  22. package/commands/massu-push-light.md +207 -0
  23. package/commands/massu-push.md +434 -0
  24. package/commands/massu-refactor.md +410 -0
  25. package/commands/massu-release.md +363 -0
  26. package/commands/massu-review.md +238 -0
  27. package/commands/massu-simplify.md +281 -0
  28. package/commands/massu-status.md +278 -0
  29. package/commands/massu-tdd.md +201 -0
  30. package/commands/massu-test.md +516 -0
  31. package/commands/massu-verify-playwright.md +281 -0
  32. package/commands/massu-verify.md +667 -0
  33. package/dist/cli.js +12521 -0
  34. package/dist/hooks/cost-tracker.js +80 -5
  35. package/dist/hooks/post-edit-context.js +72 -6
  36. package/dist/hooks/post-tool-use.js +234 -57
  37. package/dist/hooks/pre-compact.js +144 -5
  38. package/dist/hooks/pre-delete-check.js +141 -11
  39. package/dist/hooks/quality-event.js +80 -5
  40. package/dist/hooks/security-gate.js +29 -0
  41. package/dist/hooks/session-end.js +83 -8
  42. package/dist/hooks/session-start.js +153 -7
  43. package/dist/hooks/user-prompt.js +166 -5
  44. package/package.json +6 -5
  45. package/src/backfill-sessions.ts +5 -4
  46. package/src/cli.ts +6 -1
  47. package/src/commands/doctor.ts +193 -6
  48. package/src/commands/init.ts +235 -6
  49. package/src/commands/install-commands.ts +137 -0
  50. package/src/config.ts +68 -2
  51. package/src/db.ts +115 -2
  52. package/src/docs-tools.ts +8 -6
  53. package/src/hooks/post-edit-context.ts +1 -1
  54. package/src/hooks/post-tool-use.ts +130 -0
  55. package/src/hooks/pre-compact.ts +23 -1
  56. package/src/hooks/pre-delete-check.ts +92 -4
  57. package/src/hooks/security-gate.ts +32 -0
  58. package/src/hooks/session-start.ts +97 -4
  59. package/src/hooks/user-prompt.ts +46 -1
  60. package/src/import-resolver.ts +2 -1
  61. package/src/knowledge-db.ts +169 -0
  62. package/src/knowledge-indexer.ts +704 -0
  63. package/src/knowledge-tools.ts +1413 -0
  64. package/src/license.ts +482 -0
  65. package/src/memory-db.ts +14 -1
  66. package/src/observation-extractor.ts +11 -4
  67. package/src/page-deps.ts +3 -2
  68. package/src/python/coupling-detector.ts +124 -0
  69. package/src/python/domain-enforcer.ts +83 -0
  70. package/src/python/impact-analyzer.ts +95 -0
  71. package/src/python/import-parser.ts +244 -0
  72. package/src/python/import-resolver.ts +135 -0
  73. package/src/python/migration-indexer.ts +115 -0
  74. package/src/python/migration-parser.ts +332 -0
  75. package/src/python/model-indexer.ts +70 -0
  76. package/src/python/model-parser.ts +279 -0
  77. package/src/python/route-indexer.ts +58 -0
  78. package/src/python/route-parser.ts +317 -0
  79. package/src/python-tools.ts +629 -0
  80. package/src/sentinel-db.ts +2 -1
  81. package/src/server.ts +29 -6
  82. package/src/session-archiver.ts +4 -5
  83. package/src/tools.ts +283 -31
  84. package/README.md +0 -40
@@ -0,0 +1,214 @@
1
+ ---
2
+ name: massu-parity
3
+ description: Generic feature parity check between two systems or components
4
+ allowed-tools: Bash(*), Read(*), Grep(*), Glob(*), Write(*), Task(*)
5
+ ---
6
+ name: massu-parity
7
+
8
+ # Massu Parity: Feature Parity Check
9
+
10
+ ## Purpose
11
+
12
+ Deep comparison between two systems, components, or versions to identify feature gaps, content drift, and update needs. Covers multiple layers -- source code, configuration, commands, hooks, tests, and operational tooling.
13
+
14
+ Run periodically (weekly recommended) or when comparing systems for migration/sync.
15
+
16
+ ## Configuration
17
+
18
+ The user provides the two systems to compare. Default paths if not specified:
19
+
20
+ ```
21
+ SOURCE_ROOT=[user-specified or prompted]
22
+ TARGET_ROOT=$(git rev-parse --show-toplevel)
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Step 1: Scan Recent Changes
28
+
29
+ Check source commits since last parity check (default: 7 days).
30
+
31
+ ```bash
32
+ cd $SOURCE_ROOT && git log --oneline --since="7 days ago" | head -50
33
+ ```
34
+
35
+ Note the commit count and summarize key infrastructure changes.
36
+
37
+ ---
38
+
39
+ ## Step 2: Top-Level Config Comparison (Layer 1)
40
+
41
+ ### 2a. Compare configuration files
42
+
43
+ ```bash
44
+ echo "=== Configuration Files ==="
45
+ for FILE in package.json tsconfig.json .claude/CLAUDE.md; do
46
+ SEXISTS="NO"; TEXISTS="NO"
47
+ [ -f "$SOURCE_ROOT/$FILE" ] && SEXISTS="YES ($(wc -c < "$SOURCE_ROOT/$FILE" | tr -d ' ')B)"
48
+ [ -f "$TARGET_ROOT/$FILE" ] && TEXISTS="YES ($(wc -c < "$TARGET_ROOT/$FILE" | tr -d ' ')B)"
49
+ echo "$FILE | Source: $SEXISTS | Target: $TEXISTS"
50
+ done
51
+ ```
52
+
53
+ ### 2b. Compare CLAUDE.md section headings
54
+
55
+ ```bash
56
+ echo "=== SOURCE CLAUDE.md sections ==="
57
+ grep "^## " "$SOURCE_ROOT/.claude/CLAUDE.md" 2>/dev/null | head -30
58
+ echo ""
59
+ echo "=== TARGET CLAUDE.md sections ==="
60
+ grep "^## " "$TARGET_ROOT/.claude/CLAUDE.md" 2>/dev/null | head -30
61
+ ```
62
+
63
+ ---
64
+
65
+ ## Step 3: Command Parity (Layer 2)
66
+
67
+ ### 3a. List commands in both
68
+
69
+ ```bash
70
+ echo "=== SOURCE COMMANDS ($(ls $SOURCE_ROOT/.claude/commands/*.md 2>/dev/null | wc -l | tr -d ' ')) ==="
71
+ ls $SOURCE_ROOT/.claude/commands/*.md 2>/dev/null | xargs -I{} basename {} | sort
72
+ echo ""
73
+ echo "=== TARGET COMMANDS ($(ls $TARGET_ROOT/.claude/commands/*.md 2>/dev/null | wc -l | tr -d ' ')) ==="
74
+ ls $TARGET_ROOT/.claude/commands/*.md 2>/dev/null | xargs -I{} basename {} | sort
75
+ ```
76
+
77
+ ### 3b. Find commands only in source / only in target
78
+
79
+ Compare normalized command names (strip prefixes) and report gaps.
80
+
81
+ ### 3c. Compare matching commands for content drift
82
+
83
+ For each matching command pair, compare file sizes and modification dates. Flag significant drift (>50 lines difference).
84
+
85
+ ---
86
+
87
+ ## Step 4: Source Code Parity (Layer 3)
88
+
89
+ ### 4a. Compare source file inventories
90
+
91
+ ```bash
92
+ echo "=== Source Files ==="
93
+ echo "Source: $(find $SOURCE_ROOT -name '*.ts' -not -path '*/node_modules/*' -not -path '*/__tests__/*' | wc -l) files"
94
+ echo "Target: $(find $TARGET_ROOT -name '*.ts' -not -path '*/node_modules/*' -not -path '*/__tests__/*' | wc -l) files"
95
+ ```
96
+
97
+ ### 4b. Files only in source / only in target
98
+
99
+ List files that exist in one system but not the other.
100
+
101
+ ### 4c. Compare matching files for drift
102
+
103
+ For matching files, report diff line counts.
104
+
105
+ ---
106
+
107
+ ## Step 5: Test Parity (Layer 4)
108
+
109
+ ### 5a. Compare test file inventories
110
+
111
+ ```bash
112
+ echo "=== Test Files ==="
113
+ echo "Source: $(find $SOURCE_ROOT -name '*.test.ts' -not -path '*/node_modules/*' | wc -l) tests"
114
+ echo "Target: $(find $TARGET_ROOT -name '*.test.ts' -not -path '*/node_modules/*' | wc -l) tests"
115
+ ```
116
+
117
+ ### 5b. Test files only in source / only in target
118
+
119
+ ### 5c. Test drift for matching files
120
+
121
+ ---
122
+
123
+ ## Step 6: Hook & Script Parity (Layer 5)
124
+
125
+ ### 6a. Compare hooks
126
+
127
+ ```bash
128
+ echo "=== Hooks ==="
129
+ echo "Source:" && ls $SOURCE_ROOT/packages/core/src/hooks/*.ts 2>/dev/null | xargs -I{} basename {} || ls $SOURCE_ROOT/scripts/hooks/*.sh 2>/dev/null | xargs -I{} basename {}
130
+ echo "Target:" && ls $TARGET_ROOT/packages/core/src/hooks/*.ts 2>/dev/null | xargs -I{} basename {}
131
+ ```
132
+
133
+ ### 6b. Compare scripts
134
+
135
+ ```bash
136
+ echo "=== Scripts ==="
137
+ echo "Source:" && ls $SOURCE_ROOT/scripts/*.sh 2>/dev/null | xargs -I{} basename {}
138
+ echo "Target:" && ls $TARGET_ROOT/scripts/*.sh 2>/dev/null | xargs -I{} basename {}
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Step 7: Tool/Feature Inventory Parity (Layer 6)
144
+
145
+ ### 7a. Extract registered tool names from both systems
146
+
147
+ ```bash
148
+ echo "=== SOURCE TOOLS ==="
149
+ grep -hE "name:\s*['\"\`]" $SOURCE_ROOT/packages/core/src/tools.ts $SOURCE_ROOT/packages/core/src/*-tools.ts $SOURCE_ROOT/packages/core/src/*.ts 2>/dev/null | head -40
150
+
151
+ echo ""
152
+ echo "=== TARGET TOOLS ==="
153
+ grep -hE "name:\s*['\"\`]" $TARGET_ROOT/packages/core/src/tools.ts $TARGET_ROOT/packages/core/src/*-tools.ts $TARGET_ROOT/packages/core/src/*.ts 2>/dev/null | head -40
154
+ ```
155
+
156
+ ### 7b. Compare tool inventories
157
+
158
+ Normalize tool names (strip prefixes) and diff.
159
+
160
+ ---
161
+
162
+ ## Step 8: Build Report
163
+
164
+ Create the full parity report at `docs/reports/PARITY_REPORT.md` with:
165
+
166
+ ```markdown
167
+ # Feature Parity Report
168
+ **Date**: [today]
169
+ **Source**: [source system]
170
+ **Target**: [target system]
171
+ **Source Commits Since Last Check**: [count]
172
+ **Period**: Last 7 days
173
+
174
+ ## Summary Scorecard
175
+
176
+ | Layer | Description | Source | Target | Parity % | Items Needing Update |
177
+ |-------|-------------|--------|--------|----------|---------------------|
178
+ | 1 | Config & CLAUDE.md | - | - | X% | [list] |
179
+ | 2 | Commands | N | N | X% | [list] |
180
+ | 3 | Source Code | N files | N files | X% | [list] |
181
+ | 4 | Tests | N | N | X% | [list] |
182
+ | 5 | Hooks & Scripts | N | N | X% | [list] |
183
+ | 6 | Tools/Features | N | N | X% | [list] |
184
+ | **Overall** | - | - | - | **X%** | **N total items** |
185
+
186
+ ## Items Updated in Source, Not Yet in Target
187
+ [Table with layer, file, change description, priority]
188
+
189
+ ## Items in Target but NOT in Source
190
+ [Table -- these are target innovations to preserve]
191
+
192
+ ## Recommended Actions (Priority Order)
193
+ 1. [action]
194
+ 2. [action]
195
+ ...
196
+ ```
197
+
198
+ ---
199
+
200
+ ## Step 9: Present Summary
201
+
202
+ Show the user:
203
+ 1. Overall parity percentage across all layers
204
+ 2. Count of items needing update, broken down by priority
205
+ 3. Top 10 priority actions
206
+ 4. Link to full report
207
+
208
+ **Classification for each gap:**
209
+ - **CRITICAL**: Core functionality, security, session state
210
+ - **HIGH**: Safety features, hook functionality, config alignment
211
+ - **MEDIUM**: Additional commands, tests, scripts
212
+ - **LOW**: Nice-to-have, cosmetic differences
213
+
214
+ **Target-only items**: Items that exist in target but not source should be PRESERVED and noted as innovations. Do NOT recommend removing them for "parity" -- parity means target has everything source has, not that they are identical.
@@ -0,0 +1,456 @@
1
+ ---
2
+ name: massu-plan
3
+ description: Continuous Verification Audit Loop with ZERO-GAP STANDARD
4
+ allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*), Task(*)
5
+ ---
6
+ name: massu-plan
7
+
8
+ > **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
9
+
10
+ # CS Plan: Continuous Verification Audit Loop (ZERO-GAP STANDARD)
11
+
12
+ ## Workflow Position
13
+
14
+ ```
15
+ /massu-create-plan -> /massu-plan -> /massu-loop -> /massu-commit -> /massu-push
16
+ (CREATE) (AUDIT) (IMPLEMENT) (COMMIT) (PUSH)
17
+ ```
18
+
19
+ **This command is step 2 of 5 in the standard workflow.**
20
+
21
+ ---
22
+
23
+ ## CRITICAL: THIS IS A PLAN-AUDIT COMMAND, NOT AN IMPLEMENTATION COMMAND
24
+
25
+ **THIS COMMAND AUDITS AND IMPROVES PLAN DOCUMENTS. IT DOES NOT IMPLEMENT CODE.**
26
+
27
+ ### FORBIDDEN Actions (Zero Tolerance)
28
+ - Writing code to source files (Edit/Write to packages/)
29
+ - Creating modules, tools, or hooks
30
+ - Implementing any plan items
31
+
32
+ ### ALLOWED Actions
33
+ - Research to verify plan feasibility (Read, Grep, Glob)
34
+ - Edit the PLAN DOCUMENT to fix gaps (Write/Edit to docs/plans/)
35
+ - Loop until plan has zero gaps
36
+ - Present completed plan to user
37
+ - **STOP AND WAIT** for explicit user approval
38
+
39
+ ### AFTER AUDIT COMPLETE: MANDATORY WAIT
40
+
41
+ **After the audit loop completes with zero gaps, you MUST:**
42
+ 1. **Present the plan** to the user
43
+ 2. **STOP completely** - Do not start implementation
44
+ 3. **WAIT** for explicit user instruction to implement (e.g., "run /massu-loop")
45
+
46
+ **This command AUDITS plans. It does NOT implement them. Implementation requires /massu-loop.**
47
+
48
+ ---
49
+
50
+ ## START NOW
51
+
52
+ **Step 0: Write AUTHORIZED_COMMAND to session state (CR-35)**
53
+
54
+ Update `session-state/CURRENT.md` to include `AUTHORIZED_COMMAND: massu-plan`.
55
+
56
+ **Step 0.1: Workflow State Tracking**
57
+
58
+ Write a transition entry to `.massu/workflow-log.md`:
59
+ ```
60
+ | [timestamp] | PLAN | AUDIT | /massu-plan | [session-id] |
61
+ ```
62
+
63
+ ---
64
+
65
+ ## MANDATORY LOOP CONTROLLER (EXECUTE THIS - DO NOT SKIP)
66
+
67
+ **This section is the EXECUTION ENTRY POINT. You MUST follow these steps exactly.**
68
+
69
+ ### How This Command Works
70
+
71
+ This command is a **loop controller**. Your job is to:
72
+ 1. Spawn a `general-purpose` subagent for ONE audit pass
73
+ 2. Parse the structured result (`GAPS_DISCOVERED: N`)
74
+ 3. If gaps discovered > 0: the auditor may fix them, but you MUST spawn ANOTHER full pass
75
+ 4. Only when a COMPLETE FRESH PASS discovers ZERO gaps can you declare complete
76
+
77
+ **You are NOT the auditor. You are the LOOP. The auditor runs inside Task subagents.**
78
+
79
+ ### CRITICAL: GAPS_DISCOVERED Semantics
80
+
81
+ **`GAPS_DISCOVERED` = total gaps FOUND during the pass, REGARDLESS of whether they were also fixed.**
82
+
83
+ | Scenario | GAPS_DISCOVERED | Loop Action |
84
+ |----------|----------------|-------------|
85
+ | Pass finds 0 gaps | 0 | **EXIT** - audit complete |
86
+ | Pass finds 16 gaps, fixes all 16 | **16** (NOT 0) | **CONTINUE** - must re-audit |
87
+ | Pass finds 3 gaps, fixes 2, 1 needs controller | **3** | **CONTINUE** - fix remaining, re-audit |
88
+
89
+ **THE RULE**: A clean pass means zero gaps DISCOVERED from the start. Fixing gaps during a pass does NOT make it a clean pass. Only a fresh pass starting clean and finding nothing wrong proves the plan is correct.
90
+
91
+ ### Execution Protocol
92
+
93
+ ```
94
+ PLAN_PATH = $ARGUMENTS (the plan file path)
95
+ iteration = 0
96
+
97
+ WHILE true:
98
+ iteration += 1
99
+
100
+ # Spawn auditor subagent for ONE complete pass
101
+ result = Task(subagent_type="general-purpose", model="opus", prompt="
102
+ Audit iteration {iteration} for plan: {PLAN_PATH}
103
+ This is a Massu plan (library/MCP server, NOT a web app).
104
+ Execute ONE complete audit pass following all steps below.
105
+ Read the plan from disk. Read .claude/CLAUDE.md. Verify all deliverables.
106
+ Fix any plan document gaps you find.
107
+
108
+ CONTEXT: Massu is a TypeScript monorepo with:
109
+ - packages/core/src/ (MCP server source)
110
+ - packages/core/src/__tests__/ (vitest tests)
111
+ - packages/core/src/hooks/ (esbuild-compiled hooks)
112
+ - massu.config.yaml (project config)
113
+ - Tool registration: 3-function pattern (getDefs, isTool, handleCall) wired in tools.ts
114
+
115
+ VR-* CHECKS (use ONLY these, per CLAUDE.md):
116
+ - VR-FILE, VR-GREP, VR-NEGATIVE, VR-COUNT (generic)
117
+ - VR-BUILD: npm run build (tsc + hooks)
118
+ - VR-TYPE: cd packages/core && npx tsc --noEmit
119
+ - VR-TEST: npm test (vitest)
120
+ - VR-TOOL-REG: tool definitions + handler wired in tools.ts
121
+ - VR-HOOK-BUILD: cd packages/core && npm run build:hooks
122
+ - VR-CONFIG: massu.config.yaml parses
123
+ - VR-PATTERN: bash scripts/massu-pattern-scanner.sh
124
+
125
+ AUDIT STEPS:
126
+ 1. Read the plan file from disk (not memory)
127
+ 2. Read .claude/CLAUDE.md for rules
128
+ 3. Extract ALL deliverables into a numbered list
129
+ 4. For EACH deliverable, verify:
130
+ a. Specificity: exact file path, exact changes, verification command
131
+ b. Feasibility: target files exist (or create is planned), patterns are correct
132
+ c. Completeness: all aspects covered (tool reg, tests, config if needed)
133
+ 5. Check pattern compliance matrix against CS patterns
134
+ 6. If adding tools: verify plan includes VR-TOOL-REG steps
135
+ 7. If modifying hooks: verify plan includes VR-HOOK-BUILD
136
+ 8. If changing config: verify plan includes VR-CONFIG
137
+ 9. Fix any gaps found in the plan document
138
+
139
+ CRITICAL INSTRUCTION FOR GAPS_DISCOVERED:
140
+ Report GAPS_DISCOVERED as the total number of gaps you FOUND during this pass,
141
+ EVEN IF you also fixed them. Finding 16 gaps and fixing all 16 = GAPS_DISCOVERED: 16.
142
+ A clean pass that finds nothing wrong from the start = GAPS_DISCOVERED: 0.
143
+
144
+ Return the structured result block at the end:
145
+ ---STRUCTURED-RESULT---
146
+ ITERATION: {iteration}
147
+ GAPS_DISCOVERED: [number]
148
+ GAPS_FIXED: [number]
149
+ GAPS_REMAINING: [number]
150
+ PLAN_ITEMS_TOTAL: [number]
151
+ PLAN_ITEMS_VERIFIED: [number]
152
+ ---END-RESULT---
153
+ ")
154
+
155
+ # Parse structured result
156
+ gaps = parse GAPS_DISCOVERED from result
157
+
158
+ # Report iteration to user
159
+ Output: "Iteration {iteration}: {gaps} gaps discovered"
160
+
161
+ IF gaps == 0:
162
+ Output: "AUDIT COMPLETE - Clean pass with zero gaps discovered in iteration {iteration}"
163
+ BREAK
164
+ ELSE:
165
+ Output: "{gaps} gaps discovered (and possibly fixed) in iteration {iteration}, starting fresh re-audit..."
166
+ CONTINUE
167
+ END WHILE
168
+ ```
169
+
170
+ ### Rules for the Loop Controller
171
+
172
+ | Rule | Meaning |
173
+ |------|---------|
174
+ | **NEVER output a final verdict while gaps discovered > 0** | Only a CLEAN zero-gap-from-start iteration produces the final report |
175
+ | **NEVER treat "found and fixed" as zero gaps** | Fixing during a pass still means gaps were discovered |
176
+ | **NEVER ask user "should I continue?"** | The loop is mandatory - just execute it |
177
+ | **NEVER stop after fixing gaps** | Fixing gaps requires a FRESH re-audit to verify the fixes |
178
+ | **ALWAYS use Task tool for audit passes** | Subagents keep context clean |
179
+ | **ALWAYS parse GAPS_DISCOVERED from result** | This is the loop control variable |
180
+ | **Maximum 10 iterations** | If still failing after 10, report to user with remaining gaps |
181
+
182
+ ---
183
+
184
+ ## Objective
185
+
186
+ Run a repeatable audit->fix->re-audit loop that verifies the entire plan against:
187
+ 1. **The Plan** (source of truth for requirements)
188
+ 2. **CLAUDE.md** (source of truth for rules, patterns, architecture constraints)
189
+
190
+ **CLAUDE.md is the ONLY authority on patterns. Do NOT infer patterns from the codebase.**
191
+
192
+ ---
193
+
194
+ ## CRITICAL: DUAL VERIFICATION REQUIREMENT
195
+
196
+ **This audit verifies BOTH plan quality AND plan feasibility.**
197
+
198
+ | Verification | What It Checks |
199
+ |--------------|----------------|
200
+ | **Plan Quality** | Is every deliverable specific, actionable, and verifiable? |
201
+ | **Plan Feasibility** | Can every deliverable actually be implemented? |
202
+
203
+ ---
204
+
205
+ ## PLAN ITEM EXTRACTION (MANDATORY FIRST STEP)
206
+
207
+ **Before auditing, you MUST extract ALL items from the plan into a trackable list.**
208
+
209
+ ### Extraction Protocol
210
+
211
+ #### Step 1: Read Plan Document (File, Not Memory)
212
+ ```bash
213
+ cat [PLAN_FILE_PATH]
214
+ ```
215
+
216
+ #### Step 2: Extract ALL Deliverables
217
+
218
+ ```markdown
219
+ ## PLAN ITEM EXTRACTION
220
+
221
+ ### Plan Document
222
+ - **File**: [path]
223
+ - **Title**: [title]
224
+
225
+ ### Extracted Items
226
+
227
+ | Item # | Type | Description | Expected Location | Verification Command |
228
+ |--------|------|-------------|-------------------|---------------------|
229
+ | P1-001 | MODULE | foo-tools.ts | packages/core/src/ | ls -la [path] |
230
+ | P1-002 | TOOL_WIRE | Wire into tools.ts | packages/core/src/tools.ts | grep [module] tools.ts |
231
+ | P2-001 | TEST | foo-tools.test.ts | packages/core/src/__tests__/ | npm test |
232
+
233
+ ### Coverage Baseline
234
+ - **Total Items**: [N]
235
+ - **Current Status**: 0/[N] verified (0%)
236
+ ```
237
+
238
+ ---
239
+
240
+ ## VR-PLAN-FEASIBILITY: Plan Reality Verification (MANDATORY)
241
+
242
+ **Before accepting ANY plan, verify the plan is REALISTIC and CAN be implemented.**
243
+
244
+ ### Feasibility Check Protocol
245
+
246
+ #### Check 1: File System Reality
247
+ For EACH file modification in the plan, verify the target exists:
248
+
249
+ ```bash
250
+ # For files plan says to MODIFY:
251
+ ls -la [file_path]
252
+
253
+ # For directories plan says to CREATE files in:
254
+ ls -la [directory_path]
255
+ ```
256
+
257
+ #### Check 2: Dependency Reality
258
+ For EACH new import/dependency in the plan:
259
+
260
+ ```bash
261
+ # Check if dependency is installed
262
+ npm list [package-name] 2>/dev/null || echo "NOT INSTALLED"
263
+
264
+ # Check if internal import path exists
265
+ ls -la packages/core/src/[import-path].ts
266
+ ```
267
+
268
+ #### Check 3: Pattern Reality
269
+ For EACH pattern the plan references:
270
+
271
+ ```bash
272
+ # Verify pattern is documented in CLAUDE.md
273
+ grep -n "[pattern_name]" .claude/CLAUDE.md
274
+ ```
275
+
276
+ #### Check 4: Tool Registration Completeness
277
+ If plan adds MCP tools:
278
+
279
+ ```bash
280
+ # Verify plan includes ALL 3 registration steps
281
+ grep "getToolDefinitions\|isXTool\|handleToolCall" [plan_file]
282
+ ```
283
+
284
+ ### Feasibility Gate
285
+
286
+ ```markdown
287
+ ### VR-PLAN-FEASIBILITY GATE
288
+
289
+ | Check | Items | Passed | Failed | Status |
290
+ |-------|-------|--------|--------|--------|
291
+ | File System | N | N | 0 | PASS |
292
+ | Dependencies | N | N | 0 | PASS |
293
+ | Patterns | N | N | 0 | PASS |
294
+ | Tool Registration | N | N | 0 | PASS |
295
+
296
+ **FEASIBILITY GATE: PASS / FAIL**
297
+ ```
298
+
299
+ ---
300
+
301
+ ## VR-PLAN-SPECIFICITY: Implementation Specificity Check (MANDATORY)
302
+
303
+ **Every plan item MUST have implementation details specific enough to execute WITHOUT guessing.**
304
+
305
+ | Requirement | Check |
306
+ |-------------|-------|
307
+ | **Exact file path** | Not "add a module" but `packages/core/src/foo.ts` |
308
+ | **Exact changes** | Not "export functions" but `getFooToolDefinitions, isFooTool, handleFooToolCall` |
309
+ | **Pattern reference** | Which existing module to follow as template |
310
+ | **Verification command** | Specific grep/ls that proves the item was implemented |
311
+
312
+ **Specificity by item type:**
313
+
314
+ | Type | Must Include |
315
+ |------|-------------|
316
+ | MODULE_CREATE | File path + exported functions + pattern reference |
317
+ | MODULE_MODIFY | File path + exact changes + insertion point |
318
+ | TOOL_WIRE | tools.ts changes (import + definition + handler) |
319
+ | TEST | Test file path + what it covers + expected assertions |
320
+ | CONFIG | config.ts interface changes + YAML example |
321
+ | HOOK | Hook file path + stdin/stdout format + esbuild compatibility |
322
+
323
+ ---
324
+
325
+ ## PATTERN COMPLIANCE MATRIX (Massu-Specific)
326
+
327
+ The auditor MUST verify plan items against these patterns:
328
+
329
+ | Pattern | Check | Expected |
330
+ |---------|-------|----------|
331
+ | ESM imports | No require() in plan code | 0 violations |
332
+ | Config access | getConfig() not direct YAML | Referenced correctly |
333
+ | Tool prefix | p() helper for tool names | All tool names use prefix |
334
+ | Tool registration | 3-function pattern | All 3 present per tool |
335
+ | Hook I/O | JSON stdin/stdout | Correct format |
336
+ | Test location | __tests__/ directory | Correct path |
337
+ | No process.exit() | Library code only | Not in plan modules |
338
+
339
+ ---
340
+
341
+ ## B-MCP: Tool Registration Verification
342
+
343
+ For EVERY tool in the plan:
344
+
345
+ ```markdown
346
+ ### Tool Registration Matrix
347
+
348
+ | Tool Name | getDefs() | isTool() | handleCall() | wired in tools.ts | Test | Status |
349
+ |-----------|-----------|----------|--------------|-------------------|------|--------|
350
+ | [name] | [file:line] | [file:line] | [file:line] | YES/NO | [test] | PASS/FAIL |
351
+ ```
352
+
353
+ **A tool that exists but is not registered is INVISIBLE to users.**
354
+
355
+ ---
356
+
357
+ ## B-HOOK: Hook Compilation Verification
358
+
359
+ If plan includes hooks:
360
+
361
+ ```markdown
362
+ ### Hook Compilation Matrix
363
+
364
+ | Hook | File | stdin format | stdout format | esbuild compatible | Status |
365
+ |------|------|-------------|---------------|-------------------|--------|
366
+ | [name] | [path] | [format] | [format] | YES/NO | PASS/FAIL |
367
+ ```
368
+
369
+ ---
370
+
371
+ ## B-CONFIG: Config Validation
372
+
373
+ If plan includes config changes:
374
+
375
+ ```markdown
376
+ ### Config Validation Matrix
377
+
378
+ | Config Section | Interface in config.ts | Example in YAML | Default value | Status |
379
+ |----------------|----------------------|-----------------|---------------|--------|
380
+ | [section] | YES/NO | YES/NO | [value] | PASS/FAIL |
381
+ ```
382
+
383
+ ---
384
+
385
+ ## FIX PROTOCOL
386
+
387
+ ### Fix Queue (by severity)
388
+
389
+ | Priority | Definition |
390
+ |----------|------------|
391
+ | **P0** | Missing deliverables, impossible items, security issues |
392
+ | **P1** | Vague/unverifiable items, missing verification commands |
393
+ | **P2** | Minor specificity gaps, formatting issues |
394
+
395
+ ### For Each Fix
396
+ 1. Edit the plan document directly
397
+ 2. Add missing detail or correct errors
398
+ 3. Mark the fix with a comment: `<!-- Fixed in audit iteration N -->`
399
+
400
+ ---
401
+
402
+ ## PLAN DOCUMENT COMPLETION TRACKING (MANDATORY)
403
+
404
+ When audit completes, update the plan document itself with a completion table at TOP:
405
+
406
+ ```markdown
407
+ # IMPLEMENTATION STATUS
408
+
409
+ **Plan**: [Name] | **Status**: COMPLETE/PARTIAL/NOT STARTED | **Last Audited**: [date]
410
+
411
+ | # | Task/Phase | Status | Verification | Date |
412
+ |---|------------|--------|--------------|------|
413
+ | 1 | [Task] | 100% COMPLETE | VR-GREP: 0 refs | [date] |
414
+ | 2 | [Task] | PARTIAL (40%) | 5/12 done | [date] |
415
+ ```
416
+
417
+ Checklist: completion table at TOP, all tasks have status, completed tasks have evidence, partial tasks show progress, dates recorded, plan status reflects reality.
418
+
419
+ ---
420
+
421
+ ## CONTEXT MANAGEMENT
422
+
423
+ Use Task tool with subagents for exploration. Update session-state/CURRENT.md after major phases. If compacted mid-protocol, read CURRENT.md and resume. Never mix unrelated tasks during a protocol.
424
+
425
+ ---
426
+
427
+ ## SESSION STATE UPDATE
428
+
429
+ After EACH iteration, update `session-state/CURRENT.md` with: audit iteration, status, gap summary (P0/P1/P2), verified work with file paths, next focus.
430
+
431
+ ---
432
+
433
+ ## COMPLETION REPORT
434
+
435
+ ```markdown
436
+ ## CS PLAN AUDIT COMPLETE
437
+
438
+ ### Audit Summary
439
+ - **Plan**: [path]
440
+ - **Total Items**: [N]
441
+ - **Iterations**: [N]
442
+ - **Final Status**: ZERO GAPS
443
+
444
+ ### Verification Results
445
+ | Check | Status |
446
+ |-------|--------|
447
+ | Plan Feasibility | PASS |
448
+ | Plan Specificity | PASS |
449
+ | Pattern Compliance | PASS |
450
+ | Tool Registration (if applicable) | PASS |
451
+ | Hook Compilation (if applicable) | PASS |
452
+ | Config Validation (if applicable) | PASS |
453
+
454
+ ### Next Steps
455
+ 1. Run `/massu-loop [plan-path]` to implement with verification
456
+ ```