promptwheel 0.7.16 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptwheel",
-  "version": "0.7.16",
+  "version": "0.8.1",
   "description": "A deterministic, zero-LLM check for your coding loop. A win must survive a re-run from the agent's source edits alone, so a test that went green by editing the test reads GAMED. Runs in CI or a Claude Code plugin.",
   "type": "module",
   "bin": {

package/packs/supply-chain/README.md

@@ -27,7 +27,7 @@ clean git worktrees, so a pack that is not in git is absent at both refs and the
   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.
+- **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 locked but not counted by default (`node .promptwheel/packs/supply-chain/lock.mjs drift . --list` shows it). To hold new routes too, add `--routes` to the end of the `lock_drift` metric's `cmd` in `promptwheel.config.json`, so it reads `node .promptwheel/packs/supply-chain/lock.mjs drift . --routes`. The flag belongs to that script: `promptwheel lock` takes no flags and always writes routes into the lock. The config is a frozen path here, so that edit passes with `promptwheel run --allow "<reason>"`. 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%, dependency changes; use the CI path below for those.
 
 **On a pull request.** Someone with write access comments `sawbuck-allow: <reason>` and re-runs the check. `sawbuck contract` marks everyday guards `report: true`, so they note a change without failing until you tighten them; this preset on its own holds them all.
@@ -57,10 +57,10 @@ Sometimes adding a dependency is exactly what was asked. Say so, and the gate re
 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
+A commit trailer does not count here. The seven metrics carry `allowable: "flag"`, which means a
+reason from the `--allow` flag clears their guarded regression for that one run, with the reason
+written into `report.allowed`. 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
@@ -69,8 +69,8 @@ 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.
+A mandate is a path the agent must not touch in a change. Touching one fails the gate whatever the
+metrics say, and a mandate deleted or narrowed in the same change that violates it stays in force.
 
 | mandate | paths | why |
 | --- | --- | --- |
@@ -79,15 +79,20 @@ and a mandate deleted or narrowed in the same change that violates it stays in f
 | 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 |
+| scanner-frozen | `.promptwheel/packs/**` | the scanners are not edited by the change they read |
 | contract-frozen | `promptwheel.config.json`, `sawbuck.config.json` | the contract changes with a reason from a person (`--allow`) |
-| hooks-frozen | `.claude/settings.json`, `.claude/settings.local.json`, `.sawbuck/**` | the hooks that enforce the contract are wired by a person |
+| lock-frozen | `promptwheel.lock.json` | the lock changes with a reason from a person (`--allow`) |
+| hooks-frozen | `.claude/settings.json`, `.claude/settings.local.json`, `.sawbuck/**` | the hooks change with a reason from a person (`--allow`) |
 
 The contract itself (`promptwheel.config.json`, `sawbuck.config.json`) is frozen too, and it is also an
 `evaluatorPaths` entry. A change to it needs `--allow "<reason>"` from a person. Without that, a change that
 only weakens a rule would pass, and the next change would be judged by the weakened contract.
 
-A person who needs to change a frozen path does it in a separate change that only touches that
-path, reviewed as such.
+`--allow` clears only three of these: `contract-frozen`, `lock-frozen` and `hooks-frozen` (so a team can commit
+shared hooks to a repo that already has its rules). A commit trailer clears none. Every other frozen path stays
+frozen, even with `--allow`. To change one, a person first retires its mandate in a change of its own
+(it edits the contract, so it needs `--allow`), then makes the change, then puts the mandate back the
+same way.
 
 ## What this is not
 
@@ -100,5 +105,4 @@ path, reviewed as such.
 - **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.
+Pair it with the GitHub Action so the gate runs where the agent cannot switch it off.

package/packs/supply-chain/pack.json

@@ -1,5 +1,5 @@
 {
-  "$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.",
+  "$comment": "PromptWheel supply-chain guard-pack. Install it with `promptwheel init --preset supply-chain`: that copies the pack to .promptwheel/packs/supply-chain/, writes these metrics into promptwheel.config.json with their commands pointed at the copy, and writes the mandates. The commands in this file run packs/supply-chain/..., which exists only in the PromptWheel repository itself, so `extends` on this file (here or on the copy under .promptwheel/packs/) reads every metric as unmeasurable, and the gate fails, in any other repository. Seven counts the gate holds: a rise fails the gate unless a person gives a reason with `--allow \"<reason>\"` (a commit trailer does not count), which is recorded in report.allowed. 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",

package/packs/security/README.md

@@ -1,62 +0,0 @@
-# PromptWheel security guard-pack
-
-Gate your AI coding loop on **security invariants**, not just tests. When an agent
-writes backend code, "tests pass" says nothing about whether it shipped a CORS
-wildcard, a client-controlled payment amount, or a hardcoded secret. This pack
-adds a `security_findings` metric that must not climb - and because it's a
-PromptWheel metric, the win has to survive `--detect-gaming`: an agent can't
-lower the count by editing the pattern file or a config, only by fixing the code.
-
-## Use it
-
-The pack ships inside the `promptwheel` package, not in your repo, so install it with the
-preset:
-
-```bash
-promptwheel init --preset security            # or --preset security-antihack, which adds the tripwires
-```
-
-`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`.
-
-## What it checks (v0.1 - 8 high-precision invariants)
-
-Decanted from [securitychecks](https://securitychecks.ai)' "recommended" tier - 
-the regex-portable subset, chosen for near-zero false positives:
-
-| Invariant | Severity |
-| --- | --- |
-| CORS wildcard origin | P0 |
-| CORS origin reflection | P0 |
-| Insecure session cookie (`secure:false`) | P0 |
-| Payment amount from client input | P0 |
-| Hardcoded secret in a sensitive variable | P0 |
-| NPM token committed in `.npmrc` | P0 |
-| Template autoescape disabled (XSS) | P0 |
-| S3 presigned upload without content validation | P2 |
-
-Each pattern ships with its own false-positive guards (the `exclude` regexes).
-
-## Scope, honestly
-
-This is the **regex-portable** slice. The other ~75 recommended invariants
-(auth-enforcement, authz-revocation, tenant-isolation, dataflow-tainted sinks)
-need an AST + dataflow engine and are a possible follow-up, not part of this
-pack. The point of v0.1 is the architecture: security invariants are
-now a first-class, un-gameable PromptWheel metric. Zero dependencies; the scanner
-is one file (`scan.mjs`).

package/packs/security/pack.json

@@ -1,12 +0,0 @@
-{
-  "$comment": "PromptWheel security guard-pack. Decanted from securitychecks (recommended tier). Use via { \"extends\": [\"packs/security/pack.json\"] } in your promptwheel.config.json. Gates on the count of security-invariant violations (direction: down = lower is better; guard: true = fail if it climbs). Because it's a promptwheel metric, the win must survive --detect-gaming: an agent can't lower the count by editing the pattern file or a config, only by fixing the code.",
-  "metrics": [
-    {
-      "name": "security_findings",
-      "cmd": "node packs/security/scan.mjs .",
-      "extract": "number",
-      "direction": "down",
-      "guard": true
-    }
-  ]
-}

package/packs/security/patterns.json

@@ -1,209 +0,0 @@
-{
-  "pack": "security",
-  "version": "0.1.0",
-  "source": "securitychecks recommended tier (regex-portable subset)",
-  "patterns": [
-    {
-      "id": "DATAFLOW.UNTRUSTED.XSS",
-      "name": "Template Engine Autoescape Disabled",
-      "severity": "P0",
-      "match": "autoescape\\s*:\\s*false",
-      "exclude": [],
-      "message": "Template engine autoescape disabled \u2014 enables stored XSS attacks",
-      "fix": "Enable autoescape or sanitize all user input before rendering",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**",
-        "!**/www/**",
-        "!**/docs/**",
-        "!**/documentation/**"
-      ]
-    },
-    {
-      "id": "SESSION.INSECURE_COOKIE",
-      "name": "Insecure Session Cookie",
-      "severity": "P0",
-      "match": "secure\\s*:\\s*false",
-      "exclude": [],
-      "message": "Session cookies must have secure and httpOnly flags",
-      "fix": "Verify this is not a false positive",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "**/*.tsx",
-        "**/*.jsx",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**",
-        "!**/e2e/**",
-        "!**/playwright/**",
-        "!**/cypress/**",
-        "!**/test-utils/**",
-        "!**/*.e2e.*",
-        "!**/e2e-*/**"
-      ]
-    },
-    {
-      "id": "AUTHZ.CORS_WILDCARD",
-      "name": "CORS Wildcard Origin",
-      "severity": "P0",
-      "match": "Access-Control-Allow-Origin.*\\*|origin\\s*:\\s*\\*|origin:\\s*true",
-      "exclude": [
-        "!credentials"
-      ],
-      "message": "Wildcard origin with credentials exposes user data",
-      "fix": "Verify this is not a false positive",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "**/*.tsx",
-        "**/*.jsx",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**",
-        "!**/*.tsx",
-        "!**/*.jsx",
-        "!**/components/**"
-      ]
-    },
-    {
-      "id": "AUTHZ.CORS_REFLECT",
-      "name": "CORS Origin Reflection",
-      "severity": "P0",
-      "match": "(?:Access-Control-Allow-Origin|res\\.(?:set|setHeader|header)\\(['\"]Access-Control).*(?:req\\.headers\\.origin|headers\\.get\\(['\"]origin['\"]\\))",
-      "exclude": [],
-      "message": "Reflecting origin is equivalent to wildcard \u2014 validate against allowlist",
-      "fix": "Verify this is not a false positive",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "**/*.tsx",
-        "**/*.jsx",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**"
-      ]
-    },
-    {
-      "id": "PAY.CLIENT_AMOUNT",
-      "name": "Payment Amount From Client",
-      "severity": "P0",
-      "match": "amount.*req\\.body|price.*req\\.body|total.*body\\.amount",
-      "exclude": [
-        "server|database|catalog"
-      ],
-      "message": "Calculate payment amounts server-side, not from client input",
-      "fix": "Verify this is not a false positive",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "**/*.tsx",
-        "**/*.jsx",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**"
-      ]
-    },
-    {
-      "id": "CONFIG.NPMRC_TOKEN",
-      "name": "NPM Token in .npmrc",
-      "severity": "P0",
-      "match": "_authToken=|//registry.*:_auth",
-      "exclude": [
-        "\\$\\{NPM_TOKEN\\}|process\\.env"
-      ],
-      "message": "NPM tokens should come from environment variables",
-      "fix": "Verify this is not a false positive",
-      "files": [
-        "**/*",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**"
-      ]
-    },
-    {
-      "id": "VALID.UPLOAD_NOCHECK",
-      "name": "S3 Presigned Upload Without Content Validation",
-      "severity": "P2",
-      "match": "(?:createPresignedPost|getSignedUrl|PutObjectCommand)\\s*\\(",
-      "exclude": [
-        "ContentType|content-type|Content-Length|content-length|Conditions|conditions",
-        "allowedTypes|fileFilter|mimetype|maxSize|maxFileSize",
-        "@example|Example:|```|description:|guidance",
-        "GetObjectCommand|getObject|HeadObjectCommand|DeleteObjectCommand|download|Download|read|Read",
-        "generateSignedUrl.*get|getSignedUrl.*getObject"
-      ],
-      "message": "S3 presigned upload URL has no content type or size conditions \u2014 any file type/size can be uploaded",
-      "fix": "Add Conditions to presigned POST or ContentType/ContentLength constraints",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "!**/*.tsx",
-        "!**/*.jsx",
-        "!**/components/**",
-        "!**/frontend/**",
-        "!**/public/**",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**"
-      ]
-    },
-    {
-      "id": "SECRETS.HARDCODED",
-      "name": "Hardcoded Secret in Sensitive Variable",
-      "severity": "P0",
-      "match": "(?:const|let|var)\\s+(?:[A-Z_]*(?:SECRET|JWT_SECRET|API_KEY|AUTH_TOKEN|PRIVATE_KEY|SIGNING_KEY|ENCRYPTION_KEY)[A-Z_]*)\\s*=\\s*['\"][^'\"]{8,}['\"]",
-      "exclude": [
-        "process\\.env|import\\.meta\\.env|getenv|\\$\\{|placeholder|changeme|YOUR_|TODO|FIXME|example|EXAMPLE"
-      ],
-      "message": "Secret value hardcoded in source code \u2014 use environment variables",
-      "fix": "Verify this is not a placeholder or example value",
-      "files": [
-        "**/*.ts",
-        "**/*.js",
-        "!**/__tests__/**",
-        "!**/*.test.*",
-        "!**/*.spec.*",
-        "!**/test/**",
-        "!**/tests/**",
-        "!**/__mocks__/**",
-        "!**/fixtures/**",
-        "!**/sample/**",
-        "!**/samples/**",
-        "!**/example/**",
-        "!**/examples/**"
-      ]
-    }
-  ]
-}

