feature: Evidence Freshness Management (FPF B.3.4)

Author: m0n0x41d

CHANGELOG.md

@@ -87,6 +87,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Added SQL indexes for efficient WLNK traversal.
   - Documented structural relations (B.1.1) in CLAUDE.md.
 
+- **Evidence Freshness Management (FPF B.3.4)**:
+  - New `waivers` table for tracking temporary risk acceptance with full audit trail.
+  - `quint_check_decay` now supports three modes:
+    - **Report mode** (default): Shows freshness report with STALE/FRESH/WAIVED holons.
+    - **Deprecate mode**: Downgrades hypothesis (L2→L1 or L1→L0) when evidence is terminally stale.
+    - **Waive mode**: Records explicit risk acceptance with rationale and expiration date.
+  - `quint_test` now accepts L2 hypotheses for evidence refresh (L2 + PASS stays L2 with fresh evidence).
+  - Freshness report now shows individual evidence IDs (not just counts) for actionable output.
+  - Implements WLNK principle: one expired evidence item = entire holon is STALE.
+  - Updated command documentation: `q-decay.md` and `q3-validate.md`.
+
 - **CI/CD Pipeline**:
   - New GitHub Actions workflow (`.github/workflows/ci.yml`) for pull requests.
   - Triggers on PRs and pushes to `main` and `dev` branches.

src/mcp/cmd/commands/q-decay.md

@@ -1,33 +1,258 @@
-# q-decay: Assurance Maintenance
+# q-decay: Evidence Freshness Management
 
 ## Intent
-Identifies **Epistemic Debt (ED)** by finding holons with expired evidence that need re-validation.
 
-## Action (Run-Time)
-1.  Call `quint_check_decay` to get a report of all holons with expired evidence.
-2.  Review the output - it shows:
-    -   Which holons have stale evidence
-    -   How many evidence items are expired
-    -   How many days overdue
-3.  Present findings to the user with recommendations.
+Manages **evidence freshness** by identifying stale decisions and providing governance actions. Implements FPF B.3.4 (Evidence Decay).
 
