fini-proof 0.3.0 → 0.4.0

package/README.md

@@ -75,6 +75,33 @@ npx fini-proof licence                                                     # lic
 
 A skipped test is allowed without a baseline when a comment names why: `// SKIP-LEDGER: JIRA-123 reason`.
 
+## Proven fixes
+
+```bash
+npx fini-proof fix              # dry run: prints each finding's outcome, writes .fini-proof/fixes/<run id>.patch
+npx fini-proof fix --apply      # the same, and writes the proven fixes to the working tree (never commits)
+```
+
+`fix` runs the same check, then for each finding does one of three things:
+
+- **`fixed (proven)`** — a deterministic text transform (no AI, no network; your code never leaves your machine) is
+  applied to a throw-away copy of the repository and proved there by the same engines: the unfixed file still
+  reproduces the finding (red), `prove` no longer finds it (green), a whole `check` of that file raises no new finding
+  from any engine, and the rule's negative control is still caught (the check can still fail).
+- **`manual`** — no safe transform exists for that rule (or that instance); the engine's own FIX text is shown.
+- **`refused (fix did not prove)`** — a transform existed but failed one of the proofs; nothing is changed.
+
+Scope is deliberately small. Fixers exist only for: `OR_TRUE` (drop `|| true` / `|| exit 0` / `--passWithNoTests`),
+`SET_PLUS_E` (→ `set -e`), `CONTINUE_ON_ERROR` / `ALLOW_FAILURE` (→ `false`), `CATCH_EXIT_ZERO` (→ `process.exit(1)`),
+`EMPTY_CATCH` (rethrow; a swallowing `.catch(() => {})` is removed), `EXCEPT_PASS` (`pass` → `raise`, `exit(0)` →
+`exit(1)`) and `FOCUSED_TEST` (`it.only(` → `it(`). Everything else — hollow tests, secrets, tenant filters, every
+migration rule, skipped tests, entry-point guards, `except: return 0` — needs a human decision and stays `manual`.
+A proven fix makes the failure visible again; it does not make your tests pass. Review the patch like any other diff.
+
+The evidence record of a `fix` run carries an optional `fixes` field (`mode`, `summary`, and per finding `status`,
+`proof { red, finding_gone, no_new_findings, negative_control }`, before/after sha256). It is additive, so the schema
+stays `evidence@2` and the digest covers it.
+
 ## Evidence file (evidence@2)
 
 Every `check` writes one JSON record (`.fini-proof/runs/<run id>.json`, or `--json-out` / `--evidence <file>`).
@@ -178,7 +205,7 @@ Add `.fini-proof/runs/` to `.gitignore`. Every check writes an evidence file the
 The agent that wrote the code does not decide whether it is done.
 
 - **MCP server:** `npx fini-proof mcp` gives the agent three tools: `check`, `explain_finding` and `list_rules`.
-  Claude Code: `claude mcp add fini-proof -- npx --yes fini-proof@0.3.0 mcp`.
+  Claude Code: `claude mcp add fini-proof -- npx --yes fini-proof@0.4.0 mcp`.
 - **Claude Code hooks:** see `integrations/claude-code/`. The Stop hook exits 2 with the findings while the verdict is
   FAIL, so Claude cannot finish. PostToolUse gives feedback on each file as it is written.
 - **Codex and other agents:** see `integrations/codex/` for an `AGENTS.md` section and a CI gate. The gate also fails
