oh-my-customcode 0.37.2 → 0.39.0

package/dist/index.js

@@ -544,7 +544,9 @@ function getDefaultConfig() {
       ".claude/agent-memory/",
       ".claude/agent-memory-local/"
     ],
-    customComponents: []
+    customComponents: [],
+    domain: undefined,
+    teamMode: false
   };
 }
 function getDefaultPreferences() {
@@ -1387,6 +1389,7 @@ async function installEntryDocWithTracking(targetDir, options, result) {
 async function updateInstallConfig(targetDir, options, installedComponents) {
   const config = await loadConfig(targetDir);
   config.language = options.language ?? DEFAULT_LANGUAGE;
+  config.domain = options.domain;
   config.installedAt = new Date().toISOString();
   config.installedComponents = installedComponents;
   await saveConfig(targetDir, config);

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.37.2",
+  "workspaces": ["packages/*"],
+  "version": "0.39.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {
@@ -41,6 +42,7 @@
     "prepublishOnly": "bun run build && bun run test"
   },
   "dependencies": {
+    "@clack/prompts": "^1.1.0",
     "commander": "^14.0.2",
     "i18next": "^25.8.0",
     "yaml": "^2.8.2"

package/templates/.claude/hooks/hooks.json

@@ -141,6 +141,18 @@
         "description": "Record agent outcomes on subagent completion (complements PostToolUse Agent matcher)"
       }
     ],
+    "PostCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Context was just compacted. MANDATORY post-compaction steps: 1) All enforced rules (R007 Agent ID, R008 Tool ID, R009 Parallel, R010 Orchestrator, R018 Agent Teams) remain ACTIVE — compaction does NOT disable rules. 2) Your next response MUST include agent identification per R007. 3) Continue delegating ALL file modifications to subagents per R010. 4) Re-read CLAUDE.md if needed to refresh project-specific context."
+          }
+        ],
+        "description": "Reinforce enforced rules after context compaction — prevents rule amnesia (v2.1.76+)"
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "tool == \"Bash\"",
@@ -212,16 +224,6 @@
         ],
         "description": "Type check Python files with ty after edits"
       },
-      {
-        "matcher": "tool == \"Task\" || tool == \"Agent\"",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash .claude/hooks/scripts/task-outcome-recorder.sh"
-          }
-        ],
-        "description": "Record agent/task outcomes (success/failure) for model escalation decisions"
-      },
       {
         "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"Bash\" || tool == \"Task\" || tool == \"Agent\" || tool == \"Read\" || tool == \"Glob\" || tool == \"Grep\"",
         "hooks": [
@@ -294,15 +296,25 @@
         ],
         "description": "Final console.log audit and session diagnostics before session ends"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/eval-core-batch-save.sh"
+          }
+        ],
+        "description": "Batch-save agent outcomes to eval-core DB on session end (advisory, exit 0)"
+      },
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Session-end memory checkpoint (R011 enforcement). Check conversation history for these 2 steps: 1) sys-memory-keeper was delegated to update MEMORY.md 2) claude-mem save was attempted via ToolSearch + mcp__plugin_claude-mem_mcp-search__save_memory. Note: episodic-memory auto-indexes after session — no manual verification needed. Decision rules: If BOTH were attempted (success or failure both count): approve. If MCP tools are unavailable after ToolSearch attempt: approve with note. If session had no explicit session-end signal from user (quick question, no memory work): approve. If any step was NOT attempted despite user signaling session end: block with systemMessage listing the missing steps."
+            "prompt": "Session-end memory checkpoint (R011 enforcement). Check if the session-end memory save workflow was completed: 1) sys-memory-keeper was delegated to update MEMORY.md 2) claude-mem save was attempted via ToolSearch + mcp__plugin_claude-mem_mcp-search__save_memory. Note: episodic-memory auto-indexes after session — no manual action needed. Decision rules (evaluate in order): 1. If session had no explicit session-end signal (quick question, no memory work): APPROVE immediately. 2. If BOTH steps were already attempted (success or failure both count): APPROVE. 3. If MCP tools unavailable after ToolSearch attempt: APPROVE with note. 4. If steps were NOT yet performed: PERFORM THEM NOW (maximum 1 attempt each): a. Delegate to sys-memory-keeper to update MEMORY.md — call Agent tool with sys-memory-keeper. b. Attempt claude-mem save — ToolSearch for save_memory tool, then call it. c. After completion (success or failure), APPROVE stop. IMPORTANT: Do NOT block indefinitely. After 1 attempt per step, always APPROVE. IMPORTANT: Do NOT loop — if you already performed these steps in this same stop hook evaluation, APPROVE."
           }
         ],
