promptwheel 0.7.10 → 0.7.11

package/README.md

@@ -54,7 +54,7 @@ npx promptwheel run --working             # gate UNCOMMITTED changes (incl. newl
 npx promptwheel run --repeat 5 --json     # measure 5× to establish a noise band, emit JSON
 
 npx promptwheel init                      # optional: write promptwheel.config.json (guarded tests + antihack tripwires, + lint if eslint is set up)
-npx promptwheel init --list               # presets: tests-pass · lint · bundle-size · security · llm-eval · antihack · no-ai-tells · security-antihack
+npx promptwheel init --list               # presets: tests-pass · lint · bundle-size · security · llm-eval · antihack · no-ai-tells · security-antihack · supply-chain
 
 # 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'"
@@ -99,6 +99,8 @@ Gaming detection is on by default in `run` and `improve`; `--no-detect-gaming` g
 - **gamingThreshold**, the fraction of a win that must survive the source-only re-run to count as earned (default `0.5`). Config-level scalar, overridable per metric; inherited through `extends` like `repeat`.
 - **evaluatorPaths**, globs for files that *define* your gate (a threshold file, a budget, a CI limit). Editing one in the same diff that improves a metric is `GAMED` by declaration, deterministically. Opt-in, because only you know which files are the goalposts.
 
+- **allowable**, `true` lets a declared reason (`--allow "<reason>"`, a `Promptwheel-Allow:` commit trailer, `check({ allow })`) clear *this* metric's guarded regression for that run, recorded in `report.allowed` and on the metric as `allowed: true`. For counts where a rise is sometimes the job (the `supply-chain` preset: a new dependency), so the change passes with the reason on the record instead of the guard being loosened. Without a reason the guard fails as usual.
+
 Dependency and environment keys (config-level; `init` writes stack defaults):
 
 - **linkDirs**, dirs to symlink from your checkout into each measuring worktree, for deps that live outside git. Default `["node_modules"]`; `init` writes `[".venv"]` for Python and `[]` for Rust (`cargo test` writes to `target/`, so it is built fresh in the worktree rather than shared across refs). `"linkNodeModules": false` still works as shorthand for "link nothing".
@@ -133,6 +135,16 @@ Some rules are not a metric at all, they are a hard line: *never touch `src/auth
 
 A mandate is deterministic (a path match on the diff, zero-LLM), rides at the top of the report, and **inherits through `extends`** so a parent scope's hard rule holds for every repo beneath it. It is folded into the gate fingerprint at both refs, so quietly deleting a mandate changes the fingerprint: the report records `gate.changed: true` and prints a "gate definition changed" line, a tracked, tamper-evident change. And deleting it does not clear it: the mandates in force are the union of the base ref's and the head's, so a change that removes a mandate and touches its path in the same diff still fails (reported with `removed: true`). Retire a mandate in its own change, with the protected path untouched. (Before 0.7.5 the base-ref fingerprint did not include mandates, so this was recorded backwards: an unchanged mandate read as a changed gate and a deleted one did not, and the deletion cleared the rule.) This is the line between a contract and a request: `AGENTS.md` can *ask* an agent not to touch auth; a mandate will not let the change past the gate.
 
+### Supply chain (preset `supply-chain`)
+
+The step every npm supply-chain attack needs inside a target repo is a supply-chain edit: a lifecycle script, a new dependency, a lockfile entry that resolves somewhere other than the registry, a workflow or publish config. Those are paths and counts, so the gate can hold them deterministically, whatever steered the agent into the edit.
+
+```bash
+npx promptwheel init --preset supply-chain
+```
+
+writes `promptwheel.lock.json` (the shape of the repo, from `promptwheel lock`) and seven guarded counts that must not rise (`lifecycle_scripts`, `dependency_entries`, `lock_nonregistry_sources`, `unpinned_execution`, `install_policy_gaps`, `lock_drift`, `pins_changed`, measured by a zero-dep pack copied into `.promptwheel/packs/supply-chain/`), mandates that freeze `.github/workflows/**`, `.npmrc` and the yarn rc files, `Dockerfile*` and `docker-compose*`, `scripts/release*` and `scripts/publish*`, `CODEOWNERS`, and the Claude Code hook files, and lists the contract itself (`promptwheel.config.json`, `sawbuck.config.json`) under `evaluatorPaths`, so a change that edits it alongside a win is gamed by declaration while a change that only edits the contract still passes. When the rise is the job, say so and it is recorded: `promptwheel run --allow "needed for the CSV export (papaparse)"`. It is not a dependency firewall and not an injection detector: it does nothing about a package already compromised on the registry, and it does not decide where an instruction came from. Details in [packs/supply-chain/README.md](packs/supply-chain/README.md).
+
 ## In CI and in Claude Code
 
 **GitHub Action.** Drop this in your repo; it posts a verdict comment on every PR and fails the check on a guarded regression, a gamed win, or an inconclusive gate:
@@ -169,7 +181,7 @@ Then `/promptwheel:setup` (write a config) · `/promptwheel:gate` (gate uncommit
 
 - **Tripwire guards** (`test_count`, `skipped_tests`, `suppressions`, `assertions`, written by the plain `init` default) catch the quieter shapes: an inline suppression (`@ts-nocheck`, `eslint-disable`, `# noqa`) or a suite gutted while the metric stays flat.
 - **Gate integrity.** The gate is resolved as of the base commit too. A change that disables a guard or deletes a guarded metric in the same diff it passes is re-measured under the base definition and reads `GAMED` if that guard would have failed. The gate definition (metrics, guards, `evaluatorPaths`, `gamingThreshold`, `mandates`) is fingerprinted at both refs; a difference is recorded as `gate.changed` and printed.
-- **A sanctioned override.** When you *do* mean to change a test, config, or grader, declare it: a `Promptwheel-Allow: <reason>` trailer on the commit (`Sawbuck-Allow:` is accepted as an alias), `--allow "<reason>"` on the CLI, or the `allow` option on `check()`, turns what would read `GAMED` into a `pass` with the reason recorded in `report.allowed`. It covers a win whose source-only re-run could not be applied (`unprovable`, otherwise `inconclusive`) the same way. An undeclared test-only win is still `gamed`, and a reasonless declaration does not override. The check never judges intent; it forces intent to be explicit and auditable.
+- **A sanctioned override.** A commit trailer can be written by whoever writes the commit, including an agent, so `"allowTrailer": false` in the contract turns trailers off and only the `--allow` flag counts (the supply-chain preset sets this; the contract at the base ref decides, so a change cannot turn trailers back on for itself). When you *do* mean to change a test, config, or grader, declare it: a `Promptwheel-Allow: <reason>` trailer on the commit (`Sawbuck-Allow:` is accepted as an alias), `--allow "<reason>"` on the CLI, or the `allow` option on `check()`, turns what would read `GAMED` into a `pass` with the reason recorded in `report.allowed`. It covers a win whose source-only re-run could not be applied (`unprovable`, otherwise `inconclusive`) the same way. An undeclared test-only win is still `gamed`, and a reasonless declaration does not override. The check never judges intent; it forces intent to be explicit and auditable.
 - **A provenance receipt** on every verdict (`report.provenance`: base and head SHAs, a config hash, a verdict hash), so a skeptic can re-run `(base, head, config)` and get the same hash.
 
 **The honest limit.** This is one layer, not a silver bullet. It catches the evaluator-tampering class (test, grader, golden and config edits) deterministically and for free. It is blind, by construction, to a cheat that lives in the source file itself (a hardcoded answer, behavior that differs under test): that needs held-out tests, an LLM judge, or a human, and those expensive layers should be reserved for the calls only they can make. The coverage matrix and the in/out-of-scope boundary are in [docs/DETECTION-LAYERS.md](docs/DETECTION-LAYERS.md); the measured numbers are in [bench/RESULTS.md](bench/RESULTS.md) (`node bench/gaming-bench.mjs` to reproduce). Another gameable thing, an LLM judge asking "did you cheat?", is deliberately not part of the check.

package/bin/promptwheel.d.ts

@@ -40,6 +40,8 @@ export interface MetricConfig {
   extract?: ExtractMode;
   /** Default `'up'`. */
   direction?: Direction;
