@kaddo/cli 3.114.0 → 3.116.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 (34) hide show
  1. package/dist/admin-dist/assets/{architectureDiagram-3BPJPVTR-eYr0CQIi.js → architectureDiagram-3BPJPVTR-DP6srEcc.js} +1 -1
  2. package/dist/admin-dist/assets/{chunk-727SXJPM-DrnpGnui.js → chunk-727SXJPM-DnQC9siX.js} +1 -1
  3. package/dist/admin-dist/assets/{chunk-AQP2D5EJ-CEGy8SpK.js → chunk-AQP2D5EJ-BpyJpCJ-.js} +1 -1
  4. package/dist/admin-dist/assets/{classDiagram-v2-Q7XG4LA2-DA001cdf.js → classDiagram-4FO5ZUOK-CGoPFtaR.js} +1 -1
  5. package/dist/admin-dist/assets/{classDiagram-4FO5ZUOK-DA001cdf.js → classDiagram-v2-Q7XG4LA2-CGoPFtaR.js} +1 -1
  6. package/dist/admin-dist/assets/{dagre-BM42HDAG-BRJ0nXQb.js → dagre-BM42HDAG-CRZz5h6U.js} +1 -1
  7. package/dist/admin-dist/assets/{diagram-2AECGRRQ-xd6Livp4.js → diagram-2AECGRRQ-2IUax-pn.js} +1 -1
  8. package/dist/admin-dist/assets/{diagram-5GNKFQAL-o9d2ix0l.js → diagram-5GNKFQAL-Dbar3g31.js} +1 -1
  9. package/dist/admin-dist/assets/{diagram-LMA3HP47-DcnWjF35.js → diagram-LMA3HP47-CDpppwwZ.js} +1 -1
  10. package/dist/admin-dist/assets/{diagram-OG6HWLK6-Cw5XQicu.js → diagram-OG6HWLK6-CxJNrhOa.js} +1 -1
  11. package/dist/admin-dist/assets/{erDiagram-TEJ5UH35-DRxLZQPp.js → erDiagram-TEJ5UH35-CqGkUDrY.js} +1 -1
  12. package/dist/admin-dist/assets/{flowDiagram-I6XJVG4X-Pb5MivY8.js → flowDiagram-I6XJVG4X-Dj-jj3Xs.js} +1 -1
  13. package/dist/admin-dist/assets/{ganttDiagram-6RSMTGT7-Cm7UHfMW.js → ganttDiagram-6RSMTGT7-BsslcFFi.js} +1 -1
  14. package/dist/admin-dist/assets/{index-M8TdCEku.js → index-DVXcBuvj.js} +6 -6
  15. package/dist/admin-dist/assets/{infoDiagram-5YYISTIA-Bwq-Ae1z.js → infoDiagram-5YYISTIA-Bm8y-W5K.js} +1 -1
  16. package/dist/admin-dist/assets/{ishikawaDiagram-YF4QCWOH-CN8u3lkW.js → ishikawaDiagram-YF4QCWOH-B1q-JfoS.js} +1 -1
  17. package/dist/admin-dist/assets/{kanban-definition-UN3LZRKU-DFp13Kfy.js → kanban-definition-UN3LZRKU-iEF70R2u.js} +1 -1
  18. package/dist/admin-dist/assets/{linear-sB0c581b.js → linear-Cp_M7piX.js} +1 -1
  19. package/dist/admin-dist/assets/{mindmap-definition-RKZ34NQL-Ds_AH-UF.js → mindmap-definition-RKZ34NQL-IS3zSxy4.js} +1 -1
  20. package/dist/admin-dist/assets/{pieDiagram-4H26LBE5-CT6aVbJD.js → pieDiagram-4H26LBE5-FRW3jbwa.js} +1 -1
  21. package/dist/admin-dist/assets/{quadrantDiagram-W4KKPZXB-QacGkpjr.js → quadrantDiagram-W4KKPZXB-BWvrA0U2.js} +1 -1
  22. package/dist/admin-dist/assets/{requirementDiagram-4Y6WPE33-UjzvMQAY.js → requirementDiagram-4Y6WPE33-BDo5C4-W.js} +1 -1
  23. package/dist/admin-dist/assets/{sequenceDiagram-3UESZ5HK-Drii4Z9H.js → sequenceDiagram-3UESZ5HK-BqkNcdXk.js} +1 -1
  24. package/dist/admin-dist/assets/{stateDiagram-AJRCARHV-Cu5M1jgm.js → stateDiagram-AJRCARHV-BPRhmY_L.js} +1 -1
  25. package/dist/admin-dist/assets/{stateDiagram-v2-BHNVJYJU-Dnkqr8wc.js → stateDiagram-v2-BHNVJYJU-DqC9KnuP.js} +1 -1
  26. package/dist/admin-dist/assets/{timeline-definition-PNZ67QCA-BmCLa1NQ.js → timeline-definition-PNZ67QCA-BKU6Xg5t.js} +1 -1
  27. package/dist/admin-dist/assets/{vennDiagram-CIIHVFJN-BhHRtC9_.js → vennDiagram-CIIHVFJN-BRePJms1.js} +1 -1
  28. package/dist/admin-dist/assets/{wardleyDiagram-YWT4CUSO-BzHZzKlk.js → wardleyDiagram-YWT4CUSO-BZP5Do-p.js} +1 -1
  29. package/dist/admin-dist/assets/{xychartDiagram-2RQKCTM6-uU2Utuv0.js → xychartDiagram-2RQKCTM6-Cf0SjuRr.js} +1 -1
  30. package/dist/admin-dist/index.html +1 -1
  31. package/dist/admin-server/index.js +90 -0
  32. package/dist/core.js +482 -92
  33. package/dist/index.js +664 -115
  34. package/package.json +1 -1
