@kaddo/cli 3.117.0 → 3.118.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.
package/README.md CHANGED
@@ -61,7 +61,10 @@ a conclusion.
61
61
  kaddo init --mode poc
62
62
  # or change an existing project
63
63
  kaddo project mode poc
64
- kaddo bootstrap
64
+ # define the hypothesis and success criteria in knowledge/delivery/poc.md
65
+ kaddo context
66
+ kaddo understand
67
+ kaddo create spike
65
68
  ```
66
69
 
67
70
  The canonical record is `knowledge/delivery/poc.md`. It concludes as `validated`, `rejected`, or
@@ -69,6 +72,9 @@ The canonical record is `knowledge/delivery/poc.md`. It concludes as `validated`
69
72
  first experiment. Token savings can result from this focused context, but the goal is better
70
73
  evidence and decisions, not prompt optimization.
71
74
 
75
+ POC mode does not require the standard Business/Product knowledge baseline. Add technical context
76
+ or Project Resources only when they are relevant to the experiment.
77
+
72
78
  ## The Knowledge Model
73
79
 
74
80
  Kaddo organizes project knowledge into four layers under `knowledge/`:
package/dist/core.js CHANGED
@@ -3537,7 +3537,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
3537
3537
  if (projectMode(config) === "poc") {
3538
3538
  const poc = readPocSummary(dir);
3539
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}.` };
3540
+ return { id: "poc-artifact", phase: "POC Definition", label: "Create or restore the POC artifact.", command: "kaddo project mode poc", target: POC_ARTIFACT_PATH, reason: `Missing ${POC_ARTIFACT_PATH}.` };
3541
3541
  }
3542
3542
  if (!poc.hypothesisDefined) {
3543
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." };
@@ -3547,12 +3547,9 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
3547
3547
  }
3548
3548
  const qCurrentState2 = analyzeKnowledgeArtifact(dir, CS);
3549
3549
  const qCodebase2 = analyzeKnowledgeArtifact(dir, CB);
3550
- if (qCurrentState2 !== "useful" || qCodebase2 !== "useful") {
3550
+ if (exists(join(dir, ".kaddo", "scan.json")) && (qCurrentState2 !== "useful" || qCodebase2 !== "useful")) {
3551
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
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
3553
  const delivery = buildDeliveryState(dir);
3557
3554
  if (delivery.total_work_items === 0) {
3558
3555
  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." };
@@ -7790,6 +7787,11 @@ var definePocHypothesis = {
7790
7787
  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
7788
  }
7792
7789
  };
7790
+ var ensurePocArtifact = {
7791
+ id: "poc-artifact",
7792
+ label: "Create POC artifact",
7793
+ evaluate: (ctx) => exists(join(ctx.dir, POC_ARTIFACT_PATH)) ? { status: "done", evidence: [POC_ARTIFACT_PATH] } : { status: "current", command: "kaddo project mode poc", reason: "Create the canonical POC artifact before defining the experiment." }
7794
+ };
7793
7795
  var definePocCriteria = {
7794
7796
  id: "poc-success-criteria",
7795
7797
  label: "Define success criteria",
@@ -7798,11 +7800,15 @@ var definePocCriteria = {
7798
7800
  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
7801
  }
7800
7802
  };
7801
- var describePocTech = { ...describeArchitecture, id: "poc-technical-context", label: "Document minimal technical context" };
7803
+ var describePocTech = {
7804
+ id: "poc-technical-context",
7805
+ label: "Document minimal technical context",
7806
+ evaluate: (ctx) => ctx.hasScan ? describeArchitecture.evaluate(ctx) : { status: "optional", command: "kaddo scan", reason: "Add technical context only when the experiment needs to inspect existing code." }
7807
+ };
7802
7808
  var identifyPocResources = {
7803
7809
  id: "poc-resources",
7804
7810
  label: "Identify relevant resources",
7805
- evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "pending", command: "kaddo resources list" }
7811
+ evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "optional", command: "kaddo resources list", reason: "Add Project Resources only when the experiment depends on external systems." }
7806
7812
  };
