feat: Add end-of-day session cleanup as MCP tool

- Create tools/mcp-server/src/handlers/end-of-day.ts handler
- Register end_of_day_session_cleanup MCP tool in MCP server
- Expose modes: report (default), commit, push with confirmation gating
- Return structured check results: 4X4.md, CHANGELOG.md, MEMORY.md, build validation
- Include git state reporting: branch, modified files, untracked files
- Support dryRun, force, skipValidation flags for automation
- Update MCP server version to 0.9.0
- Update tools/mcp-server/README.md with tool documentation
- Update tools/mcp-server/package.json version and description
- Update main CHANGELOG.md with MCP tool entry

Author: noelsaw1

4X4.md

@@ -1,10 +1,10 @@
 ---
 client: Hypercart Dev Tools
 repo: https://github.com/Hypercart-Dev-Tools/AI-DDTK
-last_edit: 2026-03-24
-week_of: 2026-03-24
+last_edit: 2026-04-05
+week_of: 2026-04-05
 source_pr_number: n/a
-sprint: Playwright Auth helper (pw-auth)
+sprint: Core tooling hardening and experimental promotion
 
 ---
 
@@ -16,17 +16,17 @@ A simple, actionable framework to prioritize and track engineering tasks. Focus
 # About the Current Project
 AI-DDTK (AI Driven Development ToolKit) is a central, install-once toolkit used across WordPress projects to standardize AI agent guidance, security practices, and developer workflows (e.g., WPCC scanning, runtime perf profiling, AJAX endpoint testing).
 
-This week’s focus is adding passwordless Playwright auth for WP admin (`pw-auth`) to enable AI agents to drive headless browser automation without hardcoded credentials.
+This week’s focus is shipping core tooling improvements (.wpcignore, servers-audit promotion) and reducing the gap between experimental tooling and mainline.
 
 ---
 
 ## 1. Strategic Backlog
 **Maximum of 4 items. Focus on long-term goals and impactful improvements.**
 
-1. - [ ] Ship native `.wpcignore` support in WPCC (reduce recursive scans; unblock repo-wide scanning)
+1. - [x] Ship native `.wpcignore` support in WPCC (reduce recursive scans; unblock repo-wide scanning)
 2. - [x] Weekly UX audit now automated via CI ([recipe](recipes/weekly-ux-audit.md)) — version drift, doc parity, and link checks run every Monday; failures create GitHub issues
 3. - [ ] Prove the experimental crash-loop workflow on 2-3 projects before promoting it beyond `experimental/`
-4. - [ ] Continue release hygiene improvements (consistent SemVer sections, lightweight summaries)
+4. - [x] Release hygiene: CHANGELOG restructured (no Unreleased, maintainer rules, consistent SemVer blocks)
 
 ---
 
