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

package/docs/01-scope.md

@@ -0,0 +1,70 @@
+# 01 — Scope and product brief
+
+## Problem
+
+AI agents can complete a plausible-looking task while omitting requirements, changing behaviour outside the requested scope, skipping mandatory checks, relying on stale assumptions, or overstating what was validated. The same agent that performs the work is not a sufficient independent authority on whether the work meets its contract.
+
+## Product statement
+
+**Proofline is an independent verification and delivery gate for AI-agent work.** It keeps the task contract separate from implementation, records evidence, tests the implementation against the contract, reconciles discrepancies, and reports what can legitimately be claimed at delivery.
+
+## Target user
+
+A developer, technical lead, researcher, or team using coding agents and needing reliable control over scope, validation, and delivery—not just more generated code.
+
+## Primary jobs to be done
+
+1. Turn a request into a reviewable contract with explicit acceptance criteria.
+2. Observe work without assuming that narrated progress is accurate.
+3. Map each requirement to a change, test, or explicit exception.
+4. Execute or independently evaluate required checks under controlled policy.
+5. Detect missing coverage, scope drift, contradictory evidence, and unsupported claims.
+6. Provide bounded, specific corrective feedback.
+7. Produce an auditable delivery decision and portable report.
+
+## Core workflow
+
+1. **Contract:** establish requirements, constraints, exclusions, risk tier, required evidence, and approval rules.
+2. **Observe:** capture permitted lifecycle events, commands, diffs, and revision identifiers.
+3. **Verify:** run policy-approved checks and independent challenges.
+4. **Reconcile:** compare requested, implemented, tested, and reported outcomes.
+5. **Correct or escalate:** return specific gaps, retry within configured limits, or request human judgement.
+6. **Deliver:** produce status, residual risks, exceptions, and evidence references.
+
+## MVP — in scope
+
+- Local CLI and local task/session state.
+- Versioned task-contract schema.
+- One deeply supported agent adapter, chosen after a spike.
+- Event ingestion with schema validation.
+- Evidence ledger with immutable record IDs and revision/environment context.
+- Configurable command/check runner with allowlists and timeouts.
+- Requirement-to-evidence traceability.
+- Reconciliation rules and explicit terminal states.
+- Bounded corrective feedback and loop detection.
+- Markdown and JSON delivery reports.
+- Unit, integration, adapter-contract, and end-to-end tests.
+- A standalone mode with no required hosted service or HiveVault dependency.
+
+## Explicitly out of scope for MVP
+
+- A general-purpose multi-agent orchestration platform.
+- A hosted SaaS control plane or central telemetry service.
+- A mandatory HiveVault integration.
+- Automatic approval of production deployment, financial actions, or other irreversible changes.
+- A claim that arbitrary natural-language work can be fully proven correct.
+- A dashboard before the CLI and evidence model are validated.
+- A universal policy pack for every programming language and domain.
+- An agent marketplace or broad adapter matrix before one adapter is reliable.
+
+## Product boundaries
+
+- The implementing agent proposes and changes; Proofline evaluates against the accepted contract.
+- The user/team owns the contract and can explicitly approve changes to it.
+- The verifier may identify a likely defect, but domain-specific correctness still depends on the available oracle and evidence.
+- An evidence record establishes what was recorded and under what conditions; it does not automatically establish that the chosen test was sufficient.
+- HiveVault may provide prior decisions, but prior context cannot satisfy a current-run verification gate by itself.
+
+## Success criteria for the first pilot
+
+The MVP is worth continuing only if a real workflow shows that it catches meaningful omissions or false completion claims while keeping false blocks, latency, and interruptions tolerable. See [metrics](14-metrics.md).

package/docs/02-requirements.md

