@bcelep/capint 0.4.2

package/scripts/validate-matrix.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(__dirname, "..");
+
+const REQUIRED_TOP = [
+  "schema_version",
+  "resolver_order",
+  "fallback_policy",
+  "execution_policy_defaults",
+  "clarification_policy",
+  "classification",
+  "task_types"
+];
+
+const MEMORY_LEVELS = new Set(["none", "optional", "required"]);
+const WEIGHTS = new Set(["light", "medium", "heavy"]);
+const PLANS = new Set(["auto", "confirm", "override"]);
+
+function fail(msg) {
+  console.error(`matrix validation error: ${msg}`);
+  process.exit(1);
+}
+
+function validateMatrix(matrix) {
+  if (!matrix || typeof matrix !== "object") fail("root must be object");
+
+  for (const key of REQUIRED_TOP) {
+    if (!(key in matrix)) fail(`missing top-level key: ${key}`);
+  }
+
+  const semver = String(matrix.schema_version || "");
+  if (!/^\d+\.\d+$/.test(semver)) fail("schema_version must be major.minor (e.g. 1.1)");
+
+  const ids = new Set();
+  for (const tt of matrix.task_types) {
+    if (!tt.id) fail("task_types entry missing id");
+    if (ids.has(tt.id)) fail(`duplicate task_type id: ${tt.id}`);
+    ids.add(tt.id);
+    if (!tt.capability) fail(`task_type ${tt.id} missing capability`);
+    if (!Array.isArray(tt.keywords)) fail(`task_type ${tt.id} keywords must be array`);
+    if (tt.requires_memory && !MEMORY_LEVELS.has(tt.requires_memory)) {
+      fail(`task_type ${tt.id} invalid requires_memory`);
+    }
+    if (tt.weight_default && !WEIGHTS.has(tt.weight_default)) {
+      fail(`task_type ${tt.id} invalid weight_default`);
+    }
+    if (tt.default_execution_policy && !PLANS.has(tt.default_execution_policy)) {
+      fail(`task_type ${tt.id} invalid default_execution_policy`);
+    }
+    for (const p of tt.providers || []) {
+      if (!p.name || !p.type || !p.resource) {
+        fail(`task_type ${tt.id} provider missing name/type/resource`);
+      }
+    }
+  }
+
+  const policy = matrix.provider_activation_policy;
+  if (policy) {
+    for (const kind of ["memory_providers", "graph_providers"]) {
+      const block = policy[kind];
+      if (!block) continue;
+      if (block.default !== "off" && block.default !== "on") {
+        fail(`${kind}.default must be off|on`);
+      }
+    }
+  }
+
+  for (const chain of matrix.capability_chains || []) {
+    if (!chain.from_capability || !chain.then_capability) {
+      fail("capability_chains entry needs from_capability and then_capability");
+    }
+  }
+
+  console.log(`matrix valid (schema_version ${matrix.schema_version}, ${matrix.task_types.length} task_types)`);
+}
+
+const matrixPath = process.argv[2] || path.join(root, "skill-routing-matrix.json");
+if (!fs.existsSync(matrixPath)) fail(`file not found: ${matrixPath}`);
+validateMatrix(JSON.parse(fs.readFileSync(matrixPath, "utf-8")));

package/skill-routing-matrix.json

