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

package/docs/06-verification.md

@@ -0,0 +1,57 @@
+# 06 — Verification and reconciliation
+
+## Verification gates
+
+| Gate | Question | Minimum evidence |
+|---|---|---|
+| G1 — Contract | Is the accepted scope complete and testable? | Validated, frozen contract; criteria and exclusions |
+| G2 — Traceability | Does each requirement map to a change and/or verification record? | Requirement-to-evidence matrix |
+| G3 — Execution | Were required checks actually run against the relevant revision? | Command identity, environment, revision, exit status, bounded output |
+| G4 — Independent challenge | What plausible failure modes or regressions are not covered by the agent's own checks? | Diff review, negative/edge-case tests, regression challenges |
+| G5 — Reconciliation | Do requested scope, observed changes, results, and agent claims agree? | Discrepancy list with dispositions |
+| G6 — Delivery | Is the report accurate and are artifacts present? | Final revision, report, mandatory gate status, exceptions |
+
+## Reconciliation dimensions
+
+For each requirement, compare:
+
+1. **Requested:** what the accepted contract requires.
+2. **Changed:** what the workspace diff actually changed.
+3. **Tested:** what the recorded checks actually exercised.
+4. **Observed:** what adapter and repository events show.
+5. **Claimed:** what the agent says it completed.
+6. **Accepted:** what a human explicitly waived or changed through contract amendment.
+
+A mismatch must create a finding. The system must not silently choose the most optimistic interpretation.
+
+## Finding format
+
+Each finding should include:
+- stable finding ID and severity;
+- affected requirement IDs;
+- category (`omission`, `scope_drift`, `failed_check`, `stale_evidence`, `unsupported_claim`, `security`, `ambiguity`, `policy_denial`);
+- concise statement;
+- supporting evidence IDs and revision;
+- confidence/verification method where probabilistic;
+- recommended next action;
+- disposition (`open`, `resolved`, `accepted_exception`, `not_applicable`) and who recorded it.
+
+## Independence model
+
+Independence is layered, not absolute:
+- **Deterministic:** schema validation, status rules, diff paths, command exit codes, freshness checks, traceability completeness.
+- **Test-based:** tests generated or selected from acceptance criteria and run independently.
+- **Heuristic:** static analysis, diff heuristics, suspicious claim checks.
+- **Model-assisted:** a separate reviewer/model may challenge the work, but its output is a finding to corroborate, not proof by itself.
+- **Human:** domain judgement for ambiguous requirements, high-risk changes, or inadequate automated oracles.
+
+## Decision matrix
+
+| Condition | Permitted outcome |
+|---|---|
+| All mandatory requirements have fresh sufficient evidence; no open mandatory findings | `verified` |
+| Work is useful but one or more requirements remain incomplete or explicitly waived | `partial` |
+| Mandatory check failed, policy denied a required action, or dependency blocks required validation | `blocked` |
+| Evidence is absent, stale, contradictory, or too weak to decide | `unverified` |
+
+No status may be inferred from an agent's final message alone.

package/docs/07-evidence.md

