retrospect-core

retrospect-core

The meta-review engine. It is to checkpoint what deliver is to discover/prep/review: one mechanism, its consumers kept single-responsibility without duplicating the engine.

It does not know how to find decision drift or organ overlap — that domain logic lives in the calling skill's passes. retrospect-core owns the four things every meta-review run shares: orient, diff against the prior run, render per the review output contract, and route each confirmed finding to the organ that actually fixes it.

When to run

• A meta-review skill (checkpoint) invokes one of the functions below programmatically.
• Do not respond to user prose triggers. There is no /retrospect-core command and no "when the user says X" branch. It is a format-and-orchestration helper.
• Stateless per call, with one exception: persist writes a report artefact to disk (the substrate the next run's diff reads).

The contract

The caller (checkpoint) owns:

• Which corpus to point at and where its files live.
• The passes — the domain logic that produces findings.

retrospect-core owns:

• orient(target) — inventory + since-last-run delta.
• diff(findings, baselinePath) — NEW/CARRIED/RESOLVED/WONT_FIX tagging.
• render(report) — the review-output-contract report body.
• route(finding) — propose-confirm-commit, then hand off to capture / memory-audit / a proposals stub.
• persist(report, scope) — write latest.md + v<N>.md for the next run's baseline.

A finding passed between caller and engine has this shape:

Finding = {
  id: "R<NNN>",                 // assigned by diff(); provisional in scan order before that
  pass: string,                 // caller's pass label — e.g. "decision-integrity", "responsibility-overlap"
  locator: string,              // the thing the finding is about: a proposal id, memory path, skill name, file:line
  verdict: string,              // pass-specific tag — e.g. HOLDS / SUPERSEDED-unmarked / DEAD / OVERLAP
  severity: "Critical"|"High"|"Medium"|"Low",
  what: string,                 // one-line, specific
  route: "capture"|"memory-audit"|"proposal"|"direct-fix"|"none",
  proposed_action: string,      // concrete — the capture content, the back-link edit, the proposal stub title
  status?: string,              // open | applied | skipped | wont_fix:<reason>  (set during route())
}