@@ -0,0 +1,150 @@
+{
+  "schema_version": "1.2",
+  "updated_at": "2026-05-30",
+  "resolver_order": ["exact_keyword", "domain_rules", "classification_default"],
+  "fallback_policy": {
+    "ambiguous_default_capability": "request-clarification",
+    "override_hint": "/workflow"
+  },
+  "execution_policy_defaults": {
+    "light": "auto",
+    "medium": "confirm",
+    "heavy": "confirm"
+  },
+  "clarification_policy": {
+    "mode": "always_confirm",
+    "max_options": 3,
+    "default_option": "plan_first"
+  },
+  "verification_defaults": {
+    "require_on_light": false,
+    "profile": "standard"
+  },
+  "provider_activation_policy": {
+    "memory_providers": {
+      "default": "off",
+      "require_doctor_pass": true,
+      "allow_on_light": false,
+      "high_risk_capabilities": ["incident-response", "threat-modeling", "memory-retrieval"]
+    },
+    "graph_providers": {
+      "default": "off",
+      "require_doctor_pass": true,
+      "allow_on_light": false,
+      "high_risk_capabilities": ["memory-retrieval"]
+    }
+  },
+  "capability_chains": [
+    {
+      "from_capability": "systematic-debugging",
+      "then_capability": "refactor-simplify",
+      "when": "plan_first"
+    },
+    {
+      "from_capability": "refactor-simplify",
+      "then_capability": "verification",
+      "when": "after_apply"
+    }
+  ],
+  "classification": {
+    "security_override_min": "medium",
+    "ambiguous_default": "medium",
+    "multi_item_bundle_min": "medium",
+    "file_thresholds": { "medium": 3, "heavy": 10 },
+    "security_keywords": ["auth", "login", "session", "payment", "secret", "credential", ".env"],
+    "heavy_keywords": ["new module", "architecture", "mimari", "schema design", "from scratch"],
+    "medium_keywords": ["migration", "endpoint", "refactor", "unit test", "todo", "api"]
+  },
+  "rules_domain_map": {
+    "rules/security.md": {
+      "skills": ["security-hardening"],
+      "weight_min": "medium"
+    },
+    "rules/testing.md": {
+      "skills": ["test-driven-development"],
+      "weight_min": "medium"
+    }
+  },
+  "task_types": [
+    {
+      "id": "debug",
+      "capability": "systematic-debugging",
+      "phase": "build",
+      "orchestration_pattern": "producer_reviewer",
+      "keywords": ["bug", "error", "broken", "fix", "hata", "çalışmıyor"],
+      "weight_default": "medium",
+      "requires_memory": "optional",
+      "default_execution_policy": "confirm",
+      "verification_profile": "debug",
+      "providers": [
+        { "name": "workflow", "type": "workflow", "resource": "forge", "confidence_base": 0.84 },
+        { "name": "skill", "type": "skill", "resource": "systematic-debugging", "confidence_base": 0.8 }
+      ],
+      "skills": ["systematic-debugging"],
+      "workflow": "/forge"
+    },
+    {
+      "id": "i18n",
+      "capability": "localization-hub",
+      "phase": "build",
+      "orchestration_pattern": "expert_pool",
+      "keywords": ["i18n", "localization", "çeviri", "lang file", "translation hub"],
+      "weight_default": "medium",
+      "requires_memory": "optional",
+      "default_execution_policy": "confirm",
+      "providers": [
+        { "name": "skill", "type": "skill", "resource": "localization-hub", "confidence_base": 0.9 }
+      ],
+      "skills": ["localization-hub"],
+      "workflow": null
+    },
+    {
+      "id": "refactor",
+      "capability": "refactor-simplify",
+      "phase": "build",
+      "orchestration_pattern": "pipeline",
+      "keywords": ["refactor", "clean up", "simplify", "code smell"],
+      "weight_default": "medium",
+      "requires_memory": "optional",
+      "default_execution_policy": "confirm",
+      "verification_profile": "refactor",
+      "providers": [
+        { "name": "workflow", "type": "workflow", "resource": "forge", "confidence_base": 0.79 },
+        { "name": "skill", "type": "skill", "resource": "refactor", "confidence_base": 0.77 }
+      ],
+      "skills": ["refactor"],
+      "workflow": "/forge"
+    },
+    {
+      "id": "memory_lookup",
+      "capability": "memory-retrieval",
+      "phase": "analyze",
+      "orchestration_pattern": "expert_pool",
+      "keywords": ["memory lookup", "what did we decide", "geçen karar", "history"],
+      "weight_default": "light",
+      "requires_memory": "required",
+      "default_execution_policy": "confirm",
+      "verification_required": true,
+      "providers": [
+        { "name": "skill", "type": "skill", "resource": "context-memory-bridge", "confidence_base": 0.86 }
+      ],
+      "skills": ["context-memory-bridge"],
+      "workflow": null
+    },
+    {
+      "id": "workflow_override",
+      "capability": "workflow-override",
+      "phase": "meta",
+      "orchestration_pattern": "supervisor",
+      "keywords": ["/workflow", "/skill", "override"],
+      "weight_default": "light",
+      "requires_memory": "none",
+      "default_execution_policy": "override",
+      "providers": [
+        { "name": "skill", "type": "skill", "resource": "capability-router", "confidence_base": 0.88 }
+      ],
+      "skills": ["capability-router"],
+      "workflow": null
+    }
+  ]
+}