-        "description": "Enforce R011 session-end memory saves — block stop if claude-mem or episodic-memory saves were skipped"
+        "description": "Enforce R011 session-end memory saves — auto-perform if not yet done (episodic-memory auto-indexes)"
       }
     ]
   }

package/templates/.claude/hooks/scripts/agent-teams-advisor.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Agent Teams Advisor Hook
 # Trigger: PreToolUse, tool == "Task" || tool == "Agent"
 # Purpose: Track Agent/Task tool usage count per session and warn when Agent Teams may be more appropriate

package/templates/.claude/hooks/scripts/audit-log.sh

@@ -7,6 +7,9 @@
 
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 input=$(cat)
 
 # Extract fields from hook input

package/templates/.claude/hooks/scripts/content-hash-validator.sh

@@ -7,6 +7,9 @@
 
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 input=$(cat)
 
 # Hash store (PPID-scoped, session-only)

package/templates/.claude/hooks/scripts/context-budget-advisor.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Context Budget Advisor Hook
 # Trigger: PostToolUse (Edit/Write/Agent/Task/Read/Glob/Grep/Bash)
 # Purpose: Monitor context usage and advise ecomode activation based on task type
@@ -29,7 +32,7 @@ read_count=${read_count:-0}
 agent_count=${agent_count:-0}
 
 # Determine tool type from input