-## Tool Guide
+**Key principle:** Evidence is perishable. Decisions built on expired evidence carry hidden risk.
+
+---
+
+## Quick Concepts
+
+### What is "stale" evidence?
+
+Every piece of evidence has a `valid_until` date. A benchmark from 6 months ago may no longer reflect current system performance. A security audit from before a major dependency update doesn't account for new vulnerabilities.
+
+When evidence expires, the decision it supports becomes **questionable** — not necessarily wrong, just unverified.
+
+### What is "waiving"?
+
+**Waiving = "I know this evidence is stale, I accept the risk temporarily."**
+
+Use it when:
+- You're about to launch and don't have time to re-run all tests
+- The evidence is only slightly expired and probably still valid
+- You have a scheduled date to refresh it properly
+
+A waiver is NOT ignoring the problem — it's **explicitly documenting** that you know about the risk and accept it until a specific date.
+
+### The Three Actions
+
+| Situation | Action | What it does |
+|-----------|--------|--------------|
+| Evidence is old but decision is still good | **Refresh** | Re-run the test, get fresh evidence |
+| Decision is obsolete, needs rethinking | **Deprecate** | Downgrade hypothesis, restart evaluation |
+| Accept risk temporarily | **Waive** | Record the risk acceptance with deadline |
+
+---
+
+## Natural Language Usage
+
+**You don't need to memorize evidence IDs or tool parameters.** Just describe what you want.
+
+### Example Workflow
+
+```
+User: /q-decay
+
+Agent shows report:
+## Evidence Freshness Report
+
+### STALE (1 holon requires action)
+
+#### Use Redis for Caching (L2)
+| ID | Type | Status | Details |
+|----|------|--------|---------|
+| ev-benchmark-2024-06-15 | validation | EXPIRED | 180 days overdue |
+| ev-load-test-2024-06-20 | validation | EXPIRED | 175 days overdue |
+
+Actions:
+  → Refresh: /q3-validate hypothesis-redis-caching
+  → Deprecate: Tell me to deprecate this decision
+  → Waive: Tell me which evidence to waive and until when
+```
+
+Now the user can respond naturally:
+
+```
+User: Waive the benchmark until February, we'll re-run it after the migration.
+```
+
+The agent reads the context, finds the matching evidence ID, and calls:
+```
+quint_check_decay(
+    waive_id: "ev-benchmark-2024-06-15",
+    waive_until: "2025-02-01",
+    waive_rationale: "Will re-run after the migration"
+)
+```
+
+**You don't need to copy IDs. Just reference what you mean.**
+
+### More Natural Examples
+
+```
+User: /q-decay
+
+[sees report with stale evidence]
+
+User: We're launching next week. Waive everything until January 15th,
+      we have a full test cycle scheduled for January 20th.
+
+Agent: I'll waive both pieces of expired evidence until 2025-01-15
+       with rationale "Launch deadline, full test cycle scheduled Jan 20"
+
+       [calls quint_check_decay for each]
+
+---
+
+User: The vendor API is being discontinued. Deprecate that decision.
+
+Agent: Deprecating hypothesis-vendor-api from L2 to L1.
+       You'll need to run /q1-hypothesize to explore alternatives.
+
+---
+
+User: The load test is only 2 weeks overdue, I think it's still valid.
+      Can we just refresh it?
+
+Agent: Running /q3-validate to refresh the evidence for hypothesis-redis-caching.
+       [calls quint_test]
+```
+
+---
+
+## How Evidence IDs Work
+
+Evidence IDs are generated automatically when tests run:
+- Format: `ev-{type}-{date}` (e.g., `ev-benchmark-2024-06-15`)
+- Shown in the freshness report
+- **You don't need to remember them** — describe what you want, the agent finds the right ID
+
+If you want to be explicit, you can use the full syntax:
+```
+User: /q-decay --waive ev-benchmark-2024-06-15 --until 2025-02-01 --rationale "Migration pending"
+```
+
+But natural language works fine:
+```
+User: Waive the benchmark until February, migration is pending.
+```
+
+---
+
+## Detailed Actions
+
+### Refresh (via /q3-validate)
+
+**When:** Evidence is stale, but the decision is still correct. You just need fresh proof.
+
+**What happens:**
+1. Agent calls `quint_test` on the hypothesis
+2. New evidence is recorded with a fresh `valid_until` date
+3. Holon status changes from STALE to FRESH
+
+**Example:**
+```
+User: The Redis benchmark is 6 months old but Redis is still the right choice.
+      Can we refresh the evidence?
+
+Agent: Running validation for hypothesis-redis-caching...
+       [executes benchmark]
+       Evidence refreshed. Hypothesis remains at L2 with fresh evidence valid until 2025-06-21.
+```
+
+### Deprecate
+
+**When:** The decision itself is questionable. The world has changed, you need to reconsider.
+
+**What happens:**
+1. Hypothesis moves down one level (L2→L1 or L1→L0)
+2. Audit log records who deprecated it and why
+3. You're prompted to run `/q1-hypothesize` to explore alternatives
+
+**Example:**
+```
+User: AWS announced they're deprecating this service. Deprecate our decision to use it.
+
+Agent: Deprecated: hypothesis-aws-service L2 → L1
+
+       This decision now requires re-evaluation.
+       Next step: Run /q1-hypothesize to explore alternatives.
+```
+
+### Waive
+
+**When:** You know the evidence is stale, you accept the risk temporarily.
+
+**What happens:**
+1. Waiver is recorded with: who, until when, why
+2. Evidence no longer shows as STALE (shows as WAIVED)
+3. When waiver expires, evidence returns to STALE status
+4. Full audit trail preserved
+
+**Example:**
+```
+User: We're launching Tuesday. Waive the security audit until the 15th,
+      we have a re-audit scheduled for the 20th.
+
+Agent: Waiver recorded:
+       - Evidence: ev-security-audit-2024-03
+       - Waived until: 2025-01-15
+       - Rationale: Launch deadline. Re-audit scheduled for the 20th.
+
+       ⚠️ This evidence returns to EXPIRED status after 2025-01-15.
+```
+
+---
+
+## Tool Reference (for understanding, not memorization)
 
 ### `quint_check_decay`
-Scans all evidence and identifies expired items. Implements **Evidence Decay (B.3.4)**.
--   *No parameters required.*
--   *Returns:* Markdown report listing:
-    -   Holons with expired evidence
-    -   Count of expired evidence per holon
-    -   Days overdue
-    -   Recommendation to run `/q3-validate` for affected holons
-
-## Example
-User: `/q-decay`
-
-Agent calls:
-1.  `quint_check_decay()`
-
-If expired evidence is found, recommend:
--   Run `/q3-validate <hypothesis_id>` to refresh evidence
--   Or run `/q4-audit <hypothesis_id>` to reassess reliability
+
+The agent translates your natural language into these parameters:
+
+| Parameter | What it means |
+|-----------|--------------|
+| (none) | Show the freshness report |
+| `deprecate` | Which hypothesis to downgrade |
+| `waive_id` | Which evidence to waive |
+| `waive_until` | When the waiver expires (YYYY-MM-DD) |
+| `waive_rationale` | Why you're accepting this risk |
+
+---
+
+## WLNK Principle
+
+A holon is **STALE** if *any* of its evidence is expired (and not waived).
+
+This is the Weakest Link (WLNK) principle: reliability = min(all evidence). One stale piece makes the whole decision questionable.
+
+---
+
+## Audit Trail
+
+All actions are logged for accountability:
+
+| Action | What's Recorded |
+|--------|-----------------|
+| Deprecate | from_layer, to_layer, who, when |
+| Waive | evidence_id, until_date, rationale, who, when |
+
+Waivers are stored in a dedicated table — you can query "who waived what and why" at any time.
+
+---
+
+## Common Workflows
+
+### Weekly Maintenance
+```
+/q-decay                    # See what's stale
+# For each stale item, tell the agent: refresh, deprecate, or waive
+```
+
+### Pre-Release
+```
+/q-decay                    # Check for stale decisions
+# Either refresh evidence or explicitly waive with documented rationale
+# Waiver rationales become part of release documentation
+```
+
+### After Major Change
+```
+# Dependency update, API change, security advisory...
+/q-decay                    # See what's affected
+# Deprecate obsolete decisions
+# Start new hypothesis cycle for replacements
+```

