agent-method 1.5.0 → 1.5.3

package/lib/mcp-server.js

@@ -0,0 +1,524 @@
+/**
+ * MCP server — exposes methodology pipeline and registry as agent-callable tools.
+ *
+ * 8 tools:
+ *   route_query          S1-S5  End-to-end query routing
+ *   validate_entry_point S7     Entry point validation
+ *   detect_project       S8     Project type detection
+ *   resolve_cascade      S5     Cascade chain resolution
+ *   check_capability     Registry  Model tier capability check
+ *   lookup_feature       Registry  Feature lookup by ID or keyword
+ *   list_workflows       Registry  List available workflows
+ *   refactor_markdown    CTX-06    Markdown scale analysis
+ *
+ * Uses @modelcontextprotocol/sdk McpServer with stdio transport.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { loadRegistry, getFeatures, getWorkflows, getVersion } from "./registry.js";
+import {
+  classify,
+  selectWorkflow,
+  resolveFeatures,
+  computeFileSets,
+  resolveCascade,
+  validateEntryPoint,
+  detectProjectType,
+} from "./pipeline.js";
+
+// ---------------------------------------------------------------------------
+// Registry singleton (loaded once at startup)
+// ---------------------------------------------------------------------------
+
+let _registry = null;
+
+function registry(registryPath) {
+  if (!_registry) {
+    _registry = loadRegistry(registryPath || undefined);
+  }
+  return _registry;
+}
+
+// ---------------------------------------------------------------------------
+// Capability tiers — maps model tiers to supported feature domains
+// ---------------------------------------------------------------------------
+
+const TIER_CAPABILITIES = {
+  lite: {
+    supported_domains: ["CTX", "QRY", "STT"],
+    max_features: 12,
+    notes: "Haiku-class models. Core context and query routing only.",
+  },
+  standard: {
+    supported_domains: ["CTX", "QRY", "STT", "TSK", "HAI", "TPL"],
+    max_features: 24,
+    notes: "Sonnet-class models. Full methodology minus exploration/discovery.",
+  },
+  full: {
+    supported_domains: ["CTX", "QRY", "STT", "TSK", "HAI", "TPL", "EXP", "SCAN"],
+    max_features: 32,
+    notes: "Opus-class models. Complete methodology surface area.",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Markdown analysis helpers (CTX-06 scale management)
+// ---------------------------------------------------------------------------
+
+const SCALE_THRESHOLD = 300;
+
+function analyzeMarkdown(filePath) {
+  const absPath = resolve(filePath);
+  let content;
+  try {
+    content = readFileSync(absPath, "utf-8");
+  } catch {
+    return { error: `File not found: ${filePath}` };
+  }
+
+  const lines = content.split("\n");
+  const lineCount = lines.length;
+  const overThreshold = lineCount > SCALE_THRESHOLD;
+
+  // Parse sections by headings
+  const sections = [];
+  let currentSection = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^(#{1,4})\s+(.+)/);
+    if (match) {
+      if (currentSection) {
+        currentSection.end_line = i;
+        currentSection.line_count = currentSection.end_line - currentSection.start_line;
+        sections.push(currentSection);
+      }
+      currentSection = {
+        level: match[1].length,
+        title: match[2].trim(),
+        start_line: i + 1,
+        end_line: null,
+        line_count: 0,
+      };
+    }
+  }
+  if (currentSection) {
+    currentSection.end_line = lines.length;
+    currentSection.line_count = currentSection.end_line - currentSection.start_line;
+    sections.push(currentSection);
+  }
+
+  const result = {
+    file: filePath,
+    line_count: lineCount,
+    threshold: SCALE_THRESHOLD,
+    over_threshold: overThreshold,
+    sections,
+  };
+
+  // Generate split plan only if over threshold
+  if (overThreshold) {
+    const topSections = sections.filter((s) => s.level <= 2);
+    const splitCandidates = topSections
+      .filter((s) => s.line_count > 30)
+      .sort((a, b) => b.line_count - a.line_count);
+
+    result.split_plan = {
+      strategy: "index_plus_components",
+      description:
+        "Split into index file (navigation + active content) and components subdirectory (archived sections grouped by semantic boundary).",
+      candidates: splitCandidates.map((s) => ({
+        section: s.title,
+        lines: s.line_count,
+        recommendation: s.line_count > 100 ? "extract to component" : "consider extracting",
+      })),
+      estimated_index_lines: lineCount - splitCandidates.reduce((sum, s) => sum + s.line_count, 0),
+    };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Server creation
+// ---------------------------------------------------------------------------
+
+export function createServer(registryPath) {
+  const reg = registry(registryPath);
+  const version = getVersion(reg);
+
+  const server = new McpServer({
+    name: "wwa",
+    version: version,
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool 1: route_query — end-to-end pipeline (S1-S5)
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "route_query",
+    "Route a natural language query through the methodology pipeline (S1-S5). Returns query classification, workflow selection, resolved features, and computed read/write file sets.",
+    {
+      query: z.string().describe("The natural language query to route"),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general"])
+        .default("general")
+        .describe("Project type for context-aware routing"),
+      stage: z
+        .string()
+        .default("scope")
+        .describe("Pipeline stage: scope, act, or verify"),
+    },
+    async ({ query, project_type, stage }) => {
+      const classification = classify(query, project_type, reg);
+      const selection = selectWorkflow(classification.query_type, project_type);
+      const resolution = resolveFeatures(selection.workflow_id, stage, reg);
+      const fileSets = computeFileSets(resolution.features, classification.query_type, reg);
+      const cascade = resolveCascade([], null, project_type === "general" ? "universal" : project_type);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                query,
+                project_type,
+                stage,
+                query_type: classification.query_type,
+                confidence: classification.confidence,
+                matched: classification.matched,
+                workflow: selection,
+                features: resolution.features,
+                feature_source: resolution.source,
+                read_set: fileSets.read_set,
+                write_set: fileSets.write_set,
+                cascade: cascade,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 2: validate_entry_point — S7 validation
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "validate_entry_point",
+    "Validate an entry point file (CLAUDE.md, .cursorrules, AGENT.md) against the methodology registry. Checks scoping coverage, cascade completeness, convention coverage, workflow references, and scale management.",
+    {
+      file_path: z.string().describe("Path to the entry point file"),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general"])
+        .default("general")
+        .describe("Project type for validation context"),
+    },
+    async ({ file_path, project_type }) => {
+      const result = validateEntryPoint(file_path, project_type, reg);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 3: detect_project — S8 detection
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "detect_project",
+    "Detect project type from directory contents. Analyzes file patterns, extensions, and directory structure to classify a project as code, data, analytical, mixed, or general.",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Directory to analyze"),
+    },
+    async ({ directory }) => {
+      const result = detectProjectType(directory);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 4: resolve_cascade — S5 cascade resolution
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "resolve_cascade",
+    "Resolve the dependency cascade chain for a given trigger. Returns which files need updating when a specific change occurs (e.g., phase_completion, requirements_change, file_split).",
+    {
+      trigger: z
+        .string()
+        .describe(
+          "Cascade trigger: phase_completion, requirements_change, new_decision, open_question_resolved, project_structure, new_domain, file_exceeds_300_lines, file_split, database_schema, api_route, new_module, schema_change, pipeline_stage, etc."
+        ),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "universal"])
+        .default("universal")
+        .describe("Project type determines which cascade tables are included"),
+    },
+    async ({ trigger, project_type }) => {
+      const cascadeContext = project_type === "general" ? "universal" : project_type;
+      const result = resolveCascade([], trigger, cascadeContext);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                trigger,
+                project_type,
+                cascade_chain: result.cascade_files,
+                depth: result.depth,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 5: check_capability — model tier query
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "check_capability",
+    "Check whether a model tier supports a specific feature. Returns support status and recommendations for the given model tier (lite/standard/full).",
+    {
+      model_tier: z
+        .enum(["lite", "standard", "full"])
+        .describe("Model tier: lite (Haiku), standard (Sonnet), full (Opus)"),
+      feature_id: z
+        .string()
+        .describe("Feature ID to check (e.g., CTX-01, EXP-03, SCAN-02)"),
+    },
+    async ({ model_tier, feature_id }) => {
+      const tier = TIER_CAPABILITIES[model_tier];
+      const features = getFeatures(reg);
+      const feature = features[feature_id];
+
+      if (!feature) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  feature_id,
+                  error: `Feature not found: ${feature_id}`,
+                  available_features: Object.keys(features),
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      const domain = feature_id.split("-")[0];
+      const supported = tier.supported_domains.includes(domain);
+
+      const recommendations = [];
+      if (!supported) {
+        recommendations.push(
+          `Feature ${feature_id} (domain: ${domain}) is not supported at ${model_tier} tier.`
+        );
+        const requiredTier = Object.entries(TIER_CAPABILITIES).find(([, t]) =>
+          t.supported_domains.includes(domain)
+        );
+        if (requiredTier) {
+          recommendations.push(`Minimum tier required: ${requiredTier[0]}`);
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                feature_id,
+                feature_name: feature.name,
+                domain,
+                model_tier,
+                supported,
+                tier_info: tier,
+                recommendations,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 6: lookup_feature — registry feature lookup
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "lookup_feature",
+    "Look up a feature by ID or search by keyword. Returns the full feature specification including domain, reads, writes, and dependencies.",
+    {
+      query: z
+        .string()
+        .describe("Feature ID (e.g., CTX-01) or keyword to search for"),
+    },
+    async ({ query }) => {
+      const features = getFeatures(reg);
+      const queryUpper = query.toUpperCase();
+
+      // Direct ID match
+      if (features[queryUpper]) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { match: "exact", feature: features[queryUpper] },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      // Keyword search
+      const queryLower = query.toLowerCase();
+      const matches = [];
+      for (const [id, feat] of Object.entries(features)) {
+        const searchable = `${id} ${feat.name || ""} ${feat.domain || ""}`.toLowerCase();
+        if (searchable.includes(queryLower)) {
+          matches.push({ id, ...feat });
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                match: matches.length > 0 ? "keyword" : "none",
+                query,
+                results: matches,
+                total_features: Object.keys(features).length,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 7: list_workflows — registry workflow listing
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "list_workflows",
+    "List all available methodology workflows, optionally filtered by project type. Returns workflow IDs, names, steps, and applicability.",
+    {
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general", "all"])
+        .default("all")
+        .describe("Filter workflows by project type, or 'all' for complete list"),
+    },
+    async ({ project_type }) => {
+      const workflows = getWorkflows(reg);
+      let filtered = workflows;
+
+      if (project_type !== "all") {
+        filtered = workflows.filter((wf) => {
+          const types = wf.project_types || ["universal"];
+          return (
+            types.includes("universal") ||
+            types.includes(project_type) ||
+            project_type === "mixed"
+          );
+        });
+      }
+
+      const result = filtered.map((wf) => ({
+        id: wf.id,
+        name: wf.name,
+        project_types: wf.project_types || ["universal"],
+        steps: (wf.steps || []).map((s) => ({
+          stage: s.stage,
+          action: s.action,
+          features: s.features || [],
+        })),
+      }));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                project_type,
+                workflow_count: result.length,
+                workflows: result,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 8: refactor_markdown — CTX-06 scale analysis
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "refactor_markdown",
+    "Analyze a markdown file for scale management (CTX-06). Reports line count, whether it exceeds the 300-line threshold, section breakdown, and a split plan if refactoring is needed. Advisory only — does not modify the file.",
+    {
+      file_path: z.string().describe("Path to the markdown file to analyze"),
+    },
+    async ({ file_path }) => {
+      const result = analyzeMarkdown(file_path);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Standalone entry point — starts stdio transport
+// ---------------------------------------------------------------------------
+
+export async function startServer(registryPath) {
+  const server = createServer(registryPath);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}

package/lib/pipeline.js

@@ -1,5 +1,5 @@
 /**
- * 8-stage pipeline — Node.js port of agent_method/pipeline.py.
+ * 8-stage pipeline — Node.js port of wwa/pipeline.py.
  *
  * Stages:
  *   S1  classify         Query classification against registry patterns

package/lib/registry.js

@@ -49,7 +49,7 @@ export function findRegistry(start) {
 
   throw new Error(
     "Cannot find feature-registry.yaml. " +
-      "Provide --registry or run from the agent-method repo."
+      "Provide --registry or run from the wwa repo."
   );
 }
 

package/lib/watcher.js

@@ -0,0 +1,165 @@
+/**
+ * Registry watcher — chokidar-based file monitoring with proactive validation.
+ *
+ * Watches:
+ *   - Entry points (CLAUDE.md, .cursorrules, AGENT.md)
+ *   - Feature registry (feature-registry.yaml)
+ *   - Markdown files for 300-line threshold violations
+ *
+ * On change: runs S7 validation and reports results.
+ */
+
+import { watch } from "chokidar";
+import { readFileSync, statSync } from "node:fs";
+import { resolve, basename, extname } from "node:path";
+
+import { loadRegistry } from "./registry.js";
+import { validateEntryPoint, detectProjectType } from "./pipeline.js";
+
+const SCALE_THRESHOLD = 300;
+
+const ENTRY_POINT_NAMES = new Set(["CLAUDE.md", ".cursorrules", "AGENT.md"]);
+const INTELLIGENCE_LAYER = new Set([
+  "STATE.md", "ROADMAP.md", "PLAN.md", "SUMMARY.md", "PROJECT.md",
+]);
+
+// ---------------------------------------------------------------------------
+// Validation handlers
+// ---------------------------------------------------------------------------
+
+function validateEntry(filePath, registryPath) {
+  const reg = loadRegistry(registryPath || undefined);
+  const dir = resolve(filePath, "..");
+  const detected = detectProjectType(dir);
+  const projectType = detected.project_type || "general";
+  const result = validateEntryPoint(filePath, projectType, reg);
+  return { type: "entry_point", file: filePath, projectType, result };
+}
+
+function checkScale(filePath) {
+  try {
+    const content = readFileSync(resolve(filePath), "utf-8");
+    const lineCount = content.split("\n").length;
+    const over = lineCount > SCALE_THRESHOLD;
+    return {
+      type: "scale_check",
+      file: filePath,
+      line_count: lineCount,
+      threshold: SCALE_THRESHOLD,
+      over_threshold: over,
+    };
+  } catch {
+    return { type: "scale_check", file: filePath, error: "Cannot read file" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Watcher creation
+// ---------------------------------------------------------------------------
+
+export function createWatcher(directory, options = {}) {
+  const dir = resolve(directory);
+  const registryPath = options.registryPath || null;
+  const onResult = options.onResult || defaultReporter;
+
+  // Watch patterns: markdown files and yaml files
+  const patterns = [
+    `${dir}/**/*.md`,
+    `${dir}/**/feature-registry.yaml`,
+    `${dir}/.cursorrules`,
+  ];
+
+  const ignored = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+  ];
+
+  const watcher = watch(patterns, {
+    ignored,
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 300,
+      pollInterval: 100,
+    },
+  });
+
+  watcher.on("change", (filePath) => {
+    const name = basename(filePath);
+    const ext = extname(filePath);
+
+    // Entry point changed — run full validation
+    if (ENTRY_POINT_NAMES.has(name)) {
+      try {
+        const report = validateEntry(filePath, registryPath);
+        onResult(report);
+      } catch (err) {
+        onResult({ type: "error", file: filePath, message: err.message });
+      }
+      return;
+    }
+
+    // Registry changed — reload and validate all entry points
+    if (name === "feature-registry.yaml") {
+      onResult({ type: "registry_reload", file: filePath, message: "Registry changed — reload triggered" });
+      return;
+    }
+
+    // Markdown file changed — check scale threshold
+    if (ext === ".md") {
+      const report = checkScale(filePath);
+      // Only report if over threshold or if it's an intelligence layer file
+      if (report.over_threshold || INTELLIGENCE_LAYER.has(name)) {
+        onResult(report);
+      }
+    }
+  });
+
+  watcher.on("add", (filePath) => {
+    const name = basename(filePath);
+    if (ENTRY_POINT_NAMES.has(name)) {
+      onResult({ type: "entry_point_added", file: filePath, message: "New entry point detected" });
+    }
+  });
+
+  return watcher;
+}
+
+// ---------------------------------------------------------------------------
+// Default reporter — console output
+// ---------------------------------------------------------------------------
+
+function defaultReporter(report) {
+  const timestamp = new Date().toISOString().substring(11, 19);
+
+  switch (report.type) {
+    case "entry_point": {
+      const status = report.result.valid ? "PASS" : "FAIL";
+      console.log(`[${timestamp}] Entry point ${status}: ${report.file}`);
+      if (!report.result.valid && report.result.issues) {
+        for (const issue of report.result.issues) {
+          console.log(`  [${issue.severity}] ${issue.check}: ${issue.description}`);
+        }
+      }
+      break;
+    }
+    case "scale_check":
+      if (report.over_threshold) {
+        console.log(
+          `[${timestamp}] Scale warning: ${report.file} (${report.line_count} lines, threshold: ${report.threshold})`
+        );
+      }
+      break;
+    case "registry_reload":
+      console.log(`[${timestamp}] ${report.message}`);
+      break;
+    case "entry_point_added":
+      console.log(`[${timestamp}] ${report.message}: ${report.file}`);
+      break;
+    case "error":
+      console.error(`[${timestamp}] Error: ${report.file} — ${report.message}`);
+      break;
+  }
+}