@kal-elsam/kairo-runtime 0.1.2 → 0.1.4

package/global-template/components/catalog.json

@@ -20,6 +20,32 @@
         "claude": "- In repos with workspace harness: repo `AGENTS.md` wins over `CLAUDE.md` pointers.",
         "opencode": "- In repos with workspace harness: also read `.opencode/` SDD assets when present."
       }
+    },
+    {
+      "id": "engram-memory",
+      "label": "Engram Memory",
+      "version": "1.0.0",
+      "defaultEnabled": false,
+      "assetFiles": ["memory.md"],
+      "adapterHints": {
+        "cursor": "- Engram MCP (`mem_*` tools) is not auto-installed; configure in Cursor MCP settings when ready.",
+        "codex": "- Engram MCP is not auto-installed; add MCP server config when ready.",
+        "claude": "- Engram MCP is not auto-installed; add MCP server config when ready.",
+        "opencode": "- Engram MCP is not auto-installed; add MCP server config when ready."
+      }
+    },
+    {
+      "id": "graphify-context",
+      "label": "Graphify Context",
+      "version": "1.0.0",
+      "defaultEnabled": false,
+      "assetFiles": ["context-graph.md"],
+      "adapterHints": {
+        "cursor": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "codex": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "claude": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "opencode": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH."
+      }
     }
   ]
 }

package/global-template/components/engram-memory/memory.md

@@ -0,0 +1,58 @@
+# Engram Memory Contract
+
+> Managed by `@kal-elsam/kairo-runtime` component `engram-memory`.
+
+## Role
+
+Engram is an optional external memory layer. It indexes decisions, bugs, and
+conventions across sessions. It does not replace the repository as source of
+truth.
+
+## Authority order
+
+```txt
+1. Current user instruction
+2. Repository AGENTS.md (when working inside a repo)
+3. Repository docs/ai/ and docs/specs/
+4. Engram (persistent memory)
+5. Graphify (context graph)
+```
+
+If Engram contradicts AGENTS.md or repo docs, the repo wins. Update or discard
+stale memory instead of following it blindly.
+
+## When to search memory
+
+Search Engram before:
+
+- Starting a non-trivial task or a standard/complex spec.
+- Diagnosing a bug that feels familiar or recurring.
+- Proposing a new architecture or convention.
+- Resuming work after context compaction or a new session.
+- Repeating a loop task (see loop-retrospective guidance when present).
+
+Skip memory search for trivial changes (typos, formatting, comments) or tasks
+fully specified in an active spec.
+
+## When to save memory
+
+Save proactively after:
+
+- Architecture or policy decisions (with reasoning, not just the outcome).
+- Bug root causes that may recur.
+- Undocumented conventions discovered in code review.
+- Loop retrospectives and discarded approaches (with why they were rejected).
+
+Do not save secrets, credentials, PII, ephemeral debug output, or content
+already documented in AGENTS.md or docs/ai/.
+
+## MCP tools
+
+Engram is not bundled with Kairo Runtime. Configure Engram MCP tools
+(`mem_search`, `mem_save`, etc.) in your agent when you want persistent memory.
+Kairo only ships the contract and health checks — not the MCP server itself.
+
+## Decision traceability
+
+Important decisions belong in `docs/ai/decision-log.md` or an ADR. Engram
+indexes; the repo certifies.

package/global-template/components/graphify-context/context-graph.md

@@ -0,0 +1,58 @@
+# Graphify Context Contract
+
+> Managed by `@kal-elsam/kairo-runtime` component `graphify-context`.
+
+## Role
+
+Graphify is an optional context graph for architecture navigation. It maps
+modules, dependencies, features, and risks. It does not replace reading code or
+repo documentation.
+
+## Authority order
+
+```txt
+1. Current user instruction
+2. Repository AGENTS.md (when working inside a repo)
+3. Repository docs/ai/ and docs/specs/
+4. Engram (persistent memory)
+5. Graphify (context graph)
+```
+
+If the graph contradicts code or repo docs, investigate the code first. Regenerate
+the graph with `graphify update .` — never edit graph artifacts by hand.
+
+## When to consult Graphify
+
+Before answering architecture or cross-module questions:
+
+1. Read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure.
+2. If `graphify-out/wiki/index.md` exists, navigate it instead of scanning raw files.
+3. For "how does X relate to Y", prefer `graphify query`, `graphify path`, or
+   `graphify explain` over broad grep when the graph is fresh.
+
+Before modifying code in an unfamiliar area:
+
+- Check module boundaries and dependency fan-in in the graph.
+- Note circular dependencies, god modules, and untested high-centrality nodes.
+
+## When to update the graph
+
+Run `graphify update .` after modifying code files in a session (AST-only, no API
+cost). Compare `GRAPH_REPORT.md` commit hash with `git rev-parse HEAD` to detect
+staleness.
+
+## CLI prerequisite
+
+Graphify is not bundled with Kairo Runtime. Install the `graphify` CLI separately
+when you want local graph generation. Kairo only ships the contract and health
+checks.
+
+## Graph signals to watch
+
+| Signal | Risk | Action |
+|---|---|---|
+| Circular dependencies | Hidden coupling | Report and propose cycle break |
+| High fan-in ("god module") | Risky change surface | Evaluate split or narrower API |
+| Orphan module | Dead code or stale docs | Confirm before deleting |
+| High centrality, no tests | Silent regression | Prioritize coverage before edits |
+| Spec without code | Pending or abandoned work | Verify with human |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/scripts/install.sh