@@ -200,7 +227,7 @@ Developer workspace with `check --upload` (set `FINI_PROOF_API_KEY` as a CI secr
 schedule in the file; GitLab and Bitbucket need a schedule created once in their UI (the file says where). A failed
 upload is a warning and never changes the exit code.
 
-Each one is one command: `npx --yes fini-proof@0.3.0 check --base origin/<target> --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json`.
+Each one is one command: `npx --yes fini-proof@0.4.0 check --base origin/<target> --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json`.
 Clone with full history (`fetch-depth: 0`, `GIT_DEPTH: 0`, `depth: full`). A shallow clone gives NOT_MEASURED, not a guessed PASS.
 `test/ci-templates.test.mjs` runs every one of these commands against a real git repository (a clean pull request must pass, a defective one must fail). The daily templates are run the same way on the default branch, uploading to a local stand-in server.
 

package/ci/Jenkinsfile

@@ -5,7 +5,7 @@ stage('Fini Proof') {
     FINI_PROOF_HOME = "${env.WORKSPACE}/.fini-proof-home"
   }
   steps {
-    sh 'npx --yes fini-proof@0.3.0 check --base "origin/${CHANGE_TARGET:-main}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json'
+    sh 'npx --yes fini-proof@0.4.0 check --base "origin/${CHANGE_TARGET:-main}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json'
   }
   post {
     always { archiveArtifacts artifacts: 'fini-proof.sarif, fini-proof-evidence.json', allowEmptyArchive: true }

package/ci/Jenkinsfile.daily

@@ -13,7 +13,7 @@ pipeline {
     stage('Fini Proof (daily)') {
       when { anyOf { branch 'main'; branch 'master' } }
       steps {
-        sh 'npx --yes fini-proof@0.3.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json'
+        sh 'npx --yes fini-proof@0.4.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json'
       }
       post {
         always { archiveArtifacts artifacts: 'fini-proof.sarif, fini-proof-evidence.json', allowEmptyArchive: true }

package/ci/bitbucket-pipelines-daily.yml

@@ -11,5 +11,5 @@ pipelines:
           clone: { depth: full }
           script:
             - export FINI_PROOF_HOME="$BITBUCKET_CLONE_DIR/.fini-proof-home"
-            - npx --yes fini-proof@0.3.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
+            - npx --yes fini-proof@0.4.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
           artifacts: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/bitbucket-pipelines.yml

@@ -8,5 +8,5 @@ pipelines:
           clone: { depth: full }
           script:
             - export FINI_PROOF_HOME="$BITBUCKET_CLONE_DIR/.fini-proof-home"
-            - npx --yes fini-proof@0.3.0 check --base "origin/${BITBUCKET_PR_DESTINATION_BRANCH:-main}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
+            - npx --yes fini-proof@0.4.0 check --base "origin/${BITBUCKET_PR_DESTINATION_BRANCH:-main}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
           artifacts: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/github-actions-daily.yml

@@ -22,7 +22,7 @@ jobs:
           FINI_PROOF_API_KEY: ${{ secrets.FINI_PROOF_API_KEY }}
           FINI_PROOF_LICENCE: ${{ secrets.FINI_PROOF_LICENCE }}
           FINI_PROOF_HOME: ${{ runner.temp }}/fini-proof-home
-        run: npx --yes fini-proof@0.3.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
+        run: npx --yes fini-proof@0.4.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
       - if: always() && hashFiles('fini-proof.sarif') != ''
         uses: github/codeql-action/upload-sarif@v3
         with: { sarif_file: fini-proof.sarif, category: fini-proof-daily }

package/ci/github-actions-example.yml

@@ -9,6 +9,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
-      - uses: finipe/fini-proof@v0.3.0
+      - uses: finipe/fini-proof@v0.4.0
         with:
           licence: ${{ secrets.FINI_PROOF_LICENCE }}

package/ci/gitlab-ci-daily.yml

@@ -11,7 +11,7 @@ fini-proof-daily:
     GIT_DEPTH: "0"
     FINI_PROOF_HOME: "$CI_PROJECT_DIR/.fini-proof-home"
   script:
-    - npx --yes fini-proof@0.3.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
+    - npx --yes fini-proof@0.4.0 check --upload --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
   artifacts:
     when: always
     paths: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/gitlab-ci.yml

@@ -7,7 +7,7 @@ fini-proof:
     GIT_DEPTH: "0"
     FINI_PROOF_HOME: "$CI_PROJECT_DIR/.fini-proof-home"
   script:
-    - npx --yes fini-proof@0.3.0 check --base "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-$CI_DEFAULT_BRANCH}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
+    - npx --yes fini-proof@0.4.0 check --base "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-$CI_DEFAULT_BRANCH}" --fail-on high --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json
   artifacts:
     when: always
     paths: [fini-proof.sarif, fini-proof-evidence.json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fini-proof",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Proof-based code verification: every finding carries a runnable proof, every check has a negative control, and a check that cannot run is NOT_MEASURED, never PASS.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -9,7 +9,8 @@ import { exportUsage, readUsage, recordRun } from './usage.mjs'
 import { serveMcp } from './mcp.mjs'
 import { runHook } from './hooks.mjs'
 import { DEFAULT_API, gzipWanted, uploadEvidence } from './upload.mjs'
-import { readEvidenceFile, snapshotOf } from './evidence.mjs'
+import { computeDigest, readEvidenceFile, snapshotOf } from './evidence.mjs'
+import { fixFindings } from './fix.mjs'
 import { applyStaleness, deriveStates, stateDocument, stateText } from './state.mjs'
 
 const HELP = `fini-proof ${TOOL_VERSION} — proof-based code verification
@@ -23,6 +24,10 @@ const HELP = `fini-proof ${TOOL_VERSION} — proof-based code verification
                    check now; with --against it runs nothing and marks STALE what changed since that evidence
   fini-proof evidence verify <evidence.json>                      re-check an evidence file's digest (exit 1 = edited)
   fini-proof prove --engine <id> --file <path> [--line <n>]    re-run one finding (exit 1 = still there)
+  fini-proof fix [--apply] [--patch-out <file>] [--engine <id>]... [--only <file>]... [--base <ref>] [--evidence <file>]
+                   PROVEN fixes, local and deterministic (no AI, no network). Each fix is re-proved on a throw-away
+                   copy: finding gone, no new finding, negative control still caught. Dry-run by default (writes a
+                   patch); --apply writes the working tree; never commits. Output: fixed (proven) · manual · refused
   fini-proof negctl <control-id> | --all                          show a check can fail (planted defect → caught)
   fini-proof baseline [--reset]                                   write the skip ratchet baseline (can only go down)
   fini-proof usage [--export <file>]                              local usage meter (runs, repos, seats)
@@ -41,7 +46,7 @@ function parse(argv) {
     const a = argv[i]
     if (!a.startsWith('--')) { o._.push(a); continue }
     const [k, inline] = a.slice(2).split('=')
-    const flag = ['all', 'reset', 'help', 'version', 'upload', 'upload-gzip'].includes(k)
+    const flag = ['all', 'reset', 'help', 'version', 'upload', 'upload-gzip', 'apply'].includes(k)
     const v = flag ? true : (inline ?? argv[++i])
     if (!flag && v === undefined) throw new Error(`--${k} needs a value`)
     if (k === 'engine') o.engine.push(v)
@@ -58,7 +63,7 @@ const err = (s) => process.stderr.write(s.endsWith('\n') ? s : s + '\n')
  * The one licensed check path — used by `check`, the MCP `check` tool and the Claude Code hook, so all three enforce
  * the same licence, write the same evidence and meter the same way. Returns { rc, result?, ent?, evidencePath?, error? }.
  */
-export function executeCheck({ root, base, failOn, engines = [], only, licence, evidence, sarifOut, jsonOut, maker }) {
+export function executeCheck({ root, base, failOn, engines = [], only, licence, evidence, sarifOut, jsonOut, maker, augment }) {
   const unknown = engines.filter((e) => !ENGINES.some((x) => x.id === e))
   if (unknown.length) return { rc: EXIT.USAGE, error: `unknown engine(s): ${unknown.join(', ')}` }
   const info = repoInfo(root)
@@ -67,6 +72,8 @@ export function executeCheck({ root, base, failOn, engines = [], only, licence,
   if (!ent.ok) return { rc: EXIT.LICENCE, error: `VERDICT: NOT_MEASURED — licence: ${ent.reason}` }
   let result
   try { result = check(root, { base, failOn, engines, only, maker }) } catch (e) { return { rc: EXIT.USAGE, error: `fini-proof: ${e.message}` } }
+  // augment (the `fix` command): adds an optional evidence@2 field BEFORE the digest, so the digest covers it
+  if (augment) { augment(result); delete result.evidenceDigest; result.evidenceDigest = computeDigest(result) }
   result.entitlement = ent.mode === 'licence' ? { mode: 'licence', org: ent.org, seats: ent.seats, expiry: ent.expiry, licenceId: ent.licenceId } : { mode: 'trial', daysLeft: ent.daysLeft, trialEnds: ent.trialEnds }
   const evidencePath = path.resolve(root, evidence || path.join('.fini-proof', 'runs', `${result.runId}.json`))
   mkdirSync(path.dirname(evidencePath), { recursive: true })
@@ -120,6 +127,37 @@ function cmdProve(o) {
   return EXIT.FAIL
 }
 
+function cmdFix(o) {
+  const root = path.resolve(o.root || process.cwd())
+  let fx = null
+  const x = executeCheck({ root, base: o.base, failOn: o.failOn, engines: o.engine, only: o.only, licence: o.licence, evidence: o.evidence,
+    augment: (result) => {
+      if (result.reason && !result.engines.length) return // nothing was listed: nothing to fix
+      fx = fixFindings(root, result, { apply: !!o.apply })
+      result.fixes = fx.record
+    } })
+  if (x.error) { err(x.error); return x.rc }
+  if (!fx) { err(`NOT_MEASURED — ${x.result.reason}`); return EXIT.NOT_MEASURED }
+  const { record, patch } = fx
+  for (const it of record.items) {
+    const where = `${it.file}${it.line ? `:${it.line}` : ''}`
+    if (it.status === 'fixed') out(`fixed (proven)              ${it.property_id}  ${where}`)
+    else if (it.status === 'refused') out(`refused (fix did not prove) ${it.property_id}  ${where} — ${it.reason}`)
+    else out(`manual                      ${it.property_id}  ${where} — FIX: ${it.fix}`)
+  }
+  let patchPath = null
+  if (patch) {
+    patchPath = path.resolve(root, o.patchOut || path.join('.fini-proof', 'fixes', `${x.result.runId}.patch`))
+    mkdirSync(path.dirname(patchPath), { recursive: true })
+    writeFileSync(patchPath, patch)
+  }
+  const s = record.summary
+  out(`\n${s.fixed} fixed (proven) · ${s.manual} manual · ${s.refused} refused`)
+  if (patchPath) out(o.apply ? `applied to the working tree (not committed); patch: ${path.relative(process.cwd(), patchPath)}` : `dry run — nothing changed. Patch: ${path.relative(process.cwd(), patchPath)} (git apply it, or re-run with --apply)`)
+  out(`evidence: ${path.relative(process.cwd(), x.evidencePath)}`)
+  return EXIT.PASS
+}
+
 function cmdNegctl(o) {
   const all = ENGINES.flatMap((e) => e.negativeControls.map((c) => ({ e, c })))
   const pick = o.all ? all : all.filter(({ c }) => c.id === o._[1])
@@ -246,6 +284,7 @@ export function main(argv) {
     case 'prove': return cmdProve(o)
     case 'state': return cmdState(o)
     case 'evidence': return cmdEvidence(o)
+    case 'fix': return cmdFix(o)
     case 'negctl': return cmdNegctl(o)
     case 'baseline': return cmdBaseline(o)
     case 'usage': return cmdUsage(o)

package/src/engines/fail-open.mjs

@@ -39,10 +39,9 @@ function packageJsonRules(content) {
   return out
 }
 
-/** Find `catch (e) { … }` / `.catch(() => …)` bodies in masked JS and flag the fail-open shapes. */
-function jsCatchRules(src) {
+/** `catch (…) { … }` blocks in MASKED JS: { index, open, close, binding } (offsets are the original source's). */
+export function catchBlocks(masked) {
   const out = []
-  const masked = maskStringsAndComments(src)
   const re = /\bcatch\s*(\([^)]*\))?\s*\{/g
   let m
   while ((m = re.exec(masked)) !== null) {
@@ -52,13 +51,25 @@ function jsCatchRules(src) {
       if (masked[i] === '{') depth++
       else if (masked[i] === '}' && --depth === 0) { close = i; break }
     }
-    if (close < 0) continue
-    const body = masked.slice(open + 1, close)
-    const line = lineOf(src, m.index)
-    if (/process\.exit\s*\(\s*0?\s*\)/.test(body)) out.push({ line, rule: 'CATCH_EXIT_ZERO', severity: 'high', message: 'the error handler exits 0 — the script reports success exactly when it failed. FIX: exit non-zero (or rethrow) in the catch.' })
+    if (close >= 0) out.push({ index: m.index, open, close, binding: m[1] ? m[1].slice(1, -1).trim() : null })
+  }
+  return out
+}
+const PROMISE_CATCH_RE = /\.catch\s*\(\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)?\s*=>\s*(\{\s*\}|null|undefined|void 0|\(\s*\)|false|true)\s*\)/g
+const EXIT_ZERO_RE = /process\.exit\s*\(\s*0?\s*\)/
+
+/** Find `catch (e) { … }` / `.catch(() => …)` bodies in masked JS and flag the fail-open shapes. */
+function jsCatchRules(src) {
+  const out = []
+  const masked = maskStringsAndComments(src)
+  let m
+  for (const b of catchBlocks(masked)) {
+    const body = masked.slice(b.open + 1, b.close)
+    const line = lineOf(src, b.index)
+    if (EXIT_ZERO_RE.test(body)) out.push({ line, rule: 'CATCH_EXIT_ZERO', severity: 'high', message: 'the error handler exits 0 — the script reports success exactly when it failed. FIX: exit non-zero (or rethrow) in the catch.' })
     else if (body.trim() === '') out.push({ line, rule: 'EMPTY_CATCH', severity: 'medium', message: 'an empty catch swallows the error — the script carries on as if it succeeded. FIX: rethrow, or log and exit non-zero.' })
   }
-  const pc = /\.catch\s*\(\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)?\s*=>\s*(\{\s*\}|null|undefined|void 0|\(\s*\)|false|true)\s*\)/g
+  const pc = new RegExp(PROMISE_CATCH_RE.source, 'g')
   while ((m = pc.exec(masked)) !== null) out.push({ line: lineOf(src, m.index), rule: 'EMPTY_CATCH', severity: 'medium', message: '`.catch(() => {})` swallows the rejection — the script carries on as if it succeeded. FIX: let it reject, or log and exit non-zero.' })
   return out
 }
@@ -82,9 +93,86 @@ function pyRules(content) {
   return out
 }
 
+// ── Proven fixes (`fini-proof fix`, src/fix.mjs). A fixer is a deterministic, local text transform for ONE finding:
+// (content, finding) → new content, or null when this instance has no safe transform (→ reported as manual). A fixer
+// never decides that it worked: src/fix.mjs proves every candidate with this engine before it is offered.
+const OR_TRUE_RE = /\s*\|\|\s*(?:true|:|exit\s+0)\b/g
+const lineEdit = (content, n, edit) => {
+  const lines = content.split('\n')
+  const next = edit(lines[n - 1])
+  if (next === null || next === lines[n - 1]) return null
+  lines[n - 1] = next
+  return lines.join('\n')
+}
+/** Split a shell/YAML line into code and trailing `# comment` (the same comment rule shellRules() uses). */
+const codeAndComment = (l) => { const m = /(^|\s)#.*$/.exec(l); return m ? [l.slice(0, m.index), l.slice(m.index)] : [l, ''] }
+const setFlag = (key) => (content, f) => lineEdit(content, f.line, (l) => l.replace(new RegExp(`^(\\s*${key}\\s*:\\s*)true\\b`), '$1false'))
+
+const fixers = {
+  OR_TRUE(content, f, rel) {
+    if (/(^|\/)package\.json$/.test(rel)) {
+      return lineEdit(content, f.line, (l) => {
+        const next = l.replace(OR_TRUE_RE, '').replace(/\s+--passWithNoTests\b/g, '')
+        // the script value must still be on this line and still be a non-empty command
+        return /:\s*"\s*[^"\s]/.test(next) ? next : null
+      })
+    }
+    return lineEdit(content, f.line, (l) => {
+      const [code, comment] = codeAndComment(l)
+      const next = code.replace(OR_TRUE_RE, '')
+      if (!next.replace(/^\s*(-\s*)?(run\s*:)?/, '').trim()) return null // nothing left to run → not a safe transform
+      return next + comment
+    })
+  },
+  SET_PLUS_E: (content, f) => lineEdit(content, f.line, (l) => l.replace(/^(\s*set\s+)\+e\b/, '$1-e')),
+  CONTINUE_ON_ERROR: setFlag('continue-on-error'),
+  ALLOW_FAILURE: setFlag('allow_failure'),
+  CATCH_EXIT_ZERO(content, f) {
+    const masked = maskStringsAndComments(content)
+    const b = catchBlocks(masked).find((x) => lineOf(content, x.index) === f.line && EXIT_ZERO_RE.test(masked.slice(x.open + 1, x.close)))
+    if (!b) return null
+    const body = masked.slice(b.open + 1, b.close)
+    const re = new RegExp(EXIT_ZERO_RE.source, 'g')
+    let out = content.slice(0, b.open + 1), last = 0, m
+    while ((m = re.exec(body)) !== null) { out += content.slice(b.open + 1 + last, b.open + 1 + m.index) + 'process.exit(1)'; last = m.index + m[0].length }
+    return out + content.slice(b.open + 1 + last)
+  },
+  EMPTY_CATCH(content, f) {
+    const masked = maskStringsAndComments(content)
+    const b = catchBlocks(masked).find((x) => lineOf(content, x.index) === f.line && masked.slice(x.open + 1, x.close).trim() === '')
+    if (b) {
+      if (b.binding !== null && !/^[A-Za-z_$][\w$]*$/.test(b.binding)) return null // destructured binding: no safe rethrow
+      const name = b.binding || 'err'
+      const head = b.binding === null ? `catch (${name}) {` : content.slice(b.index, b.open + 1)
+      const raw = content.slice(b.open + 1, b.close)
+      const indent = (content.split('\n')[f.line - 1].match(/^\s*/) || [''])[0]
+      const body = raw.trim() === '' ? ` throw ${name} ` : `${raw.replace(/\s*$/, '')}\n${indent}  throw ${name}\n${indent}`
+      return content.slice(0, b.index) + head + body + content.slice(b.close)
+    }
+    // `.catch(() => {})`: remove the swallowing handler so the rejection propagates
+    const re = new RegExp(PROMISE_CATCH_RE.source, 'g')
+    let m
+    while ((m = re.exec(masked)) !== null) if (lineOf(content, m.index) === f.line) return content.slice(0, m.index) + content.slice(m.index + m[0].length)
+    return null
+  },
+  EXCEPT_PASS(content, f) {
+    const lines = content.split('\n')
+    const i = lines.findIndex((x, k) => k >= f.line && x.trim() && !/^\s*#/.test(x))
+    if (i < 0) return null
+    const [ind, stmt] = [lines[i].match(/^\s*/)[0], lines[i].trim()]
+    const rest = stmt.replace(/^\S+(\s*\([^)]*\))?/, '') // a trailing comment, if any
+    let next
+    if (stmt === 'pass' || /^pass\s+#/.test(stmt)) next = 'raise'
+    else if (/^(sys\.)?exit\(\s*0?\s*\)/.test(stmt)) next = stmt.replace(/^((?:sys\.)?exit)\(\s*0?\s*\)/, '$1(1)')
+    else return null // `return 0`: what the caller should get instead is a decision → manual
+    lines[i] = ind + (next === 'raise' ? 'raise' + rest.replace(/^pass/, '') : next)
+    return lines.join('\n')
+  },
+}
+
 export default {
   id: 'fail-open',
-  version: '0.1.0',
+  version: '0.2.0',
   title: 'Fail-open CI steps and scripts',
   provenance: 'finipe scripts/ci/check-entrypoint-guard.mjs rawGuards() @ 4ac53b367; CI/catch rules new',
   appliesTo: (rel) => CI_FILE_RE.test(rel) || SHELL_RE.test(rel) || /(^|\/)package\.json$/.test(rel)
@@ -98,6 +186,7 @@ export default {
     if (SCRIPT_DIR_RE.test(rel)) out.push(...jsCatchRules(content))
     return out
   },
+  fixers,
   rules: {
     OR_TRUE: { severity: 'high', summary: 'a failing command is forced to success (`|| true`, `|| exit 0`, `--passWithNoTests`)', fix: 'let it fail, or handle the one expected error' },
     SET_PLUS_E: { severity: 'medium', summary: '`set +e` turns off fail-on-error for the rest of the script', fix: 'keep set -e; capture an expected exit code explicitly' },

package/src/engines/skip-ratchet.mjs

@@ -14,9 +14,27 @@ const PY_SKIP_RE = /@pytest\.mark\.(?:skip|skipif|xfail)\b|@unittest\.(?:skip|sk
 
 function lineOf(src, idx) { return src.slice(0, idx).split('\n').length }
 
+// Proven fix (`fini-proof fix`, src/fix.mjs): drop the focus — `it.only(` → `it(`, `fit(` → `it(`. Deterministic and
+// local; src/fix.mjs proves the candidate with this engine before it is offered. Skips are NOT auto-fixed: un-skipping
+// a test (or writing its SKIP-LEDGER reason) is a human decision.
+const fixers = {
+  FOCUSED_TEST(content, f) {
+    const masked = maskStringsAndComments(content)
+    const re = new RegExp(ONLY_RE.source, 'g')
+    let m
+    while ((m = re.exec(masked)) !== null) {
+      if (lineOf(content, m.index) !== f.line) continue
+      const hit = content.slice(m.index, m.index + m[0].length)
+      const next = /\.\s*only/.test(hit) ? hit.replace(/\s*\.\s*only/, '') : hit.replace(/^f(it|describe|test)/, '$1')
+      return content.slice(0, m.index) + next + content.slice(m.index + m[0].length)
+    }
+    return null
+  },
+}
+
 export default {
   id: 'skip-ratchet',
-  version: '0.1.0',
+  version: '0.2.0',
   title: 'Focused and skipped tests (ratchet)',
   provenance: 'finipe check-vacuous-spec.mjs skip shapes + SKIP-LEDGER, fini-rule-ratchet.mjs semantics @ 4ac53b367',
   appliesTo: (rel) => JS_TEST_RE.test(rel) || PY_TEST_RE.test(rel),
@@ -56,6 +74,7 @@ export default {
     }
     return { findings: out, measurements: { skipsPerFile: Object.fromEntries(byFile), toleratedByBaseline: tolerated } }
   },
+  fixers,
   rules: {
     FOCUSED_TEST: { severity: 'high', summary: '`.only` / `fit` makes the runner skip every other test', fix: 'remove the focus' },
     SKIPPED_TEST: { severity: 'info', summary: 'a skipped test with no `SKIP-LEDGER: <ref>` reason (tolerated up to the baseline)', fix: 'un-skip, or add a SKIP-LEDGER comment' },

package/src/evidence.mjs

@@ -13,6 +13,11 @@
 //                  .scope_files  = sorted paths the engine read (scan scope + schema/context files) — Proof.scope
 //   attestation    { maker: { kind: human|agent|unknown, id, model?, session?, source },
 //                    verifier: { tool, version, engine_digests, runner: { host_digest, ci } } }
+//   fixes          OPTIONAL, written only by `fini-proof fix` (0.4.0): { mode: dry-run|apply, patch_sha256, summary:
+//                  { fixed, manual, refused }, items[]: { property_id, file, line, status: fixed|manual|refused,
+//                  proof?: { red, finding_gone, no_new_findings, negative_control: { id, caught } }, before_sha256?,
+//                  after_sha256?, reason?, fix? } }. An additive optional field, so the schema stays evidence@2: every
+//                  @2 reader ignores unknown fields, and the digest rule is unchanged (the field is inside the digest).
 import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import os from 'node:os'

package/src/fix.mjs

@@ -0,0 +1,146 @@
+// `fini-proof fix` — PROVEN fixes. No LLM, no network: every candidate is a deterministic text transform that lives
+// next to its rule (engine.fixers[RULE], today in engines/fail-open.mjs and engines/skip-ratchet.mjs), and nothing is
+// offered until the SAME engines prove it on a throw-away copy of the repository:
+//   1. red   — the unfixed file, re-scanned in the copy, still raises the rule at that line (the defect is real);
+//   2. green — with the candidate, `prove` no longer finds the rule at that line and the rule's count in the file
+//              dropped by exactly one;
+//   3. no regressions — a whole `check --only <file>` over the candidate raises no finding (any engine, any rule)
+//              that the unfixed file did not, and no engine becomes NOT_MEASURED;
+//   4. the check can still fail — the rule's negative control is still caught.
+// Anything else is `refused (fix did not prove)`. A rule with no fixer, or an instance a fixer cannot transform
+// safely, is `manual` with the engine's own FIX text — never guessed.
+//
+// REUSE NOTE: there is no second rule model here. Detection, proof and controls are runner.mjs check()/prove()/
+// runControl() and the engines' own rule tables; this file only orchestrates them and writes the diff.
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { ENGINES, check, prove, runControl, sha256 } from './runner.mjs'
+
+/** A minimal, correct unified diff of one file (one hunk spanning every change, 3 lines of context). */
+export function unifiedDiff(rel, a, b, context = 3) {
+  if (a === b) return ''
+  const split = (s) => (s.endsWith('\n') ? s.slice(0, -1) : s).split('\n')
+  const A = split(a), B = split(b)
+  let pre = 0
+  while (pre < A.length && pre < B.length && A[pre] === B[pre]) pre++
+  let suf = 0
+  while (suf < A.length - pre && suf < B.length - pre && A[A.length - 1 - suf] === B[B.length - 1 - suf]) suf++
+  // a changed final-newline state must stay inside the hunk
+  if (a.endsWith('\n') !== b.endsWith('\n') && suf > 0) suf = 0
+  const s = Math.max(0, pre - context)
+  const eA = Math.min(A.length, A.length - suf + context), eB = Math.min(B.length, B.length - suf + context)
+  const out = [`--- a/${rel}`, `+++ b/${rel}`, `@@ -${s + 1},${eA - s} +${s + 1},${eB - s} @@`]
+  const noNl = '\'
+  const ctxLine = (i) => { out.push(` ${A[i]}`); if (i === A.length - 1 && !a.endsWith('\n')) out.push(noNl) }
+  for (let i = s; i < pre; i++) ctxLine(i)
+  for (let i = pre; i < A.length - suf; i++) { out.push(`-${A[i]}`); if (i === A.length - 1 && !a.endsWith('\n')) out.push(noNl) }
+  for (let i = pre; i < B.length - suf; i++) { out.push(`+${B[i]}`); if (i === B.length - 1 && !b.endsWith('\n')) out.push(noNl) }
+  for (let i = A.length - suf; i < eA; i++) ctxLine(i)
+  return out.join('\n') + '\n'
+}
+
+/** The engine's own FIX guidance for a finding (the message's FIX: part, else the rule table's fix). */
+export function fixText(engine, f) {
+  const m = /FIX:\s*(.+)$/s.exec(f.message || '')
+  return (m ? m[1] : engine?.rules?.[f.rule]?.fix || 'see the finding message').trim()
+}
+
+/** Per-property finding counts of a whole `check --only <rel>` over `root`, plus the engines that were measured. */
+function countsOf(root, rel) {
+  const r = check(root, { only: [rel], failOn: 'none' })
+  const counts = {}
+  for (const f of r.findings) if (f.file === rel) counts[f.property_id] = (counts[f.property_id] || 0) + 1
+  const measured = new Set(r.engines.filter((e) => e.status === 'MEASURED').map((e) => e.id))
+  return { counts, measured }
+}
+
+/**
+ * Prove one candidate on the throw-away copy `work`. The copy holds `before` for `rel` on entry and on a refusal,
+ * `candidate` on success. Returns { ok, proof, reason? }.
+ */
+export function proveFix(work, { engine, rule, rel, line, before, candidate }) {
+  const file = path.join(work, rel)
+  const pid = `${engine.id}/${rule}`
+  const proof = { red: false, finding_gone: false, no_new_findings: false, negative_control: null }
+  const refuse = (reason) => { writeFileSync(file, before); return { ok: false, proof, reason } }
+  writeFileSync(file, before)
+  const red = prove(work, engine.id, rel, line)
+  if (red.status !== 'OK') return refuse(`NOT_MEASURED before the fix: ${red.reason}`)
+  proof.red = red.hits.some((h) => h.rule === rule)
+  if (!proof.red) return refuse(`the unfixed file does not reproduce ${pid} at line ${line}`)
+  const was = countsOf(work, rel)
+  writeFileSync(file, candidate)
+  const green = prove(work, engine.id, rel, line)
+  if (green.status !== 'OK') return refuse(`NOT_MEASURED after the fix: ${green.reason}`)
+  const now = countsOf(work, rel)
+  proof.finding_gone = !green.hits.some((h) => h.rule === rule) && (now.counts[pid] || 0) === (was.counts[pid] || 0) - 1
+  if (!proof.finding_gone) return refuse(`${pid} is still raised after the fix`)
+  const added = Object.entries(now.counts).filter(([k, n]) => n > (was.counts[k] || 0)).map(([k, n]) => `${k} ${was.counts[k] || 0}→${n}`)
+  const lost = [...was.measured].filter((id) => !now.measured.has(id))
+  proof.no_new_findings = added.length === 0 && lost.length === 0
+  if (added.length) return refuse(`the fix raises a new finding: ${added.join(', ')}`)
+  if (lost.length) return refuse(`the fix makes ${lost.join(', ')} NOT_MEASURED on this file`)
+  const nc = engine.negativeControls.find((c) => c.expect === rule)
+  if (!nc) return refuse(`${pid} has no negative control — a fix of a check that cannot be shown to fail is not proven`)
+  const ncr = runControl(engine, nc, 'negative', work)
+  proof.negative_control = { id: nc.id, caught: ncr.ok }
+  if (!ncr.ok) return refuse(`negative control ${nc.id} is no longer caught`)
+  return { ok: true, proof }
+}
+
+/**
+ * Plan (and optionally apply) proven fixes for the findings of one check result. Never commits; writes to the
+ * working tree only with apply. Returns the evidence `fixes` record plus the patch text.
+ */
+export function fixFindings(root, result, { apply = false } = {}) {
+  const items = []
+  const byFile = new Map()
+  for (const f of result.findings) {
+    const engine = ENGINES.find((e) => e.id === f.engine)
+    if (!engine?.fixers?.[f.rule] || typeof f.line !== 'number') {
+      items.push({ property_id: f.property_id, file: f.file, line: f.line, status: 'manual', fix: fixText(engine, f) })
+      continue
+    }
+    if (!byFile.has(f.file)) byFile.set(f.file, [])
+    byFile.get(f.file).push({ f, engine })
+  }
+  let patch = ''
+  if (byFile.size) {
+    const work = mkdtempSync(path.join(os.tmpdir(), 'fini-proof-fix-'))
+    try {
+      cpSync(root, work, { recursive: true, filter: (src) => !src.split(path.sep).includes('node_modules') })
+      for (const [rel, list] of byFile) {
+        const original = readFileSync(path.join(root, rel), 'utf8')
+        let content = original
+        // bottom-up: an edit never moves the line of a finding that is still to be fixed
+        list.sort((x, y) => y.f.line - x.f.line || x.f.rule.localeCompare(y.f.rule))
+        for (const { f, engine } of list) {
+          const base = { property_id: f.property_id, file: rel, line: f.line }
+          const candidate = engine.fixers[f.rule](content, f, rel)
+          if (candidate === null || candidate === content) { items.push({ ...base, status: 'manual', reason: 'no safe deterministic transform for this instance', fix: fixText(engine, f) }); continue }
+          const p = proveFix(work, { engine, rule: f.rule, rel, line: f.line, before: content, candidate })
+          if (!p.ok) { items.push({ ...base, status: 'refused', reason: p.reason, proof: p.proof, fix: fixText(engine, f) }); continue }
+          items.push({ ...base, status: 'fixed', proof: p.proof, before_sha256: sha256(content), after_sha256: sha256(candidate) })
+          content = candidate
+        }
+        if (content === original) continue
+        if (apply) {
+          // the working tree must still hold the bytes that were proven against
+          const cur = readFileSync(path.join(root, rel), 'utf8')
+          if (cur !== original) {
+            for (const it of items) if (it.file === rel && it.status === 'fixed') Object.assign(it, { status: 'refused', reason: `${rel} changed while fixing; nothing written` })
+            continue
+          }
+          writeFileSync(path.join(root, rel), content)
+        }
+        patch += unifiedDiff(rel, original, content)
+      }
+    } finally { rmSync(work, { recursive: true, force: true }) }
+  }
+  const n = (s) => items.filter((i) => i.status === s).length
+  return {
+    record: { mode: apply ? 'apply' : 'dry-run', patch_sha256: patch ? sha256(patch) : null, summary: { fixed: n('fixed'), manual: n('manual'), refused: n('refused') }, items },
+    patch,
+  }
+}

package/src/runner.mjs

@@ -17,7 +17,7 @@ import skipRatchet from './engines/skip-ratchet.mjs'
 import tenantFilter from './engines/tenant-filter.mjs'
 import migrations from './engines/migrations.mjs'
 
-export const TOOL_VERSION = '0.3.0'
+export const TOOL_VERSION = '0.4.0'
 // Order matters in one place: an orchestrated engine runs before the built-in engine it `replaces` (gitleaks → secrets).
 export const ENGINES = [hollow, gitleaks, secrets, failOpen, skipRatchet, tenantFilter, migrations]
 const ENGINE_FILES = {
@@ -300,7 +300,7 @@ export function prove(root, engineId, file, line = null) {
 export function ruleCatalogue() {
   return ENGINES.map((e) => ({
     engine: e.id, version: e.version, title: e.title, provenance: e.provenance,
-    rules: Object.entries(e.rules || {}).map(([id, r]) => ({ id, ...r, negativeControl: (e.negativeControls.find((c) => c.expect === id) || {}).id || null })),
+    rules: Object.entries(e.rules || {}).map(([id, r]) => ({ id, ...r, provenFix: !!e.fixers?.[id], negativeControl: (e.negativeControls.find((c) => c.expect === id) || {}).id || null })),
     negativeControls: e.negativeControls.map((c) => c.id),
   }))
 }