7807
7813
  var createPocExperiment = {
7808
7814
  id: "poc-create-experiment",
@@ -7822,7 +7828,7 @@ var concludePoc = {
7822
7828
  return conclusion === "pending" ? { status: "pending", reason: "Record validated, rejected, or inconclusive from the evidence." } : { status: "done", evidence: [POC_ARTIFACT_PATH], reason: `Conclusion: ${conclusion}.` };
7823
7829
  }
7824
7830
  };
7825
- var POC_STEPS = [enableKaddo, bootstrapBaseline, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
7831
+ var POC_STEPS = [enableKaddo, ensurePocArtifact, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
7826
7832
  function stepsForState(state) {
7827
7833
  switch (state) {
7828
7834
  case "new":
package/dist/index.js CHANGED
@@ -94,6 +94,97 @@ async function ensureTelemetryConsent(dir, config) {
94
94
  persistConsent(dir, accepted ? "enabled" : "disabled");
95
95
  }
96
96
 
97
+ // src/core/poc.ts
98
+ var POC_ARTIFACT_PATH = "knowledge/delivery/poc.md";
99
+ function pocTemplate(projectName) {
100
+ return `---
101
+ type: poc
102
+ status: active
103
+ generated_by: kaddo-init
104
+ template_version: 1
105
+ ---
106
+
107
+ # ${projectName} \u2014 Proof of Concept
108
+
109
+ ## Problem
110
+
111
+ _What are we trying to understand or solve?_
112
+
113
+ ## Hypothesis
114
+
115
+ _What assumption are we testing?_
116
+
117
+ ## Expected Value
118
+
119
+ _Why is validating this worth doing?_
120
+
121
+ ## Scenario
122
+
123
+ _What concrete scenario will demonstrate the hypothesis?_
124
+
125
+ ## Success Criteria
126
+
127
+ - [ ] _Observable result that would support the hypothesis._
128
+
129
+ ## Constraints
130
+
131
+ _Technical, time, budget, compliance, or operational constraints._
132
+
133
+ ## Non-goals
134
+
135
+ _What this experiment intentionally will not prove or deliver._
136
+
137
+ ## Evidence
138
+
139
+ _Link experiments, Work Items, measurements, and observations here._
140
+
141
+ ## Conclusion
142
+
143
+ Status: pending
144
+ `;
145
+ }
146
+ function ensurePocArtifact(dir, projectName) {
147
+ const path13 = join(dir, POC_ARTIFACT_PATH);
148
+ if (exists(path13)) return false;
149
+ ensureDir(join(dir, "knowledge", "delivery"));
150
+ writeFile(path13, pocTemplate(projectName));
151
+ return true;
152
+ }
153
+ var PLACEHOLDER = /^[_<].*[_>]$|^(describe|list|document|what|how)\b/i;
154
+ function section(markdown, heading) {
155
+ const match = markdown.match(new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im"));
156
+ return match?.[1] ?? "";
157
+ }
158
+ function meaningful(text2) {
159
+ return text2.split(/\r?\n/).some((line) => {
160
+ const value = line.trim().replace(/^[-*]\s+(?:\[[^\]]+\]\s*)?/, "");
161
+ return Boolean(value) && !PLACEHOLDER.test(value) && !/^status:\s*(pending|tbd)$/i.test(value);
162
+ });
163
+ }
164
+ function readPocSummary(dir) {
165
+ const path13 = join(dir, POC_ARTIFACT_PATH);
166
+ if (!exists(path13)) {
167
+ return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
168
+ }
169
+ let markdown = "";
170
+ try {
171
+ markdown = readFile(path13);
172
+ } catch {
173
+ return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
174
+ }
175
+ const criteria = section(markdown, "Success Criteria").split(/\r?\n/).filter((line) => /^\s*[-*]\s+(?:\[[ xX]\]\s+)?/.test(line)).filter((line) => meaningful(line)).length;
176
+ const conclusionBody = section(markdown, "Conclusion");
177
+ const conclusionMatch = conclusionBody.match(/\b(?:status|outcome)\s*:\s*(validated|rejected|inconclusive)\b/i);
178
+ return {
179
+ exists: true,
180
+ hypothesisDefined: meaningful(section(markdown, "Hypothesis")),
181
+ successCriteriaCount: criteria,
182
+ constraintsDefined: meaningful(section(markdown, "Constraints")),
183
+ nonGoalsDefined: meaningful(section(markdown, "Non-goals")),
184
+ conclusion: conclusionMatch ? conclusionMatch[1].toLowerCase() : "pending"
185
+ };
186
+ }
187
+
97
188
  // src/commands/init.ts
98
189
  var KADDO_DIR = ".kaddo";
99
190
  var ARCH_DIR = "knowledge";
@@ -307,41 +398,6 @@ _What comes after the current cycle._
307
398
  _Ideas and intentions not yet committed._
308
399
  `;
309
400
  }
310
- function buildPoc(projectName) {
311
- return `---
312
- type: poc
313
- status: active
314
- generated_by: kaddo-init
315
- template_version: 1
316
- ---
317
-
318
- # ${projectName} \u2014 Proof of Concept
319
-
320
- ## Hypothesis
321
-
322
- _What assumption are we testing?_
323
-
324
- ## Success Criteria
325
-
326
- - [ ] _Observable result that would support the hypothesis._
327
-
328
- ## Constraints
329
-
330
- _Technical, time, budget, compliance, or operational constraints._
331
-
332
- ## Non-goals
333
-
334
- _What this experiment intentionally will not prove or deliver._
335
-
336
- ## Evidence
337
-
338
- _Link experiments, Work Items, measurements, and observations here._
339
-
340
- ## Conclusion
341
-
342
- Status: pending
343
- `;
344
- }
345
401
  async function runInit(opts = {}) {
346
402
  const dir = cwd();
347
403
  intro("kaddo init");
@@ -474,7 +530,7 @@ async function runInit(opts = {}) {
474
530
  }
475
531
  if (mode === "poc") {
476
532
  ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
477
- writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), buildPoc(projectName.trim()));
533
+ writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), pocTemplate(projectName.trim()));
478
534
  log.success("Created knowledge/delivery/poc.md");
479
535
  }
480
536
  log.success("Created knowledge/tech/module/module-context.md");
@@ -489,7 +545,7 @@ async function runInit(opts = {}) {
489
545
  ensureDir(join(dir, ARCH_DIR, "agents"));
490
546
  ensureDir(join(dir, ARCH_DIR, "skills"));
491
547
  writeFile(join(dir, ARCH_DIR, "knowledge.md"), buildKnowledge(projectName.trim()));
492
- if (mode === "poc") writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), buildPoc(projectName.trim()));
548
+ if (mode === "poc") writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), pocTemplate(projectName.trim()));
493
549
  else writeFile(join(dir, ARCH_DIR, "delivery", "roadmap.md"), buildRoadmap(projectName.trim()));
494
550
  writeFile(join(dir, ARCH_DIR, "tech", "system", "system-context.md"), buildSystemContext(sysName));
495
551
  writeFile(join(dir, ARCH_DIR, "tech", "modules", "modules.md"), buildModulesFile(sysName));
@@ -504,13 +560,13 @@ async function runInit(opts = {}) {
504
560
  } else {
505
561
  ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
506
562
  writeFile(join(dir, ARCH_DIR, "knowledge.md"), buildKnowledge(projectName.trim()));
507
- if (mode === "poc") writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), buildPoc(projectName.trim()));
563
+ if (mode === "poc") writeFile(join(dir, ARCH_DIR, "delivery", "poc.md"), pocTemplate(projectName.trim()));
508
564
  else writeFile(join(dir, ARCH_DIR, "delivery", "roadmap.md"), buildRoadmap(projectName.trim()));
509
565
  log.success("Created knowledge/knowledge.md");
510
566
  if (mode === "poc") log.success("Created knowledge/delivery/poc.md");
511
567
  else log.success("Created knowledge/delivery/roadmap.md");
512
568
  log.success("Created knowledge/delivery/work-items/");
513
- log.info(mode === "poc" ? "Next: define the POC hypothesis and success criteria, then complete the minimal baseline with `kaddo bootstrap`." : "Next: run `kaddo scan` to detect your stack.");
569
+ log.info(mode === "poc" ? "Next: define the POC hypothesis and success criteria in `knowledge/delivery/poc.md`." : "Next: run `kaddo scan` to detect your stack.");
514
570
  }
515
571
  if (isInteractive()) {
516
572
  const enableTelemetry = await confirm({
@@ -722,9 +778,9 @@ function runProjectMode(mode) {
722
778
  const dir = cwd();
723
779
  try {
724
780
  if (mode === void 0) {
725
- const config = loadConfig(dir);
726
- if (!config) throw new ConfigError("No .kaddo/config.yml found. Run `kaddo init` first.");
727
- console.log(`Project mode: ${projectMode(config)}`);
781
+ const config2 = loadConfig(dir);
782
+ if (!config2) throw new ConfigError("No .kaddo/config.yml found. Run `kaddo init` first.");
783
+ console.log(`Project mode: ${projectMode(config2)}`);
728
784
  return;
729
785
  }
730
786
  if (mode !== "standard" && mode !== "poc") {
@@ -732,7 +788,10 @@ function runProjectMode(mode) {
732
788
  process.exitCode = 1;
733
789
  return;
734
790
  }
735
- setProjectMode(dir, mode);
791
+ const config = setProjectMode(dir, mode);
792
+ if (mode === "poc" && ensurePocArtifact(dir, config.project.name)) {
793
+ console.log("Created knowledge/delivery/poc.md");
794
+ }
736
795
  console.log(`Project mode set to: ${mode}`);
737
796
  } catch (err) {
738
797
  console.error(err instanceof ConfigError ? err.message : String(err));
@@ -1461,7 +1520,7 @@ import { parse as parseYaml4, stringify as stringifyYaml3 } from "yaml";
1461
1520
  import { parse as parseYaml3 } from "yaml";
1462
1521
  var SCAN_BASELINE_VERSION = "1";
1463
1522
  var UNKNOWN = "unknown";
1464
- function meaningful(...values) {
1523
+ function meaningful2(...values) {
1465
1524
  return values.filter((v) => v && v !== UNKNOWN && v !== "none");
1466
1525
  }
1467
1526
  function readProjectContext(dir) {
@@ -1505,9 +1564,9 @@ function buildBaseline(result, context, now = /* @__PURE__ */ new Date()) {
1505
1564
  generatedAt: now.toISOString(),
1506
1565
  project: context,
1507
1566
  detected: {
1508
- languages: meaningful(result.language),
1509
- frameworks: meaningful(result.framework),
1510
- packageManagers: meaningful(result.packageManager),
1567
+ languages: meaningful2(result.language),
1568
+ frameworks: meaningful2(result.framework),
1569
+ packageManagers: meaningful2(result.packageManager),
1511
1570
  sourceDirectories: result.codeDirs,
1512
1571
  migrationDirectories: result.migrationDirs,
1513
1572
  contractFiles: result.contractFiles,
@@ -1526,7 +1585,7 @@ function serializeBaseline(baseline) {
1526
1585
  }
1527
1586
 
1528
1587
  // src/templates/inventory-template.ts
1529
- function section(title, items, emptyNote = "_(none detected)_") {
1588
+ function section2(title, items, emptyNote = "_(none detected)_") {
1530
1589
  const body = items.length > 0 ? items.map((i) => `- ${i}`).join("\n") : emptyNote;
1531
1590
  return `## ${title}
1532
1591
 
@@ -1541,30 +1600,30 @@ function renderInventory(baseline) {
1541
1600
  "> Generated by `kaddo scan`. Deterministic technical baseline \u2014 not an interpretation of the system.\n"
1542
1601
  );
1543
1602
  parts.push(
1544
- section("Project Context", [
1603
+ section2("Project Context", [
1545
1604
  `State: ${project.state}`,
1546
1605
  `Structure: ${project.structure}`,
1547
1606
  `Team size: ${project.teamSize}`
1548
1607
  ])
1549
1608
  );
1550
1609
  parts.push(
1551
- section("Detected Stack", [
1610
+ section2("Detected Stack", [
1552
1611
  `Language: ${detected.languages.join(", ") || "unknown"}`,
1553
1612
  `Framework: ${detected.frameworks.join(", ") || "unknown"}`,
1554
1613
  `Package manager: ${detected.packageManagers.join(", ") || "unknown"}`
1555
1614
  ])
1556
1615
  );
1557
- parts.push(section("Source Directories", detected.sourceDirectories.map((d) => `${d}/`)));
1558
- parts.push(section("Migrations", detected.migrationDirectories.map((d) => `${d}/`)));
1559
- parts.push(section("Contracts", detected.contractFiles));
1560
- parts.push(section("Infrastructure", detected.infrastructureFiles));
1561
- parts.push(section("Tests", detected.testDirectories.map((d) => `${d}/`)));
1616
+ parts.push(section2("Source Directories", detected.sourceDirectories.map((d) => `${d}/`)));
1617
+ parts.push(section2("Migrations", detected.migrationDirectories.map((d) => `${d}/`)));
1618
+ parts.push(section2("Contracts", detected.contractFiles));
1619
+ parts.push(section2("Infrastructure", detected.infrastructureFiles));
1620
+ parts.push(section2("Tests", detected.testDirectories.map((d) => `${d}/`)));
1562
1621
  if (signalCount(baseline.signals) > 0) {
1563
1622
  parts.push("## Detected Signals\n");
1564
1623
  parts.push(renderSignalsInventory(baseline.signals));
1565
1624
  }
1566
- parts.push(section("Possible Domains", suggestions.possibleDomains));
1567
- parts.push(section("Open Questions", suggestions.openQuestions));
1625
+ parts.push(section2("Possible Domains", suggestions.possibleDomains));
1626
+ parts.push(section2("Open Questions", suggestions.openQuestions));
1568
1627
  return parts.join("\n");
1569
1628
  }
1570
1629
 
@@ -10904,7 +10963,7 @@ function buildModuleCapsule(dir, moduleId, config) {
10904
10963
  usageNotes: []
10905
10964
  };
10906
10965
  }
10907
- function section2(title, items, placeholder) {
10966
+ function section3(title, items, placeholder) {
10908
10967
  if (items.length === 0) return `## ${title}
10909
10968
 
10910
10969
  _${placeholder}_
@@ -10935,15 +10994,15 @@ function renderCapsuleMarkdown(c) {
10935
10994
 
10936
10995
  ${c.purpose || "_To be completed by the capsule-agent._"}
10937
10996
  `,
10938
- section2("Responsibilities", c.responsibilities, "List what this system is responsible for."),
10939
- section2("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
10940
- section2("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
10941
- section2("Dependencies", c.dependencies, "List systems this one depends on."),
10942
- section2("Known Risks", c.knownRisks, "List integration risks consumers should know."),
10943
- section2("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
10944
- section2("Owners", c.owners, "Who owns this system."),
10945
- section2("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
10946
- section2("Usage Notes", c.usageNotes, "How consumers should integrate."),
10997
+ section3("Responsibilities", c.responsibilities, "List what this system is responsible for."),
10998
+ section3("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
10999
+ section3("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
11000
+ section3("Dependencies", c.dependencies, "List systems this one depends on."),
11001
+ section3("Known Risks", c.knownRisks, "List integration risks consumers should know."),
11002
+ section3("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
11003
+ section3("Owners", c.owners, "Who owns this system."),
11004
+ section3("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
11005
+ section3("Usage Notes", c.usageNotes, "How consumers should integrate."),
10947
11006
  "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.",
10948
11007
  ""
10949
11008
  ];
@@ -12898,43 +12957,6 @@ function buildTechDecisions(dir) {
12898
12957
  };
12899
12958
  }
12900
12959
 
12901
- // src/core/poc.ts
12902
- var POC_ARTIFACT_PATH = "knowledge/delivery/poc.md";
12903
- var PLACEHOLDER = /^[_<].*[_>]$|^(describe|list|document|what|how)\b/i;
12904
- function section3(markdown, heading) {
12905
- const match = markdown.match(new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im"));
12906
- return match?.[1] ?? "";
12907
- }
12908
- function meaningful2(text2) {
12909
- return text2.split(/\r?\n/).some((line) => {
12910
- const value = line.trim().replace(/^[-*]\s+(?:\[[^\]]+\]\s*)?/, "");
12911
- return Boolean(value) && !PLACEHOLDER.test(value) && !/^status:\s*(pending|tbd)$/i.test(value);
12912
- });
12913
- }
12914
- function readPocSummary(dir) {
12915
- const path13 = join(dir, POC_ARTIFACT_PATH);
12916
- if (!exists(path13)) {
12917
- return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
12918
- }
12919
- let markdown = "";
12920
- try {
12921
- markdown = readFile(path13);
12922
- } catch {
12923
- return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
12924
- }
12925
- const criteria = section3(markdown, "Success Criteria").split(/\r?\n/).filter((line) => /^\s*[-*]\s+(?:\[[ xX]\]\s+)?/.test(line)).filter((line) => meaningful2(line)).length;
12926
- const conclusionBody = section3(markdown, "Conclusion");
12927
- const conclusionMatch = conclusionBody.match(/\b(?:status|outcome)\s*:\s*(validated|rejected|inconclusive)\b/i);
12928
- return {
12929
- exists: true,
12930
- hypothesisDefined: meaningful2(section3(markdown, "Hypothesis")),
12931
- successCriteriaCount: criteria,
12932
- constraintsDefined: meaningful2(section3(markdown, "Constraints")),
12933
- nonGoalsDefined: meaningful2(section3(markdown, "Non-goals")),
12934
- conclusion: conclusionMatch ? conclusionMatch[1].toLowerCase() : "pending"
12935
- };
12936
- }
12937
-
12938
12960
  // src/core/next-step.ts
12939
12961
  function buildDeliveryState(dir) {
12940
12962
  const wis = discoverWorkItems(dir);
@@ -13025,7 +13047,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
13025
13047
  if (projectMode(config) === "poc") {
13026
13048
  const poc = readPocSummary(dir);
13027
13049
  if (!poc.exists) {
13028
- return { id: "bootstrap", phase: "Setup", label: "Run `kaddo bootstrap` to create the POC knowledge baseline.", command: "kaddo bootstrap", reason: `Missing ${POC_ARTIFACT_PATH}.` };
13050
+ return { id: "poc-artifact", phase: "POC Definition", label: "Create or restore the POC artifact.", command: "kaddo project mode poc", target: POC_ARTIFACT_PATH, reason: `Missing ${POC_ARTIFACT_PATH}.` };
13029
13051
  }
13030
13052
  if (!poc.hypothesisDefined) {
13031
13053
  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." };
@@ -13035,12 +13057,9 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
13035
13057
  }
13036
13058
  const qCurrentState2 = analyzeKnowledgeArtifact(dir, CS);
13037
13059
  const qCodebase2 = analyzeKnowledgeArtifact(dir, CB);
13038
- if (qCurrentState2 !== "useful" || qCodebase2 !== "useful") {
13060
+ if (exists(join(dir, ".kaddo", "scan.json")) && (qCurrentState2 !== "useful" || qCodebase2 !== "useful")) {
13039
13061
  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." };
13040
13062
  }
13041
- if (!exists(join(dir, "knowledge", "resources"))) {
13042
- 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." };
13043
- }
13044
13063
  const delivery = buildDeliveryState(dir);
13045
13064
  if (delivery.total_work_items === 0) {
13046
13065
  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." };
@@ -14068,6 +14087,11 @@ var definePocHypothesis = {
14068
14087
  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." };
14069
14088
  }
14070
14089
  };
14090
+ var ensurePocArtifact2 = {
14091
+ id: "poc-artifact",
14092
+ label: "Create POC artifact",
14093
+ evaluate: (ctx) => exists(join(ctx.dir, POC_ARTIFACT_PATH)) ? { status: "done", evidence: [POC_ARTIFACT_PATH] } : { status: "current", command: "kaddo project mode poc", reason: "Create the canonical POC artifact before defining the experiment." }
14094
+ };
14071
14095
  var definePocCriteria = {
14072
14096
  id: "poc-success-criteria",
14073
14097
  label: "Define success criteria",
@@ -14076,11 +14100,15 @@ var definePocCriteria = {
14076
14100
  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." };
14077
14101
  }
14078
14102
  };
14079
- var describePocTech = { ...describeArchitecture, id: "poc-technical-context", label: "Document minimal technical context" };
14103
+ var describePocTech = {
14104
+ id: "poc-technical-context",
14105
+ label: "Document minimal technical context",
14106
+ evaluate: (ctx) => ctx.hasScan ? describeArchitecture.evaluate(ctx) : { status: "optional", command: "kaddo scan", reason: "Add technical context only when the experiment needs to inspect existing code." }
14107
+ };
14080
14108
  var identifyPocResources = {
14081
14109
  id: "poc-resources",
14082
14110
  label: "Identify relevant resources",
14083
- evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "pending", command: "kaddo resources list" }
14111
+ evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "optional", command: "kaddo resources list", reason: "Add Project Resources only when the experiment depends on external systems." }
14084
14112
  };
14085
14113
  var createPocExperiment = {
14086
14114
  id: "poc-create-experiment",
@@ -14100,7 +14128,7 @@ var concludePoc = {
14100
14128
  return conclusion === "pending" ? { status: "pending", reason: "Record validated, rejected, or inconclusive from the evidence." } : { status: "done", evidence: [POC_ARTIFACT_PATH], reason: `Conclusion: ${conclusion}.` };
14101
14129
  }
14102
14130
  };
14103
- var POC_STEPS = [enableKaddo, bootstrapBaseline, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
14131
+ var POC_STEPS = [enableKaddo, ensurePocArtifact2, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
14104
14132
  function stepsForState(state) {
14105
14133
  switch (state) {
14106
14134
  case "new":
@@ -18114,13 +18142,6 @@ var STANDARD_FILE_TARGETS = [
18114
18142
  { path: "knowledge/tech/current-state.md", kind: "current-state" },
18115
18143
  { path: "knowledge/delivery/roadmap.md", kind: "roadmap" }
18116
18144
  ];
18117
- var POC_FILE_TARGETS = [
18118
- { path: "knowledge/business/business.md", kind: "business" },
18119
- { path: "knowledge/product/product.md", kind: "product" },
18120
- { path: "knowledge/tech/codebase.md", kind: "codebase" },
18121
- { path: "knowledge/tech/current-state.md", kind: "current-state" },
18122
- { path: "knowledge/delivery/poc.md", kind: "poc" }
18123
- ];
18124
18145
  var DIR_TARGETS = ["knowledge/tech/decisions", "knowledge/tech/discovery", "knowledge/delivery/work-items"];
18125
18146
  function withLanguageDirective(content, language) {
18126
18147
  if (language !== "es") return content;
@@ -18146,7 +18167,8 @@ function bootstrap(dir) {
18146
18167
  }
18147
18168
  } catch {
18148
18169
  }
18149
- for (const target of mode === "poc" ? POC_FILE_TARGETS : STANDARD_FILE_TARGETS) {
18170
+ if (mode === "poc") return { state, mode, written, skipped, createdDirs };
18171
+ for (const target of STANDARD_FILE_TARGETS) {
18150
18172
  const full = join(dir, target.path);
18151
18173
  if (exists(full)) {
18152
18174
  skipped.push(target.path);
@@ -18189,7 +18211,12 @@ async function runBootstrap(dir = cwd()) {
18189
18211
  const stateLabel3 = state === "pre-ai" ? "pre-ai" : state;
18190
18212
  log.info(`Project state: ${stateLabel3}`);
18191
18213
  log.info(`Project mode: ${mode}`);
18192
- log.info(`Creating ${mode === "poc" ? "POC" : stateLabel3} knowledge baseline.`);
18214
+ if (mode === "poc") {
18215
+ log.info("POC mode does not require a standard bootstrap. Define the hypothesis and success criteria in `knowledge/delivery/poc.md`.");
18216
+ outro("Nothing changed. POC mode uses a proportional, experiment-first baseline.");
18217
+ return;
18218
+ }
18219
+ log.info(`Creating ${stateLabel3} knowledge baseline.`);
18193
18220
  log.info("Existing files will not be overwritten.");
18194
18221
  const result = bootstrap(dir);
18195
18222
  console.log("");
@@ -18209,7 +18236,7 @@ async function runBootstrap(dir = cwd()) {
18209
18236
  );
18210
18237
  printCommandFooter("bootstrap");
18211
18238
  outro(
18212
- `${mode === "poc" ? "POC" : stateLabel3} knowledge baseline ready. Next: \`kaddo add agents\` (then \`kaddo add skills\`), ` + (mode === "poc" ? "then define the POC hypothesis and success criteria." : "and refine the knowledge with the relevant agents.")
18239
+ `${stateLabel3} knowledge baseline ready. Next: \`kaddo add agents\` (then \`kaddo add skills\`), and refine the knowledge with the relevant agents.`
18213
18240
  );
18214
18241
  }
18215
18242
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.117.0",
3
+ "version": "3.118.0",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {