fini-proof 0.3.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Finipe Ventures. All rights reserved.
+
+Fini Proof is proprietary software. Use requires a valid Fini Proof licence key or an active
+trial (1 repository, 14 days). No right to copy, modify, redistribute or sublicense is granted
+except under a written agreement with Finipe Ventures.

package/README.md

@@ -0,0 +1,220 @@
+# Fini Proof — CLI and CI step (v0.1)
+
+> **Product SSOT:** [docs/FINI_PROOF_SSOT_2026-09-28.md](docs/FINI_PROOF_SSOT_2026-09-28.md) — the architecture decision every other document is downstream of.
+
+Fini Proof checks a code change and gives one verdict: **PASS**, **FAIL** or **NOT_MEASURED**.
+
+- Every finding shows the file and line, the rule, and a **proof command** that anyone can run again.
+- Every check has a **negative control**: a planted defect that the check must catch before it is allowed to judge your code. A check that cannot fail is not evidence.
+- The verdict **fails closed**: if a check cannot run (unreadable file, missing base branch, no files to check, bad licence), the verdict is NOT_MEASURED. It is never PASS.
+- Every run writes an **evidence file** (`fini-proof/evidence@2`: run id, commit and git tree hash, engine versions and
+  hashes, the result of every negative control, input file hashes, who made the change and who verified it, a digest of
+  the whole record) and can write **SARIF** for GitHub code scanning. See [Evidence file](#evidence-file-evidence2).
+
+Runs offline. No code leaves the machine. Node.js 20 or newer. No dependencies.
+
+## Quick start
+
+```bash
+npx fini-proof check                        # whole repository
+npx fini-proof check --base origin/main     # only files changed against main (for pull requests)
+npx fini-proof check --format sarif > fini-proof.sarif
+npx fini-proof check --fail-on medium       # stricter (default: high)
+```
+
+Until the package is published to npm, run it from a checkout: `node /path/to/fini-proof/bin/fini-proof.mjs check`.
+
+Exit codes: `0` PASS · `1` FAIL · `2` usage error · `3` NOT_MEASURED · `4` licence refused.
+
+## The checks (engines)
+
+| Engine | What it catches | Languages | Where it came from |
+|---|---|---|---|
+| `hollow-tests` | Tests that cannot fail: no assertion, only constant assertions (`expect(true).toBe(true)`, `assert.ok(true)`, `assert True`), swallowed catch, un-awaited promise, `done()` too early, mock-only / type-only / key-only assertions | JS/TS (Jest, Vitest, Mocha, node:test); Python (pytest, unittest) | Ported from Finipe's F4 vacuous-spec detector (`scripts/ci/check-vacuous-spec.mjs`) |
+| `secrets` | AWS keys, private keys, Slack/Stripe/SendGrid/GitHub/Google/LLM API keys, JWTs in config, real values in `.env` files, hard-coded passwords | any text file | Ported from Finipe's secrets gate (`scripts/ci/check-secrets-and-log-redaction.mjs`) |
+| `fail-open` | CI steps and scripts that report success when they failed: `\|\| true`, `set +e`, `continue-on-error`, `allow_failure`, `catch { process.exit(0) }`, empty catch, `except: pass`, broken ESM entry-point guards | CI YAML, shell, package.json, JS/TS/Python scripts | Entry-point rule ported from Finipe's `check-entrypoint-guard.mjs`; the rest generalised |
+| `skip-ratchet` | `.only` / `fit` (always), and skipped tests above the committed baseline | JS/TS, Python | Skip shapes + `SKIP-LEDGER:` convention from Finipe F4; ratchet from `fini-rule-ratchet.mjs` |
+| `tenant-filter` | A query on a multi-tenant table with no tenant filter, which leaks data across tenants (IDOR) | Raw SQL in any language; TypeORM, Prisma, Sequelize-style, Knex, Django ORM, SQLAlchemy | Detector shapes from Finipe's `.github/scripts/check-tenant-scoping.js`; schema-aware table detection is new |
+| `migrations` | `DROP TABLE` / `DROP COLUMN`, column type changes, `ADD COLUMN … NOT NULL` without a default, `SET NOT NULL`, missing or incomplete down / rollback | SQL (plain, Flyway, golang-migrate, goose, dbmate), Prisma, TypeORM, Knex, Alembic, Django | Loop expansion + down() rules from Finipe's `scripts/ci/lib/migration-invariants.cjs`; destructive-change rules are new |
+
+`tenant-filter` and `migrations` are **NOT_APPLICABLE** (they do not block) in a repository with no migrations or no
+table that has the tenant column. Each case is recorded with the reason.
+
+### Orchestrated scanner: gitleaks
+
+If a `gitleaks` binary is already on `PATH`, Fini Proof runs it as the engine `gitleaks` and holds it to the same rule
+as its own engines:
+
+- Before it judges your code, Fini Proof plants three known-shaped secrets (an AWS key, a GitHub token, a private key)
+  in a temporary copy and runs gitleaks on it. If gitleaks misses one, exits with an error, times out or writes a
+  report that is not JSON, the engine is **NOT_MEASURED** and the run cannot PASS.
+- gitleaks scans a temporary copy of exactly the files Fini Proof hashed (ignore globs, `--base` and `--only` apply),
+  with `--redact`. Findings name the file, line and gitleaks rule; the secret itself is never written anywhere.
+- When gitleaks passed its controls, it is the primary secrets check and the built-in `secrets` engine is
+  NOT_APPLICABLE for that run. When gitleaks is not installed, the `gitleaks` engine is NOT_APPLICABLE (with the reason)
+  and the built-in `secrets` engine runs as before.
+- Fini Proof never downloads a scanner. `FINI_PROOF_GITLEAKS=<path>` uses a binary outside `PATH` (a path that is not
+  executable is NOT_MEASURED); `FINI_PROOF_GITLEAKS=off` keeps the built-in engine. The binary's sha256 and version are
+  recorded, and they are part of the engine digest, so a new gitleaks binary counts as a new verifier.
+
+Every ported file carries its source path and Finipe commit in its header.
+
+## Other commands
+
+```bash
+npx fini-proof prove --engine hollow-tests --file test/a.test.js --line 12   # re-run one finding (exit 1 = still there)
+npx fini-proof state                                                       # per-property proof state for a run now
+npx fini-proof state --against .fini-proof/runs/<id>.json                  # what that run proved, as of the files now
+npx fini-proof evidence verify fini-proof-evidence.json                    # re-check an evidence file's digest
+npx fini-proof negctl hollow-tests/NC-1                                    # show the planted defect being caught
+npx fini-proof negctl --all                                                # all negative controls
+npx fini-proof baseline                                                    # accept today's skipped tests; the count can only go down
+npx fini-proof usage --export usage.json                                   # local usage meter
+npx fini-proof licence                                                     # licence / trial status
+```
+
+A skipped test is allowed without a baseline when a comment names why: `// SKIP-LEDGER: JIRA-123 reason`.
+
+## Evidence file (evidence@2)
+
+Every `check` writes one JSON record (`.fini-proof/runs/<run id>.json`, or `--json-out` / `--evidence <file>`).
+`fini-proof/evidence@2` has everything `evidence@1` had, plus:
+
+| Field | What it is |
+|---|---|
+| `snapshot.tree_hash` | `git rev-parse HEAD^{tree}`. Not a git repository, or no commit yet: `null` with `status: NOT_MEASURED` and the reason (the per-file hashes still identify what was checked). With uncommitted changes it is the HEAD tree and `dirty: true`. |
+| `findings[].property_id` | `<engine>/<rule>`, e.g. `hollow-tests/NO_ASSERTION`. The unit a proof is about. |
+| `engines[].nc_results[]` | `{ id, expect, caught, ms }` for each negative control that ran before the engine was allowed to scan. |
+| `engines[].scope_files` | the files the engine read (its scan scope plus schema files it needed). A change to any of them makes its proofs STALE. |
+| `attestation.maker` | who made the change: `{ kind, id, model?, session?, source }`. From `FINI_PROOF_MAKER_KIND` (`human` or `agent`), `FINI_PROOF_MAKER_ID`, `FINI_PROOF_MAKER_MODEL`, `FINI_PROOF_MAKER_SESSION`; the Claude Code hook records `agent / claude-code` with the session; the MCP server records the MCP client's name. Otherwise the git author of HEAD with `kind: unknown` — the kind is never guessed. |
+| `attestation.verifier` | `{ tool: fini-proof, version, engine_digests, runner: { host_digest, ci } }`. The host name is stored only as a digest. |
+
+The digest (`evidenceDigest`) covers all of this. `fini-proof evidence verify <file>` re-computes it and fails an edited
+file, and a record whose maker is `fini-proof` itself (a verifier cannot attest its own change). Every reader (text,
+SARIF, `state`, `evidence verify`, the PR app) also reads `evidence@1` files from older versions.
+
+## Proof state
+
+`fini-proof state` gives every property (`<engine>/<rule>`) exactly one of five states:
+
+| State | Meaning |
+|---|---|
+| **PROVEN** | The engine passed all its controls, this rule has its own negative control (a planted defect) that was caught and its own positive control (the nearest clean look-alike) that stayed clean, and the rule found nothing in the engine's scope. |
+| **FAILED** | The rule found a medium or high finding. Each one has its proof command. |
+| **NOT_MEASURED** | Nothing could be established. `cause` says why: `engine-not-applicable` (e.g. no migrations in the repository), `engine-not-measured`, `no-scope`, `control-failed`, `missing-negative-control` or `missing-positive-control`. |
+| **STALE** | The record says PROVEN or FAILED, but since then a file in its scope was modified, deleted or added (for a whole-repository run), or the engine changed. Run `check` again. |
+| **ADVISORY** | A low or info rule, such as `TENANT_FILTER_UNPROVEN`. A recommendation. It never blocks and is never shown as proven. |
+
+- `fini-proof state` runs the check now (the same licensed path as `check`, and it writes the same evidence file) and
+  reports the states of that run.
+- `fini-proof state --against <evidence.json>` runs nothing. It verifies the file's digest (an edited file is refused,
+  exit 3), then compares the sha256 of each file in each proof's scope with the files on disk now.
+- Every rule of the six built-in engines and the gitleaks adapter has its own negative and positive control, except
+  `skip-ratchet/SKIPPED_TEST`: it is never reported as a finding (an over-baseline skip becomes `SKIP_RATCHET`), so no
+  planted input can produce it. It is info-level and shows as ADVISORY.
+- `--format json` prints `fini-proof/state@1`: `{ property, state, reason, ncId, runId, snapshot, engineVersion,
+  provenAt, invalidatedBy, … }` for each property. `state` is a report and exits 0; use `check` to gate.
+
+## Upload to your Finipe Developer workspace (optional)
+
+```bash
+export FINI_PROOF_API_KEY=fpk_…        # Developers → Fini Proof → API keys (shown once)
+npx fini-proof check --upload            # repository = origin's owner/name; override with --repository acme/api
+```
+
+- The evidence file is sent to `POST $FINI_PROOF_API/runs` (default `https://developer.finipe.com/api/v1/fini-proof`)
+  with the repository name, the branch and `source` (`ci` when `CI` is set, else `cli`). The server re-checks the
+  evidence digest and refuses an edited file.
+- **An upload never changes the verdict or the exit code.** If it fails (no key, revoked key, network), a warning is
+  printed on stderr and the local evidence file stays the record.
+- The key is sent only in the `Authorization` header and only over https (plain http is accepted for `localhost`
+  only). It is never printed.
+- `--upload-gzip` (or `FINI_PROOF_UPLOAD_GZIP=1`) sends the body with `Content-Encoding: gzip`. It is off by default
+  because the workspace must accept it. The evidence is about 156 bytes per checked file (the per-file sha256 and
+  the per-engine scope that STALE needs): measured 1.56 MB for 10,000 files and 3.13 MB for 20,000 files. Gzip makes
+  those 0.47 MB and 0.93 MB. An HTTP 413 answer prints the evidence size and suggests `--upload-gzip`.
+
+## Configuration
+
+`.fini-proof.json` in the repository root:
+
+```json
+{
+  "ignore": ["vendor/**", "test/fixtures/**"],
+  "tenant": { "column": "tenant_id", "tables": ["orders"], "exemptTables": ["countries"], "exemptPaths": ["src/platform-admin/**"],
+              "helpers": ["buildTeamWhereQuery"], "scopeColumns": ["project_id", "user", "token"] }
+}
+```
+
+- `helpers`: a shared where-builder that adds the tenant condition. Calling it counts as the tenant filter.
+- `scopeColumns`: other columns your team treats as scoping. Examples are a parent key whose row is itself
+  tenant-scoped (`project_id`), the signed-in user for per-user data (`user`), or a secret link token (`token`). They
+  are recorded in the evidence file.
+- Tables with Postgres `ENABLE ROW LEVEL SECURITY` in the schema are isolated by the database, so they are not checked
+  at the call site. They are listed as `rlsTables`.
+- A query with no visible tenant condition is **UNPROVEN** (low, non-blocking by default) and not MISSING (high) in
+  three cases, with the reason in the message: it is re-keyed from an already-loaded row (`id: invoice.id`), the same
+  table was queried with the tenant condition earlier in the function, or the result's tenant column is checked
+  straight after the fetch.
+
+**Adopting on an existing repo:** run `fini-proof baseline` once. It records the migrations already applied
+(path → sha256). An applied migration that has not changed is history and is not judged again. A new or edited
+migration is judged. Changing the baseline is a gated change: the CI gate fails a PR that changes it unless a human
+approves.
+
+Ignored globs are written into the evidence file, so a reviewer can see what was left out. If there is no `tenant`
+block, the column is `tenant_id` (and `tenantId`), and the tenant tables are the ones whose schema (migrations, Prisma,
+TypeORM entities, Django/SQLAlchemy models) declares that column. If you set a `tenant` block and no table matches,
+the result is NOT_MEASURED, not a pass.
+
+A deliberate exception is written in the code, next to the line, with a reason that stays there for review:
+`// fini-proof: tenant-exempt platform-admin report reads all tenants (SEC-19)` and
+`-- fini-proof: allow DROP_COLUMN CHG-812 column unused since release 41`.
+
+Add `.fini-proof/runs/` to `.gitignore`. Every check writes an evidence file there.
+
+## AI coding agents (Claude Code, Codex, any MCP client)
+
+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 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
+  any pull request that changes the verifier's own config without human approval.
+- `fini-proof check --only <file>` checks just the named files, which is what an editor or agent hook needs.
+
+## CI
+
+| System | File |
+|---|---|
+| GitHub Actions | `action.yml` (reusable action) — example workflow in `ci/github-actions-example.yml` |
+| GitLab CI | `ci/gitlab-ci.yml` |
+| Jenkins | `ci/Jenkinsfile` |
+| Bitbucket Pipelines | `ci/bitbucket-pipelines.yml` |
+
+**Daily run of the default branch.** `ci/github-actions-daily.yml`, `ci/gitlab-ci-daily.yml`, `ci/Jenkinsfile.daily`
+and `ci/bitbucket-pipelines-daily.yml` check the whole default branch once a day and send the evidence to your Finipe
+Developer workspace with `check --upload` (set `FINI_PROOF_API_KEY` as a CI secret). GitHub and Jenkins carry the
+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`.
+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.
+
+## Licence
+
+- **Trial:** without a key, Fini Proof runs on 1 repository for 14 days (state in `~/.fini-proof/trial.json`).
+- **Licence key:** an offline, Ed25519-signed key (organisation, seats, expiry). Set `FINI_PROOF_LICENCE` (the key or a path to it), or save it as `.fini-proof/licence.key` or `~/.fini-proof/licence.key`. It is checked on the machine. There is no network call.
+- **Usage meter:** every run adds one line to `~/.fini-proof/usage.jsonl` (commit authors are stored only as hashes). `fini-proof usage --export` writes a summary for billing and seat checks.
+- Vendor only: licence issuing and key handling are in `LICENCE_OPS.md` (`npm run admin -- issue …`, `npm run admin -- keygen --out <dir outside any git checkout>`).
+
+## Demo
+
+`npm run demo` (add `-- --pause` to stop between steps). See `SALES_DEMO.md`.
+
+## Tests
+
+`npm test` (node:test, about 10 seconds, no build).

package/action.yml

@@ -0,0 +1,53 @@
+name: Fini Proof
+description: Proof-based code verification — every finding has a runnable proof, every check a negative control, and a check that cannot run is NOT_MEASURED, never PASS.
+branding: { icon: check-circle, color: green }
+inputs:
+  base:
+    description: Base ref to diff against (default for pull requests is the PR base branch). Empty = scan the whole repository.
+    required: false
+    default: ''
+  fail-on:
+    description: Lowest severity that fails the job (high | medium | low | none).
+    required: false
+    default: high
+  licence:
+    description: Fini Proof licence key (pass a secret, e.g. secrets.FINI_PROOF_LICENCE). Empty = trial mode.
+    required: false
+    default: ''
+  upload-sarif:
+    description: Upload SARIF to GitHub code scanning (needs security-events write).
+    required: false
+    default: 'true'
+outputs:
+  verdict:
+    description: PASS, FAIL or NOT_MEASURED
+    value: ${{ steps.check.outputs.verdict }}
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with: { node-version: '20' }
+    - id: check
+      shell: bash
+      env:
+        FINI_PROOF_LICENCE: ${{ inputs.licence }}
+        FINI_PROOF_HOME: ${{ runner.temp }}/fini-proof-home
+        INPUT_BASE: ${{ inputs.base || (github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || '') }}
+        INPUT_FAIL_ON: ${{ inputs.fail-on }}
+      run: |
+        set -euo pipefail
+        args=(check --fail-on "$INPUT_FAIL_ON" --sarif-out fini-proof.sarif --json-out fini-proof-evidence.json)
+        if [ -n "$INPUT_BASE" ]; then args+=(--base "$INPUT_BASE"); fi
+        rc=0
+        node "${{ github.action_path }}/bin/fini-proof.mjs" "${args[@]}" || rc=$?
+        case "$rc" in 0) v=PASS;; 1) v=FAIL;; *) v=NOT_MEASURED;; esac
+        echo "verdict=$v" >> "$GITHUB_OUTPUT"
+        echo "rc=$rc" >> "$GITHUB_OUTPUT"
+    - if: always() && inputs.upload-sarif == 'true' && hashFiles('fini-proof.sarif') != ''
+      uses: github/codeql-action/upload-sarif@v3
+      with: { sarif_file: fini-proof.sarif, category: fini-proof }
+    - if: always()
+      uses: actions/upload-artifact@v4
+      with: { name: fini-proof-evidence, path: fini-proof-evidence.json, if-no-files-found: ignore }
+    - shell: bash
+      run: exit ${{ steps.check.outputs.rc }}

package/bin/fini-proof.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Entry point. Always runs main() (no argv[1] self-compare — that guard shape is exactly what the
+// fail-open engine reports; a bin that only runs main is the safe form through npx symlinks).
+// main() returns an exit code, or a promise of one for the long-running commands (mcp, hook).
+import { main } from '../src/cli.mjs'
+Promise.resolve(main(process.argv.slice(2))).then((rc) => { process.exitCode = rc }, (e) => { process.stderr.write(`fini-proof: ${e.stack || e.message}\n`); process.exitCode = 2 })

package/ci/Jenkinsfile

@@ -0,0 +1,13 @@
+// Jenkinsfile snippet — add this stage. FINI_PROOF_LICENCE is a Jenkins "secret text" credential.
+stage('Fini Proof') {
+  environment {
+    FINI_PROOF_LICENCE = credentials('fini-proof-licence')
+    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'
+  }
+  post {
+    always { archiveArtifacts artifacts: 'fini-proof.sarif, fini-proof-evidence.json', allowEmptyArchive: true }
+  }
+}

package/ci/Jenkinsfile.daily

@@ -0,0 +1,23 @@
+// Jenkinsfile — daily run of the whole default branch, evidence sent to your Finipe Developer workspace (--upload).
+// Use it as the pipeline script of a job on the default branch. Credentials ("secret text"): fini-proof-api-key and
+// fini-proof-licence. Only the evidence file is sent (rule ids, file:line, hashes) — never source code.
+pipeline {
+  agent any
+  triggers { cron('H 2 * * *') }   // daily; H spreads the start minute
+  environment {
+    FINI_PROOF_API_KEY = credentials('fini-proof-api-key')
+    FINI_PROOF_LICENCE = credentials('fini-proof-licence')
+    FINI_PROOF_HOME = "${env.WORKSPACE}/.fini-proof-home"
+  }
+  stages {
+    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'
+      }
+      post {
+        always { archiveArtifacts artifacts: 'fini-proof.sarif, fini-proof-evidence.json', allowEmptyArchive: true }
+      }
+    }
+  }
+}

package/ci/bitbucket-pipelines-daily.yml

@@ -0,0 +1,15 @@
+# Bitbucket Pipelines — daily run of the whole default branch, evidence sent to your Finipe Developer workspace.
+# Add this custom pipeline, then Repository settings → Schedules → New schedule: branch = the default branch,
+# pipeline = custom: fini-proof-daily, interval = Daily. Set FINI_PROOF_API_KEY and FINI_PROOF_LICENCE as secured
+# repository variables. Only the evidence file is sent (rule ids, file:line, hashes) — never source code.
+pipelines:
+  custom:
+    fini-proof-daily:
+      - step:
+          name: Fini Proof (daily)
+          image: node:20
+          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
+          artifacts: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/bitbucket-pipelines.yml

@@ -0,0 +1,12 @@
+# Bitbucket Pipelines — add this step. Set FINI_PROOF_LICENCE as a secured repository variable.
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: Fini Proof
+          image: node:20
+          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
+          artifacts: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/github-actions-daily.yml

@@ -0,0 +1,31 @@
+# .github/workflows/fini-proof-daily.yml — once a day, the whole default branch is checked and the evidence is sent to
+# your Finipe Developer workspace (`--upload`), where proof state (PROVEN / FAILED / NOT_MEASURED / STALE / ADVISORY)
+# and the daily digest are kept. Only the evidence file is sent (rule ids, file:line, hashes) — never source code.
+# GitHub runs `schedule` on the default branch. Secrets: FINI_PROOF_API_KEY (Developers → Fini Proof → API keys) and
+# FINI_PROOF_LICENCE. The pull-request check stays in github-actions-example.yml.
+name: fini-proof-daily
+on:
+  schedule:
+    - cron: '30 2 * * *'   # daily 02:30 UTC (08:00 IST)
+  workflow_dispatch: {}
+permissions: { contents: read, security-events: write }
+jobs:
+  proof:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - name: Fini Proof — default branch, daily
+        env:
+          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
+      - if: always() && hashFiles('fini-proof.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: fini-proof.sarif, category: fini-proof-daily }
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with: { name: fini-proof-daily-evidence, path: fini-proof-evidence.json, if-no-files-found: ignore }

package/ci/github-actions-example.yml

@@ -0,0 +1,14 @@
+# .github/workflows/fini-proof.yml — one step. fetch-depth: 0 so --base can find the merge-base
+# (a shallow clone gives NOT_MEASURED, never a guessed PASS).
+name: fini-proof
+on: [pull_request, push]
+permissions: { contents: read, security-events: write }
+jobs:
+  proof:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: finipe/fini-proof@v0.3.0
+        with:
+          licence: ${{ secrets.FINI_PROOF_LICENCE }}

package/ci/gitlab-ci-daily.yml

@@ -0,0 +1,17 @@
+# GitLab CI — daily run of the whole default branch, evidence sent to your Finipe Developer workspace (`--upload`).
+# Create the schedule once: CI/CD → Schedules → New schedule, interval "30 2 * * *" (daily), target branch = the
+# default branch. Set FINI_PROOF_API_KEY and FINI_PROOF_LICENCE as masked CI/CD variables. Only the evidence file is
+# sent (rule ids, file:line, hashes) — never source code. The merge-request job stays in gitlab-ci.yml.
+fini-proof-daily:
+  image: node:20
+  stage: test
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  variables:
+    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
+  artifacts:
+    when: always
+    paths: [fini-proof.sarif, fini-proof-evidence.json]

package/ci/gitlab-ci.yml

@@ -0,0 +1,13 @@
+# GitLab CI — include this file, or paste the job. Evidence JSON is kept as an artifact; SAST report via SARIF
+# is attached for download (GitLab code-quality import of SARIF is not native).
+fini-proof:
+  image: node:20
+  stage: test
+  variables:
+    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
+  artifacts:
+    when: always
+    paths: [fini-proof.sarif, fini-proof-evidence.json]

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "fini-proof",
+  "version": "0.3.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": {
+    "fini-proof": "bin/fini-proof.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action.yml",
+    "ci",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs integrations/*/*.test.mjs",
+    "demo": "node scripts/demo.mjs",
+    "selfcheck": "node bin/fini-proof.mjs check",
+    "admin": "node scripts/fini-proof-admin.mjs",
+    "smoke:github": "bash scripts/smoke-github.sh",
+    "tokens:sync": "node scripts/sync-finipe-tokens.mjs",
+    "tokens:check": "node scripts/sync-finipe-tokens.mjs --check"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Finipe Ventures",
+  "dependencies": {}
+}