@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/mcp/README.md

@@ -1,6 +1,6 @@
 # 🔌 Kilo-Kit MCP Server
 
-> **Version:** 1.1.0
+> **Version:** 1.2.0
 > **Mode:** Read-only Skill Registry + Validator
 > **Transport:** stdio
 
@@ -12,9 +12,12 @@ The Kilo-Kit MCP server exposes the `skills/` workflow surface to MCP-capable ag
 
 | Capability | MCP Tool | Purpose |
 |------------|----------|---------|
+| C4 orchestration | `kilo_orchestrate_task` | Enforce brainstorming-first workflow, required questions, memory suggestions, and final workflow release |
 | Skill discovery | `kilo_search_skills` | Search the skill library by task/query |
-| Intent routing | `kilo_route_intent` | Recommend skills for the current chat context |
+| Intent routing | `kilo_route_intent` | Recommend skills, workflow order, rule hierarchy, and decision trail for the current chat context |
 | Skill loading | `kilo_get_skill` | Load one exact `SKILL.md` with output limits |
+| Route reporting | `kilo_route_report` | Summarize route telemetry, top skills, workflows, scores, and conflict penalties |
+| Memory reporting | `kilo_memory_report` | Inspect C4 global memory facts, decisions, and suggestions |
 | Quality gate | `kilo_validate_skills` | Run the Kilo-Kit skill validator summary |
 
 Resources:
@@ -47,8 +50,8 @@ npm run smoke
 Expected verification:
 
 ```text
-Test Files  4 passed
-Tests       8 passed
+Test Files  9 passed
+Tests       22 passed
 MCP smoke check passed.
 ```
 
@@ -71,14 +74,57 @@ Use the published npm package in any MCP-capable client:
 
 The npm package includes the Kilo-Kit skill library, core master file, validator, and built MCP server.
 
-Maintainers publish the npm package from the repository root:
+Route telemetry is in-memory by default. To persist route decisions between server runs, set:
 
 ```bash
-npm login
-npm publish --access public
+KILO_KIT_WRITE_DECISIONS=true
+# optional override:
+KILO_KIT_DECISION_TRAIL_PATH=/absolute/path/decision-trail.jsonl
 ```
 
-The root `prepublishOnly` gate runs build, typecheck, tests, smoke, and skill validation before npm accepts the publish.
+When persistence is enabled and no override is provided, decisions are written to `.kilo/decision-trail.jsonl` under the configured repository root.
+
+C4 orchestration memory is global by default at `~/.kilo-kit/orchestrator.sqlite` when Node's SQLite runtime is available. Override it with:
+
+```bash
+KILO_KIT_MEMORY_PATH=/absolute/path/orchestrator.sqlite
+KILO_KIT_ORCHESTRATION_AUDIT_PATH=/absolute/path/orchestration-audit.jsonl
+```
+
+`kilo_orchestrate_task` uses the C4 Brainstorming-First Gate: substantive work starts with `productivity/brainstorming`, then required questions, then memory suggestions that require explicit accept/reject before a final workflow is released.
+
+### Codex CLI on Windows
+
+When Codex is opened inside the Kilo-Kit source checkout, `npx -y @vodailoc/kilo-kit-mcp` can resolve the local package instead of the published package. Use an npm prefix outside the repository:
+
+```toml
+[mcp_servers.kilo-kit]
+command = "npm"
+args = ["exec", "--prefix", "C:\\Users\\Admin", "--yes", "--package=@vodailoc/kilo-kit-mcp", "--", "kilo-kit-mcp"]
+startup_timeout_sec = 60
+enabled = true
+```
+
+### Publishing
+
+Kilo-Kit publishes through npm Trusted Publishing, so releases do not require a long-lived npm token or an interactive OTP.
+
+Configure the npm package once:
+
+1. Open `@vodailoc/kilo-kit-mcp` on npm.
+2. Go to `Settings` -> `Trusted publishing`.
+3. Select `GitHub Actions`.
+4. Use repository `VoDaiLocz/KILO-KIT`.
+5. Use workflow filename `publish.yml`.
+
+Then publish by running the GitHub Actions workflow `Publish npm package`, or by pushing a version tag:
+
+```bash
+git tag v1.2.0
+git push origin v1.2.0
+```
+
+The workflow runs build, typecheck, tests, smoke, skill validation, package dry-run, and then `npm publish --access public --ignore-scripts` through OIDC.
 
 ### Local Development
 
