Skip to main content
Audit knowledge docs for staleness, detect drift from journal evidence, and generate proposed updates for human review.

​
Usage

# Audit — show what's stale
jfl organize

# Generate PENDING.md with proposed updates
jfl organize --fix

# Apply reviewed changes from PENDING.md
jfl organize --apply

# Move archive candidates to knowledge/archive/
jfl organize --archive

# Custom lookback period
jfl organize --days 60

​
How It Works

  1. Scans knowledge/*.md for all active docs
  2. Reads last N days of journal entries
  3. Extracts topics from both docs and journals
  4. Computes drift score per doc:
    • Age penalty (>7 days starts drifting)
    • Journal activity penalty (lots of activity + stale doc = drift)
    • Stale topic penalty (topics in doc not mentioned in journals)
  5. Generates knowledge/PENDING.md with:
    • TLDR of what needs attention
    • Uncovered topics (journals mention, no doc covers)
    • Per-doc proposed updates with evidence
    • Open questions for human review

​
Output

  Knowledge Organizer

  Scanning 243 journal entries from last 30 days

  Doc Health

  ✓  VISION              0d old  drift:   20%  mentions: 221
  ✓  THESIS              0d old  drift:   20%  mentions: 223
  ✓  NARRATIVE            0d old  drift:   20%  mentions: 206
  ✗  ROADMAP            14d old  drift:   65%  mentions: 89

  1 of 4 docs need attention

  Generated: knowledge/PENDING.md
  Review it, answer questions, then run: jfl organize --apply

​
The PENDING.md Workflow

PENDING.md acts as a PR for your knowledge base: 
jfl organize              → generates PENDING.md
  ↓
You review PENDING.md     → answer questions, mark keep/update/archive
  ↓
jfl organize --apply      → applies changes, clears PENDING.md

​
Example PENDING.md

# Knowledge Update — PENDING

> Review this file, answer questions, then run `jfl organize --apply`

## TLDR

1 of 4 docs need attention:
- ⚠️ **ROADMAP** — drifted (14d old, drift: 65%)

## Uncovered Topics

Recent journal activity mentions these topics but no knowledge doc covers them:
- **docker testing** — "Set up Docker-based onboarding eval"
- **memory graph edges** — "Added graph edge functions to memory-db"

## Open Questions

- [ ] VISION.md references "JFL" but recent journals mention "TENET". Update?
- [ ] New RL learning loop — should this be in THESIS or a separate doc?

**Action:** <!-- ANSWER: keep / update / archive -->

​
Options

FlagDescription
--fixGenerate PENDING.md (same as default)
--applyApply reviewed changes, clear PENDING.md
--archiveMove archive-candidate docs to knowledge/archive/
--days <N>Journal lookback period (default: 30)