-TOOL=$(echo "$input" | jq -r '.tool // ""' 2>/dev/null || echo "")
+TOOL=$(echo "$input" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
 tool_count=$((tool_count + 1))
 
 case "$TOOL" in

package/templates/.claude/hooks/scripts/eval-core-batch-save.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -euo pipefail
+
+# Eval-Core Batch Save on Session End (Advisory Only)
+# Trigger: Stop hook
+# Purpose: Auto-collect eval metrics on session end via eval-core CLI
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+#
+# This hook is advisory-only and never blocks session termination.
+# If eval-core is unavailable or collection fails, the session continues normally.
+
+input=$(cat)
+PPID_FILE="/tmp/.claude-task-outcomes-${PPID}"
+
+# Only attempt collection if outcome file exists and eval-core is available
+if [ -f "$PPID_FILE" ] && command -v eval-core >/dev/null 2>&1; then
+  echo "[Hook] Collecting eval metrics via eval-core..." >&2
+  eval-core collect --ppid "$PPID" 2>/dev/null || true
+fi
+
+# Always pass through input and exit 0 (advisory only)
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/git-delegation-guard.sh

@@ -3,6 +3,9 @@
 # Warns when git operations are delegated to a non-mgr-gitnerd agent via Agent/Task tool.
 # WARN only - does NOT block (exit 0, passes input through).
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 input=$(cat)
 
 agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // ""')

package/templates/.claude/hooks/scripts/model-escalation-advisor.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Model Escalation Advisor Hook
 # Trigger: PreToolUse, tool == "Task" || tool == "Agent"
 # Purpose: Advise model escalation when failure patterns detected

package/templates/.claude/hooks/scripts/schema-validator.sh

@@ -7,6 +7,9 @@
 
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 input=$(cat)
 
 # Extract tool info

package/templates/.claude/hooks/scripts/secret-filter.sh

@@ -7,6 +7,9 @@
 
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 input=$(cat)
 
 # Extract output to scan

package/templates/.claude/hooks/scripts/session-env-check.sh

@@ -82,6 +82,20 @@ if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/n
   fi
 fi
 
+# --- CI Status Check ---
+# Check last CI run status if gh CLI is available
+if command -v gh &>/dev/null; then
+  ci_status=$(gh run list --limit 1 --json conclusion -q '.[0].conclusion' 2>/dev/null || echo "unknown")
+  ci_name=$(gh run list --limit 1 --json name -q '.[0].name' 2>/dev/null || echo "unknown")
+  if [ "$ci_status" = "failure" ]; then
+    echo "[Session] ⚠ WARNING: Last CI run FAILED (${ci_name}) — check before pushing" >&2
+  elif [ "$ci_status" = "success" ]; then
+    echo "[Session] CI: last run passed (${ci_name})" >&2
+  elif [ "$ci_status" != "unknown" ]; then
+    echo "[Session] CI: last run status: ${ci_status} (${ci_name})" >&2
+  fi
+fi
+
 # Update availability check (local cache only — no network calls)
 OMCUSTOM_UPDATE_STATUS="unknown"
 INSTALLED_VERSION=""
@@ -173,6 +187,12 @@ case "$DRIFT_STATUS" in
 esac
 echo "------------------------------------" >&2
 
+# SessionEnd hooks timeout (v2.1.74+)
+if [ -z "${CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS:-}" ]; then
+  echo "[SessionEnv] ⚠ CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS not set (default: 1500ms)" >&2
+  echo "[SessionEnv] Recommend: export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000" >&2
+fi
+
 # Update Check report
 echo "" >&2
 echo "  [Update Check]" >&2

package/templates/.claude/hooks/scripts/stuck-detector.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Stuck Detector Hook
 # Trigger: PostToolUse, tool matches "Edit|Write|Bash|Task|Agent"
 # Purpose: Detect repetitive failure loops and advise recovery
@@ -9,7 +12,7 @@ set -euo pipefail
 #   - exit 1: hard block (extreme stuck loops, >= HARD_BLOCK_THRESHOLD repetitions)
 
 # Hard block threshold: consecutive identical operations before blocking
-HARD_BLOCK_THRESHOLD=5
+HARD_BLOCK_THRESHOLD=${CLAUDE_STUCK_THRESHOLD:-3}
 
 input=$(cat)
 

package/templates/.claude/hooks/scripts/task-outcome-recorder.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+# Dependency check: exit silently if jq not available
+command -v jq >/dev/null 2>&1 || exit 0
+
 # Task/Agent Outcome Recorder Hook
 # Trigger: PostToolUse (tool == "Task" || "Agent") and SubagentStop
 # Purpose: Record task outcomes for model escalation decisions
@@ -13,6 +16,17 @@ agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // .agent_type //
 model=$(echo "$input" | jq -r '.tool_input.model // .model // "inherit"')
 description=$(echo "$input" | jq -r '.tool_input.description // .description // ""' | head -c 80)
 
+# Extract skill name from description or prompt
+skill_name=""
+if echo "$description" | grep -qiE '(skill:|routing|→.*skill)'; then
+  skill_name=$(echo "$description" | grep -oiE '[a-z]+-[a-z]+(-[a-z]+)*-?(routing|skill|practices|detection|decomposition|orchestration|pipeline|guards|cycle|plan|review|refactor|publish|version|audit|exec|analyze|bundle|report|setup|watch|lists|status|help|save|recall)' | head -1)
+fi
+# Fallback: check prompt field for "Skill: {name}" pattern
+if [ -z "$skill_name" ]; then
+  prompt=$(echo "$input" | jq -r '.tool_input.prompt // ""' | head -c 500)
+  skill_name=$(echo "$prompt" | grep -oiE 'Skill:\s*[a-z]+-[a-z]+(-[a-z]+)*' | sed 's/[Ss]kill:\s*//' | head -1)
+fi
+
 # Determine outcome
 is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
 
@@ -61,9 +75,10 @@ entry=$(jq -n \
   --arg model "$model" \
   --arg outcome "$outcome" \
   --arg pattern "$pattern" \
+  --arg skill "$skill_name" \
   --arg desc "$description" \
   --arg err "$error_summary" \
-  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, pattern_used: $pattern, description: $desc, error_summary: $err}')
+  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, pattern_used: $pattern, skill: $skill, description: $desc, error_summary: $err}')
 
 echo "$entry" >> "$OUTCOME_FILE"
 

package/templates/.claude/rules/MAY-optimization.md

@@ -27,3 +27,15 @@
 | Repetitive tasks, clear bottleneck, measurable gain | One-time tasks, already fast, complexity > benefit |
 
 Readability > Optimization. No optimization without measurement.
