promptwheel 0.7.5 → 0.7.7

package/INTEGRATE.md

@@ -103,7 +103,9 @@ measurement runs in a throwaway git worktree.
 
 Zero dependencies, no build step, the whole engine is one file. `check()` runs the gate in
 process and returns the Section 2 object. It never prints and never calls `process.exit`; it
-throws a plain `Error` on a precondition failure.
+throws a plain `Error` on a precondition failure. Types ship in the package
+(`bin/promptwheel.d.ts`, hand-written, no build step): `import type { Report, CheckOptions, Config } from 'promptwheel'`
+works in TypeScript, and editors complete the options and the report in plain JavaScript.
 
 ```js
 import { check, verdictExitCode, conformsToContract, VERDICTS, CONTRACT_VERSION } from 'promptwheel';

package/README.md

@@ -59,7 +59,7 @@ npx promptwheel init --list               # presets: tests-pass · lint · bundl
 # the loop: run any agent/script, keep the change ONLY if a metric improved, else revert
 npx promptwheel improve --attempt "claude -p 'reduce lint errors'"
 #   exit 0 = kept a real win · 1 = guarded regression (reverted) · 2 = gamed (reverted) · 3 = plateau / inconclusive (reverted) · add --json
-while npx promptwheel improve --attempt "$AGENT"; do :; done     # converges: stops on the first non-zero
+while npx promptwheel improve --attempt "<your agent command>"; do :; done     # converges: stops on the first non-zero
 
 npx promptwheel insights                  # which metrics actually respond in this repo (counts from .promptwheel/outcomes.jsonl)
 npx promptwheel guards                    # the effective guardrails, including ones inherited through extends

package/bin/promptwheel.d.ts

@@ -0,0 +1,314 @@
+// Type declarations for bin/promptwheel.mjs. Hand-written: there is no build step and no
+// TypeScript dependency in this package. Every runtime export of the engine is declared here
+// (test/promptwheel.test.mjs checks the list stays complete). The report shape is the
+// Verified-Outcome Contract's Section 2 verdict object; see INTEGRATE.md for the integration
+// surface and CONTRACT.md for the protocol.
+
+// ---------------------------------------------------------------------------
+// Section 2 vocabularies
+// ---------------------------------------------------------------------------
+
+/** The verdict of a check. */
+export type Verdict = 'pass' | 'fail' | 'gamed' | 'inconclusive';
+
+/** The status of one metric. A delta inside the measured noise band is `inconclusive`, never a regression. */
+export type MetricStatus = 'improved' | 'regressed' | 'unchanged' | 'inconclusive' | 'unmeasurable';
+
+/** The direction that counts as better. `pass` is a 0/1 gate (1 = the command exited 0). */
+export type Direction = 'up' | 'down' | 'pass';
+
+/** How much a delta can be trusted. `none` only on an unmeasurable metric; `unverified` is a single read with no noise sample. */
+export type Confidence = 'none' | 'unverified' | 'low' | 'medium' | 'high';
+
+/**
+ * How a metric's value is read from its command: the last number in stdout (`number`, the
+ * default), the count of non-empty lines (`lines`), the exit code as 1/0 (`exit`), or the
+ * first capture group of a regex. A command that exits nonzero reads `null` (unmeasurable)
+ * unless the metric sets `allowNonzero`; `exit` mode consumes the exit code by design.
+ */
+export type ExtractMode = 'number' | 'lines' | 'exit' | { regex: string };
+
+// ---------------------------------------------------------------------------
+// Config (promptwheel.config.json, or the `config` option of check())
+// ---------------------------------------------------------------------------
+
+export interface MetricConfig {
+  name: string;
+  /** Shell command run in a throwaway worktree at each ref. */
+  cmd: string;
+  /** Default `'number'`. */
+  extract?: ExtractMode;
+  /** Default `'up'`. */
+  direction?: Direction;
+  /** A guarded metric fails the gate on a trusted regression; an unguarded one is tracked only. */
+  guard?: boolean;
+  /** Read a value even when `cmd` exits nonzero (never needed for `extract: 'exit'`). */
+  allowNonzero?: boolean;
+  /** Per-command timeout, default 300. */
+  timeoutSec?: number;
+  /** `false` skips the source-only re-proof for this metric (tripwires whose gain legitimately lives in test files). */
+  gamingCheck?: boolean;
+  /** Per-metric override of `Config.gamingThreshold`. */
+  gamingThreshold?: number;
+}
+
+/** A named hard rule: any change touching one of `paths` fails the gate before any metric is read. */
+export interface Mandate {
+  name: string;
+  /** Globs: a bare name matches that basename at any depth, a pattern with `/` is anchored at the repo root, `**` crosses directories. */
+  paths: string[];
+  reason?: string;
+}
+
+export interface Config {
+  /** Path (or paths) to a shared base config whose metrics and mandates this repo inherits; resolved relative to the config file. */
+  extends?: string | string[];
+  metrics: MetricConfig[];
+  mandates?: Mandate[];
+  /** Measurement repeats per metric, for the noise band. Default 1. */
+  repeat?: number;
+  /** Back-compat for `linkDirs`: `false` links nothing. */
+  linkNodeModules?: boolean;
+  /** Directories outside git to symlink into each worktree (default `['node_modules']`). */
+  linkDirs?: string[];
+  /** Extra environment for the metric commands; `{wt}` expands to the worktree path. */
+  env?: Record<string, string>;
+  /** A per-ref build or install, run in the worktree before measuring (a failed setup leaves the metric inert, never a false green). */
+  setup?: string;
+  /** `false` never appends to `.promptwheel/outcomes.jsonl`. */
+  record?: boolean;
+  /** Fraction of a gain that must survive the source-only re-run; below it the win is `gamed`. Default 0.5. */
+  gamingThreshold?: number;
+  /** Extra files that define the gate (a threshold, a budget); a change to one alongside a win is gamed by declaration. Same glob rules as `Mandate.paths`. */
+  evaluatorPaths?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// check()
+// ---------------------------------------------------------------------------
+
+export interface CheckOptions {
+  /** Repo path. Default: discovered from `process.cwd()`. */
+  repo?: string;
+  /** Base ref. Default: the merge-base with `origin/main` (then `origin/master`, `main`, `master`); on the trunk itself, `HEAD~1`. */
+  base?: string;
+  /** Head ref. Default `HEAD`. */
+  head?: string;
+  /** Gate uncommitted changes (tracked and untracked) instead of `base..head`. Default `false`. */
+  working?: boolean;
+  /**
+   * A resolved config supplied in process, used as given (an `extends` chain is resolved only
+   * when the config is loaded from `promptwheel.config.json`). Omit to load the file, or to
+   * auto-detect the test command when there is none.
+   */
+  config?: Config;
+  /** Allow the zero-config auto-detect fallback when there is no config file and no `config` option. Default `true`; `false` throws instead. */
+  auto?: boolean;
+  /** Measurement repeats for the noise band. Default `config.repeat ?? 1`. */
+  repeat?: number;
+  /** Run the Section 3 source-only re-proof. Default `true`. */
+  detectGaming?: boolean;
+  /** A declared override reason (the same as `--allow` or a `Promptwheel-Allow:` commit trailer): a would-be `gamed` reads `pass`, recorded in `report.allowed`. */
+  allow?: string;
+  /** Append the run to `.promptwheel/outcomes.jsonl`. Default `false`. */
+  record?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// The report (Section 2 verdict object)
+// ---------------------------------------------------------------------------
+
+/** What `evaluate()` returns for one metric: the before/after medians and the trust call on their delta. */
+export interface Evaluation {
+  before: number | null;
+  after: number | null;
+  /** `null` when either side is unmeasurable. */
+  delta: number | null;
+  status: MetricStatus;
+  /** `false` only for a guarded metric with a trusted regression. */
+  ok: boolean;
+  confidence: Confidence;
+  /** The measured jitter band (max spread across repeats); `null` when unmeasurable. */
+  noise: number | null;
+  /** A guarded pass/fail metric stuck at 0 at both refs: it protects nothing. */
+  inert?: true;
+}
+
+export interface MetricResult extends Evaluation {
+  name: string;
+  direction: Direction;
+  guard: boolean;
+  /** `true` when the win did not survive the source-only re-run; `null` when the source-only patch did not apply. Absent without gaming detection or when the metric did not improve. */
+  gamed?: boolean | null;
+  /** The metric's value with only the source edits applied. */
+  sourceOnly?: number | null;
+  /** The fraction of the gain that survived source-only (0..1). */
+  retained?: number | null;
+  gamingReason?: string;
+  /** Set when a declared override cleared a `gamed` on this metric. */
+  allowed?: true;
+}
+
+export interface MandateViolation {
+  name: string;
+  reason: string;
+  /** The protected paths this change touched (at most 20). */
+  files: string[];
+  /** The mandate was deleted in this same change; it stays in force for the change that removes it. */
+  removed?: true;
+  /** The mandate's paths were edited in this same change; the version before the change stays in force for the change that edits it. */
+  edited?: true;
+}
+
+export interface GateWeakening {
+  name: string;
+  change: 'guard-removed' | 'guard-disabled';
+  /** What the dropped guard would have read at head under its base definition. */
+  status: MetricStatus;
+}
+
+export interface EvaluatorChange {
+  path: string;
+  /** Truncated SHA-256 of the file at each ref; `null` where the file is absent. */
+  base: string | null;
+  head: string | null;
+}
+
+/** The gate-integrity record, present when gaming detection ran. */
+export interface GateRecord {
+  /** Truncated SHA-256 of the gate definition (metrics, guards, evaluatorPaths, gamingThreshold, mandates) at each ref; `base` is `null` when there was no config at base. */
+  fingerprint: { base: string | null; head: string };
+  /** The gate definition differs between base and head. */
+  changed?: true;
+  /** Guards the change dropped that would have failed at head; non-empty forces `gamed` unless allowed. */
+  weakened?: GateWeakening[];
+  /** Declared `evaluatorPaths` files whose content changed in this diff. */
+  evaluatorChanged?: EvaluatorChange[];
+  /** A declared override cleared the weakening. */
+  allowed?: true;
+}
+
+export interface AllowedRecord {
+  reason: string;
+  /** The metric names (and `'gate'`) the override cleared. */
+  cleared: string[];
+}
+
+/** Tamper-evident receipt: re-run `(base, head, config)` and `verdictHash` must match. Additive; never changes the verdict. */
+export interface Provenance {
+  tool: 'promptwheel';
+  toolVersion: string | null;
+  baseSha: string | null;
+  headSha: string | null;
+  configHash: string;
+  verdictHash: string;
+}
+
+export interface Report {
+  /** Short SHA (or the ref as given when it cannot be resolved). */
+  base: string;
+  head: string;
+  mode: 'refs' | 'working';
+  repeat: number;
+  verdict: Verdict;
+  metrics: MetricResult[];
+  /** Present only when a mandate was violated (the verdict is then `fail`). */
+  mandates?: MandateViolation[];
+  gate?: GateRecord;
+  allowed?: AllowedRecord;
+  provenance: Provenance;
+}
+
+// ---------------------------------------------------------------------------
+// Public library API (stable across 0.x minors)
+// ---------------------------------------------------------------------------
+
+/** The Contract revision this build implements; bumps only when the verdict schema or the exit codes change. */
+export declare const CONTRACT_VERSION: '1';
+export declare const VERDICTS: readonly ['pass', 'fail', 'gamed', 'inconclusive'];
+export declare const METRIC_STATUSES: readonly ['improved', 'regressed', 'unchanged', 'inconclusive', 'unmeasurable'];
+export declare const DIRECTIONS: readonly ['up', 'down', 'pass'];
+
+/** Section 1: `pass` 0, `fail` 1, `gamed` 2, `inconclusive` 3 (any other string maps to 1). The CLI exits with this. */
+export declare function verdictExitCode(verdict: Verdict | string): 0 | 1 | 2 | 3;
+
+/**
+ * Run the gate in process and return the Section 2 verdict object (identical to `run --json`).
+ * Measures only in throwaway git worktrees, never the caller's working tree. Never prints and
+ * never calls `process.exit`; throws a plain `Error` on a precondition failure (not a git
+ * repository, `auto: false` with no config, a `config` without a non-empty `metrics` array).
+ */
+/**
+ * Runs the gate in process and returns the report. Never prints and never exits the process: a
+ * precondition failure (not a git repository, a missing, malformed or cyclic config, a missing
+ * `extends` target, no commits yet) throws an Error whose `name` is `'ConfigError'` and whose
+ * `exitCode` is 64, the code the CLI exits with for the same condition.
+ */
+export declare function check(options?: CheckOptions): Report;
+
+/**
+ * Structurally validate any verdict object against Section 2 (shapes, the fixed vocabularies,
+ * and the honest-verdict rules). Zero dependency, so a third-party implementation can self-check
+ * the artifact it emits. `errors` is empty exactly when `ok` is `true`.
+ */
+export declare function conformsToContract(report: unknown): { ok: boolean; errors: string[] };
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests and for consumers that want the arithmetic)
+// ---------------------------------------------------------------------------
+
+/** Read a metric value from a command's stdout and exit code. */
+export declare function extract(stdout: string, code: number, mode?: ExtractMode, allowNonzero?: boolean): number | null;
+
+/** Median of the non-null samples; `null` when there are none. */
+export declare function median(samples: ReadonlyArray<number | null | undefined>): number | null;
+
+/** `max - min` of the non-null samples; `0` when there are none. */
+export declare function spread(samples: ReadonlyArray<number | null | undefined>): number;
+
+/** The credibility core: compare before/after samples and trust the delta only if it clears the observed noise band. */
+export declare function evaluate(
+  metric: Pick<MetricConfig, 'direction' | 'guard' | 'extract'>,
+  beforeSamples: ReadonlyArray<number | null>,
+  afterSamples: ReadonlyArray<number | null>,
+  repeat: number,
+): Evaluation;
+
+/** Render a report as the PR-comment markdown the GitHub Action posts. */
+export declare function renderMarkdown(report: Report): string;
+
+/** The built-in classifier: is this repo-relative path test / config / grader / golden (not production source)? */
+export declare function isNonSource(path: string): boolean;
+
+/** Compile a config's `evaluatorPaths` globs into a matcher over repo-relative paths (always `false` when none are declared). */
+export declare function evaluatorMatcher(config?: { evaluatorPaths?: string[] } | null): (path: string) => boolean;
+
+/** Directional improvement of `value` over `before` (positive = better); `null` when either is missing. */
+export declare function gain(metric: { direction?: Direction }, before: number | null, value: number | null): number | null;
+
+/** The samples measured with only the source slice of the change applied. */
+export interface SourceOnlyResult {
+  samples: ReadonlyArray<number | null>;
+  /** `false` when the change touched zero production-source files. */
+  hadSourceChange: boolean;
+  /** The source-only patch did not apply cleanly, so the judgement is inconclusive. */
+  applyFailed?: boolean;
+}
+
+export interface GamingJudgement {
+  /** `null` when the source-only patch did not apply. */
+  gamed: boolean | null;
+  sourceOnly: number | null;
+  retained: number | null;
+  reason: string;
+}
+
+/** Did a metric's full-diff win survive on the source edits alone? `gamed` when less than `threshold` (default 0.5) of the gain is retained. */
+export declare function judgeGaming(
+  metric: { direction?: Direction; before: number | null; after: number | null },
+  sourceOnly: SourceOnlyResult,
+  threshold?: number,
+): GamingJudgement;
+
+/** Truncated SHA-256 of the verdict content (everything but `provenance`), the reproducible half of the receipt. */
+export declare function verdictFingerprint(report: Pick<Report, 'verdict'> & Partial<Pick<Report, 'metrics' | 'gate'>>): string;

package/bin/promptwheel.mjs

@@ -35,10 +35,13 @@ const spread = (xs) => { const a = xs.filter((x) => x != null); return a.length
 // (0 pass, 1 fail, 2 gamed, 3 inconclusive): in CI a config typo must not read as GAMED.
 const EX_USAGE = 64;
 function die(msg) { console.error(msg); process.exit(EX_USAGE); }
+// a config or precondition error: thrown, so the library path (check()) surfaces it to the caller
+// instead of exiting the host process; the CLI catches it in main() and exits EX_USAGE.
+function bad(msg) { const e = new Error(msg); e.name = 'ConfigError'; e.exitCode = EX_USAGE; throw e; }
 
 function readConfigFile(p) {
   try { return JSON.parse(readFileSync(p, 'utf8')); }
-  catch (e) { die(`invalid config ${p}: ${e.message}`); }
+  catch (e) { bad(`invalid config ${p}: ${e.message}`); }
 }
 
 const relOf = (repo, p) => { try { return relative(repo, p) || p; } catch { return p; } };
@@ -48,7 +51,7 @@ const relOf = (repo, p) => { try { return relative(repo, p) || p; } catch { retu
 // a repo INHERITS their guardrails, and a local metric of the same name overrides the inherited one.
 function resolveConfig(p, repo, label, seen) {
   const abs = realpathSync(p);
-  if (seen.has(abs)) die(`config inheritance cycle at ${relOf(repo, p)}`);
+  if (seen.has(abs)) bad(`config inheritance cycle at ${relOf(repo, p)}`);
   seen.add(abs);
   try {
     const cfg = readConfigFile(p);
@@ -57,7 +60,7 @@ function resolveConfig(p, repo, label, seen) {
     const scalars = {};
     for (const ref of [].concat(cfg.extends || [])) {
       const bp = isAbsolute(ref) ? ref : join(dirname(p), ref);
-      if (!existsSync(bp)) die(`extends target not found: ${ref} (from ${relOf(repo, p)})`);
+      if (!existsSync(bp)) bad(`extends target not found: ${ref} (from ${relOf(repo, p)})`);
       const base = resolveConfig(bp, repo, relOf(repo, bp), seen);
       for (const m of base.metrics) byName.set(m.name, m);
       for (const md of (base.mandates || [])) if (md && md.name) mandatesByName.set(md.name, md);
@@ -76,9 +79,9 @@ function resolveConfig(p, repo, label, seen) {
 
 function loadConfig(repo) {
   const p = join(repo, 'promptwheel.config.json');
-  if (!existsSync(p)) die('no promptwheel.config.json, run: promptwheel init   (writes one for your stack)');
+  if (!existsSync(p)) bad('no promptwheel.config.json, run: promptwheel init   (writes one for your stack)');
   const cfg = resolveConfig(p, repo, 'local', new Set());
-  if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) die('config.metrics must be a non-empty array');
+  if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) bad('config.metrics must be a non-empty array');
   return cfg;
 }
 
@@ -285,13 +288,18 @@ function evaluatorMatcher(cfg) {
 // so a parent scope's rule holds for every repo beneath it.
 // The mandates in force are the UNION of the head config's and the base ref's (`baseMandates`,
 // resolved by gateDefAtRef): deleting a mandate in the same change that violates it does not
-// clear it. A mandate removed at head but violated in the diff is reported with `removed: true`.
+// clear it. A mandate removed at head but violated in the diff is reported with `removed: true`; one
+// whose paths were edited at head (same name, different paths) is tested in BOTH versions and reported
+// with `edited: true`, so narrowing a rule in the change that breaks it does not clear it either.
 // The honest way to retire one is a separate change that only edits the config.
 function checkMandates(repo, base, head, cfg, baseMandates) {
   const headList = Array.isArray(cfg.mandates) ? cfg.mandates : [];
   const headNames = new Set(headList.map((m) => m && m.name).filter(Boolean));
-  const removed = (Array.isArray(baseMandates) ? baseMandates : []).filter((m) => m && m.name && !headNames.has(m.name));
-  const mandates = [...headList, ...removed.map((m) => ({ ...m, __removed: true }))];
+  const key = (m) => JSON.stringify([String(m.name), [...(Array.isArray(m.paths) ? m.paths : [])].filter((x) => typeof x === 'string').sort()]);
+  const headKeys = new Set(headList.filter((m) => m && m.name).map(key));
+  const kept = (Array.isArray(baseMandates) ? baseMandates : []).filter((m) => m && m.name && !headKeys.has(key(m)))
+    .map((m) => (headNames.has(m.name) ? { ...m, __edited: true } : { ...m, __removed: true }));
+  const mandates = [...headList, ...kept];
   if (!mandates.length) return [];
   let changed = [];
   try { changed = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean); } catch { return []; }
@@ -301,9 +309,18 @@ function checkMandates(repo, base, head, cfg, baseMandates) {
     if (!pats.length) continue;
     const res = pats.map(globToRe);
     const hit = changed.filter((f) => res.some((re) => re.test(f)));
-    if (hit.length) out.push({ name: String(m.name || 'mandate'), reason: m.reason ? String(m.reason).slice(0, 300) : '', files: hit.slice(0, 20), ...(m.__removed ? { removed: true } : {}) });
+    if (hit.length) out.push({ name: String(m.name || 'mandate'), reason: m.reason ? String(m.reason).slice(0, 300) : '', files: hit.slice(0, 20), ...(m.__removed ? { removed: true } : {}), ...(m.__edited ? { edited: true } : {}) });
   }
-  return out;
+  // one entry per name: the head version and the edited base version of a rule merge (files unioned)
+  const merged = [];
+  for (const v of out) {
+    const prev = merged.find((x) => x.name === v.name);
+    if (!prev) { merged.push(v); continue; }
+    prev.files = [...new Set([...prev.files, ...v.files])].slice(0, 20);
+    if (v.edited) prev.edited = true;
+    if (!prev.reason && v.reason) prev.reason = v.reason;
+  }
+  return merged;
 }
 
 // split the agent's changed files into production-source vs test/config/grader/golden.
@@ -626,7 +643,7 @@ function gate(repo, opts) {
     // never touches the real index or working tree. (A loop agent's most common action
     // is to ADD a file; `git stash create` omits untracked, which silently reverted them.)
     try { git(['rev-parse', '--verify', 'HEAD'], repo); }
-    catch { die('no commits yet, make an initial commit before gating --working changes'); }
+    catch { bad('no commits yet, make an initial commit before gating --working changes'); }
     base = 'HEAD';
     head = workingSnapshot(repo);
   } else {
@@ -884,6 +901,13 @@ function hasEslint(repo) {
   } catch { return false; }
 }
 
+// does git ignore this repo-relative path? `check-ignore -q` exits 0 when it does; 1 when it does
+// not; anything else (not a git repo) counts as not ignored, so init never fails on the check.
+function gitIgnores(repo, relPath) {
+  try { execFileSync('git', ['check-ignore', '-q', relPath], { cwd: repo, stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
 function init(argv) {
   if (argv.includes('--list')) {
     console.log('PromptWheel presets (promptwheel init --preset <name>):\n');
@@ -911,8 +935,14 @@ function init(argv) {
       const src = fileURLToPath(new URL(`../${pk[2]}/`, import.meta.url));
       const dst = join(repo, '.promptwheel', pk[2]);
       mkdirSync(dst, { recursive: true });
-      for (const f of readdirSync(src)) copyFileSync(join(src, f), join(dst, f));
+      const files = readdirSync(src);
+      for (const f of files) copyFileSync(join(src, f), join(dst, f));
       console.log(`  ✓ installed ${pk[2]} → .promptwheel/${pk[2]} (commit it with the config)`);
+      // the gate measures in clean worktrees, so a pack that git ignores (common: the outcome
+      // record lives in .promptwheel/ too) is absent at both refs and the metric reads
+      // unmeasurable, failing the guard with no hint why. Say so now, while it is one edit.
+      if (files.length && gitIgnores(repo, `.promptwheel/${pk[2]}/${files[0]}`))
+        console.log(`  ⚠ .promptwheel/${pk[2]} is gitignored: the gate measures in clean worktrees, so an ignored pack is absent at both refs and ${m.name} reads unmeasurable (the guard fails). Replace ".promptwheel/" in .gitignore with ".promptwheel/*" and "!.promptwheel/packs/", then commit the pack`);
       return { ...m, cmd: m.cmd.replaceAll(pk[2] + '/', `.promptwheel/${pk[2]}/`) };
     });
     note = presetName;
@@ -993,7 +1023,7 @@ const short = (repo, ref) => { try { return git(['rev-parse', '--short', ref], r
 function printHuman(r) {
   const arrowFor = (m) => (m.delta == null ? '?' : m.delta > 0 ? '▲' : m.delta < 0 ? '▼' : '=');
   console.log(`\nPromptWheel  ${r.base} → ${r.head}${r.repeat > 1 ? `  (×${r.repeat})` : ''}\n`);
-  if (r.mandates) for (const md of r.mandates) console.log(`  ⛔ MANDATE "${md.name}" violated${md.reason ? ': ' + md.reason : ''}  (touched: ${md.files.join(', ')})${md.removed ? '  [deleted in this same change; a mandate stays in force for the change that removes it]' : ''}`);
+  if (r.mandates) for (const md of r.mandates) console.log(`  ⛔ MANDATE "${md.name}" violated${md.reason ? ': ' + md.reason : ''}  (touched: ${md.files.join(', ')})${md.removed ? '  [deleted in this same change; a mandate stays in force for the change that removes it]' : md.edited ? '  [edited in this same change; the version before the change stays in force for the change that edits it]' : ''}`);
   for (const m of r.metrics) {
     const tag = m.guard ? (m.ok ? 'guard✓' : 'GUARD✗') : 'info';
     const d = m.delta == null ? 'n/a' : (m.delta > 0 ? `+${m.delta}` : `${m.delta}`);
@@ -1025,7 +1055,7 @@ function renderMarkdown(r) {
     '',
     `\`${r.base} → ${r.head}\` · ${r.mode} mode${r.repeat > 1 ? ` · ×${r.repeat}` : ''}`,
     '',
