@burtson-labs/agent-core 1.6.47 → 1.6.49

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export declare const createAgentRuntime: (options?: CreateAgentRuntimeOptions) =
 export * from './tools';
 export * from './graph';
 export * from './suggestions';
+export * from './lessons';
+export * from './spec';
 export * from './mcp';
 export { redactSecrets, redactSecretsString, BUILTIN_SECRET_PATTERNS, type SecretPattern, type RedactionResult } from './security/secretPatterns';
 export { TelemetryExporter, resolveTelemetryConfig, TTFT_BUCKETS, DURATION_BUCKETS, type TelemetryConfig } from './telemetry/otlpExporter';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,yBAA0B,SAAQ,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC;IAC/F,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAS,yBAA8B,KAAG,YAO5E,CAAC;AAGF,cAAc,SAAS,CAAC;AAGxB,cAAc,SAAS,CAAC;AAExB,cAAc,eAAe,CAAC;AAK9B,cAAc,OAAO,CAAC;AAKtB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,yBAA0B,SAAQ,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC;IAC/F,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAS,yBAA8B,KAAG,YAO5E,CAAC;AAGF,cAAc,SAAS,CAAC;AAGxB,cAAc,SAAS,CAAC;AAExB,cAAc,eAAe,CAAC;AAE9B,cAAc,WAAW,CAAC;AAE1B,cAAc,QAAQ,CAAC;AAKvB,cAAc,OAAO,CAAC;AAKtB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -43,6 +43,10 @@ __exportStar(require("./tools"), exports);
 __exportStar(require("./graph"), exports);
 // Next-prompt prediction (composer "what's next?" suggestions).
 __exportStar(require("./suggestions"), exports);
+// Learning memory — distill durable repo lessons from turns (host stores them).
+__exportStar(require("./lessons"), exports);
+// Spec-driven development — spec markdown → graph plan (criteria = contracts).
+__exportStar(require("./spec"), exports);
 // MCP — Model Context Protocol client (Phase 1: groundwork). See
 // docs/integration-playlist/mcp-roadmap.md. Off by default — hosts
 // that don't construct an McpClientPool get zero behavior change.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AACA,yDAAsD;AACtD,+EAAiF;AAGjF,gDAA8B;AAC9B,gDAA8B;AAC9B,uCAAkD;AAAzC,0GAAA,iBAAiB,OAAA;AAE1B,+DAIqC;AADnC,oHAAA,iBAAiB,OAAA;AAGnB,6EAG4C;AAF1C,qIAAA,2BAA2B,OAAA;AAI7B,uDAUgC;AAT9B,4GAAA,YAAY,OAAA;AAeP,MAAM,kBAAkB,GAAG,CAAC,UAAqC,EAAE,EAAgB,EAAE;IAC1F,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,QAAQ,GAAG,gBAAgB,IAAI,IAAI,oDAA2B,EAAE,CAAC;IACvE,OAAO,IAAI,2BAAY,CAAC;QACtB,QAAQ;QACR,GAAI,IAA8C;KACnD,CAAC,CAAC;AACL,CAAC,CAAC;AAPW,QAAA,kBAAkB,sBAO7B;AAEF,cAAc;AACd,0CAAwB;AACxB,uEAAuE;AACvE,8EAA8E;AAC9E,0CAAwB;AACxB,gEAAgE;AAChE,gDAA8B;AAE9B,iEAAiE;AACjE,mEAAmE;AACnE,kEAAkE;AAClE,wCAAsB;AAEtB,wDAAwD;AACxD,mEAAmE;AACnE,4CAA4C;AAC5C,4DAMmC;AALjC,+GAAA,aAAa,OAAA;AACb,qHAAA,mBAAmB,OAAA;AACnB,yHAAA,uBAAuB,OAAA;AAKzB,iFAAiF;AACjF,iFAAiF;AACjF,yDAMkC;AALhC,iHAAA,iBAAiB,OAAA;AACjB,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,gHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AACA,yDAAsD;AACtD,+EAAiF;AAGjF,gDAA8B;AAC9B,gDAA8B;AAC9B,uCAAkD;AAAzC,0GAAA,iBAAiB,OAAA;AAE1B,+DAIqC;AADnC,oHAAA,iBAAiB,OAAA;AAGnB,6EAG4C;AAF1C,qIAAA,2BAA2B,OAAA;AAI7B,uDAUgC;AAT9B,4GAAA,YAAY,OAAA;AAeP,MAAM,kBAAkB,GAAG,CAAC,UAAqC,EAAE,EAAgB,EAAE;IAC1F,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,QAAQ,GAAG,gBAAgB,IAAI,IAAI,oDAA2B,EAAE,CAAC;IACvE,OAAO,IAAI,2BAAY,CAAC;QACtB,QAAQ;QACR,GAAI,IAA8C;KACnD,CAAC,CAAC;AACL,CAAC,CAAC;AAPW,QAAA,kBAAkB,sBAO7B;AAEF,cAAc;AACd,0CAAwB;AACxB,uEAAuE;AACvE,8EAA8E;AAC9E,0CAAwB;AACxB,gEAAgE;AAChE,gDAA8B;AAC9B,gFAAgF;AAChF,4CAA0B;AAC1B,+EAA+E;AAC/E,yCAAuB;AAEvB,iEAAiE;AACjE,mEAAmE;AACnE,kEAAkE;AAClE,wCAAsB;AAEtB,wDAAwD;AACxD,mEAAmE;AACnE,4CAA4C;AAC5C,4DAMmC;AALjC,+GAAA,aAAa,OAAA;AACb,qHAAA,mBAAmB,OAAA;AACnB,yHAAA,uBAAuB,OAAA;AAKzB,iFAAiF;AACjF,iFAAiF;AACjF,yDAMkC;AALhC,iHAAA,iBAAiB,OAAA;AACjB,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,gHAAA,gBAAgB,OAAA"}