+
+## CLAUDE.md Context Optimization (v2.1.72+)
+
+HTML comments in CLAUDE.md are hidden from the model during auto-injection but visible via Read tool.
+
+| Use Case | Example |
+|----------|---------|
+| Metadata tags | `<!-- agents: 44, skills: 74 -->` |
+| Validation checksums | `<!-- validate-docs: hash=abc123 -->` |
+| Conditional context | `<!-- detailed-architecture: see guides/architecture/ -->` |
+
+**Rule**: Move model-unnecessary metadata into HTML comments to reduce context token usage. Keep actionable instructions as visible text.

package/templates/.claude/rules/MUST-agent-design.md

@@ -11,7 +11,7 @@ Location: `.claude/agents/{name}.md` (single file, kebab-case)
 ```yaml
 name: agent-name           # Unique identifier (kebab-case)
 description: Brief desc    # One-line summary
-model: sonnet              # sonnet | opus | haiku
+model: sonnet              # sonnet | opus | haiku (or full ID: claude-sonnet-4-6)
 tools: [Read, Write, ...]  # Allowed tools
 ```
 
@@ -31,9 +31,10 @@ escalation:              # Model escalation policy (optional)
   path: haiku → sonnet → opus  # Escalation sequence
   threshold: 2           # Failures before advisory
 soul: true                 # Enable SOUL.md identity injection
-isolation: worktree        # Run in isolated git worktree
+isolation: worktree | sandbox  # worktree = git worktree, sandbox = restricted bash
 background: true           # Run in background
 maxTurns: 10               # Max conversation turns
+maxTokens: 100000          # Per-turn token ceiling
 mcpServers: [server-1]     # MCP servers available
 hooks:                     # Agent-specific hooks
   PreToolUse:
@@ -41,9 +42,33 @@ hooks:                     # Agent-specific hooks
       command: "echo hook"
 permissionMode: bypassPermissions  # Permission mode
 disallowedTools: [Bash]    # Tools to disallow
+limitations:               # Negative capability declarations
+  - "cannot execute tests"
+  - "cannot modify code"
+domain: backend              # backend | frontend | data-engineering | devops | universal
 ```
 
-> **Note**: `isolation`, `background`, `maxTurns`, `mcpServers`, `hooks`, `permissionMode`, `disallowedTools` are supported in Claude Code v2.1.63+.
+> **Note**: `isolation`, `background`, `maxTurns`, `maxTokens`, `mcpServers`, `hooks`, `permissionMode`, `disallowedTools`, `limitations` are supported in Claude Code v2.1.63+. Hook types `PostCompact`, `Elicitation`, `ElicitationResult` require v2.1.76+.
+
+### Isolation Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `worktree` | Isolated git worktree copy | Code changes that need rollback safety |
+| `sandbox` | Restricted Bash environment | Agents running untrusted or scan commands |
+
+When `isolation: sandbox` is set, the agent's Bash calls run with restricted permissions. This is advisory metadata — enforcement depends on the execution environment.
+
+### Token Ceiling
+
+When `maxTokens` is set, it serves as advisory metadata for the orchestrator to manage agent turn budgets. The orchestrator should track output and consider escalation or task splitting when an agent approaches its ceiling.
+
+### Negative Capabilities (Limitations)
+
+The `limitations` field declares what an agent explicitly CANNOT or SHOULD NOT do. This enables:
+1. **Clearer routing**: Orchestrator knows agent boundaries
+2. **Safer delegation**: Prevents accidental capability overreach
+3. **Better documentation**: Makes agent scope explicit
 
 ### Escalation Policy
 
@@ -144,6 +169,19 @@ user-invocable: false      # Whether user can invoke directly
 disable-model-invocation: true  # Prevent model from auto-invoking
 ```
 
+### Skill Effectiveness Tracking
+
+Skills can optionally track effectiveness metrics via auto-populated fields:
+
+```yaml
+effectiveness:              # Auto-populated by sys-memory-keeper
+  invocations: 0            # Total invocation count across sessions
+  success_rate: 0.0         # Success rate (0.0-1.0)
+  last_invoked: ""          # ISO-8601 timestamp
+```
+
+These fields are read-only from the skill's perspective — sys-memory-keeper updates them at session end based on task-outcome-recorder data. They inform model selection, routing optimization, and skill maintenance priorities.
+
 ## Skill Scope
 
 | Scope | Purpose | Deployed via init? |
