@optitransfer/proofline 0.0.0-stage → 0.2.0-next.0

package/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md: the loop a coding agent follows in a repository that uses proofline (copy this file into that repository)
+
+Proofline decides whether your work is done. Your report is a claim; Proofline re-runs every check itself.
+
+## Loop (every task, no exceptions)
+
+1. `proofline next` (MCP: `task_next`). Work only on the task it returns. Read the whole brief. If the contract has owners, add `--owner <your name>` (MCP: `owner`) so you only get your tasks and unowned ones.
+2. Write the failing test(s) first. Run them and keep the failing output.
+3. Implement the root-cause fix **on the default path** (wired in, default config). Code that is built but unreachable does not count.
+4. `proofline verify <TASK>` (MCP: `verify`). Read the corrective instruction. Fix and repeat until `DECISION: PASS`.
+   Max 3 corrective cycles; then report `blocked` with root cause (file:line), what you tried, what you need.
+5. Commit (one task per commit) and push to the contract's remote and branch (`defaults.remote`, default `origin`; `defaults.branch`, default `main`) with hooks on. The pre-push hook re-gates the task. You may end the commit message with the trailer `Proofline-Base: <sha>` (the base the brief names), so a fresh clone gates against the same base.
+6. `proofline gate <TASK> --claims "<report line>"` (MCP: `gate` with `claims`). Paste the report. In a clone where `next` did not run, add `--base <sha>` (MCP: `base`); without a base the gate is BLOCKED, never PASS.
+7. Back to step 1. The closing text of each gate says which step is next: push (PASS, not pushed yet), report with claims (PASS on the pushed HEAD), or `proofline next` (claims accepted).
+
+## Report line (exact)
+
+`TASK-ID | done/partial/not done/blocked | <commit> | <test names> | <metric=value vs target> | <what is missing>`
+
+Proofline rejects: "done" without a commit, test names or measured numbers; numbers that differ from its own measurement (>15%); commits not on the contract's push branch; tests that don't exist; hedged or deferred wording ("should work", "likely", "follow-up", "later", "out of scope").
+
+## Never
+
+- Skip/only/todo tests, raise timeouts, delete tests or assertions, edit fixtures to pass (unless the fixture is the proven root cause, with proof).
+- Lower a target, cap or test size, or touch thresholds/commands/criteria in `proofline.json` (detected; BLOCKED until the owner approves).
+- `--no-verify`, bypass env vars, skip flags. There is no bypass. If CI runs `proofline gate --ci`, it re-runs the gate.
+- Say "done" for anything that is not PASS on the pushed HEAD.
+- Defer. Only the owner approves a deferral.
+
+## Stop rules
+
+If a metric misses its threshold: STOP. Report the measured number, the per-stage trace and file:line. Do not start the next task.

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable project changes are recorded here. Dates use ISO 8601 (`YYYY-MM-DD`).
+
+## [Unreleased]
+
+### Fixed
+- `contract create` keeps one level of `scope.allow` when the task file writes the scope as the contract does, `{ "allow": [...] }`, and `contract validate` refuses a scope that is not a list of patterns, so `next` cannot crash on it (#19).
+- A failed `command` criterion's evidence names the failed tests. `out_tail` keeps the last 1,200 characters, where node's summary of repeated failures with their stacks held the last two or three names. The new `failing` field lists the failed test names found anywhere in the output (TAP `not ok` lines, the spec reporter's `✖ <name> (<ms>ms)` lines and the `failing tests:` section), without todos, skips or repeats, in order of first appearance and at most 100, with `failing_total` when there were more. The FAIL detail names the first 10, a flaky result keeps both runs' lists, and the gate report lists the names under Failing tests (#13).
+- The forbidden scan no longer reads `proofline.json` or `.proofline/`: the commit that adds or amends the contract failed on its own deny-list. Contract changes stay covered by the weakening check, and the gate report says whether the contract was added, changed or unchanged vs the base (#4).
+- `init` no longer replaces an existing `pre-commit` or `pre-push` hook: it keeps it as `<hook>.proofline-prev`, and the installed hook runs it first (same arguments and stdin) and stops on its failure. A second `init` changes nothing (#1).
+- The corrective text for an unpushed task and the brief name the push target from the criterion's `remote`/`branch`, else `defaults.remote`/`defaults.branch`, instead of always `origin` (#8).
+- A PASS no longer always says "Commit, push to main ... Then call task_next". On a HEAD already on the push target it says the task is verified on the pushed HEAD and gives the `gate` command with claims (and `--base` when one was passed); after accepted claims it points to `proofline next`; only an unpushed PASS says to push, to the configured remote and branch (#9).
+- A verify or gate with no pinned base, where the default base is HEAD (a fresh clone after the push), is BLOCKED instead of passing every diff check on an empty diff (#5).
+
+### Added
+- `@optitransfer/proofline@0.2.0-next.0` is the public package on the `next` dist-tag. `private` is false, the test script runs `node --test test/*.test.mjs`, and `files` lists what this revision ships. The sixty-second start installs that package and calls `npx proofline`. The package description, keywords, homepage, repository, bugs and author match the GitHub repository page.
+- The pre-commit hook accepts a contract change only when an approval marker is present. The marker is a file named with the sha256 of the staged `proofline.json` bytes, in the directory set by `init --approvals` and stored in `.proofline/config.json` (never committed). The refusal prints the weakenings, the sha256 and the marker path. A marker for other bytes does not count, what else is staged does not matter, and with no directory configured every contract change is refused. `verify` and `gate` use the same marker for the current `proofline.json` bytes: a regular file approves the weakenings, the report names the marker path, and the decision is not blocked.
+- Opt-in result reuse: with `defaults.reuse_results` (validated, default `false`), a `command` or `metric` PASS on a clean tree is recorded in the evidence log and reused by a later `verify` or `gate` on the same HEAD, so `verify`, `gate` and the pre-push hook run the full suite once per commit. The key is the verifier, HEAD, `process.version` and the env vars the command names; only a PASS is stored; `defaults.reuse_max_age_h` (default 24) bounds its age; a metric is reused only within `max_load_per_cpu`. A result is reused only from an evidence entry still in an intact chain with the hash the cache file stored. Reused criteria say `reused from <time> (evidence entry <n>)` and are listed apart in the gate report and its evidence entry. `--fresh` on `verify` and `gate` (MCP: `fresh`) runs every check. Turning reuse on or off is not a weakening (#12).
+- Metric evidence and report lines record the load before the run, the CPU count and the `node --version` the bench command resolves. Optional `defaults.max_load_per_cpu`: a metric run on a busier machine is BLOCKED (machine busy, with the numbers) and the bench is not run; raising or removing the limit is a weakening (#7).
+- `defaults.remote` in the contract (validated as a string), used by `pushed`, by claim reconciliation and by the default base, which is now `defaults.base`, else `<remote>/<branch>`. A repository whose remote is not `origin` no longer gets a BLOCKED gate on an unresolved base, or a claim check that silently checks nothing (#6).
+- Optional `owner` on a task and `defaults.owners` in the contract (validated); `--owner <name>` on `next`, `status` and `brief` (MCP: `task_next` and `status`). `next --owner` hands out that owner's tasks and unowned ones, never another owner's (#2).
+- `--base <rev>` on `verify` and `gate` (MCP: `base`), an optional `Proofline-Base:` commit trailer, and the base source (`--base`, contract, pinned at start, commit trailer, default) in every report. The `next` brief prints the pinned base (#5).
+- `brief <TASK> --base <rev>`: the brief ends with the base `verify` and `gate` will use, its source, and the reason it would be BLOCKED, if any (#5).
+
+## [0.1.0] - 2026-10-14
+
+### Added
+- Executable MVP: CLI (`init`, `contract`, `next`, `brief`, `verify`, `gate`, `report`, `status`, `evidence`, `hook`, `mcp`).
+- Contract schema `proofline/1` with ten deterministic verifier types, phase + dependency task graph, contract-weakening detection.
+- Hash-chained append-only evidence log; red-green replay in a git worktree; flaky re-run policy; baseline regression check.
+- Claim reconciliation of `TASK | status | commit | tests | numbers | missing` lines; corrective prompts per failed criterion.
+- MCP stdio server, git pre-commit/pre-push hooks with no bypass variable, GitHub Actions self-gate.
+- AGENTS.md agent loop, FAIL to PASS demo.
+- Initial product scope, requirements, architecture, lifecycle, evidence model, security posture, verification strategy, delivery pipeline, roadmap, and dependency map.
+- Initial Mermaid diagrams, ADRs, task-contract example, and project templates.

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+## Current phase
+
+The repository holds the CLI, the MCP server, the engine and their tests. Changes to scope, requirements, architecture, security, or acceptance criteria should be explicit and traceable.
+
+## Change process
+
+1. State the problem and the requirement(s) affected.
+2. Record assumptions and exclusions.
+3. Update the relevant specification and, if needed, an ADR.
+4. Add or update conformance cases for behaviour changes.
+5. Update the roadmap and changelog when status or commitments change.
+6. Do not label a capability implemented until code and repeatable evidence exist.
+
+## Design review checklist
+
+- Does the change preserve the separation between agent claims and independent evidence?
+- Can it be used without any optional integration (context store, agent SDK, network)?
+- Does it distinguish pass, fail, skipped, not run, and inconclusive?
+- Does it introduce unbounded retries, hidden side effects, or excessive interruption?
+- Are permission boundaries and secret handling explicit?
+- Can the outcome be reproduced from the report and captured revision?
+
+## Sign-off
+
+Each commit needs a Developer Certificate of Origin sign-off (https://developercertificate.org/). Put this line in the commit message, with the name and email of the commit:
+
+Signed-off-by: Name <email>

package/LICENSE

@@ -0,0 +1,154 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control
+   with that entity. For the purposes of this definition, "control" means
+   (i) the power, direct or indirect, to cause the direction or management
+   of such entity, whether by contract or otherwise, or (ii) ownership of
+   fifty percent (50%) or more of the outstanding shares, or (iii)
+   beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation source,
+   and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but not
+   limited to compiled object code, generated documentation, and
+   conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright
+   notice that is included in or attached to the work (an example is
+   provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including the
+   original version of the Work and any modifications or additions to that
+   Work or Derivative Works thereof, that is intentionally submitted to
+   Licensor for inclusion in the Work by the copyright owner or by an
+   individual or Legal Entity authorized to submit on behalf of the
+   copyright owner. For the purposes of this definition, "submitted" means
+   any form of electronic, verbal, or written communication sent to the
+   Licensor or its representatives, including communication on electronic
+   mailing lists, source code control systems, and issue tracking systems
+   that are managed by, or on behalf of, the Licensor for the purpose of
+   discussing and improving the Work, but excluding communication that is
+   conspicuously marked or otherwise designated in writing by the copyright
+   owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license
+   to reproduce, prepare Derivative Works of, publicly display, publicly
+   perform, sublicense, and distribute the Work and such Derivative Works
+   in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+   this section) patent license to make, have made, use, offer to sell,
+   sell, import, and otherwise transfer the Work, where such license applies
+   only to those patent claims licensable by such Contributor that are
+   necessarily infringed by their Contribution(s) alone or by combination
+   of their Contribution(s) with the Work to which such Contribution(s) was
+   submitted. If You institute patent litigation against any entity
+   (including a cross-claim or counterclaim in a lawsuit) alleging that the
+   Work or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses granted
+   to You under this License for that Work shall terminate as of the date
+   such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications,
+   and in Source or Object form, provided that You meet the following
+   conditions:
+   (a) You must give any other recipients of the Work or Derivative Works
+       a copy of this License; and
+   (b) You must cause any modified files to carry prominent notices stating
+       that You changed the files; and
+   (c) You must retain, in the Source form of any Derivative Works that
+       You distribute, all copyright, patent, trademark, and attribution
+       notices from the Source form of the Work, excluding notices that do
+       not pertain to any part of the Derivative Works; and
+   (d) If the Work includes a "NOTICE" text file as part of its distribution,
+       then any Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained within such NOTICE file,
+       excluding those notices that do not pertain to any part of the
+       Derivative Works.
+   You may add Your own copyright statement to Your modifications and may
+   provide additional or different license terms and conditions for use,
+   reproduction, or distribution of Your modifications, or for any such
+   Derivative Works as a whole, provided Your use, reproduction, and
+   distribution of the Work otherwise complies with the conditions stated
+   in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work by You
+   to the Licensor shall be under the terms and conditions of this License,
+   without any additional terms or conditions. Notwithstanding the above,
+   nothing herein shall supersede or modify the terms of any separate
+   license agreement you may have executed with Licensor regarding such
+   Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to
+   in writing, Licensor provides the Work (and each Contributor provides
+   its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+   OF ANY KIND, either express or implied, including, without limitation,
+   any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
+   or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+   determining the appropriateness of using or redistributing the Work and
+   assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether
+   in tort (including negligence), contract, or otherwise, unless required
+   by applicable law or agreed to in writing, shall any Contributor be liable
+   to You for damages, including any direct, indirect, special, incidental,
+   or consequential damages of any character arising as a result of this
+   License or out of the use or inability to use the Work (including but not
+   limited to damages for loss of goodwill, work stoppage, computer failure
+   or malfunction, or any and all other commercial damages or losses), even
+   if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+   or Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   and/or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You
+   agree to indemnify, defend, and hold each Contributor harmless for any
+   liability incurred by, or claims asserted against, such Contributor by
+   reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,10 @@
+proofline
+Copyright 2026 Ryan Gillespie / Optitransfer
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+"proofline" is a trademark of Ryan Gillespie / Optitransfer. The Apache License 2.0 (Section 6)
+grants no trademark rights: any fork or a derived product uses its own name, and may say that it
+is derived from proofline.
+Contributions are accepted under the Apache License 2.0 with a Developer Certificate of Origin
+sign-off on each commit (CONTRIBUTING.md); there is no contributor licence agreement.

package/PATENTS-NONASSERT.md

@@ -0,0 +1 @@
+Apache-2.0 section 3 grants the patent licence for contributions to this project. A fuller non-assert follows counsel review, and the entity signs that covenant.

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# Proofline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The agent says done. Proofline verifies and validates the work against a V&V contract, to assure agent performance.**
+
+A coding agent reports that a task is finished. Proofline does not take the report: it holds the definition of done as a contract a machine can check, hands the agent one task at a time, re-runs every check itself when the agent reports, and lets a commit through only when the evidence says PASS. The agent gets a corrective prompt that names the file and the line to fix next, never a verdict it can argue with. Zero dependencies, Node 22+, Apache-2.0.
+
+```mermaid
+flowchart LR
+    C["proofline.json<br/>tasks, criteria, scope,<br/>forbidden actions"] --> N["proofline next<br/>one task, its brief,<br/>the base revision pinned"]
+    N --> A["the agent<br/>failing test first,<br/>then the fix"]
+    A --> H1{"pre-commit hook<br/>forbidden actions,<br/>contract change without a marker"}
+    H1 -- "refused" --> A
+    H1 -- "clean" --> V["proofline verify<br/>every criterion re-run<br/>from the base revision"]
+    V -- "FAIL or BLOCKED:<br/>corrective prompt,<br/>file and line" --> A
+    V -- "PASS" --> G["proofline gate --claims<br/>the agent's report line<br/>against the evidence"]
+    G -- "a claim the evidence<br/>does not support" --> A
+    G -- "PASS, report written" --> H2{"pre-push hook<br/>does this HEAD gate PASS?"}
+    H2 -- "no" --> A
+    H2 -- "yes" --> M[("main")]
+    M --> N
+    O["owner marker<br/>sha256 of the approved<br/>proofline.json"] -. "approves a<br/>contract change" .-> H1
+```
+
+## Sixty seconds
+
+In the repository the agent works on:
+
+```bash
+npm install --save-dev @optitransfer/proofline@next && npx proofline init --approvals ~/.proofline/approved && cp node_modules/@optitransfer/proofline/AGENTS.md .
+```
+
+```text
+initialised /path/to/your-repo
+  proofline.json
+  .proofline/config.json
+  .gitignore
+  hooks/pre-commit
+  hooks/pre-push
+```
+
+That writes the contract skeleton, the local evidence log, the two git hooks, the directory where you (the owner) approve contract changes, and the loop the agent follows in `AGENTS.md`. Add one task and tell the agent to start:
+
+```bash
+cat > task.json <<'JSON'
+{ "id": "TASK-1", "title": "Reject an empty body", "phase": "implement",
+  "scope": { "allow": ["src/**", "test/**", "CHANGELOG.md"] },
+  "criteria": [
+    { "id": "TASK-1-AC01", "mandatory": true, "statement": "an empty body is refused",
+      "verifier": { "type": "test_red_green", "test_file": "test/empty_body.test.mjs", "cmd": "node --test {test}" } },
+    { "id": "TASK-1-AC02", "mandatory": true, "statement": "suite green",
+      "verifier": { "type": "command", "cmd": "npm test" } },
+    { "id": "TASK-1-AC03", "mandatory": true, "statement": "pushed", "verifier": { "type": "pushed" } } ] }
+JSON
+npx proofline contract create --from task.json     # TASK-1: valid
+npx proofline next                                   # the agent's first command: the brief, with the base pinned
+```
+
+When the agent reports, Proofline checks. Before any work this is what it says, and the agent is told what to do next:
+
+```text
+$ npx proofline verify TASK-1
+== TASK-1: FAIL
+  base: 0a88576db5567f08c9f1cd9481c633001036d8e1 = 0a88576d (pinned at start)
+  FAIL  TASK-1-AC01 [test_red_green] test file test/empty_body.test.mjs not found
+  PASS  TASK-1-AC02 [command] exit 0 in 393 ms
+  FAIL  TASK-1-AC03 [pushed] working tree not clean (3 paths); work held locally
+  report: .proofline/reports/TASK-1-latest.md
+
+PROOFLINE CORRECTIVE INSTRUCTION for TASK-1 (Reject an empty body): gate FAIL
+1. TASK-1-AC01 [test_red_green] FAIL: an empty body is refused
+   Next step: The test test/empty_body.test.mjs must FAIL on the base and PASS now.
+2. TASK-1-AC03 [pushed] FAIL: pushed
+   Next step: Commit everything and `git push origin main` (hooks on; never --no-verify).
+DECISION: FAIL
+```
+
+Exit codes: `0` PASS, `1` FAIL, `2` BLOCKED, `3` usage. Every command takes `--json`. The published package is `@optitransfer/proofline` at `0.2.0-next.0` on the `next` dist-tag: `npx @optitransfer/proofline@next`.
+
+## Why
+
+An agent's report is a claim. Left to itself it says "done" for a test it skipped, a timeout it raised, a target it lowered, a commit it never pushed, or a number it did not measure. Reviewing every claim by hand does not scale past one agent, and asking a second model whether the first one is right only adds a second opinion.
+
+Proofline replaces the opinion with a contract and a re-run. The contract is yours: it names each task, the files it may touch, and the checks that prove it, and it cannot be weakened by the agent, because a changed criterion, threshold or forbidden rule is refused at commit time unless a marker with the hash of the new contract sits in the directory only you write to. The checks are the kind a machine can settle: a test that fails on the base revision and passes now, a command and its exit code, a metric against its target, changed files inside the allowed scope, a HEAD that is on the contract's branch. Every result is appended to a hash-chained evidence log, so a report can be checked later against what actually ran.
+
+## What it checks
+
+Every criterion names a verifier. Each one is deterministic: no model reads the diff, no opinion decides.
+
+| Type | Passes only when |
+|---|---|
+| `command` | exit code matches; no hung/cancelled tests; optional `max_skipped`, `min_tests` (catches deleted tests). A fail-then-pass is **flaky**, not a pass. Test counts and failing-test names are parsed from the Node test runner's output (TAP or spec reporter); for other runners use `command` criteria without `min_tests` |
+| `test_red_green` | the test exists, **fails** on the base revision (replayed in a git worktree) and **passes** now; named test actually executed |
+| `test_exists` | test file (and name) present |
+| `metric` | bench command's JSON (`key` dotted path) meets `op value`; also fails on >20% regression vs `baseline.metrics`. One bench run feeds all its metrics. Missing rig → BLOCKED. The evidence and report line record the 1-minute load, the CPU count and the `node --version` the command resolves; with `defaults.max_load_per_cpu` set, a load per CPU above it before the run is BLOCKED (machine busy), never PASS or FAIL, and raising or removing that limit is a contract weakening |
+| `grep` | pattern present/absent (e.g. the new code path is the default config) |
+| `wiring` | the symbol is **called** in a file reachable by static imports from the default entry (catches "built but not wired in") |
+| `scope` | every changed file matches the allowlist |
+| `docs` | generator leaves no diff in the given paths |
+| `pushed` | tree clean and HEAD == `<remote>/<branch>` (the criterion's `remote`/`branch`, else `defaults.remote`/`defaults.branch`, else `origin`/`main`) |
+| `file_exists` | path exists (e.g. the bench rig is committed) |
+
+Always on: forbidden-action scan of the diff (skip/only/todo, raised timeouts, net assertion loss, deleted tests, `--no-verify`, bypass env vars, lowered protected caps; `proofline.json` and `.proofline/` are left out, because the contract declares the deny-list and would match it), contract-weakening check vs the base revision (loosened thresholds, removed criteria, changed commands → BLOCKED), hash-chained evidence log integrity, claim reconciliation.
+
+
+## How it decides
+
+### Owners
+
+Two or more builders can share one contract. A task may carry an `owner`, and `defaults.owners` may list the names (`contract validate` then refuses an owner outside the list). `next --owner <name>` (MCP: `task_next` with `owner`) hands out only that owner's tasks and unowned ones, never another owner's; the phase gate applies to that lane, and `depends_on` still waits on any owner's task. `status --owner <name>` and `brief <TASK> --owner <name>` take the same filter, and `brief` refuses another owner's task. Without `--owner`, nothing changes.
+
+
+### Git hooks
+
+`init` installs `pre-commit` (forbidden actions and contract weakening vs HEAD) and `pre-push` (the active task must gate PASS). If the repository already has one of these hooks and it is not proofline's, `init` keeps it as `<hook>.proofline-prev` and says so. The installed hook runs it first, with the same arguments and stdin; if it fails, its exit code stands and the gate does not run. Running `init` again changes nothing. If both `<hook>` and `<hook>.proofline-prev` exist and neither is proofline's, `init` stops rather than lose one.
+
+A contract change is refused unless an approval marker is present. `proofline init --approvals <dir>` (re-runnable) stores that directory in `.proofline/config.json`, which is never committed. The marker is a file in that directory named with the sha256 of the staged `proofline.json` bytes. The refusal prints the weakenings, the sha256 and the marker path. A marker named for any other bytes does not count, and what else the commit stages makes no difference. With no directory configured, every contract change is refused. There is no bypass.
+
+`verify` and `gate` read the same marker for the current `proofline.json` bytes. When that marker is a regular file, the weakenings are an approved contract change: the report names the marker path, and the decision is not blocked. A missing marker, a marker for other bytes, or a symlink still blocks.
+
+
+### Base revision
+
+Every diff check (forbidden scan, `scope`, `test_red_green`, contract weakening) compares the base revision with the working tree. The base is taken from, first match wins:
+
+1. `--base <rev>` on `verify` or `gate` (MCP: `base`);
+2. the task's own `base` in the contract;
+3. the base pinned when the task started (`proofline next` records it in the local `.proofline/` log, and the brief prints it);
+4. a `Proofline-Base: <sha>` trailer on the HEAD commit (optional; it must name an ancestor of HEAD, or the gate is BLOCKED);
+5. the default: `defaults.base`, else `<defaults.remote>/<defaults.branch>` (`origin/main` when neither is set).
+
+A repository whose remote is not called `origin` sets `defaults.remote` (for example `"github"`) and leaves `defaults.base` out; `pushed`, claim reconciliation and the default base then use that remote.
+
+Every report says which one it used, and `brief <TASK> [--base <rev>]` says which base `verify` and `gate` will use and whether it would block. A fresh clone has no log, and after the push the default base is HEAD, so the diff is empty and every diff check would pass on nothing. In that case the gate is BLOCKED, never PASS, and the corrective line asks for `--base <rev>` (for one commit, its parent) or `proofline next`. The CI workflow passes the previous tip of the pushed branch as `--base`.
+
+
+### Reusing results (verify, then gate)
+
+`verify` and `gate` run every check each time. When a task's slowest check is the full suite, `verify`, `gate` and the pre-push hook on the same commit run it two or three times with nothing changed. A contract can opt in to reuse:
+
+```json
+"defaults": { "reuse_results": true, "reuse_max_age_h": 24 }
+```
+
+- `reuse_results` (`true`/`false`, default `false`): with it off, or left out, every check runs every time, as before. Turning it on or off is not a contract weakening.
+- Only `command` and `metric` results are reused. `test_red_green`, `scope`, `wiring`, `grep`, `docs`, `pushed`, the forbidden scan and the weakening check always run: they are cheap, or they depend on the base.
+- Only a PASS is stored. A FAIL, a flaky result, a busy-machine block or an error runs again every time.
+- A PASS is reused only on the same HEAD with a clean tree: `git status` shows nothing outside `.proofline/`, untracked files included. An uncommitted edit never reuses a result, and a check run on a dirty tree is not stored.
+- The key is the criterion's verifier object (canonical JSON), the HEAD sha, `process.version` and the values of the env vars the command names (`$VAR`, `${VAR}`; `{VAR}` in a metric's `output_file`); for a metric also its baseline and the regression tolerance. Change any of them and the check runs again. Gitignored files, env vars the command does not name and tools outside the repo are not in the key: a check that depends on them needs `--fresh`.
+- `reuse_max_age_h` (a positive number, default 24): an older PASS runs again.
+- A metric PASS is reused only if the load per CPU it recorded is within `defaults.max_load_per_cpu`, when that is set. Its measured value is reused with it, so claims are checked against it.
+- A fresh PASS is recorded in the evidence log (a `result` entry) and `.proofline/cache/<sha256 of key>.json` points at that entry with its hash, time, status, detail and evidence (exit code, test counts, duration). A result is reused only from that entry, and only while it is in an intact chain with the same hash; an edited or truncated log, or a cache file that names another hash, means the check runs again.
+- Every reused criterion says `reused from <time> (evidence entry <n>)` in its report line, the gate report lists reused criteria under **Reused results** (not run again in that gate), and the gate's evidence entry carries the same lines.
+- `--fresh` on `verify` and `gate` (MCP: `fresh: true`) ignores stored results and runs every check; a PASS it gets replaces the stored one.
+
+Demo (claimed done with no evidence, FAIL, then real work, PASS): `npm run demo`.
+
+
+## For agents
+
+Read [AGENTS.md](AGENTS.md): the loop, the exact report line, what is never allowed and the stop rules. MCP config: [examples/mcp-config.json](examples/mcp-config.json). Tools: `contract_create`, `task_next`, `evidence_record`, `verify`, `gate`, `report`, `status`.
+
+## Repository layout
+
+```text
+proofline/
+├── bin/proofline.mjs        the command: init, contract, next, brief, verify, gate, report, status, evidence, hook, mcp
+├── src/contract.mjs         contract schema, validation, task graph, weakening detection
+├── src/checks.mjs           the verifiers
+├── src/forbidden.mjs        the forbidden-action scan
+├── src/claims.mjs           report-line parser and claim reconciliation
+├── src/evidence.mjs         the append-only, hash-chained evidence log (.proofline/evidence.jsonl)
+├── src/engine.mjs           verify, the corrective prompt, gate and its report, next and brief, phases
+├── src/mcp.mjs              the MCP server on stdio
+├── src/index.mjs            the API, init, hooks
+├── examples/demo/           the FAIL to PASS demo (npm run demo)
+├── examples/demo-contract/  an example contract with one task; the self-gate validates it
+├── docs/                    the source design: scope, requirements, architecture, lifecycle, evidence, roadmap
+├── plans/                   definition of done, risk register, pilot plan
+└── proofline.json           Proofline's own contract: the repository gates itself
+```
+
+## Documentation
+
+[docs/00-index.md](docs/00-index.md) lists the design documents. [CONTRIBUTING.md](CONTRIBUTING.md) has the sign-off rule; [SECURITY.md](SECURITY.md) says how to report a vulnerability.
+
+## Known limits
+
+See `KNOWN_LIMITS` in `src/engine.mjs`; they are printed in every report. In short: same-machine agents can edit local state (tampering is detected, and CI re-verifies, but protect `proofline.json` with branch protection/CODEOWNERS); `--no-verify` can skip local hooks (CI catches it); static wiring/forbidden checks are heuristics; contracts are JSON only; with `reuse_results` on, a reused PASS is keyed on HEAD, node and the env vars the command names, not on gitignored files or tools outside the repo.
+
+
+## License
+
+Apache-2.0 (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). Contributions are accepted under the same licence with a Developer Certificate of Origin sign-off on each commit.

package/bin/proofline.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Proofline CLI. Exit codes: 0 PASS/ok, 1 FAIL, 2 BLOCKED, 3 usage error.
+import fs from 'node:fs';
+import * as P from '../src/index.mjs';
+import { verifyChain, readLog } from '../src/evidence.mjs';
+
+const argv = process.argv.slice(2);
+const flags = {}; const pos = [];
+const SWITCHES = ['fresh']; // never take a value: `verify --fresh T` keeps T as the task
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) flags[k] = v; else if (!SWITCHES.includes(k) && argv[i + 1] && !argv[i + 1].startsWith('--')) flags[k] = argv[++i]; else flags[k] = true; }
+  else pos.push(a);
+}
+const root = flags.root ? flags.root : P.findRoot();
+const json = !!flags.json;
+const print = (obj, text) => { process.stdout.write((json || text === undefined ? JSON.stringify(obj, null, 2) : text) + '\n'); };
+const code = (d) => (d === 'PASS' ? 0 : d === 'BLOCKED' ? 2 : 1);
+const owner = () => { if (flags.owner === true) throw new Error('--owner needs a name'); return flags.owner; };
+const base = () => { if (flags.base === true) throw new Error('--base needs a revision'); return flags.base; };
+const claims = () => flags['claims-file'] ? fs.readFileSync(flags['claims-file'], 'utf8') : flags.claims === true ? fs.readFileSync(0, 'utf8') : flags.claims;
+
+const HELP = `proofline — independent V&V and delivery controller
+  init [--no-hooks] [--approvals <dir>] create proofline.json, .proofline/, install git hooks;
+                                        --approvals sets the directory of owner markers (re-runnable)
+  contract create --from spec.json      add a task contract (or --id --title [--phase] [--owner n] [--depends a,b] [--scope g1,g2])
+  contract validate | show
+  next [--owner <name>]                 the single next task with its full brief (marks it active);
+                                        --owner: only that owner's tasks and unowned ones
+  brief <TASK> [--owner <name>] [--base <rev>]  brief for a task, with the base verify will use
+                                        (refuses another owner's task)
+  verify <TASK> [--claims "line"] [--base <rev>] [--fresh]   run every check independently; prints corrective prompt
+  gate <TASK>|--all [--claims ...] [--base <rev>] [--fresh]  release decision PASS/FAIL/BLOCKED + report (.proofline/reports)
+                                        --base: the revision the task started from (needed in a fresh clone
+                                        unless \`next\` pinned it or HEAD carries a Proofline-Base: trailer)
+                                        --fresh: run every check again, ignoring PASS results reused under
+                                        defaults.reuse_results
+  report <TASK>                         latest gate report
+  status [--owner <name>]               task + phase status, evidence chain
+  evidence record <type> --data '{..}' | evidence verify | evidence log
+  hook pre-commit|pre-push              (used by git hooks)
+  mcp                                   MCP server on stdio
+Global: --json  --root <dir>   Exit: 0 PASS, 1 FAIL, 2 BLOCKED, 3 usage`;
+
+try {
+  const [cmd, sub] = pos;
+  switch (cmd) {
+    case 'init': {
+      if (flags.approvals === true) throw new Error('--approvals needs a directory');
+      const r = P.init(root, { hooks: !flags['no-hooks'], approvals: flags.approvals });
+      print(r, `initialised ${root}${r.made.map((m) => `\n  ${m}`).join('')}`);
+      break;
+    }
+    case 'contract': {
+      if (sub === 'create') {
+        const spec = flags.from ? JSON.parse(fs.readFileSync(flags.from, 'utf8')) : { id: flags.id, title: flags.title, phase: flags.phase, owner: owner(), description: flags.description || '', depends_on: flags.depends ? String(flags.depends).split(',') : [], scope: flags.scope ? String(flags.scope).split(',') : undefined, criteria: [] };
+        const specs = Array.isArray(spec) ? spec : spec.tasks || [spec];
+        const out = specs.map((s) => P.contractCreate(root, s));
+        print(out, out.map((o) => `${o.task.id}: ${o.valid ? 'valid' : 'INCOMPLETE — ' + o.problems.join('; ')}`).join('\n'));
+        process.exitCode = out.every((o) => o.valid) ? 0 : 1;
+      } else if (sub === 'validate') { const e = P.C.validate(P.C.load(root)); print({ valid: !e.length, problems: e }, e.length ? e.join('\n') : 'contract valid'); process.exitCode = e.length ? 1 : 0; }
+      else if (sub === 'show') print(P.C.load(root));
+      else { console.error(HELP); process.exitCode = 3; }
+      break;
+    }
+    case 'next': { const n = P.taskNext(root, { owner: owner() }); print(n, n.brief || n.message); break; }
+    case 'brief': { const b = P.taskBrief(root, sub, { owner: owner(), base: base() }); print({ brief: b }, b); break; }
+    case 'verify': case 'gate': {
+      const c = P.C.load(root);
+      const ids = flags.all ? c.tasks.map((t) => t.id) : flags.ci ? (c.ci?.tasks || []) : [sub || P.activeTask(root)].filter(Boolean);
+      if (!ids.length) { if (flags.ci) { const e = P.C.validate(c); print({ decision: e.length ? 'FAIL' : 'PASS', problems: e }, e.length ? e.join('\n') : 'contract valid; no ci.tasks'); process.exitCode = e.length ? 1 : 0; break; } throw new Error('which task? (proofline next)'); }
+      const outs = ids.map((id) => P.E.gate(root, id, { claims: claims(), base: base(), fresh: flags.fresh === true, skipTypes: flags['skip-pushed'] || flags.ci ? ['pushed'] : [] }));
+      const worst = outs.some((o) => o.decision === 'BLOCKED') ? 'BLOCKED' : outs.some((o) => o.decision === 'FAIL') ? 'FAIL' : 'PASS';
+      print(outs.length === 1 ? outs[0] : { decision: worst, gates: outs.map((o) => ({ task: o.task, decision: o.decision, failing: o.failing, blocked: o.blocked })) },
+        outs.map((o) => `== ${o.task}: ${o.decision}\n  base: ${o.base_ref} = ${o.base?.slice(0, 8) || 'not found'} (${o.base_source})\n${o.results.map((r) => `  ${r.status.toUpperCase().padEnd(5)} ${r.id} [${r.type}] ${r.detail.split('\n')[0]}`).join('\n')}${o.forbidden.length ? '\n  forbidden: ' + o.forbidden.map((f) => `${f.rule}@${f.file}`).join(', ') : ''}\n  report: ${o.report}\n\n${o.corrective_prompt}`).join('\n\n') + `\n\nDECISION: ${worst}`);
+      process.exitCode = code(worst);
+      break;
+    }
+    case 'report': { const r = P.report(root, sub); print(r, r.markdown || r.error); process.exitCode = r.error ? 1 : 0; break; }
+    case 'status': { const s = P.status(root, { owner: owner() }); print(s, Object.entries(s.tasks).map(([k, v]) => `${k.padEnd(14)} ${v.status}`).join('\n') + '\n\n' + s.phases.map((p) => `${p.phase.padEnd(10)} ${p.verified}/${p.tasks}${p.open ? ' (open)' : ''}`).join('\n') + `\n\nevidence chain: ${s.chain.ok ? 'intact' : 'BROKEN'} (${s.chain.entries ?? '?'} entries); active: ${s.active || '-'}`); break; }
+    case 'evidence': {
+      if (sub === 'record') print(P.evidenceRecord(root, pos[2] || 'note', flags.data ? JSON.parse(flags.data) : {}));
+      else if (sub === 'verify') { const v = verifyChain(root); print(v, v.ok ? `chain intact: ${v.entries} entries, head ${v.head.slice(0, 16)}` : `CHAIN BROKEN at ${v.at}: ${v.reason}`); process.exitCode = v.ok ? 0 : 2; }
+      else if (sub === 'log') print(readLog(root));
+      else { console.error(HELP); process.exitCode = 3; }
+      break;
+    }
+    case 'hook': {
+      const r = sub === 'pre-commit' ? P.hookPreCommit(root) : sub === 'pre-push' ? P.hookPrePush(root) : null;
+      if (!r) { process.exitCode = 3; break; }
+      if (!r.ok) { console.error(`proofline ${sub}: REFUSED\n${r.msg}\n(There is no bypass. Fix the cause.)`); process.exitCode = 1; }
+      break;
+    }
+    case 'mcp': await import('../src/mcp.mjs').then((m) => m.serve(root)); break;
+    default: console.log(HELP); process.exitCode = cmd ? 3 : 0;
+  }
+} catch (e) { console.error(`proofline: ${e.message}`); process.exitCode = 3; }

package/docs/00-index.md

@@ -0,0 +1,43 @@
+# Documentation index
+
+This is the source of truth for the Proofline design. Requirements are normative where marked **MUST**; roadmap dates and implementation details remain provisional until explicitly accepted.
+
+## Product and design
+
+- [01 — Scope and product brief](01-scope.md)
+- [02 — Requirements](02-requirements.md)
+- [03 — Domain model and terminology](03-domain-model.md)
+- [04 — Architecture](04-architecture.md)
+- [05 — Task lifecycle and state machine](05-lifecycle.md)
+- [06 — Verification and reconciliation](06-verification.md)
+- [07 — Evidence model](07-evidence.md)
+- [08 — Agent adapters](08-adapters.md)
+- [09 — Security and trust boundaries](09-security.md)
+
+## Delivery and validation
+
+- [10 — Test and conformance strategy](10-conformance.md)
+- [11 — Development and release pipeline](11-development-pipeline.md)
+- [12 — Roadmap](12-roadmap.md)
+- [13 — Interdependencies](13-interdependencies.md)
+- [14 — Metrics and evaluation](14-metrics.md)
+
+## Decisions and examples
+
+- [Architecture decision records](adr/)
+- [Example task contract](../examples/demo-contract/proofline.json)
+- [Change log](../CHANGELOG.md)
+
+## Status vocabulary
+
+| Status | Meaning |
+|---|---|
+| `planned` | Defined but not implemented |
+| `in_progress` | Active implementation; not yet accepted |
+| `implemented` | Code exists; tests may still be incomplete |
+| `verified` | Required checks passed and evidence is available for the identified revision |
+| `blocked` | A mandatory gate or dependency prevents progress |
+| `partial` | Some requirements are met; remaining gaps are explicit |
+| `unverified` | Evidence is absent, stale, inconclusive, or insufficient |
+
+A status label is not a substitute for evidence. In particular, `implemented` is not equivalent to `verified`.