@bcelep/capint 0.4.2

package/src/lib/intent-parser.js

@@ -0,0 +1,116 @@
+const WEIGHT_RANK = { light: 0, medium: 1, heavy: 2 };
+
+function normalize(text) {
+  return text.toLowerCase().normalize("NFD").replace(/\p{M}/gu, "");
+}
+
+function splitSubtasks(text) {
+  const trimmed = text.trim();
+  const lines = trimmed.split(/\n/).map((l) => l.replace(/^[\s\-*•\d.)]+\s*/, "").trim()).filter(Boolean);
+  if (lines.length >= 2) return lines;
+  const parts = trimmed.split(/\s*,\s*|\s+ve\s+|\s+and\s+/i).filter((p) => p.trim().length > 3);
+  if (parts.length >= 2) return parts;
+  return [trimmed];
+}
+
+function matchKeywords(text, keywords) {
+  const n = normalize(text);
+  return keywords.some((kw) => n.includes(normalize(kw)));
+}
+
+function parseEstimatedFiles(text) {
+  const patterns = [
+    /(\d+)\s*\+\s*(?:file|files|dosya)/i,
+    /(?:file|files|dosya)\s*[:=]?\s*(\d+)/i,
+    /(\d+)\s*(?:file|files|dosya)/i
+  ];
+  for (const re of patterns) {
+    const m = text.match(re);
+    if (m?.[1]) return Number(m[1]);
+  }
+  return null;
+}
+
+function findBestTaskType(text, matrix) {
+  let bestType = null;
+  for (const tt of matrix.task_types || []) {
+    if (matchKeywords(text, tt.keywords || [])) {
+      if (!bestType || WEIGHT_RANK[tt.weight_default || "light"] > WEIGHT_RANK[bestType.weight_default || "light"]) {
+        bestType = tt;
+      }
+    }
+  }
+  return bestType;
+}
+
+function classifySubtask(text, matrix) {
+  const c = matrix.classification;
+  const reasons = [];
+  const estimatedFiles = parseEstimatedFiles(text);
+
+  if (matchKeywords(text, c.heavy_keywords || [])) {
+    reasons.push("heavy keyword");
+    return { weight: "heavy", reasons, taskType: findBestTaskType(text, matrix), signals: { estimated_files: estimatedFiles } };
+  }
+
+  if (matchKeywords(text, c.security_keywords || [])) {
+    reasons.push("security domain");
+    const securityFloor = c.security_override_min || "medium";
+    return {
+      weight: securityFloor,
+      reasons,
+      taskType: findBestTaskType(text, matrix),
+      signals: { estimated_files: estimatedFiles }
+    };
+  }
+
+  if (matchKeywords(text, c.medium_keywords || [])) {
+    reasons.push("medium keyword");
+    return {
+      weight: "medium",
+      reasons,
+      taskType: findBestTaskType(text, matrix),
+      signals: { estimated_files: estimatedFiles }
+    };
+  }
+
+  const bestType = findBestTaskType(text, matrix);
+  if (bestType) {
+    reasons.push(`task_type:${bestType.id}`);
+    return {
+      weight: bestType.weight_default || "medium",
+      reasons,
+      taskType: bestType,
+      signals: { estimated_files: estimatedFiles }
+    };
+  }
+
+  reasons.push("ambiguous default");
+  return { weight: c.ambiguous_default || "medium", reasons, signals: { estimated_files: estimatedFiles } };
+}
+
+function parseIntent(text, matrix) {
+  const subtasks = splitSubtasks(text);
+  const useMultiple = subtasks.length >= 2;
+  const segments = (useMultiple ? subtasks : [text.trim()]).map((sub, index) => ({
+    index: index + 1,
+    text: sub,
+    classification: classifySubtask(sub, matrix)
+  }));
+
+  return {
+    rawText: text,
+    useMultiple,
+    subtasks,
+    overrides: {
+      workflow: /\/workflow\b/i.test(text),
+      skill: /\/skill\b/i.test(text)
+    },
+    segments
+  };
+}
+
+module.exports = {
+  parseIntent,
+  matchKeywords
+};

