Make a finished plan admit it is finished

Context

The story behind this plan — what prompted the work and why it matters now.

Plans generated by plan-agent routinely finish implementation and never get
marked completed. The gallery then misrepresents what shipped.

The completion machinery is not missing — it is unreachable. Verified in the
current tree:

- skills/implementation-plan/SKILL.md:423,439,461 — the acceptance-criteria,
end-to-end-verification, and completion-checklist gates are all nested inside
the Implement now branch at :417. No other path reaches them.
- skills/implementation-plan/SKILL.md:400,516 — the sibling branch,
Exit — I'll implement later, states: "No implementation, no status change —
the plan stays at todo everywhere."
- skills/finalize-plan/SKILL.md:5 — disable-model-invocation: true bars the
model from ever auto-invoking the skill. Only a manually typed
/plan-agent:finalize-plan reaches it.
- hooks.json:3 — all four hooks are PostToolUse on Write|Edit|MultiEdit.
There is no Stop or SubagentStop hook, so nothing observes a session
ending.
- The only "always update status" instruction is ~/.claude/rules/plan-mode.md
§7 — a maintainer-local file that ships to nobody. Marketplace installs
(plan-agent 3.0.0) receive none of it.

Net: the dominant path — generate a plan, exit, implement it in a later
session — hits no gate at all.

### The mechanism, and why this one

Recommended: a drift-detector hook that hands off to the existing
verification skill. A new hooks/detect-plan-completion-drift.py fires on
plan-spec writes and reports one specific contradiction: every step carries
[x], every acceptance criterion is - [x], and status is not completed.
It reports; it never writes status. finalize-plan — unlocked in Step 3 — does
the actual verification and status write, behind its own existing
user-confirmation gate.

This is one mechanism in two files: the detector needs a callee it can actually
reach, and today it has none.

The design turns on a distinction that matters. The hook does not judge
whether the work is done — it cannot; acceptance criteria are prose. It detects
that the document contradicts itself, which is mechanical string-matching over
committed state. Resolving the contradiction is delegated to the skill that
already verifies against the codebase and asks the user. So nothing in this
chain asks the model to self-attest to completion.

Against the four failure modes:

| Failure mode | How this handles it |
|---|---|
| Silent skip (today's bug) | Solved for the dominant case. The renderer's implement-prompt already instructs the implementing agent to tick [x] markers and criteria as it goes; what gets forgotten is the final status: flip. That forgetting is the drift state, so the last tick trips the detector. |
| False completion | Structurally prevented. The hook writes nothing and decides nothing. finalize-plan inspects codebase evidence and gates on AskUserQuestion before any status write — behavior this plan does not alter. |
| Noisy prompts | Four conditions must hold simultaneously: the written file is a # Plan: spec inside the resolved plansDirectory, every step is [x], every criterion is - [x], and status != completed. The hook cannot fire in a session with no plan in play, because it only fires on writes to plan specs. |
| Plugin-user gap | Every behavioral change lands in kit/plugins/plan-agent/** and ships via the git-subdir source. Nothing depends on ~/.claude/rules/, repo-local settings, or this repo's layout. |

What this deliberately does not solve: a session that implements a plan and
ticks nothing. With no write to the spec there is no hook event, and the plan
stays silently at todo. Closing that hole completely needs a Stop hook
scanning the transcript to distinguish "implemented this plan" from "happened to
read it" — which trades directly into the noise column and cannot make that
distinction reliably. It is named in Next Steps rather than smuggled in here.
Partially ticked plans (some steps [x], not all) are likewise out of range by
design: that is a genuinely unfinished plan, and status: in-progress is
accurate.

### Feeding the detector: the prompts must ask for ticks

A detector that only fires on ticks is worth nothing if the prompts never ask
for any. Three prompts start an implementation, and only one of them teaches
check-off:

| Prompt | Path | Instructs check-off today? |
|---|---|---|
| Implement | copyCmd → buildImplementPrompt() (plan-shell.mjs:1306) | Yes — five numbered instructions covering [x] step markers, - [x] criteria, status: completed, and re-render. |
| Goal | copyGoal (plan-shell.mjs:1390) + plan-goal meta | No — copies the bare one-liner's textContent. |
| Workflow | copyWorkflow (plan-shell.mjs:1383) + plan-workflow meta | No — copies the bare one-liner's textContent. |

The workflow gap is the worst of the three, because that prompt says "Brief
subagents with the plan file" — so every subagent is briefed with a plan and
never told to record anything. Nothing ticks, no spec write happens, and the
detector in Steps 1–2 never fires. This plan's own rendered HTML has the defect:
its plan-workflow meta tag tells subagents to implement it and says nothing
about completion.

Both the copy handlers and the meta-tag strings need fixing, because they are
different delivery paths: implementation-plan/SKILL.md:482-483 sends the user
the workflow prompt read from the plan-workflow meta tag, not from the copy
button. Fixing only the button would leave the primary workflow path untouched.

Steps 6–8 close this. Together with the detector they narrow the never-ticked
hole to sessions that ignore the prompt entirely — without the Stop hook.

### Risks

- Exit-2 styling. This plugin's hook convention is stderr + sys.exit(2)
(hooks/validate-plan-filename.py:210-211), which the UI renders as a
"blocking error" even though PostToolUse cannot block an already-run tool.
A completion nudge styled as an error is a cosmetic mismatch. Mitigation:
follow the established convention for consistency; the message text carries
the framing. Revisiting the delivery channel repo-wide is a Next Step.
- Unlocking finalize-plan widens its activation surface. Mitigated by its
narrow description and its own confirmation gate. Step 3 tightens the
description so it reads as a completion action rather than an ambient one.
- The goal prompt gets the full check-off, including per-step [x] markers.
Decided during the plan interview, over the narrower alternative of criteria +
status only. The tension it creates is real and worth stating: the goal prompt
exists to tell an agent to optimize for the outcome and treat the plan as
reference, so an agent may legitimately achieve the objective without
following the plan's steps. Ticking those steps would then record work that
never happened — a false record, adjacent to the false-completion failure mode
this plan otherwise guards against. What keeps it honest is that the inherited
instruction is already conditional ("after completing each step, mark it
done"), so a bypassed step stays unticked. The consequence is that a
goal-driven agent which met every criterion by a different route cannot reach
status: completed, because not every step is [x]. Step 6 resolves that with
the mechanism the section catalog already provides: route the discrepancy to a
## Completion Report entry rather than a false tick. Re-open this if goal-run
plans start stalling at in-progress with clean criteria.
- The version bump reads the rule's spirit over its letter. Decided during
the plan interview: .claude/rules/marketplace.md lists "changing activation
behavior" under MAJOR, and this plan changes it. It ships as 3.1.0 anyway,
because the clause targets changes that invalidate existing usage and this one
does not — the command still works, nothing an installed user does breaks. The
cost is that a user skimming version numbers sees a routine minor bump and may
not notice the skill can now fire on its own. Mitigation: Step 9 makes the
CHANGELOG entry state the activation change outright, since it is now the only
place that information surfaces.