maxsimcli 4.4.0 → 4.5.0

package/dist/assets/templates/workflows/realign.md

@@ -0,0 +1,288 @@
+<sanity_check>
+Before executing any step in this workflow, verify:
+1. The current directory contains a `.planning/` folder -- if not, stop and tell the user to run `/maxsim:new-project` first.
+2. `.planning/DRIFT-REPORT.md` exists -- if not, stop and tell the user to run `/maxsim:check-drift` first.
+</sanity_check>
+
+<purpose>
+Correct spec-code divergence in either direction. Realign-to-code updates `.planning/` to match the actual codebase. Realign-to-spec generates new fix phases to make code match the spec. Reads the DRIFT-REPORT.md produced by `/maxsim:check-drift`.
+</purpose>
+
+<core_principle>
+This is an interactive orchestrator workflow, not an agent spawn. Realign-to-code requires per-item user decisions (Accept/Skip/Edit). Realign-to-spec requires user approval of proposed phase groupings. The workflow drives the interaction directly.
+</core_principle>
+
+<required_reading>
+Read STATE.md before any operation to load project context.
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context and validate prerequisites:
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init realign "$DIRECTION")
+```
+
+Parse JSON for: `has_report`, `has_planning`, `report_path`, `state_path`, `requirements_path`, `roadmap_path`, `phase_dirs`, `current_phase`, `commit_docs`.
+
+**Validation gates:**
+- If `has_planning` is false: "No `.planning/` directory found. Run `/maxsim:new-project` first." STOP.
+- If `has_report` is false: "No DRIFT-REPORT.md found. Run `/maxsim:check-drift` first to generate a drift report." STOP.
+</step>
+
+<step name="read_report">
+Read the drift report metadata and content:
+
+```bash
+REPORT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs drift read-report)
+```
+
+Parse the result to extract:
+- **Frontmatter:** `status`, `critical_count`, `warning_count`, `info_count`, `undocumented_count`, `total_items`, `aligned_count`
+- **Body sections:** "Spec Ahead of Code", "Code Ahead of Spec", "No-Go Violations", "Undocumented Features"
+
+**If `status` is `aligned`:**
+```
+No drift detected -- nothing to realign. All spec items match the codebase.
+```
+STOP.
+</step>
+
+<step name="select_direction">
+Determine the realignment direction.
+
+**If `$DIRECTION` was provided via `$ARGUMENTS`:** Use it directly. Validate it is either `to-code` or `to-spec`.
+
+**If no direction was provided:** Present the user with a choice:
+
+```markdown
+## Drift Report Summary
+
+**Status:** {critical_count} critical | {warning_count} warning | {info_count} info | {undocumented_count} undocumented
+
+Choose a realignment direction:
+
+1. **to-code** -- Update `.planning/` to match current codebase (spec follows code)
+   Best when: Code is correct and spec is outdated. Accepts code reality.
+
+2. **to-spec** -- Generate fix phases to make code match spec (code follows spec)
+   Best when: Spec is correct and code has gaps. Creates implementation phases.
+```
+
+Wait for user selection.
+</step>
+
+<step name="realign_to_code">
+**Execute only if direction is `to-code`.**
+
+Parse the drift report body to extract all drifted items from:
+- "Spec Ahead of Code" section (requirements marked complete but code missing/incomplete)
+- "Code Ahead of Spec" section (features in code but not captured in spec)
+- "No-Go Violations" section (code violating declared constraints)
+- "Undocumented Features" section (features with no spec coverage)
+
+Build a list of actionable items. For each item, extract:
+- Requirement ID (if applicable)
+- Section heading/description
+- Current spec text and location
+- What was found (or not found) in code
+- The report's fix recommendation
+- All spec file references from the evidence section
+
+**Process each item interactively:**
+
+For each drifted item, present it to the user:
+
+```markdown
+### Item {N}/{total}: {Requirement ID or Feature Name}
+
+**Severity:** {CRITICAL | WARNING | INFO}
+**Direction:** {Spec ahead of code | Code ahead of spec | No-go violation | Undocumented}
+
+**Current spec:** {spec text from report}
+**Code reality:** {what was found or not found}
+**Recommendation:** {fix recommendation from report}
+
+**Affected spec files:** {list of files that reference this item}
+
+Choose:
+- **Accept** -- Apply the recommended spec change
+- **Skip** -- Leave as-is (no changes for this item)
+- **Edit** -- Provide a custom change description
+```
+
+Wait for user response.
+
+**Apply accepted changes based on item direction:**
+
+**For "Spec ahead of code" items** (requirement marked done but code missing):
+- Update REQUIREMENTS.md: change `[x]` to `[ ]` for the requirement using `node ~/.claude/maxsim/bin/maxsim-tools.cjs requirements mark-incomplete {REQ_ID}`, or manually edit the checkbox if the tool does not support it.
+- Check ROADMAP.md: if the requirement appears in success criteria for a phase, add a note that the criterion is unmet.
+- Check STATE.md: if a decision references this requirement, add a note that the implementation is pending.
+- Check phase SUMMARY.md files: if any summary claims this requirement was completed, add a caveat note.
+
+**For "Code ahead of spec" items** (feature exists but spec does not mention it):
+- If user accepts the default recommendation: add the feature as a new requirement in REQUIREMENTS.md under the appropriate version section.
+- If user provides an edit: apply their custom text instead.
+- Update PROJECT.md if the feature represents a significant capability not documented there.
+
+**For "No-go violation" items** (code violating a declared constraint):
+- Document as known tech debt in STATE.md under "Blockers/Concerns" or a "Known Tech Debt" section.
+- Optionally mark for future fix phase.
+
+**For "Undocumented feature" items** (code with no spec coverage):
+- Add to REQUIREMENTS.md as a new entry documenting the existing capability.
+- Or update PROJECT.md to document it as an existing capability, depending on user's edit.
+
+**CRITICAL -- Multi-file consistency:** For each accepted item, identify ALL spec files that reference it (from the drift report evidence section) and update all of them. Do NOT update only REQUIREMENTS.md while leaving ROADMAP.md or STATE.md inconsistent. Use the spec file references in the drift report as the update checklist.
+
+Track changes: maintain a running count of accepted, skipped, and edited items, and a list of all modified files.
+
+**After processing all items:**
+
+Check if any phase now has all success criteria met in code. For each phase referenced in the drift report:
+
+```bash
+# Check if phase criteria are now all satisfied
+PHASE_STATUS=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "{phase_number}")
+```
+
+If all criteria for a phase are met after the realignment updates, auto-mark that phase complete:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs phase complete "{phase_number}"
+```
+
+**If ALL items were skipped:** "No changes applied. Drift report remains unchanged." STOP (do not commit).
+
+**Commit changes:**
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: realign spec to match codebase" --files {space-separated list of all modified files}
+```
+</step>
+
+<step name="realign_to_spec">
+**Execute only if direction is `to-spec`.**
+
+Parse the drift report to extract all "Spec Ahead of Code" items -- requirements and success criteria that are specified but not yet implemented in code. Also include any "No-Go Violations" that require code changes.
+
+Build a list of implementation gaps. For each gap, extract:
+- Requirement ID
+- Description of what needs to be implemented
+- Current spec location (file and section)
+- Evidence of what is missing from the report
+
+**Group gaps into phases using this algorithm:**
+
+1. **Group by requirement prefix:** Collect all gaps sharing a requirement prefix (e.g., all `DRIFT-*` gaps into one phase, all `INIT-*` into another, all `ROT-*` into another). The prefix is the text before the hyphen and number in the requirement ID.
+
+2. **If no prefix grouping possible** (gaps have no requirement IDs or all have unique prefixes): group by affected subsystem. Cluster gaps whose evidence references common file paths or directories.
+
+3. **Apply the 5-phase cap:**
+   - If 5 or fewer groups: use them as-is.
+   - If more than 5 groups: sort groups by gap count (ascending). Merge the smallest groups into a "Remaining Gaps" phase until only 5 groups remain.
+
+4. **Minimum group size:** Each phase should have at minimum 2 gaps, unless it is the only group or merging is not possible.
+
+5. **Name each phase** descriptively: "{Prefix} Implementation Gaps" or "{Subsystem} Fixes" or similar concise name.
+
+**Present proposed phases to user:**
+
+```markdown
+## Proposed Realignment Phases
+
+Based on the drift report, {gap_count} implementation gaps will be organized into {phase_count} new phases inserted after the current active phase ({current_phase}).
+
+| # | Phase Name | Requirements | Gap Count | Description |
+|---|-----------|-------------|-----------|-------------|
+| 1 | {name} | {REQ-01, REQ-02} | {N} | {brief description} |
+| 2 | {name} | {REQ-03} | {N} | {brief description} |
+
+Approve this breakdown? (yes / suggest changes)
+```
+
+Wait for user approval. If user suggests changes, adjust the grouping accordingly.
+
+**For each approved phase, insert after the current active phase:**
+
+```bash
+RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs phase insert "{current_phase}" "{phase_name}")
+```
+
+The insert command creates the phase directory with decimal numbering (e.g., `04.1`, `04.2`) and updates ROADMAP.md.
+
+**For each inserted phase, update the ROADMAP.md phase section** to include:
+- The requirement IDs covered by this phase
+- Success criteria extracted from the drift report (what needs to be implemented)
+- A brief goal statement
+
+Use the Edit tool to add requirement details and success criteria to each newly created phase entry in ROADMAP.md.
+
+**Commit changes:**
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "feat: add realignment phases from drift report" --files .planning/ROADMAP.md .planning/STATE.md
+```
+
+Note: Include any new phase directories created by the insert commands in the commit files list.
+</step>
+
+<step name="summary">
+Display a summary of what was changed.
+
+**For realign-to-code:**
+
+```markdown
+## Realignment Complete (to-code)
+
+**Items processed:** {total}
+- Accepted: {accepted_count}
+- Skipped: {skipped_count}
+- Edited: {edited_count}
+
+**Files modified:** {list of modified files}
+**Phases auto-completed:** {list of phases marked complete, or "None"}
+**Commit:** {commit hash}
+
+The spec now reflects the current codebase state for the accepted items.
+Skipped items remain as drift -- run `/maxsim:check-drift` again to see remaining drift.
+```
+
+**For realign-to-spec:**
+
+```markdown
+## Realignment Complete (to-spec)
+
+**Implementation gaps:** {gap_count}
+**New phases created:** {phase_count}
+
+| Phase | Name | Requirements |
+|-------|------|-------------|
+| {num} | {name} | {REQ IDs} |
+
+**Next step:** Run `/maxsim:execute-phase {first_new_phase}` to begin implementing the gaps.
+```
+</step>
+
+</process>
+
+<error_handling>
+- **DRIFT-REPORT.md missing:** Direct user to run `/maxsim:check-drift` first. Do not attempt to generate a report.
+- **Report status is "aligned":** Nothing to do. Inform user and stop.
+- **All items skipped (to-code):** No changes made. Inform user that drift remains.
+- **Zero "Spec Ahead of Code" gaps (to-spec):** Inform user "All specified items appear implemented. No fix phases needed. Consider realign-to-code instead to capture undocumented features."
+- **Phase insert fails:** Report the error. Continue with remaining phases if possible. Document any failures in the summary.
+- **Invalid direction argument:** Show usage: `/maxsim:realign [to-code | to-spec]`
+</error_handling>
+
+<critical_rules>
+- **Item-by-item approval for to-code:** Never batch-apply changes. Present each item individually and wait for Accept/Skip/Edit.
+- **Multi-file consistency:** When updating spec for an accepted item, update ALL referencing spec files, not just REQUIREMENTS.md. Use the evidence section from the drift report to identify all affected files.
+- **Phase cap for to-spec:** Never create more than 5 new phases. Group and merge as described in the algorithm.
+- **Insert after current phase:** New phases go after the current active phase, not at the end of the roadmap.
+- **No auto-generation of reports:** This workflow reads an existing DRIFT-REPORT.md. It does not run drift detection itself.
+- **Auto-complete phases:** After realign-to-code, check if any phase has all criteria met and auto-mark it complete.
+</critical_rules>