@@ -0,0 +1,69 @@
+# 07 — Evidence model
+
+## Evidence record fields
+
+The exact schema will be versioned in implementation. Every record should support the following fields:
+
+| Field | Purpose |
+|---|---|
+| `schema_version` | Parse/migration contract |
+| `evidence_id` | Stable unique identifier |
+| `run_id` | Run that produced or collected it |
+| `kind` | `command`, `test`, `diff`, `agent_claim`, `review`, `approval`, `environment`, `observation`, etc. |
+| `source` | Adapter, runner, repository inspector, human, or verifier |
+| `created_at` | Timestamp with timezone |
+| `requirement_ids` | Related requirements where known |
+| `revision` | Commit/tree/workspace identifier, where applicable |
+| `environment` | Relevant runtime/tool versions and configuration fingerprint |
+| `result` | `passed`, `failed`, `skipped`, `not_run`, `inconclusive`, `stale`, or `waived` |
+| `command` | Structured argv, working directory, and policy ID for executed checks |
+| `exit_code` | Process result where applicable |
+| `output_ref` | Reference to bounded/sanitized output artifact |
+| `digest` | Content digest for integrity and deduplication |
+| `redactions` | Fields/content omitted or redacted and reason |
+| `supersedes` | Prior record IDs replaced by a corrected observation |
+| `notes` | Short explanation, not a substitute for structured fields |
+
+## Command evidence
+
+A `command` criterion records one evidence object per run. A run that failed is re-run (`defaults.flaky_reruns`), and the evidence then holds both runs as `first` and `rerun`, so a flaky result shows which tests failed on the first run and passed on the re-run.
+
+| Field | Purpose |
+|---|---|
+| `cmd`, `exit`, `ms`, `timedOut` | The command as run, its exit code, its duration and whether it hit `timeout_s` |
+| `counts` | `tests`, `pass`, `fail`, `skipped`, `todo` and `cancelled` from node's summary (`# fail 3` or `ℹ fail 3`) |
+| `out_tail` | The last 1,200 characters of stdout and stderr |
+| `failing` | The names of the failed tests found anywhere in the output, not only in `out_tail`: TAP `not ok <n> - <name>` lines, spec and dot reporter `✖ <name> (<ms>ms)` lines, and the `failing tests:` summary node prints at the end. Tests marked TODO or SKIP (in the spec reporter, a `# <reason>` after the duration) are left out. Repeats are dropped, the order is that of first appearance, and the list holds at most 100 names. Output in another format gives an empty list; `out_tail` still holds its end |
+| `failing_total` | Present only when more than 100 names were found: how many there were |
+
+The FAIL detail names the first 10 failing tests (`9 tests failed: a, b, c`, then `and <n> more` past 10), and the gate report lists every recorded name under **Failing tests**, per run.
+
+## Evidence rules
+
+- Capture the exact revision against which each check ran.
+- A check run before a relevant change is stale for the changed behaviour unless freshness policy proves otherwise.
+- With `defaults.reuse_results` on, a `command` or `metric` PASS is recorded as a `result` entry, and a later verify or gate on the same HEAD with a clean tree may reuse it (key: verifier, HEAD, node version, the env vars the command names) for up to `reuse_max_age_h` hours. The reused result is read from that entry, only while it is in an intact chain with the hash the cache file stored, and the report names it: `reused from <time> (evidence entry <n>)`.
+- Preserve failed results after a later retry passes; final state may improve but history must not be rewritten.
+- Bound output size and execution time.
+- Redact secrets before persistence; do not assume command output is safe.
+- Record why a check was skipped or could not run.
+- Separate raw source evidence from verifier interpretation.
+- A hash protects integrity, not semantic validity.
+- Evidence may be exported without including full source code or secrets.
+
+## Evidence lifecycle
+
+```mermaid
+flowchart LR
+    S[Source event / check] --> N[Normalize + validate]
+    N --> R[Redact + bound]
+    R --> H[Digest + assign ID]
+    H --> L[Append to ledger]
+    L --> F[Link to requirements/findings]
+    F --> D[Gate decision]
+    D --> P[Portable report]
+```
+
+## Report portability
+
+The report must contain sufficient metadata to interpret the decision after the local process exits: contract version, run ID, revision, policy/verifier versions, requirement status, check status, exceptions, findings, and artifact references. Any omitted raw data must be clearly marked as omitted/redacted and not silently treated as inspected.

package/docs/08-adapters.md

