@evoclock/pi-agentic-driver 0.9.3 → 0.9.4

package/scripts/enforcement/session_tasks_validate_pi.js

@@ -0,0 +1,235 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// `tasks validate` (rule 30): a read-only setup-time validator in the shape
+// of nudge_validate_pi.js and router_validate_pi.js. It loads everything
+// exactly as the runtime would, checks it, and exits 0 only when the tasks
+// surface is operational — otherwise nonzero with a machine-readable error
+// list. It never mutates state, never writes the board, never promotes.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+import {
+  SESSION_TASKS_SCHEMA,
+  resolveTaskListId, tasksMirrorPath, loadSnapshotFile,
+  validateSnapshot, validateSessionTask,
+  promotionIdempotencyKey, findExistingPromotedCard, resolveCallerOrigin, hasTasksCapability,
+  TASKS_CAPABILITY_ENV,
+} from "./session_tasks_core_pi.js";
+import { validateBoard } from "./task_board_core_pi.js";
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTasksConfig(repoRoot) {
+  const candidates = [
+    join(repoRoot, ".agentic-driver", "tasks.json"),
+    join(homedir(), ".config", "agentic-driver", "tasks.json"),
+  ];
+  for (const candidate of candidates) {
+    const value = readJsonIfExists(candidate);
+    if (value !== null) return { path: candidate, value };
+  }
+  return { path: null, value: null };
+}
+
+/**
+ * Validate the tasks surface. Pure observation: no writes, no promotion.
+ * Returns { valid, operational, checks, errors, warnings }.
+ */
+export function validateTasksSetup({
+  repoRoot = process.cwd(),
+  session = null,
+  boardPath = null,
+  tasksRoot = null,
+  capabilityEnv = process.env,
+  resolveOrigin = null,
+} = {}) {
+  const errors = [];
+  const warnings = [];
+  const checks = {};
+  const root = typeof repoRoot === "string" && repoRoot !== "" ? resolve(repoRoot) : process.cwd();
+
+  // 1. taskListId resolution (the same chain the runtime uses).
+  const taskListId = resolveTaskListId({ session });
+  checks.taskListId = taskListId ? { ok: true, taskListId } : { ok: false, reason: "no PI_TASK_LIST_ID, CLAUDE_CODE_TASK_LIST_ID, or session id" };
+  if (!taskListId) errors.push("taskListId could not be resolved (PI_TASK_LIST_ID, then CLAUDE_CODE_TASK_LIST_ID, then the session id)");
+
+  // 2. Session snapshot shape (picc-tasks mirror file).
+  let snapshot = null;
+  if (taskListId) {
+    const mirrorPath = tasksMirrorPath(taskListId, { tasksRoot });
+    checks.snapshot = { ok: true, path: mirrorPath, present: existsSync(mirrorPath) };
+    if (existsSync(mirrorPath)) {
+      snapshot = loadSnapshotFile(mirrorPath);
+      if (snapshot === null) {
+        checks.snapshot = { ok: false, path: mirrorPath, present: true, reason: "the snapshot does not satisfy agentic-driver.session-tasks.v1" };
+        errors.push(`session snapshot at ${mirrorPath} does not satisfy ${SESSION_TASKS_SCHEMA}`);
+      } else {
+        const ids = snapshot.tasks.map((task) => task.id);
+        if (new Set(ids).size !== ids.length) {
+          errors.push("session snapshot has duplicate task ids");
+        }
+        const hwmMax = snapshot.tasks.reduce((max, task) => {
+          const n = Number.parseInt(task.id, 10);
+          return Number.isNaN(n) ? max : Math.max(max, n);
+        }, 0);
+        if (snapshot.highWaterMark < hwmMax) {
+          errors.push(`highWaterMark ${snapshot.highWaterMark} is below the largest task id ${hwmMax}`);
+        }
+        for (const task of snapshot.tasks) {
+          if (!validateSessionTask(task)) {
+            errors.push(`task ${task.id} is outside the closed session-task shape`);
+          }
+          if (task.metadata?.origin !== undefined && task.metadata?.origin !== null
+            && !["coordinator", "worker", "legacy-unknown"].includes(task.metadata.origin)) {
+            errors.push(`task ${task.id} metadata.origin "${task.metadata.origin}" is outside the closed origin values`);
+          }
+        }
+      }
+    } else {
+      warnings.push(`no session snapshot present at ${mirrorPath} (a fresh session has none; not an error)`);
+    }
+  }
+
+  // 3. Board availability + validity (TASKS.md first; board.md never).
+  let resolvedBoardPath = boardPath;
+  if (!resolvedBoardPath) {
+    // TASKS.md first; board.md is a derived projection and is never the
+    // promotion target. When only a projection exists, the canonical path
+    // is reported so the error names the right fix.
+    const canonical = join(root, "TASKS.md");
+    resolvedBoardPath = existsSync(canonical) ? canonical : canonical;
+  }
+  if (resolvedBoardPath.endsWith("board.md")) {
+    checks.board = { ok: false, path: resolvedBoardPath, reason: "board.md is a projection; it is never the promotion target" };
+    errors.push("board.md must never be the promotion target; the canonical TASKS.md is required");
+  } else if (existsSync(resolvedBoardPath)) {
+    const markdown = readFileSync(resolvedBoardPath, "utf8");
+    const validated = validateBoard(markdown);
+    checks.board = { ok: validated.ok, path: resolvedBoardPath, cards: validated.cards.length };
+    if (!validated.ok) errors.push(...validated.errors.map((e) => `board invalid: ${e}`));
+    // 4. Linkage integrity: every promotedCardId on session tasks must
+    //    resolve to a card whose importedId points back at the task.
+    if (snapshot && taskListId) {
+      const brokenLinks = [];
+      for (const task of snapshot.tasks) {
+        const cardLink = task.metadata?.promotedCardId ?? task.metadata?.promotedcardid;
+        if (typeof cardLink !== "string" || cardLink === "") continue;
+        const card = validated.cards.find((c) => c.cardId === cardLink);
+        if (!card) { brokenLinks.push(`task ${task.id} -> card ${cardLink}: card not found`); continue; }
+        const expectedImported = findExistingPromotedCard(markdown, promotionIdempotencyKey(taskListId, task.id));
+        if (!expectedImported || expectedImported.cardId !== cardLink) {
+          brokenLinks.push(`task ${task.id} -> card ${cardLink}: card importedId does not link back`);
+        }
+      }
+      checks.linkage = { ok: brokenLinks.length === 0, brokenLinks };
+      errors.push(...brokenLinks);
+    }
+  } else {
+    checks.board = { ok: false, path: resolvedBoardPath, reason: "no TASKS.md in this workspace" };
+    warnings.push("no TASKS.md found for the workspace; promotion is unavailable until a board exists (a write tool call bootstraps one)");
+  }
+  // 5. Promotion target configuration.
+  const config = readTasksConfig(root);
+  if (config.value === null) {
+    checks.promotionConfig = { ok: true, path: null, defaults: true };
+    checks.promotionConfig.defaults = true;
+  } else {
+    const value = config.value;
+    const problems = [];
+    if (value.schema !== undefined && value.schema !== "agentic-driver.tasks.v1") {
+      problems.push(`schema "${value.schema}" is not recognized`);
+    }
+    if (value.promotion !== undefined) {
+      const p = value.promotion;
+      if (p === null || typeof p !== "object" || Array.isArray(p)) {
+        problems.push("promotion must be an object");
+      } else {
+        for (const [key, val] of Object.entries(p)) {
+          if (key === "completedTasks" && !["skip", "promote-as-done"].includes(val)) {
+            problems.push(`promotion.completedTasks "${val}" must be skip or promote-as-done`);
+          }
+          if (key === "batchAtSessionEnd" && !["offered", "off"].includes(val)) {
+            problems.push(`promotion.batchAtSessionEnd "${val}" must be offered or off`);
+          }
+        }
+      }
+    }
+    checks.promotionConfig = { ok: problems.length === 0, path: config.path, problems };
+    errors.push(...problems.map((p) => `promotion config: ${p}`));
+  }
+
+  // 6. Origin provenance + worker capability (observation only).
+  const origin = typeof resolveOrigin === "function" ? resolveOrigin() : resolveCallerOrigin();
+  checks.origin = { ok: true, origin: origin.origin, proven: origin.proven, reason: origin.reason };
+  checks.capability = {
+    ok: true,
+    loaded: hasTasksCapability({ env: capabilityEnv }),
+    marker: TASKS_CAPABILITY_ENV,
+  };
+  if (!checks.capability.loaded) {
+    warnings.push(`tasks skill capability not declared (${TASKS_CAPABILITY_ENV}); session tools still work, worker briefs must set the marker explicitly`);
+  }
+
+  const valid = errors.length === 0;
+  // Operational means ready end-to-end: valid state AND a resolvable board
+  // AND linkage clean. A missing snapshot is tolerated (fresh session).
+  const operational = valid
+    && Boolean(taskListId)
+    && Boolean(checks.board?.ok);
+  return { valid, operational, checks, errors, warnings };
+}
+
+function formatTasksValidateReport(report) {
+  const lines = [];
+  lines.push("tasks validate — unified session tasks + promotion (v1)");
+  for (const [name, check] of Object.entries(report.checks)) {
+    const ok = check.ok ? "ok" : "FAIL";
+    const detail = check.reason ?? check.taskListId ?? check.path ?? check.origin ?? "";
+    lines.push(`  [${ok}] ${name}${detail ? `: ${detail}` : ""}`);
+  }
+  for (const warning of report.warnings) lines.push(`  [warn] ${warning}`);
+  for (const error of report.errors) lines.push(`  [error] ${error}`);
+  lines.push(`result: ${report.operational ? "operational" : "not operational"}`);
+  return lines.join("\n");
+}
+
+function isEntrypoint() {
+  try {
+    return pathToFileURL(process.argv[1] ?? "").href === import.meta.url;
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  const args = process.argv.slice(2);
+  const take = (flag) => {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : null;
+  };
+  const report = validateTasksSetup({
+    repoRoot: take("--repo-root") ?? process.cwd(),
+    session: take("--session"),
+    boardPath: take("--board"),
+    tasksRoot: take("--tasks-root"),
+  });
+  process.stdout.write(`${formatTasksValidateReport(report)}\n`);
+  if (!report.valid || !report.operational) {
+    process.stderr.write(`${JSON.stringify({
+      valid: report.valid, operational: report.operational,
+      errors: report.errors, warnings: report.warnings,
+    }, null, 2)}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}

package/skills/tasks/SKILL.md

@@ -0,0 +1,110 @@
+# tasks — unified session task list + board promotion (v1)
+
+Owner-facing skill for the pi-agentic-driver session task list and
+owner-initiated promotion to the durable `TASKS.md` board.
+
+## Prior art and credit
+
+The session task tools (`TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`)
+reimplement the documented behavior of
+[`@ladbabynpm/picc-tasks`](https://www.npmjs.com/package/@ladbabynpm/picc-tasks)
+v0.2.0 (MIT, Copyright (c) 2026 Ladbaby) as prior art: the same tool names,
+the same storage model (session JSONL snapshot entries plus a disk mirror at
+`~/.pi/tasks/{taskListId}/tasks.json`), and the same result text. No code is
+copied; this is a clean AGPL-3.0-only reimplementation to the same behavior
+spec. picc-tasks is an independent project by its author, used as reference;
+it is not affiliated with, nor does it endorse, pi-agentic-driver.
+
+## What this skill owns
+
+1. The **session task list** — working memory for the current session. Every
+   task carries `metadata.origin` (`coordinator` or `worker`, with
+   `legacy-unknown` for unprovable runtime identity).
+2. **Promotion** — `TaskPromote`, an explicit owner-initiated action that
+   turns selected session tasks into `TASKS.md` cards through the trusted
+   board writer (`scripts/enforcement/task_board_core_pi.js`). The skill is
+   a writer CLIENT: it never serializes or writes board bytes itself, and it
+   never creates a second authority store.
+
+## Promotion rules (non-negotiable)
+
+- **Owner-initiated only.** Promotion is never automatic, never a
+  session-shutdown hook, and never worker-authorized.
+- **Fresh authority.** Every promotion requires the owner's actual
+  instruction quoted verbatim (`quotedInstruction`) supplied through the
+  owner-facing tool call. A digest alone is not accepted.
+- **Preview before mutation.** The preview shows the target repository root
+  and canonical `TASKS.md` path, title/description, specification,
+  definitionOfDone, stoppingPoint, scopePaths, lane, dependencies,
+  session-qualified source identity, and the resulting idempotency key.
+  Missing required board fields are errors — owner-authorized fields are
+  never invented from task text.
+- **Workers cannot promote.** Worker origin is observed (never trusted) and
+  recorded as audit metadata; a proven worker pane is refused. Unproven
+  identity is recorded as `legacy-unknown` and still requires fresh owner
+  authority.
+- **Completed tasks are skipped by default** in v1. Surviving
+  pending/in_progress tasks default to the `backlog` lane so they remain
+  dispatchable. `in-progress` lane placement does not make a card
+  dispatchable by itself.
+
+## Idempotency
+
+The promotion key binds `taskListId` + `taskId`
+(`p1-<sha256(taskListId + NUL + taskId).hex32>`): slash-free,
+collision-resistant across sessions. Retrying the same promotion returns the
+existing card and link; another session's same numeric task id never
+collides. The forward link is stored on the card as `importedId`; the
+reverse link (`metadata.promotedCardId`) is set on the session task after
+the writer confirms the write.
+
+## Batch promotion
+
+A batch is a sequence of independent writer calls. **Atomicity is not
+claimed.** Partial success is reported per task and reconciled
+deterministically using the idempotency key and the card↔session link.
+Dependency edges are mapped to writer-minted card IDs only after all cards
+in the batch exist; edges pointing outside the batch are dropped and
+recorded, never written dangling.
+
+## Worker loading contract
+
+The tasks tools ship in the package, so the session tools are present in any
+driver-equipped workspace — but presence is not authorization. The
+`AGENTIC_DRIVER_TASKS_CAPABILITY` marker is the per-session loading contract:
+worker briefs set it when the coordinator intends the worker to plan with the
+session tools, and `TaskPromote` commit **enforces** it — a session without
+the marker cannot commit a promotion regardless of what authority text it
+supplies. The marker never substitutes for the owner confirmation boundary;
+it is an additional fail-closed gate on the authority-bearing surface.
+Spawned workers receive briefs through prompts (Herdr `agent start` exposes
+no environment mechanism), so the marker must be carried in the worker brief
+text and exported by the worker's own shell setup; a worker that cannot set
+it cannot promote, which is the intended default.
+
+## Migration from picc-tasks
+
+The driver skill reads the existing picc-tasks mirror file on first run; the
+shape is identical, so snapshots replay as-is. Tasks missing
+`metadata.origin` are NEVER inferred: there is no trusted runtime source for
+a legacy task's creation context, so they backfill to `legacy-unknown` audit
+metadata on import. Existing `worker` origin values are preserved unchanged.
+
+**Rollback is not symmetric.** The file layout is preserved (re-installing
+picc-tasks finds its data intact), but custom session entries and
+UI/reminder behavior changes are retained by the driver skill and are not
+reverted by re-installing picc-tasks.
+
+## Validation (rule 30)
+
+`node scripts/enforcement/session_tasks_validate_pi.js --repo-root <root>`
+is read-only. It validates session snapshot shape, taskListId resolution,
+promotion metadata, linkage integrity, board availability (canonical
+`TASKS.md` first; `board.md` never), and promotion target configuration.
+Exit 0 only when ready; nonzero with a machine-readable error list
+otherwise. It never mutates state, never writes the board, never promotes.
+
+## Out of scope in v1
+
+No Obsidian work. No automatic worker proposal store. No session-end prompt.
+No completed-task promotion. No Vogelkop writer-authority changes.

package/templates/AGENTS.md

@@ -35,6 +35,17 @@ acceptance result, and exact next step in the existing task and report. Create
 a follow-up task only when no existing task represents the remaining work. The
 next session or worker resumes that task instead of rediscovering scope.
 
+Session task tools (`TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`) are
+available when the tasks capability is loaded for the session — declared by
+the `AGENTIC_DRIVER_TASKS_CAPABILITY` marker in the worker brief. Package
+presence is not the loading contract; a worker without the marker must not
+assume the session tools exist. Worker task lists are session-scoped:
+promotion to the durable board (`TaskPromote`) is owner-initiated only and is
+refused in worker sessions — the commit path additionally requires the
+capability marker, so a session that cannot declare it can never promote. A
+worker that believes a task deserves a board card states that in its report
+text; it never promotes and never invents an authority record.
+
 Every worker report should state:
 
 - repository and revision;

package/janus/README.draft.md

@@ -1,210 +0,0 @@
-# janus — Jev evaluation wrapper service
-
-janus is the local wrapper service for the Jev decision layer (design of
-record: `.private-planning/JEV_DECISION_LAYER_DESIGN.md` §5–§7, Revision 2.1).
-It wraps the official `@typesafe-ai/sdk` (TypeSafe Direct — the sole
-provider; the Vercel AI Gateway and merge gateway were dropped by owner
-decision) and exposes one evaluation endpoint plus health/readiness/version
-probes on loopback.
-
-## What janus does
-
-- `POST /evaluate` — evaluates typed questions (boolean / choice / score)
-  against one shared state via TypeSafe Direct (`typesafe-ai`, model `jev-latest`).
-- `GET /healthz` — liveness.
-- `GET /readyz` — readiness (gateway key resolvable from the Keychain).
-- `GET /version` — janus version, AI SDK version, schema versions, allowlist.
-
-Guarantees:
-
-- **Model allowlist** (server-side config; request-level model overrides are
-  rejected with `model_unauthorized`).
-- **Loopback only** — binds `127.0.0.1` and nothing else. No auth beyond
-  loopback; it is a local tool. There is deliberately no bind-address option.
-- **Single-flight** — identical requests (same evalInputDigest) coalesce;
-  distinct in-flight evaluations are capped (default 4) and rejected with
-  `busy`.
-- **30k-token request budget** — oversized requests are rejected with
-  `state_too_large`, never truncated silently.
-- **Redaction** — a general secrets/PII pass runs over the state before any
-  external call.
-- **Audit log** — append-only JSONL of request id, timestamps, question
-  names, verdict probabilities, and token usage. **State contents never
-  reach the audit log.** 90-day default retention, size-capped with
-  oldest-first rotation.
-- **Daily cost breaker** — token/cost ceilings in config; on exceed,
-  `/evaluate` returns `busy` with `budget_exhausted` detail until the UTC
-  day window resets.
-- **Timeouts** — 30s service-side cap; callers may pass a shorter
-  per-request `timeoutMs` (capped at 30s).
-
-## Provisioning the Keychain item
-
-The TypeSafe Direct key is read from the macOS Keychain at runtime — janus
-does not rely on inherited environment variables. The `typesafe-ai` /
-`Typesafe AI` generic-password item does not exist by default; create it
-once (interactive provisioning):
-
-```sh
-security add-generic-password -U -a typesafe-ai -s "Typesafe AI" -w
-# prompts for the secret; nothing is echoed
-```
-
-janus reads it with `security find-generic-password -w` under guarded
-capture: stdout is piped directly into memory, never echoed, never logged,
-never passed to spawned subprocesses. If the item is missing, janus returns
-`model_unauthorized` with `detail.key_unavailable: true` and `GET /readyz`
-reports 503 with the provisioning hint.
-
-Verify the item is present (no secret material is printed):
-
-```sh
-/usr/bin/security find-generic-password -s "Typesafe AI" -a typesafe-ai >/dev/null 2>&1 && echo present
-```
-
-To rotate the secret, re-run the `security add-generic-password -U` command
-above and enter the new value at the prompt (`-U` updates the existing item).
-To remove the item entirely:
-
-```sh
-security delete-generic-password -a typesafe-ai -s "Typesafe AI"
-```
-
-## Running
-
-Dev (from `janus/`):
-
-```sh
-npx tsx janus/server.ts          # listens on 127.0.0.1:8787
-```
-
-Config is read from `~/.config/typesafe-ai/jev/janus-config.json`
-(override with `JANUS_CONFIG_PATH`). Defaults work with no file:
-
-```json
-{
-  "port": 8787,
-  "modelAllowlist": ["typesafe-ai/jev"],
-  "defaultModel": "typesafe-ai/jev",
-  "maxConcurrent": 4,
-  "dailyTokenCeiling": 2000000,
-  "dailyCostCeilingUsd": 10,
-  "audit": { "path": "~/.local/share/janus/audit", "maxBytes": 10485760, "retentionDays": 90 }
-}
-```
-
-launchd — template at `janus/user.janus.plist`. The template is a starting
-point: every user-specific value (the label, the checkout path, log
-locations) is marked ADJUST in the file. Copy it out of the repository,
-adjust it, then load it:
-
-```sh
-cp janus/user.janus.plist ~/Library/LaunchAgents/
-```
-
-```sh
-launchctl load ~/Library/LaunchAgents/user.janus.plist
-```
-
-Tests (no live gateway calls — the SDK is mocked):
-
-```sh
-cd janus && npm test
-```
-
-## Endpoint contract
-
-### POST /evaluate
-
-Request:
-
-```json
-{
-  "state": "string | object | array (message histories pass directly)",
-  "questions": [
-    { "type": "boolean", "question": "Was a refund issued?", "threshold": 0.9 },
-    { "type": "choice", "question": "Route this ticket", "choices": ["billing", "tech", "other"] },
-    { "type": "score", "question": "Rate this PR" }
-  ],
-  "model": "optional; must be on the server allowlist, overrides rejected",
-  "timeoutMs": 10000
-}
-```
-
-Question schema v1 (§6), enforced atomically — any malformed, absent, or
-contradictory element fails the whole request with `validation_error`:
-
-- **boolean** — `threshold` optional, default `0.9`, comparison
-  `probability >= threshold`. Optional `criteria: {true?, false?}` labels.
-- **choice** — `choices` array REQUIRED; the verdict's `choice` is guaranteed
-  to be a member.
-- **score** — numeric 0..5, one decimal. Ordinal vocabularies must be
-  **choice** questions, not scores.
-
-§6 → SDK mapping (verified against ai@7.0.106 at launch step 1): the SDK's
-`experimental_evaluate` has **no top-level `criteria` argument**; the
-candidate set lives inside each question as a REQUIRED `criteria` field
-(choice: `Record<option, description | null>`; score: ordered level array;
-boolean: optional `{true?, false?}`). janus accepts §6's `choices` array at
-the transport layer and maps it to `criteria: {a: null, b: null, ...}`. The
-score vocabulary is passed as the ordered level array `["0".."5"]`.
-
-Success response (200):
-
-```json
-{
-  "request_id": "uuid",
-  "verdict": {
-    "Was a refund issued?": { "type": "boolean", "probability": 0.97, "passed": true },
-    "Route this ticket": { "type": "choice", "choice": "billing", "probabilities": {} },
-    "Rate this PR": { "type": "score", "score": 3.0 }
-  },
-  "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 },
-  "model": "typesafe-ai/jev",
-  "digest": "sha256 evalInputDigest"
-}
-```
-
-"Model returned false" is a **200** with `passed: false` / low probability —
-not an error.
-
-### Error taxonomy
-
-All errors: `{ "error": code, "message": ..., "request_id": ..., "detail"?: {...} }`
-
-| Code | HTTP | Meaning |
-|---|---|---|
-| `validation_error` | 400 | bad request (schema, JSON, unknown route) |
-| `state_too_large` | 413 | over the 30k-token budget; never truncated |
-| `unknown_question` | 400 | reserved for router/schema-version mismatches |
-| `model_unauthorized` | 403/502/503 | not on allowlist, credential rejected, or key unavailable (`detail.key_unavailable`) |
-| `gateway_unavailable` | 503 | gateway unreachable / model missing / rate limit |
-| `timeout` | 504 | evaluation exceeded the budget |
-| `busy` | 429 | concurrency cap or `detail.budget_exhausted` |
-| `degraded` | 503 | internal error |
-
-Callers distinguish **"model returned false"** (200, low probability) from
-**"no verdict"** (`timeout` / `gateway_unavailable`) from **"bad request"**
-(`validation_error`).
-
-## Layout
-
-```
-janus/
-  janus/
-    config.ts          config load/validate (allowlist, ceilings, retention)
-    schema.ts          §6 question schema v1 enforcement (atomic fail-closed)
-    verdict.ts         verdict enforcement (membership, ranges, thresholds)
-    budget.ts          token estimation, 30k budget, evalInputDigest
-                       redaction pass: shared library typesafe-secure
-                       lib/redaction (MIT), wired via a file: dependency
-    keychain.ts        guarded `security find-generic-password -w` capture
-    single_flight.ts   digest coalescing + concurrency cap
-    budget_breaker.ts  daily token/cost breaker
-    audit.ts           append-only JSONL audit log, rotation + retention
-    sdk.ts             THE ONLY AI SDK import site (pinned versions)
-    evaluate.ts        /evaluate pipeline + SDK error classification
-    server.ts          HTTP surface, loopback bind, entrypoint
-  tests/               node:test suites (mocked SDK, no live calls)
-  user.janus.plist  launchd template
-```