kirograph 0.27.1 → 0.28.0

package/dist/bin/installer/steering.js

@@ -102,8 +102,13 @@ function buildSteeringContent(opts) {
   const enablePatterns = opts?.enablePatterns ?? false;
   const enableWiki = opts?.enableWiki ?? false;
   const enableCodeHealth = opts?.enableCodeHealth ?? false;
-  const enableAdvancedAnalysis = opts?.enableAdvancedAnalysis ?? false;
+  const enableNavigation = opts?.enableNavigation ?? false;
+  const enableGitContext = opts?.enableGitContext ?? false;
+  const enableComplexity = opts?.enableComplexity ?? false;
+  const enableEditPrimitives = opts?.enableEditPrimitives ?? false;
+  const enableBranch = opts?.enableBranch ?? false;
   const enableAgentUtils = opts?.enableAgentUtils ?? false;
+  const enableGeneralCompression = opts?.enableGeneralCompression ?? false;
   const trackCallSites = opts?.trackCallSites ?? false;
   const guideRows = [
     "| Where do I start on this task? | `kirograph_context` |",
@@ -113,15 +118,17 @@ function buildSteeringContent(opts) {
       "| Who calls function X? | `kirograph_callers` |",
       "| What does function X call? | `kirograph_callees` |"
     ] : [],
-    "| What breaks if I change X? | `kirograph_impact` |",
-    "| How are X and Y connected? | `kirograph_path` |",
-    ...enableAdvancedAnalysis ? ["| What extends / implements this type? | `kirograph_type_hierarchy` |"] : [],
+    ...enableNavigation ? [
+      "| What breaks if I change X? | `kirograph_impact` |",
+      "| What files are indexed? | `kirograph_files` |",
+      "| Is the index healthy? | `kirograph_status` |"
+    ] : [],
     ...enableCodeHealth ? [
+      "| How are X and Y connected? | `kirograph_path` |",
+      "| What extends / implements this type? | `kirograph_type_hierarchy` |",
       "| Which code is never called? | `kirograph_dead_code` |",
       "| Are there import cycles? | `kirograph_circular_deps` |"
     ] : [],
-    "| What files are indexed? | `kirograph_files` |",
-    "| Is the index healthy? | `kirograph_status` |",
     ...enableCodeHealth ? [
       "| What are the most critical symbols? | `kirograph_hotspots` |",
       "| Any unexpected cross-module coupling? | `kirograph_surprising` |",
@@ -133,6 +140,7 @@ function buildSteeringContent(opts) {
       "| What does package X depend on? | `kirograph_package` |"
     ] : [],
     ...enableCompression ? ["| Run a command with token savings | `kirograph_exec` |"] : [],
+    ...enableGeneralCompression ? ["| Compress text or shell output before sending | `kirograph_compress` |"] : [],
     ...enableAgentUtils ? ["| Check token savings stats | `kirograph_gain` |"] : [],
     ...enableData ? [
       "| What data files are indexed? | `kirograph_data_list` |",
@@ -149,7 +157,30 @@ function buildSteeringContent(opts) {
       "| Generate SBOM/VEX | `kirograph_sbom` / `kirograph_vex` |",
       "| Add a private CVE | `kirograph_vuln_add` |"
     ] : [],
-    ...enablePatterns ? ["| Find structural code patterns? | `kirograph_live_search` |"] : []
+    ...enablePatterns ? ["| Find structural code patterns? | `kirograph_live_search` |"] : [],
+    ...enableComplexity ? [
+      "| Overall graph health score | `kirograph_health` |",
+      "| Most complex functions? | `kirograph_complexity` |",
+      "| Which functions are highest risk to change? | `kirograph_test_risk` |",
+      "| How are modules coupled? | `kirograph_dsm` |"
+    ] : [],
+    ...enableGitContext ? [
+      "| What symbols did I change? | `kirograph_diff_context` |",
+      "| Build commit message context | `kirograph_commit_context` |",
+      "| Generate PR description | `kirograph_pr_context` |",
+      "| What tests cover symbol X? | `kirograph_test_map` |",
+      "| Show per-file coverage report | `kirograph_test_coverage` |"
+    ] : [],
+    ...enableEditPrimitives ? [
+      "| Replace a unique string in a file | `kirograph_str_replace` |",
+      "| Insert content before/after an anchor | `kirograph_insert_at` |",
+      "| Atomic multi-replacement in a file | `kirograph_multi_str_replace` |"
+    ] : [],
+    ...enableBranch ? [
+      "| List tracked branches | `kirograph_branch_list` |",
+      "| What changed between branches? | `kirograph_branch_diff` |",
+      "| Search symbols in another branch | `kirograph_branch_search` |"
+    ] : []
   ];
   let toolRef = `
 ## Tool reference
@@ -203,7 +234,8 @@ BFS over outgoing \`calls\` edges (depth 1).
 kirograph_callees(symbol: "handleRequest")
 \`\`\``;
   }
-  toolRef += `
+  if (enableNavigation) {
+    toolRef += `
 
 ### \`kirograph_impact\`: blast radius before a change
 
@@ -211,7 +243,10 @@ Traverses all incoming edges up to \`depth\` hops. Call this before editing a sy
 
 \`\`\`
 kirograph_impact(symbol: "UserRepository", depth: 3)
-\`\`\`
+\`\`\``;
+  }
+  if (enableCodeHealth) {
+    toolRef += `
 
 ### \`kirograph_path\`: how are two symbols connected?
 
@@ -219,9 +254,7 @@ BFS shortest path across all edge types.
 
 \`\`\`
 kirograph_path(from: "LoginController", to: "DatabasePool")
-\`\`\``;
-  if (enableAdvancedAnalysis) {
-    toolRef += `
+\`\`\`
 
 ### \`kirograph_type_hierarchy\`: class/interface inheritance
 
@@ -252,6 +285,7 @@ kirograph_circular_deps()
   }
   toolRef += `
 
+${enableNavigation ? `
 ### \`kirograph_files\`: indexed file structure
 
 \`\`\`
@@ -264,7 +298,7 @@ kirograph_files(pattern: "**/*.test.ts")
 
 ### \`kirograph_status\`: index health
 
-Returns file count, symbol count, edge count, embedding coverage, DB size. Call when something feels off.`;
+Returns file count, symbol count, edge count, embedding coverage, DB size. Call when something feels off.` : ""}`;
   if (enableCodeHealth) {
     toolRef += `
 
@@ -330,6 +364,168 @@ Returns metadata, coupling metrics, outgoing deps, incoming dependents, and file
 \`\`\`
 kirograph_package(package: "auth")
 kirograph_package(package: "src/services", includeFiles: false)
+\`\`\``;
+  }
+  if (enableComplexity) {
+    toolRef += `
+
+---
+
+## Complexity tools *(require \`enableComplexity: true\` in config)*
+
+### \`kirograph_health\`: composite graph health score
+
+Returns a 0\u201310000 score across four dimensions: complexity, dead code, coupling, circular deps.
+Higher is better. Excellent \u2265 9000 \xB7 Good \u2265 7000 \xB7 Fair \u2265 5000 \xB7 Poor \u2265 3000 \xB7 Critical < 3000.
+
+\`\`\`
+kirograph_health()
+\`\`\`
+
+### \`kirograph_complexity\`: rank functions by complexity
+
+Returns cyclomatic complexity (CC), cognitive complexity, maintainability index (MI), and nesting depth, sorted by chosen metric.
+
+\`\`\`
+kirograph_complexity(metric: "cyclomatic", limit: 30, threshold: 10)
+kirograph_complexity(metric: "cognitive")
+kirograph_complexity(metric: "maintainability")  // sort ASC \u2014 lowest MI first
+\`\`\`
+
+### \`kirograph_dsm\`: design structure matrix
+
+Groups nodes by top-level directory and shows a dependency count matrix between groups. Reveals which modules depend on which others and where tight coupling lives.
+
+\`\`\`
+kirograph_dsm()
+kirograph_dsm(limit: 10)  // cap number of groups shown
+\`\`\`
+
+### \`kirograph_test_risk\`: risk-ranked functions
+
+Risk = complexity \xD7 fan-in. Highest-risk functions are most likely to cause failures when changed.
+
+\`\`\`
+kirograph_test_risk(limit: 20)
+kirograph_test_risk(threshold: 50)  // only show risk score \u2265 50
+\`\`\``;
+  }
+  if (enableGitContext) {
+    toolRef += `
+
+---
+
+## Git Context tools *(require \`enableGitContext: true\` in config)*
+
+### \`kirograph_diff_context\`: changed symbols in working tree
+
+Returns symbols whose definitions overlap with \`git diff\` line ranges, plus their callers and callees. Use before a commit to understand what you actually changed.
+
+\`\`\`
+kirograph_diff_context()              // unstaged changes
+kirograph_diff_context(staged: true)  // staged changes only
+\`\`\`
+
+### \`kirograph_commit_context\`: staged changes summary
+
+Returns staged files, diff stat, and affected symbols. Ready to paste into a commit message prompt.
+
+\`\`\`
+kirograph_commit_context()
+\`\`\`
+
+### \`kirograph_pr_context\`: semantic diff between two refs
+
+Returns symbols added/removed/changed between two git refs. Use for PR descriptions.
+
+\`\`\`
+kirograph_pr_context(base: "main", head: "HEAD")
+kirograph_pr_context(base: "v1.2.0")
+\`\`\`
+
+### \`kirograph_test_map\`: symbol \u2192 test file mapping
+
+Shows which test files cover a symbol (by caller graph), and which symbols have no test coverage at all.
+
+\`\`\`
+kirograph_test_map()                         // all uncovered symbols
+kirograph_test_map(symbol: "processPayment") // tests for a specific symbol
+\`\`\`
+
+### \`kirograph_test_coverage\`: per-file coverage report
+
+Parses lcov/Istanbul/Cobertura files. Sorted worst-first by default.
+
+\`\`\`
+kirograph_test_coverage()
+kirograph_test_coverage(sortBy: "desc", limit: 20)  // best coverage first
+\`\`\``;
+  }
+  if (enableEditPrimitives) {
+    toolRef += `
+
+---
+
+## Edit Primitives *(require \`enableEditPrimitives: true\` in config)*
+
+Atomic file edit tools. Each validates the anchor is unique before writing, then triggers \`kirograph sync\` to keep the graph up to date.
+
+### \`kirograph_str_replace\`: replace a unique string
+
+Fails on 0 or >1 matches \u2014 safe to use without counting occurrences first.
+
+\`\`\`
+kirograph_str_replace(file: "src/auth.ts", old_str: "const timeout = 5000", new_str: "const timeout = 10000")
+\`\`\`
+
+### \`kirograph_multi_str_replace\`: N replacements as one transaction
+
+All-or-nothing: if any replacement fails, none are applied.
+
+\`\`\`
+kirograph_multi_str_replace(file: "src/auth.ts", pairs: [
+  { old_str: "oldFunctionName", new_str: "newFunctionName" },
+  { old_str: "OldClass", new_str: "NewClass" }
+])
+\`\`\`
+
+### \`kirograph_insert_at\`: insert before/after an anchor
+
+\`\`\`
+kirograph_insert_at(file: "src/routes.ts", anchor: "// END ROUTES", content: "router.get('/health', healthCheck);", position: "before")
+\`\`\`
+
+### \`kirograph_refactor\`: structured search-and-replace across the graph
+
+\`\`\`
+kirograph_refactor(symbol: "OldName", newName: "NewName", kind: "function")
+\`\`\``;
+  }
+  if (enableBranch) {
+    toolRef += `
+
+---
+
+## Branch tools *(require \`enableBranch: true\` in config)*
+
+Each branch gets its own SQLite DB at \`.kirograph/branch-<name>.db\`. Use \`kirograph branch add\` to start tracking a branch.
+
+### \`kirograph_branch_list\`: tracked branches
+
+\`\`\`
+kirograph_branch_list()
+\`\`\`
+
+### \`kirograph_branch_diff\`: symbols added/removed/changed between branches
+
+\`\`\`
+kirograph_branch_diff(branchA: "feature/new-auth", branchB: "main")
+\`\`\`
+
+### \`kirograph_branch_search\`: search symbols in another branch
+
+\`\`\`
+kirograph_branch_search(query: "processPayment", branch: "main")
 \`\`\``;
   }
   let bugFixWorkflow = `**Bug fix or feature:**
@@ -376,13 +572,53 @@ ${bugFixWorkflow}`;
 2. \`kirograph_circular_deps\`: find import cycles to untangle.
 3. \`kirograph_surprising\`: find unexpected coupling to decouple.`;
   }
+  if (enableComplexity) {
+    workflows += `
+
+**Code quality audit:**
+1. \`kirograph_health\`: get overall health score and breakdown.
+2. \`kirograph_complexity\`: rank functions by cyclomatic complexity \u2014 focus on CC > 10.
+3. \`kirograph_test_risk\`: find highest-risk functions (complexity \xD7 fan-in) to prioritize test coverage.
+4. \`kirograph_dsm\`: check architectural coupling \u2014 high off-diagonal counts = tight coupling.`;
+  }
+  if (enableGitContext) {
+    workflows += `
+
+**Pre-commit / pre-push review:**
+1. \`kirograph_diff_context\`: understand what symbols changed and who calls them.
+2. \`kirograph_test_map\`: verify changed symbols have test coverage.
+3. \`kirograph_commit_context\`: build a structured commit message.
+
+**PR description:**
+1. \`kirograph_pr_context(base: "main")\`: get semantic diff between branches.
+2. Use the output as structured context for the PR summary.`;
+  }
+  if (enableEditPrimitives) {
+    workflows += `
+
+**Safe atomic edit:**
+1. \`kirograph_impact\`: check blast radius before editing.
+2. \`kirograph_str_replace\` or \`kirograph_insert_at\`: apply atomic change \u2014 validates uniqueness first.
+3. After edit: \`kirograph_diff\` to verify only intended symbols changed.`;
+  }
+  if (enableBranch) {
+    workflows += `
+
+**Cross-branch investigation:**
+1. \`kirograph_branch_list\`: see which branches are tracked.
+2. \`kirograph_branch_diff\`: find symbols added/removed/changed vs target branch.
+3. \`kirograph_branch_search\`: locate a symbol in another branch's graph.`;
+  }
+  const hasRichFeatures = enableNavigation || enableCodeHealth || trackCallSites;
   const workflowRows = [
     ...enableSecurity ? ["| security audit, check vulnerabilities, CVE review | `.kiro/steering/kirograph-security.md` |"] : [],
-    "| code review, review this PR | `.kiro/steering/kirograph-review.md` |",
-    "| debug, trace this bug, root cause | `.kiro/steering/kirograph-debug.md` |",
+    ...hasRichFeatures ? ["| code review, review this PR | `.kiro/steering/kirograph-review.md` |"] : [],
+    ...hasRichFeatures ? ["| debug, trace this bug, root cause | `.kiro/steering/kirograph-debug.md` |"] : [],
     ...enableArchitecture ? ["| architecture, understand structure, package map | `.kiro/steering/kirograph-architecture.md` |"] : [],
-    "| onboard, understand this codebase | `.kiro/steering/kirograph-onboard.md` |",
-    "| refactor, rename, safe refactoring | `.kiro/steering/kirograph-refactor.md` |",
+    ...hasRichFeatures ? ["| onboard, understand this codebase | `.kiro/steering/kirograph-onboard.md` |"] : [],
+    ...hasRichFeatures ? ["| refactor, rename, safe refactoring | `.kiro/steering/kirograph-refactor.md` |"] : [],
+    ...enableGitContext ? ["| git diff review, PR context, commit message | `.kiro/steering/kirograph-git-context.md` |"] : [],
+    ...enableComplexity ? ["| code quality audit, complexity, health score | `.kiro/steering/kirograph-complexity.md` |"] : [],
     ...enableMemory ? ["| memory, recall decisions, conflict detection | `.kiro/steering/kirograph-mem-workflow.md` |"] : [],
     ...enableWiki ? ["| wiki, update knowledge base, ingest docs | `.kiro/steering/kirograph-wiki-workflow.md` |"] : []
   ];
@@ -545,6 +781,42 @@ KiroGraph can search for structural code patterns using @ast-grep/napi.
 `;
     content = content.trimEnd() + "\n\n" + patternsSection.trim() + "\n";
   }
+  if (enableGeneralCompression) {
+    const generalCompressionSection = `
+## General-purpose compression
+
+\`kirograph_compress\` is an on-demand tool for reducing token usage before content reaches the model.
+Call it whenever you receive large input that you need to reason over but not reproduce verbatim.
+
+**Two engines \u2014 auto-routed by the \`command\` parameter:**
+
+| Scenario | Call |
+|----------|------|
+| Paste of shell output (git log, npm install, test run, docker ps\u2026) | \`kirograph_compress(text: "...", command: "git log")\` |
+| Prose text, RAG chunk, observation, or mixed content | \`kirograph_compress(text: "...")\` |
+
+- **With \`command\`:** rtk-style structural filters \u2014 pattern-matched to the command family (git, test, lint, docker, etc.), removes noise, deduplicates repeated lines, keeps structure.
+- **Without \`command\`:** caveman grammar \u2014 removes filler words, articles, hedging phrases, and (at ultra level) applies standard abbreviations. Preserves code blocks, paths, URLs, and identifiers unchanged.
+
+**Compression levels** (same enum for both engines):
+- \`lite\` / \`normal\` \u2014 light touch: remove noise and filler only
+- \`full\` / \`aggressive\` \u2014 default: also remove articles, hedging, group repeated output
+- \`ultra\` \u2014 maximum: abbreviations, causality arrows (\u2192), conjunction compression (+)
+
+**When to use:**
+- You received a large file diff, log dump, or search result and only need the structure
+- You want to store an observation in memory and the text is verbose
+- A tool output is close to or over budget and you need to trim before reasoning
+
+**When NOT to use:**
+- Content that must be reproduced exactly (code to be written to disk, user quotes)
+- Short content (< 200 tokens) \u2014 overhead not worth it
+- Already-compressed output (kirograph_exec already applies rtk filters automatically)
+
+**Savings are reported inline:** \`[42% saved | 1800\u21921044 | rtk:git:aggressive]\`
+`;
+    content = content.trimEnd() + "\n\n" + generalCompressionSection.trim() + "\n";
+  }
   if (enableWiki) {
     const wikiSection = `
 ## Wiki
@@ -640,39 +912,63 @@ function writeWorkflowSteering(steeringDir, opts) {
   const trackCallSites = opts?.trackCallSites ?? false;
   const enableCodeHealth = opts?.enableCodeHealth ?? false;
   const enableArchitecture = opts?.enableArchitecture ?? false;
-  const enableAdvancedAnalysis = opts?.enableAdvancedAnalysis ?? false;
-  const reviewSteps = [
-    `1. **Understand the change scope**
+  const enableNavigation = opts?.enableNavigation ?? false;
+  const enableGitContext = opts?.enableGitContext ?? false;
+  const enableComplexity = opts?.enableComplexity ?? false;
+  const enableEditPrimitives = opts?.enableEditPrimitives ?? false;
+  const hasRichFeatures = enableNavigation || enableCodeHealth || trackCallSites;
+  if (hasRichFeatures) {
+    const reviewSteps = [
+      `1. **Understand the change scope**
    \`\`\`
    kirograph_context(task: "<describe what changed>")
-   \`\`\``,
-    `2. **Analyze blast radius**
+   \`\`\``
+    ];
+    if (enableGitContext) {
+      reviewSteps.push(`2. **See exactly what symbols changed**
+   \`\`\`
+   kirograph_diff_context(staged: true)
+   \`\`\`
+   Lists changed symbols, their callers (who may break), and callees (what they depend on).`);
+    }
+    reviewSteps.push(`${reviewSteps.length + 1}. **Analyze blast radius**
    For each key symbol that was modified:
    \`\`\`
    kirograph_impact(symbol: "<changed symbol>", depth: 2)
-   \`\`\``
-  ];
-  if (trackCallSites) {
-    reviewSteps.push(`3. **Check test coverage**
+   \`\`\``);
+    if (enableGitContext) {
+      reviewSteps.push(`${reviewSteps.length + 1}. **Verify test coverage for changed symbols**
+   \`\`\`
+   kirograph_test_map(symbol: "<changed symbol>")
+   \`\`\`
+   Flag any changed symbols with no test files in their caller graph.`);
+    } else if (trackCallSites) {
+      reviewSteps.push(`${reviewSteps.length + 1}. **Check test coverage**
    \`\`\`
    kirograph_callers(symbol: "<changed symbol>")
    \`\`\`
    Look for test files among the callers. Flag untested changes.`);
-  }
-  if (enableCodeHealth) {
-    const n = reviewSteps.length + 1;
-    reviewSteps.push(`${n}. **Look for surprising coupling**
+    }
+    if (enableComplexity) {
+      reviewSteps.push(`${reviewSteps.length + 1}. **Check risk score of changed functions**
+   \`\`\`
+   kirograph_test_risk(limit: 10)
+   \`\`\`
+   High risk (complexity \xD7 fan-in) = extra scrutiny warranted.`);
+    }
+    if (enableCodeHealth) {
+      reviewSteps.push(`${reviewSteps.length + 1}. **Look for surprising coupling**
    \`\`\`
    kirograph_surprising(limit: 10)
    \`\`\``);
-  }
-  const findingsN = reviewSteps.length + 1;
-  reviewSteps.push(`${findingsN}. **Produce findings** grouped by risk level (high/medium/low) with:
+    }
+    const findingsN = reviewSteps.length + 1;
+    reviewSteps.push(`${findingsN}. **Produce findings** grouped by risk level (high/medium/low) with:
    - What changed and why it matters
    - Test coverage status
    - Suggested improvements
    - Overall merge recommendation`);
-  fs.writeFileSync(path.join(steeringDir, "kirograph-review.md"), `---
+    fs.writeFileSync(path.join(steeringDir, "kirograph-review.md"), `---
 inclusion: manual
 ---
 
@@ -684,40 +980,47 @@ Follow these steps for a structured, risk-aware code review using the knowledge
 
 ${reviewSteps.join("\n\n")}
 `);
-  const debugSteps = [
-    `1. **Find related code**
+    const debugSteps = [
+      `1. **Find related code**
    \`\`\`
    kirograph_search(query: "<error message or symptom keywords>")
    \`\`\``,
-    `2. **Get full context**
+      `2. **Get full context**
    \`\`\`
    kirograph_context(task: "<describe the bug>")
    \`\`\``
-  ];
-  if (trackCallSites) {
-    debugSteps.push(`3. **Trace the call chain**
+    ];
+    if (enableGitContext) {
+      debugSteps.push(`3. **Check what recently changed in related symbols**
    \`\`\`
-   kirograph_callers(symbol: "<suspected function>")
-   kirograph_callees(symbol: "<suspected function>")
-   \`\`\``);
-  }
-  if (enableCodeHealth) {
-    const n = debugSteps.length + 1;
-    debugSteps.push(`${n}. **Check what changed recently**
+   kirograph_diff_context()
+   \`\`\`
+   Most bugs trace back to recent changes \u2014 this surfaces them immediately.`);
+    } else if (enableCodeHealth) {
+      debugSteps.push(`3. **Check what changed recently**
    \`\`\`
    kirograph_diff()
    \`\`\``);
-  }
-  const blastN = debugSteps.length + 1;
-  debugSteps.push(`${blastN}. **Understand blast radius**
+    }
+    if (trackCallSites) {
+      const n = debugSteps.length + 1;
+      debugSteps.push(`${n}. **Trace the call chain**
+   \`\`\`
+   kirograph_callers(symbol: "<suspected function>")
+   kirograph_callees(symbol: "<suspected function>")
+   \`\`\``);
+    }
+    const blastN = debugSteps.length + 1;
+    debugSteps.push(`${blastN}. **Understand blast radius**
    \`\`\`
    kirograph_impact(symbol: "<root cause symbol>", depth: 3)
    \`\`\``);
-  const debugTips = [];
-  if (trackCallSites) debugTips.push("- Check both callers and callees to understand the full context");
-  if (enableCodeHealth) debugTips.push("- Recent changes (via diff) are the most common source of new issues");
-  debugTips.push("- Use `kirograph_path` to trace how two symbols are connected");
-  fs.writeFileSync(path.join(steeringDir, "kirograph-debug.md"), `---
+    const debugTips = [];
+    if (trackCallSites) debugTips.push("- Check both callers and callees to understand the full context");
+    if (enableGitContext) debugTips.push("- `kirograph_diff_context` is the fastest way to spot a regression \u2014 check it first");
+    else if (enableCodeHealth) debugTips.push("- Recent changes (via diff) are the most common source of new issues");
+    debugTips.push("- Use `kirograph_path` to trace how two symbols are connected");
+    fs.writeFileSync(path.join(steeringDir, "kirograph-debug.md"), `---
 inclusion: manual
 ---
 
@@ -732,44 +1035,44 @@ ${debugSteps.join("\n\n")}
 ## Tips
 ${debugTips.join("\n")}
 `);
-  const onboardSteps = [
-    `1. **Project overview**
+    const onboardSteps = [
+      `1. **Project overview**
    \`\`\`
    kirograph_status()
    \`\`\``,
-    `2. **File structure**
+      `2. **File structure**
    \`\`\`
    kirograph_files(format: "tree", maxDepth: 2)
    \`\`\``
-  ];
-  if (enableCodeHealth) {
-    onboardSteps.push(`3. **Key entry points**
+    ];
+    if (enableCodeHealth) {
+      onboardSteps.push(`3. **Key entry points**
    \`\`\`
    kirograph_hotspots(limit: 15)
    \`\`\``);
-  }
-  if (enableArchitecture) {
-    const n = onboardSteps.length + 1;
-    onboardSteps.push(`${n}. **Architecture layers**
+    }
+    if (enableArchitecture) {
+      const n = onboardSteps.length + 1;
+      onboardSteps.push(`${n}. **Architecture layers**
    \`\`\`
    kirograph_architecture()
    \`\`\``);
-  }
-  const exploreN = onboardSteps.length + 1;
-  onboardSteps.push(`${exploreN}. **Explore a specific area**
+    }
+    const exploreN = onboardSteps.length + 1;
+    onboardSteps.push(`${exploreN}. **Explore a specific area**
    \`\`\`
    kirograph_context(task: "<area you want to understand>")
    \`\`\``);
-  const symbolN = onboardSteps.length + 1;
-  onboardSteps.push(`${symbolN}. **Understand a key symbol**
+    const symbolN = onboardSteps.length + 1;
+    onboardSteps.push(`${symbolN}. **Understand a key symbol**
    \`\`\`
    kirograph_node(symbol: "<symbol name>", includeCode: true)
    \`\`\``);
-  const onboardTips = ["- Start broad (status, files) then narrow down"];
-  if (enableCodeHealth) onboardTips[0] = "- Start broad (status, files, hotspots) then narrow down";
-  if (enableAdvancedAnalysis) onboardTips.push("- Use `kirograph_type_hierarchy` to understand inheritance patterns");
-  if (trackCallSites) onboardTips.push("- Use `kirograph_callees` on entry points to trace execution flow");
-  fs.writeFileSync(path.join(steeringDir, "kirograph-onboard.md"), `---
+    const onboardTips = ["- Start broad (status, files) then narrow down"];
+    if (enableCodeHealth) onboardTips[0] = "- Start broad (status, files, hotspots) then narrow down";
+    if (enableCodeHealth) onboardTips.push("- Use `kirograph_type_hierarchy` to understand inheritance patterns");
+    if (trackCallSites) onboardTips.push("- Use `kirograph_callees` on entry points to trace execution flow");
+    fs.writeFileSync(path.join(steeringDir, "kirograph-onboard.md"), `---
 inclusion: manual
 ---
 
@@ -784,44 +1087,45 @@ ${onboardSteps.join("\n\n")}
 ## Tips
 ${onboardTips.join("\n")}
 `);
-  const refactorSteps = [
-    `1. **Understand what you're changing**
+    const refactorSteps = [
+      `1. **Understand what you're changing**
    \`\`\`
    kirograph_node(symbol: "<target symbol>", includeCode: true)
    \`\`\``,
-    `2. **Check blast radius**
+      `2. **Check blast radius**
    \`\`\`
    kirograph_impact(symbol: "<target symbol>", depth: 3)
    \`\`\``
-  ];
-  if (trackCallSites) {
-    refactorSteps.push(`3. **Find all callers (rename preview)**
+    ];
+    if (trackCallSites) {
+      refactorSteps.push(`3. **Find all callers (rename preview)**
    \`\`\`
    kirograph_callers(symbol: "<target symbol>", limit: 50)
    \`\`\``);
-  }
-  if (enableCodeHealth) {
-    let n = refactorSteps.length + 1;
-    refactorSteps.push(`${n}. **Check for cycles that might complicate the refactor**
+    }
+    if (enableCodeHealth) {
+      let n = refactorSteps.length + 1;
+      refactorSteps.push(`${n}. **Check for cycles that might complicate the refactor**
    \`\`\`
    kirograph_circular_deps()
    \`\`\``);
-    n++;
-    refactorSteps.push(`${n}. **Find dead code to clean up**
+      n++;
+      refactorSteps.push(`${n}. **Find dead code to clean up**
    \`\`\`
    kirograph_dead_code(limit: 30)
    \`\`\``);
-    n++;
-    refactorSteps.push(`${n}. **Verify after changes**
+      n++;
+      refactorSteps.push(`${n}. **Verify after changes**
    Run \`kirograph sync\` then:
    \`\`\`
    kirograph_diff()
    \`\`\``);
-  }
-  const refactorChecks = ["- Always check `kirograph_impact` before major refactors"];
-  if (trackCallSites) refactorChecks.push("- Use `kirograph_callers` as a rename preview (all locations that reference the symbol)");
-  if (enableCodeHealth) refactorChecks.push("- After changes, use `kirograph_diff` to verify only intended symbols changed");
-  fs.writeFileSync(path.join(steeringDir, "kirograph-refactor.md"), `---
+    }
+    const refactorChecks = ["- Always check `kirograph_impact` before major refactors"];
+    if (trackCallSites) refactorChecks.push("- Use `kirograph_callers` as a rename preview (all locations that reference the symbol)");
+    if (enableCodeHealth) refactorChecks.push("- After changes, use `kirograph_diff` to verify only intended symbols changed");
+    if (enableEditPrimitives) refactorChecks.push("- Use `kirograph_str_replace` / `kirograph_multi_str_replace` for atomic edits that auto-sync the graph");
+    fs.writeFileSync(path.join(steeringDir, "kirograph-refactor.md"), `---
 inclusion: manual
 ---
 
@@ -836,6 +1140,7 @@ ${refactorSteps.join("\n\n")}
 ## Safety Checks
 ${refactorChecks.join("\n")}
 `);
+  }
   if (enableArchitecture) {
     const archSteps = [
       `1. **Get project overview**
@@ -868,6 +1173,27 @@ ${refactorChecks.join("\n")}
    kirograph_circular_deps()
    \`\`\``);
     }
+    if (enableComplexity) {
+      let n = archSteps.length + 1;
+      archSteps.push(`${n}. **Module coupling matrix (DSM)**
+   \`\`\`
+   kirograph_dsm()
+   \`\`\`
+   High off-diagonal counts = tight coupling. Complements \`kirograph_coupling\` (package-level) with a symbol-level view.`);
+      n++;
+      archSteps.push(`${n}. **Overall health score**
+   \`\`\`
+   kirograph_health()
+   \`\`\`
+   The circular deps and coupling components directly reflect architectural quality.`);
+    }
+    const archInterpretation = [
+      "- High Ca (afferent) = load-bearing, risky to change interface",
+      "- High Ce (efferent) = depends on many things, safe to refactor internals",
+      ...enableCodeHealth ? ["- Surprising edges = hidden coupling that may break during refactoring"] : [],
+      ...enableComplexity ? ["- DSM diagonal = self-coupling (normal). Off-diagonal = cross-module coupling (minimize)."] : [],
+      ...enableComplexity ? ["- Health circular_score < 1500 = architectural debt requiring attention"] : []
+    ];
     fs.writeFileSync(path.join(steeringDir, "kirograph-architecture.md"), `---
 inclusion: manual
 ---
@@ -881,11 +1207,24 @@ Follow these steps to understand the high-level structure of the codebase.
 ${archSteps.join("\n\n")}
 
 ## Interpretation
-- High Ca (afferent) = load-bearing, risky to change interface
-- High Ce (efferent) = depends on many things, safe to refactor internals
-${enableCodeHealth ? "- Surprising edges = hidden coupling that may break during refactoring\n" : ""}`);
+${archInterpretation.join("\n")}
+`);
   }
   if (opts?.enableSecurity) {
+    const securityPatternsStep = opts?.enablePatterns ? `
+### 5b. Structural vulnerability patterns (AST search)
+\`\`\`
+kirograph_live_search(pattern: "eval($X)", language: "javascript")
+kirograph_live_search(pattern: "$OBJ.query($A + $B)", language: "typescript")
+\`\`\`
+Use \`kirograph pattern --list\` to browse bundled SAST rules (SQL injection, path traversal, hardcoded secrets, etc.).
+These patterns find code issues missed by dependency scanning.` : "";
+    const securityComplexityStep = enableComplexity ? `
+### 5c. High-complexity code in security-critical paths
+\`\`\`
+kirograph_test_risk(limit: 15)
+\`\`\`
+High risk (complexity \xD7 fan-in) in auth/payment/session code = higher attack surface. Cross-reference with reachability results.` : "";
     fs.writeFileSync(path.join(steeringDir, "kirograph-security.md"), `---
 inclusion: manual
 ---
@@ -937,6 +1276,7 @@ kirograph_licenses(policy: true)
 \`\`\`
 Review any DENY violations \u2014 these must be resolved before shipping.
 WARN violations should be documented and approved by the team.
+${securityPatternsStep}${securityComplexityStep}
 
 ### 6. Dependency staleness
 \`\`\`
@@ -967,7 +1307,7 @@ kirograph_vex()    // Vulnerability Exploitability eXchange
 | \`not_affected\` | No reachable path found | Document, no action needed |
 | \`under_investigation\` | Reachability unclear | Manual review required |
 | Stale >= 0.7 | Very outdated | Review for accumulated CVEs |
-| License DENY | Policy violation | Must resolve before release |
+| License DENY | Policy violation | Must resolve before release |${opts?.enablePatterns ? "\n| Pattern match in security-critical code | Code-level vulnerability pattern found | Review context with `kirograph_node` |" : ""}
 `);
     console.log(`  \u2713 Security workflow steering file written`);
   }
@@ -1247,13 +1587,142 @@ superseded via \`kirograph_mem_judge\`.
 `);
     console.log(`  \u2713 Memory workflow steering file written`);
   }
-  const written = ["review", "debug", "onboard", "refactor"];
+  if (enableGitContext) {
+    fs.writeFileSync(path.join(steeringDir, "kirograph-git-context.md"), `---
+inclusion: manual
+---
+
+# KiroGraph: Git Context Workflow
+
+Use this workflow for pre-commit reviews, PR descriptions, and understanding what changed.
+
+## 1. Before committing \u2014 understand what you changed
+
+\`\`\`
+kirograph_diff_context()              // unstaged \u2014 see what's touched
+kirograph_diff_context(staged: true)  // staged \u2014 final check before commit
+\`\`\`
+
+This shows changed symbols, their callers (who might break), and their callees (what they call).
+
+## 2. Build commit message context
+
+\`\`\`
+kirograph_commit_context()
+\`\`\`
+
+Returns staged files, diff stat, and affected symbols. Feed into commit message generation.
+
+## 3. Check test coverage for changed symbols
+
+\`\`\`
+kirograph_test_map()                          // all symbols with no test coverage
+kirograph_test_map(symbol: "<changed fn>")    // tests for a specific symbol
+\`\`\`
+
+## 4. PR description
+
+\`\`\`
+kirograph_pr_context(base: "main", head: "HEAD")
+\`\`\`
+
+Returns symbols added/removed/changed between refs. Use as structured context for PR summary.
+
+## 5. Coverage report (if lcov/Istanbul files exist)
+
+\`\`\`
+kirograph_test_coverage()                    // worst-covered files first
+kirograph_test_coverage(sortBy: "desc")      // best-covered files first
+\`\`\`
+
+## Quick reference
+
+| Intent | Tool |
+|--------|------|
+| What did I change? | \`kirograph_diff_context\` |
+| Commit message | \`kirograph_commit_context\` |
+| PR description | \`kirograph_pr_context\` |
+| Are my changes tested? | \`kirograph_test_map\` |
+| Per-file coverage % | \`kirograph_test_coverage\` |
+| Semantic changelog | \`kirograph_changelog\` |
+`);
+    console.log(`  \u2713 Git context workflow steering file written`);
+  }
+  if (enableComplexity) {
+    fs.writeFileSync(path.join(steeringDir, "kirograph-complexity.md"), `---
+inclusion: manual
+---
+
+# KiroGraph: Code Quality Workflow
+
+Use this workflow to audit code quality, find high-risk functions, and track health over time.
+
+## 1. Get an overall health score
+
+\`\`\`
+kirograph_health()
+\`\`\`
+
+Returns a 0\u201310000 score across complexity, dead code, coupling, and circular dependencies.
+Check all four components \u2014 a high total can mask one very low component.
+
+## 2. Find complex functions
+
+\`\`\`
+kirograph_complexity(metric: "cyclomatic", threshold: 10)
+kirograph_complexity(metric: "maintainability")  // lowest MI first \u2014 most unmaintainable
+\`\`\`
+
+**Thresholds:** CC > 10 = review candidate. CC > 20 = refactor. MI < 50 = unmaintainable.
+
+## 3. Find highest-risk functions to change
+
+\`\`\`
+kirograph_test_risk(limit: 20)
+\`\`\`
+
+Risk = complexity \xD7 fan-in. These functions will have the widest blast radius if they break.
+
+## 4. Check architectural coupling
+
+\`\`\`
+kirograph_dsm()
+\`\`\`
+
+High off-diagonal counts = tight coupling. Aim for low counts outside the diagonal.
+
+## 5. Scan for simplification candidates
+
+\`\`\`
+kirograph_simplify_scan()
+\`\`\`
+
+Lists functions that fail on CC, MI, or LOC thresholds.
+
+## Quick reference
+
+| Intent | Tool |
+|--------|------|
+| Overall health | \`kirograph_health\` |
+| Most complex functions | \`kirograph_complexity\` |
+| Highest-risk to change | \`kirograph_test_risk\` |
+| Module coupling matrix | \`kirograph_dsm\` |
+| Simplification candidates | \`kirograph_simplify_scan\` |
+`);
+    console.log(`  \u2713 Complexity workflow steering file written`);
+  }
+  const written = [];
+  if (hasRichFeatures) written.push("review", "debug", "onboard", "refactor");
   if (opts?.enableArchitecture) written.push("architecture");
   if (opts?.enableSecurity) written.push("security");
   if (opts?.enablePatterns) written.push("patterns");
+  if (enableGitContext) written.push("git-context");
+  if (enableComplexity) written.push("complexity");
   if (opts?.enableMemory) written.push("memory");
   if (opts?.enableWiki) written.push("wiki");
-  console.log(`  \u2713 Workflow steering files written (${written.join(", ")})`);
+  if (written.length > 0) {
+    console.log(`  \u2713 Workflow steering files written (${written.join(", ")})`);
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {