agent-bober 0.17.1 → 0.19.0

package/dist/orchestrator/memory/hygiene.js

@@ -0,0 +1,153 @@
+/**
+ * PURE deterministic lesson hygiene: decay-based pruning + conflict quarantine.
+ *
+ * PURE — the clock is never read here; `now` is injected by the CLI handler
+ * (mirrors reconcileFact's { now } pattern at reconcile.ts:54). Operates
+ * ONLY on the fields each record carries; the CLI assembles recency input (createdAt)
+ * by reading per-lesson files and passing it in via PrunableLesson.createdAt.
+ *
+ * Conflict detection: DETERMINISTIC — two lessons sharing the same contradiction key
+ * (category root + discriminator tag) with opposing polarity markers are BOTH moved
+ * to quarantine. No LLM.
+ *
+ * Decay: lessons below `minOccurrences` that are also older than `maxAgeMs` are
+ * quarantined. Missing createdAt is treated as "maximally stale" (decays immediately
+ * when occurrences are below threshold), which is conservative and documented here
+ * as a deliberate choice — prefer to quarantine an unknown-age low-occurrence lesson
+ * rather than silently keep it forever.
+ */
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Default age threshold for decay: 30 days in milliseconds. */
+export const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+/** Polarity markers for conflict detection (keep vs. avoid). */
+const KEEP_MARKERS = new Set(["keep", "stable", "pass", "trusted"]);
+const AVOID_MARKERS = new Set(["avoid", "fragile", "fail", "untrusted"]);
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Derive the category root from a category string (substring before the first ":").
+ * e.g. "eval-strategy-failure:unit-test" → "eval-strategy-failure"
+ *      "sprint-rework" → "sprint-rework"
+ */
+function categoryRoot(category) {
+    const idx = category.indexOf(":");
+    return idx === -1 ? category : category.slice(0, idx);
+}
+/**
+ * Extract the first discriminator tag from a tag list.
+ * Priority: sprintId: > strategy: > verificationMethod:
+ * Falls back to the first tag present, or empty string.
+ */
+function discriminatorTag(tags) {
+    for (const prefix of ["sprintId:", "strategy:", "verificationMethod:"]) {
+        const found = tags.find((t) => t.startsWith(prefix));
+        if (found !== undefined)
+            return found;
+    }
+    return tags[0] ?? "";
+}
+/**
+ * Extract the polarity marker from a tag list.
+ * Returns "keep", "avoid", or "neutral" based on the first matching tag.
+ */
+function polarityOf(tags) {
+    for (const tag of tags) {
+        const bare = tag.toLowerCase();
+        if (KEEP_MARKERS.has(bare))
+            return "keep";
+        if (AVOID_MARKERS.has(bare))
+            return "avoid";
+    }
+    return "neutral";
+}
+/**
+ * Build the contradiction key for conflict detection.
+ * Two records with the same key and opposing polarity (keep vs. avoid) are conflicts.
+ */
+function contradictionKey(record) {
+    return `${categoryRoot(record.category)}|${discriminatorTag(record.tags)}`;
+}
+// ── Core ─────────────────────────────────────────────────────────────────────
+/**
+ * Partition lessons into kept vs. quarantined.
+ *
+ * Phase 1 (conflict detection): identifies deterministically contradictory pairs.
+ *   A pair is contradictory when both records share the same contradiction key
+ *   (category root + discriminator tag) AND carry opposing polarity markers
+ *   (one "keep"-marked, one "avoid"-marked). BOTH are quarantined.
+ *
+ * Phase 2 (decay): for remaining records, quarantines those below `minOccurrences`
+ *   that are also stale (createdAt older than maxAgeMs, or createdAt absent).
+ *
+ * Both output arrays are sorted by lessonId ASC for byte-identical repeated runs.
+ *
+ * @param records - Enriched lesson records (with optional createdAt from CLI)
+ * @param opts.now - ISO 8601 wall-clock, injected — never read inside
+ * @param opts.minOccurrences - Below-threshold occurrence count (default 2)
+ * @param opts.maxAgeMs - Staleness threshold in ms (default 30 days)
+ */
+export function pruneLessons(records, { now, minOccurrences = 2, maxAgeMs = THIRTY_DAYS_MS }) {
+    const nowMs = Date.parse(now);
+    // ── Phase 1: conflict detection ─────────────────────────────────────────
+    // Group by contradiction key, collecting polarity.
+    const byKey = new Map();
+    for (const rec of records) {
+        const key = contradictionKey(rec);
+        let bucket = byKey.get(key);
+        if (bucket === undefined) {
+            bucket = { keeps: [], avoids: [] };
+            byKey.set(key, bucket);
+        }
+        const polarity = polarityOf(rec.tags);
+        if (polarity === "keep") {
+            bucket.keeps.push(rec);
+        }
+        else if (polarity === "avoid") {
+            bucket.avoids.push(rec);
+        }
+        // "neutral" polarity: the record is bucketed but will not trigger a conflict on its own
+    }
+    // A conflict fires when a key has BOTH keep-marked AND avoid-marked records.
+    const conflictIds = new Set();
+    for (const [, bucket] of byKey) {
+        if (bucket.keeps.length > 0 && bucket.avoids.length > 0) {
+            for (const r of [...bucket.keeps, ...bucket.avoids]) {
+                conflictIds.add(r.lessonId);
+            }
+        }
+    }
+    // ── Phase 2: decay ───────────────────────────────────────────────────────
+    const decayIds = new Set();
+    for (const rec of records) {
+        if (conflictIds.has(rec.lessonId))
+            continue; // already quarantined by conflict
+        if (rec.occurrences >= minOccurrences)
+            continue; // well-established, keep
+        // Below minOccurrences: quarantine if stale (or no age info → maximally stale).
+        if (rec.createdAt === undefined) {
+            // No age info = unknown = treat as maximally stale → quarantine
+            decayIds.add(rec.lessonId);
+            continue;
+        }
+        const ageMs = nowMs - Date.parse(rec.createdAt);
+        if (ageMs > maxAgeMs) {
+            decayIds.add(rec.lessonId);
+        }
+    }
+    // ── Partition ────────────────────────────────────────────────────────────
+    const quarantinedSet = new Set([...conflictIds, ...decayIds]);
+    const kept = [];
+    const quarantined = [];
+    for (const rec of records) {
+        if (quarantinedSet.has(rec.lessonId)) {
+            quarantined.push(rec);
+        }
+        else {
+            kept.push(rec);
+        }
+    }
+    // Sort both arrays by lessonId for deterministic, byte-identical output.
+    kept.sort((a, b) => a.lessonId.localeCompare(b.lessonId));
+    quarantined.sort((a, b) => a.lessonId.localeCompare(b.lessonId));
+    return { kept, quarantined };
+}
+//# sourceMappingURL=hygiene.js.map

