opencode-traceability 0.2.0

package/.opencode/commands/traceability-sync.md

@@ -0,0 +1,20 @@
+---
+description: Export Engram and enrich the shared vault with current CodeGraph callers.
+---
+
+Run the team traceability sync for the current workspace.
+
+Requirements:
+
+- `TRACEABILITY_VAULT`
+- `TRACEABILITY_PROJECT`
+- `TRACEABILITY_REPO_ROOT`
+- `ENGRAM_BIN` or `engram` on PATH
+
+Run:
+
+```powershell
+traceability sync --vault "$env:TRACEABILITY_VAULT" --project "$env:TRACEABILITY_PROJECT" --repo "$env:TRACEABILITY_REPO_ROOT"
+```
+
+Report the export, enrichment, reindex, and validation results. Do not modify application code.

package/.opencode/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.31"
+  }
+}

package/.opencode/plugins/traceability.ts

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+const execFileAsync = promisify(execFile)
+type CommandResult = { stdout: string; stderr: string }
+
+async function run(command: string, args: string[], env: NodeJS.ProcessEnv): Promise<CommandResult> {
+  return execFileAsync(command, args, {
+    env: { ...process.env, ...env },
+    windowsHide: true,
+    maxBuffer: 256 * 1024,
+  }) as Promise<CommandResult>
+}
+
+function required(name: string): string {
+  const value = process.env[name]
+  if (!value) throw new Error(`Missing required environment variable: ${name}`)
+  return value
+}
+
+async function optional(label: string, action: () => Promise<CommandResult>): Promise<string> {
+  try {
+    const result = await action()
+    return `### ${label}\n${result.stdout.trim() || result.stderr.trim() || "(sin resultados)"}`
+  } catch (error) {
+    return `### ${label}\nUnavailable: ${String(error)}`
+  }
+}
+
+const TraceabilityPlugin: Plugin = async ({ $, client }) => {
+  const autoSync = process.env.TRACEABILITY_AUTO_SYNC === "true"
+  const kitRoot = process.env.TRACEABILITY_KIT_ROOT
+  let syncInFlight: Promise<unknown> | undefined
+
+  const sync = async () => {
+    if (!autoSync || !kitRoot || syncInFlight) return
+    syncInFlight = (async () => {
+      try {
+        if (process.platform === "win32") {
+          await $`powershell -NoProfile -ExecutionPolicy Bypass -File ${kitRoot}/scripts/traceability-sync.ps1 -Enrich`
+        } else {
+          await $`${kitRoot}/scripts/traceability-sync.sh`
+        }
+        await client.app.log({ body: { service: "traceability", level: "info", message: "Automatic traceability sync completed" } })
+      } catch (error) {
+        await client.app.log({ body: { service: "traceability", level: "warn", message: `Automatic sync failed: ${String(error)}` } })
+      } finally {
+        syncInFlight = undefined
+      }
+    })()
+    await syncInFlight
+  }
+
+  const contextTool = tool({
+    description: "Return bounded historical, vault, and CodeGraph context before changing a functionality.",
+    args: {
+      query: tool.schema.string().min(1).max(200).describe("Natural-language question or behavior to investigate"),
+      symbol: tool.schema.string().max(160).optional().describe("Optional exact CodeGraph symbol"),
+      limit: tool.schema.number().int().min(1).max(8).optional().describe("Maximum results per source"),
+    },
+    async execute(args) {
+      const vault = required("TRACEABILITY_VAULT")
+      const project = required("TRACEABILITY_PROJECT")
+      const repo = required("TRACEABILITY_REPO_ROOT")
+      const node = process.env.TRACEABILITY_NODE || "node"
+      const cli = process.env.OBSIDIAN_INTELLIGENCE_CLI || "vault-intelligence.js"
+      const engram = process.env.ENGRAM_BIN || "engram"
+      const codegraph = process.env.TRACEABILITY_CODEGRAPH_BIN || "codegraph"
+      const limit = String(args.limit || 5)
+
+      const parts = await Promise.all([
+        optional("Obsidian", () => run(node, [cli, "search", args.query, "--hybrid", "--limit", limit], { VAULT_PATH: vault })),
+        optional("Engram", () => run(engram, ["search", args.query, "--project", project, "--limit", limit], {})),
+        args.symbol
+          ? optional("CodeGraph callers", () => run(codegraph, ["callers", args.symbol!, "--path", repo, "--limit", limit, "--json"], {}))
+          : Promise.resolve("### CodeGraph callers\nNo symbol supplied; caller lookup skipped."),
+      ])
+
+      return [
+        "# Traceability context",
+        `Query: ${args.query}`,
+        args.symbol ? `Symbol: ${args.symbol}` : "",
+        ...parts,
+        "Use this as evidence. Confirm current source with CodeGraph before editing.",
+      ].filter(Boolean).join("\n\n")
+    },
+  })
+
+  return {
+    tool: { traceability_context: contextTool },
+    event: async ({ event }: { event: { type?: string } }) => {
+      if (event.type === "session.idle") await sync()
+    },
+    "tool.execute.after": async (input: { tool?: string }) => {
+      if (input.tool && /sdd[-_]archive/i.test(input.tool)) await sync()
+    },
+  }
+}
+
+export { TraceabilityPlugin }
+export default TraceabilityPlugin