@@ -0,0 +1,61 @@
+# 08 — Agent adapters
+
+## Purpose
+
+Adapters translate tool-specific lifecycle signals into a stable event model. They do not make final verification decisions and must not have authority to weaken the contract.
+
+## Adapter boundary
+
+```mermaid
+flowchart LR
+    AGENT[Agent / IDE / CLI] <--> AD[Vendor adapter]
+    AD --> EV[Normalized event schema]
+    EV --> CORE[Proofline core]
+    CORE --> FB[Policy-approved feedback/action]
+    FB --> AD
+    AD --> AGENT
+```
+
+## Initial adapter selection
+
+The first adapter should be chosen by a short technical spike using:
+- quality of lifecycle signals (start, tool use, stop/completion);
+- ability to capture the changed revision and command results;
+- stability and documented extension points;
+- safe failure behaviour when the agent or hook crashes;
+- ease of local installation and reproducible integration tests.
+
+Claude Code and Codex are candidate first adapters because they are widely used and expose lifecycle hooks. The choice must be recorded after testing rather than assumed in advance. Do not implement many thin adapters before one end-to-end path is trustworthy.
+
+## Normalized event categories
+
+- `run_started`
+- `agent_message` (claim, not proof)
+- `tool_invocation_requested`
+- `tool_invocation_completed`
+- `workspace_changed`
+- `check_requested`
+- `check_completed`
+- `agent_paused`
+- `agent_completed`
+- `approval_requested`
+- `approval_granted`
+- `approval_denied`
+- `adapter_error`
+
+Each event includes schema version, event ID, run ID, source adapter/version, timestamp, and any relevant revision or correlation ID.
+
+## Adapter requirements
+
+- Validate and normalize all incoming data.
+- Treat tool arguments and agent text as untrusted.
+- Do not leak secrets in logs or feedback.
+- Preserve ordering/correlation where the host supports it; otherwise report the limitation.
+- Fail closed for enforcement-critical events when the adapter cannot establish a required fact.
+- Never mark a gate verified merely because the host emitted a completion event.
+- Support `observe` mode without taking control of the agent.
+- Document host-specific gaps and version compatibility.
+
+## Hook versus core
+
+Hooks are an integration mechanism, not the product differentiator. The durable value is the contract, evidence model, independent checks, reconciliation logic, and enforceable delivery semantics behind those hooks.

package/docs/09-security.md

@@ -0,0 +1,64 @@
+# 09 — Security and trust boundaries
+
+## Threat model
+
+Assets:
+- source code and working-tree state;
+- credentials, environment variables, and private tool output;
+- task contracts, evidence, findings, and approvals;
+- integrity of the delivery decision;
+- ability to execute commands or modify external systems.
+
+Threat actors and failure sources:
+- malicious or compromised agent output;
+- prompt injection embedded in repository files, issue text, tool output, or dependency docs;
+- unsafe project scripts or malicious test commands;
+- compromised adapter or model provider;
+- accidental secret capture;
+- confused-deputy behaviour where an agent tricks the verifier into using broader permissions;
+- false confidence from stale tests, mocked checks, or weak acceptance criteria.
+
+## Trust boundaries
+
+```mermaid
+flowchart TB
+    subgraph Untrusted
+      A[Agent output]
+      R[Repository files / tool output]
+      X[External model review]
+    end
+    subgraph Controlled
+      AD[Validated adapter]
+      P[Command policy]
+      L[Evidence ledger]
+      V[Deterministic verifier]
+      G[Gate engine]
+    end
+    H[Human approval] --> G
+    A --> AD
+    R --> AD
+    AD --> L
+    P --> L
+    L --> V
+    X -. advisory findings only .-> V
+    V --> G
+```
+
+## Required controls for MVP
+
+- Explicit command allowlist/policy; no arbitrary command execution by default.
+- Command argv should be structured; avoid shell interpolation where possible.
+- Working-directory containment and path traversal protections.
+- Process timeouts, output-size limits, and environment filtering.
+- Secret redaction before evidence persistence.
+- Read-only observe mode as the safest starting point.
+- Separate permission for applying corrective edits versus reporting findings.
+- Explicit approval for destructive or external side effects.
+- Adapter event schema validation and compatibility checks.
+- Report that identifies policy and verifier versions.
+- No default telemetry or background upload.
+- Audit trail for policy changes, exceptions, and approvals.
+
+## Security non-goals
+
+A local verifier cannot guarantee that arbitrary code is harmless, that every malicious change will be detected, or that a model reviewer is free from manipulation. The system reduces specific classes of process failure and makes evidence and residual uncertainty visible; it is not a formal proof of software safety.