package/skills/capability-router/SKILL.md

@@ -0,0 +1,3 @@
+# capability-router
+
+Routes normalized intent to capabilities/providers using `skill-routing-matrix.json`.

package/skills/context-memory-bridge/SKILL.md

@@ -0,0 +1,17 @@
+# context-memory-bridge
+
+Use when the task requires prior decisions, handoff context, or session history lookup.
+
+## When
+
+- memory lookup, what did we decide, geçen karar, history
+
+## Steps
+
+1. Read HANDOFF.md, AGENT.md, design.md when present
+2. Summarize relevant prior decisions
+3. Do not invent history; cite file paths
+
+## CapInt
+
+Matrix capability: `memory-retrieval` · Memory: required

package/skills/localization-hub/SKILL.md

@@ -0,0 +1,17 @@
+# localization-hub
+
+Use for i18n, translation files, locale keys, and language hub tasks.
+
+## When
+
+- User mentions i18n, localization, çeviri, lang file, translation hub
+
+## Steps
+
+1. Identify target locales and key namespaces
+2. Check existing translation patterns in the repo
+3. Apply consistent key naming; avoid hardcoded strings
+
+## CapInt
+
+Matrix capability: `localization-hub`

package/skills/refactor/SKILL.md

@@ -0,0 +1,17 @@
+# refactor
+
+Use when simplifying code, reducing smell, or cleaning structure without changing behavior.
+
+## When
+
+- refactor, clean up, simplify, code smell
+
+## Steps
+
+1. Ensure tests exist or add minimal coverage
+2. Make smallest structural change
+3. Re-run tests; no behavior change unless intended
+
+## CapInt
+
+Matrix capability: `refactor-simplify` · Workflow: `/forge`

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,19 @@
+# systematic-debugging
+
+Use when fixing bugs, errors, or unexpected behavior before proposing fixes.
+
+## When
+
+- User reports broken behavior, test failures, or regressions
+- Keywords: bug, error, fix, hata, çalışmıyor
+
+## Steps
+
+1. Reproduce the issue with minimal steps
+2. Gather evidence (logs, stack traces)
+3. Form hypothesis; test one change at a time
+4. Verify fix with targeted test
+
+## CapInt
+
+Matrix capability: `systematic-debugging` · Workflow: `/forge`

package/src/commands/audit.js

@@ -0,0 +1,32 @@
+const { runAudit } = require("../lib/audit");
+
+module.exports = async function audit(_args, flags) {
+  const rootDir = process.cwd();
+  const report = runAudit(rootDir);
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.pass) process.exit(report.exit_code);
+    return;
+  }
+
+  console.log("\n## CapInt Audit (read-only)\n");
+  console.log(`Result: ${report.pass ? "PASS" : "FAIL"}`);
+  console.log(`Doctor: ${report.doctor_pass ? "pass" : "fail"}`);
+  console.log(`Findings: ${report.summary.issues} issues, ${report.summary.warnings} warnings, ${report.summary.info} info\n`);
+
+  if (report.findings.length) {
+    for (const f of report.findings) {
+      console.log(`  [${f.level}] ${f.message}`);
+    }
+    console.log("");
+  }
+
+  if (report.recommendations.length) {
+    console.log("Recommendations:");
+    for (const r of report.recommendations) console.log(`  - ${r}`);
+    console.log("");
+  }
+
+  if (!report.pass) process.exit(report.exit_code);
+};