package/.opencode/skills/code-traceability/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: code-traceability
+description: Use before changing code or completing an SDD phase to connect current CodeGraph impact, Engram history, and the shared Markdown knowledge graph.
+---
+
+# Team Code Traceability
+
+## Before changing code
+
+1. Resolve the repository root and project identity.
+2. Search the shared vault with `hybrid_search` or `search_content` for the requested behavior.
+3. Search Engram for the project and affected symbol/file.
+4. Query CodeGraph for callers, callees, and affected files.
+5. Compare historical decisions with the current tree. Report conflicts instead of guessing.
+
+Use bounded context: include the relevant notes and up to the configured caller limit. Do not dump the complete vault into a prompt.
+
+## During SDD
+
+Persist phase artifacts under `sdd/<change>/<phase>` and preserve the user prompt/decision that produced them. Use Engram as operational memory; do not treat generated Markdown as the only source of truth.
+
+## After archive or a significant change
+
+1. Run the portable sync script with `TRACEABILITY_VAULT` and `TRACEABILITY_PROJECT`.
+2. Run the CodeGraph enrichment script with `TRACEABILITY_REPO_ROOT`.
+3. Update the corresponding Markdown node with:
+   - `Archivos que usan esta funcionalidad` from CodeGraph;
+   - `Historial de cambios sobre este nodo` from Engram;
+   - source IDs, dates, and links to the project MOC.
+4. Reindex Obsidian Intelligence and validate broken links.
+5. Keep the diff reviewable. Never rewrite unrelated notes.
+
+## Safety
+
+- Never modify application code automatically from this skill.
+- Never use absolute paths belonging to another developer.
+- Never commit credentials, SQLite databases, or CodeGraph indexes.
+- Treat ambiguous or conflicting history as a human decision, not as permission to infer.
+- Keep source files and Markdown projections separate and auditable.

package/README.md