package/docs/10-conformance.md

@@ -0,0 +1,59 @@
+# 10 — Test and conformance strategy
+
+## Test layers
+
+1. **Schema tests:** valid/invalid contracts, event records, evidence records, and reports.
+2. **Unit tests:** state machine, freshness, gate decisions, retry limits, traceability, redaction.
+3. **Property tests:** deterministic decisions; evidence append/supersede rules; no `verified` state with unmet mandatory gates.
+4. **Adapter contract tests:** event normalization, failure behaviour, version compatibility.
+5. **Integration tests:** CLI + local workspace + check runner + ledger + report.
+6. **End-to-end tests:** realistic agent session with controlled fixtures; no live provider required in default CI.
+7. **Adversarial fixtures:** false completion claims, skipped tests, stale test results, scope drift, malformed events, secret output, repeated corrective loops.
+8. **Security tests:** command injection attempts, path traversal, environment leakage, oversized output, unsafe symlinks, permission denial.
+9. **Usability/pilot tests:** interruption count, false blocks, caught omissions, latency, user review burden.
+
+## Mandatory negative fixtures
+
+| Fixture | Expected result |
+|---|---|
+| Agent says tests passed; no test evidence exists | Not `verified`; report missing evidence |
+| Mandatory test exits non-zero | `blocked` unless authorized policy explicitly defines a different non-verified disposition |
+| Mandatory test was skipped | Not `verified` |
+| Tests pass on old revision, then relevant code changes | Mark evidence stale and re-run or block |
+| Required acceptance criterion has no evidence mapping | Finding; not `verified` |
+| Diff changes excluded path or unrelated behaviour | Scope-drift finding |
+| Same finding repeats without meaningful change | Stop retry loop |
+| Agent claims a file changed but diff does not contain it | Unsupported-claim finding |
+| Check output contains a secret-shaped value | Redact before persistence; test redaction metadata |
+| Adapter drops an enforcement-critical event | Enforcement cannot silently pass |
+| Gate in a fresh clone with no pinned base, where the default base is HEAD | `BLOCKED` with a corrective naming `--base`; never a pass on an empty diff |
+| Same gate with `--base <parent>` and a change outside the task's scope | Scope-drift finding |
+| Repository already has a pre-push hook that refuses the push | After `init` the push is still refused by that hook; a passing hook hands over to the gate |
+| Two builders share a contract with owners | `next --owner a` never returns a task owned by `b`; an owner outside `defaults.owners` fails validation |
+| Metric run while the machine's load per CPU is above `defaults.max_load_per_cpu` | `BLOCKED` (machine busy, with the numbers); no measured value recorded |
+| Commit adds or amends `proofline.json` with the default deny-list | No forbidden finding in the contract itself; the change is judged by the weakening check |
+| `defaults.reuse_results` on (`true`/`false`, default `false`; `defaults.reuse_max_age_h`, a positive number, default 24): `verify` then `gate` on one clean commit | A `command` or `metric` PASS runs once; the gate report lists it under Reused results as `reused from <time> (evidence entry <n>)`, and the gate entry says the same |
+| Same, with an uncommitted edit or untracked file, a new commit, `--fresh`, a changed env var the command names, a PASS older than `reuse_max_age_h`, or a log that no longer holds the recording entry intact with its hash | The check runs again |
+| Same, where the check FAILs, is flaky, is blocked or cannot run | Nothing is stored; it runs every time |
+| `reuse_results` left out or `false` | Every check runs every time; nothing is stored |
+
+## Conformance fixture format
+
+Each fixture should include:
+- contract;
+- initial and final workspace state or synthetic diff;
+- event stream;
+- check results;
+- agent delivery claims;
+- expected findings;
+- expected terminal status;
+- rationale.
+
+## Release gate
+
+No release candidate may be described as verified until:
+- all required CI checks pass;
+- all mandatory conformance fixtures pass;
+- security-sensitive changes have explicit review;
+- release artifacts and checksums are recorded;
+- documentation and known limitations match the actual build.

package/docs/11-development-pipeline.md