package/dist/orchestrator/memory/hygiene.js.map

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

package/dist/orchestrator/memory/reconcile.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PURE deterministic reconcile-on-write for semantic facts.
+ *
+ * PURE — never reads the clock (now is injected), never calls createClient,
+ * no network access, no Date.now(), no side effects beyond the injected store.
+ * The injected FactJudge is the ONLY async/LLM surface and is consulted ONLY
+ * on a deterministic normalized-key collision (the ambiguity branch).
+ * Exact-match NOOP/UPDATE/ADD never touch the judge or the network.
+ */
+import type { FactStore, FactInput } from "../../state/facts.js";
+import type { FactJudge } from "./fact-judge.js";
+export type ReconcileAction = "add" | "update" | "delete" | "noop";
+/**
+ * Reconcile an incoming fact against the active state in the store.
+ *
+ * Algorithm:
+ * 1. Query getActiveFacts(scope, subject, predicate) — exact key, active-only.
+ * 2. Exact match with SAME value → NOOP.
+ * 3. Exact match with DIFFERENT value → UPDATE:
+ *    supersedeFact(old.id, now, incoming.tValid) then insertFact(incoming).
+ * 4. No exact match → AMBIGUITY check via normalizeKey over all active facts in scope.
+ *    a. Collision AND judge provided → judge.resolve(incoming, candidate) → apply.
+ *    b. Collision but NO judge → deterministic ADD fallback.
+ *    c. No collision → ADD.
+ * 5. DELETE = supersedeFact(candidate.id, now, incoming.tValid) without inserting incoming.
+ *
+ * @param store - The FactStore to read from and write to.
+ * @param incoming - The incoming fact input (validated by insertFact on the ADD path).
+ * @param opts.judge - Optional LLM-backed judge for ambiguity resolution.
+ * @param opts.now - ISO 8601 wall-clock timestamp (record-time); NEVER read inside.
+ */
+export declare function reconcileFact(store: FactStore, incoming: FactInput, { judge, now }: {
+    judge?: FactJudge;
+    now: string;
+}): Promise<ReconcileAction>;
+/**
+ * Reconcile-then-write a fact. Wall-clock `now` is injected by the caller —
+ * this function never reads the clock (mirrors the store's purity contract).
+ *
+ * The `judge` is optional; when absent the exact-match UPDATE/NOOP paths run
+ * deterministically and ambiguous collisions fall back to ADD.
+ */
+export declare function writeFact(store: FactStore, incoming: FactInput, opts: {
+    judge?: FactJudge;
+    now: string;
+}): Promise<ReconcileAction>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/orchestrator/memory/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgBnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,SAAS,EACnB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAwCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,SAAS,EACnB,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/orchestrator/memory/reconcile.js