@@ -35,30 +35,30 @@ This week’s focus is adding passwordless Playwright auth for WP admin (`pw-aut
 
 > **Tip:** If your team frequently handles urgent issues, consider reserving 1-2 slots for hotfixes. Otherwise, use all 4 slots for planned work.
 
-- [x] Refactor bin/pw-auth to improve maintainability by externalizing embedded helper scripts (Phase 1).
-
-- [ ] Formalize Valet clone-lab as an optional recipe (macOS-only) with clear guardrails and no core-toolset promotion
+- [x] Implement `.wpcignore` support in WPCC `check-performance.sh` (gitignore-style file filtering)
+- [x] Promote `servers-audit.sh` and `servers-preflight.sh` from `experimental/` to `tools/`
+- [x] VS Code extension v0.2.0 — dynamic MCP server discovery with file watchers
+- [ ] Prove crash-loop workflow on 2-3 real projects
 
 ---
 
 ## 3. Previous Week
 **Review completed, deferred, or blocked tasks from the prior week.**
 
-- [x] Validate the tmux workflow end-to-end on a machine where `tmux` is installed (v1.0.7)
-- [x] Move the theme crash-loop workflow into `experimental/theme-crash-loop.sh` (v1.0.7)
-- [x] Standardize crash-loop artifacts under the target project `/temp` folder and add optional `--tmux` mode (v1.0.7)
-- [x] Update README.md, CHANGELOG.md, and the dashboard for the experimental workflow (v1.0.7)
+- [x] Refactor bin/pw-auth to improve maintainability by externalizing embedded helper scripts
+- [x] Formalize Valet clone-lab as an optional recipe (macOS-only) with guardrails
+- [x] `project.sh` v1.5 — secrets scanner, scrub command, filename normalization, robustness fixes
+- [x] `servers-audit.sh` — Launchd plist parsing, KeepAlive conflict detection, expanded TLD coverage
 
 ---
 
 ## 4. Recent Lessons Learned
 **Capture insights to improve processes and avoid repeating mistakes.**
 
-1. Externalizing embedded helper scripts (e.g., from bash into separate `.js` files) is a low-risk, high-reward first step in a larger refactor. It immediately improves syntax highlighting, linting, and code isolation without changing the core logic.
-2. Unit tests that mock shell execution are good for verifying a script's *interface* (arguments, output), but they don't confirm the script's *functionality*. End-to-end testing, even via a simple manual `doctor` command, is necessary to ensure the refactored script still works.
-3. A well-built `doctor` command in a CLI tool is an invaluable asset for both development and testing, providing a quick way to verify environment-dependent functionality.
-4. Never use `eval` with user-controlled strings in shell scripts — bash arrays with `"${arr[@]}"` invocation are safer and just as flexible.
-5. `.mjs` files run as ESM — `require()` is CJS-only. Use `.js` extension for scripts that need `require()`.
+1. Dropping the `[Unreleased]` CHANGELOG section eliminated friction without losing signal — at current velocity, versioned blocks on commit are more useful than a batched unreleased bucket.
+2. Experimental scripts that receive 4+ consecutive hardening commits are no longer experimental — promote them to reduce confusion about maturity.
+3. The VS Code extension's real value is zero-config workspace onboarding (MCP server auto-discovery), not wrapping terminal commands with UI chrome.
+4. `.wpcignore` should have shipped much earlier — the placeholder file existed but was never wired in, leaving WPCC unable to do repo-wide scans without false positives from `tools/`, `temp/`, etc.
 
 ---
 

CHANGELOG.md

@@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Native `.wpcignore` support in WPCC** — `check-performance.sh` now loads gitignore-style patterns from a `.wpcignore` file and filters the PHP file list before scanning. Auto-detects `.wpcignore` in the scan target directory or current working directory. Supports directory patterns (`tools/`), extension globs (`*.min.js`), and literal substring matches. New flags: `--wpcignore-file <path>` for explicit file, `--no-wpcignore` to disable. Unblocks repo-wide scanning without false positives from embedded tools, temp files, and vendor directories.
 - **VS Code extension dynamic MCP discovery (v0.2.0)** — the extension's MCP server definition provider now merges configs from 5 layers (static AI-DDTK fallback, workspace `.mcp.json`, `.vscode/mcp.json`, `.mcp.local.json`, `temp/mcp/local-snippets/*.json`) with file watchers for live re-discovery. Site-specific WP MCP Adapter servers are automatically provided to all VS Code MCP clients without manual wiring or restart.
 - **`experimental/end-of-day.sh` — solo developer session cleanup script** — automated script for end-of-work synchronization. Checks 4X4.md, CHANGELOG.md, and MEMORY.md freshness; archives session-scoped MEMORY.md to `PROJECT/1-INBOX/MEMORY-<timestamp>.md` for clean sessions. Supports `--commit` (with confirmation), `--push` (implies commit, with confirmation), `--force` (skip prompts for automation), `--dry-run`, and agent hook integration for orchestration. Default mode reports findings only; opt-in flags enable commit/push. Includes build validation (PHP syntax check) and structured event emission for agent coordination.
+- **MCP tool: `end_of_day_session_cleanup`** — expose end-of-day.sh as a typed MCP tool (v0.9.0). Agents can call `end_of_day_session_cleanup` with `mode` (report/commit/push), `dryRun`, `force`, `skipValidation` flags. Returns structured check results (4X4.md, CHANGELOG.md, MEMORY.md, build validation), git state (branch, modified files, untracked), and command exit code. Enables VS Code agents to orchestrate session cleanup without shell escaping.
 
 ### Changed
 - **`servers-audit.sh` and `servers-preflight.sh` promoted to `tools/`** — moved from `experimental/` to `tools/` alongside `servers.md` template. These scripts have received 4+ consecutive hardening releases (Launchd plist parsing, KeepAlive detection, expanded TLD coverage, Valet site discovery) and are no longer experimental. Internal path references (`$SCRIPT_DIR`) are relative and required no changes. CLI-REFERENCE.md updated with new sections for both scripts.

docs/CLI-REFERENCE.md

@@ -1,6 +1,6 @@
 # AI-DDTK CLI Reference
 
-Complete command reference for all AI-DDTK tools: `pw-auth`, `wpcc`, `local-wp`, `wp-ajax-test`, `aiddtk-tmux`, `tools/valet-site-copy.sh`.
+Complete command reference for all AI-DDTK tools: `pw-auth`, `wpcc`, `local-wp`, `wp-ajax-test`, `aiddtk-tmux`, `tools/valet-site-copy.sh`, `tools/servers-audit.sh`, `tools/servers-preflight.sh`.
 
 **Last Updated:** 2026-03-22  
 **Version:** 1.0.0
@@ -240,6 +240,8 @@ wpcc [options] [paths...]
 - `--baseline <path>` — Use custom baseline file (default: `.hcc-baseline`)
 - `--ignore-baseline` — Ignore baseline file even if present
 - `--enable-clone-detection` — Enable function clone detection
+- `--wpcignore-file <path>` — Use custom `.wpcignore` file (default: auto-detect in scan dir or cwd)
+- `--no-wpcignore` — Disable `.wpcignore` file loading
 - `--help` — Show help message
 
 **Examples:**
@@ -264,6 +266,12 @@ wpcc --severity-config ./custom-severity.json
 
 # Verbose output with all matches
 wpcc --verbose --context-lines 5
+
+# Repo-wide scan using .wpcignore to skip tools/, temp/, etc.
+wpcc --paths .
+
+# Scan without .wpcignore filtering
+wpcc --paths . --no-wpcignore
 ```
 
 **Output:**
@@ -287,6 +295,32 @@ wpcc --features
 
 ---
 
+#### `.wpcignore` File
+
+Place a `.wpcignore` file in the scan target directory (or current working directory) to exclude paths from scanning. Uses gitignore-style patterns:
+
+```
+# Directories (trailing slash)
+tools/
+temp/
+vendor/
+node_modules/
+
+# Extension globs
+*.min.js
+*.min.css
+
+# Literal substring
+some-legacy-file.php
+```
+
+**Auto-detection order:**
+1. `<scan-dir>/.wpcignore` (if `--paths` points to a directory)
+2. `./.wpcignore` (current working directory)
+3. `--wpcignore-file <path>` overrides auto-detection
+
+---
+
 ## local-wp
 
 **Purpose:** WP-CLI wrapper for Local by Flywheel sites.
@@ -596,6 +630,43 @@ tools/valet-site-copy.sh teardown clone-test-01 --yes
 
 ---
 
+## servers-audit.sh
+
+**Purpose:** Capture a baseline snapshot of your local development environment — running services, ports, hostnames, DNS config, and Launchd service states — for diffing when things break.
+
+**Location:** `~/bin/ai-ddtk/tools/servers-audit.sh`
+
+```bash
+# Full audit to file
+tools/servers-audit.sh --output ~/bin/servers-audit.md
+
+# Focus on hostname checks
+tools/servers-audit.sh --output ~/bin/servers-audit.md --focus hostname
+
+# Diff against previous snapshot
+tools/servers-audit.sh --output /tmp/servers-now.md --previous-snapshot ~/bin/servers-audit.md
+```
+
+Writes machine-readable artifacts under `temp/servers-audit/<run-id>/`.
+
+---
+
+## servers-preflight.sh
+
+**Purpose:** Interactive pre-check for adding new local development domains — validates that hostnames, ports, and DNS entries won't conflict with existing Local WP sites, Valet links, or Homebrew services.
+
+**Location:** `~/bin/ai-ddtk/tools/servers-preflight.sh`
+
+```bash
+# Check if a domain is safe to add
+tools/servers-preflight.sh check-domain mysite.local
+
+# JSON output for agent consumption
+tools/servers-preflight.sh check-domain mysite.local --json
+```
+
+---
+
 ## Exit Codes
 
 | Code | Meaning |

tools/mcp-server/README.md

@@ -1,8 +1,8 @@
 # AI-DDTK MCP Server
 
-> Version: 0.7.0
+> Version: 0.9.0
 
-Unified MCP server for AI-DDTK. Exposes LocalWP, WPCC, `pw-auth`, `wp-ajax-test`, tmux, and Query Monitor workflows as typed **Tools**, **Resources**, and **Prompts** — compatible with Claude Code, GitHub Copilot, Cline, Augment Code, Cursor, Claude Desktop, and any MCP-capable client.
+Unified MCP server for AI-DDTK. Exposes LocalWP, WPCC, `pw-auth`, `wp-ajax-test`, tmux, Query Monitor, and end-of-day session cleanup workflows as typed **Tools**, **Resources**, and **Prompts** — compatible with Claude Code, GitHub Copilot, Cline, Augment Code, Cursor, Claude Desktop, and any MCP-capable client.
 
 ## Quick Start
 
@@ -55,6 +55,7 @@ npm run mcp:http
 | AJAX | `wp_ajax_test` | Test `admin-ajax.php` endpoints with structured inputs |
 | tmux | `tmux_start`, `tmux_send`, `tmux_capture`, `tmux_stop`, `tmux_list`, `tmux_status` | Run resilient long-lived commands and inspect output |
 | Query Monitor | `qm_profile_page`, `qm_slow_queries`, `qm_duplicate_queries` | Profile pages, find slow queries, detect N+1 patterns |
+| Session cleanup | `end_of_day_session_cleanup` | Automated solo dev session cleanup: sync 4X4.md/CHANGELOG.md/MEMORY.md, optionally commit and push with confirmation |
 
 ## Resources
 

tools/mcp-server/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-ddtk-mcp",
-  "version": "0.6.3",
-  "description": "AI-DDTK MCP server for LocalWP, pw-auth, wp-ajax-test, tmux, and WPCC tools/resources",
+  "version": "0.9.0",
+  "description": "AI-DDTK MCP server for LocalWP, pw-auth, wp-ajax-test, tmux, WPCC, Query Monitor, and end-of-day session cleanup workflows",
   "type": "module",
   "main": "dist/src/index.js",
   "bin": {

tools/mcp-server/src/handlers/end-of-day.ts

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { ExecFileTextError, execFileText, type ExecFileText, type ExecResult } from "../utils/exec.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type EndOfDayMode = "report" | "commit" | "push";
+
+export type EndOfDayCheckResult = Record<string, unknown> & {
+  check: string;
+  status: "ok" | "missing" | "stale" | "dirty" | "error";
+  message: string;
+};
+
+export type EndOfDayResult = Record<string, unknown> & {
+  mode: EndOfDayMode;
+  dryRun: boolean;
+  force: boolean;
+  checks: EndOfDayCheckResult[];
+  gitBranch: string;
+  gitState: "clean" | "dirty";
+  modifiedFiles: number;
+  untrackedFiles: number;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export interface EndOfDayHandlerDeps {
+  repoRoot: string;
+  timeoutMs?: number;
+  execRunner?: ExecFileText;
+}
+
+export function createEndOfDayHandlers(deps: EndOfDayHandlerDeps) {
+  const { repoRoot, timeoutMs = DEFAULT_TIMEOUT_MS, execRunner = execFileText } = deps;
+  const scriptPath = path.join(repoRoot, "experimental/end-of-day.sh");
+
+  async function runEndOfDay(options: {
+    mode?: EndOfDayMode;
+    dryRun?: boolean;
+    force?: boolean;
+    skipValidation?: boolean;
+  }): Promise<EndOfDayResult> {
+    const { mode = "report", dryRun = false, force = false, skipValidation = false } = options;
+
+    const args: string[] = [];
+
+    if (mode === "commit") {
+      args.push("--commit");
+    } else if (mode === "push") {
+      args.push("--push");
+    }
+
+    if (force) {
+      args.push("--force");
+    }
+
+    if (dryRun) {
+      args.push("--dry-run");
+    }
+
+    if (skipValidation) {
+      args.push("--no-validate");
+    }
+
+    try {
+      const result = await execRunner("bash", [scriptPath, ...args], {
+        cwd: repoRoot,
+        timeoutMs,
+      });
+
+      // Parse stdout for check results and git state
+      const lines = result.stdout.split("\n");
+      const checks: EndOfDayCheckResult[] = [];
+      let gitBranch = "unknown";
+      let gitState: "clean" | "dirty" = "clean";
+      let modifiedFiles = 0;
+      let untrackedFiles = 0;
+
+      for (const line of lines) {
+        if (line.includes("4X4.md")) {
+          checks.push({
+            check: "4X4.md",
+            status: line.includes("✓") ? "ok" : line.includes("⚠") ? "stale" : "error",
+            message: line,
+          });
+        } else if (line.includes("CHANGELOG.md")) {
+          checks.push({
+            check: "CHANGELOG.md",
+            status: line.includes("✓") ? "ok" : line.includes("⚠") ? "stale" : "error",
+            message: line,
+          });
+        } else if (line.includes("MEMORY.md")) {
+          checks.push({
+            check: "MEMORY.md",
+            status: line.includes("archived") ? "ok" : "ok",
+            message: line,
+          });
+        } else if (line.includes("Build validation")) {
+          checks.push({
+            check: "build",
+            status: line.includes("✓") ? "ok" : "error",
+            message: line,
+          });
+        } else if (line.includes("Branch:")) {
+          const match = line.match(/Branch:\s+(\S+)/);
+          if (match) gitBranch = match[1];
+        } else if (line.includes("Git state:")) {
+          if (line.includes("clean")) {
+            gitState = "clean";
+          } else {
+            gitState = "dirty";
+            const modMatch = line.match(/(\d+)\s+modified/);
+            const untMatch = line.match(/(\d+)\s+untracked/);
+            if (modMatch) modifiedFiles = parseInt(modMatch[1], 10);
+            if (untMatch) untrackedFiles = parseInt(untMatch[1], 10);
+          }
+        }
+      }
+
+      return {
+        mode,
+        dryRun,
+        force,
+        checks: checks.length > 0 ? checks : [{ check: "session", status: "ok", message: "Session check complete" }],
+        gitBranch,
+        gitState,
+        modifiedFiles,
+        untrackedFiles,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      };
+    } catch (error) {
+      if (error instanceof ExecFileTextError) {
+        return {
+          mode,
+          dryRun,
+          force,
+          checks: [
+            {
+              check: "script",
+              status: "error",
+              message: error.message,
+            },
+          ],
+          gitBranch: "unknown",
+          gitState: "clean",
+          modifiedFiles: 0,
+          untrackedFiles: 0,
+          stdout: error.stdout || "",
+          stderr: error.stderr || error.message,
+          exitCode: error.exitCode || 2,
+        };
+      }
+      throw error;
+    }
+  }
+
+  return { runEndOfDay };
+}
+