agent-bober 0.17.1 → 0.19.0

package/dist/seo/verifier.js.map

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

package/dist/seo/workflow-capabilities.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WORKFLOW_CAPABILITIES — per-workflow capability-subset map
+ * (spec-20260717-seo-improver-builder, Sprint 9; ADR-7).
+ *
+ * `gatherDataBundle` (`./runner.ts`) probes ONLY the capabilities listed for
+ * the running workflow, so the metered `ai-visibility` capability is fetched
+ * ONLY for workflows that actually consume it. An omitted capability leaves
+ * its `SeoDataBundle` arm `undefined`, which the analyzer already renders as
+ * "not requested" (`analyzer.ts:127-128`) — no analyzer change is needed for
+ * omission itself.
+ *
+ * `CORE` is the original five capabilities gathered before this sprint
+ * (`search-analytics`, `url-inspection`, `serp`, `keywords`, `backlinks`).
+ * Every pre-existing workflow keeps exactly `CORE` so the byte-identical
+ * offline golden report (sc-9-5) is unaffected — adding/removing a CORE
+ * capability for an existing workflow would change `dataProvenance` and
+ * break the deep-equal (see the sprint briefing §11 Pitfall 1).
+ *
+ * `SeoWorkflow` is a closed 8-member union (`types.ts:17-25`) — this is an
+ * EXHAUSTIVE `Record<SeoWorkflow, SeoCapability[]>` (not `Partial`), so a
+ * missing workflow key is a compile error, not a silent gap (Pitfall 6).
+ */
+import type { SeoWorkflow } from "./types.js";
+import type { SeoCapability } from "./data-source.js";
+export declare const WORKFLOW_CAPABILITIES: Record<SeoWorkflow, SeoCapability[]>;
+//# sourceMappingURL=workflow-capabilities.d.ts.map

package/dist/seo/workflow-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-capabilities.d.ts","sourceRoot":"","sources":["../../src/seo/workflow-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,WAAW,EAAE,aAAa,EAAE,CAStE,CAAC"}

package/dist/seo/workflow-capabilities.js

@@ -0,0 +1,12 @@
+const CORE = ["search-analytics", "url-inspection", "serp", "keywords", "backlinks"];
+export const WORKFLOW_CAPABILITIES = {
+    "technical-audit": CORE, // MUST NOT include "ai-visibility" (sc-9-4 / stopCondition)
+    "rank-track": CORE,
+    "content-decay": CORE,
+    "topical-map": CORE,
+    "ai-visibility": [...CORE, "ai-visibility"], // MUST include "ai-visibility"
+    "parasite-watch": [...CORE, "ai-visibility"], // AI-answer surfaces are relevant to parasite/answer-engine watch
+    "internal-linking": [...CORE, "link-graph"], // link-graph consumer
+    "schema-audit": CORE,
+};
+//# sourceMappingURL=workflow-capabilities.js.map

package/dist/seo/workflow-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-capabilities.js","sourceRoot":"","sources":["../../src/seo/workflow-capabilities.ts"],"names":[],"mappings":"AAyBA,MAAM,IAAI,GAAoB,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;AAEtG,MAAM,CAAC,MAAM,qBAAqB,GAAyC;IACzE,iBAAiB,EAAE,IAAI,EAAE,4DAA4D;IACrF,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,CAAC,EAAE,+BAA+B;IAC5E,gBAAgB,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,CAAC,EAAE,kEAAkE;IAChH,kBAAkB,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,EAAE,sBAAsB;IACnE,cAAc,EAAE,IAAI;CACrB,CAAC"}

