0xhoneyjar/detecting-staleness

Detecting Staleness

Scan all artifacts with confidence metadata, compute freshness scores using a pure derived formula, and output a staleness report with suggested actions.

---

Core Principle

Confidence is always derived, never stored. The score is computed from immutable inputs (frontmatter + git history + config). Same inputs always produce the same score.

---

Triggers

/stale                              # All artifacts, default threshold
/stale --threshold 0.50             # Custom threshold
/stale --pack observer              # Specific pack's artifacts

---

When to Use

• Periodic health check of artifact freshness
• Before starting a new sprint (are our artifacts still valid?)
• After a burst of code changes (did anything go stale?)
• When planning what to refresh next

---

Workflow

Phase 1: Scan Artifacts

Glob the following paths for artifacts with confidence frontmatter:

  grimoires/*/canvas/*.md
  grimoires/*/journeys/*.md
  grimoires/*/reality/*.md
  grimoires/artisan/taste.md

IF --pack specified:
  Filter to grimoires/{pack}/ only

For each file:
  Parse YAML frontmatter
  Look for confidence: block

When frontmatter is MISSING: Classify artifact as unknown with suggested action:

Run `/refresh {path}` to initialize confidence tracking

Phase 2: Compute Scores

For each artifact WITH confidence metadata:

READ INPUTS (from frontmatter):
  last_validated_commit   # Git SHA anchor
  validation_count        # Times re-validated

READ INPUTS (from git):
  commits_since = git rev-list --count {last_validated_commit}..HEAD -- {related_paths}

  IF last_validated_commit not found in history:
    Fallback: git log --oneline --since="30 days ago" -- {related_paths} | wc -l
    Warn: "Baseline commit not found — using 30-day window"

  IF .git unavailable (shallow clone, no git):
    Use validation_count only
    Mark score as "approx"
    Warn: "Git history unavailable — confidence approximate"

READ INPUTS (from .loa.config.yaml):
  decay_rate              = confidence.decay.rate (default: 0.02)
  code_change_penalty     = confidence.penalties.code_change (default: 0.05)
  revalidation_boost      = confidence.boosts.revalidation (default: 0.20)
  diminishing_factor      = confidence.boosts.diminishing_factor (default: 0.7)
  floor                   = confidence.decay.floor (default: 0.20)
  initial_score           = confidence.initial_score (default: 0.90)

COMPUTE:
  days_since = days between last_validated_commit date and now (UTC)
  time_decay = days_since * decay_rate
  code_penalty = commits_since * code_change_penalty
  boost = revalidation_boost * (diminishing_factor ^ validation_count)

  score = clamp(initial_score - time_decay - code_penalty + boost, floor, 0.95)

CLASSIFY:
  score >= healthy_threshold (0.70)  → "healthy"
  score >= warning_threshold (0.50)  → "warning"
  score >= stale_threshold (0.30)    → "stale"
  score < stale_threshold            → "archive"

Phase 3: Output Table

STALENESS REPORT
════════════════

| Artifact | Confidence | Status | Last Validated | Suggested Action |
|----------|-----------|--------|----------------|------------------|
| canvas/xabbu.md | 0.72 | healthy | 2026-02-01 | — |
| canvas/elcapitan.md | 0.48 | warning | 2026-01-20 | /drift, /refresh |
| reality/profile.md | 0.31 | stale | 2026-01-10 | /ground profile |
| taste.md | unknown | unknown | — | /refresh grimoires/artisan/taste.md |

Summary: {N} healthy, {M} warning, {P} stale, {Q} archive, {R} unknown

IF --threshold specified: Only show artifacts below the threshold.

---

Configuration

Thresholds and decay parameters are read from .loa.config.yaml:

confidence:
  initial_score: 0.90
  decay:
    rate: 0.02
    floor: 0.20
  thresholds:
    healthy: 0.70
    warning: 0.50
    stale: 0.30
  penalties:
    code_change: 0.05
  boosts:
    revalidation: 0.20
    diminishing_factor: 0.7

If config is missing, use the defaults shown above.

---

Error Handling

| Error | Resolution | |-------|------------| | No artifacts found | Report "No artifacts with confidence metadata found" | | Git not available | Use validation_count only, mark as "approx" | | Config missing | Use defaults | | Frontmatter parse error | Skip artifact, log warning | | Baseline commit not in history | Use 30-day window fallback |

---

Integration Points

• Reads: Artifact frontmatter, git history, .loa.config.yaml
• Consumed by: Operators deciding what to refresh
• Related: /drift (detailed per-artifact), /refresh (re-validate)

---

Validation

• [ ] Scans all artifact paths (canvas, journeys, reality, taste.md)
• [ ] Correctly computes decay formula
• [ ] Handles missing confidence frontmatter as "unknown"
• [ ] Handles missing git as "approx"
• [ ] Respects --threshold filter
• [ ] Respects --pack filter
• [ ] Config defaults work when .loa.config.yaml missing