musememory 2.3.0 → 3.0.0

package/.agents/plans/2026-10-20-wave-22-failure-attribution-negative-mining-design.md

@@ -0,0 +1,198 @@
+# 🏛️ Wave 22 Design Specification: Failure Attribution & Negative Memory Mining
+
+> **Version Target**: `v2.11.0`  
+> **Status**: APPROVED SPECIFICATION  
+> **Date**: 2026-10-20  
+> **Author**: Muse (Chief Agency Orchestrator) & Nexus (Quality Gate)  
+> **Tracked Tickets**: `T-313`, `T-144`, `T-314`, `T-315`  
+> **Related Epics**: R17b (Ecosystem Teardown), v2 Gap Audit, LangMem Frequency Modeling
+
+---
+
+## 1. Executive Summary & Goals
+
+Wave 22 hardens Muse Memory's cognitive learning and retrieval quality loops across four foundational axes:
+
+1. **Scoped Failure Attribution (`T-313`)**: Scopes command and test regressions (`isRegression = exitCode !== 0`) strictly to memories with matching code anchors, affected paths, or specific symbols. Replaces the naive 3-strike immediate demotion with session-deduplicated strikes and a dual-decay counter (2 clean runs or 30 days), protecting innocent architectural guidelines and preferences from false-positive disputes.
+2. **Trajectory Fix-Pair Mining (`T-144`)**: Detects sequential trajectories of `Error ➔ Remediation ➔ No Recurrence` across session observations. Distills them into candidate negative memories (`AVOID: ...`) with sanitized error reasons, verified alternatives, and template-safe reproduction commands.
+3. **Source-Tagged Recall Hits & HOT.md (`T-314`)**: Connects the compiled `.memory/HOT.md` working cache directly into the retrieval engine, tagging candidate hits with origin channels (`hot`, `fts`, `vector`, `tree`, `distilled`) and applying relevance-gated provenance bonuses.
+4. **LangMem Frequency Rank Axis (`T-315`)**: Upgrades linear access counters to a mathematically bounded logarithmic frequency curve, blending retrieval frequency with verified application success.
+
+---
+
+## 2. Invariants & Guardrails
+
+- **Zero External Daemons**: All attribution, distillation, and scoring executes in-process via Bun and SQLite (`memory.db`).
+- **Constitutional Protection Gate**: Memories marked with `type: "constraint"`, `temporal_mode: "timeless"`, or `salience >= 0.95` can never be auto-disputed by automated test evaluations.
+- **Vibeguard Secret Defense**: All mined error snippets, terminal commands, and failure logs are scrubbed via `scanSecrets` before candidate creation or audit logging.
+- **Template-Safe Test Commands (`T-001`)**: Reproduction commands must strictly conform to allowed safe templates (`bun test <relative-file>`, `bunx tsc --noEmit`, `node --check <file>`); arbitrary shell commands are kept strictly in documentation text.
+- **Zero-Migration Compatibility**: New utility metrics live safely within the existing `data` JSON blob and lazily backfill on access without altering SQLite table structures.
+
+---
+
+## 3. Detailed Component Architecture
+
+### Section 1: Scoped Failure Attribution & Decaying Strike Engine (`T-313`)
+
+#### 1.1 Relevance Detection (`isMemoryRelevantToFailure`)
+In `src/learning/feedback.ts`:
+```typescript
+export interface FailureRelevanceContext {
+  command?: string;
+  logs?: string;
+  exitCode: number;
+  project: string;
+}
+
+export function isMemoryRelevantToFailure(
+  entry: MemoryEntry,
+  context: FailureRelevanceContext,
+): boolean;
+```
+A memory is relevant to a failure if and only if:
+1. **Code Anchors**: Any anchor file or symbol in `entry.anchors` matches the failure context using word boundaries:
+   - File match: `matchesWordBoundary(context.command + " " + context.logs, anchor.file)` or exact basename match.
+   - Symbol match: Symbol has `calculateSymbolSpecificity(anchor.symbol) > 0.3` and `matchesWordBoundary(context.logs, anchor.symbol)`.
+2. **Affected Paths**: Any path in `entry.graph?.affected_paths` matches paths referenced in `context.command` or `context.logs`.
+3. **Reproduction Command**: `entry.test_command` or `entry.negative?.reproduction_command` matches `context.command`.
+
+Memories without anchor or symbol affinity are classified as **bystanders** and are exempt from regression strikes.
+
+#### 1.2 Data Structures & Strike State
+In `src/types.ts`:
+```typescript
+export interface MemoryUtility {
+  retrieval_count: number;
+  application_count: number;
+  successful_applications: number;
+  failed_applications: number;
+  regressions: number;
+  contradictions: number;
+  reuse_success_rate: number;
+  last_applied_at?: string;
+  // Wave 22 Additions (T-313)
+  regression_strikes?: number;          // Active un-decayed corroborated strikes (0-3)
+  last_regression_at?: string;          // ISO timestamp of latest attributed failure
+  last_regression_session?: string;     // Session ID to deduplicate retry loops
+  clean_runs_since_regression?: number; // Count of clean runs since last strike
+}
+```
+
+#### 1.3 Strike Accumulation, Deduplication & Decay Dynamics
+In `src/quality/utility.ts`:
+- **Session Deduplication**: At most **1 regression strike** is added per session (or 10-minute window) per memory, regardless of how many times a test is retried in that turn.
+- **Dual Decay Ladder**:
+  - **Usage Decay**: Each consecutive successful application increments `clean_runs_since_regression`. Every **2 clean runs**, `regression_strikes = Math.max(0, regression_strikes - 1)`.
+  - **Time Decay**: If `now - last_regression_at > 30 days`, active strikes decay by 1.
+- **Demotion Threshold**:
+  - `entry.status` flips from `"confirmed"` to `"disputed"` **only if**:
+    $$\text{regression\_strikes} \ge 3 \quad \text{AND} \quad \text{entry.type} \ne \text{"constraint"} \quad \text{AND} \quad \text{entry.salience} < 0.95$$
+  - When auto-disputed, an audit event `dispute_triggered` is logged with the full strike history.
+
+---
+
+### Section 2: Trajectory Fix-Pair Mining (`T-144`)
+
+#### 2.1 The Trajectory Pattern
+Session observations in `.memory/observations.jsonl` are inspected for pairs:
+$$\text{Observation } A \text{ (Failure)} \xrightarrow{\le 5 \text{ turns}} \text{Observation } B \text{ (Success)}$$
+
+#### 2.2 Target & Command Affinity Matching
+To prevent pairing unrelated commands (e.g. `git push` network failure paired with `ls -la`), Event $B$ is validated against Event $A$:
+1. **Exclude Informational Commands**: Event $B$ cannot be a read/informational command (`ls`, `cat`, `git status`, `pwd`, `echo`, `find`).
+2. **Affinity Rules**: Event $B$ must satisfy at least one condition:
+   - Same command or file target as Event $A$ (verifying the error was cleared).
+   - Toolchain remedy verb (e.g. `bun add <pkg>`, `bun install`, package update) following a missing module/dependency error.
+   - Same test suite or script with green exit code (`exitCode === 0`).
+
+#### 2.3 Error Signature Normalization & Deduplication
+- Error messages are normalized:
+  - Strip dynamic line/column numbers (`:\d+:\d+`).
+  - Strip memory addresses, timestamps, and thread IDs.
+  - Collapse consecutive attempts of the same normalized signature into a single failure block.
+- Deduplication Hash:
+  $$\text{dedupHash} = \text{sha256}(\text{normalizedApproach} + "::" + \text{normalizedErrorSignature})$$
+
+#### 2.4 Candidate Proposal
+Via `recordNegativeLesson(store, ...)` in `src/learning/negative.ts`:
+- `title`: `AVOID: <concise summary of failed approach>`
+- `status`: `"candidate"` (never auto-promoted)
+- `salience`: 0.75
+- `temporal_mode`: `"timeless"`
+- `failed_approach`: Event $A$ command/input
+- `failure_reason`: Sanitized error text (Vibeguard-scrubbed)
+- `alternative_recommended`: Event $B$ successful remediation command
+- `source_ids`: `[eventA.id, eventB.id]`
+- `tags`: `["fix-pair", "mined-trajectory", "anti-pattern"]`
+- **Volume Cap**: Maximum **3 candidates** proposed per harvest pass.
+
+---
+
+### Section 3: Scoring Model & Retrieval Pipeline (`T-314` & `T-315`)
+
+#### 3.1 Retrieval Source Channels (`T-314`)
+```typescript
+export type RetrievalSourceChannel = "hot" | "fts" | "vector" | "tree" | "distilled";
+```
+
+#### 3.2 In-Memory HOT.md Cache
+In `src/compounding/temporal.ts`:
+- Maintain an in-memory `hotCacheState: { mtime: number; ids: Set<string> }`.
+- Check file `mtime` before reading `.memory/HOT.md`. If unchanged, return memoized `ids` in $<1\mu\text{s}$.
+
+#### 3.3 Relevance-Gated Source Bonus
+In `src/retrieval.ts`:
+- Base source weights:
+  - `hot`: $+0.20$
+  - `fts`: $+0.15$
+  - `vector`: $+0.15$
+  - `tree`: $+0.10$
+  - `distilled`: $+0.08$
+- **Relevance Gate**:
+  `sourceBonus` is applied **only if**:
+  $$\text{baseApplicability} > 0 \lor \text{bm25Match} > 0 \lor \text{exactSymbolMatch} > 0 \lor \text{semanticMatch} > 0$$
+  This prevents hot memory "zombie distraction" on totally unrelated queries.
+- Multi-channel cap: $\text{sourceBonus} \le +0.25$.
+
+#### 3.4 Logarithmic LangMem Frequency Axis (`T-315`)
+In `computeFactors` (`src/retrieval.ts`):
+- Effective Count:
+  $$\text{effectiveCount} = \text{access\_count} + 2 \times (\text{utility.successful\_applications} \mathbin{??} 0)$$
+- Frequency Curve:
+  $$\text{frequencyScore} = 0.25 \times \frac{\ln(1 + \text{effectiveCount})}{\ln(1 + 50)}$$
+- Recency Modulation:
+  - If `daysSince(last_accessed_at) <= 7`: $+0.05$ boost.
+  - If `daysSince(last_accessed_at) > 60`: frequency bonus decayed by $0.7\times$.
+- Expose `frequencyScore` and `source_channels` in `ScoreFactors` and `deriveWhyRetrieved`.
+
+---
+
+## 4. Error Handling & Audit Telemetry
+
+### 4.1 Defensive Try/Catch Wrappers
+- All failure evaluation and fix-pair mining calls run wrapped in try/catch blocks; errors emit `console.warn` and return neutral results without failing agent turns.
+- Timestamp injection (`now?: number`) is supported on all utility and evaluation methods to guarantee 100% deterministic testing.
+
+### 4.2 Structured Audit Events
+Log four distinct operations to `.memory/audit.jsonl`:
+1. `regression_strike`: Memory ID, matched anchor, failing command, strike count.
+2. `strike_decay`: Memory ID, decay reason (`clean_runs` or `time`), remaining strikes.
+3. `dispute_triggered`: Memory ID, total regressions, corroborating strike history.
+4. `fix_pair_mined`: Candidate ID, failed approach, successful remedy.
+
+---
+
+## 5. Verification & Test Plan
+
+| Test File | Target Ticket | Key Assertions |
+|---|---|---|
+| `test/failure_attribution.test.ts` | `T-313` | - Anchor/symbol match increments strike<br>- Bystander memory ignored on exit != 0<br>- 1 strike max per session retry loop<br>- 2 clean runs decay strike<br>- 30 days decay strike<br>- Constraints cannot be auto-disputed |
+| `test/fix_pair_mining.test.ts` | `T-144` | - Error + success pairs into candidate negative memory<br>- Informational commands (`ls`, `pwd`) rejected as remedies<br>- Normalized error deduplication<br>- Vibeguard secret scrubbing<br>- Session volume capped at 3 |
+| `test/source_tagging_frequency.test.ts` | `T-314`, `T-315` | - Memoized `HOT.md` candidate lookup<br>- Irrelevant hot entries receive zero bonus<br>- Logarithmic frequency curve ($0 \to 0, 5 \to \approx 0.11, \ge 50 \to 0.25$)<br>- `deriveWhyRetrieved` outputs `source:*` and `freq:*` tokens |
+
+### Gate Verification Commands
+1. `bun test test/failure_attribution.test.ts test/fix_pair_mining.test.ts test/source_tagging_frequency.test.ts`
+2. `bun test` (full suite, 527+ tests green)
+3. `bunx tsc --noEmit` (clean, 0 type errors)
+4. `bun run build` (build completes without warnings)
+5. `bun ~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts .` (0 secret leaks)