@@ -0,0 +1,64 @@
+# 02 — Requirements
+
+This is the initial normative requirements baseline. IDs are stable references for issues, tests, reports, and changes. `MUST` is mandatory for MVP unless explicitly re-scoped through an ADR and changelog entry.
+
+## Functional requirements
+
+| ID | Priority | Requirement | Acceptance evidence |
+|---|---|---|---|
+| REQ-001 | MUST | The system MUST create or load a versioned task contract before enforcement. | Contract schema tests; invalid-contract rejection |
+| REQ-002 | MUST | The contract MUST express acceptance criteria, exclusions, constraints, required checks, and risk/approval policy. | Schema and contract round-trip tests |
+| REQ-003 | MUST | The system MUST preserve the accepted contract separately from agent-authored task notes. | Mutation/tampering tests |
+| REQ-004 | MUST | The observer MUST ingest supported adapter events and validate event schema/version. | Adapter conformance suite |
+| REQ-005 | MUST | Every evidence record MUST identify its source, timestamp, task/run, revision where applicable, and result state. | Evidence schema tests |
+| REQ-006 | MUST | The system MUST distinguish `passed`, `failed`, `skipped`, `not_run`, and `inconclusive`. | State-transition tests |
+| REQ-007 | MUST | Each acceptance criterion MUST resolve to evidence, an explicit exception, or an unresolved gap. | Traceability report tests |
+| REQ-008 | MUST | Verification MUST be able to run configured checks independently of the implementing agent's claims. | End-to-end test with deliberately false claim |
+| REQ-009 | MUST | The system MUST compare requested scope, observed changes, checks, and delivery claims. | Scope-drift and reconciliation fixtures |
+| REQ-010 | MUST | Delivery status MUST distinguish `verified`, `partial`, `blocked`, and `unverified`. | Decision matrix tests |
+| REQ-011 | MUST | Mandatory failed, skipped, stale, or absent evidence MUST NOT be reported as verified. | Negative delivery-gate tests |
+| REQ-012 | MUST | Corrective feedback MUST cite the gap, requirement ID, supporting evidence, and next action. | Feedback contract tests |
+| REQ-013 | MUST | Corrective retries MUST be bounded and repeated-loop detection MUST exist. | Retry-limit and loop fixtures |
+| REQ-014 | MUST | The system MUST emit human-readable and machine-readable reports. | Snapshot/schema tests |
+| REQ-015 | MUST | The system MUST work without any external context store or network connection for local workflows. | Offline integration test |
+| REQ-016 | MUST | The system MUST record human-approved exceptions with actor, rationale, scope, and timestamp. | Exception audit tests |
+| REQ-017 | SHOULD | The system SHOULD support baseline and final revision comparison. | Git integration tests |
+| REQ-018 | SHOULD | The system SHOULD support report export and verification replay. | Replay integration test |
+| REQ-019 | SHOULD | The system SHOULD expose a stable adapter contract for future agent integrations. | Contract test harness |
+| REQ-020 | COULD | The system COULD integrate with an external context store for prior decisions and accepted exceptions. | Optional integration tests |
+
+## Non-functional requirements
+
+| ID | Requirement | Initial acceptance target |
+|---|---|---|
+| NFR-001 | Local-first | Core contract, evidence, and report path works offline. |
+| NFR-002 | Deterministic decisions | Same contract, policy, evidence set, and verifier version produce the same gate decision. |
+| NFR-003 | Explainability | Every block identifies one or more unmet gates and the evidence behind the decision. |
+| NFR-004 | Performance | Establish a measured baseline; avoid arbitrary latency promises before pilot data. |
+| NFR-005 | Safety | Commands run only through explicit policy; timeout and output-size limits exist. |
+| NFR-006 | Privacy | No telemetry by default; evidence redaction and local storage documented. |
+| NFR-007 | Portability | Reports are plain text/JSON with schema versions and no hosted-service dependency. |
+| NFR-008 | Recoverability | Interrupted runs are recoverable without silently promoting status. |
+| NFR-009 | Compatibility | Adapter and report schemas are versioned and migration policy documented. |
+| NFR-010 | Testability | Core state machine and policy decisions are testable without live AI-provider calls. |
+
+## MVP acceptance criteria
+
+The MVP cannot be declared complete until all of the following are demonstrated:
+
+- [ ] A contract can be created, validated, frozen for a run, and versioned.
+- [ ] One supported agent can be observed through a real task lifecycle.
+- [ ] The changed revision and permitted verification commands are captured.
+- [ ] A deliberately omitted requirement is detected.
+- [ ] A deliberately false “all tests passed” claim is rejected when evidence disagrees or is absent.
+- [ ] A skipped mandatory check cannot produce `verified`.
+- [ ] Scope drift is reported with changed paths and a contract reference.
+- [ ] Retry limits prevent unbounded corrective loops.
+- [ ] Human exceptions are explicit and visible in the final report.
+- [ ] Reports can be read without Proofline running.
+- [ ] Offline tests and end-to-end tests pass in CI.
+- [ ] Security review covers command execution, secrets, path handling, and adapter trust.
+
+## Change control
+
+A requirement may be changed only with a recorded rationale, impact assessment, updated acceptance evidence, and (for architectural or trust-boundary changes) an ADR. The implementing agent cannot silently weaken the contract it is being evaluated against.