+  /** `true`: the value is a fingerprint, so any change at all regresses, whichever way the number moves. */
+  exact?: boolean;
   /** 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'`). */
@@ -50,6 +52,14 @@ export interface MetricConfig {
   gamingCheck?: boolean;
   /** Per-metric override of `Config.gamingThreshold`. */
   gamingThreshold?: number;
+  /**
+   * `true` lets a declared reason (`--allow`, a `Promptwheel-Allow:` trailer, `check({ allow })`) clear
+   * THIS metric's guarded regression for that run, recorded in `report.allowed` and on the metric as
+   * `allowed: true`. The supply-chain preset's counters use it: a new dependency is sometimes the job,
+   * so it passes with the reason on the record instead of the guard being loosened. Without a reason
+   * the guard fails as usual.
+   */
+  allowable?: boolean;
 }
 
 /** A named hard rule: any change touching one of `paths` fails the gate before any metric is read. */
@@ -149,6 +159,8 @@ export interface MetricResult extends Evaluation {
   gamingReason?: string;
   /** Set when a declared override cleared a `gamed` or an `unprovable` on this metric. */
   allowed?: true;
+  /** Present (`true`) only when this guarded metric regressed, no reason was declared, and `allowable: true` means a `--allow` / trailer reason would clear it. */
+  allowable?: true;
 }
 
 export interface MandateViolation {

package/bin/promptwheel.mjs

@@ -83,13 +83,13 @@ function resolveConfig(p, repo, label, seen) {
       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);
-      for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths']) if (base[k] !== undefined) scalars[k] = base[k];
+      for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths', 'allowTrailer']) if (base[k] !== undefined) scalars[k] = base[k];
     }
     for (const m of (cfg.metrics || [])) {
       byName.set(m.name, { ...m, __src: label, __override: byName.has(m.name) });
     }
     for (const md of (cfg.mandates || [])) if (md && md.name) mandatesByName.set(md.name, { ...md, __src: label });
-    for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths']) if (cfg[k] !== undefined) scalars[k] = cfg[k];
+    for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths', 'allowTrailer']) if (cfg[k] !== undefined) scalars[k] = cfg[k];
     return { ...scalars, metrics: [...byName.values()], mandates: [...mandatesByName.values()] };
   } finally {
     seen.delete(abs); // only ACTIVE ancestors are a cycle, a diamond (a base reached two ways) is fine
@@ -228,6 +228,7 @@ function evaluate(m, beforeS, afterS, repeat) {
   if (dir === 'up') { improved = delta > 0; regressed = delta < 0; }
   else if (dir === 'down') { improved = delta < 0; regressed = delta > 0; }
   else if (dir === 'pass') { improved = after === 1 && before !== 1; regressed = after < before; }
+  if (m.exact === true) { improved = false; regressed = delta !== 0; }   // a fingerprint: any change at all needs a reason
 
   let status;
   if (withinNoise && delta !== 0) { status = 'inconclusive'; improved = regressed = false; } // within measured noise → don't call it
@@ -333,7 +334,7 @@ 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 } : {}), ...(m.__edited ? { edited: 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.allowable ? { allowable: m.allowable } : {}), ...(m.__removed ? { removed: true } : {}), ...(m.__edited ? { edited: true } : {}) });
   }
   // one entry per name: the head version and the edited base version of a rule merge (files unioned)
   const merged = [];