package/dist/state/facts.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+export { writeFact } from "../orchestrator/memory/reconcile.js";
+export type { ReconcileAction } from "../orchestrator/memory/reconcile.js";
+/**
+ * Zod schema for a fact input — mirrors LessonEntrySchema in memory.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export declare const FactSchema: z.ZodObject<{
+    scope: z.ZodString;
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    value: z.ZodString;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    sourceRunId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tValid: z.ZodString;
+    tCreated: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    confidence: number;
+    sourceRunId: string | null;
+    tValid: string;
+    tCreated: string;
+}, {
+    value: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    tValid: string;
+    tCreated: string;
+    confidence?: number | undefined;
+    sourceRunId?: string | null | undefined;
+}>;
+export type FactInput = z.infer<typeof FactSchema>;
+export interface FactRecord {
+    id: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    confidence: number;
+    sourceRunId: string | null;
+    tValid: string;
+    tInvalid: string | null;
+    tCreated: string;
+    tInvalidated: string | null;
+}
+/**
+ * Derive a deterministic 16-char hex fact id from the fact signature.
+ * Mirrors lessonIdFromSignature in src/orchestrator/memory/distill.ts:88-99.
+ * Identical inputs always produce the same id — no wall-clock dependency.
+ */
+export declare function factId(scope: string, subject: string, predicate: string, value: string, tCreated: string): string;
+/**
+ * Resolve the absolute path to facts.db for the given project root and namespace.
+ * Uses the same memoryDir mapping rule as memory.ts (no duplication).
+ */
+export declare function factsDbPath(projectRoot: string, namespace?: string): string;
+/**
+ * Ensure the directory that will hold the DB file exists.
+ * Must be called by the CLI handler before constructing a file-backed FactStore.
+ * Not needed for ':memory:' paths.
+ */
+export declare function ensureFactsDir(projectRoot: string, namespace?: string): Promise<void>;
+/**
+ * Bi-temporal SQLite-backed fact store.
+ *
+ * PURE: Never calls Date.now() or new Date() — every timestamp is a parameter.
+ * Hidden behind this interface so the driver (better-sqlite3) is swappable.
+ *
+ * bober: in-memory or file-backed via better-sqlite3 (synchronous); swap for
+ * node:sqlite when engines.node is raised to >=22.5.
+ */
+export declare class FactStore {
+    private db;
+    constructor(dbPath: string, opts?: {
+        journalModeWal?: boolean;
+        busyTimeoutMs?: number;
+        readonly?: boolean;
+    });
+    /**
+     * Insert a new fact. Validates input with FactSchema and derives the
+     * deterministic id. Returns the persisted FactRecord.
+     */
+    insertFact(input: FactInput): FactRecord;
+    /**
+     * Return all active (non-invalidated) facts matching the given scope.
+     * Optionally filtered by subject and/or predicate.
+     * Active = t_invalidated IS NULL.
+     */
+    getActiveFacts(scope: string, subject?: string, predicate?: string): FactRecord[];
+    /**
+     * Return a single fact by its id regardless of invalidation status.
+     * Returns null if not found.
+     */
+    getFact(id: string): FactRecord | null;
+    /**
+     * Soft-delete a fact by setting t_invalidated.
+     * Returns true if the fact was invalidated, false if it was already invalidated or not found.
+     * Never deletes rows.
+     */
+    invalidateFact(id: string, tInvalidated: string): boolean;
+    /**
+     * Supersede a fact: set BOTH t_invalidated (record-time) AND t_invalid (world-time end).
+     * Used by reconcile on UPDATE to carry both bi-temporal closure fields.
+     * Returns true if the row was updated; false if not found or already invalidated.
+     */
+    supersedeFact(id: string, tInvalidated: string, tInvalid: string): boolean;
+    /** Close the underlying database connection. */
+    close(): void;
+}
+//# sourceMappingURL=facts.d.ts.map

package/dist/state/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/state/facts.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAI3E;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;EASrB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAInD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf;AAoCD;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAe;gBAGvB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE;IAgCjF;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU;IA4CxC;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAqCjF;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAOtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAWzD;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAW1E,gDAAgD;IAChD,KAAK,IAAI,IAAI;CAGd"}

package/dist/state/facts.js

