@kaddo/cli 3.113.0 → 3.115.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 (35) hide show
  1. package/README.md +199 -452
  2. package/dist/admin-dist/assets/{architectureDiagram-3BPJPVTR-eYr0CQIi.js → architectureDiagram-3BPJPVTR-YcMJYo0g.js} +1 -1
  3. package/dist/admin-dist/assets/{chunk-727SXJPM-DrnpGnui.js → chunk-727SXJPM-BVnKaPXl.js} +1 -1
  4. package/dist/admin-dist/assets/{chunk-AQP2D5EJ-CEGy8SpK.js → chunk-AQP2D5EJ-D_Hcj3zm.js} +1 -1
  5. package/dist/admin-dist/assets/{classDiagram-v2-Q7XG4LA2-DA001cdf.js → classDiagram-4FO5ZUOK-C1j2IJF8.js} +1 -1
  6. package/dist/admin-dist/assets/{classDiagram-4FO5ZUOK-DA001cdf.js → classDiagram-v2-Q7XG4LA2-C1j2IJF8.js} +1 -1
  7. package/dist/admin-dist/assets/{dagre-BM42HDAG-BRJ0nXQb.js → dagre-BM42HDAG-ADdKf6j1.js} +1 -1
  8. package/dist/admin-dist/assets/{diagram-2AECGRRQ-xd6Livp4.js → diagram-2AECGRRQ-Z_xeHBlY.js} +1 -1
  9. package/dist/admin-dist/assets/{diagram-5GNKFQAL-o9d2ix0l.js → diagram-5GNKFQAL-Wgzw55l3.js} +1 -1
  10. package/dist/admin-dist/assets/{diagram-LMA3HP47-DcnWjF35.js → diagram-LMA3HP47-Dj6c7SSM.js} +1 -1
  11. package/dist/admin-dist/assets/{diagram-OG6HWLK6-Cw5XQicu.js → diagram-OG6HWLK6-hHqRSSZr.js} +1 -1
  12. package/dist/admin-dist/assets/{erDiagram-TEJ5UH35-DRxLZQPp.js → erDiagram-TEJ5UH35-BTGBIaZr.js} +1 -1
  13. package/dist/admin-dist/assets/{flowDiagram-I6XJVG4X-Pb5MivY8.js → flowDiagram-I6XJVG4X-RZJDjzR6.js} +1 -1
  14. package/dist/admin-dist/assets/{ganttDiagram-6RSMTGT7-Cm7UHfMW.js → ganttDiagram-6RSMTGT7-DI5Lr-xB.js} +1 -1
  15. package/dist/admin-dist/assets/{index-M8TdCEku.js → index-RwMAZcWr.js} +4 -4
  16. package/dist/admin-dist/assets/{infoDiagram-5YYISTIA-Bwq-Ae1z.js → infoDiagram-5YYISTIA-T5KZWjTy.js} +1 -1
  17. package/dist/admin-dist/assets/{ishikawaDiagram-YF4QCWOH-CN8u3lkW.js → ishikawaDiagram-YF4QCWOH-C6Gyb7TQ.js} +1 -1
  18. package/dist/admin-dist/assets/{kanban-definition-UN3LZRKU-DFp13Kfy.js → kanban-definition-UN3LZRKU-Dg8kSuqH.js} +1 -1
  19. package/dist/admin-dist/assets/{linear-sB0c581b.js → linear-NG3wfuct.js} +1 -1
  20. package/dist/admin-dist/assets/{mindmap-definition-RKZ34NQL-Ds_AH-UF.js → mindmap-definition-RKZ34NQL-B1dMo93T.js} +1 -1
  21. package/dist/admin-dist/assets/{pieDiagram-4H26LBE5-CT6aVbJD.js → pieDiagram-4H26LBE5-iIbw9aCq.js} +1 -1
  22. package/dist/admin-dist/assets/{quadrantDiagram-W4KKPZXB-QacGkpjr.js → quadrantDiagram-W4KKPZXB-CBsaVubF.js} +1 -1
  23. package/dist/admin-dist/assets/{requirementDiagram-4Y6WPE33-UjzvMQAY.js → requirementDiagram-4Y6WPE33-CobNACNF.js} +1 -1
  24. package/dist/admin-dist/assets/{sequenceDiagram-3UESZ5HK-Drii4Z9H.js → sequenceDiagram-3UESZ5HK-CpE56jux.js} +1 -1
  25. package/dist/admin-dist/assets/{stateDiagram-AJRCARHV-Cu5M1jgm.js → stateDiagram-AJRCARHV-pSzN5IAu.js} +1 -1
  26. package/dist/admin-dist/assets/{stateDiagram-v2-BHNVJYJU-Dnkqr8wc.js → stateDiagram-v2-BHNVJYJU-LhQFrdKp.js} +1 -1
  27. package/dist/admin-dist/assets/{timeline-definition-PNZ67QCA-BmCLa1NQ.js → timeline-definition-PNZ67QCA-q4yUdZjI.js} +1 -1
  28. package/dist/admin-dist/assets/{vennDiagram-CIIHVFJN-BhHRtC9_.js → vennDiagram-CIIHVFJN-D5DxPuNK.js} +1 -1
  29. package/dist/admin-dist/assets/{wardleyDiagram-YWT4CUSO-BzHZzKlk.js → wardleyDiagram-YWT4CUSO-451b1uEN.js} +1 -1
  30. package/dist/admin-dist/assets/{xychartDiagram-2RQKCTM6-uU2Utuv0.js → xychartDiagram-2RQKCTM6-DnOwq6Mk.js} +1 -1
  31. package/dist/admin-dist/index.html +1 -1
  32. package/dist/admin-server/index.js +2 -0
  33. package/dist/core.js +254 -45
  34. package/dist/index.js +380 -129
  35. package/package.json +1 -1