package/docs/03-domain-model.md

@@ -0,0 +1,43 @@
+# 03 — Domain model and terminology
+
+## Core entities
+
+- **Task contract:** accepted statement of scope, acceptance criteria, exclusions, constraints, required checks, risk tier, and approval rules.
+- **Run:** one bounded attempt to fulfil one frozen contract against a repository/workspace revision.
+- **Event:** timestamped observation from an adapter, runner, repository inspector, or human action.
+- **Evidence record:** normalized, attributable record of a check, diff, claim, approval, or observation.
+- **Requirement link:** mapping from a requirement to one or more implementation and verification records.
+- **Finding:** a discrepancy, risk, failure, omission, or ambiguity produced by a verifier.
+- **Exception:** explicit, attributable acceptance of a known gap or policy deviation.
+- **Gate decision:** a deterministic decision derived from contract, policy, evidence freshness, and findings.
+- **Delivery report:** portable summary of the decision, evidence, requirements coverage, exceptions, and residual risks.
+
+## Trust distinctions
+
+| Item | What it can establish | What it cannot establish alone |
+|---|---|---|
+| Agent statement | The agent asserted something | That the assertion is true |
+| Exit code | A process returned a status | That the command tested the right property |
+| Test output | A test produced the recorded output | That test coverage is sufficient |
+| Git diff | Files changed between revisions | That all changes are justified |
+| Hash/signature | Record integrity/authorship under key assumptions | Semantic correctness of the underlying work |
+| Human approval | A named actor accepted a stated risk/scope | That the risk no longer exists |
+
+## Required result vocabulary
+
+- `passed`: the configured check ran and met its explicit success condition.
+- `failed`: the configured check ran and did not meet its success condition.
+- `skipped`: the check was deliberately not run; reason required.
+- `not_run`: no execution evidence exists for this check.
+- `inconclusive`: the check ran but could not establish pass or fail.
+- `stale`: evidence applies to a different or superseded revision/context.
+- `waived`: an authorized actor explicitly accepted a named gap; never equivalent to passed.
+
+## Terminal delivery states
+
+- `verified`: all mandatory requirements and gates have fresh sufficient evidence; no unresolved mandatory finding remains.
+- `partial`: useful work is delivered, but one or more requirements remain incomplete or waived and are clearly reported.
+- `blocked`: a mandatory gate, policy, or dependency prevents delivery.
+- `unverified`: there is insufficient evidence to determine whether the contract was met.
+
+The system must never infer `verified` merely because the agent stopped or returned a success message.

package/docs/04-architecture.md