@@ -112,7 +158,9 @@ Use `.mcp/kilo-kit.example.json` as the portable template.
 
 ## 🛡️ Security Posture
 
-- Read-only tools only.
+- Externally read-only by default.
+- Route telemetry is in-memory by default; JSONL persistence is opt-in with `KILO_KIT_WRITE_DECISIONS=true`.
+- C4 memory stores structured facts and decisions, not raw chat logs.
 - No arbitrary filesystem reads.
 - Category and skill names must be single kebab-case path segments.
 - Repository paths are resolved through an allowlist boundary.
@@ -125,8 +173,12 @@ Use `.mcp/kilo-kit.example.json` as the portable template.
 
 ```text
 User request
-→ kilo_route_intent(message, context)
-→ kilo_get_skill(category, skill)
-→ follow selected SKILL.md
+→ kilo_orchestrate_task(message, context)
+→ answer required C4 questions
+→ accept/reject memory suggestions
+→ kilo_get_skill(category, skill) for the first workflow skill
+→ follow final workflow skills in order
+→ kilo_route_report when you need routing analytics
+→ kilo_memory_report when you need memory analytics
 → kilo_validate_skills before claiming the skill library is healthy
 ```

package/mcp/dist/formatters.js

@@ -54,7 +54,23 @@ export function formatRoute(result, format) {
     return [
         "# Kilo-Kit Skill Route",
         "",
-        ...result.recommended.map((item, index) => `${index + 1}. **${item.skill.id}** (${Math.round(item.confidence * 100)}%)\n   ${item.reason}\n   Path: \`${item.skill.skillPath}\``),
+        `Task mode: \`${result.taskMode}\``,
+        "",
+        "## Recommended Skills",
+        "",
+        ...result.recommended.map((item, index) => `${index + 1}. **${item.skill.id}** (${Math.round(item.confidence * 100)}%, score ${item.score ?? "n/a"})\n   ${item.reason}\n   Path: \`${item.skill.skillPath}\``),
+        "",
+        "## Workflow",
+        "",
+        ...result.workflow.map((step, index) => `${index + 1}. **${step.skill.id}** (${step.role})\n   ${step.reason}`),
+        "",
+        "## Rule Hierarchy",
+        "",
+        result.ruleHierarchy.map((rule, index) => `${index + 1}. \`${rule}\``).join("\n"),
+        "",
+        "## Decision Trail",
+        "",
+        ...result.decisionTrail.slice(0, 5).map((entry, index) => `${index + 1}. **${entry.skillId}** score ${entry.score}\n   Signals: ${entry.matchedSignals.length > 0 ? entry.matchedSignals.map((signal) => `\`${signal}\``).join(", ") : "none"}\n   ${entry.reason}`),
         "",
         `Next action: ${result.nextAction}`,
     ].join("\n");
@@ -75,3 +91,128 @@ export function formatValidation(summary, format) {
         "```",
     ].join("\n");
 }
