closure-archivist

Closure Archivist

Use this skill to finish a spec-superflow change cleanly.

Use This Skill When

Invoke this skill when the user says things like:

"wrap this up"
"give me the final summary"
"is this ready to close"
"what remains before we ship"
"prepare the handoff"

The Iron Law: Verification Before Completion

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Claiming work is complete without verification is dishonesty, not efficiency.

Violating the letter of this rule is violating the spirit of this rule.

If you haven't run the verification command in this session, you cannot claim anything passes.

The Gate Function

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Forbidden Words

These words MUST NOT appear in your output until AFTER verification evidence is presented:

"should" (as in "tests should pass")
"probably" (as in "it probably works")
"seems to" (as in "it seems to be done")
"Great!" / "Perfect!" / "Done!" (before verification output)
Any expression of satisfaction without evidence

Rationalization Prevention

Excuse	Reality
"Should work now"	RUN the verification
"I'm confident"	Confidence ≠ evidence
"Just this once"	No exceptions
"Linter passed"	Linter ≠ compiler
"Partial check is enough"	Partial proves nothing
"Different words so rule doesn't apply"	Spirit over letter

Verification Evidence Requirements

Claim	Requires	Not Sufficient
Tests pass	Test command output: 0 failures	Previous run, "should pass"
Linter clean	Linter output: 0 errors	Partial check, extrapolation
Build succeeds	Build command: exit 0	Linter passing, logs look good
Bug fixed	Test original symptom: passes	Code changed, assumed fixed
Regression test works	Red-green cycle verified	Test passes once
Requirements met	Line-by-line checklist	Tests passing

Responsibilities

verify that the approved behavior was actually implemented
summarize what changed
identify remaining risks or follow-up work
prepare the change for archive or handoff
check for delta specs that need syncing

Required Inputs

Read:

execution-contract.md
tasks.md
relevant specs/
change summary notes, if any

Verification Steps

Step 1: Test Suite Verification (Correctness)

Run the full test suite. Record:

Total tests, passed, failed, skipped
Zero failures required for PASS
Any failure = CRITICAL finding in Correctness dimension

Step 2: Completeness Verification

Compare the execution contract's task batches against the actual diff:

List all tasks from the execution contract
For each task, verify a corresponding code change exists in the diff
For each SHALL/MUST requirement in specs, verify at least one implementation artifact
Missing items = CRITICAL findings in Completeness dimension

Step 3: Coherence Verification

Compare design.md decisions against the implementation:

Extract each decision's Choice from design.md
Verify the choice is reflected in the code (naming, patterns, architecture)
Check naming consistency between specs and implementation
Inconsistencies = IMPORTANT findings in Coherence dimension

Step 4: Unintended Scope Detection

Check the diff for unplanned changes:

Files modified that are not in the execution contract's scope fence
New dependencies added that are not in the design's constraints
Unplanned changes = WARN findings in Completeness dimension

Step 5: Verification Report

Produce a structured report:

Dimension	Status	Findings
Completeness	PASS/FAIL/WARN	[list]
Correctness	PASS/FAIL/WARN	[list]
Coherence	PASS/FAIL/WARN	[list]

Overall verdict: PASS (all PASS) / CONDITIONAL (WARN only) / FAIL (any FAIL)

If FAIL → do not claim completion. Fix issues or route back to execution-governor. If CONDITIONAL → present WARN findings to user, proceed only with explicit acceptance. If PASS → proceed to final checks.

Final Checks

Are required tests passing? (cite the command and output)
Are execution batches complete? (cite batch-by-batch status)
Was any scope added without artifact updates? (cite specific files if yes)
Are there unresolved blockers or known risks?
Is the change ready to archive, or should it remain active?
Do delta specs exist that need merging into main specs?

Output

Verification report table (three dimensions with status and findings)
Overall verdict
If PASS: summary of all contract obligations met
If CONDITIONAL: list of accepted warnings
Risks and follow-ups
Archive readiness assessment

Archive Rule

Do not archive blindly.

If implementation diverged from the contract, return to bridging before closure.

Post-Verification Routing

After verification completes:

Run: node scripts/spec-superflow.mjs state transition <change-dir> closing
This updates .spec-superflow.yaml with state: closing and records the transition
If delta specs were created, route to spec-syncer before final archiving
If no delta specs exist, the change is ready to archive

The closure is not complete until delta specs are merged. Specs that aren't synced become lies.

Output Standard

Your response should include:

verification evidence (command run, output excerpt, exit code)
contract obligation status (which passed, which didn't)
delivered behavior summary
residual risks
delta spec status (exist or not)
recommended routing (to spec-syncer or archive)

Lightweight Closure (hotfix/tweak mode)

When workflow is hotfix or tweak, closure-archivist performs lightweight verification:

Verify all changed files exist and are non-empty
Run syntax check on code files (node --check for .mjs/.js)
Skip the full 5-step three-dimensional verification
Still record DP-6 (verification failed) and DP-7 (archive confirmation) decision points
Delta specs are NOT generated in lightweight closure (no specs to sync)

Reference: docs/decision-points.md → DP-6, DP-7