package/dist/core.js CHANGED
@@ -130,8 +130,8 @@ function loadConfig(dir) {
130
130
  const parsed = configSchema.safeParse(raw ?? {});
131
131
  if (!parsed.success) {
132
132
  const issues = parsed.error.issues.map((i) => {
133
- const path4 = i.path.join(".");
134
- return path4 ? ` - ${path4}: ${i.message}` : ` - ${i.message}`;
133
+ const path5 = i.path.join(".");
134
+ return path5 ? ` - ${path5}: ${i.message}` : ` - ${i.message}`;
135
135
  }).join("\n");
136
136
  throw new ConfigError(`Invalid .kaddo/config.yml:
137
137
  ${issues}`);
@@ -366,11 +366,11 @@ function moduleArtifactCoverage(dir, id) {
366
366
  };
367
367
  }
368
368
  function loadMappedModules(dir) {
369
- const path4 = join(dir, DESCRIPTOR_PATH);
370
- if (!exists(path4)) return [];
369
+ const path5 = join(dir, DESCRIPTOR_PATH);
370
+ if (!exists(path5)) return [];
371
371
  let parsed;
372
372
  try {
373
- parsed = parseYaml3(readFile(path4));
373
+ parsed = parseYaml3(readFile(path5));
374
374
  } catch {
375
375
  return [];
376
376
  }
@@ -1601,7 +1601,7 @@ function sectionParagraph(md, title) {
1601
1601
  }
1602
1602
  return "";
1603
1603
  }
1604
- function parseCapsule(id, path4, md) {
1604
+ function parseCapsule(id, path5, md) {
1605
1605
  const { data } = matter2(md);
1606
1606
  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
1607
1607
  let ageDays = null;
@@ -1611,7 +1611,7 @@ function parseCapsule(id, path4, md) {
1611
1611
  }
1612
1612
  return {
1613
1613
  id,
1614
- path: path4,
1614
+ path: path5,
1615
1615
  system: data.system ? String(data.system) : id,
1616
1616
  owner: data.owner ? String(data.owner) : void 0,
1617
1617
  updatedAt,
@@ -1844,8 +1844,146 @@ function suggestInitiativesForExternalItem(dir, integration, externalId) {
1844
1844
  );
1845
1845
  }
1846
1846
 
1847
+ // src/core/resources.ts
1848
+ import matter4 from "gray-matter";
1849
+ var RESOURCE_ARTIFACT_TYPE = "project-resource";
1850
+ var RESOURCE_TYPES = [
1851
+ "database",
1852
+ "cloud",
1853
+ "api",
1854
+ "queue",
1855
+ "storage",
1856
+ "repository",
1857
+ "platform",
1858
+ "service",
1859
+ "other"
1860
+ ];
1861
+ var INTERFACE_TYPES = ["cli", "mcp", "api", "sql", "sdk", "iac", "console", "other"];
1862
+ var RESOURCE_ROLES = ["affected", "implementation", "validation", "delivery"];
1863
+ function str(v) {
1864
+ return typeof v === "string" && v.trim() ? v.trim() : null;
1865
+ }
1866
+ function strArray(v) {
1867
+ if (Array.isArray(v)) return v.map((x) => String(x).trim()).filter(Boolean);
1868
+ if (typeof v === "string" && v.trim()) return [v.trim()];
1869
+ return [];
1870
+ }
1871
+ function parseInterfaces(v) {
1872
+ if (!Array.isArray(v)) return [];
1873
+ const out = [];
1874
+ for (const raw of v) {
1875
+ if (!raw || typeof raw !== "object") continue;
1876
+ const o = raw;
1877
+ const type = str(o.type);
1878
+ if (!type) continue;
1879
+ out.push({
1880
+ type,
1881
+ tool: str(o.tool),
1882
+ provider: str(o.provider),
1883
+ purpose: str(o.purpose),
1884
+ operations: strArray(o.operations),
1885
+ environments: strArray(o.environments),
1886
+ constraints: str(o.constraints)
1887
+ });
1888
+ }
1889
+ return out;
1890
+ }
1891
+ function parseBoundaries(v) {
1892
+ if (!v || typeof v !== "object" || Array.isArray(v)) return {};
1893
+ const out = {};
1894
+ for (const [env, val] of Object.entries(v)) {
1895
+ const list2 = strArray(val);
1896
+ if (list2.length > 0) out[env] = list2;
1897
+ }
1898
+ return out;
1899
+ }
1900
+ function parseAuth(v) {
1901
+ if (!v || typeof v !== "object" || Array.isArray(v)) return { mode: null, refs: [] };
1902
+ const o = v;
1903
+ const refs = strArray(o.refs).filter((r) => !r.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r));
1904
+ return { mode: str(o.mode), refs };
1905
+ }
1906
+ function parseScope(v) {
1907
+ if (!v || typeof v !== "object" || Array.isArray(v)) return null;
1908
+ const o = v;
1909
+ const type = str(o.type);
1910
+ if (!type) return null;
1911
+ return { type, module: str(o.module) };
1912
+ }
1913
+ function purposeFromBody(body) {
1914
+ const m = body.match(/^#{1,2}\s+Purpose\s*\n+([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m);
1915
+ const text2 = m ? m[1].trim() : "";
1916
+ return text2 || null;
1917
+ }
1918
+ function toDetail(filePath, relPath, raw) {
1919
+ const parsed = matter4(raw);
1920
+ const fm = parsed.data ?? {};
1921
+ const body = parsed.content.trim();
1922
+ const id = str(fm.id) ?? "";
1923
+ return {
1924
+ id,
1925
+ title: str(fm.title) ?? id,
1926
+ resourceType: str(fm.resource_type),
1927
+ provider: str(fm.provider),
1928
+ environments: strArray(fm.environments),
1929
+ scope: parseScope(fm.scope),
1930
+ modules: strArray(fm.modules),
1931
+ path: relPath,
1932
+ purpose: str(fm.purpose) ?? purposeFromBody(body),
1933
+ interfaces: parseInterfaces(fm.access_interfaces),
1934
+ boundaries: parseBoundaries(fm.access_boundaries),
1935
+ ...(() => {
1936
+ const a = parseAuth(fm.authentication);
1937
+ return { authRefs: a.refs, authMode: a.mode };
1938
+ })(),
1939
+ markdownBody: body
1940
+ };
1941
+ }
1942
+ function getResources(dir) {
1943
+ return discoverKnowledge(dir).filter((a) => a.type === RESOURCE_ARTIFACT_TYPE).map((a) => {
1944
+ const fm = a.rawFrontmatter;
1945
+ return {
1946
+ id: a.id || str(fm.id) || a.title,
1947
+ title: a.title || str(fm.title) || a.id,
1948
+ resourceType: str(fm.resource_type),
1949
+ provider: str(fm.provider),
1950
+ environments: strArray(fm.environments),
1951
+ scope: parseScope(fm.scope),
1952
+ modules: strArray(fm.modules),
1953
+ path: a.relPath
1954
+ };
1955
+ }).sort((x, y) => x.id.localeCompare(y.id));
1956
+ }
1957
+ function getResource(dir, id) {
1958
+ const match = discoverKnowledge(dir).find(
1959
+ (a) => a.type === RESOURCE_ARTIFACT_TYPE && (a.id === id || a.title === id)
1960
+ );
1961
+ if (!match) return null;
1962
+ const raw = readFile(match.filePath);
1963
+ return toDetail(match.filePath, match.relPath, raw);
1964
+ }
1965
+ function parseWorkItemResources(fm) {
1966
+ const v = fm.resources;
1967
+ if (!Array.isArray(v)) return [];
1968
+ const out = [];
1969
+ for (const raw of v) {
1970
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
1971
+ const o = raw;
1972
+ const id = str(o.id);
1973
+ if (!id) continue;
1974
+ out.push({ id, role: str(o.role) ?? "affected" });
1975
+ }
1976
+ return out;
1977
+ }
1978
+
1847
1979
  // src/core/graph.ts
1848
1980
  var KNOWLEDGE2 = "knowledge";
1981
+ var RESOURCE_ROLE_EDGE = {
1982
+ affected: "affects",
1983
+ implementation: "uses",
1984
+ validation: "validates_with",
1985
+ delivery: "delivers_through"
1986
+ };
1849
1987
  var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
1850
1988
  var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
1851
1989
  function scopeStatuses(scope) {
@@ -1882,9 +2020,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
1882
2020
  ];
1883
2021
  const presentLayers = [];
1884
2022
  for (const layer of layerDocs) {
1885
- const path4 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
1886
- if (path4) {
1887
- addNode({ id: layer.id, type: layer.type, label: layer.label, path: path4 });
2023
+ const path5 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
2024
+ if (path5) {
2025
+ addNode({ id: layer.id, type: layer.type, label: layer.label, path: path5 });
1888
2026
  presentLayers.push(layer.id);
1889
2027
  }
1890
2028
  }
@@ -1924,6 +2062,24 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
1924
2062
  if (cand.materializedAs) addEdge(candId, `wi:${cand.materializedAs}`, "materialized_as");
1925
2063
  }
1926
2064
  }
2065
+ const resourceTitleById = /* @__PURE__ */ new Map();
2066
+ for (const r of getResources(dir)) {
2067
+ resourceTitleById.set(r.id, r.title);
2068
+ const resId = `resource:${r.id}`;
2069
+ addNode({
2070
+ id: resId,
2071
+ type: "project-resource",
2072
+ label: r.title ? `${r.id} ${r.title}`.trim() : r.id,
2073
+ path: r.path
2074
+ });
2075
+ const depModules = new Set(r.modules);
2076
+ if (r.scope?.type === "module" && r.scope.module) depModules.add(r.scope.module);
2077
+ for (const mod of depModules) {
2078
+ const modId = `module:${mod}`;
2079
+ addNode({ id: modId, type: "module", label: mod });
2080
+ addEdge(modId, resId, "depends_on");
2081
+ }
2082
+ }
1927
2083
  for (const wi of selectedWIs) {
1928
2084
  const id = wi.id || wi.title;
1929
2085
  if (!id || !id.trim()) continue;
@@ -1948,6 +2104,12 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
1948
2104
  addNode({ id: capId, type: "capability", label: cap });
1949
2105
  addEdge(wiNodeId, capId, "implements");
1950
2106
  }
2107
+ for (const rel of parseWorkItemResources(wi.rawFrontmatter)) {
2108
+ const resId = `resource:${rel.id}`;
2109
+ const title = resourceTitleById.get(rel.id);
2110
+ addNode({ id: resId, type: "project-resource", label: title ? `${rel.id} ${title}`.trim() : rel.id });
2111
+ addEdge(wiNodeId, resId, RESOURCE_ROLE_EDGE[rel.role] ?? "uses");
2112
+ }
1951
2113
  for (const dec of wi.decisions) {
1952
2114
  if (!dec || !dec.trim()) continue;
1953
2115
  const adrId = `adr:${dec}`;
@@ -2222,7 +2384,7 @@ function loadGraphHints(dir) {
2222
2384
  }
2223
2385
 
2224
2386
  // src/services/installed-skills.ts
2225
- import matter4 from "gray-matter";
2387
+ import matter5 from "gray-matter";
2226
2388
  var SKILLS_DIR = join("knowledge", "skills");
2227
2389
  function discoverInstalledSkills(dir) {
2228
2390
  const base = join(dir, SKILLS_DIR);
@@ -2232,7 +2394,7 @@ function discoverInstalledSkills(dir) {
2232
2394
  const skillFile = join(base, entry, "skill.md");
2233
2395
  if (!isFile(skillFile)) continue;
2234
2396
  try {
2235
- const { data } = matter4(readFile(skillFile));
2397
+ const { data } = matter5(readFile(skillFile));
2236
2398
  if (data.type && String(data.type) !== "skill") continue;
2237
2399
  const id = String(data.id ?? entry);
2238
2400
  out.push({
@@ -3310,10 +3472,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
3310
3472
  const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
3311
3473
  const resolveAgent = (agent) => {
3312
3474
  const file = agent.endsWith(".md") ? agent : `${agent}.md`;
3313
- const path4 = agentInstallPath(file);
3314
- const installed = isFile(join(dir, path4));
3475
+ const path5 = agentInstallPath(file);
3476
+ const installed = isFile(join(dir, path5));
3315
3477
  const group = agentGroupOf(file);
3316
- return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
3478
+ return { agentPath: path5, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
3317
3479
  };
3318
3480
  const moduleRepo = isModule(config);
3319
3481
  const coreRepo = isCore(config);
@@ -3743,7 +3905,7 @@ function deriveDeliveryCompletedStatus(dir) {
3743
3905
  }
3744
3906
 
3745
3907
  // src/core/assets.ts
3746
- import matter5 from "gray-matter";
3908
+ import matter6 from "gray-matter";
3747
3909
 
3748
3910
  // src/core/version.ts
3749
3911
  import { fileURLToPath } from "url";
@@ -3898,8 +4060,13 @@ dependencies.
3898
4060
  flags, content/copy, authentication/authorization, notifications, analytics, documentation,
3899
4061
  operations/release \u2014 as affected, reviewed-not-affected, unknown, or not-applicable.
3900
4062
  4. **Module review** \u2014 for multirepo, evaluate each mapped module with the same statuses.
3901
- 5. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, unknowns
3902
- visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
4063
+ 5. **Resource review** \u2014 ask: does this change need to observe, modify, validate or deliver against a
4064
+ known external resource of the project (a Project Resource under \`knowledge/tech/resources/\` \u2014
4065
+ database, cloud, API, queue, storage\u2026)? If so, declare it in the WI front matter \`resources:\` with
4066
+ a role (\`affected\`, \`implementation\`, \`validation\`, \`delivery\`). Resources are external systems,
4067
+ distinct from \`affected_modules\` (code). Not every WI needs resources (e.g. a CSS change does not).
4068
+ 6. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, resources
4069
+ assessed, unknowns visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
3903
4070
 
3904
4071
  ## Rules
3905
4072
 
@@ -3910,6 +4077,8 @@ dependencies.
3910
4077
  - Include at least one end-to-end acceptance criterion for user-facing changes.
3911
4078
  - Do not reduce a product intent to the first technical implementation found.
3912
4079
  - Evaluate surfaces and modules before proposing files.
4080
+ - Consider Project Resources when the scope justifies it; never invent resources not backed by
4081
+ project knowledge, and keep \`resources\` (external systems) separate from \`affected_modules\` (code).
3913
4082
  - This skill refines scope and acceptance criteria but does not approve implementation readiness.
3914
4083
  Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
3915
4084
 
@@ -5061,6 +5230,16 @@ supporting notes as \`knowledge/tech/discovery/architecture-notes.md\` and decis
5061
5230
  under \`knowledge/tech/decisions/\`. Kaddo still reads the legacy root locations for backward
5062
5231
  compatibility, but new output should use \`discovery/\`.
5063
5232
 
5233
+ ## Project Resource candidates
5234
+
5235
+ When the knowledge describes an external system the project depends on (a database, cloud account,
5236
+ API, queue, storage, service\u2026), you may propose it as a **candidate** Project Resource \u2014 never create
5237
+ it silently. Discovery \u2260 creation: present candidates for human review and materialize only through
5238
+ \`kaddo_create_resource\` / \`kaddo resources create\` with explicit confirmation. Ground every
5239
+ candidate in the knowledge (no guessing from ambiguous names). Model the stable system, not its access
5240
+ interface (CLI/MCP/SQL/API are interfaces); keep \`resources\` separate from \`affected_modules\`; and
5241
+ never include secret values \u2014 only reference names.
5242
+
5064
5243
  ## Quality Checklist
5065
5244
 
5066
5245
  - Every component is backed by evidence from the context pack.
@@ -6949,7 +7128,7 @@ function canonicalSkills() {
6949
7128
  }
6950
7129
  function versionOf(content) {
6951
7130
  try {
6952
- const v = matter5(content).data.version;
7131
+ const v = matter6(content).data.version;
6953
7132
  return v === void 0 || v === null ? null : String(v);
6954
7133
  } catch {
6955
7134
  return null;
@@ -7640,7 +7819,7 @@ function buildProjectRoute(dir) {
7640
7819
  }
7641
7820
 
7642
7821
  // src/core/metadata-health.ts
7643
- import matter6 from "gray-matter";
7822
+ import matter7 from "gray-matter";
7644
7823
  var KNOWLEDGE_FILES2 = [
7645
7824
  "knowledge/business/business.md",
7646
7825
  "knowledge/product/product.md",
@@ -7660,7 +7839,7 @@ function analyzeMetadataHealth(dir) {
7660
7839
  let data;
7661
7840
  try {
7662
7841
  const raw = readFile(p);
7663
- data = matter6(raw).data;
7842
+ data = matter7(raw).data;
7664
7843
  } catch {
7665
7844
  continue;
7666
7845
  }
@@ -7692,7 +7871,7 @@ function analyzeMetadataHealth(dir) {
7692
7871
  if (isFile(p) && entry.endsWith(".md")) {
7693
7872
  try {
7694
7873
  const raw = readFile(p);
7695
- const fm = matter6(raw).data;
7874
+ const fm = matter7(raw).data;
7696
7875
  if (fm.status === "done") {
7697
7876
  const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
7698
7877
  findings.push({
@@ -8053,6 +8232,164 @@ function buildProjectExplanation(dir) {
8053
8232
  };
8054
8233
  }
8055
8234
 
8235
+ // src/core/resource-write.ts
8236
+ import fs2 from "fs";
8237
+ import path2 from "path";
8238
+ import matter8 from "gray-matter";
8239
+ var RESOURCES_DIR = "knowledge/tech/resources";
8240
+ var ResourceWriteError = class extends Error {
8241
+ constructor(code, message) {
8242
+ super(message);
8243
+ this.code = code;
8244
+ this.name = "ResourceWriteError";
8245
+ }
8246
+ code;
8247
+ };
8248
+ function slug3(s) {
8249
+ return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
8250
+ }
8251
+ function atomicWrite(filePath, content) {
8252
+ const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
8253
+ fs2.writeFileSync(tmp, content, "utf-8");
8254
+ fs2.renameSync(tmp, filePath);
8255
+ }
8256
+ function sanitizeRefs(refs) {
8257
+ if (!Array.isArray(refs)) return [];
8258
+ return refs.map((r) => String(r).trim()).filter((r) => r && !r.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r));
8259
+ }
8260
+ function allResourceArtifacts(dir) {
8261
+ return discoverKnowledge(dir).filter((a) => a.type === RESOURCE_ARTIFACT_TYPE);
8262
+ }
8263
+ function nextResourceId(dir, title, explicit) {
8264
+ const existing = new Set(allResourceArtifacts(dir).map((a) => (a.id || "").toUpperCase()));
8265
+ if (explicit && explicit.trim()) return explicit.trim();
8266
+ const base = `RES-${slug3(title) || "resource"}`;
8267
+ if (!existing.has(base.toUpperCase())) return base;
8268
+ for (let i = 2; i < 1e3; i++) {
8269
+ const candidate = `${base}-${i}`;
8270
+ if (!existing.has(candidate.toUpperCase())) return candidate;
8271
+ }
8272
+ throw new ResourceWriteError("ID_EXHAUSTED", `Could not derive a unique id for "${title}".`);
8273
+ }
8274
+ function validateResource(dir, input) {
8275
+ const findings = [];
8276
+ if (input.resourceType && !RESOURCE_TYPES.includes(input.resourceType)) {
8277
+ findings.push({ level: "warning", message: `Unknown resource_type "${input.resourceType}" (not in the known set).` });
8278
+ }
8279
+ for (const i of input.accessInterfaces ?? []) {
8280
+ if (i.type && !INTERFACE_TYPES.includes(i.type)) {
8281
+ findings.push({ level: "warning", message: `Unknown access interface type "${i.type}".` });
8282
+ }
8283
+ }
8284
+ const mapped = loadMappedModules(dir).map((m) => m.id);
8285
+ if (mapped.length > 0) {
8286
+ const refs = /* @__PURE__ */ new Set();
8287
+ if (input.scope?.type === "module" && input.scope.module) refs.add(input.scope.module);
8288
+ for (const m of input.modules ?? []) refs.add(m);
8289
+ for (const m of refs) {
8290
+ if (!mapped.includes(m)) findings.push({ level: "warning", message: `Module "${m}" is not in .kaddo/modules.yml.` });
8291
+ }
8292
+ }
8293
+ if (input.scope && input.scope.type === "module" && !input.scope.module) {
8294
+ findings.push({ level: "error", message: 'scope.type "module" requires a module id.' });
8295
+ }
8296
+ return findings;
8297
+ }
8298
+ function buildFrontmatter(id, input, base = {}) {
8299
+ const data = { ...base };
8300
+ data.type = RESOURCE_ARTIFACT_TYPE;
8301
+ data.id = id;
8302
+ if (input.title != null) data.title = input.title;
8303
+ if (input.resourceType != null) data.resource_type = input.resourceType;
8304
+ if (input.provider != null) data.provider = input.provider;
8305
+ if (input.environments != null) data.environments = input.environments;
8306
+ if (input.scope != null) data.scope = input.scope.module ? { type: input.scope.type, module: input.scope.module } : { type: input.scope.type };
8307
+ if (input.modules != null) data.modules = input.modules;
8308
+ if (input.accessInterfaces != null) data.access_interfaces = input.accessInterfaces;
8309
+ if (input.accessBoundaries != null) data.access_boundaries = input.accessBoundaries;
8310
+ if (input.authentication != null) {
8311
+ const mode = input.authentication.mode;
8312
+ const refs = sanitizeRefs(input.authentication.refs);
8313
+ data.authentication = { ...mode ? { mode } : {}, ...refs.length ? { refs } : {} };
8314
+ }
8315
+ return data;
8316
+ }
8317
+ function serialize(data, body) {
8318
+ return matter8.stringify(`
8319
+ ${body.trim()}
8320
+ `, data);
8321
+ }
8322
+ function createResource(dir, input) {
8323
+ const title = (input.title ?? "").trim();
8324
+ if (!title) throw new ResourceWriteError("INVALID_INPUT", "A resource title is required.");
8325
+ const resourceType = (input.resourceType ?? "").trim();
8326
+ if (!resourceType) throw new ResourceWriteError("INVALID_INPUT", "A resource_type is required.");
8327
+ const findings = validateResource(dir, input);
8328
+ if (findings.some((f) => f.level === "error")) {
8329
+ throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f) => f.level === "error").map((f) => f.message).join("; "));
8330
+ }
8331
+ const existing = allResourceArtifacts(dir);
8332
+ if (input.id && existing.some((a) => (a.id || "").toUpperCase() === input.id.toUpperCase())) {
8333
+ throw new ResourceWriteError("DUPLICATE", `A resource with id "${input.id}" already exists.`);
8334
+ }
8335
+ if (existing.some((a) => (a.title || "").toLowerCase() === title.toLowerCase())) {
8336
+ throw new ResourceWriteError("DUPLICATE", `A resource titled "${title}" already exists.`);
8337
+ }
8338
+ const id = nextResourceId(dir, title, input.id);
8339
+ const data = buildFrontmatter(id, input);
8340
+ const body = `# Purpose
8341
+
8342
+ ${(input.purpose ?? "").trim() || "TODO: describe what this resource is for."}`;
8343
+ const relPath = `${RESOURCES_DIR}/${slug3(title) || slug3(id)}.md`;
8344
+ const filePath = join(dir, relPath);
8345
+ if (exists(filePath)) throw new ResourceWriteError("DUPLICATE", `Resource file already exists: ${relPath}`);
8346
+ ensureDir(path2.dirname(filePath));
8347
+ atomicWrite(filePath, serialize(data, body));
8348
+ return { id, path: relPath, findings };
8349
+ }
8350
+ function updateResource(dir, id, input) {
8351
+ const match = allResourceArtifacts(dir).find((a) => a.id === id || a.title === id);
8352
+ if (!match) throw new ResourceWriteError("NOT_FOUND", `Project Resource "${id}" not found.`);
8353
+ const findings = validateResource(dir, input);
8354
+ if (findings.some((f) => f.level === "error")) {
8355
+ throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f) => f.level === "error").map((f) => f.message).join("; "));
8356
+ }
8357
+ const raw = readFile(match.filePath);
8358
+ const parsed = matter8(raw);
8359
+ const base = parsed.data ?? {};
8360
+ const data = buildFrontmatter(match.id || id, input, base);
8361
+ let body = parsed.content.trim();
8362
+ if (input.purpose != null) {
8363
+ const purpose = `# Purpose
8364
+
8365
+ ${input.purpose.trim()}`;
8366
+ body = /^#\s+Purpose/m.test(body) ? body.replace(/#\s+Purpose[\s\S]*?(?=\n#\s|\n*$)/, purpose + "\n") : `${purpose}
8367
+
8368
+ ${body}`.trim();
8369
+ }
8370
+ atomicWrite(match.filePath, serialize(data, body));
8371
+ return { id: match.id || id, path: match.relPath, findings };
8372
+ }
8373
+ function getResourceReferences(dir, id) {
8374
+ const refs = [];
8375
+ for (const wi of discoverWorkItems(dir)) {
8376
+ for (const rel of parseWorkItemResources(wi.rawFrontmatter)) {
8377
+ if (rel.id === id) refs.push({ kind: "work-item", id: wi.id || wi.title, role: rel.role, path: wi.relPath });
8378
+ }
8379
+ }
8380
+ return refs;
8381
+ }
8382
+ function deleteResource(dir, id, opts = {}) {
8383
+ const match = allResourceArtifacts(dir).find((a) => a.id === id || a.title === id);
8384
+ if (!match) throw new ResourceWriteError("NOT_FOUND", `Project Resource "${id}" not found.`);
8385
+ const references = getResourceReferences(dir, match.id || id);
8386
+ if (!opts.confirm) {
8387
+ return { deleted: false, preview: { id: match.id || id, references } };
8388
+ }
8389
+ fs2.rmSync(match.filePath, { force: true });
8390
+ return { deleted: true, path: match.relPath };
8391
+ }
8392
+
8056
8393
  // src/core/scope-coverage.ts
8057
8394
  var VALID_CONFIDENCE_LEVELS = /* @__PURE__ */ new Set(["high", "medium", "low"]);
8058
8395
  var VALID_COVERAGE_STATUSES2 = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
@@ -8289,12 +8626,12 @@ function analyzeCrossRepoEvidence(input) {
8289
8626
  }
8290
8627
 
8291
8628
  // src/core/work-items.ts
8292
- import matter7 from "gray-matter";
8629
+ import matter9 from "gray-matter";
8293
8630
 
8294
8631
  // src/core/system-topology.ts
8295
8632
  import { parse as parseYaml8, stringify as stringifyYaml4 } from "yaml";
8296
- import fs2 from "fs";
8297
- import path2 from "path";
8633
+ import fs3 from "fs";
8634
+ import path3 from "path";
8298
8635
  import crypto from "crypto";
8299
8636
  var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
8300
8637
  var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
@@ -8462,15 +8799,15 @@ function serializeTopology(entities, relationships) {
8462
8799
  };
8463
8800
  return stringifyYaml4(doc);
8464
8801
  }
8465
- function atomicWrite(filePath, content) {
8466
- fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
8802
+ function atomicWrite2(filePath, content) {
8803
+ fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
8467
8804
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
8468
- fs2.writeFileSync(tmp, content, "utf-8");
8805
+ fs3.writeFileSync(tmp, content, "utf-8");
8469
8806
  try {
8470
- fs2.renameSync(tmp, filePath);
8807
+ fs3.renameSync(tmp, filePath);
8471
8808
  } catch (err) {
8472
8809
  try {
8473
- fs2.rmSync(tmp, { force: true });
8810
+ fs3.rmSync(tmp, { force: true });
8474
8811
  } catch {
8475
8812
  }
8476
8813
  throw err;
@@ -8504,7 +8841,7 @@ function applyTopologyProposal(dir, proposalYaml, expectedRevision) {
8504
8841
  const raw = serializeTopology([...entityMap.values()], [...relMap.values()]);
8505
8842
  const finalCheck = validateTopologyProposal(dir, raw);
8506
8843
  if (!finalCheck.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The merged topology is invalid; no changes were written.");
8507
- atomicWrite(join(dir, TOPOLOGY_FILE), raw);
8844
+ atomicWrite2(join(dir, TOPOLOGY_FILE), raw);
8508
8845
  return { revision: topologyRevision(dir), entitiesNew, entitiesUpdated, relationshipsNew };
8509
8846
  }
8510
8847
  function buildTopologyEnrichmentHandoff(dir, projectName) {
@@ -8659,6 +8996,8 @@ function getWorkItem(dir, workItemId) {
8659
8996
  path: match.relPath,
8660
8997
  // Faithful source of truth: the artifact body already read above, not reconstructed (WI-025).
8661
8998
  markdownBody: body.trim(),
8999
+ // External systems this WI relates to (WI-030), separate from affectedModules (code).
9000
+ resources: parseWorkItemResources(fm),
8662
9001
  ...parseSystemImpact(dir, fm)
8663
9002
  };
8664
9003
  return { ...detail, refinement: computeRefinementStatus(detail) };
@@ -8667,8 +9006,8 @@ function parseGraphReason(v) {
8667
9006
  if (!v || typeof v !== "object") return null;
8668
9007
  const o = v;
8669
9008
  const relationship = typeof o.relationship === "string" && o.relationship.trim() ? o.relationship.trim() : null;
8670
- const path4 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
8671
- return relationship || path4.length ? { relationship, path: path4 } : null;
9009
+ const path5 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
9010
+ return relationship || path5.length ? { relationship, path: path5 } : null;
8672
9011
  }
8673
9012
  function parseExplain(o) {
8674
9013
  const refs = Array.isArray(o.evidence) ? o.evidence : Array.isArray(o.evidence_refs) ? o.evidence_refs : [];
@@ -8723,7 +9062,7 @@ function parseOriginalSnapshot(fm) {
8723
9062
  function readBody(filePath) {
8724
9063
  try {
8725
9064
  const raw = readFile(filePath);
8726
- return matter7(raw).content;
9065
+ return matter9(raw).content;
8727
9066
  } catch {
8728
9067
  return "";
8729
9068
  }
@@ -8887,10 +9226,10 @@ function parseRelatedKnowledge(fm, knowledgeById) {
8887
9226
  }
8888
9227
 
8889
9228
  // src/core/work-item-write.ts
8890
- import fs3 from "fs";
8891
- import path3 from "path";
9229
+ import fs4 from "fs";
9230
+ import path4 from "path";
8892
9231
  import crypto2 from "crypto";
8893
- import matter8 from "gray-matter";
9232
+ import matter10 from "gray-matter";
8894
9233
 
8895
9234
  // src/core/knowledge-levels.ts
8896
9235
  var WORK_ITEM_TYPES2 = ["feature", "bugfix", "hotfix", "spike", "chore"];
@@ -9102,7 +9441,7 @@ function nextWorkItemId(dir) {
9102
9441
  let max = 0;
9103
9442
  const walk = (d) => {
9104
9443
  if (!exists(d)) return;
9105
- for (const entry of fs3.readdirSync(d)) {
9444
+ for (const entry of fs4.readdirSync(d)) {
9106
9445
  const full = join(d, entry);
9107
9446
  if (isFile(full)) {
9108
9447
  const m = entry.match(/WI-(\d+)/);
@@ -9115,15 +9454,15 @@ function nextWorkItemId(dir) {
9115
9454
  walk(wiDir);
9116
9455
  return `WI-${String(max + 1).padStart(3, "0")}`;
9117
9456
  }
9118
- function atomicWrite2(filePath, content) {
9119
- fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
9457
+ function atomicWrite3(filePath, content) {
9458
+ fs4.mkdirSync(path4.dirname(filePath), { recursive: true });
9120
9459
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
9121
- fs3.writeFileSync(tmp, content, "utf-8");
9460
+ fs4.writeFileSync(tmp, content, "utf-8");
9122
9461
  try {
9123
- fs3.renameSync(tmp, filePath);
9462
+ fs4.renameSync(tmp, filePath);
9124
9463
  } catch (err) {
9125
9464
  try {
9126
- fs3.rmSync(tmp, { force: true });
9465
+ fs4.rmSync(tmp, { force: true });
9127
9466
  } catch {
9128
9467
  }
9129
9468
  throw err;
@@ -9296,8 +9635,8 @@ function applyFrontmatter(data, input) {
9296
9635
  else delete next.related_knowledge;
9297
9636
  return next;
9298
9637
  }
9299
- function serialize(data, body) {
9300
- return matter8.stringify(`
9638
+ function serialize2(data, body) {
9639
+ return matter10.stringify(`
9301
9640
  ${body.trim()}
9302
9641
  `, data);
9303
9642
  }
@@ -9356,7 +9695,7 @@ function toInput(data, content) {
9356
9695
  function getWorkItemForEdit(dir, id) {
9357
9696
  const { filePath, relPath } = findArtifact(dir, id);
9358
9697
  const raw = readFile(filePath);
9359
- const { data, content } = matter8(raw);
9698
+ const { data, content } = matter10(raw);
9360
9699
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9361
9700
  const input = toInput(data, content);
9362
9701
  const editable = EDITABLE_STATES.includes(status);
@@ -9434,8 +9773,8 @@ function createWorkItem(dir, opts) {
9434
9773
  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify2(title)}.md`;
9435
9774
  const filePath = join(dir, relPath);
9436
9775
  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
9437
- const raw = serialize(data, body);
9438
- atomicWrite2(filePath, raw);
9776
+ const raw = serialize2(data, body);
9777
+ atomicWrite3(filePath, raw);
9439
9778
  return { id, path: relPath, revision: revisionOf(raw) };
9440
9779
  }
9441
9780
  function validateInput(input) {
@@ -9449,21 +9788,21 @@ function updateWorkItem(dir, id, input, expectedRevision) {
9449
9788
  if (revisionOf(raw) !== expectedRevision) {
9450
9789
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before saving.");
9451
9790
  }
9452
- const { data, content } = matter8(raw);
9791
+ const { data, content } = matter10(raw);
9453
9792
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9454
9793
  if (!EDITABLE_STATES.includes(status)) {
9455
9794
  throw new WorkItemWriteError("WORK_ITEM_NOT_EDITABLE", `A ${status} Work Item cannot be edited. Reopen it as Draft first.`);
9456
9795
  }
9457
9796
  const nextData = applyFrontmatter(data, input);
9458
9797
  const nextBody = mergeBody(content, input);
9459
- const nextRaw = serialize(nextData, nextBody);
9460
- atomicWrite2(filePath, nextRaw);
9798
+ const nextRaw = serialize2(nextData, nextBody);
9799
+ atomicWrite3(filePath, nextRaw);
9461
9800
  return { revision: revisionOf(nextRaw), path: relPath };
9462
9801
  }
9463
9802
  function validateWorkItem(dir, id) {
9464
9803
  const { filePath } = findArtifact(dir, id);
9465
9804
  const raw = readFile(filePath);
9466
- const { data, content } = matter8(raw);
9805
+ const { data, content } = matter10(raw);
9467
9806
  const input = toInput(data, content);
9468
9807
  const findings = [];
9469
9808
  const modules = validModuleIds(dir);
@@ -9516,7 +9855,7 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
9516
9855
  if (revisionOf(raw) !== expectedRevision) {
9517
9856
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
9518
9857
  }
9519
- const { data, content } = matter8(raw);
9858
+ const { data, content } = matter10(raw);
9520
9859
  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9521
9860
  if (!(ALLOWED[from] ?? []).includes(to)) {
9522
9861
  throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
@@ -9526,14 +9865,14 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
9526
9865
  if (!canMarkReady) throw new WorkItemWriteError("INVALID_TRANSITION", "This Work Item has blocking issues and cannot be marked Ready.");
9527
9866
  }
9528
9867
  const nextData = { ...data, status: to };
9529
- const nextRaw = serialize(nextData, content);
9530
- const filename = path3.basename(filePath);
9868
+ const nextRaw = serialize2(nextData, content);
9869
+ const filename = path4.basename(filePath);
9531
9870
  const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
9532
9871
  const targetPath = join(dir, targetRel);
9533
- atomicWrite2(targetPath, nextRaw);
9534
- if (path3.resolve(targetPath) !== path3.resolve(filePath)) {
9872
+ atomicWrite3(targetPath, nextRaw);
9873
+ if (path4.resolve(targetPath) !== path4.resolve(filePath)) {
9535
9874
  try {
9536
- fs3.rmSync(filePath, { force: true });
9875
+ fs4.rmSync(filePath, { force: true });
9537
9876
  } catch {
9538
9877
  }
9539
9878
  }
@@ -9782,16 +10121,16 @@ function findSystemPaths(dir, source, target, opts = {}) {
9782
10121
  out.get(r.source).push(r.target);
9783
10122
  }
9784
10123
  const paths = [];
9785
- const walk = (node, path4) => {
10124
+ const walk = (node, path5) => {
9786
10125
  if (paths.length >= 20) return;
9787
- if (node === target && path4.length > 1) {
9788
- paths.push([...path4]);
10126
+ if (node === target && path5.length > 1) {
10127
+ paths.push([...path5]);
9789
10128
  return;
9790
10129
  }
9791
- if (path4.length > maxDepth) return;
10130
+ if (path5.length > maxDepth) return;
9792
10131
  for (const nxt of out.get(node) ?? []) {
9793
- if (path4.includes(nxt)) continue;
9794
- walk(nxt, [...path4, nxt]);
10132
+ if (path5.includes(nxt)) continue;
10133
+ walk(nxt, [...path5, nxt]);
9795
10134
  }
9796
10135
  };
9797
10136
  walk(source, [source]);
@@ -9816,14 +10155,14 @@ function getImpactCandidates(dir, seedIds, opts = {}) {
9816
10155
  existing.reason.push(reason);
9817
10156
  continue;
9818
10157
  }
9819
- const path4 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
10158
+ const path5 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
9820
10159
  candidates.set(n.id, {
9821
10160
  nodeId: n.id,
9822
10161
  label: n.label,
9823
10162
  kind: n.type,
9824
10163
  ...n.moduleId ? { moduleId: n.moduleId } : {},
9825
10164
  reason: [reason],
9826
- ...path4 ? { graphPath: path4.map((id) => byId.get(id)?.label ?? id) } : {},
10165
+ ...path5 ? { graphPath: path5.map((id) => byId.get(id)?.label ?? id) } : {},
9827
10166
  ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
9828
10167
  ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
9829
10168
  status: "candidate",
@@ -10013,6 +10352,7 @@ function buildImplementationHandoff(dir, workItemId) {
10013
10352
  const affectedModules = match.affectedModules;
10014
10353
  const domains = match.domains;
10015
10354
  const scopeConfidence = match.scopeConfidence;
10355
+ const wiResources = parseWorkItemResources(match.rawFrontmatter);
10016
10356
  const lines = [
10017
10357
  `Implement Work Item ${wiId} \u2014 "${wiTitle}" \u2014 in project "${projectName}" using Kaddo.`,
10018
10358
  "",
@@ -10102,6 +10442,41 @@ function buildImplementationHandoff(dir, workItemId) {
10102
10442
  "Do not copy all legacy knowledge \u2014 assemble proportionally to scope."
10103
10443
  );
10104
10444
  }
10445
+ if (wiResources.length > 0) {
10446
+ lines.push(
10447
+ "",
10448
+ "--- Relevant Resources ---",
10449
+ "",
10450
+ "This Work Item relates to external project resources. The handoff INFORMS you about them \u2014 it",
10451
+ "never connects to them, runs any interface, or reveals credential values. Respect each boundary."
10452
+ );
10453
+ for (const rel of wiResources) {
10454
+ const res = getResource(dir, rel.id);
10455
+ if (!res) {
10456
+ lines.push("", `- ${rel.id} (role: ${rel.role}) \u2014 definition not found under knowledge/tech/resources/.`);
10457
+ continue;
10458
+ }
10459
+ lines.push("", `- ${res.id} \u2014 ${res.title} (role: ${rel.role})`);
10460
+ if (res.resourceType || res.provider) {
10461
+ lines.push(` type: ${res.resourceType ?? "\u2014"}${res.provider ? ` \xB7 provider: ${res.provider}` : ""}`);
10462
+ }
10463
+ if (res.purpose) lines.push(` purpose: ${res.purpose}`);
10464
+ if (res.environments.length > 0) lines.push(` environments: ${res.environments.join(", ")}`);
10465
+ if (res.interfaces.length > 0) {
10466
+ const ifaces = res.interfaces.map((i) => i.tool || i.provider ? `${i.type} (${i.tool ?? i.provider})` : i.type);
10467
+ lines.push(` interfaces: ${ifaces.join(", ")}`);
10468
+ }
10469
+ for (const [env, ops] of Object.entries(res.boundaries)) {
10470
+ lines.push(` boundary (${env}): ${ops.join(", ")}`);
10471
+ }
10472
+ if (res.authRefs.length > 0) lines.push(` auth references (names only): ${res.authRefs.join(", ")}`);
10473
+ }
10474
+ lines.push(
10475
+ "",
10476
+ "Treat these as knowledge, not availability: an interface being declared does not mean it is",
10477
+ "installed or connected. Do not execute any interface or migration without explicit human confirmation."
10478
+ );
10479
+ }
10105
10480
  lines.push(
10106
10481
  "",
10107
10482
  "--- Implementation Plan ---",
@@ -10122,6 +10497,7 @@ function buildImplementationHandoff(dir, workItemId) {
10122
10497
  projectName,
10123
10498
  lifecycle,
10124
10499
  affectedModules,
10500
+ resources: wiResources,
10125
10501
  domains,
10126
10502
  scopeConfidence,
10127
10503
  hasUnmaterializedDecisions: unmaterialized,
@@ -10357,8 +10733,8 @@ function deriveImplementationStatus(repos) {
10357
10733
 
10358
10734
  // src/core/work-item-import.ts
10359
10735
  import crypto3 from "crypto";
10360
- import fs4 from "fs";
10361
- import matter9 from "gray-matter";
10736
+ import fs5 from "fs";
10737
+ import matter11 from "gray-matter";
10362
10738
  var MAX_INPUT_BYTES = 102400;
10363
10739
  var LIFECYCLE_FIELDS = /* @__PURE__ */ new Set([
10364
10740
  "id",
@@ -10380,7 +10756,7 @@ function detectFormat(raw) {
10380
10756
  if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
10381
10757
  if (trimmed.startsWith("---")) {
10382
10758
  try {
10383
- const { data } = matter9(trimmed);
10759
+ const { data } = matter11(trimmed);
10384
10760
  if (data && typeof data === "object" && Object.keys(data).length > 0) {
10385
10761
  const d = data;
10386
10762
  if (d.type === "work-item" || d.id && typeof d.id === "string" && /^WI-\d+/.test(d.id)) {
@@ -10402,7 +10778,7 @@ function parseContent(raw) {
10402
10778
  let bodyText = trimmed;
10403
10779
  if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
10404
10780
  try {
10405
- const parsed = matter9(trimmed);
10781
+ const parsed = matter11(trimmed);
10406
10782
  frontmatterFields = parsed.data ?? {};
10407
10783
  bodyText = parsed.content.trim();
10408
10784
  } catch {
@@ -10499,7 +10875,7 @@ function findDuplicateByHash(dir, hash) {
10499
10875
  const raw = readFile(item.filePath);
10500
10876
  if (!raw) continue;
10501
10877
  try {
10502
- const { data } = matter9(raw);
10878
+ const { data } = matter11(raw);
10503
10879
  const source = data?.source;
10504
10880
  if (source && typeof source === "object" && !Array.isArray(source)) {
10505
10881
  const s = source;
@@ -10566,7 +10942,7 @@ function importWorkItem(dir, opts) {
10566
10942
  };
10567
10943
  }
10568
10944
  if (opts.onConflict === "replace") {
10569
- fs4.rmSync(existing.filePath, { force: true });
10945
+ fs5.rmSync(existing.filePath, { force: true });
10570
10946
  replacedWorkItem = existing.workItemId;
10571
10947
  }
10572
10948
  }
@@ -10608,7 +10984,7 @@ var ImportError = class extends Error {
10608
10984
  };
10609
10985
 
10610
10986
  // src/services/integrations.ts
10611
- import matter10 from "gray-matter";
10987
+ import matter12 from "gray-matter";
10612
10988
  import { parse as parseYaml9, stringify as stringifyYaml5 } from "yaml";
10613
10989
 
10614
10990
  // ../integrations/src/errors.ts
@@ -11377,8 +11753,8 @@ async function handleJiraResponse(res) {
11377
11753
  }
11378
11754
  return await res.json();
11379
11755
  }
11380
- async function jiraFetch(baseUrl, path4, auth, timeoutMs, params) {
11381
- const url = new URL(path4, baseUrl + "/");
11756
+ async function jiraFetch(baseUrl, path5, auth, timeoutMs, params) {
11757
+ const url = new URL(path5, baseUrl + "/");
11382
11758
  if (params) for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
11383
11759
  const controller = new AbortController();
11384
11760
  const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -11396,8 +11772,8 @@ async function jiraFetch(baseUrl, path4, auth, timeoutMs, params) {
11396
11772
  clearTimeout(timer);
11397
11773
  }
11398
11774
  }
11399
- async function jiraPost(baseUrl, path4, auth, timeoutMs, body) {
11400
- const url = new URL(path4, baseUrl + "/");
11775
+ async function jiraPost(baseUrl, path5, auth, timeoutMs, body) {
11776
+ const url = new URL(path5, baseUrl + "/");
11401
11777
  const controller = new AbortController();
11402
11778
  const timer = setTimeout(() => controller.abort(), timeoutMs);
11403
11779
  try {
@@ -11950,7 +12326,7 @@ function findLinkedWorkItem(dir, integrationId, externalId) {
11950
12326
  for (const art of discoverWorkItems(dir)) {
11951
12327
  let data;
11952
12328
  try {
11953
- data = matter10(readFile(art.filePath)).data;
12329
+ data = matter12(readFile(art.filePath)).data;
11954
12330
  } catch {
11955
12331
  continue;
11956
12332
  }
@@ -11966,7 +12342,7 @@ function buildImportIndex(dir) {
11966
12342
  for (const art of discoverWorkItems(dir)) {
11967
12343
  let data;
11968
12344
  try {
11969
- data = matter10(readFile(art.filePath)).data;
12345
+ data = matter12(readFile(art.filePath)).data;
11970
12346
  } catch {
11971
12347
  continue;
11972
12348
  }
@@ -12142,7 +12518,7 @@ function getStatus(dir) {
12142
12518
  }
12143
12519
 
12144
12520
  // src/core/initiative-write.ts
12145
- import matter11 from "gray-matter";
12521
+ import matter13 from "gray-matter";
12146
12522
  var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
12147
12523
  var DRAFT_DIR = `${WORK_ITEMS_DIR2}/draft`;
12148
12524
  var ROADMAP_PATH2 = "knowledge/delivery/roadmap.md";
@@ -12255,7 +12631,7 @@ function buildInitiativeContent(id, input) {
12255
12631
  if (input.priority) data.priority = input.priority;
12256
12632
  if (input.source) data.source = input.source;
12257
12633
  if (input.sourceId) data.source_id = input.sourceId;
12258
- return matter11.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12634
+ return matter13.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12259
12635
  }
12260
12636
  function createInitiative(dir, input) {
12261
12637
  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -12279,10 +12655,10 @@ function transitionInitiative(dir, id, to) {
12279
12655
  throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
12280
12656
  }
12281
12657
  const raw = readFile(ini.filePath);
12282
- const { data, content } = matter11(raw, {});
12658
+ const { data, content } = matter13(raw, {});
12283
12659
  data.status = to;
12284
12660
  if (to === "completed") data.completed_at = today();
12285
- const newContent = matter11.stringify(content, data);
12661
+ const newContent = matter13.stringify(content, data);
12286
12662
  writeFile(ini.filePath, newContent);
12287
12663
  const updated = parseInitiative(dir, ini.filePath, newContent);
12288
12664
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -12292,7 +12668,7 @@ function addCandidate(dir, id, candidate) {
12292
12668
  const ini = getInitiative(dir, id);
12293
12669
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12294
12670
  const raw = readFile(ini.filePath);
12295
- const { data, content } = matter11(raw, {});
12671
+ const { data, content } = matter13(raw, {});
12296
12672
  const existing = Array.isArray(data.candidates) ? data.candidates : [];
12297
12673
  const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
12298
12674
  const normalized = normalizeCandidate(candidate, fallbackId);
@@ -12300,7 +12676,7 @@ function addCandidate(dir, id, candidate) {
12300
12676
  throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
12301
12677
  }
12302
12678
  data.candidates = [...existing, candidateToData(normalized)];
12303
- const newContent = matter11.stringify(content, data);
12679
+ const newContent = matter13.stringify(content, data);
12304
12680
  writeFile(ini.filePath, newContent);
12305
12681
  const updated = parseInitiative(dir, ini.filePath, newContent);
12306
12682
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
@@ -12310,7 +12686,7 @@ function updateInitiative(dir, id, patch) {
12310
12686
  const ini = getInitiative(dir, id);
12311
12687
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12312
12688
  const raw = readFile(ini.filePath);
12313
- const { data, content } = matter11(raw, {});
12689
+ const { data, content } = matter13(raw, {});
12314
12690
  if (patch.title !== void 0) {
12315
12691
  if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
12316
12692
  data.title = patch.title.trim();
@@ -12320,7 +12696,7 @@ function updateInitiative(dir, id, patch) {
12320
12696
  if (patch.knowledgeLevel !== void 0) data.knowledge_level = patch.knowledgeLevel;
12321
12697
  if (patch.domains !== void 0) data.domains = patch.domains;
12322
12698
  if (patch.relatedCapabilities !== void 0) data.related_capabilities = patch.relatedCapabilities;
12323
- const newContent = matter11.stringify(content, data);
12699
+ const newContent = matter13.stringify(content, data);
12324
12700
  writeFile(ini.filePath, newContent);
12325
12701
  const updated = parseInitiative(dir, ini.filePath, newContent);
12326
12702
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
@@ -12338,10 +12714,10 @@ function addExternalLink(dir, id, link) {
12338
12714
  throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
12339
12715
  }
12340
12716
  const raw = readFile(ini.filePath);
12341
- const { data, content } = matter11(raw, {});
12717
+ const { data, content } = matter13(raw, {});
12342
12718
  const existing = Array.isArray(data.external_links) ? data.external_links : [];
12343
12719
  data.external_links = [...existing, externalLinkToData(link)];
12344
- const newContent = matter11.stringify(content, data);
12720
+ const newContent = matter13.stringify(content, data);
12345
12721
  writeFile(ini.filePath, newContent);
12346
12722
  const updated = parseInitiative(dir, ini.filePath, newContent);
12347
12723
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
@@ -12410,7 +12786,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
12410
12786
  "_What did we learn? Update after completion._",
12411
12787
  ""
12412
12788
  ].join("\n");
12413
- return matter11.stringify("\n" + body, data);
12789
+ return matter13.stringify("\n" + body, data);
12414
12790
  }
12415
12791
  function materializeCandidate(dir, id, candidateId) {
12416
12792
  const ini = getInitiative(dir, id);
@@ -12427,13 +12803,13 @@ function materializeCandidate(dir, id, candidateId) {
12427
12803
  ensureDir(join(dir, DRAFT_DIR));
12428
12804
  writeFile(join(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
12429
12805
  const raw = readFile(ini.filePath);
12430
- const { data, content } = matter11(raw, {});
12806
+ const { data, content } = matter13(raw, {});
12431
12807
  const cands = Array.isArray(data.candidates) ? data.candidates : [];
12432
12808
  for (const c of cands) {
12433
12809
  if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
12434
12810
  }
12435
12811
  data.candidates = cands;
12436
- const newContent = matter11.stringify(content, data);
12812
+ const newContent = matter13.stringify(content, data);
12437
12813
  writeFile(ini.filePath, newContent);
12438
12814
  const updated = parseInitiative(dir, ini.filePath, newContent);
12439
12815
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -12586,10 +12962,15 @@ export {
12586
12962
  INITIATIVE_STATES,
12587
12963
  INITIATIVE_TRANSITIONS,
12588
12964
  INTEGRATIONS_FILE,
12965
+ INTERFACE_TYPES,
12589
12966
  ImportError,
12590
12967
  InitiativeWriteError,
12591
12968
  IntegrationError,
12592
12969
  IntegrationServiceError,
12970
+ RESOURCE_ARTIFACT_TYPE,
12971
+ RESOURCE_ROLES,
12972
+ RESOURCE_TYPES,
12973
+ ResourceWriteError,
12593
12974
  TOPOLOGY_FILE,
12594
12975
  TopologyWriteError,
12595
12976
  WorkItemNotFoundError,
@@ -12617,10 +12998,12 @@ export {
12617
12998
  consentNotice,
12618
12999
  createInitiative,
12619
13000
  createIntegration,
13001
+ createResource,
12620
13002
  createWorkItem,
12621
13003
  cwd,
12622
13004
  deferConsent,
12623
13005
  deleteIntegration,
13006
+ deleteResource,
12624
13007
  detectFormat,
12625
13008
  disableIntegration,
12626
13009
  discoverExternalWorkItems,
@@ -12645,6 +13028,9 @@ export {
12645
13028
  getIntegration,
12646
13029
  getIntegrationFilters,
12647
13030
  getIntegrationSecretStatus,
13031
+ getResource,
13032
+ getResourceReferences,
13033
+ getResources,
12648
13034
  getSystemMapProjection,
12649
13035
  getSystemNeighbors,
12650
13036
  getSystemNodeContext,
@@ -12678,7 +13064,9 @@ export {
12678
13064
  nextInitiativeId,
12679
13065
  parseContent,
12680
13066
  parseInitiative,
13067
+ parseScope,
12681
13068
  parseSuccessCriteria,
13069
+ parseWorkItemResources,
12682
13070
  persistConsent,
12683
13071
  previewImport,
12684
13072
  readFile,
@@ -12692,8 +13080,10 @@ export {
12692
13080
  updateInitiative,
12693
13081
  updateIntegration,
12694
13082
  updateIntegrationFilters,
13083
+ updateResource,
12695
13084
  updateWorkItem,
12696
13085
  validateConfigAgainstSchema,
13086
+ validateResource,
12697
13087
  validateSystemTopology,
12698
13088
  validateTopologyProposal,
12699
13089
  validateWorkItem,