package/dist/assets/templates/workflows/roadmap.md

@@ -1,5 +1,5 @@
 <purpose>
-Render the project roadmap in a readable format with phase status icons and plan progress counts. Read-only — does not modify any files.
+Render the project roadmap in a readable format with phase status icons and plan progress counts. Auto-collapses completed phases to one-liners for visual clarity and paginates at 20 phases per page for large projects. Read-only — does not modify any files.
 </purpose>
 
 <process>
@@ -16,6 +16,8 @@ Parse JSON. If `planning_exists` is false, hard stop:
 > No roadmap found. Run /maxsim:new-project to initialize.
 
 Exit immediately. Do not continue.
+
+**Parse `--page` argument:** If the command was invoked with `--page N`, extract the page number (default: 1). This controls which page of phases to display when total phases exceed 20.
 </step>
 
 <step name="analyze">
@@ -43,31 +45,74 @@ Print the roadmap to the terminal.
 
 **Blank line.**
 
-**Per-phase lines (in numeric order):**
+**Auto-collapse completed phases (always active, regardless of phase count):**
 
-For each phase in `phases[]`:
-- `disk_status === 'complete'` → icon `✓`, label `DONE`
-- `disk_status === 'partial'` → icon `►`, label `IN PROGRESS`
-- `disk_status === 'planned' || 'empty' || 'discussed' || 'researched' || 'no_directory'` → icon `□`, label `PLANNED`
+Render phases in two visual groups:
 