@@ -0,0 +1,135 @@
+# OpenCode Traceability
+
+Portable npm package that lets each developer investigate **their own** Engram memories and current repository with CodeGraph, then generate a local Obsidian-compatible knowledge graph.
+
+The package contains no project memories, no vault notes, no SQLite database, and no credentials.
+
+## Install
+
+From npm:
+
+```powershell
+npm install --global opencode-traceability
+```
+
+For a local package build:
+
+```powershell
+npm install --global .\traceability-kit
+```
+
+Requirements:
+
+- Node.js >= 18; npm installs `obsidian-intelligence` automatically.
+- Engram CLI available as `engram` or through `ENGRAM_BIN`.
+- CodeGraph initialized in the selected repository.
+- OpenCode is optional for CLI-only use and required for the plugin.
+
+## Create a project graph
+
+The user chooses the project and vault. Nothing is imported until `sync` is executed.
+
+```powershell
+traceability init `
+  --vault "C:\workspace\traceability-vault" `
+  --project "ta_schedule_backend"
+
+traceability sync `
+  --vault "C:\workspace\traceability-vault" `
+  --project "ta_schedule_backend" `
+  --repo "C:\workspace\ta_schedule_backend"
+```
+
+`sync` performs:
+
+1. `engram obsidian-export` for the selected Engram project.
+2. CodeGraph caller enrichment for notes containing `codegraph_symbols`.
+3. Obsidian Intelligence reindexing using the bundled npm dependency, or `OBSIDIAN_INTELLIGENCE_CLI` when overridden.
+
+The generated graph belongs to the selected user/workspace. A different developer can select a different project and vault.
+
+## Available commands
+
+```text
+traceability init   --vault <path> [--project <name>]
+traceability sync   --vault <path> --project <name> --repo <path> [--since <date>] [--force]
+traceability watch  --vault <path> --project <name> --repo <path> [--interval <minutes>]
+traceability status --vault <path>
+traceability graph  --vault <path> [--limit <n>]
+traceability context --query <text> [--symbol <name>] [--project <name>] [--repo <path>] [--vault <path>]
+traceability opencode-install --repo <path>
+```
+
+Example investigation:
+
+```powershell
+traceability context `
+  --query "qué archivos usan el resolver de batches GTFS y qué cambios tuvo" `
+  --symbol "GtfsBatchResolver" `
+  --project "ta_schedule_backend" `
+  --repo "C:\workspace\ta_schedule_backend" `
+  --vault "C:\workspace\traceability-vault"
+```
+
+## Continuous mode
+
+```powershell
+traceability watch `
+  --vault "C:\workspace\traceability-vault" `
+  --project "ta_schedule_backend" `
+  --repo "C:\workspace\ta_schedule_backend" `
+  --interval 10
+```
+
+The watcher exports, enriches, and reindexes periodically. Stop with `Ctrl+C`.
+
+## OpenCode integration
+
+Install the npm plugin in the project's OpenCode configuration:
+
+```powershell
+traceability opencode-install --repo "C:\workspace\ta_schedule_backend"
+```
+
+Restart OpenCode. The plugin provides `traceability_context` and triggers a bounded sync after an idle session or an `sdd-archive` tool event when:
+
+```powershell
+$env:TRACEABILITY_AUTO_SYNC = "true"
+```
+
+The plugin uses these environment variables:
+
+```powershell
+$env:TRACEABILITY_VAULT = "C:\workspace\traceability-vault"
+$env:TRACEABILITY_PROJECT = "ta_schedule_backend"
+$env:TRACEABILITY_REPO_ROOT = "C:\workspace\ta_schedule_backend"
+$env:OBSIDIAN_INTELLIGENCE_CLI = "C:\workspace\node_modules\opencode-traceability\node_modules\obsidian-intelligence\vault-intelligence.js"
+```
+
+## Team-sharing policy
+
+Share the npm package or publish it to the team's private registry. Do not package or publish:
+
+- Markdown notes from another developer's project;
+- `.vault-intelligence.db` or other SQLite files;
+- `.codegraph` indexes;
+- `node_modules`;
+- `.env`, tokens, credentials, or absolute machine paths.
+
+The package is code only. Each developer creates or selects their own vault and Engram project at runtime.
+
+## Source layout
+
+```text
+bin/traceability.js       # npm CLI
+plugin.ts                 # OpenCode plugin entrypoint
+scripts/                  # sync, validation, and CodeGraph enrichment
+config/                   # portable configuration examples
+```
+
+## Safety
+
+- The CLI never deletes notes or application code.
+- Queries are bounded to eight results by default.
+- The package treats Engram as operational memory and Markdown as the generated projection.
+- Ambiguous project names must be resolved explicitly with `--project`.