@@ -0,0 +1,116 @@
+/**
+ * PURE deterministic reconcile-on-write for semantic facts.
+ *
+ * PURE — never reads the clock (now is injected), never calls createClient,
+ * no network access, no Date.now(), no side effects beyond the injected store.
+ * The injected FactJudge is the ONLY async/LLM surface and is consulted ONLY
+ * on a deterministic normalized-key collision (the ambiguity branch).
+ * Exact-match NOOP/UPDATE/ADD never touch the judge or the network.
+ */
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Normalize a subject+predicate pair into a collision key.
+ * Lowercase + strip non-alphanumeric characters — mirrors tokenize() in retrieve.ts:30-35.
+ * Private to this module; do not import from retrieve.ts (it is not exported).
+ */
+function normalizeKey(subject, predicate) {
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+    return `${norm(subject)}|${norm(predicate)}`;
+}
+// ── Core ──────────────────────────────────────────────────────────────────
+/**
+ * Reconcile an incoming fact against the active state in the store.
+ *
+ * Algorithm:
+ * 1. Query getActiveFacts(scope, subject, predicate) — exact key, active-only.
+ * 2. Exact match with SAME value → NOOP.
+ * 3. Exact match with DIFFERENT value → UPDATE:
+ *    supersedeFact(old.id, now, incoming.tValid) then insertFact(incoming).
+ * 4. No exact match → AMBIGUITY check via normalizeKey over all active facts in scope.
+ *    a. Collision AND judge provided → judge.resolve(incoming, candidate) → apply.
+ *    b. Collision but NO judge → deterministic ADD fallback.
+ *    c. No collision → ADD.
+ * 5. DELETE = supersedeFact(candidate.id, now, incoming.tValid) without inserting incoming.
+ *
+ * @param store - The FactStore to read from and write to.
+ * @param incoming - The incoming fact input (validated by insertFact on the ADD path).
+ * @param opts.judge - Optional LLM-backed judge for ambiguity resolution.
+ * @param opts.now - ISO 8601 wall-clock timestamp (record-time); NEVER read inside.
+ */
+export async function reconcileFact(store, incoming, { judge, now }) {
+    // ── Step 1: Exact-key lookup (active only) ────────────────────────────
+    const exactMatches = store.getActiveFacts(incoming.scope, incoming.subject, incoming.predicate);
+    // ── Step 2: Same value → NOOP ─────────────────────────────────────────
+    if (exactMatches.length > 0) {
+        const same = exactMatches.find((r) => r.value === incoming.value);
+        if (same !== undefined) {
+            return "noop";
+        }
+        // ── Step 3: Different value → UPDATE (supersede) ─────────────────────
+        // Supersede every matching active row (normally only one, but be safe).
+        for (const old of exactMatches) {
+            // Set BOTH t_invalid (world-time = incoming tValid) AND t_invalidated (record-time = now)
+            store.supersedeFact(old.id, now, incoming.tValid);
+        }
+        store.insertFact(incoming);
+        return "update";
+    }
+    // ── Step 4: No exact match → Ambiguity check ─────────────────────────
+    const incomingKey = normalizeKey(incoming.subject, incoming.predicate);
+    const allActive = store.getActiveFacts(incoming.scope);
+    const candidate = allActive.find((r) => normalizeKey(r.subject, r.predicate) === incomingKey);
+    if (candidate !== undefined) {
+        // ── Step 4a: Collision AND judge → delegate ───────────────────────
+        if (judge !== undefined) {
+            const action = await judge.resolve(incoming, candidate);
+            return applyJudgeDecision(store, incoming, candidate, action, now);
+        }
+        // ── Step 4b: Collision but NO judge → deterministic ADD fallback ──
+        store.insertFact(incoming);
+        return "add";
+    }
+    // ── Step 4c: No collision → ADD ───────────────────────────────────────
+    store.insertFact(incoming);
+    return "add";
+}
+/**
+ * Apply a judge's decision to the store.
+ * DELETE = supersede candidate only; no insertFact.
+ */
+function applyJudgeDecision(store, incoming, candidate, action, now) {
+    switch (action) {
+        case "add":
+            store.insertFact(incoming);
+            return "add";
+        case "update":
+            store.supersedeFact(candidate.id, now, incoming.tValid);
+            store.insertFact(incoming);
+            return "update";
+        case "delete":
+            store.supersedeFact(candidate.id, now, incoming.tValid);
+            return "delete";
+        case "noop":
+            return "noop";
+        default: {
+            // Exhaustive check — if judge returns unknown action, fall back to ADD
+            store.insertFact(incoming);
+            return "add";
+        }
+    }
+}
+// ── writeFact ─────────────────────────────────────────────────────────────
+//
+// Thin wrapper that calls reconcileFact. Lives here (not in facts.ts) to
+// avoid a state→orchestrator import cycle at runtime.
+// The CLI and future consumers import writeFact from this module.
+/**
+ * Reconcile-then-write a fact. Wall-clock `now` is injected by the caller —
+ * this function never reads the clock (mirrors the store's purity contract).
+ *
+ * The `judge` is optional; when absent the exact-match UPDATE/NOOP paths run
+ * deterministically and ambiguous collisions fall back to ADD.
+ */
+export async function writeFact(store, incoming, opts) {
+    return reconcileFact(store, incoming, opts);
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/orchestrator/memory/reconcile.js.map

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

package/dist/orchestrator/memory/retrieve.d.ts

@@ -12,8 +12,9 @@ import type { LessonIndexRecord } from "../../state/memory.js";
  * to the given `keywords`.
  *
  * Scoring is deterministic token-overlap between the lowercased keyword tokens
- * and each record's tags + category + summarySnippet. Ties break by lessonId
- * (ASC lexicographic) for byte-stable output.
+ * and each record's tags + category + summarySnippet. When overlap scores tie,
+ * records with higher occurrences rank above lower-occurrence records.
+ * Final tiebreak is by lessonId ASC (lexicographic) for byte-stable output.
  *
  * A non-matching keyword set (no overlap with any record) yields an empty result.
  *
@@ -22,9 +23,10 @@ import type { LessonIndexRecord } from "../../state/memory.js";
  * @param options     - topK cap (default 5) and optional charBudget (ignored here; passed to serializer)
  * @returns At most topK records sorted by relevance (descending), then lessonId (ascending)
  */
-export declare function retrieveRelevantLessons(projectRoot: string, keywords: string[], { topK, charBudget: _charBudget, }?: {
+export declare function retrieveRelevantLessons(projectRoot: string, keywords: string[], { topK, charBudget: _charBudget, namespace, }?: {
     topK?: number;
     charBudget?: number;
+    namespace?: string;
 }): Promise<LessonIndexRecord[]>;
 /**
  * Render a compact planner context block from an array of LessonIndexRecord values.

package/dist/orchestrator/memory/retrieve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsD/D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAAE,EAClB,EACE,IAAoB,EACpB,UAAU,EAAE,WAAW,GACxB,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAAE,EAC5B,EAAE,UAAgC,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,MAAM,CAmBR"}
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsD/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAAE,EAClB,EACE,IAAoB,EACpB,UAAU,EAAE,WAAW,EACvB,SAAS,GACV,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAAE,EAC5B,EAAE,UAAgC,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,MAAM,CAmBR"}

package/dist/orchestrator/memory/retrieve.js

@@ -52,8 +52,9 @@ function scoreRecord(record, keywordTokens) {
  * to the given `keywords`.
  *
  * Scoring is deterministic token-overlap between the lowercased keyword tokens
- * and each record's tags + category + summarySnippet. Ties break by lessonId
- * (ASC lexicographic) for byte-stable output.
+ * and each record's tags + category + summarySnippet. When overlap scores tie,
+ * records with higher occurrences rank above lower-occurrence records.
+ * Final tiebreak is by lessonId ASC (lexicographic) for byte-stable output.
  *
  * A non-matching keyword set (no overlap with any record) yields an empty result.
  *
@@ -62,14 +63,16 @@ function scoreRecord(record, keywordTokens) {
  * @param options     - topK cap (default 5) and optional charBudget (ignored here; passed to serializer)
  * @returns At most topK records sorted by relevance (descending), then lessonId (ascending)
  */
-export async function retrieveRelevantLessons(projectRoot, keywords, { topK = DEFAULT_TOP_K, charBudget: _charBudget, } = {}) {
-    const records = await loadLessonIndex(projectRoot, { limit: INDEX_LOAD_LIMIT });
+export async function retrieveRelevantLessons(projectRoot, keywords, { topK = DEFAULT_TOP_K, charBudget: _charBudget, namespace, } = {}) {
+    const records = await loadLessonIndex(projectRoot, { limit: INDEX_LOAD_LIMIT }, namespace);
     const keywordTokens = new Set(keywords.flatMap(tokenize));
     const scored = records
         .map((r) => ({ r, score: scoreRecord(r, keywordTokens) }))
         .filter((x) => x.score > 0); // C1: non-matching keyword -> empty
-    // Sort: score DESC, then lessonId ASC for stable tiebreak
-    scored.sort((a, b) => b.score - a.score || a.r.lessonId.localeCompare(b.r.lessonId));
+    // Sort: score DESC, then occurrences DESC (tiebreak booster), then lessonId ASC (byte-stable)
+    scored.sort((a, b) => b.score - a.score || // 1. token overlap (DOMINANT)
+        b.r.occurrences - a.r.occurrences || // 2. higher occurrences win on ties (sc-3-2)
+        a.r.lessonId.localeCompare(b.r.lessonId));
     return scored.slice(0, topK).map((x) => x.r);
 }
 /**

package/dist/orchestrator/memory/retrieve.js.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve.js","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,uEAAuE;AAEvE,2CAA2C;AAC3C,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,iEAAiE;AACjE,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC,4EAA4E;AAC5E,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,wEAAwE;AAExE;;;GAGG;AACH,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,CAAC;SACL,WAAW,EAAE;SACb,KAAK,CAAC,YAAY,CAAC;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAClB,MAAyB,EACzB,aAA0B;IAE1B,IAAI,aAAa,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEvC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS;QACnC,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC5B,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QAChC,GAAG,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC;KACnC,CAAC,CAAC;IAEH,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wEAAwE;AAExE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAmB,EACnB,QAAkB,EAClB,EACE,IAAI,GAAG,aAAa,EACpB,UAAU,EAAE,WAAW,MACmB,EAAE;IAE9C,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAEhF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAG,OAAO;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;SACzD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,oCAAoC;IAEnE,0DAA0D;IAC1D,MAAM,CAAC,IAAI,CACT,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CACxE,CAAC;IAEF,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA4B,EAC5B,EAAE,UAAU,GAAG,mBAAmB,KAA8B,EAAE;IAElE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG;QACZ,qDAAqD;QACrD,EAAE;QACF,GAAG,OAAO,CAAC,GAAG,CACZ,CAAC,CAAC,EAAE,EAAE,CACJ,MAAM,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,WAAW,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,CACxG;QACD,EAAE;KACH,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE/B,+CAA+C;IAC/C,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"retrieve.js","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/model-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.d.ts","sourceRoot":"","sources":["../../src/orchestrator/model-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,gBAAgB,CAAC,EAAE,MAAM,GACxB,aAAa,CAgCf;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD"}
+{"version":3,"file":"model-resolver.d.ts","sourceRoot":"","sources":["../../src/orchestrator/model-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,gBAAgB,CAAC,EAAE,MAAM,GACxB,aAAa,CAgCf;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD"}

package/dist/orchestrator/model-resolver.js

@@ -28,6 +28,10 @@ const SHORTHAND_MAP = {
     deepseek: { provider: "openai-compat", modelId: "deepseek-v4-pro" },
     "deepseek-v4-pro": { provider: "openai-compat", modelId: "deepseek-v4-pro" },
     "deepseek-v4-flash": { provider: "openai-compat", modelId: "deepseek-v4-flash" },
+    // Grok / xAI — resolved via openai-compat adapter at api.x.ai/v1
+    grok: { provider: "openai-compat", modelId: "grok-4" },
+    "grok-4": { provider: "openai-compat", modelId: "grok-4" },
+    "grok-4-fast": { provider: "openai-compat", modelId: "grok-4-fast" },
 };
 /**
  * Resolve a model string and optional explicit provider into a ResolvedModel.
@@ -61,12 +65,12 @@ export function resolveProviderModel(model, explicitProvider) {
     const mapped = SHORTHAND_MAP[model];
     if (mapped) {
         if (mapped.provider === "openai-compat") {
-            // openai-compat shorthands (e.g. deepseek) need an endpoint attached.
-            return {
-                provider: mapped.provider,
-                modelId: mapped.modelId,
-                endpoint: "https://api.deepseek.com",
-            };
+            // openai-compat shorthands need an endpoint attached.
+            // Grok/xAI shorthands resolve to api.x.ai/v1; DeepSeek to api.deepseek.com.
+            const endpoint = mapped.modelId.startsWith("grok")
+                ? "https://api.x.ai/v1"
+                : "https://api.deepseek.com";
+            return { provider: mapped.provider, modelId: mapped.modelId, endpoint };
         }
         return { provider: mapped.provider, modelId: mapped.modelId };
     }

package/dist/orchestrator/model-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/orchestrator/model-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;;GAGG;AACH,MAAM,aAAa,GAA0D;IAC3E,YAAY;IACZ,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE;IAC3D,UAAU,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,iBAAiB;IACpF,UAAU,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,qBAAqB;IACxF,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,EAAE;IAC/D,KAAK,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE;IAC7D,SAAS;IACT,SAAS,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE;IACrD,cAAc,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE;IAC/D,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;IACzC,SAAS,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE;IACrD,SAAS;IACT,YAAY,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE;IAC/D,cAAc,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,EAAE;IACnE,oEAAoE;IACpE,QAAQ,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,EAAE;IACnE,iBAAiB,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,EAAE;IAC5E,mBAAmB,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE;CACjF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAa,EACb,gBAAyB;IAEzB,oEAAoE;IACpE,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IAED,qDAAqD;IACrD,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9C,OAAO;YACL,QAAQ,EAAE,eAAe;YACzB,OAAO;YACP,QAAQ,EAAE,2BAA2B;SACtC,CAAC;IACJ,CAAC;IAED,qBAAqB;IACrB,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,CAAC,QAAQ,KAAK,eAAe,EAAE,CAAC;YACxC,sEAAsE;YACtE,OAAO;gBACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,QAAQ,EAAE,0BAA0B;aACrC,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAChE,CAAC;IAED,+DAA+D;IAC/D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/orchestrator/model-resolver.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/pipeline.d.ts

@@ -14,7 +14,7 @@ import type { BoberConfig } from "../config/schema.js";
 import type { PlanSpec } from "../contracts/spec.js";
 import type { SprintContract } from "../contracts/sprint-contract.js";
 import type { EvaluationRunResult } from "../evaluators/registry.js";
-import type { ProjectContext } from "./context-handoff.js";
+import type { ContextHandoff, ProjectContext } from "./context-handoff.js";
 import type { GeneratorResult } from "./generator-agent.js";
 export interface PipelineResult {
     success: boolean;
@@ -36,7 +36,23 @@ export interface SprintCycleResult {
     evaluation?: EvaluationRunResult;
     generatorResult?: GeneratorResult;
 }
-export declare function runSprintCycle(contract: SprintContract, spec: PlanSpec, completedContracts: SprintContract[], projectRoot: string, config: BoberConfig, projectContext: ProjectContext, pipelineRunId?: string): Promise<SprintCycleResult>;
+/**
+ * Pure helper: inject queued guidance texts into a ContextHandoff by
+ * appending them to `issues`. When guidanceTexts is empty, returns the
+ * SAME handoff reference unchanged (deep-equal no-op for sc-4-7).
+ * Exported for direct unit testing (sc-4-6/sc-4-7).
+ */
+export declare function injectGuidanceIntoHandoff(handoff: ContextHandoff, guidanceTexts: string[]): ContextHandoff;
+export interface RunSprintCycleParams {
+    contract: SprintContract;
+    spec: PlanSpec;
+    completedContracts: SprintContract[];
+    projectRoot: string;
+    config: BoberConfig;
+    projectContext: ProjectContext;
+    pipelineRunId?: string;
+}
+export declare function runSprintCycle(params: RunSprintCycleParams): Promise<SprintCycleResult>;
 /**
  * Run the complete orchestration pipeline:
  *
@@ -53,10 +69,19 @@ export declare function runSprintCycle(contract: SprintContract, spec: PlanSpec,
  * Extracted so TsPipelineEngine can wrap it without an import cycle.
  * Do NOT change the algorithm, phase order, or .bober/ write behaviour here.
  */
-export declare function runTsPipeline(userPrompt: string, projectRoot: string, config: BoberConfig): Promise<PipelineResult>;
+export declare function runTsPipeline(userPrompt: string, projectRoot: string, config: BoberConfig, opts?: {
+    runId?: string;
+}): Promise<PipelineResult>;
 /**
  * Public entry point. Resolves the configured pipeline engine and delegates.
  * Signature is frozen — callers must not be updated when the engine changes.
+ *
+ * opts.teamId selects the active team (Phase 4). With no teamId, resolves to
+ * 'programming', whose pipelineShape === resolveEngineName(config) — identical
+ * to today's selectPipelineEngine(config) behaviour.
  */
-export declare function runPipeline(userPrompt: string, projectRoot: string, config: BoberConfig): Promise<PipelineResult>;
+export declare function runPipeline(userPrompt: string, projectRoot: string, config: BoberConfig, opts?: {
+    runId?: string;
+    teamId?: string;
+}): Promise<PipelineResult>;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/orchestrator/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/orchestrator/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAKtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAMrE,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQ3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA8B5D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACnC,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAiDD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,QAAQ,EACd,kBAAkB,EAAE,cAAc,EAAE,EACpC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,cAAc,EAAE,cAAc,EAC9B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA2Z5B;AAID;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC,CA8XzB;AAMD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC,CAEzB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/orchestrator/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAMrE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQ3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAiC5D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACnC,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAiDD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,EACvB,aAAa,EAAE,MAAM,EAAE,GACtB,cAAc,CAShB;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,kBAAkB,EAAE,cAAc,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAmhB5B;AAID;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,OAAO,CAAC,cAAc,CAAC,CA6UzB;AAQD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,cAAc,CAAC,CAezB"}