-Format per line:
-```
-{icon}  Phase {number}: {name}    {label}  ({summary_count}/{plan_count} plans)
-```
+1. **Completed phases** — collapsed one-liners with no plan counts or status label:
+   ```
+   ✓  Phase {number}: {name}
+   ```
+   Just checkmark + phase number + name. One line per completed phase. This keeps the roadmap scannable when many phases are done.
+
+2. **Active and upcoming phases** — full detail format with icon, label, and plan counts:
+   ```
+   {icon}  Phase {number}: {name}    {label}  ({summary_count}/{plan_count} plans)
+   ```
 
-Pad phase names with spaces so status labels align in a column.
+For active/upcoming phases:
+- `disk_status === 'partial'` -> icon `>`, label `IN PROGRESS`
+- `disk_status === 'planned' || 'empty' || 'discussed' || 'researched' || 'no_directory'` -> icon `[ ]`, label `PLANNED`
+
+Pad phase names with spaces so status labels align in a column (within the active/upcoming group only).
 
 Only show `({summary_count}/{plan_count} plans)` when `plan_count > 0`.
 
-Example output:
+**Pagination (only when total phases exceed 20):**
+
+After assembling all phase lines (both collapsed completed and full-detail active/upcoming), check the total phase count:
+
+- If total phases is **20 or fewer**: show all phases. No pagination footer. This is the default experience for small/medium projects.
+- If total phases **exceeds 20**: apply pagination.
+  - Page size: 20 phases per page.
+  - Use the `--page N` argument (default page 1) to determine which slice to show.
+  - Calculate: `first = (page - 1) * 20 + 1`, `last = min(page * 20, total)`.
+  - Show only phases from index `first` to `last`.
+  - Add a footer line after the phase list:
+    ```
+    Showing phases {first}-{last} of {total}. Use --page {next_page} for next.
+    ```
+  - If on the last page, omit the "Use --page" hint.
+
+Example output (small project, no pagination):
 ```
-NX Monorepo Migration — 5 done / 1 active / 6 planned
+Context-Aware SDD — 3 done / 1 active / 1 planned
+
+✓  Phase 1: Context Rot Prevention
+✓  Phase 2: Init Flow Overhaul
+✓  Phase 3: Agent Coherence
+
+>  Phase 4: Spec Drift Management        IN PROGRESS  (2/3 plans)
+[ ]  Phase 5: Workflow Coverage             PLANNED
+```
+
+Example output (large project with pagination, page 1):
+```
+NX Monorepo Migration — 15 done / 1 active / 9 planned
+
+✓  Phase 01: NX Workspace Scaffold
+✓  Phase 02: packages/core TypeScript Port
+✓  Phase 03: Shared Types
+...
+✓  Phase 15: CI Pipeline
+
+>  Phase 16: Dashboard Rewrite              IN PROGRESS  (2/5 plans)
+[ ]  Phase 17: Plugin System                  PLANNED
+[ ]  Phase 18: Performance Optimization       PLANNED
+[ ]  Phase 19: Documentation                  PLANNED
+[ ]  Phase 20: Security Audit                 PLANNED
 
-✓  Phase 01: NX Workspace Scaffold                    DONE       (4/4 plans)
-✓  Phase 02: packages/core TypeScript Port            DONE       (6/6 plans)
-►  Phase 09: End-to-end install and publish test loop IN PROGRESS (2/3 plans)
-□  Phase 11: Remove Discord command                   PLANNED
-□  Phase 12: UX Polish + Core Hardening               PLANNED
+Showing phases 1-20 of 25. Use --page 2 for next.
 ```
 </step>
 