package/bin/traceability.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs")
+const os = require("node:os")
+const path = require("node:path")
+const { spawnSync } = require("node:child_process")
+
+const packageRoot = path.resolve(__dirname, "..")
+
+function parseArgs(argv) {
+  const result = { _: [] }
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+    if (!token.startsWith("--")) {
+      result._.push(token)
+      continue
+    }
+    const [key, inlineValue] = token.slice(2).split("=", 2)
+    if (inlineValue !== undefined) {
+      result[key] = inlineValue
+      continue
+    }
+    const next = argv[index + 1]
+    if (!next || next.startsWith("--")) {
+      result[key] = true
+      continue
+    }
+    result[key] = next
+    index += 1
+  }
+  return result
+}
+
+function usage() {
+  console.log(`Usage:
+  traceability init   --vault <path> [--project <name>]
+  traceability sync   --vault <path> --project <name> --repo <path> [--since <date>] [--force]
+  traceability watch  --vault <path> --project <name> --repo <path> [--interval <minutes>]
+  traceability status --vault <path>
+  traceability graph  --vault <path> [--limit <n>]
+  traceability context --query <text> [--symbol <name>] [--project <name>] [--repo <path>] [--vault <path>]
+  traceability opencode-install --repo <path>
+
+Environment defaults:
+  TRACEABILITY_VAULT, TRACEABILITY_PROJECT, TRACEABILITY_REPO_ROOT,
+  TRACEABILITY_NODE, ENGRAM_BIN, TRACEABILITY_CODEGRAPH_BIN,
+  OBSIDIAN_INTELLIGENCE_CLI, TRACEABILITY_AUTO_SYNC`)
+}
+
+function value(args, name, environmentName, required = false) {
+  const resolved = args[name] || process.env[environmentName]
+  if (required && !resolved) throw new Error(`Missing --${name} or ${environmentName}`)
+  return resolved
+}
+
+function executable(name, environmentName) {
+  return process.env[environmentName] || name
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...(options.env || {}) },
+    encoding: "utf8",
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    shell: process.platform === "win32",
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with code ${result.status}`)
+  }
+  return options.capture ? { stdout: result.stdout || "", stderr: result.stderr || "" } : undefined
+}
+
+function ensureDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true })
+}
+
+function writeIfMissing(file, content) {
+  if (!fs.existsSync(file)) fs.writeFileSync(file, content, "utf8")
+}
+
+function copyFilesIfMissing(sourceDirectory, destinationDirectory) {
+  ensureDirectory(destinationDirectory)
+  let copied = false
+  for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+    const source = path.join(sourceDirectory, entry.name)
+    const destination = path.join(destinationDirectory, entry.name)
+    if (entry.isDirectory()) {
+      copied = copyFilesIfMissing(source, destination) || copied
+    } else if (!fs.existsSync(destination)) {
+      fs.copyFileSync(source, destination)
+      copied = true
+    }
+  }
+  return copied
+}
+
+function init(args) {
+  const vault = value(args, "vault", "TRACEABILITY_VAULT", true)
+  const project = value(args, "project", "TRACEABILITY_PROJECT") || "knowledge-base"
+  ensureDirectory(vault)
+  writeIfMissing(path.join(vault, ".gitignore"), ".vault-intelligence.db\n*.db\n")
+  writeIfMissing(path.join(vault, "Inicio.md"), `---\ntype: moc\ntags: [inicio, moc]\n---\n\n# Bóveda de conocimiento\n\n- [[MOC - ${project}]]\n`)
+  writeIfMissing(path.join(vault, `MOC - ${project}.md`), `---\ntype: moc\ntags: [moc, ${project}]\n---\n\n# MOC — ${project}\n\n- [[Inicio]]\n\n## Cambios SDD\n\nLas notas se generan con el comando traceability sync.\n`)
+  console.log(`Vault initialized: ${vault}`)
+}
+
+function exportMemories({ vault, project, since, force, watch = false, interval }) {
+  const args = ["obsidian-export", "--vault", vault, "--project", project]
+  if (since) args.push("--since", since)
+  if (force) args.push("--force")
+  if (watch) args.push("--watch", "--interval", `${interval}m`)
+  run(executable("engram", "ENGRAM_BIN"), args)
+}
+
+function enrich({ vault, repo, maxCallers }) {
+  const script = path.join(packageRoot, "scripts", "enrich-codegraph.ps1")
+  const environment = {
+    TRACEABILITY_VAULT: vault,
+    TRACEABILITY_REPO_ROOT: repo,
+    TRACEABILITY_CODEGRAPH_BIN: process.env.TRACEABILITY_CODEGRAPH_BIN || "codegraph",
+  }
+  if (process.platform === "win32") {
+    run("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-MaxCallers", String(maxCallers || 8)], { env: environment })
+  } else {
+    console.warn("CodeGraph PowerShell enrichment is not available on POSIX yet; export completed.")
+  }
+}
+
+function reindex(vault) {
+  const cli = process.env.OBSIDIAN_INTELLIGENCE_CLI || path.join(packageRoot, "node_modules", "obsidian-intelligence", "vault-intelligence.js")
+  if (!cli) {
+    console.warn("Reindex skipped. Set OBSIDIAN_INTELLIGENCE_CLI to vault-intelligence.js.")
+    return
+  }
+  const node = executable("node", "TRACEABILITY_NODE")
+  run(node, [cli, "index", "--vault", vault])
+  run(node, [cli, "status", "--vault", vault])
+}
+
+function sync(args) {
+  const vault = value(args, "vault", "TRACEABILITY_VAULT", true)
+  const project = value(args, "project", "TRACEABILITY_PROJECT", true)
+  const repo = value(args, "repo", "TRACEABILITY_REPO_ROOT", true)
+  exportMemories({ vault, project, since: args.since, force: Boolean(args.force) })
+  enrich({ vault, repo, maxCallers: args.limit || 8 })
+  reindex(vault)
+}
+
+function watch(args) {
+  const interval = Number(args.interval || 10)
+  if (!Number.isFinite(interval) || interval < 1) throw new Error("--interval must be at least 1 minute")
+  const syncArgs = { ...args }
+  delete syncArgs._
+  sync(syncArgs)
+  console.log(`Watching ${value(args, "project", "TRACEABILITY_PROJECT", true)} every ${interval} minutes. Press Ctrl+C to stop.`)
+  setInterval(() => {
+    try { sync(syncArgs) } catch (error) { console.error(`[traceability] sync failed: ${error.message}`) }
+  }, interval * 60 * 1000)
+}
+
+function status(args) {
+  const vault = value(args, "vault", "TRACEABILITY_VAULT", true)
+  reindex(vault)
+}
+
+function graph(args) {
+  const vault = value(args, "vault", "TRACEABILITY_VAULT", true)
+  const cli = process.env.OBSIDIAN_INTELLIGENCE_CLI
+  if (!fs.existsSync(cli)) throw new Error("Obsidian Intelligence is not installed. Run npm install -g opencode-traceability or set OBSIDIAN_INTELLIGENCE_CLI.")
+  run(executable("node", "TRACEABILITY_NODE"), [cli, "graph", "hubs", String(args.limit || 10)], { env: { VAULT_PATH: vault } })
+}
+
+function context(args) {
+  const query = value(args, "query", "TRACEABILITY_QUERY", true)
+  const vault = value(args, "vault", "TRACEABILITY_VAULT", true)
+  const project = value(args, "project", "TRACEABILITY_PROJECT", true)
+  const repo = value(args, "repo", "TRACEABILITY_REPO_ROOT")
+  const limit = String(args.limit || 5)
+  const cli = process.env.OBSIDIAN_INTELLIGENCE_CLI || path.join(packageRoot, "node_modules", "obsidian-intelligence", "vault-intelligence.js")
+  if (fs.existsSync(cli)) {
+    console.log("## Obsidian")
+    const result = run(executable("node", "TRACEABILITY_NODE"), [cli, "search", query, "--hybrid", "--limit", limit], { capture: true, env: { VAULT_PATH: vault } })
+    console.log(result.stdout.trim())
+  } else console.warn("Obsidian Intelligence unavailable; Engram and CodeGraph results will still be returned.")
+  console.log("## Engram")
+  const engram = run(executable("engram", "ENGRAM_BIN"), ["search", query, "--project", project, "--limit", limit], { capture: true })
+  console.log(engram.stdout.trim())
+  if (args.symbol && repo) {
+    console.log("## CodeGraph callers")
+    const callers = run(executable("codegraph", "TRACEABILITY_CODEGRAPH_BIN"), ["callers", args.symbol, "--path", repo, "--limit", limit, "--json"], { capture: true })
+    console.log(callers.stdout.trim())
+  }
+}
+
+function installOpenCode(args) {
+  const repo = value(args, "repo", "TRACEABILITY_REPO_ROOT", true)
+  const configPath = path.join(repo, "opencode.json")
+  const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : { $schema: "https://opencode.ai/config.json" }
+  const plugins = Array.isArray(config.plugin) ? config.plugin : []
+  if (!plugins.includes("opencode-traceability")) plugins.push("opencode-traceability")
+  config.plugin = plugins
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8")
+  const opencodeRoot = path.join(repo, ".opencode")
+  const skillSource = path.join(packageRoot, ".opencode", "skills")
+  const commandSource = path.join(packageRoot, ".opencode", "commands")
+  const skillInstalled = copyFilesIfMissing(skillSource, path.join(opencodeRoot, "skills"))
+  const commandInstalled = copyFilesIfMissing(commandSource, path.join(opencodeRoot, "commands"))
+  console.log(`Added opencode-traceability to ${configPath}. Skill copied: ${skillInstalled}. Command copied: ${commandInstalled}. Restart OpenCode.`)
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const command = args._[0]
+  if (!command || command === "help" || command === "--help") return usage()
+  if (command === "init") return init(args)
+  if (command === "sync") return sync(args)
+  if (command === "watch") return watch(args)
+  if (command === "status") return status(args)
+  if (command === "graph") return graph(args)
+  if (command === "context") return context(args)
+  if (command === "opencode-install") return installOpenCode(args)
+  throw new Error(`Unknown command: ${command}`)
+}
+
+try { main() } catch (error) { console.error(`[traceability] ${error.message}`); process.exitCode = 1 }

