# VERIFY.md - Verification Subsystem

**Canonical:** plugins/VERIFY.md
**Authority:** constitution
**Layer:** Plugins
**Binding:** Yes
**Version:** v0.1.0

## Purpose

This document defines the verification subsystem for Decapod: proof-plan replay and drift detection for completed work over time.

## Verification vs Validation

**Validation (`decapod validate`):** Repo is consistent with constitution RIGHT NOW.
- Checks: provenance present, schema integrity, state machine compliance
- Scope: Current repo state
- Frequency: On-demand, pre-commit, CI

**Verification (`decapod qa verify`):** Completed work is still true OVER TIME.
- Checks: Proof-plan replay, artifact drift detection, claim staleness
- Scope: Historical completed work (TODOs, claims, decisions)
- Frequency: Periodic (daily/weekly), on-demand, post-deploy

**Separation:** Validation and verification are distinct gates. Passing validation does NOT imply verification is current.

## Contracts

### 1. Verification Targets (MVP)

**Primary:** Completed/validated TODOs with proof_plan.

A TODO marked `done` or `validated` MUST have:
- `proof_plan`: List of proofs that were satisfied at completion time
- `verification_artifacts`: Captured state (file paths, hashes, commands, results)

Verification re-executes the proof_plan and compares results against captured artifacts.

**Future:** Verifiable repo claims, knowledge records, architectural decisions.

### 2. TODO Model Extensions for Verification

Required fields (add to TODO schema v3):

```
last_verified_at: Timestamp (ISO8601, nullable)
last_verified_status: Enum (pass|fail|stale|unknown, nullable)
last_verified_notes: String (what failed or changed, nullable)
verification_policy: String (staleness threshold in days, default 90)
verification_artifacts: JSON (captured at completion time)
```

**verification_artifacts schema:**

```json
{
  "completed_at": "2026-02-13T12:00:00Z",
  "proof_plan_results": [
    {
      "proof_gate": "validate_passes",
      "status": "pass",
      "command": "decapod validate",
      "output_hash": "sha256:abc123..."
    },
    {
      "proof_gate": "tests_pass",
      "status": "pass",
      "command": "cargo test",
      "output_hash": "sha256:def456..."
    }
  ],
  "file_artifacts": [
    {
      "path": "src/core/validate.rs",
      "hash": "sha256:ghi789...",
      "size": 12345
    }
  ],
  "commit_hash": "a1b2c3d4",
  "repo_state_hash": "sha256:repo123..."
}
```

### 3. Verification Mechanics (Proof-Plan Replay)

**On TODO completion** (`decapod todo done <id>`):
1. Execute each proof in `proof_plan`
2. Capture results (status, command, output hash)
3. Capture file artifacts (paths, hashes, sizes)
4. Store in `verification_artifacts`
5. Set `last_verified_at` = now, `last_verified_status` = pass|fail based on proof outcome

**Baseline capture policy (MVP):**
- Baseline capture MUST NOT fail solely because `decapod validate` fails.
- When validate fails at capture time, the baseline is still recorded with:
  - `proof_plan_results[].status = fail` for `validate_passes`
  - `last_verified_status = fail`
  - `last_verified_notes` indicating capture occurred while validation was failing
- This preserves deterministic evidence for later drift/recovery workflows.

**On verification** (`decapod qa verify todo <id>`):
1. Re-execute each proof in `proof_plan`
2. Compare results against `verification_artifacts.proof_plan_results`
3. Check file artifacts for drift (hash mismatch, missing files)
4. Update `last_verified_at`, `last_verified_status`, `last_verified_notes`

**Drift Detection:**
- File hash changed → FAIL (drift detected)
- File missing → FAIL (artifact deleted)
- Proof command output changed → FAIL (behavior changed)
- Proof command failed (was pass) → FAIL (regression)

### 4. Staleness Threshold

**Default:** 90 days for normal TODOs, 30 days for critical TODOs.

A TODO is considered **stale** if:
- `last_verified_at` is NULL (never verified since completion)
- OR `now - last_verified_at > verification_policy` (re-verification overdue)

Stale TODOs are flagged but do not fail verification (warning only).

### 5. CLI Surface (MVP)

```bash
# Verify all due items (stale or never verified)
decapod qa verify

# Verify specific TODO
decapod qa verify todo <id>

# List items due for re-verification
decapod qa verify --stale

# Machine-readable output for CI
decapod qa verify --json

# Force verification even if not stale
decapod qa verify --force

# Show verification history for TODO
decapod qa verify todo <id> --history
```

### 6. Output Format

**Human-readable:**

```
⚡ VERIFICATION REPORT

  ℹ TODO-123: Add staleness tracking
    ● Proof: validate_passes → PASS (no drift)
    ● Proof: tests_pass → FAIL (output changed)
    ● Artifact: src/core/validate.rs → FAIL (hash mismatch)
    ✗ FAILED (1 proof failed, 1 artifact drifted)

  ℹ TODO-124: Update documentation
    ● Proof: docs_build → PASS (no drift)
    ● Artifact: README.md → PASS (no drift)
    ✓ PASSED (all proofs passed, no drift)

Summary:
  2 TODOs verified
  1 passed
  1 failed
  3 stale (not verified in >90 days)
```