@@ -75,7 +120,11 @@ NX Monorepo Migration — 5 done / 1 active / 6 planned
 
 <success_criteria>
 - [ ] Milestone summary header rendered with done/active/planned counts
-- [ ] All phases listed in numeric order with correct icon and label
-- [ ] Plan progress shown inline for phases that have plans
+- [ ] Completed phases auto-collapsed to one-liners (checkmark + name only, no plan counts)
+- [ ] Active/upcoming phases shown with full detail (icon, label, plan counts)
+- [ ] Phases listed in numeric order within each group
+- [ ] Pagination footer shown only when total phases exceed 20
+- [ ] `--page N` argument controls which page to display
+- [ ] Plan progress shown inline for active/upcoming phases that have plans
 - [ ] Hard stop if .planning/ is missing
 </success_criteria>

package/dist/backend-server.cjs

@@ -32122,17 +32122,17 @@ var require_view = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	* @private
 	*/
 	var debug = require_src$3()("express:view");
-	var path$22 = require("path");
-	var fs$20 = require("fs");
+	var path$23 = require("path");
+	var fs$21 = require("fs");
 	/**
 	* Module variables.
 	* @private
 	*/
-	var dirname = path$22.dirname;
-	var basename = path$22.basename;
-	var extname = path$22.extname;
-	var join = path$22.join;
-	var resolve = path$22.resolve;
+	var dirname = path$23.dirname;
+	var basename = path$23.basename;
+	var extname = path$23.extname;
+	var join = path$23.join;
+	var resolve = path$23.resolve;
 	/**
 	* Module exports.
 	* @public
@@ -32229,7 +32229,7 @@ var require_view = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	function tryStat(path) {
 		debug("stat \"%s\"", path);
 		try {
-			return fs$20.statSync(path);
+			return fs$21.statSync(path);
 		} catch (e) {
 			return;
 		}
@@ -34450,7 +34450,7 @@ var require_types$1 = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#region ../../node_modules/send/node_modules/mime/mime.js
 var require_mime = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	require("path");
-	var fs$19 = require("fs");
+	var fs$20 = require("fs");
 	function Mime() {
 		this.types = Object.create(null);
 		this.extensions = Object.create(null);
@@ -34485,7 +34485,7 @@ var require_mime = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	Mime.prototype.load = function(file) {
 		this._loading = file;
 		var map = {};
-		fs$19.readFileSync(file, "ascii").split(/[\r\n]+/).forEach(function(line) {
+		fs$20.readFileSync(file, "ascii").split(/[\r\n]+/).forEach(function(line) {
 			var fields = line.replace(/\s*#.*|^\s*|\s*$/g, "").split(/\s+/);
 			map[fields.shift()] = fields;
 		});
@@ -34764,12 +34764,12 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var escapeHtml = require_escape_html();
 	var etag = require_etag();
 	var fresh = require_fresh();
-	var fs$18 = require("fs");
+	var fs$19 = require("fs");
 	var mime = require_mime();
 	var ms = require_ms();
 	var onFinished = require_on_finished();
 	var parseRange = require_range_parser();
-	var path$21 = require("path");
+	var path$22 = require("path");
 	var statuses = require_statuses();
 	var Stream = require("stream");
 	var util$3 = require("util");
@@ -34777,11 +34777,11 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	* Path function references.
 	* @private
 	*/
