causoryn 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/.claude-plugin/plugin.json +36 -0
  2. package/.codex-plugin/mcp.json +19 -0
  3. package/.codex-plugin/plugin.json +38 -0
  4. package/.zcode-plugin/plugin.json +42 -0
  5. package/LICENSE +21 -0
  6. package/README.md +171 -2
  7. package/THIRD-PARTY-NOTICES.md +443 -0
  8. package/dist/bundle-manifest.json +39 -0
  9. package/dist/cli.d.ts +3 -0
  10. package/dist/cli.js +253 -0
  11. package/dist/doctor.d.ts +13 -0
  12. package/dist/doctor.js +507 -0
  13. package/dist/index.d.ts +10 -0
  14. package/dist/index.js +10 -0
  15. package/dist/mcp-server.mjs +288477 -0
  16. package/dist/mcp-server.mjs.LEGAL.txt +17 -0
  17. package/dist/node_modules/better-sqlite3/LICENSE +21 -0
  18. package/dist/node_modules/better-sqlite3/lib/binding.js +62 -0
  19. package/dist/node_modules/better-sqlite3/lib/darwin-arm64.js +3 -0
  20. package/dist/node_modules/better-sqlite3/lib/darwin-x64.js +3 -0
  21. package/dist/node_modules/better-sqlite3/lib/database.js +109 -0
  22. package/dist/node_modules/better-sqlite3/lib/index.js +3 -0
  23. package/dist/node_modules/better-sqlite3/lib/linux-arm64.js +3 -0
  24. package/dist/node_modules/better-sqlite3/lib/linux-x64.js +3 -0
  25. package/dist/node_modules/better-sqlite3/lib/linuxmusl-arm64.js +4 -0
  26. package/dist/node_modules/better-sqlite3/lib/linuxmusl-x64.js +4 -0
  27. package/dist/node_modules/better-sqlite3/lib/methods/aggregate.js +43 -0
  28. package/dist/node_modules/better-sqlite3/lib/methods/backup.js +67 -0
  29. package/dist/node_modules/better-sqlite3/lib/methods/explain.js +9 -0
  30. package/dist/node_modules/better-sqlite3/lib/methods/function.js +31 -0
  31. package/dist/node_modules/better-sqlite3/lib/methods/inspect.js +7 -0
  32. package/dist/node_modules/better-sqlite3/lib/methods/pragma.js +12 -0
  33. package/dist/node_modules/better-sqlite3/lib/methods/serialize.js +16 -0
  34. package/dist/node_modules/better-sqlite3/lib/methods/table.js +195 -0
  35. package/dist/node_modules/better-sqlite3/lib/methods/transaction.js +78 -0
  36. package/dist/node_modules/better-sqlite3/lib/methods/wrappers.js +54 -0
  37. package/dist/node_modules/better-sqlite3/lib/sqlite-error.js +25 -0
  38. package/dist/node_modules/better-sqlite3/lib/util.js +12 -0
  39. package/dist/node_modules/better-sqlite3/lib/win32-arm64.js +3 -0
  40. package/dist/node_modules/better-sqlite3/lib/win32-x64.js +3 -0
  41. package/dist/node_modules/better-sqlite3/package.json +67 -0
  42. package/dist/node_modules/better-sqlite3/prebuilds/darwin-arm64.node +0 -0
  43. package/dist/node_modules/better-sqlite3/prebuilds/darwin-x64.node +0 -0
  44. package/dist/node_modules/better-sqlite3/prebuilds/linux-arm64.node +0 -0
  45. package/dist/node_modules/better-sqlite3/prebuilds/linux-x64.node +0 -0
  46. package/dist/node_modules/better-sqlite3/prebuilds/linuxmusl-arm64.node +0 -0
  47. package/dist/node_modules/better-sqlite3/prebuilds/linuxmusl-x64.node +0 -0
  48. package/dist/node_modules/better-sqlite3/prebuilds/win32-arm64.node +0 -0
  49. package/dist/node_modules/better-sqlite3/prebuilds/win32-x64.node +0 -0
  50. package/dist/runtime-stage.d.ts +8 -0
  51. package/dist/runtime-stage.js +159 -0
  52. package/dist/setup.d.ts +15 -0
  53. package/dist/setup.js +735 -0
  54. package/dist/toml-patch.d.ts +10 -0
  55. package/dist/toml-patch.js +587 -0
  56. package/dist/types.d.ts +144 -0
  57. package/dist/types.js +35 -0
  58. package/dist/typescript-lib/lib.d.ts +22 -0
  59. package/dist/typescript-lib/lib.decorators.d.ts +384 -0
  60. package/dist/typescript-lib/lib.decorators.legacy.d.ts +22 -0
  61. package/dist/typescript-lib/lib.dom.asynciterable.d.ts +41 -0
  62. package/dist/typescript-lib/lib.dom.d.ts +39429 -0
  63. package/dist/typescript-lib/lib.dom.iterable.d.ts +571 -0
  64. package/dist/typescript-lib/lib.es2015.collection.d.ts +147 -0
  65. package/dist/typescript-lib/lib.es2015.core.d.ts +597 -0
  66. package/dist/typescript-lib/lib.es2015.d.ts +28 -0
  67. package/dist/typescript-lib/lib.es2015.generator.d.ts +77 -0
  68. package/dist/typescript-lib/lib.es2015.iterable.d.ts +605 -0
  69. package/dist/typescript-lib/lib.es2015.promise.d.ts +81 -0
  70. package/dist/typescript-lib/lib.es2015.proxy.d.ts +128 -0
  71. package/dist/typescript-lib/lib.es2015.reflect.d.ts +144 -0
  72. package/dist/typescript-lib/lib.es2015.symbol.d.ts +46 -0
  73. package/dist/typescript-lib/lib.es2015.symbol.wellknown.d.ts +326 -0
  74. package/dist/typescript-lib/lib.es2016.array.include.d.ts +116 -0
  75. package/dist/typescript-lib/lib.es2016.d.ts +21 -0
  76. package/dist/typescript-lib/lib.es2016.full.d.ts +23 -0
  77. package/dist/typescript-lib/lib.es2016.intl.d.ts +31 -0
  78. package/dist/typescript-lib/lib.es2017.arraybuffer.d.ts +21 -0
  79. package/dist/typescript-lib/lib.es2017.d.ts +26 -0
  80. package/dist/typescript-lib/lib.es2017.date.d.ts +31 -0
  81. package/dist/typescript-lib/lib.es2017.full.d.ts +23 -0
  82. package/dist/typescript-lib/lib.es2017.intl.d.ts +44 -0
  83. package/dist/typescript-lib/lib.es2017.object.d.ts +49 -0
  84. package/dist/typescript-lib/lib.es2017.sharedmemory.d.ts +135 -0
  85. package/dist/typescript-lib/lib.es2017.string.d.ts +45 -0
  86. package/dist/typescript-lib/lib.es2017.typedarrays.d.ts +53 -0
  87. package/dist/typescript-lib/lib.es2018.asyncgenerator.d.ts +77 -0
  88. package/dist/typescript-lib/lib.es2018.asynciterable.d.ts +53 -0
  89. package/dist/typescript-lib/lib.es2018.d.ts +24 -0
  90. package/dist/typescript-lib/lib.es2018.full.d.ts +24 -0
  91. package/dist/typescript-lib/lib.es2018.intl.d.ts +83 -0
  92. package/dist/typescript-lib/lib.es2018.promise.d.ts +30 -0
  93. package/dist/typescript-lib/lib.es2018.regexp.d.ts +37 -0
  94. package/dist/typescript-lib/lib.es2019.array.d.ts +79 -0
  95. package/dist/typescript-lib/lib.es2019.d.ts +24 -0
  96. package/dist/typescript-lib/lib.es2019.full.d.ts +24 -0
  97. package/dist/typescript-lib/lib.es2019.intl.d.ts +23 -0
  98. package/dist/typescript-lib/lib.es2019.object.d.ts +33 -0
  99. package/dist/typescript-lib/lib.es2019.string.d.ts +37 -0
  100. package/dist/typescript-lib/lib.es2019.symbol.d.ts +24 -0
  101. package/dist/typescript-lib/lib.es2020.bigint.d.ts +765 -0
  102. package/dist/typescript-lib/lib.es2020.d.ts +27 -0
  103. package/dist/typescript-lib/lib.es2020.date.d.ts +42 -0
  104. package/dist/typescript-lib/lib.es2020.full.d.ts +24 -0
  105. package/dist/typescript-lib/lib.es2020.intl.d.ts +474 -0
  106. package/dist/typescript-lib/lib.es2020.number.d.ts +28 -0
  107. package/dist/typescript-lib/lib.es2020.promise.d.ts +47 -0
  108. package/dist/typescript-lib/lib.es2020.sharedmemory.d.ts +99 -0
  109. package/dist/typescript-lib/lib.es2020.string.d.ts +44 -0
  110. package/dist/typescript-lib/lib.es2020.symbol.wellknown.d.ts +41 -0
  111. package/dist/typescript-lib/lib.es2021.d.ts +23 -0
  112. package/dist/typescript-lib/lib.es2021.full.d.ts +24 -0
  113. package/dist/typescript-lib/lib.es2021.intl.d.ts +166 -0
  114. package/dist/typescript-lib/lib.es2021.promise.d.ts +48 -0
  115. package/dist/typescript-lib/lib.es2021.string.d.ts +33 -0
  116. package/dist/typescript-lib/lib.es2021.weakref.d.ts +78 -0
  117. package/dist/typescript-lib/lib.es2022.array.d.ts +121 -0
  118. package/dist/typescript-lib/lib.es2022.d.ts +25 -0
  119. package/dist/typescript-lib/lib.es2022.error.d.ts +75 -0
  120. package/dist/typescript-lib/lib.es2022.full.d.ts +24 -0
  121. package/dist/typescript-lib/lib.es2022.intl.d.ts +145 -0
  122. package/dist/typescript-lib/lib.es2022.object.d.ts +26 -0
  123. package/dist/typescript-lib/lib.es2022.regexp.d.ts +39 -0
  124. package/dist/typescript-lib/lib.es2022.string.d.ts +25 -0
  125. package/dist/typescript-lib/lib.es2023.array.d.ts +924 -0
  126. package/dist/typescript-lib/lib.es2023.collection.d.ts +21 -0
  127. package/dist/typescript-lib/lib.es2023.d.ts +22 -0
  128. package/dist/typescript-lib/lib.es2023.full.d.ts +24 -0
  129. package/dist/typescript-lib/lib.es2023.intl.d.ts +56 -0
  130. package/dist/typescript-lib/lib.es2024.arraybuffer.d.ts +65 -0
  131. package/dist/typescript-lib/lib.es2024.collection.d.ts +29 -0
  132. package/dist/typescript-lib/lib.es2024.d.ts +26 -0
  133. package/dist/typescript-lib/lib.es2024.full.d.ts +24 -0
  134. package/dist/typescript-lib/lib.es2024.object.d.ts +29 -0
  135. package/dist/typescript-lib/lib.es2024.promise.d.ts +35 -0
  136. package/dist/typescript-lib/lib.es2024.regexp.d.ts +25 -0
  137. package/dist/typescript-lib/lib.es2024.sharedmemory.d.ts +68 -0
  138. package/dist/typescript-lib/lib.es2024.string.d.ts +29 -0
  139. package/dist/typescript-lib/lib.es5.d.ts +4601 -0
  140. package/dist/typescript-lib/lib.es6.d.ts +23 -0
  141. package/dist/typescript-lib/lib.esnext.array.d.ts +35 -0
  142. package/dist/typescript-lib/lib.esnext.collection.d.ts +96 -0
  143. package/dist/typescript-lib/lib.esnext.d.ts +29 -0
  144. package/dist/typescript-lib/lib.esnext.decorators.d.ts +28 -0
  145. package/dist/typescript-lib/lib.esnext.disposable.d.ts +193 -0
  146. package/dist/typescript-lib/lib.esnext.error.d.ts +24 -0
  147. package/dist/typescript-lib/lib.esnext.float16.d.ts +445 -0
  148. package/dist/typescript-lib/lib.esnext.full.d.ts +24 -0
  149. package/dist/typescript-lib/lib.esnext.intl.d.ts +21 -0
  150. package/dist/typescript-lib/lib.esnext.iterator.d.ts +148 -0
  151. package/dist/typescript-lib/lib.esnext.promise.d.ts +34 -0
  152. package/dist/typescript-lib/lib.esnext.sharedmemory.d.ts +25 -0
  153. package/dist/typescript-lib/lib.scripthost.d.ts +322 -0
  154. package/dist/typescript-lib/lib.webworker.asynciterable.d.ts +41 -0
  155. package/dist/typescript-lib/lib.webworker.d.ts +13150 -0
  156. package/dist/typescript-lib/lib.webworker.importscripts.d.ts +23 -0
  157. package/dist/typescript-lib/lib.webworker.iterable.d.ts +340 -0
  158. package/licenses/Apache-2.0.txt +55 -0
  159. package/licenses/TypeScript-ThirdPartyNoticeText.txt +193 -0
  160. package/licenses/better-sqlite3-LICENSE.txt +21 -0
  161. package/mcp_config.json +16 -0
  162. package/native/go-worker/PROTOCOL.md +316 -0
  163. package/native/go-worker/cmd/worker/main.go +440 -0
  164. package/native/go-worker/go.mod +3 -0
  165. package/native/go-worker/internal/analyze/analyze.go +820 -0
  166. package/native/go-worker/internal/analyze/model.go +182 -0
  167. package/native/go-worker/internal/analyze/routes.go +181 -0
  168. package/native/python-worker/PROTOCOL.md +342 -0
  169. package/native/python-worker/worker.py +1190 -0
  170. package/native/roslyn-worker/Causoryn.RoslynWorker.csproj +40 -0
  171. package/native/roslyn-worker/Causoryn.RoslynWorker.deps.json +59 -0
  172. package/native/roslyn-worker/Causoryn.RoslynWorker.dll +0 -0
  173. package/native/roslyn-worker/Causoryn.RoslynWorker.runtimeconfig.json +13 -0
  174. package/native/roslyn-worker/Microsoft.CodeAnalysis.CSharp.dll +0 -0
  175. package/native/roslyn-worker/Microsoft.CodeAnalysis.dll +0 -0
  176. package/native/roslyn-worker/PROTOCOL.md +285 -0
  177. package/native/roslyn-worker/Program.cs +249 -0
  178. package/native/roslyn-worker/Protocol.cs +397 -0
  179. package/native/roslyn-worker/ReferenceResolver.cs +235 -0
  180. package/native/roslyn-worker/WorkerAnalyzer.cs +1669 -0
  181. package/native/roslyn-worker/packages.lock.json +30 -0
  182. package/native/rust-worker/Cargo.lock +107 -0
  183. package/native/rust-worker/Cargo.toml +23 -0
  184. package/native/rust-worker/PROTOCOL.md +294 -0
  185. package/native/rust-worker/src/analyzer.rs +1209 -0
  186. package/native/rust-worker/src/main.rs +127 -0
  187. package/native/rust-worker/src/protocol.rs +284 -0
  188. package/native/rust-worker/src/sha256.rs +136 -0
  189. package/package.json +71 -4
  190. package/plugin.json +17 -0
  191. package/scripts/causoryn.mjs +40 -0
  192. package/scripts/lib/node-version-guard.mjs +24 -0
  193. package/scripts/plugin-mcp-launcher.mjs +111 -0
  194. package/skills/causoryn/SKILL.md +53 -0
  195. package/skills/map-system/SKILL.md +69 -0
  196. package/skills/preflight-change/SKILL.md +38 -0
  197. package/skills/verify-change/SKILL.md +31 -0
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Pre-import Node.js runtime version guard (>= 24, K-021 / F-P2-04).
3
+ *
4
+ * Zero external dependencies: runs before loading native addons or Node 24
5
+ * APIs so unsupported runtimes exit cleanly with code 2 and a clear stderr
6
+ * diagnostic while preserving strict stdout hygiene for MCP JSON-RPC.
7
+ */
8
+
9
+ export function assertSupportedNodeVersion(
10
+ nodeVersion = process.versions.node,
11
+ minMajor = 24,
12
+ ) {
13
+ const cleaned = String(nodeVersion ?? "").trim().replace(/^v/i, "");
14
+ const majorStr = cleaned.split(".")[0] ?? "0";
15
+ const major = Number.parseInt(majorStr, 10);
16
+ const ok = Number.isFinite(major) && major >= minMajor;
17
+ if (!ok) {
18
+ process.stderr.write(
19
+ `[causoryn] Unsupported Node.js version (${cleaned || "unknown"}). Causoryn requires Node.js >= ${String(minMajor)}.\n`,
20
+ );
21
+ process.exit(2);
22
+ }
23
+ return { ok: true, major };
24
+ }
@@ -0,0 +1,111 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Plugin pazaryeri başlatıcısı (`plugin-mcp-launcher.mjs`, K-021).
4
+ *
5
+ * İç içe `npx` alt-süreci açmadan kurulu plugin dizinindeki `package.json`
6
+ * sürüm bütünlüğünü doğrular, `CAUSORYN_ASSET_ROOT` ortamını bağlar ve saf
7
+ * `stdout` disipliniyle doğrudan `dist/mcp-server.mjs` modülünü yükler.
8
+ */
9
+ import { existsSync, readFileSync } from "node:fs";
10
+ import path from "node:path";
11
+ import { fileURLToPath, pathToFileURL } from "node:url";
12
+
13
+ import { assertSupportedNodeVersion } from "./lib/node-version-guard.mjs";
14
+
15
+ assertSupportedNodeVersion();
16
+
17
+ const PKG_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
18
+ const PKG_JSON_PATH = path.join(PKG_ROOT, "package.json");
19
+ const MCP_BUNDLE_PATH = path.join(PKG_ROOT, "dist", "mcp-server.mjs");
20
+
21
+ function parseLauncherArgs(argv) {
22
+ let cliExpectedVersion;
23
+ const forwardedArgs = [];
24
+
25
+ for (let i = 0; i < argv.length; i += 1) {
26
+ const token = argv[i];
27
+ if (token === "--expected-version") {
28
+ const next = argv[i + 1];
29
+ if (next === undefined || next.trim().length === 0 || next.startsWith("-")) {
30
+ console.error("[causoryn-launcher] --expected-version bayrağı geçerli bir sürüm değeri gerektirir");
31
+ process.exit(2);
32
+ }
33
+ cliExpectedVersion = next.trim();
34
+ i += 1;
35
+ continue;
36
+ }
37
+ if (token.startsWith("--expected-version=")) {
38
+ const inlineVal = token.slice("--expected-version=".length).trim();
39
+ if (inlineVal.length === 0 || inlineVal.startsWith("-")) {
40
+ console.error("[causoryn-launcher] --expected-version bayrağı boş veya geçersiz değer alamaz");
41
+ process.exit(2);
42
+ }
43
+ cliExpectedVersion = inlineVal;
44
+ continue;
45
+ }
46
+ forwardedArgs.push(token);
47
+ }
48
+
49
+ return { cliExpectedVersion, forwardedArgs };
50
+ }
51
+
52
+ const { cliExpectedVersion, forwardedArgs } = parseLauncherArgs(process.argv.slice(2));
53
+
54
+ try {
55
+ const pkgRaw = JSON.parse(readFileSync(PKG_JSON_PATH, "utf8"));
56
+ if (
57
+ typeof pkgRaw !== "object" ||
58
+ pkgRaw === null ||
59
+ pkgRaw.name !== "causoryn" ||
60
+ typeof pkgRaw.version !== "string"
61
+ ) {
62
+ console.error(`[causoryn-launcher] geçersiz plugin package.json: ${PKG_JSON_PATH}`);
63
+ process.exit(2);
64
+ }
65
+
66
+ const envExpectedVersion = process.env["CAUSORYN_EXPECTED_VERSION"]?.trim();
67
+ if (
68
+ cliExpectedVersion !== undefined &&
69
+ envExpectedVersion !== undefined &&
70
+ envExpectedVersion.length > 0 &&
71
+ cliExpectedVersion !== envExpectedVersion
72
+ ) {
73
+ console.error(
74
+ `[causoryn-launcher] çelişen sürüm pini: --expected-version=${cliExpectedVersion}, CAUSORYN_EXPECTED_VERSION=${envExpectedVersion}`,
75
+ );
76
+ process.exit(2);
77
+ }
78
+
79
+ const expectedVersion =
80
+ cliExpectedVersion ??
81
+ (envExpectedVersion !== undefined && envExpectedVersion.length > 0
82
+ ? envExpectedVersion
83
+ : undefined);
84
+
85
+ if (expectedVersion !== undefined && pkgRaw.version !== expectedVersion) {
86
+ console.error(
87
+ `[causoryn-launcher] sürüm uyuşmazlığı: beklenen ${expectedVersion}, bulunan ${pkgRaw.version}`,
88
+ );
89
+ process.exit(2);
90
+ }
91
+ } catch (error) {
92
+ console.error(
93
+ `[causoryn-launcher] package.json okunamadı: ${error instanceof Error ? error.message : String(error)}`,
94
+ );
95
+ process.exit(2);
96
+ }
97
+
98
+ if (!existsSync(MCP_BUNDLE_PATH)) {
99
+ console.error(`[causoryn-launcher] MCP sunucu paketi bulunamadı: ${MCP_BUNDLE_PATH}`);
100
+ process.exit(2);
101
+ }
102
+
103
+ process.env["CAUSORYN_ASSET_ROOT"] ??= PKG_ROOT;
104
+
105
+ const mcpArgs =
106
+ forwardedArgs.length === 0 || forwardedArgs[0] === "mcp"
107
+ ? forwardedArgs
108
+ : ["mcp", ...forwardedArgs];
109
+ process.argv = [process.argv[0] ?? process.execPath, MCP_BUNDLE_PATH, ...mcpArgs];
110
+
111
+ await import(pathToFileURL(MCP_BUNDLE_PATH).href);
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: causoryn
3
+ description: Primary orchestration runbook for the Causoryn local, deterministic, LLM-free codebase and change intelligence MCP server across the Discover, Preflight, Edit, Verify, and Explain workflow. Use before architectural exploration, cross-file refactoring, API/contract changes, or post-edit architectural verification.
4
+ ---
5
+
6
+ # causoryn — Deterministic Codebase & Change Intelligence Workflow
7
+
8
+ Causoryn is a **local, deterministic, LLM-free** static and architectural analysis engine
9
+ served over MCP. It **never writes to your source tree** (strictly read-only workspace access;
10
+ SQLite snapshots and wiki indexes live only in the authorized Causoryn data root) and every
11
+ verified edge carries source-span provenance.
12
+
13
+ ## 5-Stage Engineering Workflow
14
+
15
+ ### 1. Readiness & Snapshot Health
16
+ 1. Call `causoryn_get_capabilities` once when uncertain about active language adapters (L0–L3), configured limits, or published tools.
17
+ 2. Call `causoryn_index_status` to check whether a published snapshot exists and whether it is `stale`.
18
+ 3. If no published snapshot exists (`INDEX_NOT_READY`) or files changed on disk, trigger `causoryn_refresh_index` and poll `causoryn_index_status` with the returned `jobId`.
19
+ 4. Call `causoryn_workspace_summary` for a fast overview of languages, entrypoints, projects, and edge resolution coverage.
20
+
21
+ ### 2. Discover (Map, Symbols, Flows & Ranked Context)
22
+ - **System hierarchy:** Call `causoryn_map_system` (`level`: `"L0"`–`"L3"`, `filters`, `maxNodes`, `cursor`) to map packages, modules, classes, and handlers before reading raw files.
23
+ - **Task-focused context:** Call `causoryn_get_agent_context` with your task query to obtain a ranked, budget-bounded context package (`exact-symbol` -> `graph-proximity` -> `contract` -> `freshness` -> `fts`).
24
+ - **Symbol inspection:** Locate candidates with `causoryn_find_symbols`, then inspect direct neighbors and incoming/outgoing edges with `causoryn_get_symbol_context`.
25
+ - **Call & business flows:** Trace bounded call chains with `causoryn_trace_execution` and cross-component contract/route flows with `causoryn_trace_business_flow`.
26
+ - **Provenance:** Inspect exact file/line evidence for any node or edge ID with `causoryn_get_evidence`.
27
+
28
+ ### 3. Preflight (Before Editing Code)
29
+ Before modifying shared symbols, endpoints, schemas, or modules:
30
+ 1. Run `causoryn_preflight_change` with `intent` plus `targetSymbols` and/or `targetFiles` (`candidateOnly` is always `true`; retain the returned `preflightId` for step 5).
31
+ 2. For deeper blast-radius inspection over reverse edges, call `causoryn_analyze_impact` (note that `certainty` and edge `resolution` remain separate — never claim 100% impact certainty).
32
+ 3. If OpenAPI, AsyncAPI, JSON Schema, SQL, or Protobuf specs are involved, evaluate compatibility with `causoryn_check_contracts` or revision drift with `causoryn_detect_contract_drift`.
33
+ 4. To inspect candidate test suites without running them, call `causoryn_derive_test_plan`.
34
+
35
+ ### 4. Edit (Using Host Tools)
36
+ Perform code changes with your host environment's own editing and test-runner tools. Causoryn itself never edits source files and never executes test commands.
37
+
38
+ ### 5. Verify & Explain (After Editing Code)
39
+ 1. Call `causoryn_verify_change` passing the `preflightId` from step 3 (or `baseSnapshot`) to compare the working tree against architecture guard rules (`architecture`), `graph-diff`, and `test-plan`.
40
+ 2. Run standalone policy checks via `causoryn_check_architecture` (`.causoryn/architecture.rules.yaml`) or git-ref diffs via `causoryn_compare_architecture` and `causoryn_architecture_timeline`.
41
+ 3. For onboarding, exports, and persistent architecture documentation:
42
+ - Structural onboarding guide: `causoryn_generate_onboarding`
43
+ - Authorized artifact export (`output.allowedOutputDirs` required): `causoryn_export_documentation`
44
+ - Living Wiki (`wiki.dataDbPath` in authorized data root): `causoryn_wiki_build`, `causoryn_wiki_get_tree`, `causoryn_wiki_get_page`, `causoryn_wiki_search`, `causoryn_wiki_get_links`, `causoryn_wiki_get_versions`, `causoryn_wiki_diff`.
45
+
46
+ ## Envelope & Error Recovery Rules
47
+
48
+ Every tool returns `{ schemaVersion, requestId, workspaceId, snapshotId, status, coverage, warnings, data, nextCursor }`:
49
+ - Always check `status` (`"ok"` | `"partial"` | `"error"`), `coverage`, and `warnings`. When `status` is `"partial"`, state explicitly that results reflect partial coverage or heuristic/gap boundaries.
50
+ - On `WORKSPACE_NOT_AUTHORIZED`: ensure the server was started in a project workspace (`--allow-cwd` / MCP `roots`) or an explicit `allowRoots` root is configured.
51
+ - On `AMBIGUOUS_SYMBOL`: disambiguate using the returned candidate IDs rather than guessing.
52
+ - On `LIMIT_EXCEEDED`: reduce `maxNodes` / `maxDepth` / `maxPaths` and paginate with `nextCursor`.
53
+ - Never fabricate symbol IDs, evidence spans, or test execution claims (`not_run` is never `"passed"`).
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: map-system
3
+ description: Route the host model to causoryn_map_system when it needs a read-only architecture map of the authorized workspace (package/module/class/function hierarchy), including correct arguments (level, filters, maxNodes, cursor), envelope reading and Causoryn error-code recovery. Use for codebase overviews, structure questions and navigational queries about the workspace.
4
+ ---
5
+
6
+ # map-system — Causoryn Architecture Map routing
7
+
8
+ Causoryn is a **local, deterministic, LLM-free** code-analysis engine. This skill only
9
+ **routes** the host model; it does not change the model or the engine. The engine never
10
+ writes to the workspace (read-only) and requires an authorized project workspace root
11
+ (`--allow-cwd` / MCP `roots` or explicit `allowRoots` configuration) before any workspace
12
+ query succeeds.
13
+
14
+ ## When to call `causoryn_map_system`
15
+
16
+ Call `causoryn_map_system` when the task needs the *shape* of the system: top-level
17
+ projects, module/file layout, class/type inventory or callable surface — not the content
18
+ of one file. Do not use it to read file bodies; use the host's own file tools for that.
19
+
20
+ ### Arguments
21
+
22
+ | Argument | Type | Notes |
23
+ | --- | --- | --- |
24
+ | `level` | `"L0"` \| `"L1"` \| `"L2"` \| `"L3"` (optional, default `"L2"`) | `L0` = Workspace / Repository / Project; `L1` = Module / Package / File / Namespace / Config; `L2` = Class / Interface / Type; `L3` = Function / Method / Handler / Endpoint. `L4` (flow maps) is **not supported in this release** and answers `INVALID_ARGUMENT` (use `causoryn_trace_execution` or `causoryn_trace_business_flow` for flow tracing). |
25
+ | `filters` | object (optional) | `filters.kinds`: array of node kinds (subset of the level's kinds, e.g. `["Class"]`); `filters.pathPrefix`: relative path prefix such as `packages/domain`. |
26
+ | `maxNodes` | positive integer (optional) | Server default cap is 250. Requesting more than the configured cap answers `LIMIT_EXCEEDED`; lower the value instead of retrying with the same one. |
27
+ | `cursor` | string (optional) | Page cursor from a previous response's `nextCursor`. Pass it back verbatim; a stale or corrupted cursor answers `INVALID_ARGUMENT`. |
28
+ | `workspaceId` | string (optional) | Omit unless targeting a specific workspace identifier reported by the server. |
29
+
30
+ Start broad (`level: "L2"`), then drill into `L3` with `filters.pathPrefix` narrowed to
31
+ the interesting directory. For symbol lookup by name use `causoryn_find_symbols`, for
32
+ project/framework coverage summaries use `causoryn_workspace_summary`, and to check
33
+ adapter levels and server limits first use `causoryn_get_capabilities`. To inspect the
34
+ provenance behind a mapped node use `causoryn_get_evidence` with the node `id`.
35
+
36
+ ## Reading the response
37
+
38
+ Every tool answers the standard Causoryn envelope:
39
+ `schemaVersion, requestId, workspaceId, snapshotId, status, coverage, warnings, data, nextCursor`.
40
+
41
+ - `status`: `"ok"` or `"partial"` (partial snapshot — treat numbers as incomplete and
42
+ mention it); `"error"` carries a structured `error.code` in the envelope body.
43
+ - `data.totalNodes` / `data.returned` / `data.truncated`: page position.
44
+ - `data.nodes[]`: `id`, `kind`, `qualifiedName`, optional `language`, optional
45
+ `location { relativePath, startLine, endLine }` — cite locations when reporting.
46
+ - `data.edges[]`: `id`, `from`, `to`, `kind`, `resolution` (only edges whose both ends
47
+ are on this page).
48
+ - `nextCursor`: non-null means more pages — call `causoryn_map_system` again with the
49
+ same `level`/`filters` plus this `cursor` until `nextCursor` is `null`.
50
+
51
+ ## Error codes and recovery
52
+
53
+ | `error.code` | Meaning | Action |
54
+ | --- | --- | --- |
55
+ | `WORKSPACE_NOT_AUTHORIZED` | No authorized root bound yet, or unknown `workspaceId`. | Stop retrying. Open a project directory (so `--allow-cwd` or MCP `roots` binds it) or declare `allowRoots` in server config, then retry. |
56
+ | `INDEX_NOT_READY` | No published snapshot yet (indexing still running or not triggered). | Check `causoryn_index_status` (or trigger `causoryn_refresh_index`), wait briefly, and retry once. |
57
+ | `INVALID_ARGUMENT` | Semantically invalid input: unsupported `L4` level, broken `cursor`, bad filter shape. | Fix the argument (use `L0`–`L3`, pass the cursor back unchanged) and retry once. |
58
+ | `LIMIT_EXCEEDED` | `maxNodes` above the server cap. | Retry with a smaller `maxNodes`. |
59
+ | `INTERNAL_ERROR` | Unexpected server failure. | Retry once; if it persists, report it with the stderr log hint — do not fabricate results. |
60
+
61
+ Envelope-level codes arrive with `isError: false` `structuredContent`; protocol/schema
62
+ rejections arrive as tool errors instead. Do not paraphrase codes — quote them verbatim.
63
+
64
+ ## Hard limits of this skill
65
+
66
+ - The engine is read-only: never promise code changes, writes or LLM summarization from
67
+ Causoryn tools.
68
+ - Never invent node ids, qualified names or evidence: only cite what an envelope
69
+ actually returned.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: preflight-change
3
+ description: Run deterministic pre-change blast-radius, contract compatibility, and candidate test-plan analysis with causoryn_preflight_change before editing shared symbols, routes, schemas, or multi-module code.
4
+ ---
5
+
6
+ # preflight-change — Pre-Change Impact, Contract & Test Plan Runbook
7
+
8
+ Use this skill **before** modifying existing functions, classes, endpoints, database schemas,
9
+ or public contracts so your edit plan is grounded in verified static graph evidence rather
10
+ than guesswork.
11
+
12
+ ## Step-by-Step Procedure
13
+
14
+ 1. **Ensure Snapshot Freshness**
15
+ - Check `causoryn_index_status`. If no snapshot is published (`INDEX_NOT_READY`) or the snapshot is stale after recent file edits, run `causoryn_refresh_index` first.
16
+ 2. **Resolve Target Identifiers**
17
+ - If you only have partial symbol names, resolve exact qualified names or node IDs via `causoryn_find_symbols` and `causoryn_get_symbol_context`.
18
+ 3. **Generate the Candidate-Only Preflight Manifest**
19
+ - Call `causoryn_preflight_change` with:
20
+ - `intent`: concise description of the planned change
21
+ - `targetSymbols` and/or `targetFiles`: workspace-relative paths or resolved symbol identifiers
22
+ - Inspect the returned manifest:
23
+ - `preflightId`: **keep this ID** in your working notes to pass into `causoryn_verify_change` after editing!
24
+ - `candidateOnly`: always `true` — preflight never edits code and never claims exhaustive runtime completeness.
25
+ - `requiresDisambiguation` / `candidateTargets`: if `true`, narrow ambiguous targets and re-run `causoryn_preflight_change` instead of guessing.
26
+ - Impact items keep `certainty` (`direct | indirect | possible`) and edge `resolution` (`verified | heuristic | unresolved`) in separate fields.
27
+ - `testPlanId`: content-addressed reference (`testplan:<sha256>`) matching `causoryn_derive_test_plan`.
28
+ - `limitations` and `warnings`: surface these explicitly when summarizing risk.
29
+ 4. **Deepen Analysis When Needed**
30
+ - Call `causoryn_analyze_impact` when you need full reverse-BFS `impactPaths` across callers and consumers.
31
+ - Call `causoryn_check_contracts` (`contracts: [{ name, base, target }]`) or `causoryn_detect_contract_drift` when modifying OpenAPI, AsyncAPI, JSON Schema, SQL, or `.proto` files (`CONTRACT_PARSE_FAILED` indicates malformed spec syntax).
32
+ - Call `causoryn_derive_test_plan` to inspect `direct`, `call-site`, and `naming` test candidates plus `missingCoverageCandidates`.
33
+ - Call `causoryn_get_evidence` to inspect exact source lines backing critical dependency edges.
34
+
35
+ ## Strict Honesty Boundaries
36
+
37
+ - **Read-only guarantee:** `causoryn_preflight_change` and `causoryn_derive_test_plan` never modify files and never execute tests.
38
+ - **No 100% impact claims:** Static analysis cannot observe dynamic reflection or unindexed external consumers; always preserve `heuristic` / `possible` / `unknown` qualifiers verbatim.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: verify-change
3
+ description: Verify working-tree code modifications after editing by running causoryn_verify_change, causoryn_check_architecture, and contract drift checks with byte-deterministic, evidence-backed reporting.
4
+ ---
5
+
6
+ # verify-change — Post-Change Architectural & Contract Verification Runbook
7
+
8
+ Use this skill **after** making working-tree edits (and running relevant tests in the host
9
+ terminal) to verify architectural boundaries, graph diffs, and test-plan coverage against
10
+ the pre-change baseline.
11
+
12
+ ## Step-by-Step Procedure
13
+
14
+ 1. **Run `causoryn_verify_change`**
15
+ - Pass `preflightId` (from an earlier `causoryn_preflight_change` call in the same MCP server session) or an explicit `baseSnapshot` ID. At least one is required; if both are supplied they must match the same base snapshot.
16
+ - If you executed tests via host tools and have a verifiable evidence reference (`evidenceRef`), supply host test observations honestly; otherwise leave test execution status at its default `not_run`.
17
+ 2. **Interpret the Verification Verdict & Checks**
18
+ - Deterministic verdicts: `no_findings` | `review_required` | `blocking_findings` | `inconclusive`.
19
+ - Four check surfaces:
20
+ - `architecture`: evaluates `.causoryn/architecture.rules.yaml` (`no-cycles` SCC + `forbidden-dependency` globs). If no policy file exists in the workspace, it reports `not_evaluated` rather than failing.
21
+ - `contracts`: `causoryn_verify_change` reports `not_evaluated` when no spec-pair inputs exist on this surface; run `causoryn_check_contracts` or `causoryn_detect_contract_drift` directly whenever API/schema specs changed!
22
+ - `graph-diff`: added, removed, and modified symbols/edges between the base snapshot and the working-tree projection.
23
+ - `test-plan`: maps candidate tests from `causoryn_derive_test_plan` with honest run status (`not_run` vs evidence-backed `observed`).
24
+ 3. **Follow-Up Diagnostics**
25
+ - If `architecture` reports rule violations or `POLICY_INVALID`, call `causoryn_check_architecture` directly and inspect offending edges with `causoryn_get_evidence`.
26
+ - To compare committed git revisions (`baseRef` vs `targetRef`), call `causoryn_compare_architecture` (`INVALID_REVISION` indicates an unresolvable ref or missing snapshot blob).
27
+
28
+ ## Strict Honesty Boundaries
29
+
30
+ - **Writes no code, runs no tests:** `causoryn_verify_change` only verifies static projections; it never alters the working tree and never executes a test runner.
31
+ - **`no_findings` is not a blanket guarantee:** Always report `incompleteChecks`, `disclaimers`, and `warnings` alongside the verdict, and never claim tests `"passed"` when their status is `not_run`.