klypix-mcp 1.54.0 → 1.55.0

package/README.md

@@ -208,12 +208,26 @@ project_map_context {
 Use `compare_to` with another project-relative graph artifact to add exact total node/edge deltas
 and additions/removals from the two bounded query neighborhoods. Both paths are confined to the
 declared project root; unsafe source paths are withheld; large or unsupported artifacts are
-rejected. The tool never writes graph facts into `brain.klypix`.
+rejected. When a returned brain card names an exact mapped source path, the structured response
+also includes a review-only evidence-link proposal. It never promotes similarity into truth and
+never writes graph facts or links into `brain.klypix`.
 
 Graphify is the first compatible producer. KLYPIX reads artifacts that users generate separately;
 it does not bundle, install, or run Graphify and does not imply a partnership. A compatible generic
 `graph.json` works through the same provider-neutral boundary.
 
+For a reproducible map artifact on every pull request and main-branch push, install the shipped
+read-only workflow into a Git checkout:
+
+```bash
+npx klypix-project-map setup-github /path/to/project
+```
+
+The command refuses to overwrite an existing workflow unless `--force` is explicit. The installed
+workflow has `contents: read`, pins every action by commit SHA, pins `graphifyy==0.9.33`, validates
+the graph contract, and uploads `graphify-out/` as a 14-day build artifact. This is opt-in CI code:
+the local MCP tool still never installs or launches Graphify.
+
 ---
 
 ## Supported hosts and their integration level
@@ -419,7 +433,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
 | `brain_connect` | Find and draw related-but-unlinked cards |
-| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context; Graphify artifacts are supported but never installed or run |
+| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; Graphify artifacts are supported but never installed or run locally |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name and content |

package/bin/klypix-project-map.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { discoverProjectGraph } from '../src/project-graph.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const template = path.resolve(here, '..', 'examples', 'github', 'klypix-project-map.yml');
+const args = process.argv.slice(2);
+const command = args[0] || 'status';
+const force = args.includes('--force');
+const rootArg = args.find((value, index) => index > 0 && value !== '--force') || process.cwd();
+
+function projectRoot(value) {
+  const root = fs.realpathSync(path.resolve(value));
+  if (!fs.statSync(root).isDirectory()) throw new Error('Project root is not a directory.');
+  return root;
+}
+
+function usage() {
+  console.log([
+    'KLYPIX Project Map',
+    '',
+    '  klypix-project-map status [project]',
+    '  klypix-project-map setup-github [project] [--force]',
+    '',
+    'setup-github installs a read-only, pinned GitHub Actions workflow. It never installs or runs a provider on your computer.',
+  ].join('\n'));
+}
+
+try {
+  if (command === '--help' || command === '-h' || command === 'help') {
+    usage();
+    process.exit(0);
+  }
+  const root = projectRoot(rootArg);
+  if (command === 'status') {
+    const graph = discoverProjectGraph({ project: root });
+    const workflow = path.join(root, '.github', 'workflows', 'klypix-project-map.yml');
+    console.log(`Project: ${root}`);
+    console.log(`Graph artifact: ${graph.status === 'ready' ? `ready (${graph.artifact.graphJson})` : `missing (${graph.artifact.graphJson})`}`);
+    console.log(`GitHub workflow: ${fs.existsSync(workflow) ? 'installed' : 'not installed'}`);
+    process.exit(0);
+  }
+  if (command !== 'setup-github') {
+    usage();
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(root, '.git'))) throw new Error('Run setup-github inside a Git checkout.');
+  const destination = path.join(root, '.github', 'workflows', 'klypix-project-map.yml');
+  const source = fs.readFileSync(template, 'utf8');
+  if (fs.existsSync(destination)) {
+    const current = fs.readFileSync(destination, 'utf8');
+    if (current === source) {
+      console.log(`Project Map workflow is already current: ${destination}`);
+      process.exit(0);
+    }
+    if (!force) throw new Error(`Workflow already exists with different contents: ${destination}\nReview it, then rerun with --force if replacement is intended.`);
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, source, { encoding: 'utf8', flag: 'w' });
+  console.log(`Installed Project Map workflow: ${destination}`);
+  console.log('Commit the workflow when you are ready. Pull requests and main-branch pushes will produce a read-only Project Map artifact.');
+} catch (error) {
+  console.error(`Project Map: ${error?.message || error}`);
+  process.exit(1);
+}

package/bin/klypix-worker.mjs