@@ -0,0 +1,218 @@
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import Database from "better-sqlite3";
+import { z } from "zod";
+import { ensureDir } from "./helpers.js";
+import { memoryDir } from "./memory.js";
+// ── Re-exports from reconcile layer ──────────────────────────────────────
+// writeFact lives in reconcile.ts (to avoid a runtime import cycle) but is
+// re-exported here so consumers can import it from the facts module.
+export { writeFact } from "../orchestrator/memory/reconcile.js";
+// ── Schema ────────────────────────────────────────────────────────────
+/**
+ * Zod schema for a fact input — mirrors LessonEntrySchema in memory.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export const FactSchema = z.object({
+    scope: z.string(),
+    subject: z.string().min(1),
+    predicate: z.string().min(1),
+    value: z.string().min(1),
+    confidence: z.number().min(0).max(1).default(1),
+    sourceRunId: z.string().nullable().default(null),
+    tValid: z.string().datetime(),
+    tCreated: z.string().datetime(),
+});
+// ── Deterministic id ──────────────────────────────────────────────────
+/**
+ * Derive a deterministic 16-char hex fact id from the fact signature.
+ * Mirrors lessonIdFromSignature in src/orchestrator/memory/distill.ts:88-99.
+ * Identical inputs always produce the same id — no wall-clock dependency.
+ */
+export function factId(scope, subject, predicate, value, tCreated) {
+    return createHash("sha256")
+        .update(`${scope}|${subject}|${predicate}|${value}|${tCreated}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+// ── Path helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve the absolute path to facts.db for the given project root and namespace.
+ * Uses the same memoryDir mapping rule as memory.ts (no duplication).
+ */
+export function factsDbPath(projectRoot, namespace) {
+    return join(memoryDir(projectRoot, namespace), "facts.db");
+}
+/**
+ * Ensure the directory that will hold the DB file exists.
+ * Must be called by the CLI handler before constructing a file-backed FactStore.
+ * Not needed for ':memory:' paths.
+ */
+export async function ensureFactsDir(projectRoot, namespace) {
+    await ensureDir(memoryDir(projectRoot, namespace));
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        scope: row.scope,
+        subject: row.subject,
+        predicate: row.predicate,
+        value: row.value,
+        confidence: row.confidence,
+        sourceRunId: row.source_run_id,
+        tValid: row.t_valid,
+        tInvalid: row.t_invalid,
+        tCreated: row.t_created,
+        tInvalidated: row.t_invalidated,
+    };
+}
+// ── FactStore ─────────────────────────────────────────────────────────
+/**
+ * Bi-temporal SQLite-backed fact store.
+ *
+ * PURE: Never calls Date.now() or new Date() — every timestamp is a parameter.
+ * Hidden behind this interface so the driver (better-sqlite3) is swappable.
+ *
+ * bober: in-memory or file-backed via better-sqlite3 (synchronous); swap for
+ * node:sqlite when engines.node is raised to >=22.5.
+ */
+export class FactStore {
+    db;
+    constructor(dbPath, opts) {
+        this.db = opts?.readonly
+            ? new Database(dbPath, { readonly: true })
+            : new Database(dbPath);
+        if (opts?.journalModeWal) {
+            this.db.pragma("journal_mode = WAL");
+        }
+        if (opts?.busyTimeoutMs !== undefined) {
+            this.db.pragma(`busy_timeout = ${opts.busyTimeoutMs}`);
+        }
+        if (!opts?.readonly) {
+            this.db.exec(`
+        CREATE TABLE IF NOT EXISTS semantic_facts (
+          id TEXT PRIMARY KEY,
+          scope TEXT NOT NULL,
+          subject TEXT NOT NULL,
+          predicate TEXT NOT NULL,
+          value TEXT NOT NULL,
+          confidence REAL NOT NULL,
+          source_run_id TEXT,
+          t_valid TEXT NOT NULL,
+          t_invalid TEXT,
+          t_created TEXT NOT NULL,
+          t_invalidated TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_facts_sp ON semantic_facts(scope, subject, predicate);
+        CREATE INDEX IF NOT EXISTS idx_facts_active ON semantic_facts(scope, t_invalidated);
+      `);
+        }
+    }
+    /**
+     * Insert a new fact. Validates input with FactSchema and derives the
+     * deterministic id. Returns the persisted FactRecord.
+     */
+    insertFact(input) {
+        const result = FactSchema.safeParse(input);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+                .join("\n");
+            throw new Error(`Invalid fact input:\n${issues}`);
+        }
+        const data = result.data;
+        const id = factId(data.scope, data.subject, data.predicate, data.value, data.tCreated);
+        this.db
+            .prepare(`INSERT OR REPLACE INTO semantic_facts
+          (id, scope, subject, predicate, value, confidence, source_run_id, t_valid, t_invalid, t_created, t_invalidated)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, NULL)`)
+            .run(id, data.scope, data.subject, data.predicate, data.value, data.confidence, data.sourceRunId, data.tValid, data.tCreated);
+        return {
+            id,
+            scope: data.scope,
+            subject: data.subject,
+            predicate: data.predicate,
+            value: data.value,
+            confidence: data.confidence,
+            sourceRunId: data.sourceRunId,
+            tValid: data.tValid,
+            tInvalid: null,
+            tCreated: data.tCreated,
+            tInvalidated: null,
+        };
+    }
+    /**
+     * Return all active (non-invalidated) facts matching the given scope.
+     * Optionally filtered by subject and/or predicate.
+     * Active = t_invalidated IS NULL.
+     */
+    getActiveFacts(scope, subject, predicate) {
+        if (subject !== undefined && predicate !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND subject = ? AND predicate = ? AND t_invalidated IS NULL`)
+                .all(scope, subject, predicate);
+            return rows.map(rowToRecord);
+        }
+        if (subject !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND subject = ? AND t_invalidated IS NULL`)
+                .all(scope, subject);
+            return rows.map(rowToRecord);
+        }
+        if (predicate !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND predicate = ? AND t_invalidated IS NULL`)
+                .all(scope, predicate);
+            return rows.map(rowToRecord);
+        }
+        const rows = this.db
+            .prepare(`SELECT * FROM semantic_facts
+         WHERE scope = ? AND t_invalidated IS NULL`)
+            .all(scope);
+        return rows.map(rowToRecord);
+    }
+    /**
+     * Return a single fact by its id regardless of invalidation status.
+     * Returns null if not found.
+     */
+    getFact(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM semantic_facts WHERE id = ?`)
+            .get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Soft-delete a fact by setting t_invalidated.
+     * Returns true if the fact was invalidated, false if it was already invalidated or not found.
+     * Never deletes rows.
+     */
+    invalidateFact(id, tInvalidated) {
+        const info = this.db
+            .prepare(`UPDATE semantic_facts
+         SET t_invalidated = ?
+         WHERE id = ? AND t_invalidated IS NULL`)
+            .run(tInvalidated, id);
+        return info.changes > 0;
+    }
+    /**
+     * Supersede a fact: set BOTH t_invalidated (record-time) AND t_invalid (world-time end).
+     * Used by reconcile on UPDATE to carry both bi-temporal closure fields.
+     * Returns true if the row was updated; false if not found or already invalidated.
+     */
+    supersedeFact(id, tInvalidated, tInvalid) {
+        const info = this.db
+            .prepare(`UPDATE semantic_facts
+         SET t_invalidated = ?, t_invalid = ?
+         WHERE id = ? AND t_invalidated IS NULL`)
+            .run(tInvalidated, tInvalid, id);
+        return info.changes > 0;
+    }
+    /** Close the underlying database connection. */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=facts.js.map

package/dist/state/facts.js.map

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

package/dist/state/guidance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validate that a runId is a safe path segment.
+ * Rejects empty strings, strings containing path separators (/ or \),
+ * strings containing '..', and absolute paths.
+ * This is a security guard: a malicious runId must never escape .bober/runs.
+ */
+export declare function safeSegment(runId: string): boolean;
+/**
+ * Check whether the run directory exists for the given runId.
+ * Returns false if not found — never throws.
+ * Mirrors approval-state.ts:pendingExists.
+ */
+export declare function hasRunDir(projectRoot: string, runId: string): Promise<boolean>;
+/**
+ * Append a guidance entry to .bober/runs/<runId>/guidance.jsonl.
+ *
+ * Security: validates runId is a safe path segment BEFORE building any path.
+ * Throws with a clear message if runId is unsafe (caller should surface to user).
+ *
+ * Existence: the run directory must already exist (guard with hasRunDir if
+ * you want an unknown-run check; appendGuidance itself creates the dir for
+ * robustness, but callers in chat-session.ts should guard first for UX).
+ */
+export declare function appendGuidance(projectRoot: string, runId: string, text: string): Promise<void>;
+/**
+ * Drain pending (unconsumed) guidance entries for a runId.
+ *
+ * Reads all lines, collects the text of entries where consumed !== true,
+ * then atomically rewrites the file with ALL entries marked consumed:true
+ * (temp-file + rename, mirrors run-state.ts:41-52).
+ *
+ * Returns the drained texts in order.
+ * Missing file → returns [] (never throws — safe to call on every pipeline sprint).
+ * Second drain → returns [] (all entries already marked consumed).
+ */
+export declare function drainGuidance(projectRoot: string, runId: string): Promise<string[]>;
+//# sourceMappingURL=guidance.d.ts.map

package/dist/state/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../../src/state/guidance.ts"],"names":[],"mappings":"AAyCA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CASlD;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOpF;AAID;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAcf;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB"}

package/dist/state/guidance.js

@@ -0,0 +1,144 @@
+// ── guidance.ts ───────────────────────────────────────────────────────
+//
+// Disk-persistence helpers for the runId-keyed guidance channel.
+//
+// Layout: .bober/runs/<runId>/guidance.jsonl
+// One JSON object per line: { ts: string, text: string, consumed: boolean }
+//
+// Every drain rewrite is atomic via temp-file + rename
+// (mirrors src/state/run-state.ts:41-52 atomic write pattern).
+import { readFile, writeFile, appendFile, rename, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { ensureDir } from "./helpers.js";
+// ── Path helpers ──────────────────────────────────────────────────────
+function runsRoot(projectRoot) {
+    return join(projectRoot, ".bober", "runs");
+}
+function runDir(projectRoot, runId) {
+    return join(runsRoot(projectRoot), runId);
+}
+function guidancePath(projectRoot, runId) {
+    return join(runDir(projectRoot, runId), "guidance.jsonl");
+}
+// ── Path-traversal guard ──────────────────────────────────────────────
+/**
+ * Validate that a runId is a safe path segment.
+ * Rejects empty strings, strings containing path separators (/ or \),
+ * strings containing '..', and absolute paths.
+ * This is a security guard: a malicious runId must never escape .bober/runs.
+ */
+export function safeSegment(runId) {
+    if (!runId)
+        return false;
+    if (runId.includes("/"))
+        return false;
+    if (runId.includes("\\"))
+        return false;
+    if (runId.includes(".."))
+        return false;
+    if (runId.startsWith("."))
+        return false;
+    // Reject if it looks like an absolute path (Unix or Windows)
+    if (runId.startsWith("/") || /^[A-Za-z]:[/\\]/.test(runId))
+        return false;
+    return true;
+}
+// ── Existence guard ───────────────────────────────────────────────────
+/**
+ * Check whether the run directory exists for the given runId.
+ * Returns false if not found — never throws.
+ * Mirrors approval-state.ts:pendingExists.
+ */
+export async function hasRunDir(projectRoot, runId) {
+    try {
+        await access(runDir(projectRoot, runId), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Append ────────────────────────────────────────────────────────────
+/**
+ * Append a guidance entry to .bober/runs/<runId>/guidance.jsonl.
+ *
+ * Security: validates runId is a safe path segment BEFORE building any path.
+ * Throws with a clear message if runId is unsafe (caller should surface to user).
+ *
+ * Existence: the run directory must already exist (guard with hasRunDir if
+ * you want an unknown-run check; appendGuidance itself creates the dir for
+ * robustness, but callers in chat-session.ts should guard first for UX).
+ */
+export async function appendGuidance(projectRoot, runId, text) {
+    if (!safeSegment(runId)) {
+        throw new Error(`Invalid runId "${runId}": must be a safe path segment (no path separators, no '..').`);
+    }
+    await ensureDir(runDir(projectRoot, runId));
+    const entry = {
+        ts: new Date().toISOString(),
+        text,
+        consumed: false,
+    };
+    // appendFile is safe for JSONL: each call writes exactly one complete line.
+    await appendFile(guidancePath(projectRoot, runId), JSON.stringify(entry) + "\n", "utf-8");
+}
+// ── Drain ─────────────────────────────────────────────────────────────
+/**
+ * Drain pending (unconsumed) guidance entries for a runId.
+ *
+ * Reads all lines, collects the text of entries where consumed !== true,
+ * then atomically rewrites the file with ALL entries marked consumed:true
+ * (temp-file + rename, mirrors run-state.ts:41-52).
+ *
+ * Returns the drained texts in order.
+ * Missing file → returns [] (never throws — safe to call on every pipeline sprint).
+ * Second drain → returns [] (all entries already marked consumed).
+ */
+export async function drainGuidance(projectRoot, runId) {
+    const filePath = guidancePath(projectRoot, runId);
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch {
+        // File does not exist or is unreadable — return empty (no-op)
+        return [];
+    }
+    const lines = raw.split("\n").filter((l) => l.trim() !== "");
+    if (lines.length === 0)
+        return [];
+    const entries = [];
+    const drained = [];
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.consumed !== true) {
+                drained.push(entry.text);
+            }
+            entries.push({ ...entry, consumed: true });
+        }
+        catch {
+            // Skip malformed lines — do not lose other entries
+        }
+    }
+    if (drained.length === 0) {
+        // Nothing unconsumed — still rewrite atomically to normalize the file
+        // (all entries stay consumed:true from previous drain)
+        const allConsumed = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        const rnd = randomBytes(4).toString("hex");
+        const tmp = `${filePath}.${process.pid}.${Date.now()}.${rnd}.tmp`;
+        await writeFile(tmp, allConsumed, { encoding: "utf-8", mode: 0o600 });
+        await rename(tmp, filePath);
+        return [];
+    }
+    // Atomically rewrite all entries as consumed
+    const rewritten = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    const rnd = randomBytes(4).toString("hex");
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.${rnd}.tmp`;
+    await writeFile(tmp, rewritten, { encoding: "utf-8", mode: 0o600 });
+    await rename(tmp, filePath);
+    return drained;
+}
+//# sourceMappingURL=guidance.js.map

