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

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/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@optitransfer/proofline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-next.0",
+  "description": "Independent V&V for coding agents. The agent says done; Proofline re-runs every check against a contract, rejects claims the evidence does not support, and gates the push.",
+  "keywords": [
+    "ai-agents",
+    "llm",
+    "mcp",
+    "mcp-server",
+    "agentic-ai",
+    "claude-code",
+    "verification",
+    "validation",
+    "testing",
+    "test-automation",
+    "quality-gate",
+    "ci-cd",
+    "devops",
+    "code-review",
+    "git-hooks",
+    "audit",
+    "attestation",
+    "developer-tools",
+    "nodejs",
+    "cli"
+  ],
+  "homepage": "https://github.com/mgillr/proofline",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgillr/proofline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgillr/proofline/issues"
+  },
+  "author": "mgillr",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "bin": { "proofline": "bin/proofline.mjs" },
+  "engines": { "node": ">=22" },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "PATENTS-NONASSERT.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "demo": "node examples/demo/demo.mjs",
+    "self-gate": "node bin/proofline.mjs gate PL-SELF --skip-pushed",
+    "mcp": "node bin/proofline.mjs mcp"
+  }
+}

package/src/cache.mjs

@@ -0,0 +1,81 @@
+// Result cache: a PASS of an expensive check (command, metric) on a clean tree runs once per HEAD and is reused.
+// Opt-in per contract (defaults.reuse_results). The PASS is recorded in the evidence log; the cache file points at
+// that entry, and a result is reused only from an entry that is still in an intact chain with the same hash.
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, sha256, canon, readJson } from './util.mjs';
+import { record, readLog, verifyChain } from './evidence.mjs';
+
+/** The only verifiers whose PASS is reused. The others are cheap, or depend on the base. */
+export const REUSABLE = ['command', 'metric'];
+export const DEFAULT_MAX_AGE_H = 24;
+export const cacheDir = (root) => path.join(root, '.proofline', 'cache');
+const cacheFile = (root, key) => path.join(cacheDir(root), `${key}.json`);
+
+/** A contract's reuse settings: on only when defaults.reuse_results is true. */
+export function settings(c) {
+  const d = c.defaults || {};
+  const age = d.reuse_max_age_h;
+  return { on: d.reuse_results === true, maxAgeH: typeof age === 'number' && age > 0 ? age : DEFAULT_MAX_AGE_H, maxLoad: typeof d.max_load_per_cpu === 'number' ? d.max_load_per_cpu : undefined };
+}
+
+/** The env vars a check names: `$VAR` and `${VAR}` in its command, `{VAR}` in a metric's output_file. */
+export function namedEnv(v) {
+  const names = new Set();
+  for (const m of String(v.cmd ?? '').matchAll(/\$\{?([A-Za-z_]\w*)/g)) names.add(m[1]);
+  for (const m of String(v.output_file ?? '').matchAll(/\{(\w+)\}/g)) names.add(m[1]);
+  return [...names].sort();
+}
+
+/**
+ * The cache key of a criterion's verifier, or null when its result is neither reused nor stored: not a reusable
+ * verifier, no HEAD, or a tree that differs from HEAD outside .proofline/ (an uncommitted edit never reuses a result).
+ * The key holds the verifier (canonical JSON), HEAD, process.version and the values of the env vars the check names;
+ * for a metric also its baseline and the regression tolerance, which decide its verdict.
+ */
+export function keyFor(root, v, { baseline, tolerancePct } = {}) {
+  if (!REUSABLE.includes(v.type)) return null;
+  const head = git(['rev-parse', '--verify', '--quiet', 'HEAD'], root);
+  if (!head.ok || !head.out) return null;
+  // --untracked-files=normal: an untracked file counts even where status.showUntrackedFiles=no hides it.
+  const st = git(['status', '--porcelain', '--untracked-files=normal'], root);
+  if (!st.ok || st.out.split('\n').some((l) => l && !l.includes('.proofline/'))) return null;
+  const env = Object.fromEntries(namedEnv(v).map((n) => [n, v.env?.[n] ?? process.env[n] ?? null]));
+  const k = { verifier: v, head: head.out, node: process.version, env };
+  if (v.type === 'metric') Object.assign(k, { baseline: baseline?.[v.name || v.key] ?? null, tolerance_pct: tolerancePct ?? 20 });
+  return { key: sha256(canon(k)), head: head.out };
+}
+
+/**
+ * The evidence entry of a PASS that may be reused for `key`, or null (then the check runs). The cache file must name
+ * an entry that is in an intact chain with the hash it stored, records a PASS for this key, is no older than
+ * maxAgeH hours, and, for a metric, ran at a load per CPU within maxLoad when that is set.
+ */
+export function lookup(root, key, { maxAgeH = DEFAULT_MAX_AGE_H, maxLoad, now = Date.now() } = {}) {
+  const c = readJson(cacheFile(root, key));
+  if (!c || c.key !== key || c.status !== 'pass' || !Number.isInteger(c.entry)) return null;
+  let e;
+  try { if (!verifyChain(root).ok) return null; e = readLog(root)[c.entry]; } catch { return null; }
+  if (!e || e.hash !== c.entry_hash || e.type !== 'result' || e.data?.key !== key || e.data.status !== 'pass') return null;
+  const age = now - Date.parse(e.ts);
+  if (!(age >= 0 && age <= maxAgeH * 3600e3)) return null;
+  if (e.data.type === 'metric' && typeof maxLoad === 'number' && !(e.data.evidence?.machine?.load_per_cpu <= maxLoad)) return null;
+  return e;
+}
+
+/** Record a fresh PASS in the evidence log and point the cache file for its key at that entry. Returns the entry. */
+export function store(root, { key, head }, task, a, r) {
+  const data = { task, criterion: a.id, type: a.verifier.type, key, head, status: r.status, detail: r.detail, evidence: r.evidence };
+  const e = record(root, 'result', data);
+  const f = cacheFile(root, key), tmp = `${f}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify({ ...data, ts: e.ts, entry: e.seq, entry_hash: e.hash }, null, 2) + '\n');
+  fs.renameSync(tmp, f);
+  return e;
+}
+
+/** A criterion's result taken from the evidence entry that recorded its PASS. */
+export function reusedResult(e) {
+  const from = `reused from ${e.ts} (evidence entry ${e.seq})`;
+  return { status: 'pass', detail: `${from}: ${e.data.detail}`, evidence: { ...e.data.evidence, reused_from: { ts: e.ts, entry: e.seq, hash: e.hash, head: e.data.head } }, reused: { ts: e.ts, entry: e.seq } };
+}