package/dist/core.js CHANGED
@@ -1844,8 +1844,130 @@ 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 toDetail(filePath, relPath, raw) {
1907
+ const parsed = matter4(raw);
1908
+ const fm = parsed.data ?? {};
1909
+ const body = parsed.content.trim();
1910
+ const id = str(fm.id) ?? "";
1911
+ return {
1912
+ id,
1913
+ title: str(fm.title) ?? id,
1914
+ resourceType: str(fm.resource_type),
1915
+ provider: str(fm.provider),
1916
+ environments: strArray(fm.environments),
1917
+ path: relPath,
1918
+ purpose: str(fm.purpose),
1919
+ interfaces: parseInterfaces(fm.access_interfaces),
1920
+ boundaries: parseBoundaries(fm.access_boundaries),
1921
+ ...(() => {
1922
+ const a = parseAuth(fm.authentication);
1923
+ return { authRefs: a.refs, authMode: a.mode };
1924
+ })(),
1925
+ markdownBody: body
1926
+ };
1927
+ }
1928
+ function getResources(dir) {
1929
+ return discoverKnowledge(dir).filter((a) => a.type === RESOURCE_ARTIFACT_TYPE).map((a) => {
1930
+ const fm = a.rawFrontmatter;
1931
+ return {
1932
+ id: a.id || str(fm.id) || a.title,
1933
+ title: a.title || str(fm.title) || a.id,
1934
+ resourceType: str(fm.resource_type),
1935
+ provider: str(fm.provider),
1936
+ environments: strArray(fm.environments),
1937
+ path: a.relPath
1938
+ };
1939
+ }).sort((x, y) => x.id.localeCompare(y.id));
1940
+ }
1941
+ function getResource(dir, id) {
1942
+ const match = discoverKnowledge(dir).find(
1943
+ (a) => a.type === RESOURCE_ARTIFACT_TYPE && (a.id === id || a.title === id)
1944
+ );
1945
+ if (!match) return null;
1946
+ const raw = readFile(match.filePath);
1947
+ return toDetail(match.filePath, match.relPath, raw);
1948
+ }
1949
+ function parseWorkItemResources(fm) {
1950
+ const v = fm.resources;
1951
+ if (!Array.isArray(v)) return [];
1952
+ const out = [];
1953
+ for (const raw of v) {
1954
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
1955
+ const o = raw;
1956
+ const id = str(o.id);
1957
+ if (!id) continue;
1958
+ out.push({ id, role: str(o.role) ?? "affected" });
1959
+ }
1960
+ return out;
1961
+ }
1962
+
1847
1963
  // src/core/graph.ts
1848
1964
  var KNOWLEDGE2 = "knowledge";
1965
+ var RESOURCE_ROLE_EDGE = {
1966
+ affected: "affects",
1967
+ implementation: "uses",
1968
+ validation: "validates_with",
1969
+ delivery: "delivers_through"
1970
+ };
1849
1971
  var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
1850
1972
  var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
1851
1973
  function scopeStatuses(scope) {
@@ -1924,6 +2046,16 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
1924
2046
  if (cand.materializedAs) addEdge(candId, `wi:${cand.materializedAs}`, "materialized_as");
1925
2047
  }
1926
2048
  }
2049
+ const resourceTitleById = /* @__PURE__ */ new Map();
2050
+ for (const r of getResources(dir)) {
2051
+ resourceTitleById.set(r.id, r.title);
2052
+ addNode({
2053
+ id: `resource:${r.id}`,
2054
+ type: "project-resource",
2055
+ label: r.title ? `${r.id} ${r.title}`.trim() : r.id,
2056
+ path: r.path
2057
+ });
2058
+ }
1927
2059
  for (const wi of selectedWIs) {
1928
2060
  const id = wi.id || wi.title;
1929
2061
  if (!id || !id.trim()) continue;
@@ -1948,6 +2080,12 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
1948
2080
  addNode({ id: capId, type: "capability", label: cap });
1949
2081
  addEdge(wiNodeId, capId, "implements");
1950
2082
  }
