Synthadoc v0.6.0: Solving Knowledge Staleness with Lifecycle State Machines

The 5-State Page Lifecycle

Synthadoc v0.6.0 implements a system for automated knowledge bases that tracks content freshness through a permanent audit trail. It utilizes SHA-256 hashing of source files to trigger automatic state transitions when documentation becomes stale.

Why This Matters

Static knowledge bases lack the vocabulary to identify when previously true information becomes obsolete, often maintaining high confidence scores despite breaking changes in source libraries. By treating a wiki as a compilation pipeline rather than an append-only database, Synthadoc ensures downstream LLMs receive only active, non-contradicted content, eliminating the risk of relying on quietly incorrect data.

Key Insights

• Automated staleness detection via SHA-256 hash mismatch (v0.6.0), which triggers an ‘active’ to ‘stale’ transition during lint runs.
• Temporal awareness through a five-state machine (draft, active, stale, contradicted, archived) to track provenance and history.
• Admission control via Candidates Staging policies (off, all, threshold), allowing human gating based on confidence ratings before a page enters the lifecycle.
• Zero-cost serialization using four machine-readable export formats that derive data from stored state rather than new LLM completions.

Working Examples

CLI output showing the current distribution of pages across the five lifecycle states.

synthadoc status
Wiki: history-of-computing
Pages: 42
Jobs pending: 0
Jobs total: 187
Page lifecycle:
active 38
draft 2 <- run `synthadoc lint run` to promote
draft (staged) 1 <- promote from candidates/ first, then lint
stale 1 <- re-ingest needed
contradicted 0
archived 1

Exporting only active pages to ensure downstream agents receive reviewed and consistent content.

synthadoc export --format llms.txt --status active
synthadoc export --format json --status active --output exports/wiki.json

Practical Applications

• । Use case: Nightly ingest jobs for engineering teams where pages land in wiki/candidates/ for human review before promotion to draft state.
• 。 Pitfall: Treating knowledge bases as append-only databases, which results in ‘quietly wrong’ documentation that passes lints but relies on outdated source versions.

References:

• https://dev.to/paul_chen_90371fe7426cb44/synthadoc-staleness-detection-full-audit-trails-and-four-export-formats-no-extra-llm-calls-2ild
• https://github.com/axoviq-ai/synthadoc