@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 +7 -1
- package/dist/core.js +14 -8
- package/dist/index.js +149 -122
- package/package.json +1 -1
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
|
-
|
|
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: "
|
|
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 = {
|
|
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: "
|
|
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,
|
|
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"),
|
|
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"),
|
|
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"),
|
|
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
|
|
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
|
|
726
|
-
if (!
|
|
727
|
-
console.log(`Project mode: ${projectMode(
|
|
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
|
|
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:
|
|
1509
|
-
frameworks:
|
|
1510
|
-
packageManagers:
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
1558
|
-
parts.push(
|
|
1559
|
-
parts.push(
|
|
1560
|
-
parts.push(
|
|
1561
|
-
parts.push(
|
|
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(
|
|
1567
|
-
parts.push(
|
|
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
|
|
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
|
-
|
|
10939
|
-
|
|
10940
|
-
|
|
10941
|
-
|
|
10942
|
-
|
|
10943
|
-
|
|
10944
|
-
|
|
10945
|
-
|
|
10946
|
-
|
|
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: "
|
|
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 = {
|
|
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: "
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`${
|
|
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
|
|