package/dist/lessons.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Learning memory — the distiller half.
+ *
+ * After a turn, the host may make ONE cheap model call asking: did anything
+ * DURABLE and REPO-GENERAL happen here worth remembering for future tasks?
+ * ("this project uses pnpm, not npm"; "tests for src/api live in test/api";
+ * "the build fails unless you run codegen first"). Most turns yield nothing —
+ * the point is to accrue a SMALL set of high-signal, reusable facts about a
+ * specific repo, not a diary. Those facts are stored (see host-kit's lesson
+ * store) and injected on future turns so the agent gets better at THIS repo
+ * over time.
+ *
+ * This module is the shared, host-agnostic core: build the (small) prompt,
+ * parse the reply into a lesson or nothing. Pure + fully unit-testable, same
+ * split as the planner and next-prompt suggestions. The host owns the model
+ * call, the persistence, and the opt-in gate (off by default — it's an extra
+ * call per turn, and a store the model writes to deserves a deliberate opt-in).
+ */
+export interface LessonTurn {
+    /** The user's prompt for the turn. */
+    prompt: string;
+    /** The assistant's final response. */
+    assistantResponse: string;
+    /** Tool names used this turn, in order (optional but sharpens distillation). */
+    toolsUsed?: string[];
+    /** Whether the turn succeeded, if the host knows (a failure often teaches
+     *  the most durable lesson — "X doesn't work here, do Y"). */
+    outcome?: 'ok' | 'error';
+}
+/** The sentinel a well-behaved model returns when nothing is worth storing. */
+export declare const NO_LESSON = "NONE";
+export declare function buildLessonPrompt(turn: LessonTurn): string;
+/**
+ * Parse the distiller reply into a lesson, or null when nothing was learned.
+ * Never throws. Filters NONE, empties, over-long/paragraph replies, and the
+ * "here's a lesson:" preamble the model sometimes adds.
+ */
+export declare function parseLesson(text: string): string | null;
+/** Normalize a lesson for dedup comparison (lowercase, collapse whitespace,
+ *  drop trailing punctuation). Two lessons that normalize equal are dupes. */
+export declare function normalizeLesson(lesson: string): string;
+//# sourceMappingURL=lessons.d.ts.map