@@ -0,0 +1,50 @@
+# 11 — Development and release pipeline
+
+## Development loop
+
+```mermaid
+flowchart TD
+    I[Issue / requirement] --> C[Contract and acceptance criteria]
+    C --> D[Design / ADR if needed]
+    D --> IMP[Small implementation slice]
+    IMP --> U[Unit + schema tests]
+    U --> INT[Integration + adapter contract tests]
+    INT --> ADV[Adversarial conformance fixtures]
+    ADV --> REV[Independent diff / requirement review]
+    REV --> REC[Reconcile claims, changes, evidence]
+    REC -->|gap| IMP
+    REC -->|clean| CI[CI release gates]
+    CI --> REL[Versioned release + report]
+```
+
+## Branch and review policy
+
+- `main` should represent a coherent, CI-checked baseline.
+- Use short-lived feature branches and pull requests.
+- Each PR names requirement IDs and updates tests/docs/changelog as appropriate.
+- Do not merge a change that weakens a mandatory gate without an ADR and explicit rationale.
+- Require at least one review for changes to command execution, evidence integrity, gate logic, permissions, or schema migrations.
+- Protect `main` with required CI and review rules once repository settings are available.
+
+## CI stages
+
+1. Checkout with minimal permissions.
+2. Static formatting and lint.
+3. Type/schema checks.
+4. Unit tests.
+5. Integration tests using synthetic/local fixtures.
+6. Adapter contract tests.
+7. Adversarial conformance suite.
+8. Security and dependency checks.
+9. Build/package.
+10. Generate provenance/checksum and release report.
+
+The workflow in `.github/workflows/proofline.yml` runs the self-gate (`node bin/proofline.mjs gate --ci`) on every push to `main` and on pull requests, with the branch tip before the push as the base, and uploads the evidence report. Documentation CI must not be misrepresented as software verification.
+
+## Release discipline
+
+- Version schemas independently or document compatibility in the package versioning policy.
+- Record commit, build inputs, test results, and artifact digests.
+- Publish release notes with added behaviour, limitations, migration notes, and known issues.
+- Never publish a release based only on the agent's assertion that it is ready.
+- Keep a release checklist and a rollback/recovery plan.

package/docs/12-roadmap.md

@@ -0,0 +1,104 @@
+# 12 — Roadmap
+
+This is a dependency-ordered roadmap, not a promise of calendar dates. A phase is complete only when its exit criteria are evidenced.
+
+## Phase 0 — Contract and feasibility spike
+
+**Goal:** remove ambiguity before building a broad framework.
+
+Deliverables:
+- Agree initial adapter choice based on a small integration spike.
+- Define task-contract, event, evidence, finding, and report schemas.
+- Select implementation language/runtime based on the adapter and existing project conventions.
+- Validate that required lifecycle events and revision identity can be captured.
+- Write 5–10 adversarial scenarios.
+
+Exit criteria:
+- A real agent session can be correlated with a workspace revision.
+- The team can state which lifecycle facts are available and which are not.
+- The MVP scope and first adapter are recorded in an ADR.
+
+## Phase 1 — Local contract and evidence core
+
+**Goal:** establish the trustworthy core without agent integration complexity.
+
+Deliverables:
+- Contract validation and versioning.
+- Local run state machine.
+- Evidence schema and append-oriented local ledger.
+- Deterministic gate engine.
+- JSON/Markdown report.
+- Synthetic fixtures and negative tests.
+
+Exit criteria:
+- Missing, stale, skipped, and failed mandatory evidence cannot produce `verified`.
+- A report is reproducible from the same contract, policy, and evidence set.
+
+## Phase 2 — First real adapter
+
+**Goal:** observe one supported agent end-to-end.
+
+Deliverables:
+- Adapter event normalization.
+- Workspace/diff observation.
+- Start, observe, verify, report workflow.
+- Safe failure and adapter diagnostics.
+
+Exit criteria:
+- Real task can be observed in `observe` mode without breaking the agent workflow.
+- Event gaps and adapter limitations are documented.
+
+## Phase 3 — Verification and corrective guidance
+
+**Goal:** catch useful omissions without creating noisy loops.
+
+Deliverables:
+- Requirement traceability.
+- Independent configured checks.
+- Scope drift detection.
+- Unsupported completion-claim detection.
+- Bounded corrective feedback and loop detection.
+
+Exit criteria:
+- Mandatory adversarial fixtures pass.
+- Pilot measures both true catches and false blocks.
+
+## Phase 4 — Enforce mode and hardening
+
+**Goal:** allow policy-based delivery gates.
+
+Deliverables:
+- Enforce-mode gate integration.
+- Human approval/exception records.
+- Command policy and security hardening.
+- CI/release report integration.
+
+Exit criteria:
+- Security review and failure-mode tests pass.
+- Enforcement does not silently fail open when required signals are missing.
+
+## Phase 5 — Optional ecosystem integrations
+
+**Goal:** add value without compromising standalone operation.
+
+Candidates:
+- HiveVault connector for prior decisions and accepted exceptions.
+- Additional agent adapters.
+- CI provider integrations.
+- Export/import and evidence replay tooling.
+
+Exit criteria:
+- Core remains standalone; integrations are optional and cannot bypass evidence gates.
+
+## Deferred until justified
+
+- Dashboard.
+- Hosted control plane.
+- Multi-agent orchestration.
+- Broad domain packs outside software engineering.
+- CRDT-backed replicated evidence store.
+- Commercial/team policy management.
+
+## Go/no-go criteria
+
+Continue beyond the pilot only if measured omission detection and false-completion prevention justify added latency and review overhead. The key metric is useful, verified catches per interruption—not the number of events collected.