package/dist/state/guidance.js.map

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

package/dist/state/history.d.ts

@@ -13,13 +13,13 @@ export declare const HistoryEntrySchema: z.ZodObject<{
     details: Record<string, unknown>;
     timestamp: string;
     event: string;
-    phase: "evaluating" | "failed" | "init" | "planning" | "curating" | "generating" | "rework" | "complete";
+    phase: "complete" | "failed" | "init" | "planning" | "curating" | "generating" | "evaluating" | "rework";
     sprintId?: string | undefined;
 }, {
     details: Record<string, unknown>;
     timestamp: string;
     event: string;
-    phase: "evaluating" | "failed" | "init" | "planning" | "curating" | "generating" | "rework" | "complete";
+    phase: "complete" | "failed" | "init" | "planning" | "curating" | "generating" | "evaluating" | "rework";
     sprintId?: string | undefined;
 }>;
 export type HistoryEntry = z.infer<typeof HistoryEntrySchema>;

package/dist/state/index.d.ts

@@ -1,9 +1,9 @@
-export { saveContract, loadContract, listContracts, updateContract, } from "./sprint-state.js";
+export { saveContract, loadContract, listContracts, updateContract, clearContractsForSpec, } from "./sprint-state.js";
 export { saveSpec, loadSpec, loadLatestSpec, listSpecs, } from "./plan-state.js";
 export { PhaseSchema, HistoryEntrySchema, type Phase, type HistoryEntry, appendHistory, loadHistory, loadRecentHistory, updateProgress, } from "./history.js";
 export { saveResearch, readResearch, listResearch, } from "./research-state.js";
 export { saveDesign, readDesign, } from "./design-state.js";
-export { saveOutline, readOutline, } from "./outline-state.js";
+export { readOutline, } from "./outline-state.js";
 export { saveArchitecture, readArchitecture, saveADR, readADRs, listArchitectures, } from "./architect-state.js";
 export { saveBriefing, readBriefing, listBriefings, } from "./briefing-state.js";
 export { saveReview, readReview, listReviews, } from "./review-state.js";

package/dist/state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,WAAW,EACX,kBAAkB,EAElB,KAAK,KAAK,EACV,KAAK,YAAY,EAEjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAKxB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,WAAW,EACX,kBAAkB,EAElB,KAAK,KAAK,EACV,KAAK,YAAY,EAEjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAKxB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}