@@ -156,7 +194,7 @@ Default: `core` (when field is omitted)
 
 ### Context Fork Criteria
 
-Use `context: fork` for skills that orchestrate multi-agent workflows. Cap at **10 total** across the project.
+Use `context: fork` for skills that orchestrate multi-agent workflows. Cap at **12 total** across the project.
 
 | Use `context: fork` | Do NOT use `context: fork` |
 |---------------------|---------------------------|
@@ -165,10 +203,10 @@ Use `context: fork` for skills that orchestrate multi-agent workflows. Cap at **
 | Multi-agent coordination patterns | Single-agent reference skills |
 | Task decomposition/planning | External tool integrations |
 
-Current skills with `context: fork` (8/10 cap):
+Current skills with `context: fork` (11/12 cap):
 - secretary-routing, dev-lead-routing, de-lead-routing, qa-lead-routing
-- dag-orchestration, task-decomposition, worker-reviewer-pipeline
-- pipeline-guards
+- dag-orchestration, task-decomposition, worker-reviewer-pipeline, pipeline-guards
+- deep-plan, evaluator-optimizer, sauron-watch
 
 ## Naming
 

package/templates/.claude/rules/MUST-completion-verification.md

@@ -0,0 +1,81 @@
+# [MUST] Completion Verification Rules
+
+> **Priority**: MUST | **ID**: R020
+
+## Core Rule
+
+Before declaring any task `[Done]`, verify completion against task-type-specific criteria. False completion declarations erode trust and cause downstream failures.
+
+## Task-Type Completion Matrix
+
+| Task Type | REQUIRED Verification Before [Done] |
+|-----------|-------------------------------------|
+| Release | All issues closed, version bumped, PR merged, GitHub Release created |
+| Implementation | Code compiles/passes lint, tests pass (if exist), no TODO markers left |
+| Documentation | Links valid, counts accurate, cross-references updated |
+| Git Operations | Operation succeeded (check exit code), working tree clean |
+| Code Review | All findings addressed or explicitly deferred with justification |
+| Agent/Skill Creation | Frontmatter valid, referenced skills exist, routing updated |
+
+## Self-Check (Before Declaring Done)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  BEFORE DECLARING [Done], ASK YOURSELF:                          ║
+║                                                                   ║
+║  1. Did I verify the ACTUAL outcome (not just attempt)?          ║
+║     "I ran the command" ≠ "the command succeeded"                ║
+║     YES → Continue                                               ║
+║     NO  → Verify outcome first                                   ║
+║                                                                   ║
+║  2. Does the task type have specific criteria above?             ║
+║     YES → Check each criterion                                   ║
+║     NO  → Apply general verification                             ║
+║                                                                   ║
+║  3. Are there any unchecked items in the task's checklist?       ║
+║     YES → Complete them or explicitly defer with reason           ║
+║     NO  → Good. Proceed to [Done]                                ║
+║                                                                   ║
+║  4. Would I bet $100 this task is truly complete?                ║
+║     YES → Declare [Done]                                          ║
+║     NO  → Identify what's uncertain and verify                   ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+## Common False Completion Patterns
+
+| Pattern | Reality | Fix |
+|---------|---------|-----|
+| "Command executed" | Exit code not checked | Check `$?` or tool output |
+| "File created" | Content not verified | Read file back, verify content |
+| "PR created" | CI not checked | Wait for CI, verify green |
+| "Issue closed" | Related issues not updated | Check parent epic, cross-refs |
+| "Tests pass" | Only ran subset | Run full test suite |
+
+## Completion Contract Format
+
+For complex tasks, declare completion contract upfront:
+
+```
+[Contract] Task: {name}
+├── Criterion 1: {specific, verifiable condition}
+├── Criterion 2: {specific, verifiable condition}
+└── Criterion N: {specific, verifiable condition}
+```
+
+Then at completion:
+
+```
+[Done] Task: {name}
+├── ✓ Criterion 1: {evidence}
+├── ✓ Criterion 2: {evidence}
+└── ✓ Criterion N: {evidence}
+```
+
+## Integration
+
+| Rule | Interaction |
+|------|-------------|
+| R003 | [Done] status format now requires verification evidence |
+| R010 | Orchestrator verifies subagent completion claims |
+| R017 | Structural changes require sauron verification before [Done] |

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -14,6 +14,7 @@ Rule: If native auto memory can handle it, do NOT use claude-mem.
 Agent frontmatter `memory: project|user|local` enables persistent memory:
 - System creates memory directory, loads first 200 lines of MEMORY.md into prompt
 - Read/Write/Edit tools auto-enabled for memory directory