@@ -30,7 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
-import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph } from '../src/project-graph.mjs';
+import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import {
@@ -309,10 +309,14 @@ server.registerTool('project_map_context', {
     .filter(block => block.kind === 'text')
     .map(block => block.text)
     .join('\n\n');
+  const evidenceLinkProposals = suggestProjectGraphBrainLinks(graphResult, brainResult.context);
+  const proposalMarkdown = evidenceLinkProposals.length
+    ? `\n\n## Exact-path evidence link proposals\n\n${evidenceLinkProposals.slice(0, 12).map(proposal => `- Review brain card \`${proposal.brainCardId}\` beside **${proposal.nodeLabel}** in \`${proposal.sourceFile}\`.`).join('\n')}\n\n_These are review proposals based only on an exact source-path mention. Nothing was written to the brain._`
+    : '';
   return toContent({
-    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}` }],
+    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}${proposalMarkdown}` }],
     isError: brainResult.isError,
-    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, deepHistory: deep_history === true },
+    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, evidenceLinkProposals, deepHistory: deep_history === true },
   });
 });
 

package/examples/github/klypix-project-map.yml

@@ -0,0 +1,45 @@
+name: KLYPIX Project Map
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: klypix-project-map-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GRAPHIFY_VERSION: "0.9.33"
+
+jobs:
+  project-map:
+    name: Generate bounded map artifact
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Generate code-only graph
+        run: uvx --from "graphifyy==${GRAPHIFY_VERSION}" graphify extract . --code-only
+
+      - name: Validate the generated contract
+        run: node -e "const fs=require('fs'); const p='graphify-out/graph.json'; const g=JSON.parse(fs.readFileSync(p,'utf8')); if(!Array.isArray(g.nodes)||!(Array.isArray(g.edges)||Array.isArray(g.links))) throw Error('unsupported graph contract'); console.log('Project Map:',g.nodes.length,'nodes');"
+
+      - name: Upload Project Map artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: klypix-project-map-${{ github.sha }}
+          path: graphify-out/
+          if-no-files-found: error
+          retention-days: 14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,8 @@
     "klypix-write": "bin/klypix-write.mjs",
     "klypix-append": "bin/klypix-append.mjs",
     "klypix-install": "bin/klypix-install.mjs",
-    "klypix-uninstall": "bin/klypix-uninstall.mjs"
+    "klypix-uninstall": "bin/klypix-uninstall.mjs",
+    "klypix-project-map": "bin/klypix-project-map.mjs"
   },
   "main": "index.mjs",
   "exports": {
@@ -75,7 +76,7 @@
   },
   "scripts": {
     "test:project-graph": "node test/project-graph.mjs",
-    "test": "node test/project-graph.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/project-graph.mjs

@@ -343,6 +343,47 @@ export function compareProjectGraphResults(current, previous) {
   };
 }
 
+function textContainsExactSourcePath(text, sourceFile) {
+  const haystack = String(text || '').replace(/\\/g, '/').toLocaleLowerCase('en-US');
+  const needle = String(sourceFile || '').replace(/\\/g, '/').toLocaleLowerCase('en-US');
+  if (!needle || !haystack.includes(needle)) return false;
+  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|[\\s\`'"([{<])${escaped}($|[\\s\`'"\\])}>.,;:#])`, 'i').test(haystack);
+}
+
+/**
+ * Deterministic proposals only. These are never persisted and never imply
+ * causality: an exact project-relative source path must appear in the brain
+ * card text before KLYPIX will suggest reviewing the pair.
+ */
+export function suggestProjectGraphBrainLinks(graphResult, brainContext, limit = 40) {
+  if (graphResult?.status !== 'ready' || !Array.isArray(graphResult.nodes)) return [];
+  const hits = Array.isArray(brainContext?.hits) ? brainContext.hits : [];
+  const proposals = [];
+  const seen = new Set();
+  for (const node of graphResult.nodes) {
+    if (!node?.sourceFile) continue;
+    for (const hit of hits) {
+      const texts = [hit?.text, hit?.correctedBy].filter(Boolean);
+      if (!texts.some(text => textContainsExactSourcePath(text, node.sourceFile))) continue;
+      const key = `${hit.id}\u0000${node.id}\u0000${node.sourceFile}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      proposals.push({
+        brainCardId: hit.id,
+        brainArea: hit.area || 'Notes',
+        nodeId: node.id,
+        nodeLabel: node.label || node.id,
+        sourceFile: node.sourceFile,
+        basis: 'exact-source-path',
+        status: 'review-proposal',
+      });
+      if (proposals.length >= Math.max(1, Math.min(100, Number(limit) || 40))) return proposals;
+    }
+  }
+  return proposals;
+}
+
 export function projectGraphContextMarkdown(result) {
   if (result.status === 'missing') {
     return `# Project Map\n\nNo supported project graph was found at \`${result.artifact.graphJson}\`. KLYPIX did not install or run a provider. Generate the artifact with Graphify, then retry.`;