src/mcp/cmd/commands/q3-validate.md

@@ -1,14 +1,16 @@
 ---
 description: "Validate (Induction)"
-pre: ">=1 L1 hypothesis exists"
-post: "each L1 processed → L2 (PASS) or invalid (FAIL) or L1 with feedback (REFINE)"
+pre: ">=1 L1 or L2 hypothesis exists"
+post: "L1 processed → L2 (PASS) or invalid (FAIL) or L1 with feedback (REFINE); L2 processed → refreshed evidence"
 invariant: "test_type ∈ {internal, external}; verdict ∈ {PASS, FAIL, REFINE}"
 required_tools: ["quint_test"]
 ---
 
 # Phase 3: Induction (Validation)
 
-You are the **Inductor** operating as a **state machine executor**. Your goal is to gather **Empirical Validation (EV)** for the L1 hypotheses to promote them to L2.
+You are the **Inductor** operating as a **state machine executor**. Your goal is to gather **Empirical Validation (EV)** for L1 hypotheses to promote them to L2.
+
+**Also serves as the REFRESH action** in the Evidence Freshness governance loop (see `/q-decay`).
 
 ## Enforcement Model
 
@@ -17,25 +19,27 @@ You are the **Inductor** operating as a **state machine executor**. Your goal is
 | Precondition | Tool | Postcondition |
 |--------------|------|---------------|
 | L1 hypothesis exists | `quint_test` | L1 → L2 (PASS) or → invalid (FAIL) |
+| L2 hypothesis exists (refresh) | `quint_test` | L2 → L2 with fresh evidence |
 
 **RFC 2119 Bindings:**
-- You MUST have at least one L1 hypothesis before calling `quint_test`
-- You MUST call `quint_test` for EACH L1 hypothesis you want to validate
+- You MUST have at least one L1 or L2 hypothesis before calling `quint_test`
+- You MUST call `quint_test` for EACH hypothesis you want to validate or refresh
 - You MUST NOT call `quint_test` on L0 hypotheses — they must pass Phase 2 first
 - You SHALL specify `test_type` as "internal" (code test) or "external" (research/docs)
 - Verdict MUST be exactly "PASS", "FAIL", or "REFINE"
 
-**If precondition fails:** Tool returns BLOCKED with message "hypothesis not found in L1". This is NOT a bug — it means you skipped Phase 2.
+**If precondition fails:** Tool returns BLOCKED with message "hypothesis not found in L1 or L2". This is NOT a bug — it means you skipped Phase 2.
 
-**CRITICAL:** If you receive "not found in L1", you MUST NOT retry with the same hypothesis. Go back to Phase 2 first.
+**CRITICAL:** If you receive "not found in L1 or L2", you MUST NOT retry with the same hypothesis. Go back to Phase 2 first.
 
 ## Invalid Behaviors
 
 - Calling `quint_test` on L0 hypothesis (WILL BE BLOCKED)
 - Calling `quint_test` on hypothesis that doesn't exist
 - Stating "validated via testing" without tool call
 - Proceeding to `/q4-audit` with zero L2 hypotheses
-- Attempting to validate a hypothesis that's already in L2
+
+**Note:** Calling `quint_test` on L2 hypotheses is now VALID — it refreshes their evidence for the freshness governance loop.
 
 ## Context
 We have substantiated hypotheses (L1) that passed logical verification. We need evidence that they work in reality.
@@ -105,10 +109,25 @@ Result: Hypothesis remains L1. Phase 4 will find no L2 to audit. PROTOCOL VIOLAT
 ## Checkpoint
 
 Before proceeding to Phase 4, verify:
-- [ ] Queried L1 hypotheses (not L0, not L2)
+- [ ] Queried L1 hypotheses (not L0)
 - [ ] Called `quint_test` for EACH L1 hypothesis
 - [ ] Each call returned success (not BLOCKED)
 - [ ] At least one verdict was PASS (creating L2 holons)
 - [ ] Used valid test_type values (internal/external)
 
 **If any checkbox is unchecked, you MUST complete it before proceeding.**
+
+---
+
+## Evidence Refresh (L2 → L2)
+
+When called with an L2 hypothesis, `quint_test` adds fresh evidence without changing the layer.
+
+**Use case:** `/q-decay` shows stale evidence on an L2 holon. Run `/q3-validate <hypothesis_id>` to refresh.
+
+| Current Layer | Verdict | Outcome |
+|---------------|---------|---------|
+| L1 | PASS | Promotes to L2 |
+| L1 | FAIL | Stays L1 |
+| L2 | PASS | Stays L2, fresh evidence added |
+| L2 | FAIL | Stays L2, failure recorded, consider `/q-decay --deprecate` |