package/src/lib/orchestration.js

@@ -0,0 +1,25 @@
+const CONFIRM_TO_MODE = {
+  apply_now: "subagent",
+  plan_first: "pipeline",
+  analyze_only: "explore"
+};
+
+function resolveOrchestration(taskType, confirmDefault, matrix) {
+  const pattern = taskType?.orchestration_pattern || "expert_pool";
+  const mode = CONFIRM_TO_MODE[confirmDefault] || "pipeline";
+
+  const chains = (matrix?.capability_chains || []).filter(
+    (c) => c.from_capability === (taskType?.capability || c.from_capability)
+  );
+
+  return {
+    pattern,
+    execution_mode: mode,
+    chains: chains.map((c) => ({
+      then_capability: c.then_capability,
+      when: c.when || "after_confirm"
+    }))
+  };
+}
+
+module.exports = { resolveOrchestration, CONFIRM_TO_MODE };

package/src/lib/providers/activation-policy.js

@@ -0,0 +1,93 @@
+/**
+ * Provider activation policy — default off; explicit gating only.
+ * See docs/architecture-decisions.md
+ */
+
+const WEIGHT_RANK = { light: 0, medium: 1, heavy: 2 };
+
+function readPolicy(matrix) {
+  return (
+    matrix?.provider_activation_policy || {
+      memory_providers: { default: "off", require_doctor_pass: true, allow_on_light: false },
+      graph_providers: { default: "off", require_doctor_pass: true, allow_on_light: false }
+    }
+  );
+}
+
+function evaluateActivation({ kind, memoryLevel, overallWeight, capability, matrix, doctorPass, featureFlags = {} }) {
+  const policy = readPolicy(matrix);
+  const block = policy[kind] || { default: "off" };
+  const flagKey = kind === "memory_providers" ? "CAPINT_MEMORY" : "CAPINT_GRAPH";
+  const flagOn = featureFlags[kind] || process.env[flagKey] === "1";
+
+  const reasons = [];
+  let activated = false;
+
+  if (block.default === "on") {
+    activated = true;
+    reasons.push("policy_default_on");
+  }
+
+  if (memoryLevel === "required") {
+    activated = true;
+    reasons.push("capability_requires_memory");
+  }
+
+  if (flagOn) {
+    activated = true;
+    reasons.push("feature_flag");
+  }
+
+  if (!block.allow_on_light && overallWeight === "light" && memoryLevel !== "required") {
+    activated = false;
+    reasons.push("blocked_light_weight");
+  }
+
+  if (block.require_doctor_pass && !doctorPass && !flagOn) {
+    activated = false;
+    reasons.push("doctor_not_pass");
+  }
+
+  const highRisk = new Set(block.high_risk_capabilities || ["incident-response", "threat-modeling", "memory-retrieval"]);
+  if (highRisk.has(capability) && memoryLevel !== "none") {
+    activated = true;
+    reasons.push("high_risk_capability");
+  }
+
+  return {
+    kind,
+    activated,
+    default: block.default || "off",
+    reasons,
+    fallback: activated ? null : "local"
+  };
+}
+
+function resolveProviderActivation({ memoryLevel, overallWeight, capability, matrix, doctorPass, featureFlags }) {
+  const memory = evaluateActivation({
+    kind: "memory_providers",
+    memoryLevel,
+    overallWeight,
+    capability,
+    matrix,
+    doctorPass,
+    featureFlags
+  });
+  const graph = evaluateActivation({
+    kind: "graph_providers",
+    memoryLevel: memoryLevel === "required" ? "required" : "optional",
+    overallWeight,
+    capability,
+    matrix,
+    doctorPass,
+    featureFlags
+  });
+  return { memory, graph, anyActivated: memory.activated || graph.activated };
+}
+
+module.exports = {
+  readPolicy,
+  evaluateActivation,
+  resolveProviderActivation,
+  WEIGHT_RANK
+};