package/src/commands/consult.js

@@ -0,0 +1,64 @@
+const { routeTask } = require("../lib/route-engine");
+const { validateExecutionIntent } = require("../lib/contract");
+
+module.exports = async function consult(args, flags) {
+  const rootDir = process.cwd();
+  const text = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+  if (!text) {
+    console.error('Provide task text: capint consult "fix i18n bug"');
+    process.exit(1);
+  }
+
+  const result = routeTask(text, rootDir);
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  const contract = validateExecutionIntent(result.execution_intent);
+  const payload = {
+    mode: "dry_run",
+    side_effects: false,
+    request: text,
+    recommendation: {
+      capability: result.execution_intent.capability,
+      resolution: result.execution_intent.resolution,
+      memory: result.execution_intent.memory,
+      plan: result.execution_intent.plan,
+      confirm_default: result.execution_intent.confirm_default_option,
+      verification_required: result.execution_intent.verification_required,
+      provider_activation: result.execution_intent.provider_activation
+    },
+    weight: result.overall_weight,
+    contract_valid: contract.valid,
+    contract_errors: contract.errors,
+    next_commands: [
+      `capint route --json "${text.replace(/"/g, '\\"')}"`,
+      "capint doctor",
+      "capint status --json"
+    ]
+  };
+
+  if (flags.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log("\n## CapInt Consult (dry-run, no side effects)\n");
+  console.log(`Task: ${text}`);
+  console.log(`Capability: ${payload.recommendation.capability}`);
+  console.log(`Resolution: ${payload.recommendation.resolution}`);
+  console.log(`Memory: ${payload.recommendation.memory}`);
+  console.log(`Plan: ${payload.recommendation.plan}`);
+  console.log(`Weight: ${payload.weight}`);
+  console.log(`Verification: ${payload.recommendation.verification_required ? "required" : "optional"}`);
+  if (payload.recommendation.provider_activation) {
+    const pa = payload.recommendation.provider_activation;
+    console.log(
+      `Providers: memory=${pa.memory?.activated ? "on" : "off"}, graph=${pa.graph?.activated ? "on" : "off"}`
+    );
+  }
+  console.log("\nSuggested next:");
+  for (const c of payload.next_commands) console.log(`  ${c}`);
+  console.log("");
+};

package/src/commands/doctor.js

@@ -0,0 +1,36 @@
+const { runDoctor } = require("../lib/doctor");
+
+module.exports = async function doctor(_args, flags) {
+  const rootDir = process.cwd();
+  const report = runDoctor(rootDir);
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.pass) process.exit(report.exit_code);
+    return;
+  }
+
+  console.log("\n## CapInt Doctor\n");
+  console.log(`Result: ${report.pass ? "PASS" : "FAIL"}`);
+  console.log(`Auto-fix: ${report.auto_fix ? "yes" : "no"}\n`);
+
+  if (report.ok.length) {
+    console.log("OK:");
+    for (const o of report.ok) console.log(`  + ${o}`);
+    console.log("");
+  }
+  if (report.warnings.length) {
+    console.log("Warnings:");
+    for (const w of report.warnings) console.log(`  ! ${w}`);
+    console.log("");
+  }
+  if (report.issues.length) {
+    console.log("Issues:");
+    for (const i of report.issues) console.log(`  x ${i}`);
+    console.log("");
+  }
+  console.log(report.hint);
+  console.log("");
+
+  if (!report.pass) process.exit(report.exit_code);
+};