**Machine-readable (--json):**

```json
{
  "verified_at": "2026-02-13T12:00:00Z",
  "summary": {
    "total": 2,
    "passed": 1,
    "failed": 1,
    "stale": 3
  },
  "results": [
    {
      "todo_id": "TODO-123",
      "status": "fail",
      "proofs": [
        {"gate": "validate_passes", "status": "pass"},
        {"gate": "tests_pass", "status": "fail", "reason": "output changed"}
      ],
      "artifacts": [
        {
          "path": "src/core/validate.rs",
          "status": "fail",
          "reason": "hash mismatch",
          "expected": "sha256:abc123...",
          "actual": "sha256:xyz789..."
        }
      ]
    }
  ]
}
```

### 7. Integration with Validation (Optional)

**Validation MAY warn/fail** if:
- Critical validated TODOs are stale (>30 days unverified)
- TODOs in `done` state lack verification_artifacts

This is **configurable** (not mandatory) and staged:
- Phase 1: Verification is separate (no validation integration)
- Phase 2: Validation warns on stale verified work
- Phase 3: Validation fails on critical stale work (repo-configurable)

### 8. Storage

Verification data is stored in TODO DB:
- New fields in `tasks` table (see section 2)
- Verification history in `verification_events.jsonl` (audit log)

No separate verification.db (keep it integrated).

### 9. Governance

**Who can mark as verified?**
- Automated: `decapod qa verify` (re-runs proofs)
- Manual: `decapod qa verify todo <id> --manual --notes "<reason>"` (with audit trail)

**Who can waive verification failures?**
- `decapod qa verify todo <id> --waive --reason "<text>"` (sets status=pass despite failures, logged)

**Audit trail:**
- All verification runs logged to `verification_events.jsonl`
- Includes: timestamp, TODO ID, status, proof results, artifacts checked, waiver reason (if any)

### 10. Proof-Plan Contract

A `proof_plan` is a list of proof gates that must pass. Each gate is either:
- A validation gate (e.g., `validate_passes`)
- A test command (e.g., `cargo test`)
- A build command (e.g., `cargo build`)
- A file invariant (e.g., `file_exists:path/to/file`)
- A custom command (e.g., `./scripts/check_invariant.sh`)

**Proof gate format:**

```json
[
  "validate_passes",
  "test:cargo test --all",
  "build:cargo build --release",
  "file_exists:src/core/verify.rs",
  "file_hash:src/core/verify.rs:sha256:abc123...",
  "cmd:./scripts/check.sh"
]
```

Each gate is a string in format `type:details` or just `type` for known gates.

### 11. Failure Modes & Recovery

**Verification fails:**
- TODO `last_verified_status` = fail
- Output shows which proofs/artifacts failed
- Human reviews, fixes issues, re-runs `decapod qa verify todo <id>`

**Verification blocked (missing artifacts):**
- If `verification_artifacts` is NULL/empty, verification cannot run
- Status = unknown (never verified)

**Validation failing at baseline-capture time:**
- Capture still records artifacts and proof outputs (non-blocking)
- Status is recorded as fail (not pass)
- Remediation is to restore validation health and re-run verification
- Must complete TODO with artifact capture first

**Stale verification:**
- Warning only (does not fail)
- Human decides: re-verify now, extend threshold, or waive

### 12. Constitutional Authority

This subsystem defers to:
- `core/CONTROL_PLANE.md` — Operational contract
- `specs/SYSTEM.md` — Authority and proof doctrine
- `plugins/TODO.md` — TODO lifecycle and state model
- `specs/TODO_MODEL.md` — TODO schema definition

### 13. Non-Negotiable

- **Verification is separate from validation** (different gates, different purposes)
- **Proof-plan replay is deterministic** (same inputs → same outputs, or drift detected)
- **Drift detection is mandatory** (cannot ignore artifact changes)
- **Audit trail required** (all verification runs logged)
- **No silent failures** (output must be actionable, pointing to exact TODO/proof/artifact)

### See Also

- `core/CONTROL_PLANE.md` — Operational contract
- `specs/SYSTEM.md` — Authority and proof doctrine
- `plugins/TODO.md` — TODO subsystem
- `specs/TODO_MODEL.md` — TODO schema

---

## Links

### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**

### Authority (Constitution Layer)
- `specs/INTENT.md` - **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` - System definition and authority doctrine
- `specs/SECURITY.md` - Security contract

### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index

### Contracts (Interfaces Layer)
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns
- `interfaces/TESTING.md` - Testing contract
- `interfaces/CLAIMS.md` - Promises ledger

### Practice (Methodology Layer)
- `methodology/SOUL.md` - Agent identity

### Operations (Plugins Layer - This Subsystem)
- `plugins/TODO.md` - Work tracking
- `plugins/MANIFEST.md` - Canonical vs derived vs state
