pi-warden 0.28.4 → 0.34.1

package/CHANGELOG.md

@@ -8,6 +8,160 @@ How to keep this current: add the entry in the same pull request as the change,
 
 <!-- Empty. Next release starts here. -->
 
+## 0.34.1
+
+### Fixed
+- `scripts/calibrate-action.mjs`: `--yes` now spends what the corpus needs instead of stopping at the 2000-request default; `--max-requests N` is an explicit cap that `--yes` does not lift, and a run it stops early says how many replays it skipped and writes `report-latest-partial.md`.
+
+### Docs
+- Action guard calibration on 315 recorded sessions at 0.33.3 under `eval/reports/2026-09-21-calibration-0.33.3/`, with the headline table in `docs/guards.md`.
+- README measurement paragraph reworded for readability, same numbers.
+
+## 0.34.0
+
+### Added
+- `scripts/hold-stats.mjs`: read-only script reporting per-project and total hold statistics from the SQLite database, with `--json` output and `PI_WARDEN_DB` support.
+- `/warden status` now shows a lifetime hold sentence for the current project root (e.g. "Lifetime here: 55 holds, 11 labeled, 0 stood (0/11), 114 allowed accepted, 0 regretted.").
+
+### Docs
+- README "Does it actually help?" section now includes a measurement-on-real-use paragraph with current hold numbers, date, and the link to the floor-evidence decision in 0.33.0.
+
+## 0.33.4
+
+### Fixed
+- Rules guard no longer judges prose-only fallback documents (README.md, CLAUDE.md, AGENTS.md) as one rule; a fallback with no rule-shaped sections is skipped.
+
+## 0.33.3
+
+### Tests
+- Live smoke stuck suite now exercises the Jev-judged path: two new cases reach `source: "typesafe"` and print real scores; the existing offline-repeat case prints `offline repeat` instead of three `undefined` values.
+
+## 0.33.2
+
+### Fixed
+- Tests and eval runs now write to an isolated database via `PI_WARDEN_DB` instead of polluting the user's `holds.db`.
+
+## 0.33.1
+
+### Tests
+- Live smoke suite cap raised from 60 to 100 requests; summary line now reports budget-error misses.
+
+## 0.33.0
+
+### Changed
+- Built-in pattern floor is now evidence when a judge answers (`action.floor: "evidence"`, default). Built-in hits (shell rules, rm classifier, sensitive-path, outside-project) are fed to the judge as `floor_hits` in the request state and traced as `(evidence)`, but they no longer override the judge's `irreversible` score. User-declared rules keep their declared action. `action.floor: "level"` restores the legacy behaviour. Replay on 52 real holds: evidence mode drops held count from 52 to 28; level mode preserves 44 confirm + 8 warn.
+
+### Fixed
+- Deferred sensitive-path hit now warns (instead of silently allowing) when the judge fails in evidence mode with `failOpen: true`.
+
+## 0.32.0
+
+### Fixed
+- `replanned` outcomes now persist to SQLite, closing the gap where re-plan labels were set in memory but never written to the database.
+- `command_preview` stores the redacted command or path (capped at 200 chars) instead of the bare tool name.
+- Outcome known at record time (dialog-approved/declined) is no longer lost to a race between `noteOutcomes` and `learningIds.set`.
+- Set `PRAGMA busy_timeout` on the SQLite connection and skip VACUUM when no rows are pruned, preventing SQLITE_BUSY on startup with concurrent sessions. Fixes #36.
+
+### Changed
+- Judged allowed calls (`held = 0`) are now stored in SQLite alongside held calls, enabling precision and false-negative rate computation.
+- Disclosure and `docs/data-handling.md` updated to reflect that judged allowed calls are stored with `held = 0`.
+
+## 0.31.0
+
+### Added
+- `/warden audit` command: agent-driven workspace audit that sends a prompt to the session model. The model reads source, finds concrete Jev opportunities, produces measurable evidence, and writes an HTML report to `.pi-warden/audit-report.html`.
+
+### Changed
+- Bumped pi-typesafe dependency to ^0.6.1.
+
+## 0.30.4
+
+### Changed
+- Made `should_proceed` trace-only by default until calibrated, so low scores no longer ask the agent to pause. Set `action.shouldProceed.steer: true` to restore the existing steer; the `hold` threshold is unchanged.
+
+## 0.30.3
+
+### Fixed
+- Live status follows the newest verdict, including guards without sentence tokens; stack entries retain guard update order within their severity groups.
+- Action warning and hold sentences use verdict reasons instead of inferring irreversibility from the level or unrelated scores.
+
+## 0.30.2
+
+### Fixed
+- The live widget bar wraps its sentence to the pane width; one over-wide line tripped pi's render-width guard and aborted the session. Fixes #29.
+
+## 0.30.1
+
+### Fixed
+- Approval question now accepts generic task-level approval ("proceed", "yes", "go ahead", "sure") instead of requiring explicit approval of each specific action. Fixes the pattern where the model keeps holding after the user approved the whole task.
+
+### Changed
+- Approval question uses intent-based wording that lets Jev reason about approval directly rather than matching specific words.
+- Bumped pi-typesafe dependency to ^0.6.1.
+
+## 0.30.0
+
+### Added
+- Violation pipeline: deterministic per-violation authorization, escalation, and aggregation for pattern-detected and rules-guard violations.
+- `Violation`, `ViolationScope`, `Authorization`, `EscalatedViolation` types for the violation pipeline.
+- `authorize()`, `isNegated()`, `scopeMatches()`, `isAuthEligible()` (severity-based) for deterministic authorization.
+- `escalateBlastRadius()` and `escalateRulesViolation()` for Jev-backed severity escalation.
+- `aggregateLevel()` for final tool-call level from remaining violations.
+- `resolveRulesFile()` and `extractRules()` for token-aware rules file resolution.
+- `checkPiWardenMissing()` for first-run warning support.
+- `escalationThreshold` config key in `ActionGuardConfig` (default 0.85).
+- `/warden init` command: scaffolds a starter pi-warden.md with safety rules and project-type-specific rules.
+- `writeStarterRules()`, `generateStarterRules()`, `detectProjectType()`, `buildProjectContext()` in `src/init.ts`.
+- First-run warning when pi-warden.md is missing and a fallback is active.
+- Per-violation noul questions sent to Jev on the same request, returning P(yes) as a confidence value. Answers drive escalation (`escalateBlastRadius`, `escalateRulesViolation`) and aggregation (`aggregateLevel`) in the action guard pipeline. Calibrated: AUC 0.73 against regret, 0.42 against rejected turns (600 sessions, 2026-09-20).
+- `parseViolationJudgments()` for safe parsing of Jev noul responses with defaults for missing/malformed data; supports legacy choice fallback.
+- Resolved rules file (`rules`, `rulesSource`) passed to Jev in the request state.
+- `should_proceed` noul question on every action request: unified gate covering rule violations, unrequested scope, explicit constraint breaches, and material user decisions. Calibrated: AUC 0.26 against regret, 0.58 against rejected turns (600 sessions, 2026-09-20).
+- `action.shouldProceed` config key `{ hold: number }` (default 0.6): steer threshold for `should_proceed`.
+- `shouldProceedQuestion` exported from `src/guard.ts`.
+- `Verdict.shouldProceedSteer` flag for the unified gate steer.
+- `Judgment.shouldProceed` field for traceability.
+- `matchPathRules` is now exported for use by conscience-loader.
+
+### Changed
+- `ViolationScope` no longer has a `labels` field; scope matching uses paths only.
+- `Violation` no longer has an `authEligible` field; eligibility is derived from severity in `authorize()`.
+- `isAuthEligible()` now takes a `Severity` parameter instead of a `PatternHit`.
+- `escalateRulesViolation()` threshold check now matches `escalateBlastRadius()` style (guard clause for no-escalation).
+
+### Tests
+- 38 tests for authorization, escalation, aggregation, violation judgment parsing, rules-file resolution, and first-run warning.
+
+## 0.29.3
+
+### Fixed
+
+- Trace-only off-task findings no longer reach the agent through dedicated steers, generic headless warnings, or the headless `/warden test` report. Independent warning and confirmation reasons on the same call still deliver normally.
+
+## 0.29.2
+
+### Added
+
+- GitHub Actions CI for pull requests, main pushes, version tags, and manual runs: workflow lint plus typecheck, offline tests, and build on Node 22.19.0, 24, and 26.
+- Package installation smoke checks and downloadable npm tarballs with SHA-256 checksums; validated version tags prepare draft GitHub releases without publishing to npm.
+
+### Docs
+
+- Documented CI checks and manual release steps, and corrected the contributor version-bump instructions.
+
+## 0.29.1
+
+### Changed
+
+- Extracted duplicated credential-key regex alternation in `redact.ts` into a shared `CREDENTIAL_KEYS` constant.
+
+## 0.29.0
+
+### Changed
+
+- Off-task is now gated on the categorical scope answer instead of the score alone (AUC 0.51). `expected_step` vetoes off-task entirely; `unrelated` always warns; `plausible_side_step` warns trace-only. All off-task steers are trace-only until AUC clears 0.51.
+- Ledger records now include a `callExcerpt` (tool + path) for auditing off-task and intent-mismatch warns.
+
 ## 0.28.4
 
 ### Fixed

