memory-mirror-harness

What this loop is for

Three disciplines exist elsewhere in this plugin: a memory file (memory-file skill), a proof gate (proof-discipline skill), and a fresh-context reviewer (fresh-context-reviewer agent). In isolation, none of them survives an unattended session on their own — an agent working alone has no external forcing function to actually invoke them in order. This skill is that forcing function. It defines the five-stage cycle and the durable ledger that lets the cycle survive context compaction.

Scope of the "spec + artifact only" rule

That strict input-isolation rule belongs to exactly one boundary in this loop: the stage-4 dispatch to the fresh-context-reviewer agent. It governs what goes into that one dispatch prompt. It is not a general rule for how every stage of this loop must be phrased, and it never means "refuse a stage because the request describing it didn't paste literal file contents." Every other stage (Plan, Act, Prove, Remember, and even the mechanics of constructing the stage-4 prompt itself) should treat descriptive task framing as ordinary input to act on.

The progress ledger

Alongside LEARNINGS.md, maintain PROGRESS.md (or an equivalent durable on-disk file) as the ledger of this session's work — distinct from LEARNINGS.md's durable cross-session lessons. The ledger records, per subtask:

## <subtask name>
- Status: not-started | in-progress | proof-verified | reviewed | done
- Ruled out: <approaches tried and confirmed not to work, with the disconfirming evidence in one clause each>
- Proof: <fresh command/test evidence citation, with a timestamp or turn marker, for the most recent proof-verified claim>
- Review: <gap-list summary from the fresh-context reviewer, or "pending">

The ledger is the thing that survives when conversational memory does not. Every stage below reads and writes it.

The five stages

Run these in order, for each subtask, in an unattended session:

1. Plan

State the specific subtask and what "done" will mean for it (which spec requirement it satisfies). Check PROGRESS.md first — if this subtask (or an approach to it) already has a ledger entry, honor it: do not re-attempt an approach the ledger records as ruled out, and do not re-plan from scratch what the ledger already shows as in-progress or complete.

2. Act

Do the work. Check LEARNINGS.md (full read, not just the index — see the memory-file skill) before acting if you have not already read it this session, and apply any relevant lesson.

3. Prove

Before any completion claim for this subtask, apply the proof-discipline skill's gate in full: fresh, cited, command/test evidence produced in direct response to this claim, or an explicit not-done report with the specific gap. Record the outcome in PROGRESS.md under Proof: — including a timestamp or turn marker, so a later resume can tell whether this evidence predates a subsequent change (see Resuming after compaction, below). Only mark the ledger status proof-verified when the gate is actually satisfied.

4. Review

Dispatch the fresh-context-reviewer agent. Construct its prompt from exactly two things: the original spec text for this subtask, and the finished artifact. Do not include implementer commentary, session narrative, or framing of which parts are "fine" — see the reviewer agent's own instructions for what disqualifies a dispatch. Log the exact prompt you sent (verbatim, or a byte-identical reference to it) somewhere auditable — a run log, the ledger entry, or equivalent — so the dispatch construction can be inspected later to confirm no bias leaked in. Record the reviewer's gap list in PROGRESS.md under Review:. Mark the ledger status reviewed.

This stage is never optional and never skippable — not for time pressure, not for implementer confidence, not because the change felt small. A subtask cannot be marked done in the ledger without a Review: entry produced by an actual reviewer dispatch in this run.

If no real artifact exists yet because this is an abstract/illustrative scenario, dispatch the reviewer with the best-available description of the artifact anyway, produce a concrete illustrative gap list, and label the whole exchange as illustrative in the log — do not substitute a bare "no artifact supplied" for this stage.

5. Remember

Apply the memory-file skill's session-end procedure: decide if anything durable and generalizable was learned this subtask (not merely that work happened), add at most one new LEARNINGS.md block if so, and prune/merge any now-stale existing blocks. Then mark the ledger status done for this subtask, but only if stage 4's review produced no unresolved gaps that block completion — if the reviewer found gaps, loop back to stage 2 (Act) to address them, then re-run stages 3 and 4 before reaching stage 5 again.

Deterministic halt condition

The loop for a given subtask halts, and that subtask is reported complete, only when all of the following are simultaneously true and recorded in PROGRESS.md:

1. Proof: holds fresh evidence (not stale — see freshness rule in proof-discipline) for the current state of the code.
2. Review: holds an actual gap list from a fresh-context-reviewer dispatch that used only spec + artifact, and that gap list contains no unresolved blocking gaps.
3. Status is done.

If any of the three is missing, the loop is not complete regardless of how confident the running agent's narration sounds. This is a structural check on the ledger's fields, not a judgment call.

The overall unattended session halts when every subtask in PROGRESS.md reaches done, or when a subtask is explicitly reported blocked with the specific blocking gap named (a valid, non-silent halt outcome).

Resuming after context compaction

Context compaction erases the running agent's working memory of what it already tried and proved — it does not erase LEARNINGS.md or PROGRESS.md on disk. On any resume (after compaction, or after any session restart mid-task):

1. Read LEARNINGS.md in full, before anything else.
2. Read PROGRESS.md in full, before anything else.
3. Treat every ledger entry as authoritative even though you have no memory of producing it. Do not re-attempt an approach the ledger records under Ruled out:. Do not re-claim a subtask as freshly done on the strength of a pre-compaction Proof: entry alone — that entry certifies the code as it was at that timestamp; if any change has touched that code since (check the ledger's own record of what was in-progress at compaction time, and check the actual current file state), the proof gate must be re-satisfied fresh before a new completion claim, exactly as the freshness rule requires for any other claim.
4. Resume at the earliest stage the ledger shows as incomplete for the current subtask — do not restart from Plan if the ledger shows Act and Prove already satisfied for still-current code; do not skip to Remember if Review is missing.

Model-agnosticism

Every stage transition and halt condition in this loop is decided by reading structural fields in PROGRESS.md (is Proof: present and fresh? is Review: present and gap-free? is status done?) — never by how a particular model narrates its own progress, how long its responses are, or what vocabulary it favors. This loop is designed to produce the same stage sequence and the same halt decision whether the running model is terse or verbose, and whether it is claude-fable-5, a Sonnet/Opus/Haiku model, or any future model family. If you notice an instinct to treat a short narration as "probably fine because it sounds confident" or a long one as "probably thorough because there's a lot of it," that instinct is exactly what this loop overrides — check the ledger fields, not the prose.

If you notice an instinct to treat a request as unanswerable merely because it describes a scenario abstractly rather than pasting literal file contents, that instinct is also wrong and is covered above under "Handling scenarios without a real on-disk artifact" / "Scope of the 'spec + artifact only' rule" — a request being abstract is not the same as a request being contaminated, and neither justifies refusing to demonstrate the loop's mechanics.