-    ...(r.mandates ? [r.mandates.map((md) => `> ⛔ **Mandate violated:** \`${md.name}\`${md.reason ? ': ' + md.reason : ''} (touched \`${md.files.join('`, `')}\`)${md.removed ? ' (deleted in this same change; it stays in force for the change that removes it)' : ''}`).join('\n'), ''] : []),
+    ...(r.mandates ? [r.mandates.map((md) => `> ⛔ **Mandate violated:** \`${md.name}\`${md.reason ? ': ' + md.reason : ''} (touched \`${md.files.join('`, `')}\`)${md.removed ? ' (deleted in this same change; it stays in force for the change that removes it)' : md.edited ? ' (edited in this same change; the version before the change stays in force for the change that edits it)' : ''}`).join('\n'), ''] : []),
     '| metric | before | after | Δ | status | confidence |',
     '|---|--:|--:|--:|---|---|',
     rows,
@@ -1260,7 +1290,7 @@ function conformance(argv) {
   process.exit(1);
 }
 
-function main() {
+function dispatch() {
   const [cmd, ...rest] = process.argv.slice(2);
   if (cmd === '--version' || cmd === '-v') { console.log(TOOL_VERSION ?? 'unknown'); process.exit(0); }
   if (cmd === 'run') run(rest);
@@ -1302,4 +1332,8 @@ function main() {
 // run the CLI only when invoked directly (resolves symlinks so the npm bin still works)
 let isMain = false;
 try { isMain = !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { /* not main */ }
+function main() {
+  try { dispatch(); }
+  catch (e) { if (e && e.name === 'ConfigError') die(e.message); throw e; }
+}
 if (isMain) main();

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "promptwheel",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "A deterministic, zero-LLM check for your coding loop. It proves every change earned its win by re-running the result from the agent's source edits alone, so a green that came from editing the test reads GAMED. Runs in CI or a Claude Code hook, or import { check } in process.",
   "type": "module",
   "bin": {
     "promptwheel": "bin/promptwheel.mjs"
   },
+  "types": "./bin/promptwheel.d.ts",
   "exports": {
-    ".": "./bin/promptwheel.mjs",
+    ".": {
+      "types": "./bin/promptwheel.d.ts",
+      "default": "./bin/promptwheel.mjs"
+    },
     "./bin/promptwheel.mjs": "./bin/promptwheel.mjs",
     "./package.json": "./package.json"
   },

package/packs/security/README.md

@@ -9,18 +9,28 @@ lower the count by editing the pattern file or a config, only by fixing the code
 
 ## Use it
 
-In your `promptwheel.config.json`:
+The pack ships inside the `promptwheel` package, not in your repo, so install it with the
+preset:
 
-```json
-{ "extends": ["packs/security/pack.json"] }
+```bash
+promptwheel init --preset security            # or --preset security-antihack, which adds the tripwires
 ```
 
-Then gate as usual:
+`init` copies the pack into `.promptwheel/packs/security/` and writes a `security_findings`
+metric that runs it from there. Commit the pack with the config: the gate measures in clean
+git worktrees, so a pack that is not in git is absent at both refs and the metric reads
+`unmeasurable` (init warns when `.promptwheel/` is gitignored; change that rule to
+`.promptwheel/*` plus `!.promptwheel/packs/`, since git cannot re-include a file under an
+ignored directory). Then gate as usual:
 
 ```bash
 promptwheel run --working          # fails if security_findings increased
 ```
 
+`pack.json` is the same metric as a config fragment for `extends`
+(`{ "extends": ["packs/security/pack.json"] }`); its command is relative to a repo that
+holds the pack at `packs/security/`, such as a vendored copy or this repository.
+
 A finding-count that drops because you fixed the code is a `PASS`; a "fix" that
 only survives with test/config/pattern edits reverted is `GAMED`.