-	var extname = path$21.extname;
-	var join = path$21.join;
-	var normalize = path$21.normalize;
-	var resolve = path$21.resolve;
-	var sep = path$21.sep;
+	var extname = path$22.extname;
+	var join = path$22.join;
+	var normalize = path$22.normalize;
+	var resolve = path$22.resolve;
+	var sep = path$22.sep;
 	/**
 	* Regular expression for identifying a bytes Range header.
 	* @private
@@ -35229,7 +35229,7 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		var i = 0;
 		var self = this;
 		debug("stat \"%s\"", path);
-		fs$18.stat(path, function onstat(err, stat) {
+		fs$19.stat(path, function onstat(err, stat) {
 			if (err && err.code === "ENOENT" && !extname(path) && path[path.length - 1] !== sep) return next(err);
 			if (err) return self.onStatError(err);
 			if (stat.isDirectory()) return self.redirect(path);
@@ -35240,7 +35240,7 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 			if (self._extensions.length <= i) return err ? self.onStatError(err) : self.error(404);
 			var p = path + "." + self._extensions[i++];
 			debug("stat \"%s\"", p);
-			fs$18.stat(p, function(err, stat) {
+			fs$19.stat(p, function(err, stat) {
 				if (err) return next(err);
 				if (stat.isDirectory()) return next();
 				self.emit("file", p, stat);
@@ -35264,7 +35264,7 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 			}
 			var p = join(path, self._index[i]);
 			debug("stat \"%s\"", p);
-			fs$18.stat(p, function(err, stat) {
+			fs$19.stat(p, function(err, stat) {
 				if (err) return next(err);
 				if (stat.isDirectory()) return next();
 				self.emit("file", p, stat);
@@ -35283,7 +35283,7 @@ var require_send = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	SendStream.prototype.stream = function stream(path, options) {
 		var self = this;
 		var res = this.res;
-		var stream$5 = fs$18.createReadStream(path, options);
+		var stream$5 = fs$19.createReadStream(path, options);
 		this.emit("stream", stream$5);
 		stream$5.pipe(res);
 		function cleanup() {
@@ -38817,7 +38817,7 @@ var require_response = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var http$3 = require("http");
 	var isAbsolute = require_utils$1().isAbsolute;
 	var onFinished = require_on_finished();
-	var path$20 = require("path");
+	var path$21 = require("path");
 	var statuses = require_statuses();
 	var merge = require_utils_merge();
 	var sign = require_cookie_signature().sign;
@@ -38826,9 +38826,9 @@ var require_response = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var setCharset = require_utils$1().setCharset;
 	var cookie = require_cookie();
 	var send = require_send();
-	var extname = path$20.extname;
+	var extname = path$21.extname;
 	var mime = send.mime;
-	var resolve = path$20.resolve;
+	var resolve = path$21.resolve;
 	var vary = require_vary();
 	/**
 	* Response prototype.
@@ -74966,6 +74966,14 @@ function parseTodoFrontmatter(content) {
 * Ported from maxsim/bin/lib/verify.cjs
 */
 