package/.agents/plans/2026-10-20-wave-22-failure-attribution-negative-mining-plan.md

@@ -0,0 +1,274 @@
+# Wave 22: Failure Attribution & Negative Memory Mining Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement scoped failure attribution with decaying strikes (T-313), trajectory fix-pair mining into candidate negative memories (T-144), source-tagged recall hits with HOT.md cache (T-314), and LangMem logarithmic frequency ranking (T-315).
+
+**Architecture:** Extend existing feedback, utility, distillation, and retrieval scoring engines in-process with zero external daemons. Keep schema backward-compatible, enforce template-gated test reproduction, and maintain sub-2ms retrieval performance.
+
+**Tech Stack:** TypeScript, Bun, SQLite (via `bun:sqlite`), FTS5, Vitest/Bun test runner.
+
+## Global Constraints
+- Pinned to Bun runtime (`bun test`, `bun run build`, `tsc --noEmit`).
+- Zero resident external daemons; all logic executes in-process.
+- Zero secret exposure: Vibeguard SecretScan on all mined error snippets and terminal commands.
+- Constitutional protection gate: `type: "constraint"`, `temporal_mode: "timeless"`, or `salience >= 0.95` can never be auto-disputed.
+- Template-gated reproduction commands: only allowlisted templates (`bun test <relative-file>`, `bunx tsc --noEmit`, `node --check <file>`) allowed as `test_command`.
+
+---
+
+### Task 1: Scoped Failure Attribution (`T-313`)
+
+**Files:**
+- Modify: `src/learning/feedback.ts`
+- Test: `test/failure_attribution.test.ts`
+
+**Interfaces:**
+- Produces: `isMemoryRelevantToFailure(entry: MemoryEntry, context: FailureRelevanceContext): boolean`
+- Updates: `evaluateSessionOutcomes(store: Store, options: SessionOutcomeEvaluationOptions): SessionOutcomeResult`
+
+- [ ] **Step 1: Write failing tests for failure relevance detection**
+Create `test/failure_attribution.test.ts` asserting:
+1. An entry with an anchor matching the failure file/symbol receives `regression: true`.
+2. An entry whose anchor does not match the failure context is classified as a bystander and does NOT receive `regression: true`.
+3. Low-specificity symbols (e.g. `id`, `get`) do not trigger false attribution.
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `bun test test/failure_attribution.test.ts`
+Expected: FAIL (cannot find `isMemoryRelevantToFailure` or bystander memory gets regression).
+
+- [ ] **Step 3: Implement `isMemoryRelevantToFailure` in `src/learning/feedback.ts`**
+Add relevance matching:
+1. Anchor file basename and symbol match via `matchesWordBoundary` with specificity $> 0.3$.
+2. Affected path match in `entry.graph?.affected_paths`.
+3. Test command match in `entry.test_command`.
+Only mark `regression = isRegression && isRelevant` in `evaluateSessionOutcomes`.
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `bun test test/failure_attribution.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/learning/feedback.ts test/failure_attribution.test.ts
+git commit -m "feat(learning): scope failure attribution to anchor-relevant memories (closes T-313 part 1)"
+```
+
+---
+
+### Task 2: Decaying Strike Engine & Constitutional Gate (`T-313`)
+
+**Files:**
+- Modify: `src/types.ts`
+- Modify: `src/quality/utility.ts`
+- Test: `test/failure_attribution.test.ts`
+
+**Interfaces:**
+- Extends: `MemoryUtility` with `regression_strikes`, `last_regression_at`, `clean_runs_since_regression`, `last_regression_session`.
+- Updates: `recordApplicationOutcome(store: Store, options: ApplicationOutcomeOptions): MemoryEntry`
+
+- [ ] **Step 1: Write failing tests for strike decay, session dedup, and constitutional gate**
+In `test/failure_attribution.test.ts`, add test cases:
+1. Re-running the failing command 3 times within the same session ID adds at most 1 strike.
+2. 2 consecutive clean applications decay active strikes by 1.
+3. Simulating 30 days passing via `now?: number` parameter decays strikes by 1.
+4. Auto-dispute triggers only when `regression_strikes >= 3`.
+5. `type: "constraint"` or `salience >= 0.95` memories are immune to auto-dispute.
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `bun test test/failure_attribution.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement decaying strikes and constitutional gate in `src/quality/utility.ts`**
+1. Add `now?: number` and `sessionId?: string` to `ApplicationOutcomeOptions`.
+2. Update `ensureUtility` with default zero fields.
+3. In `recordApplicationOutcome`:
+   - If `options.regression`: check if `last_regression_session === options.sessionId`. If not, increment `regression_strikes`. Reset `clean_runs_since_regression = 0`.
+   - If `options.success`: increment `clean_runs_since_regression`. If $\ge 2$, decay 1 strike and reset count. Also check if `now - last_regression_at > 30 days`.
+   - Auto-dispute only if `regression_strikes >= 3` AND not constraint/salience $\ge 0.95$.
+   - Log audit events `regression_strike`, `strike_decay`, and `dispute_triggered`.
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `bun test test/failure_attribution.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/types.ts src/quality/utility.ts test/failure_attribution.test.ts
+git commit -m "feat(quality): add decaying strike counter and constitutional immunity (closes T-313 part 2)"
+```
+
+---
+
+### Task 3: Trajectory Fix-Pair Mining (`T-144`)
+
+**Files:**
+- Modify: `src/learning/distill.ts`
+- Modify: `src/compaction/harvester.ts`
+- Test: `test/fix_pair_mining.test.ts`
+
+**Interfaces:**
+- Produces: `mineFixPairsFromObservations(observations: ObservationEvent[], options?: FixPairMiningOptions): FixPairCandidate[]`
+- Integrates: `distillSessionObservations` & `harvestSessionMemories` to emit candidate negative memories.
+
+- [ ] **Step 1: Write failing tests for fix-pair mining**
+Create `test/fix_pair_mining.test.ts` asserting:
+1. A failing test command followed by a green test run produces a candidate negative memory (`AVOID: ...`).
+2. Read-only commands (`ls`, `cat`, `git status`) are rejected from remedy pairing.
+3. Error signature normalization collapses repetitive compiler line-number shifts.
+4. Secret tokens in error logs are scrubbed via Vibeguard before candidate creation.
+5. Volume cap limits candidates to at most 3 per session.
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `bun test test/fix_pair_mining.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement `mineFixPairsFromObservations` in `src/learning/distill.ts`**
+1. Traverse observations window, match failure $\to$ success within $\le 5$ events.
+2. Check target affinity and exclude informational commands.
+3. Normalize error text by stripping line/column coordinates and memory addresses.
+4. Pass through `scanSecrets`.
+5. Call `recordNegativeLesson(store, { confirmed: false, ... })` with volume cap of 3.
+6. Connect into `distillSessionObservations` and `harvestSessionMemories`.
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `bun test test/fix_pair_mining.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/learning/distill.ts src/compaction/harvester.ts test/fix_pair_mining.test.ts
+git commit -m "feat(learning): add trajectory fix-pair mining into negative memories (closes T-144)"
+```
+
+---
+
+### Task 4: Source-Tagged Recall Hits & HOT.md (`T-314`)
+
+**Files:**
+- Modify: `src/compounding/temporal.ts`
+- Modify: `src/retrieval.ts`
+- Modify: `src/retrieval/ranking.ts`
+- Test: `test/source_tagging_frequency.test.ts`
+
+**Interfaces:**
+- Produces: `getHotCandidateIds(store: Store, memoryDir: string): Set<string>`
+- Extends: `ScoreFactors` with `source_channels?: RetrievalSourceChannel[]` and `sourceBonus: number`
+- Updates: `computeFactors` and `rankAndRetrieveMemories`
+
+- [ ] **Step 1: Write failing tests for HOT.md source tagging**
+Create `test/source_tagging_frequency.test.ts` asserting:
+1. Entries in `.memory/HOT.md` are tagged with channel `"hot"`.
+2. Candidates with channel `"hot"` receive $+0.20$ bonus when applicable to the query.
+3. Completely irrelevant hot entries receive $+0$ bonus (relevance gate prevents zombie distraction).
+4. `deriveWhyRetrieved` outputs `source:hot` and `source:fts`.
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `bun test test/source_tagging_frequency.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement memoized `HOT.md` lookup and source tagging**
+1. In `src/compounding/temporal.ts`: add `getHotCandidateIds` with file `mtime` memoization.
+2. In `src/retrieval/ranking.ts`: ingest `HOT.md` candidate IDs and track `candidateSources: Map<string, Set<RetrievalSourceChannel>>`.
+3. In `src/retrieval.ts`: add `sourceBonus` to `ScoreFactors` in `computeFactors`, gated on non-zero applicability.
+4. Update `deriveWhyRetrieved` with `source:*` reason tokens.
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `bun test test/source_tagging_frequency.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/compounding/temporal.ts src/retrieval.ts src/retrieval/ranking.ts test/source_tagging_frequency.test.ts
+git commit -m "feat(retrieval): wire HOT.md candidate source tagging into ranking (closes T-314)"
+```
+
+---
+
+### Task 5: LangMem Frequency Rank Axis (`T-315`)
+
+**Files:**
+- Modify: `src/retrieval.ts`
+- Modify: `src/retrieval/ranking.ts`
+- Test: `test/source_tagging_frequency.test.ts`
+
+**Interfaces:**
+- Extends: `ScoreFactors` with `frequencyScore: number`.
+- Updates: `computeFactors` with logarithmic LangMem formula.
+
+- [ ] **Step 1: Write failing tests for logarithmic frequency curve**
+In `test/source_tagging_frequency.test.ts`, assert:
+1. `access_count = 0` produces `frequencyScore = 0`.
+2. `access_count = 5` produces `frequencyScore ≈ 0.11`.
+3. `access_count >= 50` smoothly caps at `0.25`.
+4. Successful applications boost effective count $2\times$ faster than passive retrieval.
+5. Recency boost adds $+0.05$ if accessed within 7 days.
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `bun test test/source_tagging_frequency.test.ts`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement LangMem frequency curve in `src/retrieval.ts`**
+Replace linear `access_count * 0.02` with:
+$$\text{effectiveCount} = \text{access\_count} + 2 \times (\text{utility.successful\_applications} \mathbin{??} 0)$$
+$$\text{frequencyScore} = 0.25 \times \frac{\ln(1 + \text{effectiveCount})}{\ln(1 + 50)}$$
+Incorporate 7-day recency bonus and 60-day decay. Expose in `ScoreFactors` and `deriveWhyRetrieved` (`freq:high`, `freq:moderate`).
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `bun test test/source_tagging_frequency.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/retrieval.ts src/retrieval/ranking.ts test/source_tagging_frequency.test.ts
+git commit -m "feat(retrieval): implement LangMem logarithmic frequency rank axis (closes T-315)"
+```
+
+---
+
+### Task 6: Full Verification Gate & Clean Build
+
+**Files:**
+- Entire codebase
+
+- [ ] **Step 1: Run full test suite**
+Run: `bun test`
+Expected: All 85+ test files pass, 0 failures.
+
+- [ ] **Step 2: Run type check**
+Run: `bunx tsc --noEmit`
+Expected: 0 errors.
+
+- [ ] **Step 3: Run build**
+Run: `bun run build`
+Expected: Clean build, 0 warnings.
+
+- [ ] **Step 4: Run pre-ship SecretScan**
+Run: `bun ~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts .`
+Expected: 0 secrets detected.
+
+---
+
+### Task 7: Documentation & Agent Memory Synchronization (`/updatedocs` & `/updateagents`)
+
+**Files:**
+- Modify: `docs/failure-attribution-and-negative-mining.md` (new)
+- Modify: `CHANGELOG.md`
+- Modify: `README.md`
+- Modify: `.agents/context/ticket-plan.md`
+- Modify: `.agents/context/current.md`
+- Modify: `.memory/CURRENT.md`
+
+- [ ] **Step 1: Write detailed documentation**
+Document scoped failure attribution, fix-pair mining, HOT.md source tagging, and LangMem frequency curves.
+
+- [ ] **Step 2: Update CHANGELOG & README**
+Record Wave 22 features, tickets `T-313`, `T-144`, `T-314`, `T-315`.
+
+- [ ] **Step 3: Mark tickets landed in ticket-plan.md & update current.md**
+Update tickets `T-313`, `T-144`, `T-314`, `T-315` from `[ ]` to `[x]`, advance shipped capabilities, and update working constraints.
+
+- [ ] **Step 4: Commit documentation & agent context pass**
+```bash
+git commit -m "docs(wave-22): document failure attribution, fix-pair mining, and frequency ranking"
+```