+- Custom directory: set `autoMemoryDirectory` in settings to override default paths (v2.1.74+)
 
 | Scope | Location | Git Tracked |
 |-------|----------|-------------|
@@ -71,6 +72,45 @@ Memory entries in MEMORY.md should include confidence annotations to distinguish
 [any] → contradicted by evidence → demoted or removed
 ```
 
+### Temporal Decay
+
+Memory entries include an optional verification timestamp for decay tracking:
+
+**Format**: `[confidence: high, verified: 2026-03-15]`
+
+| Age (unverified) | Action |
+|-------------------|--------|
+| 0-30 days | No change — entry is fresh |
+| 30-60 days | Demote one level (high→medium, medium→low) |
+| 60-90 days | Demote again if not re-verified |
+| 90+ days | Removal candidate — flag for review |
+
+**Decay Schedule**:
+```
+Day 0:   [confidence: high, verified: 2026-03-15]
+Day 30:  [confidence: high, verified: 2026-03-15]  ← still within window
+Day 31:  [confidence: medium, verified: 2026-03-15] ← auto-demoted
+Day 61:  [confidence: low, verified: 2026-03-15]    ← demoted again
+Day 91:  [REVIEW NEEDED, verified: 2026-03-15]      ← flagged
+```
+
+**Re-verification**: Any session that confirms a memory entry resets the verified date:
+```
+Before: [confidence: medium, verified: 2026-01-15]
+Action: Pattern confirmed in session
+After:  [confidence: high, verified: 2026-03-15]
+```
+
+**Enforcement**: sys-memory-keeper checks decay at session start and end:
+1. Session start: scan MEMORY.md for entries past decay threshold
+2. Flag stale entries with `[STALE]` prefix
+3. Session end: remove or demote unconfirmed stale entries
+
+**Exceptions**: Entries marked `[permanent]` are exempt from decay:
+```
+### Architecture Decisions [confidence: high, permanent]
+```
+
 ## Behavioral Memory
 
 MEMORY.md supports an optional `## Behaviors` section for tracking user interaction preferences and workflow patterns.
@@ -140,6 +180,47 @@ When sys-memory-keeper updates MEMORY.md at session end:
 2. Findings that match existing entries → promote confidence
 3. Findings that contradict existing entries → flag for review
 
+## Agent Metrics
+
+MEMORY.md supports an optional `## Metrics` section for tracking per-agent-type performance data.
+
+### Metrics Section Format
+
+```markdown
+## Metrics [auto-updated by sys-memory-keeper]
+
+| Agent Type | Tasks | Success Rate | Avg Model | Last Used |
+|------------|-------|-------------|-----------|-----------|
+| lang-golang-expert | 12 | 92% | sonnet | 2026-03-15 |
+| mgr-gitnerd | 8 | 100% | sonnet | 2026-03-15 |
+```
+
+### Metrics Collection
+
+sys-memory-keeper aggregates metrics at session end:
+
+1. Read `/tmp/.claude-task-outcomes-${PPID}` (JSONL from task-outcome-recorder hook)
+2. Parse each entry: `{agent_type, outcome, model, timestamp}`
+3. Aggregate by agent_type: total tasks, success count, model distribution
+4. Merge with existing Metrics table in MEMORY.md
+5. Budget: max 20 rows (prune lowest-usage agents when exceeded)
+
+### Metrics Fields
+
+| Field | Source | Calculation |
+|-------|--------|-------------|
+| Tasks | task-outcome-recorder JSONL | Count of entries per agent_type |
+| Success Rate | outcome field | `success_count / total_count * 100` |
+| Avg Model | model field | Most frequently used model |
+| Last Used | timestamp field | Most recent invocation |
+
+### Budget Management
+
+The Metrics section shares the 200-line MEMORY.md budget:
+1. Max 20 agent rows in Metrics table
+2. When adding new agent, prune agent with lowest task count
+3. Merge identical agent types across sessions (cumulative)
+
 ## Session-End Auto-Save
 
 ### Trigger