@@ -184,7 +184,7 @@ require_cmd npm
 NODE_VERSION="$(node --version 2>/dev/null || true)"
 NPM_VERSION="$(npm --version 2>/dev/null || true)"
 GLOBAL_SPEC="$(resolve_global_spec)"
-GLOBAL_INSTALL_CMD="npm install -g ${GLOBAL_SPEC}"
+GLOBAL_INSTALL_CMD="npm install -g --force ${GLOBAL_SPEC}"
 SETUP_CMD="${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
 
 printf '%s\n' \
@@ -224,7 +224,7 @@ fi
 
 printf '%s\n' "Installing global CLI..." ""
 # shellcheck disable=SC2086
-npm install -g ${GLOBAL_SPEC}
+npm install -g --force ${GLOBAL_SPEC}
 
 KAIRO_BIN="$(resolve_kairo_bin || true)"
 if [ -z "$KAIRO_BIN" ]; then

package/scripts/lib/install-script-url.mjs

@@ -2,6 +2,31 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 const DEFAULT_REPO = "Kal-elSam/harness";
+const LEGACY_HARNESS_MINOR_CUTOFF = 29;
+
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-.+)?$/.exec(version);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3])
+  };
+}
+
+export function usesLegacyHarnessTag(version) {
+  const semver = parseSemver(version);
+
+  if (!semver) {
+    return false;
+  }
+
+  return semver.major === 0 && semver.minor >= LEGACY_HARNESS_MINOR_CUTOFF;
+}
 
 export function resolveInstallScriptRef({ version, tag = null }) {
   if (version === "latest") {
@@ -12,7 +37,11 @@ export function resolveInstallScriptRef({ version, tag = null }) {
     return tag;
   }
 
-  return `v${version}`;
+  if (usesLegacyHarnessTag(version)) {
+    return `v${version}`;
+  }
+
+  return `kairo-runtime-v${version}`;
 }
 
 export function resolveInstallScriptUrl({

package/src/global/component-builders.js

@@ -1,10 +1,14 @@
 import { join } from "node:path";
+import { buildEngramMemoryManagedSection } from "./components/engram-memory.js";
+import { buildGraphifyContextManagedSection } from "./components/graphify-context.js";
 import { buildOrchestratorManagedSection } from "./components/orchestrator.js";
 import { buildSddCoreManagedSection } from "./components/sdd-core.js";
 
 export const COMPONENT_BUILDERS = {
   orchestrator: buildOrchestratorManagedSection,
-  "sdd-core": buildSddCoreManagedSection
+  "sdd-core": buildSddCoreManagedSection,
+  "engram-memory": buildEngramMemoryManagedSection,
+  "graphify-context": buildGraphifyContextManagedSection
 };
 
 export function resolveComponentBuilder(componentId) {

package/src/global/component-ecosystem-checks.js

@@ -0,0 +1,147 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { formatCliCommand } from "./brand/cli.js";
+
+const GRAPH_REPORT_COMMIT_PATTERN = /Built from commit:\s*`([0-9a-f]+)`/i;
+
+export async function runComponentEcosystemChecks({ installedComponents, workspaceRoot = null } = {}) {
+  const installedIds = new Set(installedComponents.map((component) => component.id));
+  const checks = [];
+
+  if (installedIds.has("engram-memory")) {
+    checks.push(buildEngramMcpCheck());
+  }
+
+  if (installedIds.has("graphify-context")) {
+    checks.push(...await buildGraphifyChecks(workspaceRoot));
+  }
+
+  return checks;
+}
+
+function buildEngramMcpCheck() {
+  return {
+    name: "engram:mcp-tools",
+    status: "warning",
+    category: "integration",
+    componentId: "engram-memory",
+    detail: "Engram MCP is not bundled. Configure mem_* tools in your agent (user-engram or plugin-engram-engram) when ready."
+  };
+}
+
+async function buildGraphifyChecks(workspaceRoot) {
+  const checks = [];
+
+  if (!workspaceRoot) {
+    checks.push({
+      name: "graphify:workspace",
+      status: "warning",
+      category: "integration",
+      componentId: "graphify-context",
+      detail: "No workspace root; graph freshness checks skipped. Run doctor from a repo cwd."
+    });
+    return checks;
+  }
+
+  const resolvedRoot = resolve(workspaceRoot);
+  const graphifyAvailable = isCommandAvailable("graphify");
+
+  checks.push({
+    name: "graphify:cli",
+    status: graphifyAvailable ? "ok" : "warning",
+    category: "integration",
+    componentId: "graphify-context",
+    detail: graphifyAvailable
+      ? "graphify CLI found in PATH."
+      : "graphify CLI not found in PATH. Install separately when you want local graph generation."
+  });
+
+  const graphPath = join(resolvedRoot, "graphify-out", "graph.json");
+  const reportPath = join(resolvedRoot, "graphify-out", "GRAPH_REPORT.md");
+
+  if (!existsSync(graphPath)) {
+    checks.push({
+      name: "graphify:graph.json",
+      status: "warning",
+      category: "integration",
+      componentId: "graphify-context",
+      detail: existsSync(join(resolvedRoot, "graphify-out"))
+        ? "graphify-out/graph.json is absent. Run `graphify update .` when the workspace is ready."
+        : "graphify-out/ not found. Run `graphify update .` when the workspace is ready."
+    });
+    return checks;
+  }
+
+  const freshness = await readGraphFreshness(resolvedRoot, reportPath);
+  checks.push({
+    name: "graphify:graph.json",
+    status: freshness.status,
+    category: "integration",
+    componentId: "graphify-context",
+    detail: freshness.detail
+  });
+
+  return checks;
+}
+
+async function readGraphFreshness(workspaceRoot, reportPath) {
+  if (!existsSync(reportPath)) {
+    return {
+      status: "warning",
+      detail: "graphify-out/graph.json exists but GRAPH_REPORT.md is missing. Run `graphify update .` to refresh metadata."
+    };
+  }
+
+  const report = await readFile(reportPath, "utf8");
+  const match = report.match(GRAPH_REPORT_COMMIT_PATTERN);
+
+  if (!match) {
+    return {
+      status: "ok",
+      detail: "graphify-out/graph.json present. Commit metadata unavailable in GRAPH_REPORT.md."
+    };
+  }
+
+  const graphCommit = match[1];
+  const headCommit = resolveGitHead(workspaceRoot);
+
+  if (!headCommit) {
+    return {
+      status: "warning",
+      detail: `graphify-out/graph.json present (built from ${graphCommit}). Git HEAD unavailable for staleness check.`
+    };
+  }
+
+  const isFresh = headCommit.startsWith(graphCommit) || graphCommit.startsWith(headCommit);
+
+  if (isFresh) {
+    return {
+      status: "ok",
+      detail: `graphify-out/graph.json in sync with HEAD (${headCommit.slice(0, 8)}).`
+    };
+  }
+
+  return {
+    status: "warning",
+    detail: `graphify-out/graph.json may be stale (graph ${graphCommit}, HEAD ${headCommit.slice(0, 8)}). Run \`graphify update .\` or ${formatCliCommand("sync")} for managed assets only.`
+  };
+}
+
+function resolveGitHead(workspaceRoot) {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], {
+    cwd: workspaceRoot,
+    encoding: "utf8"
+  });
+
+  if (result.status !== 0) return null;
+
+  const head = result.stdout.trim();
+  return head.length > 0 ? head : null;
+}
+
+function isCommandAvailable(command) {
+  const result = spawnSync("which", [command], { encoding: "utf8" });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}

package/src/global/components/engram-memory.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+
+export function buildEngramMemoryManagedSection(context, adapter, catalogEntry) {
+  const contractPath = join(context.componentsDir, "engram-memory", "memory.md");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### Engram Memory",
+    "",
+    `- Contract: ${contractPath}`,
+    "- Optional persistent memory; repo AGENTS.md and docs/ai/ govern when present.",
+    "- Search memory before non-trivial tasks; save decisions, bugs, and conventions proactively.",
+    "- Authority: user > AGENTS.md > repo docs > Engram > Graphify.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}

package/src/global/components/graphify-context.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+
+export function buildGraphifyContextManagedSection(context, adapter, catalogEntry) {
+  const contractPath = join(context.componentsDir, "graphify-context", "context-graph.md");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### Graphify Context",
+    "",
+    `- Contract: ${contractPath}`,
+    "- Optional architecture graph; read GRAPH_REPORT.md before cross-module questions.",
+    "- Run `graphify update .` after code changes when the CLI is available.",
+    "- Authority: user > AGENTS.md > repo docs > Engram > Graphify.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}

package/src/global/global-doctor.js

@@ -1,5 +1,6 @@
 import { listBackupSnapshots } from "./backups.js";
 import { buildAdapterContext } from "./adapter-context.js";
+import { runComponentEcosystemChecks } from "./component-ecosystem-checks.js";
 import { detectGlobalDrift, hasRepairableDrift } from "./drift.js";
 import { harnessHomePaths } from "./paths.js";
 import { resolveComponent } from "./component-registry.js";
@@ -23,6 +24,10 @@ export async function runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoo
 
   if (packageRoot) {
     checks.push(await backupsCheck(paths));
+    checks.push(...await runComponentEcosystemChecks({
+      installedComponents,
+      workspaceRoot
+    }));
   }
 
   const hasMissing = checks.some((check) => check.status === "missing");