package/src/commands/ide.js

@@ -0,0 +1,62 @@
+const path = require("path");
+const {
+  syncIdeProjections,
+  checkIdeProjection,
+  appendIdeManifestEntries,
+  DEFAULT_TARGETS,
+  CAPINT_SYNC_MARKER
+} = require("../lib/ide-sync");
+
+module.exports = async function ide(args, flags) {
+  const sub = args[0];
+  const rootDir = process.cwd();
+  const dryRun = Boolean(flags["dry-run"]);
+
+  if (sub === "check") {
+    const checks = checkIdeProjection(rootDir);
+    if (flags.json) {
+      console.log(JSON.stringify({ marker: CAPINT_SYNC_MARKER, checks }, null, 2));
+      return;
+    }
+    console.log("\n## CapInt IDE check\n");
+    for (const c of checks) {
+      console.log(`  ${c.ok ? "✓" : "✗"} ${c.name} (${c.path})`);
+    }
+    console.log("");
+    return;
+  }
+
+  if (sub !== "sync") {
+    console.error("Usage: capint ide sync|check [--dry-run] [--json] [--targets cursor,claude,...]");
+    process.exit(1);
+  }
+
+  const targets = flags.targets
+    ? flags.targets.split(",").map((t) => t.trim())
+    : DEFAULT_TARGETS;
+
+  const result = syncIdeProjections(rootDir, { targets, dryRun });
+  if (result.errors.length) {
+    console.error(result.errors.join("; "));
+    process.exit(1);
+  }
+
+  if (!dryRun) {
+    appendIdeManifestEntries(rootDir, result, dryRun);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log("\n## CapInt IDE sync\n");
+  if (dryRun) console.log("(dry-run — no files written)\n");
+  for (const w of result.written) {
+    console.log(`  wrote ${path.relative(rootDir, w) || w}`);
+  }
+  for (const s of result.skipped) {
+    console.log(`  skipped: ${s}`);
+  }
+  console.log("");
+};

package/src/commands/init.js

@@ -0,0 +1,50 @@
+const path = require("path");
+const { runScaffold, PRESET_MANIFEST } = require("../lib/scaffold");
+const { syncIdeProjections, appendIdeManifestEntries } = require("../lib/ide-sync");
+
+module.exports = async function init(args, flags) {
+  const rootDir = process.cwd();
+  const preset = flags.preset || "minimal";
+  const projectName = flags.name || path.basename(rootDir);
+  const force = Boolean(flags.force);
+  const ideSync = !flags["no-ide-sync"];
+
+  const report = runScaffold({ rootDir, preset, projectName, force });
+  if (report.error) {
+    console.error(report.error);
+    process.exit(1);
+  }
+
+  let ideResult = null;
+  if (ideSync) {
+    ideResult = syncIdeProjections(rootDir, { dryRun: false });
+    if (ideResult.errors.length === 0) {
+      appendIdeManifestEntries(rootDir, ideResult, false);
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ...report, ide_sync: ideResult }, null, 2));
+    return;
+  }
+
+  console.log("\n## CapInt Init\n");
+  console.log(`Preset: ${preset}`);
+  console.log(`Project: ${projectName}`);
+  console.log(`Created: ${report.summary.created}, Updated: ${report.summary.updated}, Skipped: ${report.summary.skipped}, Conflicts: ${report.summary.conflict}\n`);
+  for (const r of report.results) {
+    const extra = r.sidecar ? ` -> see ${r.sidecar}` : r.reason ? ` (${r.reason})` : "";
+    console.log(`  [${r.action}] ${r.path}${extra}`);
+  }
+  if (ideSync && ideResult) {
+    if (ideResult.errors.length) {
+      console.log(`\nIDE sync skipped: ${ideResult.errors.join("; ")}`);
+    } else {
+      console.log(`\nIDE sync: ${ideResult.written.length} projection(s) written`);
+    }
+  } else if (!ideSync) {
+    console.log("\nIDE sync skipped (--no-ide-sync). Run: capint ide sync");
+  }
+  console.log("\nNext: capint route \"i18n\"");
+  console.log("Conflict policy: existing files without capint managed blocks are never overwritten.\n");
+};

