@kaddo/cli 3.115.0 → 3.117.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 +19 -0
  2. package/dist/admin-dist/assets/{architectureDiagram-3BPJPVTR-YcMJYo0g.js → architectureDiagram-3BPJPVTR-VNE4N202.js} +1 -1
  3. package/dist/admin-dist/assets/{chunk-727SXJPM-BVnKaPXl.js → chunk-727SXJPM-Dycfm5kx.js} +1 -1
  4. package/dist/admin-dist/assets/{chunk-AQP2D5EJ-D_Hcj3zm.js → chunk-AQP2D5EJ-CZfRVDeZ.js} +1 -1
  5. package/dist/admin-dist/assets/{classDiagram-v2-Q7XG4LA2-C1j2IJF8.js → classDiagram-4FO5ZUOK-ZqEUMLi9.js} +1 -1
  6. package/dist/admin-dist/assets/{classDiagram-4FO5ZUOK-C1j2IJF8.js → classDiagram-v2-Q7XG4LA2-ZqEUMLi9.js} +1 -1
  7. package/dist/admin-dist/assets/{dagre-BM42HDAG-ADdKf6j1.js → dagre-BM42HDAG-BPoktDQ7.js} +1 -1
  8. package/dist/admin-dist/assets/{diagram-2AECGRRQ-Z_xeHBlY.js → diagram-2AECGRRQ-DX6VsCIO.js} +1 -1
  9. package/dist/admin-dist/assets/{diagram-5GNKFQAL-Wgzw55l3.js → diagram-5GNKFQAL-DaVO8tr4.js} +1 -1
  10. package/dist/admin-dist/assets/{diagram-LMA3HP47-Dj6c7SSM.js → diagram-LMA3HP47-C7OMxYl7.js} +1 -1
  11. package/dist/admin-dist/assets/{diagram-OG6HWLK6-hHqRSSZr.js → diagram-OG6HWLK6-Ba7L6sdv.js} +1 -1
  12. package/dist/admin-dist/assets/{erDiagram-TEJ5UH35-BTGBIaZr.js → erDiagram-TEJ5UH35-B8GR6jN8.js} +1 -1
  13. package/dist/admin-dist/assets/{flowDiagram-I6XJVG4X-RZJDjzR6.js → flowDiagram-I6XJVG4X-GnYF-YSu.js} +1 -1
  14. package/dist/admin-dist/assets/{ganttDiagram-6RSMTGT7-DI5Lr-xB.js → ganttDiagram-6RSMTGT7-Ci5gXlfB.js} +1 -1
  15. package/dist/admin-dist/assets/{index-RwMAZcWr.js → index-BQS_UR2v.js} +5 -5
  16. package/dist/admin-dist/assets/{infoDiagram-5YYISTIA-T5KZWjTy.js → infoDiagram-5YYISTIA-CXCqRy3V.js} +1 -1
  17. package/dist/admin-dist/assets/{ishikawaDiagram-YF4QCWOH-C6Gyb7TQ.js → ishikawaDiagram-YF4QCWOH-CHnyKPlH.js} +1 -1
  18. package/dist/admin-dist/assets/{kanban-definition-UN3LZRKU-Dg8kSuqH.js → kanban-definition-UN3LZRKU-DZ2E5eRA.js} +1 -1
  19. package/dist/admin-dist/assets/{linear-NG3wfuct.js → linear-CBbecos1.js} +1 -1
  20. package/dist/admin-dist/assets/{mindmap-definition-RKZ34NQL-B1dMo93T.js → mindmap-definition-RKZ34NQL-C_PLO1RL.js} +1 -1
  21. package/dist/admin-dist/assets/{pieDiagram-4H26LBE5-iIbw9aCq.js → pieDiagram-4H26LBE5-Bnzx1mbG.js} +1 -1
  22. package/dist/admin-dist/assets/{quadrantDiagram-W4KKPZXB-CBsaVubF.js → quadrantDiagram-W4KKPZXB-vDV6emR-.js} +1 -1
  23. package/dist/admin-dist/assets/{requirementDiagram-4Y6WPE33-CobNACNF.js → requirementDiagram-4Y6WPE33-BS-WaBoL.js} +1 -1
  24. package/dist/admin-dist/assets/{sequenceDiagram-3UESZ5HK-CpE56jux.js → sequenceDiagram-3UESZ5HK-DHBKXsre.js} +1 -1
  25. package/dist/admin-dist/assets/{stateDiagram-AJRCARHV-pSzN5IAu.js → stateDiagram-AJRCARHV-Cvrc0x1G.js} +1 -1
  26. package/dist/admin-dist/assets/{stateDiagram-v2-BHNVJYJU-LhQFrdKp.js → stateDiagram-v2-BHNVJYJU-B9k2LCWQ.js} +1 -1
  27. package/dist/admin-dist/assets/{timeline-definition-PNZ67QCA-q4yUdZjI.js → timeline-definition-PNZ67QCA-BPg3zrWH.js} +1 -1
  28. package/dist/admin-dist/assets/{vennDiagram-CIIHVFJN-D5DxPuNK.js → vennDiagram-CIIHVFJN-Cr5_ruRl.js} +1 -1
  29. package/dist/admin-dist/assets/{wardleyDiagram-YWT4CUSO-451b1uEN.js → wardleyDiagram-YWT4CUSO-CCFwsa6d.js} +1 -1
  30. package/dist/admin-dist/assets/{xychartDiagram-2RQKCTM6-DnOwq6Mk.js → xychartDiagram-2RQKCTM6-zM8ePcPG.js} +1 -1
  31. package/dist/admin-dist/index.html +1 -1
  32. package/dist/admin-server/index.js +105 -0
  33. package/dist/core.js +447 -97
  34. package/dist/index.js +1066 -318
  35. package/package.json +1 -1