@@ -501,7 +502,7 @@ function warnEditableInstall(repo) {
 // guarded metric in the very diff it "passes". We resolve the gate as of BASE too and, if a
 // guard was dropped, re-measure it under its BASE definition; the pass only reads GAMED when
 // that guard WOULD HAVE FAILED at head (a real regression hidden by moving the goalposts).
-const GATE_SCALARS = ['gamingThreshold', 'evaluatorPaths'];
+const GATE_SCALARS = ['gamingThreshold', 'evaluatorPaths', 'allowTrailer'];
 
 // Resolve the gate definition as of `ref` (metrics + mandates + scalars), following `extends` by
 // reading every file from that ref via `git show`, mirroring resolveConfig (a parent's mandates
@@ -731,7 +732,12 @@ function gate(repo, opts) {
   // It covers an `unprovable` win too (the source-only re-run could not be applied): the declared
   // intent is exactly the uncertainty that verdict expresses, and without this a declared change
   // whose source slice will not re-apply had no override short of turning the check off.
-  const allow = opts.allow ? { reason: String(opts.allow).slice(0, 300) } : (opts.working ? null : readAllowTrailer(repo, head));
+  // A trailer is off when the committed contract says `allowTrailer: false` or the caller set
+  // PROMPTWHEEL_NO_ALLOW_TRAILER (Sawbuck does, for a commit an agent made): an agent can write a
+  // commit message, so where the threat is the agent itself only the --allow flag counts. The base
+  // ref's contract is read too, so an agent cannot turn trailers back on in the change it is making.
+  const trailersOff = () => !!process.env.PROMPTWHEEL_NO_ALLOW_TRAILER || cfg.allowTrailer === false || ((gateDefAtRef(repo, base) || {}).scalars || {}).allowTrailer === false;
+  const allow = opts.allow ? { reason: String(opts.allow).slice(0, 300), by: 'flag' } : (opts.working || trailersOff() ? null : readAllowTrailer(repo, head));
   let allowed = null;
   if (opts.detectGaming && allow) {
     const gm = metrics.filter((m) => m.gamed === true);
@@ -745,11 +751,37 @@ function gate(repo, opts) {
       if (gw) gateInfo.allowed = true;
     }
   }
+  // `allowable: true` on a guarded metric (the supply-chain counters: a new dependency or lifecycle
+  // script is sometimes the job) lets the same declared reason clear THAT metric's regression, so the
+  // change passes with the reason on the record instead of the guard being loosened to let it through.
+  // Never implicit: without a reason an allowable guard fails like any other, and the reason is recorded.
+  {
+    // `allowable: 'flag'` takes the reason from the --allow flag only, never from a commit trailer: an
+    // agent can write a trailer, so a guard meant to stop a compromised agent cannot be cleared by one.
+    const mode = new Map((cfg.metrics || []).filter((c) => c && c.allowable && c.name).map((c) => [c.name, c.allowable]));
+    const ga = metrics.filter((m) => m.guard && !m.ok && mode.has(m.name) && (mode.get(m.name) === true || !allow || allow.by === 'flag'));
+    const held = metrics.filter((m) => m.guard && !m.ok && mode.has(m.name) && !ga.includes(m));
+    for (const m of held) m.allowable = true;
+    if (ga.length && allow) {
+      allowed = allowed || { reason: allow.reason, cleared: [] };
+      for (const m of ga) { m.ok = true; m.allowed = true; allowed.cleared.push(m.name); }
+    } else for (const m of ga) m.allowable = true;   // failed, and a declared reason would clear it: say so in the report
+  }
   // mandates run first: a protected-path hard rule fails the gate no matter what the metrics say.
   // The base ref's mandates count too (resolved through `extends` by gateDefAtRef), so a change
   // cannot clear a mandate by deleting it in the same diff that violates it.
   const baseMandates = (gateInfo && gateInfo.baseMandates) || (!opts.detectGaming ? ((gateDefAtRef(repo, base) || {}).scalars || {}).mandates : null);
-  const mandateViolations = checkMandates(repo, base, head, cfg, baseMandates);
+  let mandateViolations = checkMandates(repo, base, head, cfg, baseMandates);
+  // an allowable mandate (the lock file) changes only with a reason from the --allow flag, recorded
+  // like any other override; a commit trailer never clears one.
+  if (allow && allow.by === 'flag') {
+    const clear = mandateViolations.filter((v) => v.allowable);
+    if (clear.length) {
+      allowed = allowed || { reason: allow.reason, cleared: [] };
+      for (const v of clear) allowed.cleared.push(`mandate:${v.name}`);
+      mandateViolations = mandateViolations.filter((v) => !v.allowable);
+    }
+  }
   const mandated = mandateViolations.length > 0;
   const verdict = deriveVerdict(metrics, gateInfo, mandated);
   const report = {
@@ -900,6 +932,32 @@ const PRESETS = {
     metrics: [
       { name: 'em_dashes', cmd: 'grep -rIoe "—" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=coverage --exclude-dir=.next --exclude-dir=out --exclude-dir=lib-cov --exclude-dir=__pycache__ --exclude-dir=.pytest_cache --exclude-dir=target --exclude-dir=.venv --exclude-dir=venv --exclude=promptwheel.config.json . 2>/dev/null | wc -l | tr -d " "', extract: 'number', direction: 'down', guard: true, gamingCheck: false },
     ] },
+  // supply-chain: the step every npm supply-chain attack needs inside a target repo is a supply-chain
+  // edit (a lifecycle script, a new dependency, a non-registry lock source, a workflow or publish
+  // config). Paths and counts, checked deterministically: three guarded counts that must not rise
+  // without a declared reason (`allowable`), plus mandates that freeze the paths. The contract itself is
+  // an evaluatorPath, not a mandate, so a person can still retire a rule in a change that only edits it.
+  'supply-chain': { allowTrailer: false, desc: 'gate: no new lifecycle scripts, dependencies, or non-registry lock sources without a recorded reason; the agent cannot touch workflows, registries, publish scripts, or the contract',
+    evaluatorPaths: ['promptwheel.config.json', 'sawbuck.config.json'],
+    mandates: [
+      { name: 'workflows-frozen', paths: ['.github/workflows/**'], reason: 'workflows run with the repository secrets; change them in a separate, reviewed change' },
+      { name: 'registry-config-frozen', paths: ['.npmrc', '.yarnrc', '.yarnrc.yml'], reason: 'registry and token configuration decides where packages come from and where credentials go' },
+      { name: 'build-images-frozen', paths: ['Dockerfile*', 'docker-compose*'], reason: 'what runs at build and deploy time is not an agent decision' },
+      { name: 'publish-scripts-frozen', paths: ['scripts/release*', 'scripts/publish*'], reason: 'the publish path is how a compromise spreads' },
+      { name: 'codeowners-frozen', paths: ['CODEOWNERS'], reason: 'review ownership is set by people' },
+      { name: 'scanner-frozen', paths: ['.promptwheel/packs/**'], reason: 'the scanners that read the contract are not edited by the change they read' },
+      { name: 'lock-frozen', paths: ['promptwheel.lock.json'], allowable: 'flag', reason: 'the architecture lock changes with a reason from a person (--allow), never as a side effect of a change' },
+      { name: 'hooks-frozen', paths: ['.claude/settings.json', '.claude/settings.local.json', '.sawbuck/**'], reason: 'the hooks that enforce the contract are wired by a person, not detached by the agent' },
+    ],
+    metrics: [
+      { name: 'lifecycle_scripts', cmd: 'node packs/supply-chain/scan.mjs lifecycle .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'dependency_entries', cmd: 'node packs/supply-chain/scan.mjs deps .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'lock_nonregistry_sources', cmd: 'node packs/supply-chain/scan.mjs lock-sources .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'unpinned_execution', cmd: 'node packs/supply-chain/scan.mjs unpinned .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'install_policy_gaps', cmd: 'node packs/supply-chain/scan.mjs policy .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'lock_drift', cmd: 'node packs/supply-chain/lock.mjs drift .', extract: 'number', direction: 'down', guard: true, gamingCheck: false, allowable: 'flag' },
+      { name: 'pins_changed', cmd: 'node packs/supply-chain/lock.mjs pins .', extract: 'number', direction: 'down', exact: true, guard: true, gamingCheck: false, allowable: 'flag' },
+    ] },
 };
 
 // security-antihack = the security-invariant findings gate + the SAME antihack tripwires
@@ -985,19 +1043,23 @@ function init(argv) {
   if (existsSync(out) && !argv.includes('--force')) die('promptwheel.config.json already exists, pass --force to overwrite');
   const pi = argv.indexOf('--preset');
   const presetName = pi >= 0 ? argv[pi + 1] : null;
-  let metrics, note, evaluatorPaths;
+  let allowTrailer, metrics, note, evaluatorPaths, mandates;
   if (presetName) {
     const p = PRESETS[presetName];
     if (!p) die(`unknown preset "${presetName}", try: promptwheel init --list`);
     evaluatorPaths = p.evaluatorPaths;   // a preset may ship a starter evaluator allowlist (e.g. security-antihack)
+    mandates = p.mandates; allowTrailer = p.allowTrailer;               // a preset may ship hard rules (supply-chain: workflows, registries, publish scripts, hooks)
     metrics = p.metrics || [{ name: 'tests_pass', cmd: detectTestCmd(repo), extract: 'exit', direction: 'pass', guard: true }];
     metrics = metrics.map((m) => m.cmd === '__TESTCMD__' ? { ...m, cmd: detectTestCmd(repo) } : m); // fill the preset's target
     // pack-backed presets: the referenced scripts live in THIS package, not
     // the user's repo, copy them in so the generated config is
     // self-contained and committable (a bare reference silently 404'd)
+    const installed = new Set();   // a pack several metrics run (supply-chain) is copied and announced once
     metrics = metrics.map((m) => {
       const pk = /(^|\s)(packs\/[\w-]+)\//.exec(m.cmd);
       if (!pk) return m;
+      if (installed.has(pk[2])) return { ...m, cmd: m.cmd.replaceAll(pk[2] + '/', `.promptwheel/${pk[2]}/`) };
+      installed.add(pk[2]);
       const src = fileURLToPath(new URL(`../${pk[2]}/`, import.meta.url));
       const dst = join(repo, '.promptwheel', pk[2]);
       mkdirSync(dst, { recursive: true });
@@ -1025,8 +1087,10 @@ function init(argv) {
   const setup = presetName ? undefined : detectSetup(repo);
   const envCfg = presetName ? {} : { ...detectEnv(repo), ...(setup ? { setup } : {}) };
   if (envCfg.linkDirs) note += ` · linking ${envCfg.linkDirs.join(', ')}`;
-  writeFileSync(out, JSON.stringify({ repeat: 1, ...envCfg, ...(evaluatorPaths ? { evaluatorPaths } : {}), metrics }, null, 2) + '\n');
+  writeFileSync(out, JSON.stringify({ repeat: 1, ...envCfg, ...(evaluatorPaths ? { evaluatorPaths } : {}), ...(mandates ? { mandates } : {}), ...(allowTrailer === false ? { allowTrailer } : {}), metrics }, null, 2) + '\n');
   console.log(`✓ wrote promptwheel.config.json, ${note}`);
+  const lockTool = join(repo, '.promptwheel', 'packs', 'supply-chain', 'lock.mjs');
+  if (existsSync(lockTool)) console.log(`✓ ${execFileSync(process.execPath, [lockTool, 'write', repo], { encoding: 'utf8' }).trim()} (commit it with the config)`);
   warnEditableInstall(repo);   // one-time advice at setup, never on the per-turn path
   if (!argv.includes('--no-agent-block')) {
     const wrote = writeAgentBlock(repo);
@@ -1102,6 +1166,7 @@ function printHuman(r) {
   const failReason = r.mandates ? ', a mandate was violated (a protected path changed)' : ', a guarded metric regressed (beyond noise)';
   console.log(`\n  VERDICT: ${r.verdict.toUpperCase()}${r.verdict === 'fail' ? failReason : r.verdict === 'gamed' ? ', a metric "improved" by editing the goalposts, not the source' : r.verdict === 'inconclusive' ? ', a guard is inert (measured nothing); a pass cannot be certified' : ''}`);
   if (r.verdict === 'fail' && r.mandates) console.log('  a mandate is a hard rule; if the change is truly intended, edit the mandate in promptwheel.config.json (a tracked, tamper-evident change), do not work around it');
+  else if (r.verdict === 'fail' && r.metrics.some((m) => m.allowable)) console.log(`  intentional? this guard accepts a person's declared reason: promptwheel run --allow "<reason>" passes with the reason on the record (${r.metrics.filter((m) => m.allowable).map((m) => m.name).join(', ')})`);
   else if (r.verdict === 'fail') console.log('  intentional? loosen that guard locally in promptwheel.config.json (guard:false, or override the inherited metric by name), `promptwheel guards` shows the effective set');
   if (r.allowed) console.log(`  ✓ allowed: ${r.allowed.cleared.join(', ')} acknowledged as an intentional change, recorded (Promptwheel-Allow: ${r.allowed.reason})`);
   console.log('');
@@ -1368,7 +1433,7 @@ function conformance(argv) {
 const GATE_FLAGS = ['--base', '--head', '--repeat', '--working', '--no-record', '--no-auto', '--allow', '--detect-gaming', '--no-detect-gaming', '--json', '--markdown'];
 const COMMAND_FLAGS = {
   run: GATE_FLAGS, improve: [...GATE_FLAGS, '--attempt'], insights: ['--json'], guards: ['--json'],
-  init: ['--preset', '--list', '--force', '--no-agent-block'], conformance: ['--cmd'],
+  init: ['--preset', '--list', '--force', '--no-agent-block'], conformance: ['--cmd'], lock: [],
 };
 const VALUED_FLAGS = new Set(['--base', '--head', '--repeat', '--allow', '--attempt', '--preset', '--cmd']);
 function checkFlags(cmd, argv) {
@@ -1381,6 +1446,14 @@ function checkFlags(cmd, argv) {
   }
 }
 
+// write or refresh the architecture lock from the tree as it stands. A person runs this: the lock file is
+// a mandate, so the refreshed file passes the gate only with --allow "<reason>".
+async function lock() {
+  const repo = repoRoot(process.cwd());
+  const { writeLock, LOCK_FILE } = await import(new URL('../packs/supply-chain/lock.mjs', import.meta.url));
+  console.log(`✓ ${writeLock(repo)} items locked in ${LOCK_FILE} (commit it; a later change to it needs promptwheel run --allow "<reason>")`);
+}
+
 function dispatch() {
   const [first, ...rest] = process.argv.slice(2);
   if (first === '--version' || first === '-v') { console.log(TOOL_VERSION ?? 'unknown'); process.exit(0); }
@@ -1392,6 +1465,7 @@ function dispatch() {
   else if (cmd === 'init') init(rest);
   else if (cmd === 'guards') guards(rest);
   else if (cmd === 'conformance') conformance(rest);
+  else if (cmd === 'lock') lock(rest);
   else {
     const help = !cmd || cmd === '--help' || cmd === '-h' || cmd === 'help';
     if (!help) console.error(`unknown command: ${cmd}`);
@@ -1400,6 +1474,7 @@ function dispatch() {
       '',
       '  promptwheel --version | -v                   print the version',
       '  promptwheel --help | -h                      this banner',
+      '  promptwheel lock                             write promptwheel.lock.json, the shape of this repo (dependencies, install scripts, workflows, modules, import edges, routes, entry points, hosts); the supply-chain preset holds it',
       '  promptwheel init [--preset <name> | --list] [--no-agent-block]  write a starter config + an AGENTS.md guide so your agent runs the gate (OPTIONAL: run works zero-config, auto-detecting your test command)',
       '  promptwheel run [--base R] [--head R] [--repeat N] [--json|--markdown]',
       '       catches reward-hacking BY DEFAULT, re-proves each win from SOURCE edits alone (verdict GAMED,',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptwheel",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "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": {

package/packs/supply-chain/README.md

@@ -0,0 +1,103 @@
+# PromptWheel supply-chain guard-pack
+
+The step every npm supply-chain attack needs inside a target repo is a supply-chain edit: a
+lifecycle script, a new dependency, a lockfile entry that resolves somewhere other than the
+registry, a workflow or publish config. Those are paths and counts, and paths and counts are what
+the gate checks deterministically. This pack holds the counts; the preset that installs it also
+writes the mandates that freeze the paths.
+
+```bash
+promptwheel init --preset supply-chain
+```
+
+`init` copies the pack into `.promptwheel/packs/supply-chain/`, writes seven guarded metrics that run
+it from there, and writes the mandates below. 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 metrics read
+`unmeasurable` (init warns when `.promptwheel/` is gitignored).
+
+## The seven counts
+
+- **lifecycle_scripts**: install-time script entries (`preinstall`, `install`, `postinstall`,
+  `prepare`, `prepublish`, `prepublishOnly`, `postpack`) across every `package.json` in the repo.
+- **dependency_entries**: dependency entries across every `package.json` (`dependencies`,
+  `devDependencies`, `optionalDependencies`, `peerDependencies`).
+- **lock_nonregistry_sources**: lockfile entries (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`)
+  resolved from somewhere other than the npm registry (git, ssh, http, a tarball on another host,
+  `file:`) plus registry entries that carry no integrity hash. Workspace links inside the repo do not
+  count. A private registry mirror makes this baseline large, not failing.
+- **unpinned_execution**: code run from a reference that can move. A GitHub Action not pinned to a full commit SHA (a local `./action` does not count), `npx`, `bunx` or `dlx` with no exact version, `npm install -g` with no exact version, and a remote script piped into a shell. Read from workflows, `action.yml`, package.json scripts, `scripts/*.sh` and Dockerfiles. In package.json scripts, a tool the manifest declares does not count: the lockfile already pins it.
+- **install_policy_gaps**: 0, 1 or 2. Are install scripts disabled, and is a release-age cooldown set (`ignore-scripts=true` and `min-release-age` in `.npmrc`, or the pnpm or yarn equivalents)? The cooldown is enforced by the package manager, not by this pack: a registry lookup here would make the verdict depend on the clock.
+- **lock_drift**: structural items the tree has that `promptwheel.lock.json` does not. `promptwheel lock` reads the repo once and writes its shape: dependencies, install scripts, workflows, modules, import edges between modules, routes, public entry points, and the network hosts the source names. It also records each script's body, native binaries, and what a module can do (network, process spawning, eval), so a new capability shows even when the host is built at runtime. Ordinary edits never touch it. A new route is reported but not held by default; add `--routes` to hold it. On 1,403 commits across eight repositories this guard would have stopped 5.1%, about one in 20. JS and TS only for edges, routes, hosts and capabilities today.
+- **pins_changed**: a fingerprint of the resolved dependency tree, compared base to head, because a new version under an old name is how a worm arrives. It covers every package, version, source and integrity, not the file's bytes, so a release of your own project does not count. Any change needs a reason. Nothing is stored, so the lock does not change across updates and an approved update does not blind the next check. On the same commits this stopped 8.7%, all real dependency changes; use the CI path below for those.
+
+**Dependency updates in CI.** Give the reason from a step the agent cannot reach. Workflows are a frozen path, so an agent cannot edit this:
+
+```yaml
+- uses: promptwheel-ai/promptwheel@<full commit sha>
+  with:
+    allow: ${{ github.event.pull_request.user.login == 'dependabot[bot]' && 'dependabot update, reviewed in this PR' || '' }}
+```
+
+Check the PR author, not `github.actor`, which is whoever last triggered the run. Everything else still fails without a person's reason.
+
+**What this does not catch.** A new destination reached through a module that already uses the network, when the address is assembled at runtime, reads as nothing new. The lock holds structure; it cannot follow a value.
+
+A reason clears these guards only through the `--allow` flag, never through a commit trailer: an agent can write a trailer, so a guard meant to stop a compromised agent cannot be cleared by one. The lock file itself is a mandate that a person's `--allow` can clear, so an agent cannot launder a change by updating the lock in the same diff.
+
+Each is a count, not a finding. The gate holds the number: a change that makes it rise fails,
+whatever else the change did right. The count does not have to be zero.
+
+## When the rise is the job
+
+Sometimes adding a dependency is exactly what was asked. Say so, and the gate records it:
+
+```bash
+promptwheel run --working --allow "needed for the CSV export (papaparse)"
+```
+
+or a `Promptwheel-Allow: <reason>` trailer on the commit. The seven metrics carry `allowable: true`,
+which means a declared reason clears their guarded regression for that one run, with the reason
+written into `report.allowed` and the outcome record. Nothing is loosened in the config, and a rise
+without a reason still fails. That is the point: every added package, script, or non-registry
+source leaves an audit line a reviewer can read.
+
+`gamingCheck` is `false` on all seven because these numbers legitimately live in config files
+(`package.json`, lockfiles), which the source-only re-run reverts; re-proving them from source would
+flag every honest dependency bump.
+
+## The mandates the preset writes
+
+A mandate is a path the agent must not touch in a change; the gate fails before any metric is read,
+and a mandate deleted or narrowed in the same change that violates it stays in force.
+
+| mandate | paths | why |
+| --- | --- | --- |
+| workflows-frozen | `.github/workflows/**` | workflows run with the repository's secrets |
+| registry-config-frozen | `.npmrc`, `.yarnrc`, `.yarnrc.yml` | where packages come from and where tokens go |
+| build-images-frozen | `Dockerfile*`, `docker-compose*` | what runs at build and deploy time |
+| publish-scripts-frozen | `scripts/release*`, `scripts/publish*` | the publish path is how a compromise spreads |
+| codeowners-frozen | `CODEOWNERS` | review ownership is set by people |
+| hooks-frozen | `.claude/settings.json`, `.claude/settings.local.json`, `.sawbuck/**` | the hooks that enforce the contract are wired by a person |
+
+The contract itself (`promptwheel.config.json`, `sawbuck.config.json`) is protected as an
+`evaluatorPaths` entry rather than a mandate: a change that edits it alongside a win is `GAMED` by
+declaration unless the change carries a declared reason, while a change that only edits the
+contract (a person retiring a rule) still passes. A mandate there would make the contract
+un-editable through the gate.
+
+A person who needs to change a frozen path does it in a separate change that only touches that
+path, reviewed as such.
+
+## What this is not
+
+- **Not a dependency firewall.** It does nothing about installing a package that is already
+  compromised on the registry. Use a registry policy, a cooldown on new versions, and
+  `--ignore-scripts` for that.
+- **Not an injection detector.** It does not decide whether an instruction came from you or from
+  content the agent read. Whatever steered the agent, a supply-chain edit it was steered into fails
+  here, deterministically.
+- **Not a scanner.** No matchers, no findings, no false positives to triage: a path, a count, or a
+  hash.
+
+Pair it with the `security` preset for the eight code-level invariants, and with the GitHub Action so
+the gate runs where the agent cannot switch it off.

package/packs/supply-chain/lock.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// PromptWheel architecture lock, zero-dep and zero-LLM. It reads a repository once and writes the shape
+// of it to promptwheel.lock.json: dependencies, install scripts, workflows, modules, import edges between
+// modules, routes, public entry points, and the network hosts the source names. The gate then holds that
+// shape: anything the lock has not seen is drift.
+//   node lock.mjs write [path]            write or refresh promptwheel.lock.json
+//   node lock.mjs drift [path] [--list] [--routes]   print how many structural items the tree has that the lock does not
+//   node lock.mjs pins [path]             print a fingerprint of the resolved dependency tree (the gate compares base to head)
+//                                         (routes are locked and listed, and counted only with --routes)
+// The lock lists structure, not content, so ordinary edits never touch it. There is no timestamp in it:
+// the same tree always writes the same bytes. JS and TS only for edges, routes and hosts today.
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, normalize } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const LOCK_FILE = 'promptwheel.lock.json';
+const SKIP = /(^|\/)(node_modules|\.git|dist|build|\.next|\.astro|coverage|vendor|out|target|\.venv|venv|__pycache__|\.promptwheel|\.sawbuck)(\/|$)/;
+const TESTISH = /(^|\/)(test|tests|__tests__|__mocks__|e2e|spec|fixtures?|examples?|docs?|bench)\/|\.(test|spec|stories)\.[^/]+$/;
+const CODE = /\.(mjs|cjs|js|jsx|ts|tsx|astro|svelte|vue)$/;
+const DEP_KEYS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+const LIFECYCLE = new Set(['preinstall', 'install', 'postinstall', 'prepare', 'prepublish', 'prepublishOnly', 'postpack']);
+const IMPORT = /(?:\bfrom\s+|\brequire\(\s*|\bimport\s*\(\s*|^\s*import\s+)['"](\.{1,2}\/[^'"]+|@\/[^'"]+)['"]/gm;
+const ROUTE_CALL = /\b(?:app|router|server|fastify)\.(get|post|put|patch|delete|all)\(\s*['"`](\/[^'"`]*)['"`]/g;
+const HOST = /\bhttps?:\/\/([a-z0-9][a-z0-9.-]*\.[a-z]{2,}|\d{1,3}(?:\.\d{1,3}){3})(?=[:/'"`\s)]|$)/gi;
+const NOT_A_HOST = /(^|\.)(example\.(com|org|net)|localhost|w3\.org|schema\.org|json-schema\.org|npmjs\.(com|org)|github\.com)$|^(127\.|0\.0\.0\.0)/i;
+// lockfiles are fingerprinted, binaries hashed: any change to either needs a reason, whatever the name
+const LOCKFILE = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lock)$/;
+const BINARY = /\.(node|wasm)$/;
+const sha = (t) => createHash('sha256').update(t).digest('hex').slice(0, 16);
+// the resolved tree a lockfile pins, not its bytes: an npm lock repeats the project's own version, so a
+// release would otherwise read as a dependency change. Every package, its version, source and hash stay in.
+function resolvedTree(path, text) {
+  if (!/(package-lock|npm-shrinkwrap)\.json$/.test(path)) return text;
+  let j; try { j = JSON.parse(text); } catch { return text; }
+  const rows = [];
+  for (const [k, v] of Object.entries(j.packages || {})) if (k && v && !v.link) rows.push([k, v.version, v.resolved, v.integrity].join(' '));
+  const walk = (deps, pre) => { for (const [k, v] of Object.entries(deps || {})) { rows.push([pre + k, v.version, v.resolved, v.integrity].join(' ')); walk(v.dependencies, pre + k + '/'); } };
+  if (!j.packages) walk(j.dependencies, '');
+  return rows.sort().join('\n');
+}
+// what a module is able to do. First use in a module is structural; this is what catches an IP literal or a
+// host assembled at runtime, which no URL pattern can see.
+const CAPS = [
+  ['exec', /\b(?:from\s+|require\(\s*|import\s*\(\s*)['"](?:node:)?(?:child_process|worker_threads|vm)['"]/],
+  ['eval', /(?:^|[^.\w])eval\s*\(|\bnew\s+Function\s*\(/],
+  ['net', /\bfetch\s*\(|\bXMLHttpRequest\b|\bWebSocket\s*\(|\b(?:from\s+|require\(\s*|import\s*\(\s*)['"](?:node:)?(?:net|dgram|http|https|tls|http2|dns)['"]/],
+];
+
+// the top-level module a path belongs to: packages/x, apps/x, src/x, lib/x, or the first directory
+export function moduleOf(path) {
+  const p = path.split('/');
+  for (const pre of [['src', 'lib'], ['apps'], ['packages'], ['src'], ['lib']])
+    if (p.length > pre.length + 1 && pre.every((s, i) => p[i] === s)) return p.slice(0, pre.length + 1).join('/');   // src/app stays one module: a new page is a route, not a new module
+  return p.length > 1 ? p[0] : '.';
+}
+function routeOf(path) {
+  let m = path.match(/(?:^|\/)app\/(.*)\/(?:route|page)\.[jt]sx?$/);
+  if (m) return '/' + m[1].split('/').filter((s) => !/^\(.*\)$/.test(s)).join('/');
+  if (/(?:^|\/)app\/(?:route|page)\.[jt]sx?$/.test(path)) return '/';
+  m = path.match(/(?:^|\/)pages\/(.+)\.(?:astro|mdx?|[jt]sx?)$/);
+  if (m && !/\/_|^_/.test(m[1])) return '/' + m[1].replace(/(^|\/)index$/, '');
+  return null;
+}
+// every structural item one file contributes; pure, so a replay over history uses the same code
+export function itemsOf(path, text) {
+  const out = new Set();
+  if (SKIP.test(path)) return out;
+  if (path.startsWith('.github/workflows/')) { out.add(`workflow:${path}`); return out; }
+  if (BINARY.test(path)) { out.add(`binary:${path}:${sha(text)}`); return out; }
+  if (path === 'package.json' || path.endsWith('/package.json')) {
+    let j; try { j = JSON.parse(text); } catch { return out; }
+    for (const k of DEP_KEYS) for (const n of Object.keys(j[k] || {})) out.add(`dep:${n}`);
+    for (const [s, v] of Object.entries(j.scripts || {})) { if (LIFECYCLE.has(s)) out.add(`script:${path}:${s}`); out.add(`scripthash:${path}:${s}:${sha(String(v))}`); }
+    if (path === 'package.json') {
+      if (typeof j.bin === 'string') out.add(`entry:bin:${j.name}`); else for (const b of Object.keys(j.bin || {})) out.add(`entry:bin:${b}`);
+      if (j.exports && typeof j.exports === 'object') for (const e of Object.keys(j.exports)) if (e.startsWith('.')) out.add(`entry:export:${e}`);
+    }
+    return out;
+  }
+  if (!CODE.test(path)) return out;
+  const route = routeOf(path);
+  if (route) out.add(`route:${route}`);
+  if (TESTISH.test(path)) return out;
+  const from = moduleOf(path);
+  out.add(`module:${from}`);
+  for (const m of text.matchAll(IMPORT)) {
+    const t = m[1];
+    const to = normalize(t.startsWith('@/') ? 'src/' + t.slice(2) : join(dirname(path), t));
+    if (to.startsWith('..')) continue;
+    const dest = moduleOf(to);
+    if (dest !== from) out.add(`edge:${from}>${dest}`);
+  }
+  for (const m of text.matchAll(ROUTE_CALL)) out.add(`route:${m[1].toUpperCase()} ${m[2]}`);
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) continue;
+    for (const m of t.matchAll(HOST)) if (!NOT_A_HOST.test(m[1])) out.add(`host:${m[1].toLowerCase()}`);
+    for (const [cap, re] of CAPS) if (re.test(t)) out.add(`cap:${from}:${cap}`);
+  }
+  return out;
+}
+function tracked(root) {
+  try { return execFileSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }).split('\0').filter(Boolean); }
+  catch { return []; }
+}
+export function shapeOf(root) {
+  const all = new Set();
+  for (const f of tracked(root)) {
+    if (f === LOCK_FILE) continue;
+    let text = '';
+    const held = LOCKFILE.test(f) || BINARY.test(f);   // never skipped for size: a large lockfile is the one that matters
+    try { if (!held && statSync(join(root, f)).size > 2_000_000) continue; text = readFileSync(join(root, f), held && BINARY.test(f) ? 'latin1' : 'utf8'); } catch { continue; }
+    for (const i of itemsOf(f, text)) all.add(i);
+  }
+  return [...all].sort();
+}
+export function writeLock(root) {
+  const items = shapeOf(root);
+  writeFileSync(join(root, LOCK_FILE), JSON.stringify({ version: 1, items }, null, 2) + '\n');
+  return items.length;
+}
+// a number that changes whenever the resolved dependency tree does. Compared base to head by the gate, so it
+// needs no stored value: the lock stays the same across updates, and an approved update never blinds the next check.
+export function pinsOf(root) {
+  const rows = [];
+  for (const f of tracked(root).filter((p) => LOCKFILE.test(p) && !SKIP.test(p)).sort()) {
+    try { rows.push(f + '\n' + resolvedTree(f, readFileSync(join(root, f), 'utf8'))); } catch { /* deleted but still in the index */ }
+  }
+  return rows.length ? parseInt(sha(rows.join('\n')).slice(0, 12), 16) : 0;
+}
+export function driftOf(root) {
+  const p = join(root, LOCK_FILE);
+  if (!existsSync(p)) return null;
+  let lock; try { lock = JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+  if (!lock || !Array.isArray(lock.items)) return null;
+  const known = new Set(lock.items);
+  return shapeOf(root).filter((i) => !known.has(i));
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  const root = args[1] || '.';
+  if (args[0] === 'write') { process.stdout.write(`${writeLock(root)} items locked in ${LOCK_FILE}\n`); }
+  else if (args[0] === 'drift') {
+    const all = driftOf(root);
+    // a new route is ordinary feature work, so by default it is reported, not held; --routes holds it too
+    const d = all && all.filter((i) => process.argv.includes('--routes') || !i.startsWith('route:'));
+    if (d === null) { process.stderr.write(`no readable ${LOCK_FILE}: run promptwheel lock\n`); process.exit(1); }   // unmeasurable, never a clean 0
+    if (process.argv.includes('--list')) for (const i of all) process.stderr.write(`  ${i}\n`);
+    process.stdout.write(process.argv.includes('--json') ? JSON.stringify(d) + '\n' : `${d.length}\n`);
+  } else if (args[0] === 'pins') { process.stdout.write(`${pinsOf(root)}\n`);
+  } else { process.stderr.write('usage: node lock.mjs <write|drift|pins> [path] [--list] [--json]\n'); process.exit(64); }
+}

package/packs/supply-chain/pack.json

@@ -0,0 +1,76 @@
+{
+  "$comment": "PromptWheel supply-chain guard-pack. Use via { \"extends\": [\"packs/supply-chain/pack.json\"] } in your promptwheel.config.json, or install it with `promptwheel init --preset supply-chain` (which also writes the mandates). Three counts the gate holds: a rise fails the gate unless the change carries a declared reason (`--allow \"<reason>\"` or a `Promptwheel-Allow:` trailer), which is recorded in the outcome record. gamingCheck is false because these numbers legitimately live in config files (package.json, lockfiles), which the source-only re-run reverts.",
+  "metrics": [
+    {
+      "$comment": "install-time script entries (preinstall, install, postinstall, prepare, prepublish, prepublishOnly, postpack) across every package.json: the step a supply-chain attack needs inside your repo",
+      "name": "lifecycle_scripts",
+      "cmd": "node packs/supply-chain/scan.mjs lifecycle .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "dependency entries across every package.json: a new package needs a recorded reason, so every addition leaves an audit line",
+      "name": "dependency_entries",
+      "cmd": "node packs/supply-chain/scan.mjs deps .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "lockfile entries resolved from outside the npm registry (git, ssh, http, another host's tarball, file:) plus registry entries with no integrity hash: where a package really comes from",
+      "name": "lock_nonregistry_sources",
+      "cmd": "node packs/supply-chain/scan.mjs lock-sources .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "code run from a floating reference: an action not pinned by SHA, npx or dlx with no exact version, a global install with no exact version, a remote script piped to a shell. Must not rise.",
+      "name": "unpinned_execution",
+      "cmd": "node packs/supply-chain/scan.mjs unpinned .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "install protections missing at the repo root: install scripts not disabled, no release-age cooldown. Must not rise.",
+      "name": "install_policy_gaps",
+      "cmd": "node packs/supply-chain/scan.mjs policy .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "structural items the tree has that promptwheel.lock.json does not. Must not rise.",
+      "name": "lock_drift",
+      "cmd": "node packs/supply-chain/lock.mjs drift .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag"
+    },
+    {
+      "$comment": "a fingerprint of the resolved dependency tree, compared base to head: a new version under an old name is how a worm arrives. Any change needs a reason.",
+      "name": "pins_changed",
+      "cmd": "node packs/supply-chain/lock.mjs pins .",
+      "extract": "number",
+      "direction": "down",
+      "guard": true,
+      "gamingCheck": false,
+      "allowable": "flag",
+      "exact": true
+    }
+  ]
+}

package/packs/supply-chain/scan.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// PromptWheel supply-chain guard-pack scanner, zero-dep. Counters over the repo's package
+// manifests and lockfiles; each is a number the gate holds (it must not rise):
+//   lifecycle     install-time script entries across every package.json
+//                 (preinstall, install, postinstall, prepare, prepublish, prepublishOnly, postpack)
+//   deps          dependency entries across every package.json
+//                 (dependencies, devDependencies, optionalDependencies, peerDependencies)
+//   lock-sources  lockfile entries resolved from somewhere other than the npm registry (git, ssh,
+//                 http, a tarball on another host, file:) plus registry entries with no integrity hash
+// These are counts, not findings. A private registry makes the baseline large, not failing: the
+// guard only fails when a count rises, and a rise with a reason is recorded with `--allow`.
+//
+// Usage: node scan.mjs <lifecycle|deps|lock-sources> [path]        prints one integer
+//        node scan.mjs <what> [path] --list                          also lists each hit on stderr
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+const positional = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+const WHAT = positional[0] || '';
+const ROOT = positional[1] || '.';
+const LIST = process.argv.includes('--list');
+
+const SKIP = /(^|\/)(node_modules|\.git|dist|build|\.next|coverage|vendor|out|target|\.venv|venv|__pycache__)(\/|$)/;
+const LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare', 'prepublish', 'prepublishOnly', 'postpack'];
+const DEP_KEYS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+const REGISTRY = /^https:\/\/(registry\.npmjs\.org|registry\.yarnpkg\.com)\//;
+
+const hits = [];
+const hit = (where, what) => hits.push(`${where}: ${what}`);
+
+function* walk(dir, names) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const e of entries) {
+    const p = join(dir, e);
+    if (SKIP.test(p)) continue;
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (st.isDirectory()) yield* walk(p, names);
+    else if (names.has(basename(p))) yield p;
+  }
+}
+function readJson(p) { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } }
+function readText(p) { try { return readFileSync(p, 'utf8'); } catch { return ''; } }
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+// --- lifecycle: install-time script entries ---------------------------------------------------
+function lifecycle() {
+  for (const file of walk(ROOT, new Set(['package.json']))) {
+    const pkg = readJson(file);
+    if (!isObj(pkg) || !isObj(pkg.scripts)) continue;
+    for (const k of LIFECYCLE) if (typeof pkg.scripts[k] === 'string' && pkg.scripts[k].trim()) hit(file, `${k} = ${pkg.scripts[k].slice(0, 120)}`);   // an empty script runs nothing
+  }
+}
+
+// --- deps: dependency entries -------------------------------------------------------------------
+function deps() {
+  for (const file of walk(ROOT, new Set(['package.json']))) {
+    const pkg = readJson(file);
+    if (!isObj(pkg)) continue;
+    for (const k of DEP_KEYS) if (isObj(pkg[k])) for (const name of Object.keys(pkg[k])) hit(file, `${k}: ${name}`);
+  }
+}
+
+// --- lock-sources: where lockfile entries come from ---------------------------------------------
+// npm: lockfileVersion 2/3 carry a `packages` map; 1 carries nested `dependencies`. A workspace
+// link (`link: true`) is a path inside the repo, not a source. Bundled entries carry no `resolved`
+// and are skipped. Any entry with a `resolved` that is not the registry counts once; a registry
+// entry with no `integrity` counts once.
+function npmLock(file) {
+  const lock = readJson(file);
+  if (!isObj(lock)) return;
+  const judge = (entry, label) => {
+    if (!isObj(entry) || entry.link === true) return;
+    const r = entry.resolved;
+    if (typeof r !== 'string' || !r) return;
+    if (!REGISTRY.test(r)) hit(`${file} ${label}`, r.slice(0, 160));
+    else if (typeof entry.integrity !== 'string' || !entry.integrity) hit(`${file} ${label}`, 'no integrity');
+  };
+  if (isObj(lock.packages)) {
+    for (const [k, v] of Object.entries(lock.packages)) { if (k === '') continue; judge(v, k); }
+  } else if (isObj(lock.dependencies)) {
+    const rec = (d, prefix) => { for (const [k, v] of Object.entries(d)) { judge(v, prefix + k); if (isObj(v) && isObj(v.dependencies)) rec(v.dependencies, prefix + k + '>'); } };
+    rec(lock.dependencies, '');
+  }
+}
+// pnpm: a tolerant line scan of `resolution:` lines (no YAML parser). A registry resolution is
+// `{integrity: ...}`; a tarball on another host, a git commit, or a tarball with no integrity counts.
+// `directory:` resolutions are links inside the repo. Lines of a shape this scanner does not know
+// count nothing.
+function pnpmLock(file) {
+  const text = readText(file);
+  if (!text) return;
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*resolution:\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const rest = m[1];
+    const tb = /\btarball:\s*['"]?([^'",}\s]+)/.exec(rest);
+    if (tb) {
+      if (!REGISTRY.test(tb[1])) hit(`${file}:${i + 1}`, tb[1].slice(0, 160));
+      else if (!/\bintegrity:/.test(rest)) hit(`${file}:${i + 1}`, 'no integrity');
+    } else if (/\b(commit|repo):/.test(rest) || /\btype:\s*git\b/.test(rest)) {
+      hit(`${file}:${i + 1}`, rest.slice(0, 160));
+    }
+  }
+}
+// yarn classic: blank-line separated blocks with `resolved "<url>#<hash>"` and an `integrity` line;
+// a non-registry host counts, a registry entry with no integrity counts. yarn berry (`__metadata:`):
+// `resolution: "<name>@<protocol>:..."`; anything but npm:, workspace:, patch:, link:, portal:
+// (a git url, an https tarball, file:, exec:) counts. Berry always writes a checksum for npm
+// resolutions, so no integrity check is applied there.
+function yarnLock(file) {
+  const text = readText(file);
+  if (!text) return;
+  if (/^__metadata:/m.test(text)) {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const m = /^\s*resolution:\s*"?([^"]+)"?\s*$/.exec(lines[i]);
+      if (!m) continue;
+      const res = m[1];
+      const at = res.startsWith('@') ? res.indexOf('@', 1) : res.indexOf('@');
+      if (at < 0) continue;
+      const desc = res.slice(at + 1);
+      const proto = (/^([a-z][a-z0-9+]*):/i.exec(desc) || [])[1];
+      if (proto && ['npm', 'workspace', 'patch', 'link', 'portal'].includes(proto.toLowerCase())) continue;
+      if (REGISTRY.test(desc)) continue;
+      hit(`${file}:${i + 1}`, res.slice(0, 160));
+    }
+    return;
+  }
+  for (const block of text.split(/\n\s*\n/)) {
+    const r = /^\s*resolved\s+"?([^"\s]+)"?/m.exec(block);
+    if (!r) continue;
+    const url = r[1].replace(/#.*$/, '');
+    const label = (block.split('\n').find((l) => l.trim() && !l.startsWith('#')) || '').trim().slice(0, 80);
+    if (!REGISTRY.test(url)) hit(`${file} ${label}`, url.slice(0, 160));
+    else if (!/^\s*integrity\s/m.test(block)) hit(`${file} ${label}`, 'no integrity');
+  }
+}
+function lockSources() {
+  for (const file of walk(ROOT, new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']))) {
+    const name = basename(file);
+    try {
+      if (name === 'package-lock.json') npmLock(file);
+      else if (name === 'pnpm-lock.yaml') pnpmLock(file);
+      else yarnLock(file);
+    } catch { /* an unknown shape counts nothing, it never throws */ }
+  }
+}
+
+// --- unpinned: code that runs from a floating reference ----------------------------------------
+// The step a worm needs is a reference that moves. Counted wherever a repo executes something it
+// did not pin: a GitHub Action not pinned to a full commit SHA, npx/dlx with no exact version, a
+// global install with no exact version, and a remote script piped into a shell. Local actions
+// (./path) are not counted, and in package.json scripts neither is a tool the manifest declares,
+// because the lockfile already pins that one.
+const EXACT = /@\d+\.\d+\.\d+([-+][\w.-]+)?$/;
+const pkgToken = (t) => t.replace(/^['"]|['"]$/g, '');
+function execLines(text, where, declared) {
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith('//')) continue;
+    const u = line.match(/^(?:-\s*)?uses:\s*['"]?([^'"\s#]+)/);
+    if (u) {
+      const ref = u[1];
+      if (ref.startsWith('./') || ref.startsWith('../')) continue;
+      if (ref.startsWith('docker://') ? !/@sha256:[0-9a-f]{64}$/.test(ref) : !/@[0-9a-f]{40}$/.test(ref)) hit(where, `action not pinned by SHA: ${ref}`);
+      continue;
+    }
+    for (const m of line.matchAll(/\b(?:npx|bunx|pnpx|pnpm\s+dlx|yarn\s+dlx)\s+((?:-{1,2}[\w-]+\s+)*)([^\s;&|)]+)/g)) {
+      const t = pkgToken(m[2]);
+      if (t.startsWith('-') || t.startsWith('$') || t.startsWith('.') || t.startsWith('/')) continue;
+      const name = t.replace(/@[^@/]*$/, '') || t;
+      if (declared && (declared.has(name) || declared.has(t))) continue;
+      if (!EXACT.test(t)) hit(where, `no exact version: ${m[0].trim()}`);
+    }
+    for (const m of line.matchAll(/\bnpm\s+(?:i|install)\s+(?:-g|--global)\s+((?:[^\s;&|)]+\s*)+)/g)) {
+      for (const t of m[1].trim().split(/\s+/).map(pkgToken)) if (t && !t.startsWith('-') && !t.startsWith('.') && !EXACT.test(t)) hit(where, `no exact version: npm install -g ${t}`);
+    }
+    if (/\b(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(ba|z|da)?sh\b/.test(line)) hit(where, `remote script piped to a shell: ${line.slice(0, 80)}`);
+  }
+}
+function unpinned() {
+  const yml = /\.ya?ml$/;
+  for (const dir of [join(ROOT, '.github', 'workflows')]) {
+    let names = []; try { names = readdirSync(dir); } catch { /* no workflows */ }
+    for (const n of names) if (yml.test(n)) execLines(readText(join(dir, n)), join(dir, n));
+  }
+  for (const f of walk(ROOT, new Set(['action.yml', 'action.yaml']))) execLines(readText(f), f);
+  for (const f of walk(ROOT, new Set(['package.json']))) {
+    const j = readJson(f); if (!isObj(j) || !isObj(j.scripts)) continue;
+    const declared = new Set(DEP_KEYS.flatMap((k) => (isObj(j[k]) ? Object.keys(j[k]) : [])));
+    for (const [k, v] of Object.entries(j.scripts)) if (typeof v === 'string') execLines(v, `${f} scripts.${k}`, declared);
+  }
+  for (const n of (() => { try { return readdirSync(join(ROOT, 'scripts')); } catch { return []; } })()) if (n.endsWith('.sh')) execLines(readText(join(ROOT, 'scripts', n)), join(ROOT, 'scripts', n));
+  for (const n of (() => { try { return readdirSync(ROOT); } catch { return []; } })()) if (/^Dockerfile/.test(n)) execLines(readText(join(ROOT, n)), join(ROOT, n));
+}
+
+// --- policy: install protections the repo declares ----------------------------------------------
+// Two gaps, counted at the repo root. Release age itself stays with the package manager: a registry
+// lookup here would make the verdict depend on the clock.
+function policy() {
+  if (!readJson(join(ROOT, 'package.json'))) return;
+  const text = ['.npmrc', 'pnpm-workspace.yaml', '.yarnrc.yml'].map((f) => readText(join(ROOT, f))).join('\n');
+  if (!/^\s*ignore-scripts\s*=\s*true/m.test(text) && !/^\s*(strictDepBuilds|enableScripts)\s*:\s*(true|false)/m.test(text)) hit('.npmrc', 'install scripts are not disabled (ignore-scripts=true)');
+  if (!/^\s*min-release-age\s*=\s*[1-9]/m.test(text) && !/^\s*minimumReleaseAge\s*:\s*[1-9]/m.test(text) && !/^\s*npmMinimalAgeGate\s*:\s*[1-9"']/m.test(text)) hit('.npmrc', 'no release-age cooldown (min-release-age)');
+}
+
+const COUNTERS = { lifecycle, deps, 'lock-sources': lockSources, unpinned, policy };
+if (!COUNTERS[WHAT]) {
+  process.stderr.write('usage: node scan.mjs <lifecycle|deps|lock-sources|unpinned|policy> [path] [--list]\n');
+  process.exit(64);   // a typo in the config must read as unmeasurable, never as a clean 0
+}
+COUNTERS[WHAT]();
+if (LIST) {
+  for (const h of hits) process.stderr.write(`  ${h}\n`);
+  process.stderr.write(`\n${hits.length} ${WHAT} entr${hits.length === 1 ? 'y' : 'ies'}\n`);
+}
+// the metric value: lower is better; the gate holds the count, it does not require 0
+process.stdout.write(String(hits.length) + '\n');