package/src/commands/memory.js

@@ -0,0 +1,60 @@
+const fs = require("fs");
+const path = require("path");
+const { loadProvidersConfig, DEFAULT_PATHS, search } = require("../lib/providers/local-memory-adapter");
+const { loadProvidersConfig: loadGraphCfg, DEFAULT_PATHS: GRAPH_PATHS, query } = require("../lib/providers/local-graph-adapter");
+const { localContextEnabled } = require("../lib/context-memory-bridge");
+
+function fileStatus(rootDir, rel) {
+  const abs = path.join(rootDir, rel);
+  return { path: rel, exists: fs.existsSync(abs) };
+}
+
+module.exports = async function memory(args, flags) {
+  const sub = args[0];
+  const rootDir = process.cwd();
+
+  if (sub !== "status") {
+    console.error("Usage: capint memory status [--json]");
+    process.exit(1);
+  }
+
+  const memCfg = loadProvidersConfig(rootDir);
+  const graphCfg = loadGraphCfg(rootDir);
+  const memPaths = memCfg?.memory?.paths || DEFAULT_PATHS;
+  const graphPaths = graphCfg?.graph?.paths || GRAPH_PATHS;
+
+  const report = {
+    mode: "read_only",
+    local_context_flag: localContextEnabled({}),
+    env_CAPINT_LOCAL_CONTEXT: process.env.CAPINT_LOCAL_CONTEXT || null,
+    providers_config: fs.existsSync(path.join(rootDir, ".capint", "providers.json")),
+    memory: {
+      driver: memCfg?.memory?.driver || "local (default)",
+      paths: memPaths.map((p) => fileStatus(rootDir, p))
+    },
+    graph: {
+      driver: graphCfg?.graph?.driver || "local (default)",
+      paths: graphPaths.map((p) => fileStatus(rootDir, p))
+    },
+    sample_memory_search: search(rootDir, "", { config: memCfg }).hits.length,
+    sample_graph_query: query(rootDir, null, { config: graphCfg }).excerpts.length
+  };
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("\n## CapInt memory status\n");
+  console.log(`Local context hot-path: ${report.local_context_flag ? "enabled" : "off (set CAPINT_LOCAL_CONTEXT=1)"}`);
+  console.log(`providers.json: ${report.providers_config ? "yes" : "no (optional)"}\n`);
+  console.log("Memory paths:");
+  for (const p of report.memory.paths) {
+    console.log(`  ${p.exists ? "✓" : "✗"} ${p.path}`);
+  }
+  console.log("\nGraph paths:");
+  for (const p of report.graph.paths) {
+    console.log(`  ${p.exists ? "✓" : "✗"} ${p.path}`);
+  }
+  console.log("");
+};

package/src/commands/route.js

@@ -0,0 +1,30 @@
+const path = require("path");
+const { routeTask, formatTextReport, listCheatsheet, loadMatrix } = require("../lib/route-engine");
+
+module.exports = async function route(args, flags) {
+  const rootDir = process.cwd();
+
+  if (flags.list) {
+    const matrix = loadMatrix(rootDir);
+    if (!matrix) {
+      console.error("No skill-routing-matrix.json found");
+      process.exit(1);
+    }
+    console.log("\n" + listCheatsheet(matrix));
+    return;
+  }
+
+  const text = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+  if (!text) {
+    console.error('Provide task text: capint route "fix i18n bug"');
+    process.exit(1);
+  }
+
+  const result = routeTask(text, rootDir);
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(formatTextReport(result, { verbose: Boolean(flags.verbose || flags.v) }));
+};