Add experimental Jev semantic observer boundary

README.md

@@ -35,18 +35,37 @@ extensions/
       code/
       syntax/
   session-metrics/
+  semantic-observer/
   task/
   terminal/
+packages/
+  semantic-predicate/
 skills/
 prompts/
 docs/
 tsconfig.json
 ```
 
-Every runtime workspace now lives under `extensions/`; there is no separate `packages/` layer. `session-metrics` owns both the Pi extension and its offline CLI/analysis kernel. Multi-word extension directories use kebab-case, and the shared TypeScript configuration lives at the repository root.
+`extensions/` remains the home of Pi runtime integration. `packages/` is reserved for code that is meaningful without Pi; both are root workspaces. The experimental `semantic-predicate` package lives under `packages/` so Jev/OpenRouter evaluation can be removed or reused without changing Pi runtime contracts. `session-metrics` continues to own both its Pi extension and offline CLI/analysis kernel. Multi-word extension directories use kebab-case, and the shared TypeScript configuration lives at the repository root.
 
 The repository extension exposes `context` and `code`, and transparently strengthens the built-in `edit` path for supported source files. The old standalone Astrolabe and BM25 tool surfaces are gone; their useful structural and lexical mechanisms are internal implementation details under `src/syntax` and `src/context`.
 
-Additional independent utilities remain available through the extensions listed above. `ask` provides synchronous structured user decisions in the interactive TUI; offline session analysis is provided by the `session-metrics` CLI in `extensions/session-metrics`.
+Additional independent utilities remain available through the extensions listed above. `ask` provides synchronous structured user decisions in the interactive TUI; offline session analysis is provided by the `session-metrics` CLI in `extensions/session-metrics`. `semantic-observer` is an experimental, explicitly invoked observer: the caller selects semantic judgments, while Pi Kit builds compact evidence from task state, tracked reads/context, actual workspace changes, and executed verification. It returns advisory probabilities without changing task, verification, or completion state.
+
+
+## Experimental semantic observation
+
+`semantic-observer` treats Jev as a sensor, not an authority. It uses OpenRouter's Decisions API through the Pi-independent `packages/semantic-predicate` package and keeps thresholds or actions outside the model boundary.
+
+Context is assembled as evidence, not as a transcript:
+
+- Prefer runtime-captured primary evidence: the task goal and acceptance criteria, tracked mutations and the task-baseline Git diff, executed verification, and the successful `read`/`context` results the agent actually observed.
+- Keep fields named and structured. Questions refer to the state fields they judge rather than relying on one opaque prompt.
+- Give each judgment only the fields it needs. Questions that need different evidence are evaluated against separate minimal states; questions with the same state may be batched.
+- Keep deterministic facts in code. Jev is for semantic judgments such as scope drift or whether verification meaningfully covers a change, not whether a check exists or how many files changed.
+- Preserve probabilities. The observer does not turn Jev output into a pass/fail result; later policy may choose thresholds after the behavior has been measured.
+- Do not feed broad session history, repository dumps, or previous Jev outputs back into later state by default. Add context only when it is evidence for the next judgment.
+
+The current observer accepts only an `observations` list (`scopeDrift`, `verificationGap`, `consistencyRisk`). Evidence payloads are not authored by the calling model. It is deliberately explicit-call and advisory while the experiment is being evaluated.
 
 See [`docs/architecture.md`](docs/architecture.md) for the design rationale and runtime contracts.

docs/architecture.md

@@ -45,6 +45,45 @@ This follows the centralized asynchronous isolated delegation pattern evaluated
 
 Stable behavior belongs in tools and runtime state. `AGENTS.md` therefore contains only repository invariants and development mechanics; tool-routing and workflow state are not encoded as an always-on prompt layer. This is consistent with the repository-context results in arXiv:2602.11988.
 
+
+## Experimental semantic observation
+
+`semantic-observer` is outside the mechanical authority path. Its outputs are observations only: they cannot mutate repository state, satisfy `verify`, or unlock `task.finish`. The Pi-facing extension adapts runtime evidence; `packages/semantic-predicate` owns the Pi-independent OpenRouter Decisions API client and typed Jev primitives.
+
+The context boundary is intentionally narrower than the model context window. Jev 1.13 degrades when state contains irrelevant detail, so the observer does not treat the current conversation or repository as a default context blob. Each semantic judgment declares the evidence it needs and receives a small structured state with named fields. Primary runtime or repository evidence is preferred over a model-authored narrative summary.
+
+The observer does not ask the calling model to summarize its own work. It projects existing Pi Kit runtime state instead. `task/evidence.ts` exposes the same side-effect-free packet used by `task.review_context`: task contract and latest checkpoint, resource provenance, workspace delta, and verification evidence. The semantic observer augments that packet with a bounded Git diff from the task's captured baseline and bounded excerpts from successful `read`/`context` tool results identified by their tracked tool-call IDs.
+
+The current context views are:
+
+```text
+scopeDrift
+  task goal + acceptance
+  + current checkpoint (plan marked as hypothesis)
+  + tracked mutations + task-baseline diff
+
+verificationGap
+  task goal + acceptance
+  + tracked mutations + task-baseline diff
+  + executed verification only
+
+consistencyRisk
+  tracked mutations + task-baseline diff
+  + paths observed during the task
+  + bounded excerpts from the exact read/context results already seen
+```
+
+The caller supplies only which observation IDs to run. These are separate requests because their evidence sets differ. If future questions genuinely share the same state, they should be batched into one Decisions API request; Jev evaluates questions independently and batching avoids sending the same state repeatedly.
+
+This boundary follows four rules:
+
+1. **Filter before inference.** Retrieval and runtime state select evidence before Jev sees it.
+2. **Semantic only.** Exact checks, counts, dates, presence tests, and arithmetic stay in code.
+3. **Probabilities before policy.** Raw Noul probabilities or Choice/Score distributions are recorded first; thresholds and actions belong to deterministic policy outside the package.
+4. **No ambient accumulation.** Session history, broad diffs, repository dumps, and prior semantic answers are not automatically carried forward. A second-stage request receives earlier output only when code needs that result to construct genuinely new state.
+
+The experiment is intentionally explicit-call. Automatic hooks, escalation, or review routing should be added only after session evidence shows which judgments are useful and how their probabilities calibrate on Pi Kit work.
+
 ## Evaluation
 
 `session-metrics` reconstructs runtime behavior from Pi session JSONL without active instrumentation. In addition to generic tool/action metrics, it records the `context`, `code`, `task`, `delegate`, and `verify` surfaces and verification provenance so harness changes can be compared against historical trajectories.

extensions/background-process/index.ts

@@ -130,7 +130,8 @@ export default function backgroundProcessExtension(pi: ExtensionAPI): void {
       inspectRunning: Type.Optional(
         Type.Boolean({
           default: false,
-          description: "For check only: include stdout/stderr while a process is pending or running.",
+          description:
+            "For check only: include stdout/stderr while a process is pending or running.",
         }),
       ),
     }),

extensions/semantic-observer/evidence.test.ts

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TaskEvidencePacket } from "../task/evidence.ts";
+import { projectObservationState } from "./evidence.ts";
+
+const packet: TaskEvidencePacket = {
+  task: {
+    id: "task-1",
+    goal: "Update the parser only",
+    acceptance: ["Parser accepts the new syntax"],
+    status: "active",
+    latestCheckpoint: {
+      at: "2026-09-18T00:00:00.000Z",
+      summary: "Parser implementation is in progress",
+      plan: ["Rewrite unrelated renderer", "Update parser"],
+      completed: ["Located parser"],
+    },
+  },
+  resources: {
+    observed: ["src/parser.ts", "src/parser.test.ts"],
+    mutated: ["src/parser.ts"],
+    changedDuringTask: ["src/parser.ts"],
+    preexistingDirty: [],
+    timeline: [
+      {
+        operation: "observe",
+        path: "src/parser.ts",
+        tool: "context",
+        action: "inspect",
+        toolCallId: "context-1",
+      },
+      {
+        operation: "mutate",
+        path: "src/parser.ts",
+        tool: "code",
+        action: "edit",
+        toolCallId: "code-1",
+      },
+    ],
+    coverage: {
+      observations: "explicit-tools",
+      mutations: "explicit-tools",
+      workspaceDelta: "git",
+      opaqueToolEffects: "not-attributed",
+    },
+  },
+  verification: [
+    {
+      id: "verify-1",
+      taskId: "task-1",
+      provenance: "typecheck",
+      origin: "executed",
+      passed: true,
+      summary: "tsc --noEmit",
+      at: "2026-09-18T00:01:00.000Z",
+    },
+    {
+      id: "verify-2",
+      taskId: "task-1",
+      provenance: "self_review",
+      origin: "reported",
+      passed: true,
+      summary: "looks good",
+      at: "2026-09-18T00:02:00.000Z",
+    },
+  ],
+  workspace: {
+    baselineHead: "abc",
+    currentHead: "abc",
+    currentDirty: ["src/parser.ts"],
+    changedDuringTask: ["src/parser.ts"],
+    uncommittedTaskChanges: ["src/parser.ts"],
+    taskCommitRequired: true,
+    taskCommitPresent: false,
+  },
+};
+
+test("scope drift state uses task authority and actual changes", () => {
+  const state = projectObservationState("scopeDrift", packet, {
+    diff: "@@ parser diff @@",
+    context: [],
+  }) as any;
+
+  assert.equal(state.task.goal, "Update the parser only");
+  assert.deepEqual(state.task.acceptance, ["Parser accepts the new syntax"]);
+  assert.equal(state.task.current_stage.summary, "Parser implementation is in progress");
+  assert.equal(state.task.current_stage.plan_authority, "hypothesis");
+  assert.deepEqual(state.changes.changed_paths, ["src/parser.ts"]);
+  assert.equal(state.changes.diff, "@@ parser diff @@");
+});
+
+test("verification gap state includes only executed verification", () => {
+  const state = projectObservationState("verificationGap", packet, {
+    context: [],
+  }) as any;
+
+  assert.equal(state.verification.length, 1);
+  assert.equal(state.verification[0].provenance, "typecheck");
+  assert.equal(state.verification[0].summary, "tsc --noEmit");
+});
+
+test("consistency state reuses observed repository evidence", () => {
+  const state = projectObservationState("consistencyRisk", packet, {
+    context: [
+      {
+        tool: "context",
+        paths: ["src/parser.ts"],
+        text: "export function parse() {}",
+      },
+    ],
+  }) as any;
+
+  assert.deepEqual(state.repository_evidence.observed_paths, [
+    "src/parser.ts",
+    "src/parser.test.ts",
+  ]);
+  assert.equal(
+    state.repository_evidence.excerpts[0].text,
+    "export function parse() {}",
+  );
+});