conatus 0.1.0

package/dist/observation/observation-helpers.js

@@ -0,0 +1,173 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { ObservationLogEntrySchema, ObservationLogSchema } from "../types/state.js";
+import { KnowledgeGapSignalSchema } from "../types/knowledge.js";
+export const LAYER_CONFIG = {
+    mechanical: {
+        ceiling: 1.0,
+        tier: "mechanical",
+        range: [0.85, 1.0],
+    },
+    independent_review: {
+        ceiling: 0.90,
+        tier: "independent_review",
+        range: [0.50, 0.84],
+    },
+    self_report: {
+        ceiling: 0.70,
+        tier: "self_report",
+        range: [0.10, 0.49],
+    },
+};
+// ─── Layer Priority ───
+export const LAYER_PRIORITY = {
+    mechanical: 3,
+    independent_review: 2,
+    self_report: 1,
+};
+// Zod schema for LLM observation response
+export const LLMObservationResponseSchema = z.object({
+    score: z.number().min(0).max(1),
+    reason: z.string(),
+});
+// ─── Pure Helper Functions ───
+/**
+ * Apply progress ceiling based on observation layer.
+ * Returns min(progress, ceiling).
+ */
+export function applyProgressCeiling(progress, layer) {
+    const config = LAYER_CONFIG[layer];
+    return Math.min(progress, config.ceiling);
+}
+/**
+ * Return the ConfidenceTier and valid confidence range for a given layer.
+ */
+export function getConfidenceTier(layer) {
+    const config = LAYER_CONFIG[layer];
+    return { tier: config.tier, range: config.range };
+}
+/**
+ * Construct a new ObservationLogEntry.
+ * Confidence is clamped to the layer's valid range.
+ */
+export function createObservationEntry(params) {
+    const config = LAYER_CONFIG[params.layer];
+    const [minConf, maxConf] = config.range;
+    const clampedConfidence = Math.min(maxConf, Math.max(minConf, params.confidence));
+    const entry = ObservationLogEntrySchema.parse({
+        observation_id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        trigger: params.trigger,
+        goal_id: params.goalId,
+        dimension_name: params.dimensionName,
+        layer: params.layer,
+        method: params.method,
+        raw_result: params.rawResult,
+        extracted_value: params.extractedValue,
+        confidence: clampedConfidence,
+        notes: params.notes ?? null,
+    });
+    return entry;
+}
+/**
+ * Returns true when effective progress meets the threshold but confidence
+ * is below 0.85, meaning a mechanical verification task should be generated.
+ */
+export function needsVerificationTask(effectiveProgress, confidence, threshold) {
+    return effectiveProgress >= threshold && confidence < 0.85;
+}
+/**
+ * Resolve contradictions among multiple observation entries.
+ *
+ * Resolution rules:
+ *   1. Higher-priority layer wins (mechanical > independent_review > self_report).
+ *   2. Within the same layer, take the pessimistic (lower) numeric value.
+ *   3. For non-numeric values, take the first entry in the winning layer.
+ *
+ * Returns the single "winning" entry.
+ * Throws if entries array is empty.
+ */
+export function resolveContradiction(entries) {
+    if (entries.length === 0) {
+        throw new Error("resolveContradiction: entries array must not be empty");
+    }
+    if (entries.length === 1) {
+        return entries[0];
+    }
+    // Find highest priority layer present
+    let maxPriority = -1;
+    for (const entry of entries) {
+        const priority = LAYER_PRIORITY[entry.layer];
+        if (priority > maxPriority) {
+            maxPriority = priority;
+        }
+    }
+    // Collect all entries at the winning layer
+    const winningLayer = entries.filter((e) => LAYER_PRIORITY[e.layer] === maxPriority);
+    if (winningLayer.length === 1) {
+        return winningLayer[0];
+    }
+    // Within same layer: pessimistic (lowest numeric value)
+    let best = winningLayer[0];
+    for (let i = 1; i < winningLayer.length; i++) {
+        const candidate = winningLayer[i];
+        const bestVal = best.extracted_value;
+        const candidateVal = candidate.extracted_value;
+        if (typeof bestVal === "number" && typeof candidateVal === "number") {
+            if (candidateVal < bestVal) {
+                best = candidate;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+ * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+ *
+ * Examples:
+ *   "todo_count_2"  → "todo_count"
+ *   "quality_3"     → "quality"
+ *   "step_count"    → "step_count"  (trailing token is not a digit-only suffix)
+ *   "coverage"      → "coverage"
+ */
+export function normalizeDimensionName(name, logger) {
+    const stripped = name.replace(/_\d+$/, "");
+    if (stripped !== name) {
+        logger?.warn(`[ObservationEngine] normalizeDimensionName: stripped "${name}" → "${stripped}"`);
+    }
+    return stripped;
+}
+/**
+ * Detect whether a set of observation entries indicates a knowledge gap.
+ *
+ * Rule: if ALL entries have confidence < 0.3, interpretation is too
+ * uncertain — emit an `interpretation_difficulty` signal.
+ *
+ * Returns null when confidence is sufficient (no gap detected).
+ */
+export function detectKnowledgeGap(entries, dimensionName) {
+    if (entries.length === 0)
+        return null;
+    const allLowConfidence = entries.every((e) => e.confidence < 0.3);
+    if (!allLowConfidence)
+        return null;
+    return KnowledgeGapSignalSchema.parse({
+        signal_type: "interpretation_difficulty",
+        missing_knowledge: "Observation confidence is too low to interpret results reliably",
+        source_step: "gap_recognition",
+        related_dimension: dimensionName ?? null,
+    });
+}
+/**
+ * Load the observation log for a goal, returning an empty log if none exists.
+ * Pure function — requires stateManager passed in.
+ */
+export async function loadOrEmptyObservationLog(stateManager, goalId) {
+    const existing = await stateManager.loadObservationLog(goalId);
+    if (existing !== null) {
+        return existing;
+    }
+    return ObservationLogSchema.parse({ goal_id: goalId, entries: [] });
+}
+//# sourceMappingURL=observation-helpers.js.map

package/dist/observation/observation-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-helpers.js","sourceRoot":"","sources":["../../src/observation/observation-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAmCjE,MAAM,CAAC,MAAM,YAAY,GAA0C;IACjE,UAAU,EAAE;QACV,OAAO,EAAE,GAAG;QACZ,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;KACnB;IACD,kBAAkB,EAAE;QAClB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;KACpB;IACD,WAAW,EAAE;QACX,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;KACpB;CACF,CAAC;AAEF,yBAAyB;AAEzB,MAAM,CAAC,MAAM,cAAc,GAAqC;IAC9D,UAAU,EAAE,CAAC;IACb,kBAAkB,EAAE,CAAC;IACrB,WAAW,EAAE,CAAC;CACf,CAAC;AAEF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAEH,gCAAgC;AAEhC;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,KAAuB;IAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAuB;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAUtC;IACC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;IACxC,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAElF,MAAM,KAAK,GAAG,yBAAyB,CAAC,KAAK,CAAC;QAC5C,cAAc,EAAE,UAAU,EAAE;QAC5B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,MAAM;QACtB,cAAc,EAAE,MAAM,CAAC,aAAa;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,MAAM,CAAC,SAAS;QAC5B,eAAe,EAAE,MAAM,CAAC,cAAc;QACtC,UAAU,EAAE,iBAAiB;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;KAC5B,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,iBAAyB,EAAE,UAAkB,EAAE,SAAiB;IACpG,OAAO,iBAAiB,IAAI,SAAS,IAAI,UAAU,GAAG,IAAI,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;IACrB,CAAC;IAED,sCAAsC;IACtC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC3B,WAAW,GAAG,QAAQ,CAAC;QACzB,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAC/C,CAAC;IAEF,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,YAAY,CAAC,CAAC,CAAE,CAAC;IAC1B,CAAC;IAED,wDAAwD;IACxD,IAAI,IAAI,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC;QACrC,MAAM,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC;QAC/C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACpE,IAAI,YAAY,GAAG,OAAO,EAAE,CAAC;gBAC3B,IAAI,GAAG,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAE,MAAe;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC3C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,IAAI,CAAC,yDAAyD,IAAI,QAAQ,QAAQ,GAAG,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA8B,EAC9B,aAAsB;IAEtB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAEnC,OAAO,wBAAwB,CAAC,KAAK,CAAC;QACpC,WAAW,EAAE,2BAA2B;QACxC,iBAAiB,EACf,iEAAiE;QACnE,WAAW,EAAE,iBAAiB;QAC9B,iBAAiB,EAAE,aAAa,IAAI,IAAI;KACzC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,YAAwF,EACxF,MAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC/D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/observation/observation-llm.d.ts

@@ -0,0 +1,46 @@
+import type { ObservationLogEntry } from "../types/state.js";
+import type { ILLMClient } from "../llm/llm-client.js";
+import type { ObservationEngineOptions } from "./observation-helpers.js";
+import type { Logger } from "../runtime/logger.js";
+import type { IPromptGateway } from "../prompt/gateway.js";
+/**
+ * Fetch a concise workspace context via git diff when no contextProvider is available.
+ * Returns an empty string if git commands fail (e.g., not a git repo).
+ *
+ * Uses execFile (not exec/execSync) to avoid shell-injection risks and event-loop blocking.
+ *
+ * @param options   Engine options (may contain gitContextFetcher override).
+ * @param maxChars  Maximum characters to return (default: 3000).
+ */
+export declare function fetchGitDiffContext(options: ObservationEngineOptions, maxChars?: number): Promise<string>;
+/**
+ * Observe a goal dimension using the LLM client.
+ *
+ * The LLM is asked to score the dimension from 0.0 to 1.0.
+ * The score is used as extractedValue, and confidence is fixed at 0.70
+ * (middle of the independent_review range [0.50, 0.84]).
+ *
+ * If workspaceContext is not provided, a git diff fallback is attempted
+ * so the LLM has actual evidence to evaluate. If that also fails,
+ * the prompt includes an explicit warning and the LLM must score 0.0.
+ *
+ * @param goalId             The goal being observed.
+ * @param dimensionName      The dimension name (snake_case).
+ * @param goalDescription    Human-readable goal description.
+ * @param dimensionLabel     Human-readable dimension label.
+ * @param thresholdDescription  JSON-stringified threshold for context.
+ * @param llmClient          The LLM client to use.
+ * @param options            Engine options (for git diff fallback).
+ * @param applyObservation   Callback to persist the entry (skipped if dryRun).
+ * @param workspaceContext   Optional pre-fetched workspace context.
+ * @param previousScore      Previous observed score for trend context.
+ * @param dryRun             If true, do not write to state.
+ * @param logger             Optional logger.
+ * @param dimensionHistory   Optional history of prior observations for this dimension.
+ */
+export declare function observeWithLLM(goalId: string, dimensionName: string, goalDescription: string, dimensionLabel: string, thresholdDescription: string, llmClient: ILLMClient, options: ObservationEngineOptions, applyObservation: (goalId: string, entry: ObservationLogEntry) => void, workspaceContext?: string, previousScore?: number | null, dryRun?: boolean, logger?: Logger, dimensionHistory?: Array<{
+    value: number;
+    timestamp?: string;
+    date?: string;
+}>, gateway?: IPromptGateway): Promise<ObservationLogEntry>;
+//# sourceMappingURL=observation-llm.d.ts.map

package/dist/observation/observation-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-llm.d.ts","sourceRoot":"","sources":["../../src/observation/observation-llm.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,EAAE,QAAQ,SAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC7G;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,oBAAoB,EAAE,MAAM,EAC5B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,wBAAwB,EACjC,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,KAAK,IAAI,EACtE,gBAAgB,CAAC,EAAE,MAAM,EACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,EAC7B,MAAM,CAAC,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9E,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAuK9B"}

package/dist/observation/observation-llm.js

@@ -0,0 +1,220 @@
+import { randomUUID } from "node:crypto";
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+import { ObservationLogEntrySchema } from "../types/state.js";
+const execFile = promisify(execFileCb);
+import { LLMObservationResponseSchema } from "./observation-helpers.js";
+import { wrapXmlTag, formatObservationHistory } from "../prompt/formatters.js";
+import { OBSERVATION_SYSTEM_PROMPT } from "../prompt/purposes/observation.js";
+/**
+ * Fetch a concise workspace context via git diff when no contextProvider is available.
+ * Returns an empty string if git commands fail (e.g., not a git repo).
+ *
+ * Uses execFile (not exec/execSync) to avoid shell-injection risks and event-loop blocking.
+ *
+ * @param options   Engine options (may contain gitContextFetcher override).
+ * @param maxChars  Maximum characters to return (default: 3000).
+ */
+export async function fetchGitDiffContext(options, maxChars = 3000) {
+    // Allow test injection via options
+    if (options.gitContextFetcher) {
+        return options.gitContextFetcher(maxChars);
+    }
+    const parts = [];
+    try {
+        const { stdout: stat } = await execFile("git", ["diff", "--stat"], { timeout: 10000, encoding: "utf8" });
+        if (stat.trim()) {
+            parts.push("[git diff --stat]");
+            parts.push(stat.trim());
+        }
+    }
+    catch {
+        // not a git repo or git unavailable
+    }
+    try {
+        const { stdout: diff } = await execFile("git", ["diff"], { timeout: 10000, encoding: "utf8" });
+        if (diff.trim()) {
+            parts.push("[git diff]");
+            // Reserve space: subtract what we've already accumulated
+            const alreadyUsed = parts.join("\n\n").length;
+            const remaining = Math.max(0, maxChars - alreadyUsed - 20); // 20 for separator
+            const truncated = diff.length > remaining ? diff.slice(0, remaining) + "\n...(truncated)" : diff;
+            parts.push(truncated.trim());
+        }
+    }
+    catch {
+        // ignore
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Infer the direction of change from a history of score values.
+ */
+function inferDirection(history) {
+    if (history.length < 2)
+        return "insufficient_data";
+    const last = history[history.length - 1].value;
+    const prev = history[history.length - 2].value;
+    if (last > prev)
+        return "improving";
+    if (last < prev)
+        return "declining";
+    return "stable";
+}
+/**
+ * Observe a goal dimension using the LLM client.
+ *
+ * The LLM is asked to score the dimension from 0.0 to 1.0.
+ * The score is used as extractedValue, and confidence is fixed at 0.70
+ * (middle of the independent_review range [0.50, 0.84]).
+ *
+ * If workspaceContext is not provided, a git diff fallback is attempted
+ * so the LLM has actual evidence to evaluate. If that also fails,
+ * the prompt includes an explicit warning and the LLM must score 0.0.
+ *
+ * @param goalId             The goal being observed.
+ * @param dimensionName      The dimension name (snake_case).
+ * @param goalDescription    Human-readable goal description.
+ * @param dimensionLabel     Human-readable dimension label.
+ * @param thresholdDescription  JSON-stringified threshold for context.
+ * @param llmClient          The LLM client to use.
+ * @param options            Engine options (for git diff fallback).
+ * @param applyObservation   Callback to persist the entry (skipped if dryRun).
+ * @param workspaceContext   Optional pre-fetched workspace context.
+ * @param previousScore      Previous observed score for trend context.
+ * @param dryRun             If true, do not write to state.
+ * @param logger             Optional logger.
+ * @param dimensionHistory   Optional history of prior observations for this dimension.
+ */
+export async function observeWithLLM(goalId, dimensionName, goalDescription, dimensionLabel, thresholdDescription, llmClient, options, applyObservation, workspaceContext, previousScore, dryRun, logger, dimensionHistory, gateway) {
+    logger?.info(`[ObservationEngine] LLM observation for dimension "${dimensionLabel}" (goal: ${goalId})`);
+    // Resolve workspace context: use provided context, fall back to git diff, or warn.
+    let resolvedContext = workspaceContext;
+    if (!resolvedContext || resolvedContext.trim().length === 0) {
+        const gitCtx = await fetchGitDiffContext(options, 3000);
+        if (gitCtx.trim().length > 0) {
+            resolvedContext = gitCtx;
+            logger?.info(`[ObservationEngine] No contextProvider output — using git diff fallback for "${dimensionLabel}"`);
+        }
+    }
+    // Truncate to 4000 chars max to avoid token waste
+    const MAX_CONTEXT_CHARS = 4000;
+    if (resolvedContext && resolvedContext.length > MAX_CONTEXT_CHARS) {
+        resolvedContext = resolvedContext.slice(0, MAX_CONTEXT_CHARS) + "\n...(truncated)";
+    }
+    const hasContext = !!resolvedContext && resolvedContext.trim().length > 0;
+    const previousScoreText = previousScore !== undefined && previousScore !== null
+        ? previousScore.toFixed(2)
+        : "none";
+    const contextContent = hasContext
+        ? resolvedContext
+        : "WARNING: No workspace content was provided. Score MUST be 0.0 per Rule 2.";
+    // Build optional observation history block
+    let historyBlock = "";
+    if (dimensionHistory && dimensionHistory.length > 0) {
+        const direction = inferDirection(dimensionHistory);
+        historyBlock = wrapXmlTag("observation_history", formatObservationHistory(dimensionHistory.map((h) => ({
+            timestamp: h.timestamp ?? h.date ?? "",
+            score: h.value,
+        })), direction));
+    }
+    const prompt = `Score a goal dimension 0.0 (not achieved) to 1.0 (fully achieved).\n\n` +
+        `CRITICAL RULES:\n` +
+        `1. Use ONLY the evidence below. Do not invent or assume.\n` +
+        `2. If no workspace content is provided, score MUST be 0.0.\n` +
+        `3. Return ONLY valid JSON: {"score": <0.0-1.0>, "reason": "<one sentence>"}\n\n` +
+        `Goal: ${goalDescription}\n` +
+        `Dimension: ${dimensionLabel}\n` +
+        `Target: ${thresholdDescription}\n` +
+        `Previous score: ${previousScoreText}\n\n` +
+        (historyBlock ? `${historyBlock}\n\n` : "") +
+        `FEW-SHOT CALIBRATION:\n` +
+        `- Context: grep shows 0 TODO matches → {"score": 1.0, "reason": "No TODOs; target achieved"}\n` +
+        `- Context: grep shows 3 matches: src/foo.ts:42: TODO fix this → {"score": 0.0, "reason": "3 TODOs remain"}\n\n` +
+        `WORKSPACE CONTENT:\n` +
+        `${contextContent}\n\n` +
+        `Score now based strictly on the above content.`;
+    let parsed;
+    if (gateway) {
+        try {
+            parsed = await gateway.execute({
+                purpose: "observation",
+                goalId,
+                dimensionName,
+                additionalContext: { observation_prompt: prompt },
+                responseSchema: LLMObservationResponseSchema,
+                maxTokens: 512,
+                temperature: 0,
+            });
+        }
+        catch (err) {
+            // Fallback to direct LLM call if gateway fails
+            logger?.warn(`[ObservationEngine] PromptGateway failed for "${dimensionLabel}", falling back to direct LLM: ${String(err)}`);
+            const response = await llmClient.sendMessage([{ role: "user", content: prompt }], { system: OBSERVATION_SYSTEM_PROMPT, max_tokens: 512, temperature: 0 });
+            parsed = llmClient.parseJSON(response.content, LLMObservationResponseSchema);
+        }
+    }
+    else {
+        const response = await llmClient.sendMessage([{ role: "user", content: prompt }], { system: OBSERVATION_SYSTEM_PROMPT, max_tokens: 512, temperature: 0 });
+        parsed = llmClient.parseJSON(response.content, LLMObservationResponseSchema);
+    }
+    // P0: Score-evidence consistency check (§4.3)
+    // If no evidence (no context, no git diff), LLM score > 0.0 is unreliable
+    let score = parsed.score;
+    if (!hasContext && score > 0.0) {
+        logger?.warn(`score overridden to 0.0 (no evidence available, LLM returned ${score})`);
+        score = 0.0;
+    }
+    // §3.3: Observation score jump suppression (±0.4/cycle)
+    // When no mechanical source is available and the LLM score jumps more than 0.4
+    // from the previous score, suppress the change and lower confidence.
+    const MAX_SCORE_DELTA = 0.4;
+    let resolvedConfidence = !hasContext ? 0.1 : 0.70;
+    if (typeof previousScore === "number" &&
+        previousScore !== null &&
+        Math.abs(score - previousScore) > MAX_SCORE_DELTA) {
+        const delta = Math.abs(score - previousScore);
+        logger?.warn(`WARN: observation score jump suppressed: prev=${previousScore.toFixed(3)}, proposed=${score.toFixed(3)}, delta=${delta.toFixed(3)}`);
+        score = previousScore;
+        resolvedConfidence = 0.3;
+    }
+    logger?.info(`[ObservationEngine] LLM observation result for "${dimensionLabel}": score=${score.toFixed(3)}`);
+    // Scale LLM 0-1 score to threshold's native scale for min/max types.
+    // LLM returns 0.0-1.0 (normalized), but gap-calculator expects the raw
+    // value in the threshold's scale (e.g., min:5 expects value >= 5).
+    let extractedValue = score;
+    try {
+        const threshold = JSON.parse(thresholdDescription);
+        if (threshold.type === "min" && typeof threshold.value === "number" && threshold.value > 1) {
+            extractedValue = score * threshold.value;
+        }
+        else if (threshold.type === "max" && typeof threshold.value === "number" && threshold.value > 1) {
+            extractedValue = score * threshold.value;
+        }
+    }
+    catch { /* keep original score if threshold parsing fails */ }
+    const entry = ObservationLogEntrySchema.parse({
+        observation_id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        trigger: "periodic",
+        goal_id: goalId,
+        dimension_name: dimensionName,
+        layer: "independent_review",
+        method: {
+            type: "llm_review",
+            source: "llm",
+            schedule: null,
+            endpoint: null,
+            confidence_tier: "independent_review",
+        },
+        raw_result: { score, reason: parsed.reason },
+        extracted_value: extractedValue,
+        confidence: resolvedConfidence,
+        notes: `LLM evaluation: ${parsed.reason}`,
+    });
+    if (!dryRun) {
+        await applyObservation(goalId, entry);
+    }
+    return entry;
+}
+//# sourceMappingURL=observation-llm.js.map

package/dist/observation/observation-llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-llm.js","sourceRoot":"","sources":["../../src/observation/observation-llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAGvC,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAG9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAiC,EAAE,QAAQ,GAAG,IAAI;IAC1F,mCAAmC;IACnC,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QACzG,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/F,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzB,yDAAyD;YACzD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;YAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC,mBAAmB;YAC/E,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC;YACjG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,OAAiC;IACvD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACnD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC;IAChD,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,WAAW,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,WAAW,CAAC;IACpC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,aAAqB,EACrB,eAAuB,EACvB,cAAsB,EACtB,oBAA4B,EAC5B,SAAqB,EACrB,OAAiC,EACjC,gBAAsE,EACtE,gBAAyB,EACzB,aAA6B,EAC7B,MAAgB,EAChB,MAAe,EACf,gBAA8E,EAC9E,OAAwB;IAExB,MAAM,EAAE,IAAI,CACV,sDAAsD,cAAc,YAAY,MAAM,GAAG,CAC1F,CAAC;IAEF,mFAAmF;IACnF,IAAI,eAAe,GAAG,gBAAgB,CAAC;IACvC,IAAI,CAAC,eAAe,IAAI,eAAe,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,eAAe,GAAG,MAAM,CAAC;YACzB,MAAM,EAAE,IAAI,CACV,gFAAgF,cAAc,GAAG,CAClG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,MAAM,iBAAiB,GAAG,IAAI,CAAC;IAC/B,IAAI,eAAe,IAAI,eAAe,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAClE,eAAe,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG,kBAAkB,CAAC;IACrF,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,CAAC,eAAe,IAAI,eAAe,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1E,MAAM,iBAAiB,GACrB,aAAa,KAAK,SAAS,IAAI,aAAa,KAAK,IAAI;QACnD,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC;IAEb,MAAM,cAAc,GAAG,UAAU;QAC/B,CAAC,CAAC,eAAgB;QAClB,CAAC,CAAC,2EAA2E,CAAC;IAEhF,2CAA2C;IAC3C,IAAI,YAAY,GAAG,EAAE,CAAC;IACtB,IAAI,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,SAAS,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAAC;QACnD,YAAY,GAAG,UAAU,CACvB,qBAAqB,EACrB,wBAAwB,CACtB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3B,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE;YACtC,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC,EACH,SAAS,CACV,CACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,wEAAwE;QACxE,mBAAmB;QACnB,4DAA4D;QAC5D,8DAA8D;QAC9D,iFAAiF;QACjF,SAAS,eAAe,IAAI;QAC5B,cAAc,cAAc,IAAI;QAChC,WAAW,oBAAoB,IAAI;QACnC,mBAAmB,iBAAiB,MAAM;QAC1C,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,yBAAyB;QACzB,gGAAgG;QAChG,gHAAgH;QAChH,sBAAsB;QACtB,GAAG,cAAc,MAAM;QACvB,gDAAgD,CAAC;IAEnD,IAAI,MAAyC,CAAC;IAC9C,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC;gBAC7B,OAAO,EAAE,aAAa;gBACtB,MAAM;gBACN,aAAa;gBACb,iBAAiB,EAAE,EAAE,kBAAkB,EAAE,MAAM,EAAE;gBACjD,cAAc,EAAE,4BAA4B;gBAC5C,SAAS,EAAE,GAAG;gBACd,WAAW,EAAE,CAAC;aACf,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+CAA+C;YAC/C,MAAM,EAAE,IAAI,CAAC,iDAAiD,cAAc,kCAAkC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7H,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,WAAW,CAC1C,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EACnC,EAAE,MAAM,EAAE,yBAAyB,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,CACvE,CAAC;YACF,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,WAAW,CAC1C,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EACnC,EAAE,MAAM,EAAE,yBAAyB,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,CACvE,CAAC;QACF,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,CAAC;IAC/E,CAAC;IAED,8CAA8C;IAC9C,0EAA0E;IAC1E,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IACzB,IAAI,CAAC,UAAU,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAC/B,MAAM,EAAE,IAAI,CACV,gEAAgE,KAAK,GAAG,CACzE,CAAC;QACF,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,+EAA+E;IAC/E,qEAAqE;IACrE,MAAM,eAAe,GAAG,GAAG,CAAC;IAC5B,IAAI,kBAAkB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,IACE,OAAO,aAAa,KAAK,QAAQ;QACjC,aAAa,KAAK,IAAI;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,aAAa,CAAC,GAAG,eAAe,EACjD,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC;QAC9C,MAAM,EAAE,IAAI,CACV,iDAAiD,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACrI,CAAC;QACF,KAAK,GAAG,aAAa,CAAC;QACtB,kBAAkB,GAAG,GAAG,CAAC;IAC3B,CAAC;IAED,MAAM,EAAE,IAAI,CACV,mDAAmD,cAAc,YAAY,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAChG,CAAC;IAEF,qEAAqE;IACrE,uEAAuE;IACvE,mEAAmE;IACnE,IAAI,cAAc,GAAW,KAAK,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACnD,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC3F,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QAC3C,CAAC;aAAM,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAClG,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QAC3C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,oDAAoD,CAAC,CAAC;IAEhE,MAAM,KAAK,GAAG,yBAAyB,CAAC,KAAK,CAAC;QAC5C,cAAc,EAAE,UAAU,EAAE;QAC5B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,UAAU;QACnB,OAAO,EAAE,MAAM;QACf,cAAc,EAAE,aAAa;QAC7B,KAAK,EAAE,oBAAoB;QAC3B,MAAM,EAAE;YACN,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,IAAI;YACd,eAAe,EAAE,oBAAoB;SACtC;QACD,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAC5C,eAAe,EAAE,cAAc;QAC/B,UAAU,EAAE,kBAAkB;QAC9B,KAAK,EAAE,mBAAmB,MAAM,CAAC,MAAM,EAAE;KAC1C,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/observation/observation-task.d.ts

@@ -0,0 +1,29 @@
+import type { TaskDomain } from "../types/pipeline.js";
+import type { AgentTask } from "../execution/adapter-layer.js";
+import type { Logger } from "../runtime/logger.js";
+export interface TaskObservationContext {
+    context: string;
+    sources: string[];
+    domain: TaskDomain;
+}
+export interface ObserveForTaskDeps {
+    contextProvider?: (goalId: string, dimensionName: string) => Promise<string | null>;
+    logger?: Logger;
+}
+/**
+ * Collect domain-specific pre-execution context for a task.
+ *
+ * Phase 1 MVP: all domains use a unified strategy — concatenate the task
+ * description with any workspace context from `contextProvider`.
+ * Domain-specific collection strategies (file graphs, schema discovery,
+ * metric snapshots, etc.) will be expanded in later phases.
+ *
+ * The assembled context is intended for `implementor` and `researcher`
+ * roles only. Do NOT pass it to `verifier` or `reviewer` (bias prevention).
+ *
+ * @param deps   Injected dependencies (contextProvider, logger).
+ * @param task   The agent task requiring pre-execution context.
+ * @param domain The task domain that governs the collection strategy.
+ */
+export declare function observeForTask(deps: ObserveForTaskDeps, task: AgentTask, domain: TaskDomain): Promise<TaskObservationContext>;
+//# sourceMappingURL=observation-task.d.ts.map

package/dist/observation/observation-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-task.d.ts","sourceRoot":"","sources":["../../src/observation/observation-task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAInD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACpB;AAeD,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,sBAAsB,CAAC,CA4BjC"}

package/dist/observation/observation-task.js

@@ -0,0 +1,51 @@
+// ─── Domain labels ───
+const DOMAIN_LABEL = {
+    code: "Target files, related tests, and module dependencies",
+    data: "Data sources, schemas, and previous observation values",
+    api_action: "API endpoints, rate limits, and authentication state",
+    research: "Known knowledge and unresolved questions",
+    monitoring: "Current metric values, alert thresholds, and recent trends",
+    communication: "Recipient context and message history",
+};
+// ─── observeForTask ───
+/**
+ * Collect domain-specific pre-execution context for a task.
+ *
+ * Phase 1 MVP: all domains use a unified strategy — concatenate the task
+ * description with any workspace context from `contextProvider`.
+ * Domain-specific collection strategies (file graphs, schema discovery,
+ * metric snapshots, etc.) will be expanded in later phases.
+ *
+ * The assembled context is intended for `implementor` and `researcher`
+ * roles only. Do NOT pass it to `verifier` or `reviewer` (bias prevention).
+ *
+ * @param deps   Injected dependencies (contextProvider, logger).
+ * @param task   The agent task requiring pre-execution context.
+ * @param domain The task domain that governs the collection strategy.
+ */
+export async function observeForTask(deps, task, domain) {
+    const sources = ["task_description"];
+    const parts = [`Task: ${task.prompt}`];
+    // Attempt to pull workspace context via contextProvider.
+    // Use the domain as the dimension key since AgentTask has no goal_id field.
+    if (deps.contextProvider) {
+        try {
+            const workspaceCtx = await deps.contextProvider("", domain);
+            if (workspaceCtx) {
+                parts.push(`Workspace context (${domain}):\n${workspaceCtx}`);
+                sources.push("context_provider");
+            }
+        }
+        catch (err) {
+            deps.logger?.warn(`[ObservationEngine] observeForTask: contextProvider failed for domain "${domain}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    parts.push(`Domain focus (${domain}): ${DOMAIN_LABEL[domain]}`);
+    return {
+        context: parts.join("\n\n"),
+        sources,
+        domain,
+    };
+}
+//# sourceMappingURL=observation-task.js.map

package/dist/observation/observation-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-task.js","sourceRoot":"","sources":["../../src/observation/observation-task.ts"],"names":[],"mappings":"AAYA,wBAAwB;AAExB,MAAM,YAAY,GAA+B;IAC/C,IAAI,EAAE,sDAAsD;IAC5D,IAAI,EAAE,wDAAwD;IAC9D,UAAU,EAAE,sDAAsD;IAClE,QAAQ,EAAE,0CAA0C;IACpD,UAAU,EAAE,4DAA4D;IACxE,aAAa,EAAE,uCAAuC;CACvD,CAAC;AASF,yBAAyB;AAEzB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAwB,EACxB,IAAe,EACf,MAAkB;IAElB,MAAM,OAAO,GAAa,CAAC,kBAAkB,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAa,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD,yDAAyD;IACzD,4EAA4E;IAC5E,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC5D,IAAI,YAAY,EAAE,CAAC;gBACjB,KAAK,CAAC,IAAI,CAAC,sBAAsB,MAAM,OAAO,YAAY,EAAE,CAAC,CAAC;gBAC9D,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,0EAA0E,MAAM,KAAK;gBACrF,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,MAAM,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAEhE,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,OAAO;QACP,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/observation/workspace-context.d.ts

@@ -0,0 +1,8 @@
+export interface WorkspaceContextOptions {
+    workDir: string;
+    maxFiles?: number;
+    maxCharsPerFile?: number;
+    externalFileMaxBytes?: number;
+}
+export declare function createWorkspaceContextProvider(options: WorkspaceContextOptions, getGoalDescription: (goalId: string) => string | undefined | Promise<string | undefined>): (goalId: string, dimensionName: string) => Promise<string>;
+//# sourceMappingURL=workspace-context.d.ts.map

package/dist/observation/workspace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-context.d.ts","sourceRoot":"","sources":["../../src/observation/workspace-context.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAuID,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,uBAAuB,EAChC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GACvF,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CA+G5D"}