+//#endregion
+//#region src/core/drift.ts
+/**
+* Drift — Drift report CRUD, requirement extraction, and spec extraction
+*
+* Provides CLI tool commands for the drift-checker agent and realign workflow.
+*/
+
 //#endregion
 //#region src/core/phase.ts
 /**
@@ -79004,14 +79012,22 @@ function registerPhaseTools(server) {
 			return mcpError(e.message, "Operation failed");
 		}
 	});
-	server.tool("mcp_list_phases", "List all phase directories, sorted correctly. Optionally include archived phases from milestones.", { include_archived: booleanType().optional().default(false).describe("Include archived phases from completed milestones") }, async ({ include_archived }) => {
+	server.tool("mcp_list_phases", "List phase directories with pagination. Returns sorted phases with offset/limit support.", {
+		include_archived: booleanType().optional().default(false).describe("Include archived phases from completed milestones"),
+		offset: numberType().optional().default(0).describe("Number of phases to skip (for pagination)"),
+		limit: numberType().optional().default(20).describe("Maximum number of phases to return")
+	}, async ({ include_archived, offset, limit }) => {
 		try {
 			const cwd = detectProjectRoot();
 			if (!cwd) return mcpError("No .planning/ directory found", "Project not detected");
 			const phasesDir = phasesPath(cwd);
 			if (!node_fs.default.existsSync(phasesDir)) return mcpSuccess({
 				directories: [],
-				count: 0
+				count: 0,
+				total_count: 0,
+				offset,
+				limit,
+				has_more: false
 			}, "No phases directory found");
 			let dirs = listSubDirs(phasesDir);
 			if (include_archived) {
@@ -79019,10 +79035,17 @@ function registerPhaseTools(server) {
 				for (const a of archived) dirs.push(`${a.name} [${a.milestone}]`);
 			}
 			dirs.sort((a, b) => comparePhaseNum(a, b));
+			const total_count = dirs.length;
+			const paginated = dirs.slice(offset, offset + limit);
+			const has_more = offset + limit < total_count;
 			return mcpSuccess({
-				directories: dirs,
-				count: dirs.length
-			}, `Found ${dirs.length} phase(s)`);
+				directories: paginated,
+				count: paginated.length,
+				total_count,
+				offset,
+				limit,
+				has_more
+			}, `Showing ${paginated.length} of ${total_count} phase(s)`);
 		} catch (e) {
 			return mcpError(e.message, "Operation failed");
 		}