nw-finalize contradicts itself on removing the workspace #83

What goes wrong

nw-finalize's SKILL.md instructs the agent both to preserve and to remove the feature workspace directory. Phase C step 3 says it is not deleted and gives a reason; the Success Criteria, the Deliverables line, and Expected Outputs all say it is removed. Whichever an agent happens to weight produces the opposite tree state, so two runs of the same command on the same feature can legitimately disagree about whether docs/feature/{feature-id}/ still exists afterwards.

Why it matters

The two outcomes are not cosmetic. Phase C step 3 states the consequence of choosing wrong: "The wave matrix derives status from this directory. Removing it would make finalized features disappear from the matrix." So an agent that follows the Success Criteria silently destroys the data another part of nWave reads — and it destroys it at the one moment the feature is declared complete, which is exactly when nobody is looking for missing state.

Steps to reproduce

1. Run any feature through to a complete DELIVER (execution-log.json with all steps traced).
2. Run /nw-finalize @nw-platform-architect "{feature-id}".
3. Read ~/.claude/skills/nw-finalize/SKILL.md Phase C step 3, then its Success Criteria.
4. Observe that the two give opposite instructions for docs/feature/{feature-id}/.

Expected behaviour

One instruction. Given the stated wave-matrix dependency, preserving the directory looks like the intended behaviour and the three "removed" mentions look like leftovers from an earlier contract — but that is an inference from the surrounding text, not something I can confirm from outside the repo.

Actual behaviour

Four mutually inconsistent statements in one file (line numbers from the installed 3.21.0 copy):

Says preserve — Phase C, line 87:

3. Preserve workspace — docs/feature/{feature-id}/ is NOT deleted. The wave matrix derives status from this directory. Removing it would make finalized features disappear from the matrix. The evolution doc in docs/evolution/ is the summary; the feature directory is the history. Gate: directory preserved, session markers removed.

Reinforced at line 88:

4. Clean session artifacts only — Remove .nwave/des/deliver-session.json, .develop-progress.json, and any temp files. Do NOT remove wave artifacts (discuss/, design/, distill/, deliver/).

Says remove — Success Criteria, line 123:

• Workspace directory removed: docs/feature/{feature-id}/

Says remove — Next Wave / Deliverables, line 179:

Deliverables: docs/evolution/YYYY-MM-DD-{feature-id}.md, migrated artifacts, cleaned workspace

Says remove — Expected Outputs, line 189:

Removed: docs/feature/{feature-id}/

Phase D step 5 also reads as though a removal happened — "Commit workspace cleanup — Commit 2: workspace removal" — which leaves no commit to make if Phase C step 3 is followed.

Environment

• Version: nwave-ai 3.21.0
• OS / runtime: Linux 6.8.0-136-generic, Python 3.13
• Frequency: always — the contradiction is static text, not runtime-dependent
• Regression? Not verified. I only have the installed 3.21.0 copy and cannot tell from here which of the two contracts came first.

What I did about it

On a real finalize I followed Phase C step 3 and preserved the directory, on the grounds that it is the more specific instruction and the only one that states a reason. Flagging it because the opposite reading is equally available to an agent that reads the Success Criteria as the gate — and unlike most spec ambiguities, this one is destructive in one direction and merely untidy in the other.

Out of scope

• Whether the wave matrix should derive status from the feature directory — that is a design question; this issue is only about the file disagreeing with itself.
• The deliverable_type / plugin-mode work in First-class support for Claude Code plugin/skill projects #66.
• Any other nw-* skill; I have not audited them for the same pattern, though it would be worth a sweep if this turns out to be an artefact of a contract change.