2083
+ for (const rel of parseWorkItemResources(wi.rawFrontmatter)) {
2084
+ const resId = `resource:${rel.id}`;
2085
+ const title = resourceTitleById.get(rel.id);
2086
+ addNode({ id: resId, type: "project-resource", label: title ? `${rel.id} ${title}`.trim() : rel.id });
2087
+ addEdge(wiNodeId, resId, RESOURCE_ROLE_EDGE[rel.role] ?? "uses");
2088
+ }
1951
2089
  for (const dec of wi.decisions) {
1952
2090
  if (!dec || !dec.trim()) continue;
1953
2091
  const adrId = `adr:${dec}`;
@@ -2222,7 +2360,7 @@ function loadGraphHints(dir) {
2222
2360
  }
2223
2361
 
2224
2362
  // src/services/installed-skills.ts
2225
- import matter4 from "gray-matter";
2363
+ import matter5 from "gray-matter";
2226
2364
  var SKILLS_DIR = join("knowledge", "skills");
2227
2365
  function discoverInstalledSkills(dir) {
2228
2366
  const base = join(dir, SKILLS_DIR);
@@ -2232,7 +2370,7 @@ function discoverInstalledSkills(dir) {
2232
2370
  const skillFile = join(base, entry, "skill.md");
2233
2371
  if (!isFile(skillFile)) continue;
2234
2372
  try {
2235
- const { data } = matter4(readFile(skillFile));
2373
+ const { data } = matter5(readFile(skillFile));
2236
2374
  if (data.type && String(data.type) !== "skill") continue;
2237
2375
  const id = String(data.id ?? entry);
2238
2376
  out.push({
@@ -3743,7 +3881,7 @@ function deriveDeliveryCompletedStatus(dir) {
3743
3881
  }
3744
3882
 
3745
3883
  // src/core/assets.ts
3746
- import matter5 from "gray-matter";
3884
+ import matter6 from "gray-matter";
3747
3885
 
3748
3886
  // src/core/version.ts
3749
3887
  import { fileURLToPath } from "url";
@@ -3898,8 +4036,13 @@ dependencies.
3898
4036
  flags, content/copy, authentication/authorization, notifications, analytics, documentation,
3899
4037
  operations/release \u2014 as affected, reviewed-not-affected, unknown, or not-applicable.
3900
4038
  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.
4039
+ 5. **Resource review** \u2014 ask: does this change need to observe, modify, validate or deliver against a
4040
+ known external resource of the project (a Project Resource under \`knowledge/tech/resources/\` \u2014
4041
+ database, cloud, API, queue, storage\u2026)? If so, declare it in the WI front matter \`resources:\` with
4042
+ a role (\`affected\`, \`implementation\`, \`validation\`, \`delivery\`). Resources are external systems,
4043
+ distinct from \`affected_modules\` (code). Not every WI needs resources (e.g. a CSS change does not).
4044
+ 6. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, resources
4045
+ assessed, unknowns visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
3903
4046
 
3904
4047
  ## Rules
3905
4048
 
@@ -3910,6 +4053,8 @@ dependencies.
3910
4053
  - Include at least one end-to-end acceptance criterion for user-facing changes.
3911
4054
  - Do not reduce a product intent to the first technical implementation found.
3912
4055
  - Evaluate surfaces and modules before proposing files.
4056
+ - Consider Project Resources when the scope justifies it; never invent resources not backed by
4057
+ project knowledge, and keep \`resources\` (external systems) separate from \`affected_modules\` (code).
3913
4058
  - This skill refines scope and acceptance criteria but does not approve implementation readiness.
3914
4059
  Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
3915
4060
 
@@ -6949,7 +7094,7 @@ function canonicalSkills() {
6949
7094
  }
6950
7095
  function versionOf(content) {
6951
7096
  try {
6952
- const v = matter5(content).data.version;
7097
+ const v = matter6(content).data.version;
6953
7098
  return v === void 0 || v === null ? null : String(v);
6954
7099
  } catch {
6955
7100
  return null;
@@ -7640,7 +7785,7 @@ function buildProjectRoute(dir) {
7640
7785
  }
7641
7786
 
7642
7787
  // src/core/metadata-health.ts
7643
- import matter6 from "gray-matter";
7788
+ import matter7 from "gray-matter";
7644
7789
  var KNOWLEDGE_FILES2 = [
7645
7790
  "knowledge/business/business.md",
7646
7791
  "knowledge/product/product.md",
@@ -7660,7 +7805,7 @@ function analyzeMetadataHealth(dir) {
7660
7805
  let data;
7661
7806
  try {
7662
7807
  const raw = readFile(p);
7663
- data = matter6(raw).data;
7808
+ data = matter7(raw).data;
7664
7809
  } catch {
7665
7810
  continue;
7666
7811
  }
@@ -7692,7 +7837,7 @@ function analyzeMetadataHealth(dir) {
7692
7837
  if (isFile(p) && entry.endsWith(".md")) {
7693
7838
  try {
7694
7839
  const raw = readFile(p);
7695
- const fm = matter6(raw).data;
7840
+ const fm = matter7(raw).data;
7696
7841
  if (fm.status === "done") {
7697
7842
  const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
7698
7843
  findings.push({
@@ -8289,7 +8434,7 @@ function analyzeCrossRepoEvidence(input) {
8289
8434
  }
8290
8435
 
8291
8436
  // src/core/work-items.ts
8292
- import matter7 from "gray-matter";
8437
+ import matter8 from "gray-matter";
8293
8438
 
8294
8439
  // src/core/system-topology.ts
8295
8440
  import { parse as parseYaml8, stringify as stringifyYaml4 } from "yaml";
@@ -8659,6 +8804,8 @@ function getWorkItem(dir, workItemId) {
8659
8804
  path: match.relPath,
8660
8805
  // Faithful source of truth: the artifact body already read above, not reconstructed (WI-025).
8661
8806
  markdownBody: body.trim(),
8807
+ // External systems this WI relates to (WI-030), separate from affectedModules (code).
8808
+ resources: parseWorkItemResources(fm),
8662
8809
  ...parseSystemImpact(dir, fm)
8663
8810
  };
8664
8811
  return { ...detail, refinement: computeRefinementStatus(detail) };
@@ -8723,7 +8870,7 @@ function parseOriginalSnapshot(fm) {
8723
8870
  function readBody(filePath) {
8724
8871
  try {
8725
8872
  const raw = readFile(filePath);
8726
- return matter7(raw).content;
8873
+ return matter8(raw).content;
8727
8874
  } catch {
8728
8875
  return "";
8729
8876
  }
@@ -8890,7 +9037,7 @@ function parseRelatedKnowledge(fm, knowledgeById) {
8890
9037
  import fs3 from "fs";
8891
9038
  import path3 from "path";
8892
9039
  import crypto2 from "crypto";
8893
- import matter8 from "gray-matter";
9040
+ import matter9 from "gray-matter";
8894
9041
 
8895
9042
  // src/core/knowledge-levels.ts
8896
9043
  var WORK_ITEM_TYPES2 = ["feature", "bugfix", "hotfix", "spike", "chore"];
@@ -9253,6 +9400,14 @@ ${body}`);
9253
9400
  ${out.join("\n\n")}
9254
9401
  `.replace(/\n{3,}/g, "\n\n");
9255
9402
  }
9403
+ function ensureH1(body, title) {
9404
+ const trimmed = body.trim();
9405
+ const firstMeaningful = trimmed.split(/\r?\n/).find((l) => l.trim());
9406
+ if (firstMeaningful && /^#\s+/.test(firstMeaningful.trim())) return trimmed;
9407
+ return `# ${title}
9408
+
9409
+ ${trimmed}`;
9410
+ }
9256
9411
  function applyFrontmatter(data, input) {
9257
9412
  const next = { ...data };
9258
9413
  next.title = input.title;
@@ -9289,7 +9444,7 @@ function applyFrontmatter(data, input) {
9289
9444
  return next;
9290
9445
  }
9291
9446
  function serialize(data, body) {
9292
- return matter8.stringify(`
9447
+ return matter9.stringify(`
9293
9448
  ${body.trim()}
9294
9449
  `, data);
9295
9450
  }
@@ -9348,7 +9503,7 @@ function toInput(data, content) {
9348
9503
  function getWorkItemForEdit(dir, id) {
9349
9504
  const { filePath, relPath } = findArtifact(dir, id);
9350
9505
  const raw = readFile(filePath);
9351
- const { data, content } = matter8(raw);
9506
+ const { data, content } = matter9(raw);
9352
9507
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9353
9508
  const input = toInput(data, content);
9354
9509
  const editable = EDITABLE_STATES.includes(status);
@@ -9392,6 +9547,7 @@ function createWorkItem(dir, opts) {
9392
9547
  const id = nextWorkItemId(dir);
9393
9548
  const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
9394
9549
  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
9550
+ const summary = opts.summary?.trim() || intent;
9395
9551
  const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
9396
9552
  const data = {
9397
9553
  type,
@@ -9403,15 +9559,16 @@ function createWorkItem(dir, opts) {
9403
9559
  source,
9404
9560
  generated_by: "kaddo-admin",
9405
9561
  affected_modules: [],
9406
- summary: intent
9562
+ summary
9407
9563
  };
9408
9564
  if (opts.originalSnapshot) data.original_snapshot = opts.originalSnapshot;
9409
9565
  const answers = opts.answers ?? {};
9410
9566
  const hasAnswers = Object.values(answers).some((v) => v?.trim());
9411
- const body = hasAnswers ? captureBody(title, type, answers) : freshBody({
9567
+ const providedBody = opts.body?.trim();
9568
+ const body = providedBody ? ensureH1(providedBody, title) : hasAnswers ? captureBody(title, type, answers) : freshBody({
9412
9569
  title,
9413
9570
  type,
9414
- summary: intent,
9571
+ summary,
9415
9572
  scopeUnknowns: [],
9416
9573
  affectedModules: [],
9417
9574
  moduleCoverage: [],
@@ -9439,7 +9596,7 @@ function updateWorkItem(dir, id, input, expectedRevision) {
9439
9596
  if (revisionOf(raw) !== expectedRevision) {
9440
9597
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before saving.");
9441
9598
  }
9442
- const { data, content } = matter8(raw);
9599
+ const { data, content } = matter9(raw);
9443
9600
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9444
9601
  if (!EDITABLE_STATES.includes(status)) {
9445
9602
  throw new WorkItemWriteError("WORK_ITEM_NOT_EDITABLE", `A ${status} Work Item cannot be edited. Reopen it as Draft first.`);
@@ -9453,7 +9610,7 @@ function updateWorkItem(dir, id, input, expectedRevision) {
9453
9610
  function validateWorkItem(dir, id) {
9454
9611
  const { filePath } = findArtifact(dir, id);
9455
9612
  const raw = readFile(filePath);
9456
- const { data, content } = matter8(raw);
9613
+ const { data, content } = matter9(raw);
9457
9614
  const input = toInput(data, content);
9458
9615
  const findings = [];
9459
9616
  const modules = validModuleIds(dir);
@@ -9506,7 +9663,7 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
9506
9663
  if (revisionOf(raw) !== expectedRevision) {
9507
9664
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
9508
9665
  }
9509
- const { data, content } = matter8(raw);
9666
+ const { data, content } = matter9(raw);
9510
9667
  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9511
9668
  if (!(ALLOWED[from] ?? []).includes(to)) {
9512
9669
  throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
@@ -10003,6 +10160,7 @@ function buildImplementationHandoff(dir, workItemId) {
10003
10160
  const affectedModules = match.affectedModules;
10004
10161
  const domains = match.domains;
10005
10162
  const scopeConfidence = match.scopeConfidence;
10163
+ const wiResources = parseWorkItemResources(match.rawFrontmatter);
10006
10164
  const lines = [
10007
10165
  `Implement Work Item ${wiId} \u2014 "${wiTitle}" \u2014 in project "${projectName}" using Kaddo.`,
10008
10166
  "",
@@ -10092,6 +10250,41 @@ function buildImplementationHandoff(dir, workItemId) {
10092
10250
  "Do not copy all legacy knowledge \u2014 assemble proportionally to scope."
10093
10251
  );
10094
10252
  }
10253
+ if (wiResources.length > 0) {
10254
+ lines.push(
10255
+ "",
10256
+ "--- Relevant Resources ---",
10257
+ "",
10258
+ "This Work Item relates to external project resources. The handoff INFORMS you about them \u2014 it",
10259
+ "never connects to them, runs any interface, or reveals credential values. Respect each boundary."
10260
+ );
10261
+ for (const rel of wiResources) {
10262
+ const res = getResource(dir, rel.id);
10263
+ if (!res) {
10264
+ lines.push("", `- ${rel.id} (role: ${rel.role}) \u2014 definition not found under knowledge/tech/resources/.`);
10265
+ continue;
10266
+ }
10267
+ lines.push("", `- ${res.id} \u2014 ${res.title} (role: ${rel.role})`);
10268
+ if (res.resourceType || res.provider) {
10269
+ lines.push(` type: ${res.resourceType ?? "\u2014"}${res.provider ? ` \xB7 provider: ${res.provider}` : ""}`);
10270
+ }
10271
+ if (res.purpose) lines.push(` purpose: ${res.purpose}`);
10272
+ if (res.environments.length > 0) lines.push(` environments: ${res.environments.join(", ")}`);
10273
+ if (res.interfaces.length > 0) {
10274
+ const ifaces = res.interfaces.map((i) => i.tool || i.provider ? `${i.type} (${i.tool ?? i.provider})` : i.type);
10275
+ lines.push(` interfaces: ${ifaces.join(", ")}`);
10276
+ }
10277
+ for (const [env, ops] of Object.entries(res.boundaries)) {
10278
+ lines.push(` boundary (${env}): ${ops.join(", ")}`);
10279
+ }
10280
+ if (res.authRefs.length > 0) lines.push(` auth references (names only): ${res.authRefs.join(", ")}`);
10281
+ }
10282
+ lines.push(
10283
+ "",
10284
+ "Treat these as knowledge, not availability: an interface being declared does not mean it is",
10285
+ "installed or connected. Do not execute any interface or migration without explicit human confirmation."
10286
+ );
10287
+ }
10095
10288
  lines.push(
10096
10289
  "",
10097
10290
  "--- Implementation Plan ---",
@@ -10112,6 +10305,7 @@ function buildImplementationHandoff(dir, workItemId) {
10112
10305
  projectName,
10113
10306
  lifecycle,
10114
10307
  affectedModules,
10308
+ resources: wiResources,
10115
10309
  domains,
10116
10310
  scopeConfidence,
10117
10311
  hasUnmaterializedDecisions: unmaterialized,
@@ -10348,7 +10542,7 @@ function deriveImplementationStatus(repos) {
10348
10542
  // src/core/work-item-import.ts
10349
10543
  import crypto3 from "crypto";
10350
10544
  import fs4 from "fs";
10351
- import matter9 from "gray-matter";
10545
+ import matter10 from "gray-matter";
10352
10546
  var MAX_INPUT_BYTES = 102400;
10353
10547
  var LIFECYCLE_FIELDS = /* @__PURE__ */ new Set([
10354
10548
  "id",
@@ -10370,7 +10564,7 @@ function detectFormat(raw) {
10370
10564
  if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
10371
10565
  if (trimmed.startsWith("---")) {
10372
10566
  try {
10373
- const { data } = matter9(trimmed);
10567
+ const { data } = matter10(trimmed);
10374
10568
  if (data && typeof data === "object" && Object.keys(data).length > 0) {
10375
10569
  const d = data;
10376
10570
  if (d.type === "work-item" || d.id && typeof d.id === "string" && /^WI-\d+/.test(d.id)) {
@@ -10392,7 +10586,7 @@ function parseContent(raw) {
10392
10586
  let bodyText = trimmed;
10393
10587
  if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
10394
10588
  try {
10395
- const parsed = matter9(trimmed);
10589
+ const parsed = matter10(trimmed);
10396
10590
  frontmatterFields = parsed.data ?? {};
10397
10591
  bodyText = parsed.content.trim();
10398
10592
  } catch {
@@ -10449,15 +10643,21 @@ function extractSections(body) {
10449
10643
  flush();
10450
10644
  return sections;
10451
10645
  }
10646
+ function deriveShortSummary(parsed) {
10647
+ const paragraph = parsed.body.split(/\n{2,}/).map((p) => p.trim()).find((p) => p && !/^#{1,6}\s/.test(p) && !/^>/.test(p) && p !== parsed.title);
10648
+ const base = paragraph ? paragraph.replace(/\s+/g, " ") : parsed.title;
10649
+ return base.length > 280 ? `${base.slice(0, 277).trimEnd()}\u2026` : base;
10650
+ }
10452
10651
  function normalizeImportFields(parsed, opts) {
10453
10652
  const discardedFields = [];
10454
10653
  for (const key of Object.keys(parsed.candidateFields)) {
10455
10654
  if (LIFECYCLE_FIELDS.has(key)) discardedFields.push(key);
10456
10655
  }
10457
10656
  const type = opts.userType ? normalizeType(opts.userType) ?? "feature" : parsed.type ?? "feature";
10458
- const intent = parsed.body && parsed.body !== parsed.title ? `${parsed.title}
10459
-
10460
- ${parsed.body}` : parsed.title;
10657
+ const hasRealBody = !!parsed.body && parsed.body !== parsed.title;
10658
+ const intent = parsed.title;
10659
+ const body = hasRealBody ? parsed.body : void 0;
10660
+ const summary = hasRealBody ? deriveShortSummary(parsed) : parsed.title;
10461
10661
  const source = {
10462
10662
  type: opts.importSource === "chat" ? "chat" : "external",
10463
10663
  imported_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
@@ -10465,14 +10665,14 @@ ${parsed.body}` : parsed.title;
10465
10665
  source.source_format = opts.sourceFormat;
10466
10666
  source.source_hash = opts.sourceHash;
10467
10667
  const snapshot = { title: parsed.title };
10468
- if (parsed.summary !== parsed.title) snapshot.description = parsed.summary;
10668
+ if (summary !== parsed.title) snapshot.description = summary;
10469
10669
  if (typeof parsed.candidateFields.type === "string") snapshot.type = parsed.candidateFields.type;
10470
10670
  if (typeof parsed.candidateFields.status === "string") snapshot.status = parsed.candidateFields.status;
10471
10671
  if (Array.isArray(parsed.candidateFields.labels)) {
10472
10672
  const labels = parsed.candidateFields.labels.filter((l) => typeof l === "string");
10473
10673
  if (labels.length > 0) snapshot.labels = labels;
10474
10674
  }
10475
- return { type, intent, source, snapshot, discardedFields };
10675
+ return { type, intent, summary, body, source, snapshot, discardedFields };
10476
10676
  }
10477
10677
  function computeContentHash(raw) {
10478
10678
  return crypto3.createHash("sha256").update(raw.trim(), "utf-8").digest("hex");
@@ -10483,7 +10683,7 @@ function findDuplicateByHash(dir, hash) {
10483
10683
  const raw = readFile(item.filePath);
10484
10684
  if (!raw) continue;
10485
10685
  try {
10486
- const { data } = matter9(raw);
10686
+ const { data } = matter10(raw);
10487
10687
  const source = data?.source;
10488
10688
  if (source && typeof source === "object" && !Array.isArray(source)) {
10489
10689
  const s = source;
@@ -10558,6 +10758,8 @@ function importWorkItem(dir, opts) {
10558
10758
  const result = createWorkItem(dir, {
10559
10759
  intent: normalized.intent,
10560
10760
  type: normalized.type,
10761
+ summary: normalized.summary,
10762
+ body: normalized.body,
10561
10763
  source: normalized.source,
10562
10764
  originalSnapshot: normalized.snapshot
10563
10765
  });
@@ -10590,7 +10792,7 @@ var ImportError = class extends Error {
10590
10792
  };
10591
10793
 
10592
10794
  // src/services/integrations.ts
10593
- import matter10 from "gray-matter";
10795
+ import matter11 from "gray-matter";
10594
10796
  import { parse as parseYaml9, stringify as stringifyYaml5 } from "yaml";
10595
10797
 
10596
10798
  // ../integrations/src/errors.ts
@@ -11932,7 +12134,7 @@ function findLinkedWorkItem(dir, integrationId, externalId) {
11932
12134
  for (const art of discoverWorkItems(dir)) {
11933
12135
  let data;
11934
12136
  try {
11935
- data = matter10(readFile(art.filePath)).data;
12137
+ data = matter11(readFile(art.filePath)).data;
11936
12138
  } catch {
11937
12139
  continue;
11938
12140
  }
@@ -11948,7 +12150,7 @@ function buildImportIndex(dir) {
11948
12150
  for (const art of discoverWorkItems(dir)) {
11949
12151
  let data;
11950
12152
  try {
11951
- data = matter10(readFile(art.filePath)).data;
12153
+ data = matter11(readFile(art.filePath)).data;
11952
12154
  } catch {
11953
12155
  continue;
11954
12156
  }
@@ -12124,7 +12326,7 @@ function getStatus(dir) {
12124
12326
  }
12125
12327
 
12126
12328
  // src/core/initiative-write.ts
12127
- import matter11 from "gray-matter";
12329
+ import matter12 from "gray-matter";
12128
12330
  var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
12129
12331
  var DRAFT_DIR = `${WORK_ITEMS_DIR2}/draft`;
12130
12332
  var ROADMAP_PATH2 = "knowledge/delivery/roadmap.md";
@@ -12237,7 +12439,7 @@ function buildInitiativeContent(id, input) {
12237
12439
  if (input.priority) data.priority = input.priority;
12238
12440
  if (input.source) data.source = input.source;
12239
12441
  if (input.sourceId) data.source_id = input.sourceId;
12240
- return matter11.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12442
+ return matter12.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12241
12443
  }
12242
12444
  function createInitiative(dir, input) {
12243
12445
  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -12261,10 +12463,10 @@ function transitionInitiative(dir, id, to) {
12261
12463
  throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
12262
12464
  }
12263
12465
  const raw = readFile(ini.filePath);
12264
- const { data, content } = matter11(raw, {});
12466
+ const { data, content } = matter12(raw, {});
12265
12467
  data.status = to;
12266
12468
  if (to === "completed") data.completed_at = today();
12267
- const newContent = matter11.stringify(content, data);
12469
+ const newContent = matter12.stringify(content, data);
12268
12470
  writeFile(ini.filePath, newContent);
12269
12471
  const updated = parseInitiative(dir, ini.filePath, newContent);
12270
12472
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -12274,7 +12476,7 @@ function addCandidate(dir, id, candidate) {
12274
12476
  const ini = getInitiative(dir, id);
12275
12477
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12276
12478
  const raw = readFile(ini.filePath);
12277
- const { data, content } = matter11(raw, {});
12479
+ const { data, content } = matter12(raw, {});
12278
12480
  const existing = Array.isArray(data.candidates) ? data.candidates : [];
12279
12481
  const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
12280
12482
  const normalized = normalizeCandidate(candidate, fallbackId);
@@ -12282,7 +12484,7 @@ function addCandidate(dir, id, candidate) {
12282
12484
  throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
12283
12485
  }
12284
12486
  data.candidates = [...existing, candidateToData(normalized)];
12285
- const newContent = matter11.stringify(content, data);
12487
+ const newContent = matter12.stringify(content, data);
12286
12488
  writeFile(ini.filePath, newContent);
12287
12489
  const updated = parseInitiative(dir, ini.filePath, newContent);
12288
12490
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
@@ -12292,7 +12494,7 @@ function updateInitiative(dir, id, patch) {
12292
12494
  const ini = getInitiative(dir, id);
12293
12495
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12294
12496
  const raw = readFile(ini.filePath);
12295
- const { data, content } = matter11(raw, {});
12497
+ const { data, content } = matter12(raw, {});
12296
12498
  if (patch.title !== void 0) {
12297
12499
  if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
12298
12500
  data.title = patch.title.trim();
@@ -12302,7 +12504,7 @@ function updateInitiative(dir, id, patch) {
12302
12504
  if (patch.knowledgeLevel !== void 0) data.knowledge_level = patch.knowledgeLevel;
12303
12505
  if (patch.domains !== void 0) data.domains = patch.domains;
12304
12506
  if (patch.relatedCapabilities !== void 0) data.related_capabilities = patch.relatedCapabilities;
12305
- const newContent = matter11.stringify(content, data);
12507
+ const newContent = matter12.stringify(content, data);
12306
12508
  writeFile(ini.filePath, newContent);
12307
12509
  const updated = parseInitiative(dir, ini.filePath, newContent);
12308
12510
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
@@ -12320,10 +12522,10 @@ function addExternalLink(dir, id, link) {
12320
12522
  throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
12321
12523
  }
12322
12524
  const raw = readFile(ini.filePath);
12323
- const { data, content } = matter11(raw, {});
12525
+ const { data, content } = matter12(raw, {});
12324
12526
  const existing = Array.isArray(data.external_links) ? data.external_links : [];
12325
12527
  data.external_links = [...existing, externalLinkToData(link)];
12326
- const newContent = matter11.stringify(content, data);
12528
+ const newContent = matter12.stringify(content, data);
12327
12529
  writeFile(ini.filePath, newContent);
12328
12530
  const updated = parseInitiative(dir, ini.filePath, newContent);
12329
12531
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
@@ -12392,7 +12594,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
12392
12594
  "_What did we learn? Update after completion._",
12393
12595
  ""
12394
12596
  ].join("\n");
12395
- return matter11.stringify("\n" + body, data);
12597
+ return matter12.stringify("\n" + body, data);
12396
12598
  }
12397
12599
  function materializeCandidate(dir, id, candidateId) {
12398
12600
  const ini = getInitiative(dir, id);
@@ -12409,13 +12611,13 @@ function materializeCandidate(dir, id, candidateId) {
12409
12611
  ensureDir(join(dir, DRAFT_DIR));
12410
12612
  writeFile(join(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
12411
12613
  const raw = readFile(ini.filePath);
12412
- const { data, content } = matter11(raw, {});
12614
+ const { data, content } = matter12(raw, {});
12413
12615
  const cands = Array.isArray(data.candidates) ? data.candidates : [];
12414
12616
  for (const c of cands) {
12415
12617
  if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
12416
12618
  }
12417
12619
  data.candidates = cands;
12418
- const newContent = matter11.stringify(content, data);
12620
+ const newContent = matter12.stringify(content, data);
12419
12621
  writeFile(ini.filePath, newContent);
12420
12622
  const updated = parseInitiative(dir, ini.filePath, newContent);
12421
12623
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -12568,10 +12770,14 @@ export {
12568
12770
  INITIATIVE_STATES,
12569
12771
  INITIATIVE_TRANSITIONS,
12570
12772
  INTEGRATIONS_FILE,
12773
+ INTERFACE_TYPES,
12571
12774
  ImportError,
12572
12775
  InitiativeWriteError,
12573
12776
  IntegrationError,
12574
12777
  IntegrationServiceError,
12778
+ RESOURCE_ARTIFACT_TYPE,
12779
+ RESOURCE_ROLES,
12780
+ RESOURCE_TYPES,
12575
12781
  TOPOLOGY_FILE,
12576
12782
  TopologyWriteError,
12577
12783
  WorkItemNotFoundError,
@@ -12627,6 +12833,8 @@ export {
12627
12833
  getIntegration,
12628
12834
  getIntegrationFilters,
12629
12835
  getIntegrationSecretStatus,
12836
+ getResource,
12837
+ getResources,
12630
12838
  getSystemMapProjection,
12631
12839
  getSystemNeighbors,
12632
12840
  getSystemNodeContext,
@@ -12661,6 +12869,7 @@ export {
12661
12869
  parseContent,
12662
12870
  parseInitiative,
12663
12871
  parseSuccessCriteria,
12872
+ parseWorkItemResources,
12664
12873
  persistConsent,
12665
12874
  previewImport,
12666
12875
  readFile,