package/README.md

@@ -24,7 +24,7 @@ Works without any key (offline guards: pattern list, runaway stop, sensitive-pat
 
 | Guard | Watches | Does |
 | --- | --- | --- |
-| **Action** | `bash`, `write`, `edit` before run | Holds irreversible calls, steers off-task changes |
+| **Action** | `bash`, `write`, `edit` before run | Holds irreversible calls, records trace-only off-task findings |
 | **Rules** | every `write` and `edit` | Judges against project Markdown rules, quotes the broken rule |
 | **Slop** | code and replies | Names stubs, restating comments, dead code, hedging |
 | **Stuck** | tool results | Repeated failures using the same strategy |
@@ -74,6 +74,10 @@ An overnight stability run covered **13,952 guard cases across 109 cycles** with
 
 These are project-maintained benchmarks, not universal claims. Raw reports and reproducible eval tooling are in the repo.
 
+### Does it get in the way? Measured, not promised.
+
+**3 holds per 1,000 calls. The other 997 run.** Across 315 recorded sessions and 18,075 guarded calls, the action hold fired 48 times, each for an action that is hard to undo. On the maintainer's machine, 452 allowed calls have run since outcome tracking began and not one was regretted afterward. When a hold was wrong, one retry cleared it: 2 of 13 labeled holds stood, the other 11 cleared on retry. The 27 calls the maintainer later regretted in the replay were ordinary edits and commits, not the kind a pre-call hold can see coming; those belong to the rules guard, the done-check, and the regret label, which are measured too. Snapshot numbers: `scripts/hold-stats.mjs` refreshes them, and the full replay is in [`eval/reports/2026-09-21-calibration-0.33.3/`](eval/reports/2026-09-21-calibration-0.33.3/).
+
 [See the evals ->](eval/reports/)
 
 ## Privacy

package/dist/audit.d.ts

@@ -0,0 +1,22 @@
+export { discoverSourceFiles, findProjects } from "./discover.js";
+/**
+ * Build the user message that sends the workspace to the session model for an
+ * agent-driven audit.  The model reads source, finds Jev opportunities, produces
+ * measurable evidence, and writes an HTML report.
+ *
+ * `projects` comes from {@link findProjects}.  `cwd` is the workspace root.
+ */
+export declare function buildAuditPrompt(cwd: string, projects: string[]): string;
+export interface ReportSnapshot {
+    exists: boolean;
+    mtimeMs: number;
+}
+/**
+ * Take a point-in-time snapshot of the audit report file.  Call before
+ * sending the prompt and again after the agent finishes.
+ */
+export declare function snapshotReport(reportPath: string): ReportSnapshot;
+/**
+ * Determine whether the audit produced a new or updated report.
+ */
+export declare function reportOutcome(before: ReportSnapshot, after: ReportSnapshot): "written" | "stale" | "missing";

package/dist/audit.js

@@ -0,0 +1,110 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { redact } from "./redact.js";
+import { discoverSourceFiles, findProjects } from "./discover.js";
+export { discoverSourceFiles, findProjects } from "./discover.js";
+// ─── Prompt builder ─────────────────────────────────────────────────────────
+/**
+ * Build the user message that sends the workspace to the session model for an
+ * agent-driven audit.  The model reads source, finds Jev opportunities, produces
+ * measurable evidence, and writes an HTML report.
+ *
+ * `projects` comes from {@link findProjects}.  `cwd` is the workspace root.
+ */
+export function buildAuditPrompt(cwd, projects) {
+    const projectName = cwd.split("/").pop() ?? "workspace";
+    // Collect project summaries so the model knows the workspace shape.
+    const summaries = [];
+    for (const projectPath of projects) {
+        const name = projectPath.split("/").pop() ?? projectPath;
+        let files;
+        try {
+            files = discoverSourceFiles(projectPath);
+        }
+        catch (err) {
+            console.warn(`audit: could not discover files in ${redact(projectPath)}: ${err instanceof Error ? err.message : err}`);
+            files = [];
+        }
+        const manifests = ["package.json", "Cargo.toml", "pyproject.toml", "go.mod"];
+        let manifest = "";
+        for (const m of manifests) {
+            const p = join(projectPath, m);
+            if (existsSync(p)) {
+                manifest = m;
+                break;
+            }
+        }
+        summaries.push(`- ${name} (${files.length} source files${manifest ? `, manifest: ${manifest}` : ""})`);
+    }
+    const reportPath = join(cwd, ".pi-warden", "audit-report.html");
+    return [
+        `# Workspace Audit — ${projectName}`,
+        "",
+        "You are auditing this workspace to find concrete places where hand-written heuristics can be replaced by typed Jev (TypeSafe) questions.",
+        "",
+        "## Workspace inventory",
+        summaries.join("\n"),
+        "",
+        "## What to do",
+        "",
+        "1. **Read the actual source** of each project. Do not rely on README or manifest alone. Open the files listed above (and any others you discover) and read the code.",
+        "",
+        "2. **Find concrete replacement candidates.** Look for:",
+        "   - if/else or switch chains that classify, route, or decide",
+        "   - regex classifiers or keyword lists that label text",
+        "   - threshold tables or scoring heuristics",
+        "   - ranking or sorting by hand-built criteria",
+        "   - validation logic that checks correctness of free-form output",
+        "   - routing decisions based on intent or content",
+        "",
+        "   For each candidate, cite the exact **file:line** location.",
+        "",
+        "3. **Produce measurable data for every finding.** For each candidate, gather evidence such as:",
+        "   - Count the branches, keyword entries, or cases the current code handles",
+        "   - Count cases it misses (e.g. grep for keywords it does not cover, list known false positives from comments or issues)",
+        "   - Run the existing test suite and count pass/fail relevant to this code path",
+        "   - Write a throwaway script under the OS temp directory that feeds sample inputs through both the current code and a Jev question (using `typesafe_evaluate` when available in the session; this tool requires the operator to run `/typesafe enable` once per session — if a call fails with \"TypeSafe is disabled\", ask the operator once, and if it remains disabled, continue with the other evidence and mark those findings unmeasured)",
+        "",
+        "   A finding without measurable comparison data must be marked **\"unmeasured\"** — do not dress it up.",
+        "",
+        "4. **Rank findings** by expected improvement (high/medium/low) and setup effort (low/medium/high).",
+        "",
+        `5. **Write a self-contained HTML report** to \`${reportPath}\` (create the \`.pi-warden\` directory if it does not exist).`,
+        "   - Plain HTML + inline CSS, no external assets, no scripts that fetch anything.",
+        "   - Sections: summary, findings table, one section per finding with evidence, methodology, and what was not measured.",
+        "   - One short chat line at the end naming the file path and the finding count.",
+        "",
+        "## Constraints",
+        "",
+        "- Read-only: do not modify any project source while auditing. The only files you may write are the report and throwaway scripts under the OS temp directory.",
+        "- Be specific. Every finding must name a file:line in this workspace.",
+        "- Prefer fewer, well-evidenced findings over many thin ones.",
+        "- If no replacement opportunities exist in a project, say so briefly and move on.",
+    ].join("\n");
+}
+/**
+ * Take a point-in-time snapshot of the audit report file.  Call before
+ * sending the prompt and again after the agent finishes.
+ */
+export function snapshotReport(reportPath) {
+    if (!existsSync(reportPath))
+        return { exists: false, mtimeMs: 0 };
+    try {
+        const s = statSync(reportPath);
+        return { exists: true, mtimeMs: s.mtimeMs };
+    }
+    catch (err) {
+        console.warn(`audit: could not stat report: ${err instanceof Error ? err.message : err}`);
+        return { exists: false, mtimeMs: 0 };
+    }
+}
+/**
+ * Determine whether the audit produced a new or updated report.
+ */
+export function reportOutcome(before, after) {
+    if (!after.exists)
+        return "missing";
+    if (!before.exists || after.mtimeMs > before.mtimeMs)
+        return "written";
+    return "stale";
+}

package/dist/config.d.ts

@@ -41,6 +41,11 @@ export interface ActionGuardConfig {
     intentMismatch: number;
     /** The same, for a command whose effect is visible outside the working tree (commit, push, merge, publish, launch): less mismatch is enough. */
     visibleMismatch: number;
+    /** Low P(should_proceed) is trace-only unless steer is enabled; hold is the inclusive threshold, not a blocking decision. Calibration: AUC 0.26 against regret, 44% flagged at 0.6 (100 targeted sessions, 2026-09-20). */
+    shouldProceed: {
+        hold: number;
+        steer: boolean;
+    };
     /** Write each judged call and what the user did next (approved, declined, re-planned, regretted) to an owner-only per-session file under the agent directory; redacted, never the command. */
     feedbackLog: boolean;
     /** User-defined command rules (user file only; project files cannot set severity above warn). */
@@ -53,6 +58,11 @@ export interface ActionGuardConfig {
     pathRules: PathRule[];
     /** User-defined arming rules: editing files matching globs arms a command pattern for a window (user file only). */
     armingRules: ArmingRule[];
+    /** Jev confidence at or above this escalates a violation's severity in the blast-radius and rules-guard escalation paths. */
+    escalationThreshold: number;
+    /** When a judge answers: "evidence" (default) lets the judge decide the level from irreversible score alone, using built-in pattern hits as context; "level" restores the legacy behaviour where the floor sets the level before the judge.
+     *  User-declared rules keep their declared action in both modes. */
+    floor: "evidence" | "level";
 }
 /** A user-defined path rule: which paths, which side of the access is held, which tools, what happens on a hit. */
 export interface PathRule {

package/dist/config.js

@@ -29,12 +29,15 @@ export function defaultConfig() {
             offTask: { warn: 0.6, steer: 0.85 },
             intentMismatch: 0.9,
             visibleMismatch: 0.8,
+            shouldProceed: { hold: 0.6, steer: false },
             feedbackLog: true,
             commandRules: [],
             commandDenyRules: [],
             exemptRules: [],
             pathRules: [],
             armingRules: [],
+            escalationThreshold: 0.85,
+            floor: "evidence",
         },
         stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true },
         done: { enabled: true, claimsDone: 0.7, nudge: true },
@@ -251,6 +254,10 @@ function applyAction(base, raw, timeoutMs, source) {
         offTask: offTaskThreshold(raw.offTask, base.offTask),
         intentMismatch: probability(raw.intentMismatch, base.intentMismatch),
         visibleMismatch: Math.min(probability(raw.visibleMismatch, base.visibleMismatch), probability(raw.intentMismatch, base.intentMismatch)),
+        shouldProceed: {
+            hold: probability(raw.shouldProceed?.hold, base.shouldProceed.hold),
+            steer: boolean(raw.shouldProceed?.steer, base.shouldProceed.steer),
+        },
         feedbackLog: boolean(raw.feedbackLog, base.feedbackLog),
         // Only the user file declares these; a project file cannot add, edit, or remove them. The base (already the
         // user's rules when a project file layers on top) is carried through, so a project "action" block cannot wipe them.
@@ -261,6 +268,8 @@ function applyAction(base, raw, timeoutMs, source) {
         pathRules: source === "user" ? parsePathRules(raw.pathRules) : base.pathRules,
         // Arming rules are user-declared security policy: same gate.
         armingRules: source === "user" ? parseArmingRules(raw.armingRules) : base.armingRules,
+        escalationThreshold: probability(raw.escalationThreshold, base.escalationThreshold),
+        floor: source === "user" && (raw.floor === "level" || raw.floor === "evidence") ? raw.floor : base.floor,
     };
 }
 function applyStuck(base, raw) {

package/dist/conscience-config.d.ts

@@ -0,0 +1,21 @@
+export interface ConscienceConfig {
+    enabled: boolean;
+    skills: {
+        mode: "off" | "recommend" | "load";
+        exclude: string[];
+    };
+    tools: {
+        enabled: boolean;
+        exclude: string[];
+    };
+    timeoutMs: number;
+    maxAssessments: number;
+    maxNudges: number;
+    maxSkillBytes: number;
+    maxLoadedBytes: number;
+}
+export declare const conscienceWarnings: (config: ConscienceConfig) => readonly string[];
+export declare function disabledConscience(): ConscienceConfig;
+export declare function validConscience(value: unknown): value is ConscienceConfig;
+/** Normalize each raw layer before defaults lose the distinction between absent and explicit opt-outs. */
+export declare function mergeConscience(base: ConscienceConfig, layer: Record<string, unknown>, project: boolean): ConscienceConfig;

package/dist/conscience-config.js

@@ -0,0 +1,82 @@
+const ranges = { timeoutMs: [100, 10000], maxAssessments: [1, 10], maxNudges: [1, 5], maxSkillBytes: [1024, 131072], maxLoadedBytes: [1024, 262144] };
+const modes = ["off", "recommend", "load"];
+const warnings = new WeakMap();
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const exclusions = (value) => Array.isArray(value) && value.every(item => typeof item === "string" && /^[A-Za-z0-9_.:*\-]+$/.test(item));
+export const conscienceWarnings = (config) => warnings.get(config) ?? [];
+export function disabledConscience() {
+    return { enabled: false, skills: { mode: "off", exclude: [] }, tools: { enabled: false, exclude: [] }, timeoutMs: 1500, maxAssessments: 3, maxNudges: 2, maxSkillBytes: 32768, maxLoadedBytes: 65536 };
+}
+export function validConscience(value) {
+    if (!object(value) || typeof value.enabled !== "boolean" || !object(value.skills) || !object(value.tools))
+        return false;
+    if (!modes.includes(value.skills.mode) || !exclusions(value.skills.exclude) || typeof value.tools.enabled !== "boolean" || !exclusions(value.tools.exclude))
+        return false;
+    return Object.entries(ranges).every(([key, [min, max]]) => typeof value[key] === "number" && Number.isInteger(value[key]) && value[key] >= min && value[key] <= max);
+}
+/** Normalize each raw layer before defaults lose the distinction between absent and explicit opt-outs. */
+export function mergeConscience(base, layer, project) {
+    const notes = [...conscienceWarnings(base)];
+    const warn = (key) => notes.push(`Invalid conscience configuration: ${key}; prior policy retained or capability disabled.`);
+    const raw = object(layer.conscience) ? layer.conscience : {};
+    if (layer.conscience !== undefined && !object(layer.conscience))
+        warn("conscience");
+    const next = { ...base, skills: { ...base.skills, exclude: [...base.skills.exclude] }, tools: { ...base.tools, exclude: [...base.tools.exclude] } };
+    const action = object(layer.action) ? layer.action : {};
+    const legacyOff = action.enabled === false || action.toolRecommendation === false;
+    if (raw.enabled !== undefined && typeof raw.enabled !== "boolean")
+        warn("conscience.enabled");
+    const explicit = typeof raw.enabled === "boolean";
+    const enabled = explicit ? raw.enabled : legacyOff ? false : base.enabled;
+    next.enabled = project ? base.enabled && enabled : enabled;
+    if (layer.enabled === false)
+        next.enabled = false;
+    if (explicit && (legacyOff || layer.enabled === false))
+        notes.push("Conscience migration: conscience.enabled supersedes action.enabled/action.toolRecommendation; enabled remains the master opt-out.");
+    for (const category of ["skills", "tools"]) {
+        const value = raw[category];
+        if (value === undefined)
+            continue;
+        if (!object(value)) {
+            warn(`conscience.${category}`);
+            continue;
+        }
+        if (category === "skills" && value.mode !== undefined) {
+            if (modes.includes(value.mode)) {
+                const index = modes.indexOf(value.mode);
+                next.skills.mode = modes[project ? Math.min(index, modes.indexOf(base.skills.mode)) : index];
+            }
+            else
+                warn("conscience.skills.mode");
+        }
+        if (category === "tools" && value.enabled !== undefined) {
+            if (typeof value.enabled === "boolean")
+                next.tools.enabled = project ? base.tools.enabled && value.enabled : value.enabled;
+            else
+                warn("conscience.tools.enabled");
+        }
+        if (value.exclude !== undefined) {
+            if (exclusions(value.exclude))
+                next[category].exclude = [...new Set([...(project ? base[category].exclude : []), ...value.exclude])];
+            else {
+                warn(`conscience.${category}.exclude`);
+                if (category === "skills")
+                    next.skills.mode = "off";
+                else
+                    next.tools.enabled = false;
+            }
+        }
+    }
+    for (const key of Object.keys(ranges)) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        const [min, max] = ranges[key];
+        if (typeof value === "number" && Number.isInteger(value) && value >= min && value <= max)
+            next[key] = project ? Math.min(base[key], value) : value;
+        else
+            warn(`conscience.${key}`);
+    }
+    warnings.set(next, [...new Set(notes)]);
+    return next;
+}

package/dist/conscience-loader.d.ts

@@ -0,0 +1,26 @@
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import type { ActionGuardConfig } from "./config.js";
+export interface SkillReadRequest {
+    skill: Skill;
+    cwd: string;
+    action: ActionGuardConfig;
+    maxBytes: number;
+    signal: AbortSignal;
+    disclosed: string;
+}
+export type SkillReadResult = {
+    ok: true;
+    body: string;
+    bytes: number;
+    digest: string;
+    notice: boolean;
+} | {
+    ok: false;
+    reason: "load_denied" | "load_too_large" | "load_changed" | "load_failed" | "metadata_unsafe" | "timeout";
+};
+export declare function skillPathPolicy(skill: Skill, cwd: string, action: ActionGuardConfig, resolved?: string): {
+    allowed: boolean;
+    notice: boolean;
+};
+/** Narrow catalog read, not an agent tool call and not a filesystem sandbox. */
+export declare function readTrustedSkill(request: SkillReadRequest): Promise<SkillReadResult>;

package/dist/conscience-loader.js

@@ -0,0 +1,82 @@
+import { constants } from "node:fs";
+import { open, realpath, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { parseFrontmatter, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+import { matchPathRules } from "./guard.js";
+import { digest } from "./conscience-policy.js";
+import { safeConscienceText } from "./conscience-privacy.js";
+export function skillPathPolicy(skill, cwd, action, resolved) {
+    const hits = [skill.filePath, ...(resolved ? [resolved] : [])].flatMap(path => matchPathRules("read", { path }, cwd, action.pathRules, new Set(action.exemptRules)));
+    return { allowed: !hits.some(hit => hit.severity === "deny" || hit.severity === "destructive"), notice: hits.length > 0 };
+}
+/** Narrow catalog read, not an agent tool call and not a filesystem sandbox. */
+export async function readTrustedSkill(request) {
+    const { skill, cwd, action, signal, maxBytes } = request;
+    const check = () => signal.throwIfAborted();
+    const fingerprint = (value) => [value.dev, value.ino, value.size, value.mtimeMs, value.ctimeMs].join(":");
+    try {
+        check();
+        if (!skillPathPolicy(skill, cwd, action).allowed)
+            return { ok: false, reason: "load_denied" };
+        const advertised = resolve(cwd, skill.filePath);
+        const target = await realpath(advertised);
+        check();
+        const base = await realpath(resolve(cwd, skill.baseDir));
+        check();
+        const policy = skillPathPolicy(skill, cwd, action, target);
+        if (!policy.allowed)
+            return { ok: false, reason: "load_denied" };
+        const before = await stat(target);
+        check();
+        if (!before.isFile())
+            return { ok: false, reason: "load_failed" };
+        if (before.size > maxBytes)
+            return { ok: false, reason: "load_too_large" };
+        const handle = await open(target, constants.O_RDONLY | constants.O_NONBLOCK);
+        try {
+            check();
+            const opened = await handle.stat();
+            check();
+            if (!opened.isFile() || fingerprint(before) !== fingerprint(opened))
+                return { ok: false, reason: "load_changed" };
+            const buffer = Buffer.alloc(maxBytes + 1);
+            let count = 0;
+            while (count < buffer.length) {
+                const result = await handle.read(buffer, count, buffer.length - count, count);
+                check();
+                if (!result.bytesRead)
+                    break;
+                count += result.bytesRead;
+            }
+            if (count > maxBytes)
+                return { ok: false, reason: "load_too_large" };
+            const after = await handle.stat();
+            check();
+            const currentTarget = await realpath(advertised);
+            check();
+            const currentBase = await realpath(resolve(cwd, skill.baseDir));
+            check();
+            const current = await stat(target);
+            check();
+            if (currentTarget !== target || currentBase !== base || fingerprint(opened) !== fingerprint(after) || fingerprint(after) !== fingerprint(current) || count !== after.size)
+                return { ok: false, reason: "load_changed" };
+            const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, count));
+            if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(text))
+                return { ok: false, reason: "load_failed" };
+            const { frontmatter } = parseFrontmatter(text);
+            if ((frontmatter.name ?? basename(skill.baseDir)) !== skill.name || frontmatter.description !== skill.description || frontmatter["disable-model-invocation"] === true)
+                return { ok: false, reason: "load_changed" };
+            const body = stripFrontmatter(text);
+            if (safeConscienceText(text, request.disclosed) !== text)
+                return { ok: false, reason: "metadata_unsafe" };
+            check();
+            return { ok: true, body, bytes: count, digest: digest(text), notice: policy.notice };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return { ok: false, reason: signal.aborted ? "timeout" : "load_failed" };
+    }
+}

package/dist/conscience-policy.d.ts

@@ -0,0 +1,24 @@
+export declare const SCORE_LEVELS: string[];
+export declare const SCORE_INSTRUCTIONS = "Assess next-step usefulness of the named candidate against task, recent context, observations, supplied capabilities and constraints. A supplied workflow must not be replaced; another skill must support a new unmet need. Conversation methods may be useful before asking the user a question. An appropriate ordinary tool does not exclude a complementary skill.";
+export declare const DISPOSITION: {
+    type: "choice";
+    instructions: string;
+    criteria: {
+        advance: string;
+        awaiting_user: string;
+        no_gap: string;
+        unclear: string;
+    };
+};
+export declare const CONSCIENCE_MODEL = "jev-1.13";
+export declare const digest: (value: unknown) => string;
+export declare const QUESTION_POLICY_HASH: string;
+export interface MeasuredPolicy {
+    questionHash: string;
+    model: string;
+    recommendation: number;
+    loading: number;
+    evidence: string;
+}
+export declare const measuredPolicy: MeasuredPolicy | undefined;
+export declare function validPolicy(policy: MeasuredPolicy | undefined, model: string): policy is MeasuredPolicy;

package/dist/conscience-policy.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+export const SCORE_LEVELS = [
+    "No useful contribution to the current request, or conflicts with the supplied constraints.",
+    "Related to the subject, but already covered, premature, or unable to resolve the current need.",
+    "Addresses a concrete unmet need at the current step without displacing the active workflow.",
+    "Supplies a missing prerequisite or directly applicable documented method needed for the current step.",
+];
+export const SCORE_INSTRUCTIONS = "Assess next-step usefulness of the named candidate against task, recent context, observations, supplied capabilities and constraints. A supplied workflow must not be replaced; another skill must support a new unmet need. Conversation methods may be useful before asking the user a question. An appropriate ordinary tool does not exclude a complementary skill.";
+export const DISPOSITION = {
+    type: "choice",
+    instructions: "What is the current task disposition? An initial thinking request is not awaiting_user merely because clarification will be needed: its conversation method is an available next step. Awaiting_user requires an actual unanswered question from the assistant.",
+    criteria: {
+        advance: "A useful next step can be taken now.",
+        awaiting_user: "The assistant has already asked for information and must wait for the user.",
+        no_gap: "The request is satisfied with no useful missing step.",
+        unclear: "There is insufficient evidence to identify a useful next step.",
+    },
+};
+export const CONSCIENCE_MODEL = "jev-1.13";
+export const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const QUESTION_POLICY_HASH = digest({ levels: SCORE_LEVELS, instructions: SCORE_INSTRUCTIONS, disposition: DISPOSITION, stateVersion: 1 });
+// No shipping threshold exists until the frozen holdout and follow-through gates pass.
+export const measuredPolicy = undefined;
+export function validPolicy(policy, model) {
+    return !!policy && policy.questionHash === QUESTION_POLICY_HASH && policy.model === model && !!policy.evidence
+        && Number.isFinite(policy.recommendation) && policy.recommendation >= 0.5 && policy.recommendation <= 0.95
+        && Number.isFinite(policy.loading) && policy.loading >= policy.recommendation && policy.loading <= 0.95;
+}

package/dist/conscience-privacy.d.ts

@@ -0,0 +1,4 @@
+/** URLs are not local paths; protect them before scanning free text for filesystem spans. */
+export declare function safeConscienceText(text: string, disclosed?: string): string;
+export declare const safeCapabilityName: (name: string) => boolean;
+export declare const excludedCapability: (name: string, patterns: readonly string[]) => boolean;