package/docs/13-interdependencies.md

@@ -0,0 +1,53 @@
+# 13 — Interdependencies
+
+## Dependency map
+
+```mermaid
+flowchart TD
+    CONTRACT[Contract schema] --> STATE[Run state machine]
+    EVENTS[Normalized event schema] --> ADAPTER[First agent adapter]
+    ADAPTER --> EVENTS
+    STATE --> LEDGER[Evidence ledger]
+    EVENTS --> LEDGER
+    GIT[Workspace / revision inspector] --> LEDGER
+    RUNNER[Command policy + check runner] --> LEDGER
+    CONTRACT --> TRACE[Requirement traceability]
+    LEDGER --> TRACE
+    TRACE --> VERIFY[Verifier]
+    VERIFY --> RECON[Reconciliation]
+    CONTRACT --> RECON
+    RECON --> GATE[Gate decision]
+    POLICY[Approval / exception policy] --> GATE
+    GATE --> REPORT[Portable reports]
+    REPORT --> PILOT[Pilot metrics]
+    HV[Optional context connector] -. non-authoritative context .-> CONTRACT
+```
+
+## Dependency register
+
+| ID | Dependency | Needed by | Risk if delayed | Mitigation |
+|---|---|---|---|---|
+| DEP-01 | Contract schema and stable requirement IDs | State machine, traceability, reports | Requirements become untestable prose | Define schema and examples first |
+| DEP-02 | Adapter lifecycle capability | Observer, end-to-end workflow | Cannot reliably correlate task to events | Spike adapter early; document unsupported signals |
+| DEP-03 | Workspace/revision identity | Evidence freshness, diff review | Stale evidence may appear current | Make revision identity mandatory where available |
+| DEP-04 | Safe command runner | Independent checks | Arbitrary execution risk | Allowlist, structured argv, timeouts, isolated environment |
+| DEP-05 | Evidence record model | All verification and reporting | Lost provenance and non-reproducible decisions | Version schema before multiple consumers |
+| DEP-06 | Deterministic gate rules | Enforce mode | False pass or inconsistent status | Implement and test gate logic before hooks can block |
+| DEP-07 | Conformance fixtures | Verifier confidence | Regressions in safety semantics | Build adversarial fixtures alongside core |
+| DEP-08 | Pilot instrumentation | Product go/no-go | No evidence product helps users | Capture catches, false blocks, latency, interruptions |
+| DEP-09 | An optional context connector, for example a project-memory store such as HiveVault | Cross-run context only | Integration may couple core to memory | Keep adapter boundary optional and read-only initially |
+
+## Critical path
+
+`contract schema -> evidence schema -> deterministic gate engine -> synthetic conformance suite -> first adapter -> pilot -> enforce mode`
+
+The first adapter spike can run in parallel with schema work, but it must not force vendor-specific concepts into the core model.
+
+## Integration rule for context connectors
+
+A context connector may store or retrieve prior decisions, project constraints, known failure patterns, and accepted exceptions. Proofline must:
+- mark imported context as historical context;
+- show source and timestamp;
+- ask for confirmation when a historical decision conflicts with the current contract;
+- never treat a memory entry as current-run test evidence;
+- work with the connector absent.