+export function formatRouteReport(report, format) {
+    if (format === "json") {
+        return JSON.stringify(report, null, 2);
+    }
+    const taskModes = report.taskModes.length > 0
+        ? report.taskModes.map((item) => `- \`${item.taskMode}\`: ${item.count}`).join("\n")
+        : "- No task modes recorded.";
+    const workflows = report.workflows.length > 0
+        ? report.workflows
+            .slice(0, 5)
+            .map((item) => `- ${item.workflow.map((skill) => `\`${skill}\``).join(" -> ")}: ${item.count}`)
+            .join("\n")
+        : "- No workflows recorded.";
+    const topSkills = report.topSkills.length > 0
+        ? report.topSkills
+            .slice(0, 10)
+            .map((item) => `- \`${item.skillId}\`: recommended ${item.timesRecommended}, workflow ${item.timesInWorkflow}, primary ${item.timesPrimary}, avg score ${item.avgScore}`)
+            .join("\n")
+        : "- No skills recorded.";
+    const conflicts = report.conflictPenalties.length > 0
+        ? report.conflictPenalties
+            .map((item) => `- \`${item.skillId}\`: ${item.count} penalties, total ${item.totalPenalty}`)
+            .join("\n")
+        : "- No conflict penalties recorded.";
+    return [
+        "# Kilo-Kit Route Report",
+        "",
+        `Total events: **${report.totalEvents}**`,
+        "",
+        "## Task Modes",
+        taskModes,
+        "",
+        "## Workflows",
+        workflows,
+        "",
+        "## Top Skills",
+        topSkills,
+        "",
+        "## Conflict Penalties",
+        conflicts,
+    ].join("\n");
+}
+export function formatOrchestration(result, format) {
+    if (format === "json") {
+        return JSON.stringify(result, null, 2);
+    }
+    const questions = result.questions.length > 0
+        ? result.questions
+            .map((question, index) => `${index + 1}. **${question.id}**${question.required ? " (required)" : ""}\n   ${question.prompt}`)
+            .join("\n")
+        : "No questions required.";
+    const workflow = result.workflow.length > 0
+        ? result.workflow.map((step, index) => `${index + 1}. **${step.skill.id}** (${step.role})\n   ${step.reason}`).join("\n")
+        : "No workflow selected.";
+    const memorySuggestions = result.memorySuggestions.length > 0
+        ? result.memorySuggestions
+            .map((suggestion) => `- **${suggestion.key}** (${Math.round(suggestion.confidence * 100)}%)\n  ${suggestion.reason}\n  Requires confirmation: ${suggestion.requiresConfirmation ? "yes" : "no"}`)
+            .join("\n")
+        : "- No memory suggestions.";
+    const verification = result.verificationGate.commands.length > 0
+        ? result.verificationGate.commands.map((command) => `- \`${command}\``).join("\n")
+        : "- No commands selected.";
+    return [
+        "# Kilo-Kit C4 Orchestration",
+        "",
+        `Session: \`${result.sessionId}\``,
+        `State: \`${result.state}\``,
+        `Task mode: \`${result.taskMode}\``,
+        "",
+        "## Questions",
+        questions,
+        "",
+        "## Workflow",
+        workflow,
+        "",
+        "## Memory Suggestions",
+        memorySuggestions,
+        "",
+        "## Verification Gate",
+        verification,
+        "",
+        `Next action: ${result.nextAction}`,
+    ].join("\n");
+}
+export function formatMemoryReport(report, format) {
+    if (format === "json") {
+        return JSON.stringify(report, null, 2);
+    }
+    const facts = report.facts.length > 0
+        ? report.facts
+            .slice(0, 20)
+            .map((fact) => `- \`${fact.key}\` (${fact.kind}, confidence ${fact.confidence}) from ${fact.source}`)
+            .join("\n")
+        : "- No memory facts recorded.";
+    const decisions = report.decisions.length > 0
+        ? report.decisions.map((decision) => `- \`${decision.suggestionKey}\`: ${decision.decision}`).join("\n")
+        : "- No memory decisions recorded.";
+    const sessions = report.sessions.length > 0
+        ? report.sessions
+            .slice(0, 10)
+            .map((session) => `- \`${session.id}\`: ${session.state} (${session.taskMode})`)
+            .join("\n")
+        : "- No orchestration sessions recorded.";
+    const outcomes = report.outcomes.length > 0
+        ? report.outcomes
+            .slice(0, 10)
+            .map((outcome) => `- \`${outcome.id}\`: ${outcome.outcome} (${outcome.taskMode})`)
+            .join("\n")
+        : "- No workflow outcomes recorded.";
+    return [
+        "# Kilo-Kit Memory Report",
+        "",
+        "## Facts",
+        facts,
+        "",
+        "## Decisions",
+        decisions,
+        "",
+        "## Sessions",
+        sessions,
+        "",
+        "## Outcomes",
+        outcomes,
+    ].join("\n");
+}

package/mcp/dist/orchestration-audit.js

@@ -0,0 +1,20 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+export function createNoopOrchestrationAudit() {
+    return {
+        record() {
+            return undefined;
+        },
+    };
+}
+export function createJsonlOrchestrationAudit(filePath) {
+    return {
+        record(event) {
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            const auditRef = randomUUID();
+            appendFileSync(filePath, `${JSON.stringify({ auditRef, timestamp: new Date().toISOString(), ...event })}\n`, "utf8");
+            return auditRef;
+        },
+    };
+}

package/mcp/dist/orchestration-memory.js