@@ -0,0 +1,79 @@
+# 04 — Architecture
+
+## Architectural rule
+
+Keep the policy and decision engine independent from the agent adapter. Agent integrations translate events and actions; they must not own the truth of the delivery decision.
+
+## Component view
+
+```mermaid
+flowchart TB
+    CLI[CLI / local API] --> CONTRACT[Contract loader and validator]
+    CLI --> RUN[Run coordinator]
+    CONTRACT --> POLICY[Policy and gate engine]
+    RUN --> ADAPTER[Agent adapter]
+    RUN --> OBS[Event observer]
+    ADAPTER --> OBS
+    OBS --> LEDGER[Evidence ledger]
+    GIT[Workspace / Git inspector] --> LEDGER
+    CHECKS[Policy-controlled check runner] --> LEDGER
+    LEDGER --> TRACE[Requirement traceability]
+    TRACE --> VERIFY[Independent verifier]
+    POLICY --> VERIFY
+    VERIFY --> RECON[Reconciliation engine]
+    RECON --> DECISION[Delivery decision]
+    DECISION --> REPORT[JSON + Markdown report]
+    RECON --> FEEDBACK[Bounded corrective feedback]
+    FEEDBACK --> RUN
+    HUMAN[Human approval] --> POLICY
+    HV[Optional HiveVault connector] -. prior context only .-> CONTRACT
+```
+
+## Logical modules
+
+1. **Contract** — schema, validation, freeze/version, approved amendments.
+2. **Run coordinator** — run lifecycle, state transitions, timeout and retry budgets.
+3. **Adapters** — vendor-specific lifecycle event and action translation.
+4. **Observer** — normalized event stream and workspace/revision observations.
+5. **Evidence ledger** — append-oriented records, references, hashes, redaction metadata.
+6. **Check runner** — allowlisted commands, controlled environment, captured outputs and exit status.
+7. **Traceability engine** — requirement-to-change-to-test/evidence graph.
+8. **Verifier** — requirement coverage, freshness, regression challenges, claim checks, policy checks.
+9. **Reconciler** — compares contract, actual diff, check outcomes, exceptions, and agent delivery claims.
+10. **Gate engine** — deterministic terminal status and policy enforcement.
+11. **Reporter** — portable Markdown and JSON output.
+12. **Optional context connector** — retrieves prior decisions from HiveVault without elevating them to current-run proof.
+
+## Dependency direction
+
+`adapters -> normalized events -> ledger -> verifier -> reconciler -> gate/report`
+
+The verifier must not depend on a particular agent SDK. The gate engine must not depend on network access, model calls, or HiveVault. Model-assisted review may be an optional signal, but it must be labelled as such and cannot override hard evidence rules.
+
+## Proposed storage
+
+MVP: local run directory with versioned JSON records and report artifacts; a small embedded database may be considered only if evidence querying proves awkward. Avoid committing secrets or large raw outputs by default. Large outputs may be stored as bounded artifacts referenced by digest and path.
+
+Suggested local layout:
+
+```text
+.proofline/
+  config.yaml
+  contracts/
+  runs/
+    <run-id>/
+      run.json
+      events.jsonl
+      evidence/
+      findings.json
+      report.json
+      report.md
+```
+
+## Architectural constraints
+
+- Evidence is append-oriented; corrections supersede earlier records.
+- Every decision records verifier/policy/schema versions.
+- Any model-generated finding is distinguishable from deterministic checks.
+- A policy change during a run is versioned and must not silently rewrite the earlier decision.
+- The final report names the workspace revision it describes.

package/docs/05-lifecycle.md

@@ -0,0 +1,47 @@
+# 05 — Task lifecycle and state machine
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Contracted: validate + accept contract
+    Contracted --> Running: start run
+    Running --> Observed: task stops / checkpoint
+    Observed --> Verifying: evidence snapshot
+    Verifying --> Reconciling: checks complete
+    Reconciling --> Correcting: actionable gap + retry budget
+    Correcting --> Running: resume agent
+    Reconciling --> AwaitingApproval: explicit exception / high-risk action
+    AwaitingApproval --> Reconciling: decision recorded
+    Reconciling --> Verified: mandatory gates satisfied
+    Reconciling --> Partial: known gaps accepted / incomplete
+    Reconciling --> Blocked: mandatory failure or policy denial
+    Reconciling --> Unverified: evidence insufficient
+    Verified --> [*]
+    Partial --> [*]
+    Blocked --> [*]
+    Unverified --> [*]
+```
+
+## State transition rules
+
+- A contract must be validated before a run can enter `Running`.
+- A run is bound to a contract version and initial workspace revision.
+- Verification uses a defined evidence snapshot; new changes invalidate evidence where relevant.
+- Any material change after verification triggers re-verification of affected gates.
+- `Verified` is reachable only when all mandatory gates pass with fresh evidence.
+- A waived requirement remains visible as waived and normally results in `Partial`, unless the contract explicitly defines it as non-mandatory before the run.
+- A policy denial cannot be converted to a pass by agent retry.
+- Retry exhaustion moves the run to `Blocked` or `Unverified` with a specific reason.
+- Human approval is scoped to a specific action or exception; it does not grant blanket future approval.
+
+## Suggested bounded retry defaults
+
+Defaults must be configurable and validated through the pilot; initial design proposal:
+- Maximum corrective cycles per run: 3.
+- Maximum repeat of the same normalized finding without meaningful evidence change: 1.
+- Every retry must identify which finding it attempts to resolve.
+- A retry does not erase prior failures; it appends new evidence and re-evaluates affected gates.
+
+These are starting defaults, not validated performance claims.

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.