package/config/traceability.example.json

@@ -0,0 +1,8 @@
+{
+  "vault": "${TRACEABILITY_VAULT}",
+  "project": "${TRACEABILITY_PROJECT}",
+  "repoRoot": "${TRACEABILITY_REPO_ROOT}",
+  "maxCallers": 8,
+  "reindex": true,
+  "dryRun": false
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "opencode-traceability",
+  "private": false,
+  "version": "0.2.0",
+  "description": "Project-selectable CodeGraph, Engram, Obsidian, and OpenCode traceability toolkit",
+  "main": "plugin.ts",
+  "bin": {
+    "traceability": "bin/traceability.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "plugin.ts",
+    "scripts",
+    "README.md",
+    "config",
+    ".opencode"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.31",
+    "obsidian-intelligence": "1.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugin.ts

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+const execFileAsync = promisify(execFile)
+
+const TraceabilityPlugin: Plugin = async ({ $, client }) => {
+  const syncEnabled = process.env.TRACEABILITY_AUTO_SYNC === "true"
+  const cli = process.env.TRACEABILITY_CLI || "traceability"
+  let running = false
+
+  const sync = async () => {
+    if (!syncEnabled || running) return
+    running = true
+    try {
+      await $`${cli} sync`
+      await client.app.log({ body: { service: "traceability", level: "info", message: "Traceability sync completed" } })
+    } catch (error) {
+      await client.app.log({ body: { service: "traceability", level: "warn", message: `Traceability sync failed: ${String(error)}` } })
+    } finally {
+      running = false
+    }
+  }
+
+  return {
+    tool: {
+      traceability_context: tool({
+        description: "Investigate bounded project context across Engram, Obsidian, and CodeGraph.",
+        args: {
+          query: tool.schema.string().min(1).max(200),
+          symbol: tool.schema.string().max(160).optional(),
+          limit: tool.schema.number().int().min(1).max(8).optional(),
+        },
+        async execute(args) {
+          const command = ["context", "--query", args.query]
+          if (args.symbol) command.push("--symbol", args.symbol)
+          if (args.limit) command.push("--limit", String(args.limit))
+          const result = await execFileAsync(cli, command, {
+            env: process.env,
+            shell: process.platform === "win32",
+            maxBuffer: 256 * 1024,
+          })
+          return result.stdout || result.stderr
+        },
+      }),
+    },
+    event: async ({ event }) => {
+      if (event.type === "session.idle") await sync()
+    },
+    "tool.execute.after": async (input) => {
+      if (input.tool && /sdd[-_]archive/i.test(input.tool)) await sync()
+    },
+  }
+}
+
+export default TraceabilityPlugin

package/scripts/enrich-codegraph.ps1

@@ -0,0 +1,98 @@
+[CmdletBinding()]
+param(
+  [ValidateRange(1, 100)]
+  [int]$MaxCallers = 8,
+  [switch]$Strict
+)
+
+$ErrorActionPreference = "Stop"
+
+function Require-Environment([string]$Name) {
+  $value = [Environment]::GetEnvironmentVariable($Name)
+  if ([string]::IsNullOrWhiteSpace($value)) { throw "Required environment variable is missing: $Name" }
+  return $value
+}
+
+$vault = Require-Environment "TRACEABILITY_VAULT"
+$repo = Require-Environment "TRACEABILITY_REPO_ROOT"
+if (-not (Test-Path -LiteralPath $vault -PathType Container)) { throw "Vault does not exist: $vault" }
+if (-not (Test-Path -LiteralPath $repo -PathType Container)) { throw "Repository does not exist: $repo" }
+
+$codegraph = $env:TRACEABILITY_CODEGRAPH_BIN
+if ([string]::IsNullOrWhiteSpace($codegraph)) {
+  $command = Get-Command codegraph -ErrorAction SilentlyContinue
+  if ($null -eq $command) { throw "CodeGraph CLI not found. Set TRACEABILITY_CODEGRAPH_BIN or add codegraph to PATH." }
+  $codegraph = $command.Source
+}
+
+function Get-Symbols([string]$Text) {
+  $match = [regex]::Match($Text, '(?m)^codegraph_symbols:\s*\[(.*?)\]\s*$')
+  if (-not $match.Success) { return @() }
+  return @($match.Groups[1].Value.Split(',') | ForEach-Object { $_.Trim().Trim('"', "'") } | Where-Object { $_ })
+}
+
+function Format-Consumers([hashtable]$Consumers, [string[]]$Symbols) {
+  $lines = [System.Collections.Generic.List[string]]::new()
+  if ($Consumers.Count -eq 0) {
+    $lines.Add('- Sin consumidores detectados en CodeGraph para los símbolos declarados.')
+    return $lines
+  }
+  foreach ($path in ($Consumers.Keys | Sort-Object)) {
+    $details = @($Consumers[$path] | Sort-Object -Unique) -join ', '
+    $lines.Add(('- `{0}` — caller de `{1}`' -f $path, $details))
+  }
+  return $lines
+}
+
+$updated = 0
+$failed = 0
+foreach ($file in Get-ChildItem -LiteralPath $vault -Filter *.md -File) {
+  $text = [System.IO.File]::ReadAllText($file.FullName, [System.Text.UTF8Encoding]::new($false))
+  $symbols = @(Get-Symbols $text)
+  if ($symbols.Count -eq 0) { continue }
+
+  $consumers = @{}
+  foreach ($symbol in $symbols) {
+    try {
+      $json = (& $codegraph callers $symbol --path $repo --limit $MaxCallers --json | Out-String) | ConvertFrom-Json
+      foreach ($caller in @($json.callers)) {
+        if (-not $caller.filePath) { continue }
+        if (-not $consumers.ContainsKey($caller.filePath)) { $consumers[$caller.filePath] = [System.Collections.Generic.List[string]]::new() }
+        $line = if ($caller.startLine) { ":$($caller.startLine)" } else { "" }
+        $consumers[$caller.filePath].Add("$symbol$line")
+      }
+    } catch {
+      $failed++
+      Write-Warning ("CodeGraph failed for {0} in {1}: {2}" -f $symbol, $file.Name, $_.Exception.Message)
+    }
+  }
+
+  $section = [System.Collections.Generic.List[string]]::new()
+  $section.Add("## Archivos que usan esta funcionalidad")
+  $section.Add("")
+  foreach ($line in (Format-Consumers $consumers $symbols)) { $section.Add($line) }
+  $section.Add("")
+  $newSection = $section -join [Environment]::NewLine
+
+  $heading = "## Archivos que usan esta funcionalidad"
+  $history = "## Historial de cambios sobre este nodo"
+  $sources = "## Fuentes"
+  $start = $text.IndexOf($heading, [System.StringComparison]::Ordinal)
+  if ($start -ge 0) {
+    $end = $text.IndexOf($history, $start, [System.StringComparison]::Ordinal)
+    if ($end -lt 0) { $end = $text.IndexOf($sources, $start, [System.StringComparison]::Ordinal) }
+    if ($end -lt 0) { $end = $text.Length }
+    $text = $text.Substring(0, $start) + $newSection + [Environment]::NewLine + [Environment]::NewLine + $text.Substring($end)
+  } else {
+    $insertAt = $text.IndexOf($history, [System.StringComparison]::Ordinal)
+    if ($insertAt -lt 0) { $insertAt = $text.IndexOf($sources, [System.StringComparison]::Ordinal) }
+    if ($insertAt -lt 0) { $insertAt = $text.Length }
+    $text = $text.Substring(0, $insertAt) + $newSection + [Environment]::NewLine + [Environment]::NewLine + $text.Substring($insertAt)
+  }
+
+  [System.IO.File]::WriteAllText($file.FullName, $text, [System.Text.UTF8Encoding]::new($false))
+  $updated++
+}
+
+Write-Output "CodeGraph enrichment complete: $updated notes updated, $failed symbol queries failed."
+if ($Strict -and $failed -gt 0) { exit 1 }

package/scripts/traceability-sync.ps1

@@ -0,0 +1,74 @@
+[CmdletBinding()]
+param(
+  [string]$Since,
+  [switch]$Force,
+  [switch]$Enrich,
+  [switch]$Watch,
+  [ValidateRange(1, 1440)]
+  [int]$IntervalMinutes = 10,
+  [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+
+function Require-Environment([string]$Name) {
+  $value = [Environment]::GetEnvironmentVariable($Name)
+  if ([string]::IsNullOrWhiteSpace($value)) {
+    throw "Required environment variable is missing: $Name"
+  }
+  return $value
+}
+
+$vault = Require-Environment "TRACEABILITY_VAULT"
+$project = Require-Environment "TRACEABILITY_PROJECT"
+if (-not (Test-Path -LiteralPath $vault -PathType Container)) { throw "Vault does not exist: $vault" }
+
+$engram = $env:ENGRAM_BIN
+if ([string]::IsNullOrWhiteSpace($engram)) {
+  $command = Get-Command engram -ErrorAction SilentlyContinue
+  if ($null -eq $command) { throw "Engram CLI not found. Set ENGRAM_BIN or add engram to PATH." }
+  $engram = $command.Source
+}
+
+$args = @("obsidian-export", "--vault", $vault, "--project", $project)
+if ($Since) { $args += @("--since", $Since) }
+if ($Force) { $args += "--force" }
+if ($Watch) { $args += @("--watch", "--interval", ("{0}m" -f $IntervalMinutes)) }
+
+if ($DryRun) {
+  Write-Output ("DRY RUN: {0} {1}" -f $engram, ($args -join " "))
+  exit 0
+}
+
+& $engram @args
+if ($LASTEXITCODE -ne 0) { throw "Engram export failed with exit code $LASTEXITCODE" }
+if ($Watch) { exit 0 }
+
+if ($Enrich) {
+  $enricher = Join-Path $PSScriptRoot "enrich-codegraph.ps1"
+  & $enricher
+  if ($LASTEXITCODE -ne 0) { throw "CodeGraph enrichment failed with exit code $LASTEXITCODE" }
+}
+
+$cli = $env:OBSIDIAN_INTELLIGENCE_CLI
+if ([string]::IsNullOrWhiteSpace($cli)) {
+  $candidate = Join-Path $PSScriptRoot "..\node_modules\obsidian-intelligence\vault-intelligence.js"
+  if (Test-Path -LiteralPath $candidate) { $cli = (Resolve-Path -LiteralPath $candidate).Path }
+}
+
+if ([string]::IsNullOrWhiteSpace($cli) -or -not (Test-Path -LiteralPath $cli -PathType Leaf)) {
+  Write-Warning "Engram export completed; Obsidian reindex skipped. Set OBSIDIAN_INTELLIGENCE_CLI to vault-intelligence.js."
+  exit 0
+}
+
+$node = $env:TRACEABILITY_NODE
+if ([string]::IsNullOrWhiteSpace($node)) {
+  $nodeCommand = Get-Command node -ErrorAction SilentlyContinue
+  if ($null -eq $nodeCommand) { throw "Node not found. Set TRACEABILITY_NODE." }
+  $node = $nodeCommand.Source
+}
+
+& $node $cli index --vault $vault
+if ($LASTEXITCODE -ne 0) { throw "Obsidian index failed with exit code $LASTEXITCODE" }
+& $node $cli status --vault $vault
+if ($LASTEXITCODE -ne 0) { throw "Obsidian status failed with exit code $LASTEXITCODE" }

package/scripts/traceability-sync.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${TRACEABILITY_VAULT:?Set TRACEABILITY_VAULT}"
+: "${TRACEABILITY_PROJECT:?Set TRACEABILITY_PROJECT}"
+
+ENGRAM_BIN="${ENGRAM_BIN:-$(command -v engram || true)}"
+if [[ -z "$ENGRAM_BIN" ]]; then
+  echo "Engram CLI not found; set ENGRAM_BIN." >&2
+  exit 1
+fi
+
+args=(obsidian-export --vault "$TRACEABILITY_VAULT" --project "$TRACEABILITY_PROJECT")
+[[ -n "${TRACEABILITY_SINCE:-}" ]] && args+=(--since "$TRACEABILITY_SINCE")
+[[ "${TRACEABILITY_FORCE:-false}" == "true" ]] && args+=(--force)
+[[ "${TRACEABILITY_WATCH:-false}" == "true" ]] && args+=(--watch --interval "${TRACEABILITY_INTERVAL:-10m}")
+
+if [[ "${TRACEABILITY_DRY_RUN:-false}" == "true" ]]; then
+  printf 'DRY RUN: %q ' "$ENGRAM_BIN" "${args[@]}"
+  printf '\n'
+  exit 0
+fi
+
+"$ENGRAM_BIN" "${args[@]}"
+[[ "${TRACEABILITY_WATCH:-false}" == "true" ]] && exit 0
+
+CLI="${OBSIDIAN_INTELLIGENCE_CLI:-}"
+NODE_BIN="${TRACEABILITY_NODE:-node}"
+if [[ -z "$CLI" ]]; then
+  CLI="$PWD/node_modules/obsidian-intelligence/vault-intelligence.js"
+fi
+
+if [[ ! -f "$CLI" ]]; then
+  echo "Engram export completed; Obsidian reindex skipped. Set OBSIDIAN_INTELLIGENCE_CLI." >&2
+  exit 0
+fi
+
+"$NODE_BIN" "$CLI" index --vault "$TRACEABILITY_VAULT"
+"$NODE_BIN" "$CLI" status --vault "$TRACEABILITY_VAULT"

package/scripts/validate-vault.ps1

@@ -0,0 +1,29 @@
+[CmdletBinding()]
+param([switch]$Strict)
+
+$ErrorActionPreference = "Stop"
+$errors = [System.Collections.Generic.List[string]]::new()
+
+if ([string]::IsNullOrWhiteSpace($env:TRACEABILITY_VAULT)) { $errors.Add("TRACEABILITY_VAULT is missing") }
+elseif (-not (Test-Path -LiteralPath $env:TRACEABILITY_VAULT -PathType Container)) { $errors.Add("Vault does not exist: $env:TRACEABILITY_VAULT") }
+
+if ([string]::IsNullOrWhiteSpace($env:TRACEABILITY_PROJECT)) { $errors.Add("TRACEABILITY_PROJECT is missing") }
+if ([string]::IsNullOrWhiteSpace($env:TRACEABILITY_REPO_ROOT)) { $errors.Add("TRACEABILITY_REPO_ROOT is missing") }
+
+$engram = if ($env:ENGRAM_BIN) { $env:ENGRAM_BIN } else { (Get-Command engram -ErrorAction SilentlyContinue).Source }
+if ([string]::IsNullOrWhiteSpace($engram)) { $errors.Add("Engram CLI not found") }
+
+if ($errors.Count -gt 0) {
+  $errors | ForEach-Object { Write-Error $_ }
+  if ($Strict) { exit 1 }
+}
+
+if ($env:TRACEABILITY_VAULT -and (Test-Path -LiteralPath $env:TRACEABILITY_VAULT)) {
+  $notes = @(Get-ChildItem -LiteralPath $env:TRACEABILITY_VAULT -Filter *.md -File)
+  Write-Output "Vault: $env:TRACEABILITY_VAULT"
+  Write-Output "Markdown notes: $($notes.Count)"
+  Write-Output "SQLite indexes are local and must remain ignored by Git."
+}
+
+if ($errors.Count -gt 0) { exit 1 }
+Write-Output "Traceability configuration is valid."