package/src/lib/providers/graph-provider.js

@@ -0,0 +1,35 @@
+/**
+ * GraphProvider adapter contract (optional plugin — read-only projection in v0.x).
+ */
+
+const PROVIDER_CONTRACT = {
+  name: "string",
+  methods: ["health", "query"],
+  optionalMethods: ["project"]
+};
+
+function createGraphProviderStub(name = "local") {
+  return {
+    name,
+    async health() {
+      return { ok: true, detail: "local fallback (no graph index)" };
+    },
+    async query(_query, _scope) {
+      return [];
+    }
+  };
+}
+
+function validateGraphProvider(provider) {
+  const errors = [];
+  if (!provider?.name) errors.push("provider.name required");
+  if (typeof provider.health !== "function") errors.push("provider.health required");
+  if (typeof provider.query !== "function") errors.push("provider.query required");
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  PROVIDER_CONTRACT,
+  createGraphProviderStub,
+  validateGraphProvider
+};

package/src/lib/providers/local-graph-adapter.js

@@ -0,0 +1,40 @@
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_PATHS = ["GRAPH_REPORT.md", ".capint/graph/graph.json"];
+
+function loadProvidersConfig(rootDir) {
+  const p = path.join(rootDir, ".capint", "providers.json");
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function query(rootDir, topic, options = {}) {
+  const cfg = options.config || loadProvidersConfig(rootDir);
+  const paths = cfg?.graph?.paths || DEFAULT_PATHS;
+  const excerpts = [];
+
+  for (const rel of paths) {
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue;
+    const raw = fs.readFileSync(abs, "utf-8");
+    if (rel.endsWith(".json")) {
+      try {
+        const data = JSON.parse(raw);
+        excerpts.push({ source: rel, excerpt: JSON.stringify(data).slice(0, 800) });
+      } catch {
+        excerpts.push({ source: rel, excerpt: raw.slice(0, 800) });
+      }
+    } else {
+      excerpts.push({ source: rel, excerpt: raw.slice(0, 1200) });
+    }
+  }
+
+  return { driver: "local", topic: topic || null, excerpts, paths_checked: paths };
+}
+
+module.exports = { query, loadProvidersConfig, DEFAULT_PATHS };

package/src/lib/providers/local-memory-adapter.js

@@ -0,0 +1,41 @@
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_PATHS = ["HANDOFF.md", "design.md", "AGENT.md", ".capint/rules/core.md"];
+
+function loadProvidersConfig(rootDir) {
+  const p = path.join(rootDir, ".capint", "providers.json");
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function search(rootDir, query, options = {}) {
+  const cfg = options.config || loadProvidersConfig(rootDir);
+  const paths = cfg?.memory?.paths || DEFAULT_PATHS;
+  const q = (query || "").toLowerCase();
+  const hits = [];
+
+  for (const rel of paths) {
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue;
+    const text = fs.readFileSync(abs, "utf-8");
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (!q || lines[i].toLowerCase().includes(q)) {
+        hits.push({
+          source: rel,
+          line: i + 1,
+          excerpt: lines[i].trim().slice(0, 200)
+        });
+      }
+    }
+  }
+
+  return { driver: "local", query, hits: hits.slice(0, 20), paths_checked: paths };
+}
+
+module.exports = { search, loadProvidersConfig, DEFAULT_PATHS };

package/src/lib/providers/memory-provider.js

@@ -0,0 +1,35 @@
+/**
+ * MemoryProvider adapter contract (optional plugin — not bundled in core runtime).
+ */
+
+const PROVIDER_CONTRACT = {
+  name: "string",
+  methods: ["health", "search"],
+  optionalMethods: ["ingest"]
+};
+
+function createMemoryProviderStub(name = "local") {
+  return {
+    name,
+    async health() {
+      return { ok: true, detail: "local fallback (HANDOFF, project files)" };
+    },
+    async search(_query, _scope, _limit = 5) {
+      return [];
+    }
+  };
+}
+
+function validateMemoryProvider(provider) {
+  const errors = [];
+  if (!provider?.name) errors.push("provider.name required");
+  if (typeof provider.health !== "function") errors.push("provider.health required");
+  if (typeof provider.search !== "function") errors.push("provider.search required");
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  PROVIDER_CONTRACT,
+  createMemoryProviderStub,
+  validateMemoryProvider
+};

package/src/lib/route-engine.js

@@ -0,0 +1,191 @@
+const fs = require("fs");
+const path = require("path");
+const { parseIntent, matchKeywords } = require("./intent-parser");
+const { routeCapability } = require("./capability-router");
+const { buildExecutionPolicy } = require("./execution-policy");
+const { resolveMemoryStrategy } = require("./context-memory-bridge");
+const { appendRouteEvents } = require("./event-log");
+
+const WEIGHT_EMOJI = { light: "🟢", medium: "🟡", heavy: "🔴" };
+
+function loadMatrix(rootDir) {
+  const p = path.join(rootDir, "skill-routing-matrix.json");
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, "utf-8"));
+}
+
+function loadRegistry(rootDir) {
+  const p = path.join(rootDir, "registry.json");
+  if (!fs.existsSync(p)) return { core: [], recommended: [], optional: [], project_added: [] };
+  return JSON.parse(fs.readFileSync(p, "utf-8"));
+}
+
+function installedSkills(rootDir, registry) {
+  const skillsDir = path.join(rootDir, "skills");
+  const names = new Set([
+    ...(registry.core || []),
+    ...(registry.recommended || []),
+    ...(registry.optional || []),
+    ...(registry.project_added || [])
+  ]);
+  const onDisk = [];
+  if (fs.existsSync(skillsDir)) {
+    for (const name of fs.readdirSync(skillsDir)) {
+      if (fs.existsSync(path.join(skillsDir, name, "SKILL.md"))) {
+        onDisk.push(name);
+      }
+    }
+  }
+  return [...names].filter((n) => onDisk.includes(n));
+}
+
+function loadFeatureFlags(rootDir) {
+  const p = path.join(rootDir, ".capint", "context.json");
+  if (!fs.existsSync(p)) return {};
+  try {
+    const ctx = JSON.parse(fs.readFileSync(p, "utf-8"));
+    return ctx.feature_flags || {};
+  } catch {
+    return {};
+  }
+}
+
+function routeTask(text, rootDir) {
+  const matrix = loadMatrix(rootDir);
+  if (!matrix) return { error: "skill-routing-matrix.json not found" };
+
+  const registry = loadRegistry(rootDir);
+  const installed = installedSkills(rootDir, registry);
+  const parsedIntent = parseIntent(text, matrix);
+  const routeResult = routeCapability(parsedIntent, matrix, registry, installed, matchKeywords);
+  const memoryStrategy = resolveMemoryStrategy({
+    intent: parsedIntent,
+    routeResult,
+    matrix,
+    rootDir,
+    featureFlags: loadFeatureFlags(rootDir)
+  });
+  const executionIntent = buildExecutionPolicy({
+    rawText: text,
+    routeResult,
+    memoryStrategy,
+    matrix,
+    parsedIntent,
+    rootDir
+  });
+
+  const routeEvents = [
+    ...(memoryStrategy.events || []),
+    {
+      type: "route.provider_selected",
+      resolution: executionIntent.resolution,
+      capability: executionIntent.capability,
+      weight: routeResult.overall
+    }
+  ];
+  const eventLog = appendRouteEvents(rootDir, routeEvents);
+
+  return {
+    request: text,
+    overall_weight: routeResult.overall,
+    overall_emoji: WEIGHT_EMOJI[routeResult.overall],
+    show_skill_plan: routeResult.showPlan,
+    subtasks: routeResult.rows,
+    installed_count: installed.length,
+    execution_intent: executionIntent,
+    events: routeEvents,
+    event_log: eventLog
+  };
+}
+
+function formatTextReport(result, options = {}) {
+  if (result.error) return result.error;
+  const { verbose = false } = options;
+  const lines = [];
+  lines.push("");
+  lines.push("## Execution Intent");
+  lines.push("");
+  lines.push(`Intent: ${result.execution_intent.intent}`);
+  lines.push(`Capability: ${result.execution_intent.capability}`);
+  lines.push(`Resolution: ${result.execution_intent.resolution}`);
+  if (result.execution_intent.resolution_status) {
+    lines.push(`Resolution status: ${result.execution_intent.resolution_status}`);
+    if (result.execution_intent.resolution_hint) {
+      lines.push(`Hint: ${result.execution_intent.resolution_hint}`);
+    }
+  }
+  lines.push(`Memory: ${result.execution_intent.memory}`);
+  lines.push(`Plan: ${result.execution_intent.plan}`);
+  if (result.execution_intent.confirm?.enabled) {
+    const optionSummary = (result.execution_intent.confirm_options || []).map((o) => o.id).join("|");
+    lines.push(`Confirm: ${result.execution_intent.confirm_question}`);
+    lines.push(`Options: ${optionSummary} (default: ${result.execution_intent.confirm_default_option})`);
+  }
+  lines.push("");
+  if (result.execution_intent.fallback) {
+    lines.push(`Fallback capability: ${result.execution_intent.fallback.capability}`);
+    lines.push(`Override: ${result.execution_intent.fallback.override}`);
+    lines.push("");
+  }
+  if (result.execution_intent.verification_required) {
+    lines.push(`Verification: required (${result.execution_intent.verification_profile || "standard"})`);
+    for (const h of result.execution_intent.verification_hints || []) {
+      lines.push(`  - ${h}`);
+    }
+    lines.push("");
+  }
+  if (result.execution_intent.orchestration) {
+    const o = result.execution_intent.orchestration;
+    lines.push(`Orchestration: ${o.pattern} (${o.execution_mode})`);
+    if (o.chains?.length) {
+      lines.push(`Chains: ${o.chains.map((c) => c.then_capability).join(" → ")}`);
+    }
+    lines.push("");
+  }
+  if (result.execution_intent.context_pack?.snippets?.length) {
+    lines.push(`Context pack: ${result.execution_intent.context_pack.snippets.length} local snippet(s)`);
+    lines.push("");
+  }
+  lines.push(`Weight: ${result.overall_emoji} ${result.overall_weight}`);
+  lines.push(`Plan visible: ${result.show_skill_plan ? "yes" : "no"}`);
+  if (verbose) {
+    const ex = result.execution_intent.route_explain;
+    if (ex) {
+      lines.push("");
+      lines.push("## Route explain (verbose)");
+      lines.push(`Matched task type: ${ex.matched_task_type || "—"}`);
+      lines.push(`Resolver order: ${(ex.resolver_order || []).join(" → ")}`);
+      if (ex.winner) {
+        lines.push(`Winner: ${ex.winner.name}/${ex.winner.resource} (confidence ${ex.winner.confidence})`);
+      }
+      lines.push("");
+    }
+    lines.push("## Skill Plan (verbose)");
+    lines.push("| # | Subtask | Weight | Reason | Skills | Workflow |");
+    lines.push("|---|---------|--------|--------|--------|----------|");
+    for (const r of result.subtasks) {
+      lines.push(
+        `| ${r.index} | ${r.subtask} | ${r.emoji} | ${r.reason} | ${r.skills.map((s) => s.name).join(", ")} | ${r.workflow || "—"} |`
+      );
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function listCheatsheet(matrix) {
+  const lines = ["capability/providers from skill-routing-matrix.json", ""];
+  for (const tt of matrix?.task_types || []) {
+    const capability = tt.capability || tt.id;
+    const providerList = (tt.providers || []).map((p) => `${p.name}/${p.resource}`).join(", ");
+    lines.push(`  ${tt.id.padEnd(20)} -> ${capability}${providerList ? ` | ${providerList}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  routeTask,
+  formatTextReport,
+  listCheatsheet,
+  loadMatrix
+};

package/src/lib/scaffold/file-policy.js

@@ -0,0 +1,92 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const MARKER_START = "<!-- capint:managed:start -->";
+const MARKER_END = "<!-- capint:managed:end -->";
+
+function fileHash(content) {
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+
+function hasManagedBlock(content) {
+  return content.includes(MARKER_START) && content.includes(MARKER_END);
+}
+
+function mergeManagedBlock(existing, incoming) {
+  if (!hasManagedBlock(existing)) return null;
+  const start = existing.indexOf(MARKER_START);
+  const end = existing.indexOf(MARKER_END);
+  if (start === -1 || end === -1 || end <= start) return null;
+  const before = existing.slice(0, start + MARKER_START.length);
+  const after = existing.slice(end);
+  const innerStart = incoming.indexOf(MARKER_START);
+  const innerEnd = incoming.indexOf(MARKER_END);
+  if (innerStart === -1 || innerEnd === -1) return null;
+  const inner = incoming.slice(innerStart + MARKER_START.length, innerEnd);
+  return `${before}\n${inner}\n${after}`;
+}
+
+/**
+ * Safe-merge policy:
+ * - missing file -> created
+ * - existing with managed block -> updated (merge inner)
+ * - existing without managed block -> conflict (write *.capint.new.md)
+ */
+function applyFilePolicy({ rootDir, relativePath, content, force = false }) {
+  const abs = path.join(rootDir, relativePath);
+  const dir = path.dirname(abs);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  if (!fs.existsSync(abs)) {
+    fs.writeFileSync(abs, content, "utf-8");
+    return { path: relativePath, action: "created" };
+  }
+
+  const existing = fs.readFileSync(abs, "utf-8");
+  if (force) {
+    fs.writeFileSync(abs, content, "utf-8");
+    return { path: relativePath, action: "updated", mode: "force" };
+  }
+
+  const merged = mergeManagedBlock(existing, content);
+  if (merged && merged !== existing) {
+    fs.writeFileSync(abs, merged, "utf-8");
+    return { path: relativePath, action: "updated", mode: "safe-merge" };
+  }
+
+  if (existing.trim() === content.trim()) {
+    return { path: relativePath, action: "skipped", reason: "identical" };
+  }
+
+  const sidecar = `${relativePath}.capint.new.md`;
+  const sideAbs = path.join(rootDir, sidecar);
+  fs.writeFileSync(sideAbs, content, "utf-8");
+  return {
+    path: relativePath,
+    action: "conflict",
+    sidecar,
+    existing_hash: fileHash(existing),
+    incoming_hash: fileHash(content)
+  };
+}
+
+function buildReport(results) {
+  const summary = { created: 0, updated: 0, skipped: 0, conflict: 0 };
+  for (const r of results) {
+    if (r.action === "created") summary.created++;
+    else if (r.action === "updated") summary.updated++;
+    else if (r.action === "skipped") summary.skipped++;
+    else if (r.action === "conflict") summary.conflict++;
+  }
+  return { summary, results, generated_at: new Date().toISOString() };
+}
+
+module.exports = {
+  MARKER_START,
+  MARKER_END,
+  applyFilePolicy,
+  buildReport,
+  mergeManagedBlock,
+  hasManagedBlock
+};