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

package/bin/proofline.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// Proofline CLI. Exit codes: 0 PASS/ok, 1 FAIL, 2 BLOCKED, 3 usage error.
+import fs from 'node:fs';
+import path from 'node:path';
+import * as P from '../src/index.mjs';
+import { verifyChain, readLog } from '../src/evidence.mjs';
+import { verifyReceipt } from '../src/verify-receipt.mjs';
+import { buildReceipt } from '../src/receipt.mjs';
+import { connectClaudeCode, hookStop } from '../src/hook-stop.mjs';
+import * as G from '../src/guided.mjs';
+import * as S from '../src/signature.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);
+
+function ownerGate(root) {
+  const r = S.verifyContractSignature(root);
+  if (!r.armed || r.ok) return true;
+  console.error(`proofline: contract not owner-signed\n${r.detail}`);
+  process.exitCode = 2;
+  return false;
+}
+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
+  setup [--agent claude-code|none]      init, hooks, the owner key, approvals at .proofline/approvals
+  task "<plain words>"                  write a proposal from those words and print its hash
+  contract approve [<hash>]             show the diff; on y write the marker and apply the bytes
+  contract sign                          write proofline.json.sig with the owner key
+  contract verify-sig                    check the owner signature
+  contract propose                       write proposals/<sha256>.diff and print the hash
+  watch [TASK]                          print the active task until the gate is PASS
+  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 scaffold --title ... --scope a,b [--kind feature|docs|release] [--id TASK]
+                                        print a task with the standard criteria and stop rules
+  contract merge <fragment.json> [--owners a=b,c=d]
+                                        append tasks and new owner rules; prints the sha256
+  contract coverage <REQUIREMENTS.md> [--contracts a.json,b.json]
+                                        one line per requirement id, or MISSING
+  contract validate | show              validate also warns when a grep already matches on the base revision
+  next [--owner <name>] [--base <rev>]  the single next task with its full brief (marks it active);
+                                        --owner limits the lane; --base re-pins the base
+  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
+  verify-receipt <envelope> [--keys <dir>] [--sigstore] [--recompute --base <sha>]
+                                        exit 0 verified, 1 failed or differs, 2 unknown key, 3 usage
+  receipt [--role <name>] [--base <rev>] [--vault]
+                                        one receipt for the revision; --vault writes the note when a daemon answers
+  hook pre-commit|pre-push              (used by git hooks)
+  hook stop                             read a Stop hook payload on stdin; one receipt for new commits, or silence
+  connect claude-code                   merge a Stop hook into ~/.claude/settings.json, after any hook already there
+  mcp                                   MCP server on stdio
+Global: --json  --root <dir>   Exit: 0 PASS, 1 FAIL, 2 BLOCKED, 3 usage`;
+
+const GLOBAL_FLAGS = ['json', 'root'];
+const ACCEPTED_FLAGS = {
+  setup: ['agent'],
+  task: [],
+  init: ['approvals', 'no-hooks'],
+  'contract create': ['from', 'id', 'title', 'phase', 'owner', 'description', 'depends', 'scope'],
+  'contract merge': ['owners'],
+  'contract coverage': ['contracts'],
+  'contract scaffold': ['title', 'scope', 'kind', 'id'],
+  'contract approve': [],
+  'contract sign': [],
+  'contract verify-sig': [],
+  'contract propose': [],
+  'contract validate': ['base'],
+  'contract show': [],
+  next: ['owner', 'base'],
+  brief: ['owner', 'base'],
+  verify: ['claims', 'claims-file', 'base', 'fresh'],
+  gate: ['claims', 'claims-file', 'base', 'fresh', 'all', 'ci', 'skip-pushed'],
+  report: [],
+  status: ['owner'],
+  'evidence record': ['data'],
+  'evidence verify': [],
+  'evidence log': [],
+  'verify-receipt': ['keys', 'sigstore', 'recompute', 'base'],
+  receipt: ['base', 'role', 'task', 'vault'],
+  hook: [],
+  watch: [],
+  connect: [],
+  mcp: [],
+};
+
+function refuseUnknownFlags(cmd, sub) {
+  if (!cmd) return;
+  const key = sub ? `${cmd} ${sub}` : cmd;
+  const accepted = ACCEPTED_FLAGS[key] ?? ACCEPTED_FLAGS[cmd];
+  if (!accepted) return;
+  const allow = new Set([...GLOBAL_FLAGS, ...accepted]);
+  const bad = Object.keys(flags).filter((k) => !allow.has(k));
+  if (!bad.length) return;
+  const named = bad.map((k) => `--${k}`).join(', ');
+  const ok = [...allow].sort().map((k) => `--${k}`).join(', ');
+  console.error(`proofline: unknown flag ${named}\naccepted: ${ok}`);
+  process.exit(2);
+}
+
+try {
+  const [cmd, sub] = pos;
+  refuseUnknownFlags(cmd, sub);
+  switch (cmd) {
+    case 'setup': {
+      const agent = flags.agent === undefined ? 'none' : flags.agent;
+      if (agent === true) throw new Error('unknown agent\nNext step: proofline setup --agent none');
+      process.stdout.write(G.setup(root, { agent: String(agent) }));
+      break;
+    }
+    case 'task': {
+      process.stdout.write(G.task(root, pos.slice(1).join(' ')));
+      break;
+    }
+    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 loaded = P.C.load(root);
+        const { errors, warnings } = P.C.lint(loaded, { root, base: base() || P.C.defaultBase(loaded) });
+        const lines = [...errors, ...warnings.map((w) => `warning: ${w}`)];
+        print({ valid: !errors.length, problems: errors, warnings }, lines.length ? lines.join('\n') : 'contract valid');
+        process.exitCode = errors.length ? 1 : 0;
+      } else if (sub === 'merge') {
+        const frag = pos[2];
+        if (!frag) throw new Error('contract merge needs a fragment file');
+        const owners = flags.owners && flags.owners !== true ? String(flags.owners) : '';
+        const out = P.C.mergeContract(root, path.resolve(root, frag), { owners });
+        print(out, out.sha256);
+      } else if (sub === 'coverage') {
+        const req = pos[2];
+        if (!req) throw new Error('contract coverage needs a requirements file');
+        const contracts = flags.contracts && flags.contracts !== true ? String(flags.contracts).split(',').map((s) => s.trim()).filter(Boolean) : [];
+        const out = P.C.coverageReport(root, path.resolve(root, req), { contracts: contracts.map((f) => path.resolve(root, f)) });
+        print(out, out.lines.join('\n'));
+        process.exitCode = out.ok ? 0 : 1;
+      } else if (sub === 'scaffold') {
+        if (typeof flags.title !== 'string') throw new Error('scaffold needs --title');
+        if (typeof flags.scope !== 'string') throw new Error('scaffold needs --scope');
+        const kind = flags.kind && flags.kind !== true ? String(flags.kind) : 'feature';
+        const id = typeof flags.id === 'string' ? flags.id : 'TASK';
+        const task = P.C.scaffoldTask({ title: flags.title, scope: flags.scope, kind, id });
+        print(task, JSON.stringify(task, null, 2));
+      }
+      else if (sub === 'sign') process.stdout.write(S.signContract(root));
+      else if (sub === 'verify-sig') {
+        const r = S.verifyContractSignature(root);
+        if (!r.ok) { console.error(`proofline: contract not owner-signed\n${r.detail}`); process.exitCode = 2; }
+        else process.stdout.write(`${r.detail}\n`);
+      }
+      else if (sub === 'propose') process.stdout.write(S.proposeContract(root));
+      else if (sub === 'approve') {
+        process.stdout.write(G.approve(root, pos[2]));
+      }
+      else if (sub === 'show') print(P.C.load(root));
+      else { console.error(HELP); process.exitCode = 3; }
+      break;
+    }
+    case 'next': {
+      if (!ownerGate(root)) break;
+      const n = P.taskNext(root, { owner: owner(), ...(flags.base === undefined ? {} : { base: base() }) }); print(n, n.brief || n.message); break;
+    }
+    case 'brief': {
+      if (!ownerGate(root)) break;
+      const b = P.taskBrief(root, sub, { owner: owner(), base: base() }); print({ brief: b }, b); break;
+    }
+    case 'verify': case 'gate': {
+      if (!ownerGate(root)) break;
+      const requested = sub;
+      const settled = P.settleLanded(root);
+      if (settled && !flags.all && !flags.ci && (!requested || requested === settled.task)) {
+        print({ landed: true, task: settled.task }, settled.message);
+        break;
+      }
+      const c = P.C.load(root);
+      const ids = flags.all ? c.tasks.map((t) => t.id) : flags.ci ? (c.ci?.tasks || []) : [requested || P.activeTask(root)].filter(Boolean);
+      if (!ids.length) {
+        if (flags.ci) {
+          // Clearing ci.tasks is still a contract change. Refuse it before the empty-list short-circuit.
+          const refusal = P.E.unapprovedContractChange(root, base());
+          if (refusal) { print({ decision: 'BLOCKED', blocked: [refusal] }, `${refusal}\n\nDECISION: BLOCKED`); process.exitCode = 2; break; }
+          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';
+      const note = settled ? `${settled.message}\n\n` : '';
+      print(outs.length === 1 ? outs[0] : { decision: worst, gates: outs.map((o) => ({ task: o.task, decision: o.decision, failing: o.failing, blocked: o.blocked })) },
+        note + 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 'verify-receipt': {
+      if (!sub) { console.error(HELP); process.exitCode = 3; break; }
+      const r = await verifyReceipt(sub, {
+        root, keys: flags.keys === true ? undefined : flags.keys, sigstore: flags.sigstore === true,
+        recompute: flags.recompute === true, base: flags.base === true ? undefined : flags.base,
+      });
+      print(r, r.message);
+      process.exitCode = r.exitCode;
+      break;
+    }
+    case 'receipt': {
+      const r = await buildReceipt(root, {
+        base: flags.base === true ? undefined : flags.base,
+        role: flags.role === true ? undefined : flags.role,
+        task: flags.task === true ? undefined : flags.task,
+        vault: flags.vault === true,
+      });
+      print(r);
+      break;
+    }
+    case 'hook': {
+      if ((sub === 'pre-commit' || sub === 'pre-push') && !ownerGate(root)) break;
+      if (sub === 'stop') {
+        let payload = {};
+        try {
+          const raw = fs.readFileSync(0, 'utf8');
+          if (raw.trim()) payload = JSON.parse(raw);
+        } catch { break; }
+        const where = flags.root ? root : (payload.cwd || root);
+        const out = await hookStop(where, payload);
+        if (out.receipts.length === 1) print(out.receipts[0]);
+        break;
+      }
+      let lines;
+      if (sub === 'pre-push' && !process.stdin.isTTY) lines = fs.readFileSync(0, 'utf8').split('\n').filter((l) => l.trim());
+      const pushUrl = typeof pos[3] === 'string' ? pos[3] : undefined;
+      const r = sub === 'pre-commit' ? P.hookPreCommit(root) : sub === 'pre-push' ? P.hookPrePush(root, { lines, pushUrl }) : 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; }
+      else if (r.msg) console.error(r.msg);
+      break;
+    }
+    case 'watch': {
+      process.exitCode = G.watch(root, sub);
+      break;
+    }
+    case 'connect': {
+      if (sub !== 'claude-code') { console.error(HELP); process.exitCode = 3; break; }
+      const r = connectClaudeCode();
+      if (!r.ok) { console.error(`proofline connect: ${r.reason}`); process.exitCode = 1; break; }
+      print(r, `hook installed in ${r.file}`);
+      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`.

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.