package/packs/security/scan.mjs

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-// PromptWheel security guard-pack scanner — zero-dep.
-// Decanted from securitychecks' "recommended" tier (the regex-portable subset).
-// Emits the count of security-invariant violations to stdout (the metric value).
-// The full AST+dataflow engine (the other 75 recommended patterns) is the follow-up.
-//
-// Usage: node scan.mjs [path]            → prints the finding count (for `promptwheel` metrics)
-//        node scan.mjs [path] --list     → prints each finding (file:line · id · message)
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, extname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = process.argv[2] && !process.argv[2].startsWith('--') ? process.argv[2] : '.';
-const LIST = process.argv.includes('--list');
-const PACK = JSON.parse(readFileSync(join(fileURLToPath(new URL('.', import.meta.url)), 'patterns.json'), 'utf8'));
-
-const SKIP = /(^|\/)(node_modules|\.git|dist|build|\.next|coverage|vendor)(\/|$)/;
-const CODE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
-const CONFIG_FILES = /(^|\/)\.npmrc$/;
-
-function* walk(dir) {
-  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);
-    else if (CODE.has(extname(p)) || CONFIG_FILES.test(p)) yield p;
-  }
-}
-
-const findings = [];
-for (const file of walk(ROOT)) {
-  let text;
-  try { text = readFileSync(file, 'utf8'); } catch { continue; }
-  const lines = text.split('\n');
-  for (const pat of PACK.patterns) {
-    let re;
-    try { re = new RegExp(pat.match, 'i'); } catch { continue; }
-    const excludes = (pat.exclude || []).map((x) => { try { return new RegExp(x, 'i'); } catch { return null; } }).filter(Boolean);
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (!re.test(line)) continue;
-      if (excludes.some((ex) => ex.test(line))) continue;       // pattern's own false-positive guards
-      findings.push({ file, line: i + 1, id: pat.id, sev: pat.severity, msg: pat.message });
-    }
-  }
-}
-
-if (LIST) {
-  for (const f of findings) console.error(`  [${f.sev}] ${f.file}:${f.line} · ${f.id} · ${f.msg}`);
-  console.error(`\n${findings.length} security-invariant violation(s)`);
-}
-// the metric value: lower is better, 0 is clean
-process.stdout.write(String(findings.length) + '\n');