package/dist/lessons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.d.ts","sourceRoot":"","sources":["../src/lessons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;kEAC8D;IAC9D,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;CAC1B;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAwB1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAevD;AAED;8EAC8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/lessons.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Learning memory — the distiller half.
+ *
+ * After a turn, the host may make ONE cheap model call asking: did anything
+ * DURABLE and REPO-GENERAL happen here worth remembering for future tasks?
+ * ("this project uses pnpm, not npm"; "tests for src/api live in test/api";
+ * "the build fails unless you run codegen first"). Most turns yield nothing —
+ * the point is to accrue a SMALL set of high-signal, reusable facts about a
+ * specific repo, not a diary. Those facts are stored (see host-kit's lesson
+ * store) and injected on future turns so the agent gets better at THIS repo
+ * over time.
+ *
+ * This module is the shared, host-agnostic core: build the (small) prompt,
+ * parse the reply into a lesson or nothing. Pure + fully unit-testable, same
+ * split as the planner and next-prompt suggestions. The host owns the model
+ * call, the persistence, and the opt-in gate (off by default — it's an extra
+ * call per turn, and a store the model writes to deserves a deliberate opt-in).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_LESSON = void 0;
+exports.buildLessonPrompt = buildLessonPrompt;
+exports.parseLesson = parseLesson;
+exports.normalizeLesson = normalizeLesson;
+/** The sentinel a well-behaved model returns when nothing is worth storing. */
+exports.NO_LESSON = 'NONE';
+function buildLessonPrompt(turn) {
+    const tools = turn.toolsUsed?.length ? `\nTools used: ${turn.toolsUsed.join(', ')}` : '';
+    const outcome = turn.outcome ? `\nOutcome: ${turn.outcome}` : '';
+    const clip = (s, n) => (s.length > n ? s.slice(0, n) + '…' : s);
+    return [
+        'You maintain a small memory of DURABLE facts about THIS specific repository, to help future coding tasks.',
+        'Look at the turn below and decide: did it reveal a fact that is (a) specific to this repo, (b) still true next week, and (c) genuinely useful for a future task?',
+        '',
+        'Good lessons (store these):',
+        '- "This project uses pnpm; npm install breaks the workspace."',
+        '- "Tests for src/api/* live in test/api/* and must be updated alongside."',
+        '- "The build needs `pnpm codegen` run before `pnpm build`."',
+        '',
+        'NOT lessons (never store these):',
+        '- Anything about this ONE task ("added a clamp function") — that\'s history, not a durable fact.',
+        '- Generic programming advice true of any repo.',
+        '- Anything you are not confident is actually true of this repo.',
+        '',
+        `Reply with ONE short sentence (the lesson, max ~140 chars) OR exactly "${exports.NO_LESSON}" if nothing durable was learned. Most turns are "${exports.NO_LESSON}". No preamble, no quotes, no markdown.`,
+        '',
+        '--- turn ---',
+        `User: ${clip(turn.prompt, 500)}`,
+        `Assistant: ${clip(turn.assistantResponse, 800)}${tools}${outcome}`,
+    ].join('\n');
+}
+/**
+ * Parse the distiller reply into a lesson, or null when nothing was learned.
+ * Never throws. Filters NONE, empties, over-long/paragraph replies, and the
+ * "here's a lesson:" preamble the model sometimes adds.
+ */
+function parseLesson(text) {
+    let s = (text ?? '').trim();
+    if (!s)
+        return null;
+    // Strip a leading "lesson:" / "fact:" label if present.
+    s = s.replace(/^\s*(lesson|fact|answer)\s*:\s*/i, '').trim();
+    // Strip surrounding quotes/backticks/markdown bullet.
+    s = s.replace(/^[-*]\s+/, '').replace(/^["'`]+|["'`]+$/g, '').trim();
+    if (!s)
+        return null;
+    // Explicit "nothing to learn" in any casing/punctuation.
+    if (/^none[.!]?$/i.test(s))
+        return null;
+    // A model that ignored instructions and wrote a paragraph isn't a lesson.
+    if (s.length > 200)
+        return null;
+    // Refuse suspiciously generic non-facts.
+    if (/^(no|n\/a|nothing|not applicable|no lesson)\b/i.test(s))
+        return null;
+    return s;
+}
+/** Normalize a lesson for dedup comparison (lowercase, collapse whitespace,
+ *  drop trailing punctuation). Two lessons that normalize equal are dupes. */
+function normalizeLesson(lesson) {
+    return lesson.toLowerCase().replace(/\s+/g, ' ').replace(/[.!]+$/g, '').trim();
+}
+//# sourceMappingURL=lessons.js.map

package/dist/lessons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.js","sourceRoot":"","sources":["../src/lessons.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAiBH,8CAwBC;AAOD,kCAeC;AAID,0CAEC;AAvDD,+EAA+E;AAClE,QAAA,SAAS,GAAG,MAAM,CAAC;AAEhC,SAAgB,iBAAiB,CAAC,IAAgB;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,OAAO;QACL,2GAA2G;QAC3G,kKAAkK;QAClK,EAAE;QACF,6BAA6B;QAC7B,+DAA+D;QAC/D,2EAA2E;QAC3E,6DAA6D;QAC7D,EAAE;QACF,kCAAkC;QAClC,kGAAkG;QAClG,gDAAgD;QAChD,iEAAiE;QACjE,EAAE;QACF,0EAA0E,iBAAS,qDAAqD,iBAAS,yCAAyC;QAC1L,EAAE;QACF,cAAc;QACd,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;QACjC,cAAc,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,OAAO,EAAE;KACpE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,wDAAwD;IACxD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,kCAAkC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,sDAAsD;IACtD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,yDAAyD;IACzD,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,0EAA0E;IAC1E,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAChC,yCAAyC;IACzC,IAAI,gDAAgD,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,CAAC,CAAC;AACX,CAAC;AAED;8EAC8E;AAC9E,SAAgB,eAAe,CAAC,MAAc;IAC5C,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACjF,CAAC"}

package/dist/spec.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Spec-driven development — the shared core.
+ *
+ * A spec is a durable, human-written markdown artifact: a goal plus explicit
+ * acceptance criteria. It's the most leveraged thing a person can produce when
+ * an agent writes the code. This module turns that spec into a GRAPH PLAN:
+ * the planner (Phase 9) proposes nodes that implement the spec, and the
+ * acceptance criteria become the run's verification — the same completion-
+ * contract / verification-node machinery the graph runtime already enforces.
+ *
+ * So spec-driven dev here is a COMPOSITION, not a new engine: spec → planner →
+ * graph → contracts-as-acceptance-criteria. This file is pure (parse + prompt
+ * building), mirroring the planner/suggestions/lessons split; the host reads
+ * the file, runs the graph, and checks the criteria.
+ */
+export interface SpecDoc {
+    /** Title (the `# heading`). */
+    title: string;
+    /** The goal paragraph(s) under `## Goal`. */
+    goal: string;
+    /** Acceptance criteria (bullets/checkboxes under `## Acceptance criteria`).
+     *  These become the run's verification targets. */
+    criteria: string[];
+    /** Files/paths named under `## Context` (bias the plan toward real work). */
+    context: string[];
+    /** Hard constraints under `## Constraints` ("don't touch the public API"). */
+    constraints: string[];
+}
+/** A blank spec to scaffold with `bandit spec new`. */
+export declare function specTemplate(title: string): string;
+/**
+ * Parse a structured markdown spec. Lenient: a bare goal with no headings is
+ * treated as the goal; missing sections yield empty arrays. Checkbox markers
+ * (`- [ ]` / `- [x]`) and plain bullets both count as criteria.
+ */
+export declare function parseSpec(markdown: string): SpecDoc;
+export interface SpecValidation {
+    ok: boolean;
+    errors: string[];
+}
+/** A spec is runnable only if it has a goal and at least one criterion. */
+export declare function validateSpec(spec: SpecDoc): SpecValidation;
+/**
+ * Build the planner prompt for a spec. It asks for the SAME GraphProposal JSON
+ * the planner already emits (so parseGraphProposal validates it), but seeded
+ * with the spec: implementation nodes for the work, then a final verification
+ * node whose job is to check every acceptance criterion. The host maps that
+ * final node to a completion contract, so "did we meet the spec?" is enforced
+ * by the graph runtime, not asserted in prose.
+ */
+export declare function buildSpecPlanPrompt(spec: SpecDoc, maxNodes?: number): string;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,OAAO;IACtB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb;uDACmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAkDnD;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAK1D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAyBvE"}

package/dist/spec.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Spec-driven development — the shared core.
+ *
+ * A spec is a durable, human-written markdown artifact: a goal plus explicit
+ * acceptance criteria. It's the most leveraged thing a person can produce when
+ * an agent writes the code. This module turns that spec into a GRAPH PLAN:
+ * the planner (Phase 9) proposes nodes that implement the spec, and the
+ * acceptance criteria become the run's verification — the same completion-
+ * contract / verification-node machinery the graph runtime already enforces.
+ *
+ * So spec-driven dev here is a COMPOSITION, not a new engine: spec → planner →
+ * graph → contracts-as-acceptance-criteria. This file is pure (parse + prompt
+ * building), mirroring the planner/suggestions/lessons split; the host reads
+ * the file, runs the graph, and checks the criteria.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specTemplate = specTemplate;
+exports.parseSpec = parseSpec;
+exports.validateSpec = validateSpec;
+exports.buildSpecPlanPrompt = buildSpecPlanPrompt;
+/** A blank spec to scaffold with `bandit spec new`. */
+function specTemplate(title) {
+    const t = title.trim() || 'Untitled feature';
+    return [
+        `# ${t}`,
+        '',
+        '## Goal',
+        '<One short paragraph: what should be true when this is done, and why.>',
+        '',
+        '## Acceptance criteria',
+        '- [ ] <A concrete, checkable outcome — e.g. "GET /health returns 200 with {status:\'ok\'}">',
+        '- [ ] <Another — keep each one independently verifiable>',
+        '',
+        '## Context',
+        '- <path/to/relevant/file.ts>',
+        '',
+        '## Constraints',
+        '- <e.g. "Do not change the public API in src/index.ts">',
+        ''
+    ].join('\n');
+}
+/**
+ * Parse a structured markdown spec. Lenient: a bare goal with no headings is
+ * treated as the goal; missing sections yield empty arrays. Checkbox markers
+ * (`- [ ]` / `- [x]`) and plain bullets both count as criteria.
+ */
+function parseSpec(markdown) {
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    let title = '';
+    const sections = new Map();
+    let current = 'goal'; // text before the first heading is the goal
+    for (const line of lines) {
+        const h1 = /^#\s+(.+)$/.exec(line);
+        const h2 = /^##\s+(.+)$/.exec(line);
+        if (h1 && !title) {
+            title = h1[1].trim();
+            continue;
+        }
+        if (h2) {
+            current = h2[1].trim().toLowerCase();
+            if (!sections.has(current))
+                sections.set(current, []);
+            continue;
+        }
+        const bucket = sections.get(current) ?? [];
+        bucket.push(line);
+        sections.set(current, bucket);
+    }
+    const bullets = (key) => (sections.get(key) ?? [])
+        .map((l) => l.trim())
+        .map((l) => l.replace(/^[-*]\s+(\[[ xX]\]\s*)?/, '')) // strip bullet + optional checkbox
+        .filter((l) => l.length > 0 && !/^<.*>$/.test(l)); // drop empties + template placeholders
+    const paragraph = (key) => (sections.get(key) ?? [])
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !/^<.*>$/.test(l))
+        .join(' ')
+        .trim();
+    // Accept a few heading aliases people actually type.
+    const criteria = bullets('acceptance criteria').length
+        ? bullets('acceptance criteria')
+        : bullets('criteria').length
+            ? bullets('criteria')
+            : bullets('requirements');
+    return {
+        title: title || 'Untitled spec',
+        goal: paragraph('goal'),
+        criteria,
+        context: bullets('context'),
+        constraints: bullets('constraints')
+    };
+}
+/** A spec is runnable only if it has a goal and at least one criterion. */
+function validateSpec(spec) {
+    const errors = [];
+    if (!spec.goal.trim())
+        errors.push('spec has no ## Goal');
+    if (spec.criteria.length === 0)
+        errors.push('spec has no ## Acceptance criteria (need at least one checkable outcome)');
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * Build the planner prompt for a spec. It asks for the SAME GraphProposal JSON
+ * the planner already emits (so parseGraphProposal validates it), but seeded
+ * with the spec: implementation nodes for the work, then a final verification
+ * node whose job is to check every acceptance criterion. The host maps that
+ * final node to a completion contract, so "did we meet the spec?" is enforced
+ * by the graph runtime, not asserted in prose.
+ */
+function buildSpecPlanPrompt(spec, maxNodes = 6) {
+    const criteria = spec.criteria.map((c, i) => `  ${i + 1}. ${c}`).join('\n');
+    const context = spec.context.length ? `\nRelevant files:\n${spec.context.map((c) => `  - ${c}`).join('\n')}` : '';
+    const constraints = spec.constraints.length ? `\nConstraints (must honor):\n${spec.constraints.map((c) => `  - ${c}`).join('\n')}` : '';
+    return [
+        `You are planning how to implement a SPEC as a dependency graph. Output ONE JSON object in a \`\`\`json fence and nothing else.`,
+        '',
+        `Spec: ${spec.title}`,
+        `Goal: ${spec.goal}`,
+        '',
+        'Acceptance criteria (the definition of done):',
+        criteria,
+        context,
+        constraints,
+        '',
+        'JSON shape (same as the planner):',
+        '{"kind":"graph","reason":"one sentence","nodes":[{"id":"kebab-case","label":"short","prompt":"self-contained instruction","dependsOn":["other-id"],"readOnly":false}]}',
+        '',
+        'Rules:',
+        `- Always "kind":"graph". Use 2-${maxNodes} nodes.`,
+        '- Early nodes do the implementation work, split by concern; ids kebab-case + unique; dependsOn lists only earlier ids; no cycles.',
+        '- The LAST node must be a verification node that depends on the others and checks EVERY acceptance criterion is satisfied, reporting per-criterion pass/fail. Give it id "verify-spec".',
+        '- Each node prompt is self-contained (its reader sees only that prompt + its dependencies\' results). Reference the specific criteria a node addresses.',
+        '- Mark investigation/verification nodes "readOnly": true.'
+    ].filter((l) => l !== '').join('\n');
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burtson-labs/agent-core",
-  "version": "1.6.47",
+  "version": "1.6.49",
   "author": {
     "name": "Burtson Labs",
     "email": "team@burtson.ai",