package/dist/core.js CHANGED
@@ -35,13 +35,15 @@ function join(...parts) {
35
35
 
36
36
  // src/core/config.ts
37
37
  import { z } from "zod";
38
- import { parse as parseYaml } from "yaml";
38
+ import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
39
39
  var PROJECT_STATES = ["new", "pre-ai", "legacy", "ai-assisted"];
40
+ var PROJECT_MODES = ["standard", "poc"];
40
41
  var TEAM_SIZES = ["indie", "small", "medium", "enterprise"];
41
42
  var REPOSITORY_STRUCTURES = ["monorepo", "multirepo"];
42
43
  var PROJECT_LANGUAGES = ["en", "es"];
43
44
  var DEFAULTS = {
44
45
  state: "pre-ai",
46
+ mode: "standard",
45
47
  structure: "monorepo",
46
48
  teamSize: "indie",
47
49
  language: "en"
@@ -53,6 +55,9 @@ function projectLanguage(config) {
53
55
  const lang = config.project.language;
54
56
  return lang === "es" ? "es" : "en";
55
57
  }
58
+ function projectMode(config) {
59
+ return config.project.mode === "poc" ? "poc" : "standard";
60
+ }
56
61
  var ConfigError = class extends Error {
57
62
  constructor(message) {
58
63
  super(message);
@@ -64,6 +69,11 @@ var projectStateSchema = z.enum(["new", "pre-ai", "legacy", "ai-assisted"], {
64
69
  message: `project.state must be one of: ${PROJECT_STATES.join(", ")}`
65
70
  })
66
71
  });
72
+ var projectModeSchema = z.enum(["standard", "poc"], {
73
+ errorMap: () => ({
74
+ message: `project.mode must be one of: ${PROJECT_MODES.join(", ")}`
75
+ })
76
+ });
67
77
  var teamSizeSchema = z.enum(["indie", "small", "medium", "enterprise"], {
68
78
  errorMap: () => ({
69
79
  message: `team.size must be one of: ${TEAM_SIZES.join(", ")}`
@@ -85,6 +95,7 @@ var configSchema = z.object({
85
95
  project: z.object({
86
96
  name: z.string().default("project"),
87
97
  state: projectStateSchema.default(DEFAULTS.state),
98
+ mode: projectModeSchema.default(DEFAULTS.mode),
88
99
  structure: structureSchema.default(DEFAULTS.structure),
89
100
  language: languageSchema.default(DEFAULTS.language),
90
101
  role: multirepoRoleSchema,
@@ -130,14 +141,31 @@ function loadConfig(dir) {
130
141
  const parsed = configSchema.safeParse(raw ?? {});
131
142
  if (!parsed.success) {
132
143
  const issues = parsed.error.issues.map((i) => {
133
- const path4 = i.path.join(".");
134
- return path4 ? ` - ${path4}: ${i.message}` : ` - ${i.message}`;
144
+ const path5 = i.path.join(".");
145
+ return path5 ? ` - ${path5}: ${i.message}` : ` - ${i.message}`;
135
146
  }).join("\n");
136
147
  throw new ConfigError(`Invalid .kaddo/config.yml:
137
148
  ${issues}`);
138
149
  }
139
150
  return parsed.data;
140
151
  }
152
+ function setProjectMode(dir, mode) {
153
+ const configPath = configPathFor(dir);
154
+ if (!exists(configPath)) throw new ConfigError("No .kaddo/config.yml found. Run `kaddo init` first.");
155
+ let raw;
156
+ try {
157
+ raw = parseYaml(readFile(configPath)) ?? {};
158
+ } catch (err) {
159
+ const detail = err instanceof Error ? err.message : String(err);
160
+ throw new ConfigError(`Could not parse .kaddo/config.yml: ${detail}`);
161
+ }
162
+ const project = raw.project && typeof raw.project === "object" && !Array.isArray(raw.project) ? raw.project : {};
163
+ raw.project = { ...project, mode };
164
+ writeFile(configPath, stringifyYaml(raw));
165
+ const updated = loadConfig(dir);
166
+ if (!updated) throw new ConfigError("Could not reload .kaddo/config.yml after updating project.mode.");
167
+ return updated;
168
+ }
141
169
  function projectRole(config) {
142
170
  return config.project.role ?? config.multirepo?.role;
143
171
  }
@@ -343,7 +371,7 @@ function discoverWorkItems(dir) {
343
371
 
344
372
  // src/core/capsule.ts
345
373
  import matter2 from "gray-matter";
346
- import { parse as parseYaml6, stringify as stringifyYaml3 } from "yaml";
374
+ import { parse as parseYaml6, stringify as stringifyYaml4 } from "yaml";
347
375
 
348
376
  // src/services/owners.ts
349
377
  import { parse as parseYaml2 } from "yaml";
@@ -366,11 +394,11 @@ function moduleArtifactCoverage(dir, id) {
366
394
  };
367
395
  }
368
396
  function loadMappedModules(dir) {
369
- const path4 = join(dir, DESCRIPTOR_PATH);
370
- if (!exists(path4)) return [];
397
+ const path5 = join(dir, DESCRIPTOR_PATH);
398
+ if (!exists(path5)) return [];
371
399
  let parsed;
372
400
  try {
373
- parsed = parseYaml3(readFile(path4));
401
+ parsed = parseYaml3(readFile(path5));
374
402
  } catch {
375
403
  return [];
376
404
  }
@@ -398,7 +426,7 @@ function loadMappedModules(dir) {
398
426
  }
399
427
 
400
428
  // src/commands/modules-map.ts
401
- import { parse as parseYaml5, stringify as stringifyYaml2 } from "yaml";
429
+ import { parse as parseYaml5, stringify as stringifyYaml3 } from "yaml";
402
430
 
403
431
  // src/templates/registry.ts
404
432
  var QUALITY = "## Quality checklist";
@@ -1562,7 +1590,7 @@ ${QUALITY}
1562
1590
  `;
1563
1591
 
1564
1592
  // src/commands/modules-discover.ts
1565
- import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
1593
+ import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
1566
1594
 
1567
1595
  // src/core/capsule.ts
1568
1596
  var EXTERNAL_PATH = ".kaddo/external.yml";
@@ -1601,7 +1629,7 @@ function sectionParagraph(md, title) {
1601
1629
  }
1602
1630
  return "";
1603
1631
  }
1604
- function parseCapsule(id, path4, md) {
1632
+ function parseCapsule(id, path5, md) {
1605
1633
  const { data } = matter2(md);
1606
1634
  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
1607
1635
  let ageDays = null;
@@ -1611,7 +1639,7 @@ function parseCapsule(id, path4, md) {
1611
1639
  }
1612
1640
  return {
1613
1641
  id,
1614
- path: path4,
1642
+ path: path5,
1615
1643
  system: data.system ? String(data.system) : id,
1616
1644
  owner: data.owner ? String(data.owner) : void 0,
1617
1645
  updatedAt,
@@ -1903,6 +1931,18 @@ function parseAuth(v) {
1903
1931
  const refs = strArray(o.refs).filter((r) => !r.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r));
1904
1932
  return { mode: str(o.mode), refs };
1905
1933
  }
1934
+ function parseScope(v) {
1935
+ if (!v || typeof v !== "object" || Array.isArray(v)) return null;
1936
+ const o = v;
1937
+ const type = str(o.type);
1938
+ if (!type) return null;
1939
+ return { type, module: str(o.module) };
1940
+ }
1941
+ function purposeFromBody(body) {
1942
+ const m = body.match(/^#{1,2}\s+Purpose\s*\n+([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m);
1943
+ const text2 = m ? m[1].trim() : "";
1944
+ return text2 || null;
1945
+ }
1906
1946
  function toDetail(filePath, relPath, raw) {
1907
1947
  const parsed = matter4(raw);
1908
1948
  const fm = parsed.data ?? {};
@@ -1914,8 +1954,10 @@ function toDetail(filePath, relPath, raw) {
1914
1954
  resourceType: str(fm.resource_type),
1915
1955
  provider: str(fm.provider),
1916
1956
  environments: strArray(fm.environments),
1957
+ scope: parseScope(fm.scope),
1958
+ modules: strArray(fm.modules),
1917
1959
  path: relPath,
1918
- purpose: str(fm.purpose),
1960
+ purpose: str(fm.purpose) ?? purposeFromBody(body),
1919
1961
  interfaces: parseInterfaces(fm.access_interfaces),
1920
1962
  boundaries: parseBoundaries(fm.access_boundaries),
1921
1963
  ...(() => {
@@ -1934,6 +1976,8 @@ function getResources(dir) {
1934
1976
  resourceType: str(fm.resource_type),
1935
1977
  provider: str(fm.provider),
1936
1978
  environments: strArray(fm.environments),
1979
+ scope: parseScope(fm.scope),
1980
+ modules: strArray(fm.modules),
1937
1981
  path: a.relPath
1938
1982
  };
1939
1983
  }).sort((x, y) => x.id.localeCompare(y.id));
@@ -2004,9 +2048,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
2004
2048
  ];
2005
2049
  const presentLayers = [];
2006
2050
  for (const layer of layerDocs) {
2007
- const path4 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
2008
- if (path4) {
2009
- addNode({ id: layer.id, type: layer.type, label: layer.label, path: path4 });
2051
+ const path5 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
2052
+ if (path5) {
2053
+ addNode({ id: layer.id, type: layer.type, label: layer.label, path: path5 });
2010
2054
  presentLayers.push(layer.id);
2011
2055
  }
2012
2056
  }
@@ -2049,12 +2093,20 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
2049
2093
  const resourceTitleById = /* @__PURE__ */ new Map();
2050
2094
  for (const r of getResources(dir)) {
2051
2095
  resourceTitleById.set(r.id, r.title);
2096
+ const resId = `resource:${r.id}`;
2052
2097
  addNode({
2053
- id: `resource:${r.id}`,
2098
+ id: resId,
2054
2099
  type: "project-resource",
2055
2100
  label: r.title ? `${r.id} ${r.title}`.trim() : r.id,
2056
2101
  path: r.path
2057
2102
  });
2103
+ const depModules = new Set(r.modules);
2104
+ if (r.scope?.type === "module" && r.scope.module) depModules.add(r.scope.module);
2105
+ for (const mod of depModules) {
2106
+ const modId = `module:${mod}`;
2107
+ addNode({ id: modId, type: "module", label: mod });
2108
+ addEdge(modId, resId, "depends_on");
2109
+ }
2058
2110
  }
2059
2111
  for (const wi of selectedWIs) {
2060
2112
  const id = wi.id || wi.title;
@@ -3358,6 +3410,43 @@ function hasUnmaterializedDecisions(td) {
3358
3410
  return td.candidates > 0 && td.adrs === 0;
3359
3411
  }
3360
3412
 
3413
+ // src/core/poc.ts
3414
+ var POC_ARTIFACT_PATH = "knowledge/delivery/poc.md";
3415
+ var PLACEHOLDER = /^[_<].*[_>]$|^(describe|list|document|what|how)\b/i;
3416
+ function section(markdown, heading) {
3417
+ const match = markdown.match(new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im"));
3418
+ return match?.[1] ?? "";
3419
+ }
3420
+ function meaningful(text2) {
3421
+ return text2.split(/\r?\n/).some((line) => {
3422
+ const value = line.trim().replace(/^[-*]\s+(?:\[[^\]]+\]\s*)?/, "");
3423
+ return Boolean(value) && !PLACEHOLDER.test(value) && !/^status:\s*(pending|tbd)$/i.test(value);
3424
+ });
3425
+ }
3426
+ function readPocSummary(dir) {
3427
+ const path5 = join(dir, POC_ARTIFACT_PATH);
3428
+ if (!exists(path5)) {
3429
+ return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
3430
+ }
3431
+ let markdown = "";
3432
+ try {
3433
+ markdown = readFile(path5);
3434
+ } catch {
3435
+ return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
3436
+ }
3437
+ const criteria = section(markdown, "Success Criteria").split(/\r?\n/).filter((line) => /^\s*[-*]\s+(?:\[[ xX]\]\s+)?/.test(line)).filter((line) => meaningful(line)).length;
3438
+ const conclusionBody = section(markdown, "Conclusion");
3439
+ const conclusionMatch = conclusionBody.match(/\b(?:status|outcome)\s*:\s*(validated|rejected|inconclusive)\b/i);
3440
+ return {
3441
+ exists: true,
3442
+ hypothesisDefined: meaningful(section(markdown, "Hypothesis")),
3443
+ successCriteriaCount: criteria,
3444
+ constraintsDefined: meaningful(section(markdown, "Constraints")),
3445
+ nonGoalsDefined: meaningful(section(markdown, "Non-goals")),
3446
+ conclusion: conclusionMatch ? conclusionMatch[1].toLowerCase() : "pending"
3447
+ };
3448
+ }
3449
+
3361
3450
  // src/core/next-step.ts
3362
3451
  function buildDeliveryState(dir) {
3363
3452
  const wis = discoverWorkItems(dir);
@@ -3445,13 +3534,47 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
3445
3534
  return { id: "init", phase: "Setup", label: "Run `kaddo init` to initialize Kaddo.", command: "kaddo init", reason: "Kaddo is not initialized in this project." };
3446
3535
  }
3447
3536
  const state = config.project.state;
3537
+ if (projectMode(config) === "poc") {
3538
+ const poc = readPocSummary(dir);
3539
+ if (!poc.exists) {
3540
+ return { id: "bootstrap", phase: "Setup", label: "Run `kaddo bootstrap` to create the POC knowledge baseline.", command: "kaddo bootstrap", reason: `Missing ${POC_ARTIFACT_PATH}.` };
3541
+ }
3542
+ if (!poc.hypothesisDefined) {
3543
+ return { id: "poc-hypothesis", phase: "POC Definition", label: "Define the POC hypothesis.", target: POC_ARTIFACT_PATH, reason: "The POC needs a testable hypothesis before work begins." };
3544
+ }
3545
+ if (poc.successCriteriaCount === 0) {
3546
+ return { id: "poc-success-criteria", phase: "POC Definition", label: "Define observable POC success criteria.", target: POC_ARTIFACT_PATH, reason: "No success criteria are defined for the hypothesis." };
3547
+ }
3548
+ const qCurrentState2 = analyzeKnowledgeArtifact(dir, CS);
3549
+ const qCodebase2 = analyzeKnowledgeArtifact(dir, CB);
3550
+ if (qCurrentState2 !== "useful" || qCodebase2 !== "useful") {
3551
+ return { id: "poc-technical-context", phase: "POC Discovery", label: "Document the minimal technical context for the experiment.", target: qCurrentState2 !== "useful" ? CS : CB, agent: "architecture-agent", reason: "The experiment surface and constraints are not yet sufficiently documented." };
3552
+ }
3553
+ if (!exists(join(dir, "knowledge", "resources"))) {
3554
+ return { id: "poc-resources", phase: "POC Discovery", label: "Identify the project resources relevant to the experiment.", command: "kaddo resources list", reason: "No project resource catalog is available for the experiment context." };
3555
+ }
3556
+ const delivery = buildDeliveryState(dir);
3557
+ if (delivery.total_work_items === 0) {
3558
+ return { id: "poc-create-experiment", phase: "Experiment", label: "Create the first experiment Work Item (prefer `spike`).", command: "kaddo create spike", reason: "The POC has no Work Item to produce evidence." };
3559
+ }
3560
+ if (delivery.in_progress_work_items > 0) {
3561
+ return { id: "guard", phase: "Experiment", label: "Run `kaddo guard` and capture evidence from the experiment.", command: "kaddo guard", reason: `${delivery.in_progress_work_items} experiment Work Item(s) are in progress.` };
3562
+ }
3563
+ if (delivery.ready_work_items > 0 || delivery.draft_work_items > 0 || delivery.blocked_work_items > 0) {
3564
+ return { id: delivery.ready_work_items > 0 ? "implement-work-item" : "refine-work-item", phase: "Experiment", label: delivery.ready_work_items > 0 ? "Implement the ready experiment Work Item and collect evidence." : "Refine the experiment Work Item before running it.", agent: "work-item-agent", reason: "The POC evidence Work Item is not complete yet." };
3565
+ }
3566
+ if (poc.conclusion === "pending") {
3567
+ return { id: "poc-evaluate", phase: "Evaluation", label: "Evaluate the experiment evidence and record the POC conclusion.", target: POC_ARTIFACT_PATH, reason: "Experiment Work Items are complete but the POC conclusion is pending." };
3568
+ }
3569
+ return { id: "poc-complete", phase: "Conclusion", label: `POC concluded: ${poc.conclusion}. Decide whether to graduate it to standard delivery.`, target: POC_ARTIFACT_PATH, reason: "The POC conclusion is recorded from experiment evidence." };
3570
+ }
3448
3571
  const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
3449
3572
  const resolveAgent = (agent) => {
3450
3573
  const file = agent.endsWith(".md") ? agent : `${agent}.md`;
3451
- const path4 = agentInstallPath(file);
3452
- const installed = isFile(join(dir, path4));
3574
+ const path5 = agentInstallPath(file);
3575
+ const installed = isFile(join(dir, path5));
3453
3576
  const group = agentGroupOf(file);
3454
- return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
3577
+ return { agentPath: path5, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
3455
3578
  };
3456
3579
  const moduleRepo = isModule(config);
3457
3580
  const coreRepo = isCore(config);
@@ -5206,6 +5329,16 @@ supporting notes as \`knowledge/tech/discovery/architecture-notes.md\` and decis
5206
5329
  under \`knowledge/tech/decisions/\`. Kaddo still reads the legacy root locations for backward
5207
5330
  compatibility, but new output should use \`discovery/\`.
5208
5331
 
5332
+ ## Project Resource candidates
5333
+
5334
+ When the knowledge describes an external system the project depends on (a database, cloud account,
5335
+ API, queue, storage, service\u2026), you may propose it as a **candidate** Project Resource \u2014 never create
5336
+ it silently. Discovery \u2260 creation: present candidates for human review and materialize only through
5337
+ \`kaddo_create_resource\` / \`kaddo resources create\` with explicit confirmation. Ground every
5338
+ candidate in the knowledge (no guessing from ambiguous names). Model the stable system, not its access
5339
+ interface (CLI/MCP/SQL/API are interfaces); keep \`resources\` separate from \`affected_modules\`; and
5340
+ never include secret values \u2014 only reference names.
5341
+
5209
5342
  ## Quality Checklist
5210
5343
 
5211
5344
  - Every component is backed by evidence from the context pack.
@@ -7649,6 +7782,47 @@ var LEGACY_STEPS = [
7649
7782
  runGuard,
7650
7783
  captureLearning
7651
7784
  ];
7785
+ var definePocHypothesis = {
7786
+ id: "poc-hypothesis",
7787
+ label: "Define hypothesis",
7788
+ evaluate: (ctx) => {
7789
+ const poc = readPocSummary(ctx.dir);
7790
+ return { status: poc.hypothesisDefined ? "done" : "current", evidence: poc.hypothesisDefined ? [POC_ARTIFACT_PATH] : void 0, reason: poc.hypothesisDefined ? void 0 : "A POC starts with one testable hypothesis." };
7791
+ }
7792
+ };
7793
+ var definePocCriteria = {
7794
+ id: "poc-success-criteria",
7795
+ label: "Define success criteria",
7796
+ evaluate: (ctx) => {
7797
+ const poc = readPocSummary(ctx.dir);
7798
+ return { status: poc.successCriteriaCount > 0 ? "done" : "pending", evidence: poc.successCriteriaCount > 0 ? [POC_ARTIFACT_PATH] : void 0, reason: poc.successCriteriaCount > 0 ? void 0 : "Define observable evidence for the hypothesis." };
7799
+ }
7800
+ };
7801
+ var describePocTech = { ...describeArchitecture, id: "poc-technical-context", label: "Document minimal technical context" };
7802
+ var identifyPocResources = {
7803
+ id: "poc-resources",
7804
+ label: "Identify relevant resources",
7805
+ evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "pending", command: "kaddo resources list" }
7806
+ };
7807
+ var createPocExperiment = {
7808
+ id: "poc-create-experiment",
7809
+ label: "Create experiment Work Item",
7810
+ evaluate: (ctx) => ctx.totalWorkItems > 0 ? { status: "done", evidence: ["knowledge/delivery/work-items/"] } : { status: "pending", command: "kaddo create spike", reason: "Prefer a spike for a focused experiment." }
7811
+ };
7812
+ var capturePocEvidence = {
7813
+ id: "poc-evidence",
7814
+ label: "Capture experiment evidence",
7815
+ evaluate: (ctx) => ctx.completedWorkItems > 0 ? { status: "done", evidence: ["knowledge/delivery/work-items/"] } : { status: "pending", reason: "Complete an experiment Work Item and link its evidence in the POC artifact." }
7816
+ };
7817
+ var concludePoc = {
7818
+ id: "poc-evaluate",
7819
+ label: "Evaluate and conclude",
7820
+ evaluate: (ctx) => {
7821
+ const conclusion = readPocSummary(ctx.dir).conclusion;
7822
+ return conclusion === "pending" ? { status: "pending", reason: "Record validated, rejected, or inconclusive from the evidence." } : { status: "done", evidence: [POC_ARTIFACT_PATH], reason: `Conclusion: ${conclusion}.` };
7823
+ }
7824
+ };
7825
+ var POC_STEPS = [enableKaddo, bootstrapBaseline, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
7652
7826
  function stepsForState(state) {
7653
7827
  switch (state) {
7654
7828
  case "new":
@@ -7745,14 +7919,21 @@ function mapNextStepId(id) {
7745
7919
  "init-module-context": "enable-kaddo",
7746
7920
  "module-ready": "ready-for-core-orchestration",
7747
7921
  "validate-work-item-modules": "validate-module-knowledge",
7748
- "modules-discover": "enable-kaddo"
7922
+ "modules-discover": "enable-kaddo",
7923
+ "poc-hypothesis": "poc-hypothesis",
7924
+ "poc-success-criteria": "poc-success-criteria",
7925
+ "poc-technical-context": "poc-technical-context",
7926
+ "poc-resources": "poc-resources",
7927
+ "poc-create-experiment": "poc-create-experiment",
7928
+ "poc-evaluate": "poc-evaluate",
7929
+ "poc-complete": "poc-evaluate"
7749
7930
  };
7750
7931
  return MAP[id] ?? id;
7751
7932
  }
7752
7933
  function buildProjectRoute(dir) {
7753
7934
  const config = loadConfig(dir);
7754
7935
  const state = config?.project.state ?? "pre-ai";
7755
- const defs = config && isModule(config) ? MODULE_STEPS : stepsForState(state);
7936
+ const defs = config && projectMode(config) === "poc" ? POC_STEPS : config && isModule(config) ? MODULE_STEPS : stepsForState(state);
7756
7937
  const ctx = buildRouteContext(dir);
7757
7938
  const steps = defs.map((d) => {
7758
7939
  const result = d.evaluate(ctx);
@@ -8198,6 +8379,164 @@ function buildProjectExplanation(dir) {
8198
8379
  };
8199
8380
  }
8200
8381
 
8382
+ // src/core/resource-write.ts
8383
+ import fs2 from "fs";
8384
+ import path2 from "path";
8385
+ import matter8 from "gray-matter";
8386
+ var RESOURCES_DIR = "knowledge/tech/resources";
8387
+ var ResourceWriteError = class extends Error {
8388
+ constructor(code, message) {
8389
+ super(message);
8390
+ this.code = code;
8391
+ this.name = "ResourceWriteError";
8392
+ }
8393
+ code;
8394
+ };
8395
+ function slug3(s) {
8396
+ return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
8397
+ }
8398
+ function atomicWrite(filePath, content) {
8399
+ const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
8400
+ fs2.writeFileSync(tmp, content, "utf-8");
8401
+ fs2.renameSync(tmp, filePath);
8402
+ }
8403
+ function sanitizeRefs(refs) {
8404
+ if (!Array.isArray(refs)) return [];
8405
+ return refs.map((r) => String(r).trim()).filter((r) => r && !r.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r));
8406
+ }
8407
+ function allResourceArtifacts(dir) {
8408
+ return discoverKnowledge(dir).filter((a) => a.type === RESOURCE_ARTIFACT_TYPE);
8409
+ }
8410
+ function nextResourceId(dir, title, explicit) {
8411
+ const existing = new Set(allResourceArtifacts(dir).map((a) => (a.id || "").toUpperCase()));
8412
+ if (explicit && explicit.trim()) return explicit.trim();
8413
+ const base = `RES-${slug3(title) || "resource"}`;
8414
+ if (!existing.has(base.toUpperCase())) return base;
8415
+ for (let i = 2; i < 1e3; i++) {
8416
+ const candidate = `${base}-${i}`;
8417
+ if (!existing.has(candidate.toUpperCase())) return candidate;
8418
+ }
8419
+ throw new ResourceWriteError("ID_EXHAUSTED", `Could not derive a unique id for "${title}".`);
8420
+ }
8421
+ function validateResource(dir, input) {
8422
+ const findings = [];
8423
+ if (input.resourceType && !RESOURCE_TYPES.includes(input.resourceType)) {
8424
+ findings.push({ level: "warning", message: `Unknown resource_type "${input.resourceType}" (not in the known set).` });
8425
+ }
8426
+ for (const i of input.accessInterfaces ?? []) {
8427
+ if (i.type && !INTERFACE_TYPES.includes(i.type)) {
8428
+ findings.push({ level: "warning", message: `Unknown access interface type "${i.type}".` });
8429
+ }
8430
+ }
8431
+ const mapped = loadMappedModules(dir).map((m) => m.id);
8432
+ if (mapped.length > 0) {
8433
+ const refs = /* @__PURE__ */ new Set();
8434
+ if (input.scope?.type === "module" && input.scope.module) refs.add(input.scope.module);
8435
+ for (const m of input.modules ?? []) refs.add(m);
8436
+ for (const m of refs) {
8437
+ if (!mapped.includes(m)) findings.push({ level: "warning", message: `Module "${m}" is not in .kaddo/modules.yml.` });
8438
+ }
8439
+ }
8440
+ if (input.scope && input.scope.type === "module" && !input.scope.module) {
8441
+ findings.push({ level: "error", message: 'scope.type "module" requires a module id.' });
8442
+ }
8443
+ return findings;
8444
+ }
8445
+ function buildFrontmatter(id, input, base = {}) {
8446
+ const data = { ...base };
8447
+ data.type = RESOURCE_ARTIFACT_TYPE;
8448
+ data.id = id;
8449
+ if (input.title != null) data.title = input.title;
8450
+ if (input.resourceType != null) data.resource_type = input.resourceType;
8451
+ if (input.provider != null) data.provider = input.provider;
8452
+ if (input.environments != null) data.environments = input.environments;
8453
+ if (input.scope != null) data.scope = input.scope.module ? { type: input.scope.type, module: input.scope.module } : { type: input.scope.type };
8454
+ if (input.modules != null) data.modules = input.modules;
8455
+ if (input.accessInterfaces != null) data.access_interfaces = input.accessInterfaces;
8456
+ if (input.accessBoundaries != null) data.access_boundaries = input.accessBoundaries;
8457
+ if (input.authentication != null) {
8458
+ const mode = input.authentication.mode;
8459
+ const refs = sanitizeRefs(input.authentication.refs);
8460
+ data.authentication = { ...mode ? { mode } : {}, ...refs.length ? { refs } : {} };
8461
+ }
8462
+ return data;
8463
+ }
8464
+ function serialize(data, body) {
8465
+ return matter8.stringify(`
8466
+ ${body.trim()}
8467
+ `, data);
8468
+ }
8469
+ function createResource(dir, input) {
8470
+ const title = (input.title ?? "").trim();
8471
+ if (!title) throw new ResourceWriteError("INVALID_INPUT", "A resource title is required.");
8472
+ const resourceType = (input.resourceType ?? "").trim();
8473
+ if (!resourceType) throw new ResourceWriteError("INVALID_INPUT", "A resource_type is required.");
8474
+ const findings = validateResource(dir, input);
8475
+ if (findings.some((f) => f.level === "error")) {
8476
+ throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f) => f.level === "error").map((f) => f.message).join("; "));
8477
+ }
8478
+ const existing = allResourceArtifacts(dir);
8479
+ if (input.id && existing.some((a) => (a.id || "").toUpperCase() === input.id.toUpperCase())) {
8480
+ throw new ResourceWriteError("DUPLICATE", `A resource with id "${input.id}" already exists.`);
8481
+ }
8482
+ if (existing.some((a) => (a.title || "").toLowerCase() === title.toLowerCase())) {
8483
+ throw new ResourceWriteError("DUPLICATE", `A resource titled "${title}" already exists.`);
8484
+ }
8485
+ const id = nextResourceId(dir, title, input.id);
8486
+ const data = buildFrontmatter(id, input);
8487
+ const body = `# Purpose
8488
+
8489
+ ${(input.purpose ?? "").trim() || "TODO: describe what this resource is for."}`;
8490
+ const relPath = `${RESOURCES_DIR}/${slug3(title) || slug3(id)}.md`;
8491
+ const filePath = join(dir, relPath);
8492
+ if (exists(filePath)) throw new ResourceWriteError("DUPLICATE", `Resource file already exists: ${relPath}`);
8493
+ ensureDir(path2.dirname(filePath));
8494
+ atomicWrite(filePath, serialize(data, body));
8495
+ return { id, path: relPath, findings };
8496
+ }
8497
+ function updateResource(dir, id, input) {
8498
+ const match = allResourceArtifacts(dir).find((a) => a.id === id || a.title === id);
8499
+ if (!match) throw new ResourceWriteError("NOT_FOUND", `Project Resource "${id}" not found.`);
8500
+ const findings = validateResource(dir, input);
8501
+ if (findings.some((f) => f.level === "error")) {
8502
+ throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f) => f.level === "error").map((f) => f.message).join("; "));
8503
+ }
8504
+ const raw = readFile(match.filePath);
8505
+ const parsed = matter8(raw);
8506
+ const base = parsed.data ?? {};
8507
+ const data = buildFrontmatter(match.id || id, input, base);
8508
+ let body = parsed.content.trim();
8509
+ if (input.purpose != null) {
8510
+ const purpose = `# Purpose
8511
+
8512
+ ${input.purpose.trim()}`;
8513
+ body = /^#\s+Purpose/m.test(body) ? body.replace(/#\s+Purpose[\s\S]*?(?=\n#\s|\n*$)/, purpose + "\n") : `${purpose}
8514
+
8515
+ ${body}`.trim();
8516
+ }
8517
+ atomicWrite(match.filePath, serialize(data, body));
8518
+ return { id: match.id || id, path: match.relPath, findings };
8519
+ }
8520
+ function getResourceReferences(dir, id) {
8521
+ const refs = [];
8522
+ for (const wi of discoverWorkItems(dir)) {
8523
+ for (const rel of parseWorkItemResources(wi.rawFrontmatter)) {
8524
+ if (rel.id === id) refs.push({ kind: "work-item", id: wi.id || wi.title, role: rel.role, path: wi.relPath });
8525
+ }
8526
+ }
8527
+ return refs;
8528
+ }
8529
+ function deleteResource(dir, id, opts = {}) {
8530
+ const match = allResourceArtifacts(dir).find((a) => a.id === id || a.title === id);
8531
+ if (!match) throw new ResourceWriteError("NOT_FOUND", `Project Resource "${id}" not found.`);
8532
+ const references = getResourceReferences(dir, match.id || id);
8533
+ if (!opts.confirm) {
8534
+ return { deleted: false, preview: { id: match.id || id, references } };
8535
+ }
8536
+ fs2.rmSync(match.filePath, { force: true });
8537
+ return { deleted: true, path: match.relPath };
8538
+ }
8539
+
8201
8540
  // src/core/scope-coverage.ts
8202
8541
  var VALID_CONFIDENCE_LEVELS = /* @__PURE__ */ new Set(["high", "medium", "low"]);
8203
8542
  var VALID_COVERAGE_STATUSES2 = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
@@ -8434,12 +8773,12 @@ function analyzeCrossRepoEvidence(input) {
8434
8773
  }
8435
8774
 
8436
8775
  // src/core/work-items.ts
8437
- import matter8 from "gray-matter";
8776
+ import matter9 from "gray-matter";
8438
8777
 
8439
8778
  // src/core/system-topology.ts
8440
- import { parse as parseYaml8, stringify as stringifyYaml4 } from "yaml";
8441
- import fs2 from "fs";
8442
- import path2 from "path";
8779
+ import { parse as parseYaml8, stringify as stringifyYaml5 } from "yaml";
8780
+ import fs3 from "fs";
8781
+ import path3 from "path";
8443
8782
  import crypto from "crypto";
8444
8783
  var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
8445
8784
  var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
@@ -8605,17 +8944,17 @@ function serializeTopology(entities, relationships) {
8605
8944
  })),
8606
8945
  relationships: relationships.map((r) => ({ from: r.from, to: r.to, type: r.type, ...r.evidence.length ? { evidence: r.evidence } : {} }))
8607
8946
  };
8608
- return stringifyYaml4(doc);
8947
+ return stringifyYaml5(doc);
8609
8948
  }
8610
- function atomicWrite(filePath, content) {
8611
- fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
8949
+ function atomicWrite2(filePath, content) {
8950
+ fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
8612
8951
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
8613
- fs2.writeFileSync(tmp, content, "utf-8");
8952
+ fs3.writeFileSync(tmp, content, "utf-8");
8614
8953
  try {
8615
- fs2.renameSync(tmp, filePath);
8954
+ fs3.renameSync(tmp, filePath);
8616
8955
  } catch (err) {
8617
8956
  try {
8618
- fs2.rmSync(tmp, { force: true });
8957
+ fs3.rmSync(tmp, { force: true });
8619
8958
  } catch {
8620
8959
  }
8621
8960
  throw err;
@@ -8649,7 +8988,7 @@ function applyTopologyProposal(dir, proposalYaml, expectedRevision) {
8649
8988
  const raw = serializeTopology([...entityMap.values()], [...relMap.values()]);
8650
8989
  const finalCheck = validateTopologyProposal(dir, raw);
8651
8990
  if (!finalCheck.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The merged topology is invalid; no changes were written.");
8652
- atomicWrite(join(dir, TOPOLOGY_FILE), raw);
8991
+ atomicWrite2(join(dir, TOPOLOGY_FILE), raw);
8653
8992
  return { revision: topologyRevision(dir), entitiesNew, entitiesUpdated, relationshipsNew };
8654
8993
  }
8655
8994
  function buildTopologyEnrichmentHandoff(dir, projectName) {
@@ -8814,8 +9153,8 @@ function parseGraphReason(v) {
8814
9153
  if (!v || typeof v !== "object") return null;
8815
9154
  const o = v;
8816
9155
  const relationship = typeof o.relationship === "string" && o.relationship.trim() ? o.relationship.trim() : null;
8817
- const path4 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
8818
- return relationship || path4.length ? { relationship, path: path4 } : null;
9156
+ const path5 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
9157
+ return relationship || path5.length ? { relationship, path: path5 } : null;
8819
9158
  }
8820
9159
  function parseExplain(o) {
8821
9160
  const refs = Array.isArray(o.evidence) ? o.evidence : Array.isArray(o.evidence_refs) ? o.evidence_refs : [];
@@ -8870,7 +9209,7 @@ function parseOriginalSnapshot(fm) {
8870
9209
  function readBody(filePath) {
8871
9210
  try {
8872
9211
  const raw = readFile(filePath);
8873
- return matter8(raw).content;
9212
+ return matter9(raw).content;
8874
9213
  } catch {
8875
9214
  return "";
8876
9215
  }
@@ -9034,10 +9373,10 @@ function parseRelatedKnowledge(fm, knowledgeById) {
9034
9373
  }
9035
9374
 
9036
9375
  // src/core/work-item-write.ts
9037
- import fs3 from "fs";
9038
- import path3 from "path";
9376
+ import fs4 from "fs";
9377
+ import path4 from "path";
9039
9378
  import crypto2 from "crypto";
9040
- import matter9 from "gray-matter";
9379
+ import matter10 from "gray-matter";
9041
9380
 
9042
9381
  // src/core/knowledge-levels.ts
9043
9382
  var WORK_ITEM_TYPES2 = ["feature", "bugfix", "hotfix", "spike", "chore"];
@@ -9249,7 +9588,7 @@ function nextWorkItemId(dir) {
9249
9588
  let max = 0;
9250
9589
  const walk = (d) => {
9251
9590
  if (!exists(d)) return;
9252
- for (const entry of fs3.readdirSync(d)) {
9591
+ for (const entry of fs4.readdirSync(d)) {
9253
9592
  const full = join(d, entry);
9254
9593
  if (isFile(full)) {
9255
9594
  const m = entry.match(/WI-(\d+)/);
@@ -9262,15 +9601,15 @@ function nextWorkItemId(dir) {
9262
9601
  walk(wiDir);
9263
9602
  return `WI-${String(max + 1).padStart(3, "0")}`;
9264
9603
  }
9265
- function atomicWrite2(filePath, content) {
9266
- fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
9604
+ function atomicWrite3(filePath, content) {
9605
+ fs4.mkdirSync(path4.dirname(filePath), { recursive: true });
9267
9606
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
9268
- fs3.writeFileSync(tmp, content, "utf-8");
9607
+ fs4.writeFileSync(tmp, content, "utf-8");
9269
9608
  try {
9270
- fs3.renameSync(tmp, filePath);
9609
+ fs4.renameSync(tmp, filePath);
9271
9610
  } catch (err) {
9272
9611
  try {
9273
- fs3.rmSync(tmp, { force: true });
9612
+ fs4.rmSync(tmp, { force: true });
9274
9613
  } catch {
9275
9614
  }
9276
9615
  throw err;
@@ -9443,8 +9782,8 @@ function applyFrontmatter(data, input) {
9443
9782
  else delete next.related_knowledge;
9444
9783
  return next;
9445
9784
  }
9446
- function serialize(data, body) {
9447
- return matter9.stringify(`
9785
+ function serialize2(data, body) {
9786
+ return matter10.stringify(`
9448
9787
  ${body.trim()}
9449
9788
  `, data);
9450
9789
  }
@@ -9503,7 +9842,7 @@ function toInput(data, content) {
9503
9842
  function getWorkItemForEdit(dir, id) {
9504
9843
  const { filePath, relPath } = findArtifact(dir, id);
9505
9844
  const raw = readFile(filePath);
9506
- const { data, content } = matter9(raw);
9845
+ const { data, content } = matter10(raw);
9507
9846
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9508
9847
  const input = toInput(data, content);
9509
9848
  const editable = EDITABLE_STATES.includes(status);
@@ -9581,8 +9920,8 @@ function createWorkItem(dir, opts) {
9581
9920
  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify2(title)}.md`;
9582
9921
  const filePath = join(dir, relPath);
9583
9922
  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
9584
- const raw = serialize(data, body);
9585
- atomicWrite2(filePath, raw);
9923
+ const raw = serialize2(data, body);
9924
+ atomicWrite3(filePath, raw);
9586
9925
  return { id, path: relPath, revision: revisionOf(raw) };
9587
9926
  }
9588
9927
  function validateInput(input) {
@@ -9596,21 +9935,21 @@ function updateWorkItem(dir, id, input, expectedRevision) {
9596
9935
  if (revisionOf(raw) !== expectedRevision) {
9597
9936
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before saving.");
9598
9937
  }
9599
- const { data, content } = matter9(raw);
9938
+ const { data, content } = matter10(raw);
9600
9939
  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9601
9940
  if (!EDITABLE_STATES.includes(status)) {
9602
9941
  throw new WorkItemWriteError("WORK_ITEM_NOT_EDITABLE", `A ${status} Work Item cannot be edited. Reopen it as Draft first.`);
9603
9942
  }
9604
9943
  const nextData = applyFrontmatter(data, input);
9605
9944
  const nextBody = mergeBody(content, input);
9606
- const nextRaw = serialize(nextData, nextBody);
9607
- atomicWrite2(filePath, nextRaw);
9945
+ const nextRaw = serialize2(nextData, nextBody);
9946
+ atomicWrite3(filePath, nextRaw);
9608
9947
  return { revision: revisionOf(nextRaw), path: relPath };
9609
9948
  }
9610
9949
  function validateWorkItem(dir, id) {
9611
9950
  const { filePath } = findArtifact(dir, id);
9612
9951
  const raw = readFile(filePath);
9613
- const { data, content } = matter9(raw);
9952
+ const { data, content } = matter10(raw);
9614
9953
  const input = toInput(data, content);
9615
9954
  const findings = [];
9616
9955
  const modules = validModuleIds(dir);
@@ -9663,7 +10002,7 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
9663
10002
  if (revisionOf(raw) !== expectedRevision) {
9664
10003
  throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
9665
10004
  }
9666
- const { data, content } = matter9(raw);
10005
+ const { data, content } = matter10(raw);
9667
10006
  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
9668
10007
  if (!(ALLOWED[from] ?? []).includes(to)) {
9669
10008
  throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
@@ -9673,14 +10012,14 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
9673
10012
  if (!canMarkReady) throw new WorkItemWriteError("INVALID_TRANSITION", "This Work Item has blocking issues and cannot be marked Ready.");
9674
10013
  }
9675
10014
  const nextData = { ...data, status: to };
9676
- const nextRaw = serialize(nextData, content);
9677
- const filename = path3.basename(filePath);
10015
+ const nextRaw = serialize2(nextData, content);
10016
+ const filename = path4.basename(filePath);
9678
10017
  const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
9679
10018
  const targetPath = join(dir, targetRel);
9680
- atomicWrite2(targetPath, nextRaw);
9681
- if (path3.resolve(targetPath) !== path3.resolve(filePath)) {
10019
+ atomicWrite3(targetPath, nextRaw);
10020
+ if (path4.resolve(targetPath) !== path4.resolve(filePath)) {
9682
10021
  try {
9683
- fs3.rmSync(filePath, { force: true });
10022
+ fs4.rmSync(filePath, { force: true });
9684
10023
  } catch {
9685
10024
  }
9686
10025
  }
@@ -9929,16 +10268,16 @@ function findSystemPaths(dir, source, target, opts = {}) {
9929
10268
  out.get(r.source).push(r.target);
9930
10269
  }
9931
10270
  const paths = [];
9932
- const walk = (node, path4) => {
10271
+ const walk = (node, path5) => {
9933
10272
  if (paths.length >= 20) return;
9934
- if (node === target && path4.length > 1) {
9935
- paths.push([...path4]);
10273
+ if (node === target && path5.length > 1) {
10274
+ paths.push([...path5]);
9936
10275
  return;
9937
10276
  }
9938
- if (path4.length > maxDepth) return;
10277
+ if (path5.length > maxDepth) return;
9939
10278
  for (const nxt of out.get(node) ?? []) {
9940
- if (path4.includes(nxt)) continue;
9941
- walk(nxt, [...path4, nxt]);
10279
+ if (path5.includes(nxt)) continue;
10280
+ walk(nxt, [...path5, nxt]);
9942
10281
  }
9943
10282
  };
9944
10283
  walk(source, [source]);
@@ -9963,14 +10302,14 @@ function getImpactCandidates(dir, seedIds, opts = {}) {
9963
10302
  existing.reason.push(reason);
9964
10303
  continue;
9965
10304
  }
9966
- const path4 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
10305
+ const path5 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
9967
10306
  candidates.set(n.id, {
9968
10307
  nodeId: n.id,
9969
10308
  label: n.label,
9970
10309
  kind: n.type,
9971
10310
  ...n.moduleId ? { moduleId: n.moduleId } : {},
9972
10311
  reason: [reason],
9973
- ...path4 ? { graphPath: path4.map((id) => byId.get(id)?.label ?? id) } : {},
10312
+ ...path5 ? { graphPath: path5.map((id) => byId.get(id)?.label ?? id) } : {},
9974
10313
  ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
9975
10314
  ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
9976
10315
  status: "candidate",
@@ -10541,8 +10880,8 @@ function deriveImplementationStatus(repos) {
10541
10880
 
10542
10881
  // src/core/work-item-import.ts
10543
10882
  import crypto3 from "crypto";
10544
- import fs4 from "fs";
10545
- import matter10 from "gray-matter";
10883
+ import fs5 from "fs";
10884
+ import matter11 from "gray-matter";
10546
10885
  var MAX_INPUT_BYTES = 102400;
10547
10886
  var LIFECYCLE_FIELDS = /* @__PURE__ */ new Set([
10548
10887
  "id",
@@ -10564,7 +10903,7 @@ function detectFormat(raw) {
10564
10903
  if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
10565
10904
  if (trimmed.startsWith("---")) {
10566
10905
  try {
10567
- const { data } = matter10(trimmed);
10906
+ const { data } = matter11(trimmed);
10568
10907
  if (data && typeof data === "object" && Object.keys(data).length > 0) {
10569
10908
  const d = data;
10570
10909
  if (d.type === "work-item" || d.id && typeof d.id === "string" && /^WI-\d+/.test(d.id)) {
@@ -10586,7 +10925,7 @@ function parseContent(raw) {
10586
10925
  let bodyText = trimmed;
10587
10926
  if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
10588
10927
  try {
10589
- const parsed = matter10(trimmed);
10928
+ const parsed = matter11(trimmed);
10590
10929
  frontmatterFields = parsed.data ?? {};
10591
10930
  bodyText = parsed.content.trim();
10592
10931
  } catch {
@@ -10683,7 +11022,7 @@ function findDuplicateByHash(dir, hash) {
10683
11022
  const raw = readFile(item.filePath);
10684
11023
  if (!raw) continue;
10685
11024
  try {
10686
- const { data } = matter10(raw);
11025
+ const { data } = matter11(raw);
10687
11026
  const source = data?.source;
10688
11027
  if (source && typeof source === "object" && !Array.isArray(source)) {
10689
11028
  const s = source;
@@ -10750,7 +11089,7 @@ function importWorkItem(dir, opts) {
10750
11089
  };
10751
11090
  }
10752
11091
  if (opts.onConflict === "replace") {
10753
- fs4.rmSync(existing.filePath, { force: true });
11092
+ fs5.rmSync(existing.filePath, { force: true });
10754
11093
  replacedWorkItem = existing.workItemId;
10755
11094
  }
10756
11095
  }
@@ -10792,8 +11131,8 @@ var ImportError = class extends Error {
10792
11131
  };
10793
11132
 
10794
11133
  // src/services/integrations.ts
10795
- import matter11 from "gray-matter";
10796
- import { parse as parseYaml9, stringify as stringifyYaml5 } from "yaml";
11134
+ import matter12 from "gray-matter";
11135
+ import { parse as parseYaml9, stringify as stringifyYaml6 } from "yaml";
10797
11136
 
10798
11137
  // ../integrations/src/errors.ts
10799
11138
  var RETRYABLE = /* @__PURE__ */ new Set([
@@ -11561,8 +11900,8 @@ async function handleJiraResponse(res) {
11561
11900
  }
11562
11901
  return await res.json();
11563
11902
  }
11564
- async function jiraFetch(baseUrl, path4, auth, timeoutMs, params) {
11565
- const url = new URL(path4, baseUrl + "/");
11903
+ async function jiraFetch(baseUrl, path5, auth, timeoutMs, params) {
11904
+ const url = new URL(path5, baseUrl + "/");
11566
11905
  if (params) for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
11567
11906
  const controller = new AbortController();
11568
11907
  const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -11580,8 +11919,8 @@ async function jiraFetch(baseUrl, path4, auth, timeoutMs, params) {
11580
11919
  clearTimeout(timer);
11581
11920
  }
11582
11921
  }
11583
- async function jiraPost(baseUrl, path4, auth, timeoutMs, body) {
11584
- const url = new URL(path4, baseUrl + "/");
11922
+ async function jiraPost(baseUrl, path5, auth, timeoutMs, body) {
11923
+ const url = new URL(path5, baseUrl + "/");
11585
11924
  const controller = new AbortController();
11586
11925
  const timer = setTimeout(() => controller.abort(), timeoutMs);
11587
11926
  try {
@@ -11782,7 +12121,7 @@ function loadIntegrations(dir) {
11782
12121
  function saveIntegrations(dir, integrations) {
11783
12122
  const abs = join(dir, INTEGRATIONS_FILE);
11784
12123
  const data = serializeIntegrationsConfig(integrations);
11785
- writeFile(abs, stringifyYaml5(data, { lineWidth: 120 }));
12124
+ writeFile(abs, stringifyYaml6(data, { lineWidth: 120 }));
11786
12125
  }
11787
12126
  function configStatus(integration, findings) {
11788
12127
  if (!integration.enabled) return "disabled";
@@ -12134,7 +12473,7 @@ function findLinkedWorkItem(dir, integrationId, externalId) {
12134
12473
  for (const art of discoverWorkItems(dir)) {
12135
12474
  let data;
12136
12475
  try {
12137
- data = matter11(readFile(art.filePath)).data;
12476
+ data = matter12(readFile(art.filePath)).data;
12138
12477
  } catch {
12139
12478
  continue;
12140
12479
  }
@@ -12150,7 +12489,7 @@ function buildImportIndex(dir) {
12150
12489
  for (const art of discoverWorkItems(dir)) {
12151
12490
  let data;
12152
12491
  try {
12153
- data = matter11(readFile(art.filePath)).data;
12492
+ data = matter12(readFile(art.filePath)).data;
12154
12493
  } catch {
12155
12494
  continue;
12156
12495
  }
@@ -12215,7 +12554,7 @@ ${item.description}` : item.title;
12215
12554
  }
12216
12555
 
12217
12556
  // src/core/telemetry-consent.ts
12218
- import { parse as parseYaml10, stringify as stringifyYaml6 } from "yaml";
12557
+ import { parse as parseYaml10, stringify as stringifyYaml7 } from "yaml";
12219
12558
  var CURRENT_CONSENT_VERSION = 1;
12220
12559
  var DEFERRAL_DURATION_MS = 24 * 60 * 60 * 1e3;
12221
12560
  function getConsentState(config) {
@@ -12244,7 +12583,7 @@ function persistConsent(dir, consent) {
12244
12583
  const prev = doc.telemetry ?? {};
12245
12584
  delete prev.enabled;
12246
12585
  doc.telemetry = { ...prev, consent, consentVersion: CURRENT_CONSENT_VERSION };
12247
- writeFile(configPath, stringifyYaml6(doc));
12586
+ writeFile(configPath, stringifyYaml7(doc));
12248
12587
  }
12249
12588
  function isDeferralActive(dir) {
12250
12589
  const p = join(dir, ".kaddo", "telemetry-deferred.json");
@@ -12326,7 +12665,7 @@ function getStatus(dir) {
12326
12665
  }
12327
12666
 
12328
12667
  // src/core/initiative-write.ts
12329
- import matter12 from "gray-matter";
12668
+ import matter13 from "gray-matter";
12330
12669
  var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
12331
12670
  var DRAFT_DIR = `${WORK_ITEMS_DIR2}/draft`;
12332
12671
  var ROADMAP_PATH2 = "knowledge/delivery/roadmap.md";
@@ -12439,7 +12778,7 @@ function buildInitiativeContent(id, input) {
12439
12778
  if (input.priority) data.priority = input.priority;
12440
12779
  if (input.source) data.source = input.source;
12441
12780
  if (input.sourceId) data.source_id = input.sourceId;
12442
- return matter12.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12781
+ return matter13.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
12443
12782
  }
12444
12783
  function createInitiative(dir, input) {
12445
12784
  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -12463,10 +12802,10 @@ function transitionInitiative(dir, id, to) {
12463
12802
  throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
12464
12803
  }
12465
12804
  const raw = readFile(ini.filePath);
12466
- const { data, content } = matter12(raw, {});
12805
+ const { data, content } = matter13(raw, {});
12467
12806
  data.status = to;
12468
12807
  if (to === "completed") data.completed_at = today();
12469
- const newContent = matter12.stringify(content, data);
12808
+ const newContent = matter13.stringify(content, data);
12470
12809
  writeFile(ini.filePath, newContent);
12471
12810
  const updated = parseInitiative(dir, ini.filePath, newContent);
12472
12811
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -12476,7 +12815,7 @@ function addCandidate(dir, id, candidate) {
12476
12815
  const ini = getInitiative(dir, id);
12477
12816
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12478
12817
  const raw = readFile(ini.filePath);
12479
- const { data, content } = matter12(raw, {});
12818
+ const { data, content } = matter13(raw, {});
12480
12819
  const existing = Array.isArray(data.candidates) ? data.candidates : [];
12481
12820
  const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
12482
12821
  const normalized = normalizeCandidate(candidate, fallbackId);
@@ -12484,7 +12823,7 @@ function addCandidate(dir, id, candidate) {
12484
12823
  throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
12485
12824
  }
12486
12825
  data.candidates = [...existing, candidateToData(normalized)];
12487
- const newContent = matter12.stringify(content, data);
12826
+ const newContent = matter13.stringify(content, data);
12488
12827
  writeFile(ini.filePath, newContent);
12489
12828
  const updated = parseInitiative(dir, ini.filePath, newContent);
12490
12829
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
@@ -12494,7 +12833,7 @@ function updateInitiative(dir, id, patch) {
12494
12833
  const ini = getInitiative(dir, id);
12495
12834
  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
12496
12835
  const raw = readFile(ini.filePath);
12497
- const { data, content } = matter12(raw, {});
12836
+ const { data, content } = matter13(raw, {});
12498
12837
  if (patch.title !== void 0) {
12499
12838
  if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
12500
12839
  data.title = patch.title.trim();
@@ -12504,7 +12843,7 @@ function updateInitiative(dir, id, patch) {
12504
12843
  if (patch.knowledgeLevel !== void 0) data.knowledge_level = patch.knowledgeLevel;
12505
12844
  if (patch.domains !== void 0) data.domains = patch.domains;
12506
12845
  if (patch.relatedCapabilities !== void 0) data.related_capabilities = patch.relatedCapabilities;
12507
- const newContent = matter12.stringify(content, data);
12846
+ const newContent = matter13.stringify(content, data);
12508
12847
  writeFile(ini.filePath, newContent);
12509
12848
  const updated = parseInitiative(dir, ini.filePath, newContent);
12510
12849
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
@@ -12522,10 +12861,10 @@ function addExternalLink(dir, id, link) {
12522
12861
  throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
12523
12862
  }
12524
12863
  const raw = readFile(ini.filePath);
12525
- const { data, content } = matter12(raw, {});
12864
+ const { data, content } = matter13(raw, {});
12526
12865
  const existing = Array.isArray(data.external_links) ? data.external_links : [];
12527
12866
  data.external_links = [...existing, externalLinkToData(link)];
12528
- const newContent = matter12.stringify(content, data);
12867
+ const newContent = matter13.stringify(content, data);
12529
12868
  writeFile(ini.filePath, newContent);
12530
12869
  const updated = parseInitiative(dir, ini.filePath, newContent);
12531
12870
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
@@ -12594,7 +12933,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
12594
12933
  "_What did we learn? Update after completion._",
12595
12934
  ""
12596
12935
  ].join("\n");
12597
- return matter12.stringify("\n" + body, data);
12936
+ return matter13.stringify("\n" + body, data);
12598
12937
  }
12599
12938
  function materializeCandidate(dir, id, candidateId) {
12600
12939
  const ini = getInitiative(dir, id);
@@ -12611,13 +12950,13 @@ function materializeCandidate(dir, id, candidateId) {
12611
12950
  ensureDir(join(dir, DRAFT_DIR));
12612
12951
  writeFile(join(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
12613
12952
  const raw = readFile(ini.filePath);
12614
- const { data, content } = matter12(raw, {});
12953
+ const { data, content } = matter13(raw, {});
12615
12954
  const cands = Array.isArray(data.candidates) ? data.candidates : [];
12616
12955
  for (const c of cands) {
12617
12956
  if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
12618
12957
  }
12619
12958
  data.candidates = cands;
12620
- const newContent = matter12.stringify(content, data);
12959
+ const newContent = matter13.stringify(content, data);
12621
12960
  writeFile(ini.filePath, newContent);
12622
12961
  const updated = parseInitiative(dir, ini.filePath, newContent);
12623
12962
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -12775,9 +13114,11 @@ export {
12775
13114
  InitiativeWriteError,
12776
13115
  IntegrationError,
12777
13116
  IntegrationServiceError,
13117
+ POC_ARTIFACT_PATH,
12778
13118
  RESOURCE_ARTIFACT_TYPE,
12779
13119
  RESOURCE_ROLES,
12780
13120
  RESOURCE_TYPES,
13121
+ ResourceWriteError,
12781
13122
  TOPOLOGY_FILE,
12782
13123
  TopologyWriteError,
12783
13124
  WorkItemNotFoundError,
@@ -12805,10 +13146,12 @@ export {
12805
13146
  consentNotice,
12806
13147
  createInitiative,
12807
13148
  createIntegration,
13149
+ createResource,
12808
13150
  createWorkItem,
12809
13151
  cwd,
12810
13152
  deferConsent,
12811
13153
  deleteIntegration,
13154
+ deleteResource,
12812
13155
  detectFormat,
12813
13156
  disableIntegration,
12814
13157
  discoverExternalWorkItems,
@@ -12834,6 +13177,7 @@ export {
12834
13177
  getIntegrationFilters,
12835
13178
  getIntegrationSecretStatus,
12836
13179
  getResource,
13180
+ getResourceReferences,
12837
13181
  getResources,
12838
13182
  getSystemMapProjection,
12839
13183
  getSystemNeighbors,
@@ -12868,14 +13212,18 @@ export {
12868
13212
  nextInitiativeId,
12869
13213
  parseContent,
12870
13214
  parseInitiative,
13215
+ parseScope,
12871
13216
  parseSuccessCriteria,
12872
13217
  parseWorkItemResources,
12873
13218
  persistConsent,
12874
13219
  previewImport,
13220
+ projectMode,
12875
13221
  readFile,
13222
+ readPocSummary,
12876
13223
  removeIntegrationSecret,
12877
13224
  searchSystemNodes,
12878
13225
  setIntegrationSecret,
13226
+ setProjectMode,
12879
13227
  suggestInitiativesForExternalItem,
12880
13228
  topologyRevision,
12881
13229
  transitionInitiative,
@@ -12883,8 +13231,10 @@ export {
12883
13231
  updateInitiative,
12884
13232
  updateIntegration,
12885
13233
  updateIntegrationFilters,
13234
+ updateResource,
12886
13235
  updateWorkItem,
12887
13236
  validateConfigAgainstSchema,
13237
+ validateResource,
12888
13238
  validateSystemTopology,
12889
13239
  validateTopologyProposal,
12890
13240
  validateWorkItem,