@@ -0,0 +1,258 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+export function createInMemoryOrchestrationMemory(initialFacts = []) {
+    const facts = new Map(initialFacts.map((fact) => [fact.key, clone(fact)]));
+    const decisions = [];
+    const suggestions = [];
+    const sessions = new Map();
+    const outcomes = [];
+    return {
+        rememberFact(fact) {
+            facts.set(fact.key, normalizeFact(fact, facts.get(fact.key)));
+        },
+        suggest(input) {
+            const produced = buildSuggestions([...facts.values()], input);
+            suggestions.splice(0, suggestions.length, ...produced.map(clone));
+            return produced;
+        },
+        recordDecision(decision) {
+            decisions.push({ ...decision });
+        },
+        recordSession(session) {
+            sessions.set(session.id, clone(session));
+        },
+        recordOutcome(outcome) {
+            outcomes.push(clone(outcome));
+        },
+        report() {
+            return {
+                facts: [...facts.values()].map(clone),
+                decisions: decisions.map((decision) => ({ ...decision })),
+                suggestions: suggestions.map(clone),
+                sessions: [...sessions.values()].map(clone),
+                outcomes: outcomes.map(clone),
+            };
+        },
+    };
+}
+export async function createSqliteOrchestrationMemory(options) {
+    let sqlite;
+    try {
+        sqlite = await import("node:sqlite");
+    }
+    catch {
+        return createInMemoryOrchestrationMemory();
+    }
+    mkdirSync(path.dirname(options.filePath), { recursive: true });
+    const database = new sqlite.DatabaseSync(options.filePath);
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS memory_facts (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      key TEXT NOT NULL UNIQUE,
+      value_json TEXT NOT NULL,
+      confidence REAL NOT NULL,
+      source TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS memory_decisions (
+      id TEXT PRIMARY KEY,
+      suggestion_key TEXT NOT NULL,
+      decision TEXT NOT NULL,
+      reason TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS orchestration_sessions (
+      id TEXT PRIMARY KEY,
+      state TEXT NOT NULL,
+      message TEXT NOT NULL,
+      task_mode TEXT NOT NULL,
+      route_json TEXT NOT NULL,
+      questions_json TEXT NOT NULL,
+      answers_json TEXT NOT NULL,
+      memory_suggestions_json TEXT NOT NULL,
+      final_workflow_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS workflow_outcomes (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      task_mode TEXT NOT NULL,
+      workflow_json TEXT NOT NULL,
+      verification_json TEXT NOT NULL,
+      outcome TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+  `);
+    return {
+        rememberFact(fact) {
+            const existing = factByKey(database, fact.key);
+            const normalized = normalizeFact(fact, existing);
+            database
+                .prepare(`INSERT INTO memory_facts (id, kind, key, value_json, confidence, source, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(key) DO UPDATE SET
+             kind = excluded.kind,
+             value_json = excluded.value_json,
+             confidence = excluded.confidence,
+             source = excluded.source,
+             updated_at = excluded.updated_at`)
+                .run(normalized.id, normalized.kind, normalized.key, JSON.stringify(normalized.value), normalized.confidence, normalized.source, normalized.createdAt, normalized.updatedAt);
+        },
+        suggest(input) {
+            return buildSuggestions(allFacts(database), input);
+        },
+        recordDecision(decision) {
+            database
+                .prepare(`INSERT INTO memory_decisions (id, suggestion_key, decision, reason, created_at)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(randomUUID(), decision.suggestionKey, decision.decision, decision.reason ?? null, new Date().toISOString());
+        },
+        recordSession(session) {
+            database
+                .prepare(`INSERT INTO orchestration_sessions
+             (id, state, message, task_mode, route_json, questions_json, answers_json, memory_suggestions_json, final_workflow_json, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             state = excluded.state,
+             message = excluded.message,
+             task_mode = excluded.task_mode,
+             route_json = excluded.route_json,
+             questions_json = excluded.questions_json,
+             answers_json = excluded.answers_json,
+             memory_suggestions_json = excluded.memory_suggestions_json,
+             final_workflow_json = excluded.final_workflow_json,
+             updated_at = excluded.updated_at`)
+                .run(session.id, session.state, session.message, session.taskMode, JSON.stringify(session.route), JSON.stringify(session.questions), JSON.stringify(session.answers), JSON.stringify(session.memorySuggestions), JSON.stringify(session.finalWorkflow), session.createdAt, session.updatedAt);
+        },
+        recordOutcome(outcome) {
+            database
+                .prepare(`INSERT INTO workflow_outcomes
+             (id, session_id, task_mode, workflow_json, verification_json, outcome, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(outcome.id, outcome.sessionId, outcome.taskMode, JSON.stringify(outcome.workflow), JSON.stringify(outcome.verification), outcome.outcome, outcome.createdAt);
+        },
+        report() {
+            return {
+                facts: allFacts(database),
+                decisions: allDecisions(database),
+                suggestions: [],
+                sessions: allSessions(database),
+                outcomes: allOutcomes(database),
+            };
+        },
+    };
+}
+function buildSuggestions(facts, input) {
+    return facts
+        .filter((fact) => fact.confidence >= 0.7)
+        .filter((fact) => factApplies(fact, input))
+        .map((fact) => ({
+        key: fact.key,
+        title: suggestionTitle(fact),
+        reason: suggestionReason(fact, input),
+        value: clone(fact.value),
+        confidence: fact.confidence,
+        requiresConfirmation: true,
+        applied: false,
+    }));
+}
+function factApplies(fact, input) {
+    if (fact.kind === "verification-default") {
+        return true;
+    }
+    if (fact.kind === "workflow-default") {
+        const skillId = fact.value.skillId;
+        return typeof skillId === "string" && !input.workflowSkillIds.includes(skillId);
+    }
+    if (fact.kind === "task-mode-default") {
+        return fact.value.taskMode === input.taskMode;
+    }
+    return false;
+}
+function suggestionTitle(fact) {
+    if (fact.kind === "verification-default") {
+        return "Apply remembered verification gate";
+    }
+    if (fact.kind === "workflow-default") {
+        return "Apply remembered workflow preference";
+    }
+    return "Apply remembered operating preference";
+}
+function suggestionReason(fact, input) {
+    const project = input.projectFingerprint ? ` for ${input.projectFingerprint}` : "";
+    return `Memory fact '${fact.key}' matched task mode '${input.taskMode}'${project}. Confirmation is required before applying it.`;
+}
+function normalizeFact(input, existing) {
+    const now = new Date().toISOString();
+    return {
+        id: existing?.id ?? randomUUID(),
+        kind: input.kind,
+        key: input.key,
+        value: clone(input.value),
+        confidence: input.confidence,
+        source: input.source,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+}
+function factByKey(database, key) {
+    const row = database.prepare("SELECT * FROM memory_facts WHERE key = ?").get(key);
+    return row ? rowToFact(row) : undefined;
+}
+function allFacts(database) {
+    return database.prepare("SELECT * FROM memory_facts ORDER BY updated_at DESC").all().map(rowToFact);
+}
+function allDecisions(database) {
+    return database.prepare("SELECT * FROM memory_decisions ORDER BY created_at DESC").all().map((row) => ({
+        suggestionKey: row.suggestion_key,
+        decision: row.decision === "accepted" ? "accepted" : "rejected",
+        ...(row.reason ? { reason: row.reason } : {}),
+    }));
+}
+function allSessions(database) {
+    return database
+        .prepare("SELECT * FROM orchestration_sessions ORDER BY updated_at DESC")
+        .all().map((row) => ({
+        id: row.id,
+        state: row.state,
+        message: row.message,
+        taskMode: row.task_mode,
+        route: JSON.parse(row.route_json),
+        questions: JSON.parse(row.questions_json),
+        answers: JSON.parse(row.answers_json),
+        memorySuggestions: JSON.parse(row.memory_suggestions_json),
+        finalWorkflow: JSON.parse(row.final_workflow_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    }));
+}
+function allOutcomes(database) {
+    return database.prepare("SELECT * FROM workflow_outcomes ORDER BY created_at DESC").all().map((row) => ({
+        id: row.id,
+        sessionId: row.session_id,
+        taskMode: row.task_mode,
+        workflow: JSON.parse(row.workflow_json),
+        verification: JSON.parse(row.verification_json),
+        outcome: row.outcome,
+        createdAt: row.created_at,
+    }));
+}
+function rowToFact(row) {
+    return {
+        id: row.id,
+        kind: row.kind,
+        key: row.key,
+        value: JSON.parse(row.value_json),
+        confidence: row.confidence,
+        source: row.source,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/mcp/dist/orchestration-types.js

@@ -0,0 +1 @@
+export {};