package/docs/14-metrics.md

@@ -0,0 +1,40 @@
+# 14 — Metrics and evaluation
+
+## Primary product question
+
+Does Proofline catch meaningful omissions and unsupported completion claims at an acceptable cost in latency, false blocks, and user attention?
+
+## Metrics
+
+| Metric | Definition | Why it matters |
+|---|---|---|
+| Verified omission catches | Confirmed missing requirements caught before delivery | Core value |
+| False completion claims blocked | Delivery claims contradicted by evidence | Trust value |
+| False-positive blocks | Blocks later judged unnecessary or incorrect | Adoption risk |
+| Missed defects/omissions | Known pilot issues not detected | Reliability risk |
+| Mandatory evidence coverage | Mandatory criteria with fresh, sufficient evidence / all mandatory criteria | Traceability |
+| Stale-evidence rejection rate | Stale evidence correctly prevented from satisfying gates | Evidence freshness |
+| Mean verification latency | Time added by verification, split by deterministic and model-assisted steps | Workflow cost |
+| Interruptions per task | Agent/user interruptions introduced by the tool | Usability |
+| Corrective cycles | Number of guidance/retry cycles per run | Loop/noise risk |
+| Human review burden | Minutes spent reviewing findings and reports | Adoption |
+| Reproducible decision rate | Decisions replayed from captured contract/policy/evidence with same result | Auditability |
+
+## Pilot design
+
+- Select a representative set of real tasks, including known failure examples.
+- Establish expected acceptance criteria before running the agent.
+- Compare normal agent workflow with observe mode first.
+- Label each finding as true positive, false positive, duplicate, or inconclusive.
+- Measure total added time and user intervention.
+- Include cases where the agent succeeds cleanly; do not evaluate only failures.
+- Do not claim statistical generality from a small pilot.
+
+## Initial go/no-go
+
+No numerical threshold is asserted before baseline data exists. The pilot should agree thresholds in advance for:
+- minimum confirmed useful catches;
+- maximum false-positive block rate;
+- maximum added latency;
+- maximum user review burden;
+- no tolerance for a false `verified` status in the mandatory negative fixtures.

package/docs/adr/0001-product-boundary.md

@@ -0,0 +1,28 @@
+# ADR-0001: Product boundary and independence
+
+- Status: Accepted
+- Date: 2026-10-14
+
+## Context
+
+Agent frameworks already expose hooks and lifecycle events. A thin hook wrapper would be easy to copy and would not solve the central problem: whether the requested work was actually completed and independently verified.
+
+## Decision
+
+Build the product around an accepted task contract, evidence ledger, independent verification, reconciliation, and delivery decision. Hooks/adapters are replaceable integration layers. HiveVault is optional.
+
+## Consequences
+
+Positive:
+- Core value is not tied to a single agent.
+- Evidence can be exported and audited independently.
+- Standalone use is possible.
+
+Trade-offs:
+- More upfront design and conformance work than a prompt-only tool.
+- Verification quality is limited by the quality of the contract and available oracles.
+- The first adapter must be selected carefully to avoid premature generalization.
+
+## Revisit when
+
+Pilot evidence shows that the core abstraction is too heavy, or a specific host imposes lifecycle constraints that materially change the architecture.

