twining_housekeeping
Run periodic maintenance on Twining stores: remove duplicates, flag stale decisions, prune orphaned entities, rotate old metrics, repair index desyncs. Preview by default; execute applies changes.
Instructions
Run periodic maintenance on Twining stores. Preview by default (dry run); preview simulates the full pass pipeline, so its counts match what execute will do on the same state (#39). Removes duplicates, surfaces stale decisions and dangling warnings, prunes orphaned graph entities, rotates old metrics, and backfills missing superseded_by back-links on superseded decisions. The blackboard archive pass is OPT-IN (archive: true): it sweeps every archivable entry regardless of age, keeping decisions, unresolved need/warning/question entries (#40), and the newest archive.retain_recent entries (D4). Pass staleness_review: true to also flag entries whose scope/files/branch are gone. Pass execute: true to apply changes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| archive | No | Defaults to FALSE (D4) — housekeeping no longer sweeps the board as a side effect; repairs like compact_archives can run with execute: true safely. Set archive: true to run the blackboard archive pass: it takes no age cutoff, archiving every archivable entry except decisions, unresolved need/warning/question entries, and the newest archive.retain_recent entries (default 200). | |
| execute | No | Set to true to apply changes. Default is false (preview only). | |
| stale_days | No | Flag provisional decisions older than this many days (default: 7) | |
| merge_sweep | No | Set to true to detect branches deleted since the last housekeeping run (typically post-merge cleanup) and flag entries provenance-stamped with those branches. First call records the initial branch snapshot and returns no candidates. The branch snapshot is advanced only when execute=true; preview passes leave the baseline untouched so deletions stay visible across multiple previews. Returns candidates only; use twining_archive_stale to act on them. When run alongside staleness_review, branch-gone duplicates are removed from staleness_review (merge_sweep is the more specific signal). | |
| repair_index | No | Files backend only: detect decision files on disk that are missing from decisions/index.json (index desync — such decisions are invisible to every read path). Preview reports orphan ids; with execute: true, orphans that are recognizably decisions (id matches filename, core fields present) are appended to the index under the index lock; anything else counts in skipped_invalid and is never modified or deleted. This pass runs last, so other housekeeping passes see salvaged decisions on the NEXT call, not this one. On the sqlite backend this reports index_repair_error instead of silently succeeding. | |
| dedup_relations | No | Dedup legacy duplicate (source, target, type) graph relations left from before the 2.11 upsert. Survivor is the edge live upserts already merge into (seq-first; the created-at-oldest on the file backend); later duplicates fold their properties in under origin precedence (derived never downgrades declared) and are removed. Duplicates with non-unique ids and groups that fail to fold (e.g. dangling endpoints) are skipped and counted in the report, never silently dropped. Preview by default; execute applies. | |
| amend_candidates | No | Report candidate affected_files for active decisions whose list is empty (scope walk ranked by term overlap). ALWAYS report-only regardless of execute — confirm per record with twining_amend({decision_id, add_affected_files}). Caps: 50 decisions/run, 500 files/scope, 5 candidates each; truncation is reported, never silent. | |
| compact_archives | No | Set to true to scan .twining/archive/*.jsonl for junk generated by the pre-1.24.0 auto-archive feedback loop ('Archive: N entries archived' summary findings, #35) and report how much is reclaimable. With execute: true, junk lines are dropped (streaming, atomic rewrite), archive files left empty are deleted, and an audit-trail finding is posted. Only entries matching the archiver's exact signature are dropped — everything else, including unparseable lines, is preserved. | |
| staleness_review | No | Set to true to scan blackboard entries and decisions for staleness — flags items whose scope path, affected files, or originating branch no longer exist. Returns candidates only; use twining_archive_stale to act on them. | |
| promote_provisionals | No | Set to true to auto-promote stale provisional decisions to active. Default is false (report only). | |
| repair_entity_scopes | No | Set to true to recompute knowledge-graph entity scopes from their decided_by relations. Before scopes became a union, a decision in one scope overwrote the scope another decision had stamped on the same file — leaving entities asserting a single scope that was merely the most recent. Reports what would change; with execute: true, rewrites them. Safe to run repeatedly. | |
| metrics_retention_days | No | Remove metrics older than this many days (default: 30) |