Qstack Plan Adherence Review

/qstack-plan-adherence-review

Audit the implementation against the plan. Treat the plan as the contract, the code and test results as ground truth, and the execution record as supporting evidence that must itself be checked.

This is report-only work. Do not edit the plan, execution record, code, tests, or repository instructions. Do not commit or push. Write an adherence-review.md only when the user explicitly asks for a saved artifact; otherwise report in the final response.

Resolve the evidence

1. Use a plan path supplied by the user.
2. Otherwise use a plan clearly referenced in the conversation.
3. Otherwise inspect qstack/compound_engineering/plans/*/plan.html, then legacy compound-engineering/plans/*/plan.html and plan.md. Never select .template/. Use the only plausible candidate; ask when multiple candidates remain.
4. In the plan directory, prefer execution.md. Also read executor.md and legacy implementation-notes.md when present; do not discard history merely because a newer filename exists.
5. Read board-events.js beside them when it exists. Run node --check, then skip its required format header and fold the remaining qstackBoardEvent({...}); calls in file order for each card's final status, owner, refs, and files. Stop on broken JavaScript. Agents write the board while they work, so it has the standing execution.md already has here: evidence to be checked against the code, never trusted on its own. When only the retired board.jsonl exists, fold its raw JSON lines without editing it. If both board files exist, report the conflict and trust neither.

Read repository instruction files and the whole authoritative plan. Record the plan status. A draft or proposed plan may be reviewed, but state that it lacked implementation authority.

Determine the implementation range before judging it. Prefer, in order:

1. a base ref, reviewed fingerprint, or commit range explicitly recorded in the execution record;
2. a base supplied by the user;
3. the merge base with the repository's target branch, normally origin/main;
4. a range reconstructed from plan history and relevant commits.

Inspect committed changes, working-tree changes, and relevant untracked files. State the chosen base and inclusions. Exclude unrelated changes only with a concrete reason; list exclusions so hidden scope cannot improve the score.

Extract the plan contract

Turn the plan into individually testable obligations. Include:

• user-visible outcomes and acceptance criteria;
• locked decisions, interfaces, data shapes, and architectural constraints;
• required build and migration steps;
• validation and release gates;
• explicit non-goals when the implementation crosses them.

Do not turn background, rationale, rejected options, examples, or tentative ideas into requirements. Keep the plan's section or clause identifier on every obligation. Split compound requirements when their parts can succeed or fail independently.

Trace each obligation to reality

For every obligation, inspect the implementation and assign exactly one status:

• Met: direct code or test evidence satisfies it.
• Approved deviation: the implementation differs materially, and the record contains concrete evidence that the user approved the change.
• Partial: some required behavior exists, but a material part is absent or unproven.
• Missing: no implementation evidence exists.
• Unapproved deviation: reality materially differs without evidenced approval.
• Not verifiable: available evidence cannot establish the result.

An execution-record claim is not implementation evidence. Verify paths, symbols, behavior, migrations, generated artifacts, and tests against the current tree. When safe and proportionate, rerun focused validation rather than repeating a recorded success. Distinguish a missing test from a failing test and from a test that was not run.

With a board present, every card whose refs cite an obligation's clause is part of that obligation's evidence trail. Read Review mode from execution.md: exactly one full value says a done card passed per-card review, while exactly one final or none value deliberately omits that review. In every mode, done says only that the loop closed the card, not that the obligation holds, so verify the code exactly as above. When a legacy record has no Review mode, state that and treat it as the loops' former implicit full mode without penalizing the missing field; still verify its recorded reviews and board transitions. A duplicated, malformed, or unknown value is invalid execution evidence, not a legacy record. Flag it explicitly. Two board findings carry more weight than any card status:

• an obligation no card cites, which means the breakdown missed a requirement and nothing was ever scheduled to satisfy it;
• a card at done whose files show no corresponding change in the tree, which is the strongest single finding a board can produce.

Check the execution record and the board separately for:

• completed boxes whose implementation is missing;
• changes or decisions absent from the record;
• deviations mislabeled as ordinary implementation detail;
• approval claims with no recorded decision;
• stale validation results or fingerprints;
• a complete status that does not satisfy the plan's completion gate;
• in full mode, cards at done with no per-card review recorded, excluding the gate card of the review epic, which carries the plan-level review instead of a per-card one;
• in full or final mode, a missing or stale final review fingerprint;
• in none mode, a missing explicit record that review was skipped;
• a selected mode weaker than the minimum review required by the plan or repository instructions;
• board transitions or review evidence that contradict the recorded review mode;
• cards left at claimed or in-progress while the record calls the work complete;
• blocked cards whose question in note was never put to the user;
• split parents whose children were never created.

Score adherence

Assign one overall score. Use the lowest description that fits the material evidence; do not average away a serious miss.

Apply these score caps:

• Cap at 3 for any material unapproved deviation.
• Cap at 2 for a missing or failing blocker involving security, privacy, data correctness, migration safety, or a required release gate.
• Cap at 4 when any material obligation is not verifiable or the execution record materially misstates reality.
• Cap at 4 when the board and the execution record disagree about what was completed, because one of the two records is wrong and the review cannot tell which.
• Do not penalize an approved deviation merely for differing from the frozen plan; judge whether the approved replacement was actually implemented.

Counts support the score but do not determine it. Report totals for each status, then explain which material evidence set the score and which caps were applied.

Report

Lead with the verdict and score. Then provide:

1. Evidence reviewed: plan, execution records, base/range, working-tree state, and validation run.
2. Findings: ordered by severity, with plan clause, code or test evidence, impact, and concrete remedy. State explicitly when there are no findings.
3. Traceability matrix: one row per obligation: clause, concise promise, status, implementation evidence, execution-record evidence, and the cards citing that clause with their final status.
4. Record accuracy: contradictions and omissions in the execution record.
5. Score rationale: status counts, material failures, and any score caps.
6. Next actions: the smallest steps needed to reach a 5.

Use repository-relative file:line citations and commit identifiers. Never claim a behavior from filenames or comments alone. Separate verified facts from inference and say plainly when the evidence is insufficient.