package/docs/adr/0002-evidence-and-gates.md

@@ -0,0 +1,22 @@
+# ADR-0002: Evidence-based delivery states
+
+- Status: Accepted
+- Date: 2026-10-14
+
+## Context
+
+Agent completion messages and process exit codes are insufficient to establish that all requirements were met. Skipped checks and stale evidence must not be confused with passing checks.
+
+## Decision
+
+Use explicit check states (`passed`, `failed`, `skipped`, `not_run`, `inconclusive`, `stale`, `waived`) and terminal delivery states (`verified`, `partial`, `blocked`, `unverified`). Every gate decision is derived from the contract, policy, evidence freshness, and unresolved findings.
+
+## Consequences
+
+- Reports are more nuanced than a single green/red result.
+- The gate engine and state machine require thorough negative tests.
+- Human-approved exceptions remain visible and do not rewrite the evidence history.
+
+## Revisit when
+
+Pilot workflows demonstrate a required terminal state not covered by the model.

package/docs/adr/0003-standalone-first.md

@@ -0,0 +1,18 @@
+# ADR-0003: Standalone-first, context connectors optional
+
+- Status: Accepted
+- Date: 2026-10-14
+
+## Context
+
+HiveVault can provide persistent project context, but coupling Proofline to it would limit adoption and blur the difference between remembered claims and current evidence.
+
+## Decision
+
+The MVP works locally without HiveVault. Any connector is optional and initially supplies clearly labelled historical context only.
+
+## Consequences
+
+- Standalone use remains possible.
+- Cross-run knowledge can be added later without making the core dependent on it.
+- Imported context must never satisfy current-run verification gates by itself.

package/docs/receipt.md

@@ -0,0 +1,25 @@
+# Receipt
+
+Without a contract, `receipt` infers the suite from the manifest at the base revision. A change to that command is reported and is not what runs.
+
+| Manifest | Command |
+| --- | --- |
+| package.json `scripts.test` | that script, else `vitest run` or `jest` when that dev dependency is present |
+| Cargo.toml | `cargo test` |
+| pyproject.toml `[tool.pytest]` or pytest.ini | `pytest` |
+| go.mod | `go test ./...` |
+| build.gradle, `*.sln` | no default command, status blocked |
+
+Changed tests are paths under `test/` or `tests/`, or names matching `*_test.*`, `*.test.*`, `*.spec.*` or `test_*.py`. Nothing inferable yields an L0 receipt and exit 2. A missing toolchain is blocked, not a pass.
+
+`verify-receipt` checks the DSSE envelope offline against PEM files in `--keys` (or `$AGENTKEY_HOME/keys`), named `<keyid>.pem`. Exit 0 is verified, 1 is a bad signature, a schema problem or a `--recompute` difference, 2 is an unknown key, and 3 is usage. `--sigstore` is the only path that loads that verifier.
+
+The MCP tools `receipt` and `verify_receipt` return that same JSON. `tools/list` shows nine tools.
+
+`proofline hook stop` reads a Claude Code Stop payload and writes one receipt for the commits that session made. A second run on the same range writes none. `proofline connect claude-code` adds that hook after any Stop hook already in `~/.claude/settings.json`.
+
+When `GET /v1/state/digest` answers within 2 seconds, an L1 receipt gains `memory.vault_digest` and `memory.frontier`. An L2 receipt in ci mode gains only `memory_commitment`, the sha256 of the vault id, the digest and the frontier JSON, so a replica id is not in the receipt. No answer leaves the receipt unchanged. `--vault` writes `work/receipts/<date>-<role>-<sha7>.md` with origin `proofline`.
+
+The weakening check is a warning beside the owner signature. It names a loosened threshold, a removed criterion, or a changed command. Once `guard/owner.pub` is pinned, a missing, altered or wrongly-signed contract is refused with `contract not owner-signed`.
+
+grep, wiring and the forbidden scan are marked `heuristic` in the receipt. They are one layer, not a boundary. An isolated run records `isolated` and `env_digest`. A local run records `isolated` false.