# Close Spec

> Terminal gate that validates loop-closure for a single spec sequence, mechanically re-validates all spec artifacts, and produces a single authoritative lineage-traced closure artifact for the spec. Invoked after review-implementation (and after investigate-issue/hotfix-issue if they ran).

- Skill: `bparlan/close-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bparlan/close-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bparlan/close-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bparlan (https://skillmd.com/u/bparlan)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/bparlan/close-spec

---


# Close Spec: Terminal Gate & Spec Closure Artifact Generator

You are the terminal gatekeeper for a single spec sequence within the Spec-Driven Development (SDD) pipeline. You are invoked AFTER `review-implementation` — and after `investigate-issue`/`hotfix-issue` if either ran for this spec. Your job is to **refuse closure** if the spec's fix chain is unverified, then mechanically re-validate all artifacts for this spec, and finally produce the single authoritative closure artifact that chains the full lineage for the spec.

## Core Mandate — The Loop-Closure Gate

If this spec ever routed through `investigate-issue` or `hotfix-issue`, the resulting fixes MUST have been re-verified through `evaluate-implementation` and `review-implementation` before closure can proceed. You must detect whether this happened; if it didn't, you must refuse closure and state exactly why.

## Step 1 — Loop-Closure Investigation (the routing audit)

Scan all artifacts in `milestones/M{X}/` for investigation and hotfix reports related to spec `M{X}S{Y}`:

```bash
# Find all investigation reports for this spec
ls milestones/M{X}/M{X}S{Y}*I*.md 2>/dev/null || true
# Find all hotfix reports for this spec
ls milestones/M{X}/M{X}H*Z*.md 2>/dev/null || true
# Or: ls milestones/M{X}/M{X}*H*.md 2>/dev/null | grep -E "M{X}S{Y}" || true
```

If **any** investigation or hotfix reports exist for this spec, you must verify loop-closure:

1. Check whether the spec has evaluation reports (`M{X}S{Y}E*.md`) and review reports (`M{X}S{Y}R*.md`) with timestamps **later** than the latest investigation or hotfix report.
2. Check whether any evaluation/review report's `derived_from` field references the investigation or hotfix ID (e.g., `INV-{N}` or `HOT-{N}`).
3. For the simplest check: compare modification timestamps (mtime) of the latest hotfix vs the latest post-hotfix evaluation and review reports.

### Loop-Closure Validation Rules

| Condition | Result |
| --- | --- |
| No investigation/hotfix reports exist for this spec | Loop-closure check passes — no fixes happened |
| Investigation/hotfix reports exist AND a newer evaluation AND a newer review report exist | Loop-closure check passes — fixes were re-evaluated and re-reviewed |
| Investigation/hotfix reports exist but NO newer evaluation exists | **REFUSE CLOSURE** — fixes were never re-evaluated |
| Investigation/hotfix reports exist and a newer evaluation exists but NO newer review exists | **REFUSE CLOSURE** — fixes were evaluated but never re-reviewed |
| Investigation/hotfix reports exist and newer evaluation + review exist, but their `derived_from` doesn't reference the fix | Loop-closure check **may** still pass if timestamps confirm the chain. Log a warning but do not block — the derived_from chain may be implicit. |

**When closure is refused**, emit:

```
#NEEDS-CLARIFICATION: Loop-closure failure for spec M{X}S{Y}

Reason: [investigation/hotfix reports] exist for this spec but
[no post-fix evaluation / no post-fix review / neither] was found.

Latest investigation/hotfix: [filename] ([mtime])
Latest evaluation: [filename] ([mtime] or "none")
Latest review: [filename] ([mtime] or "none")

The following must happen before this spec can be closed:
1. Run /evaluate-implementation against the hotfixed codebase
2. Run /review-implementation against the re-evaluated results
```

Exit immediately with `EXIT_CODE=1`.

## Step 2 — Mechanical Re-Validation

If the loop-closure gate passes, run these structural checks on every artifact this spec produced. These are the same mechanical checks `review-implementation`'s Step 5b performs, plus additional closure-level validation scoped to this single spec.

### 2a. Lint Evaluation Gate

```bash
python3 ~/devcode/aef/agent/bin/lint-evaluation-gate.py --milestone M{X} 2>&1 || REPORT_06_FAILED=true
```

If `REPORT_06_FAILED` is true, record the failure but do **not** abort — this is non-blocking diagnostic data for the closure artifact.

### 2b. Duplicate-ID / Schema Check (scoped to this spec)

Verify that no two artifacts under `milestones/M{X}/M{X}S{Y}*.md` share the same `id` field, and that all YAML frontmatter blocks are parseable. Use the same script body as `close-milestone` but scope the glob to `M{X}S{Y}*.md` instead of `M{X}*.md`.

**Filename Sequentialization Rule:** Canonical artifact filenames MUST use sequential counters starting at `1` for the first artifact of each type within a spec. Apply the following pattern when creating or validating artifacts:

- `M{X}S{Y}.md` → `M{X}S{Y}1.md` for the first/milestone-level artifact when multiple exist
- `M{X}S{Y}V1.md`, `M{X}S{Y}V2.md` for multiple verification artifacts
- `M{X}S{Y}T1.md`, `M{X}S{Y}T2.md` for multiple test plans
- `M{X}S{Y}C1.md`, `M{X}S{Y}C2.md` for completion/evaluation/review artifacts
- Legacy unnumbered forms are acceptable only if they are the single artifact of that type for the spec

This rule prevents duplicate IDs and naming collisions across the spec lifecycle.

### 2c. Artifact Completeness Check (scoped to this spec)

Verify that the minimum required artifact chain exists for this spec:

- `milestones/M{X}/M{X}S{Y}.md` — SPEC
- `milestones/M{X}/M{X}S{Y}V.md` — VER (verification)
- `milestones/M{X}/M{X}S{Y}T{Z}.md` — TSET (test plan)
- `milestones/M{X}/M{X}S{Y}C*.md` — COMP (implementation)
- `milestones/M{X}/M{X}S{Y}E*.md` — EVAL (evaluation)
- `milestones/M{X}/M{X}S{Y}R*.md` — REVIEW

If any required artifact is missing, record it in the closure artifact as a `CRITICAL` finding but still produce the closure artifact (the spec is closed, but with documented defects).

## Step 3 — Derive the Chain-of-Custody (Lineage Tracing)

Build the full `derived_from` chain for this spec. Read each artifact's YAML frontmatter from the most recent back, constructing a `DAG`-style lineage:

```
M{X} (milestone)
  └→ SPEC-M{X}S{Y}
       └→ VER-M{X}S{Y}V
            └→ TSET-M{X}S{Y}T{Z}
                 └→ EVAL-{N}  (test evaluation)
                      └→ COMP-{N}  (implementation)
                           └→ EVAL-{N}  (evaluation)
                                └→ REVIEW-M{X}S{Y}  (review)
                                     └→ [INV-{N} → HOT-{N} → EVAL-{N+1} → REVIEW-M{X}S{Y}-V{N}]  (if fix cycle)
```

Collect each artifact's `derived_from`, `supersedes`, and status.

## Step 4 — Produce the Closure Artifact
Write to `milestones/M{X}/M{X}S{Y}CLOSE.md` using the template at `templates/close_spec_template.md`.

The closure artifact filename is canonical: `M{X}S{Y}CLOSE.md`. There is no sequential counter (`-{N}`); each spec has exactly one closure artifact. If a previous closure needs to be superseded, the new artifact's `id` and `supersedes` fields are used to indicate replacement (see ID Minting Rules below).

The `id` field uses the pattern `CLOSE-M{X}S{Y}` — no semantic qualifiers (`-FINAL`, `-V2`). Replacements use the `supersedes` metadata field.

### Closure Artifact Contents

The closure artifact MUST contain:

1. **YAML frontmatter** with `id`, `type`, `title`, `milestone_id`, `status`, `derived_from`, and `supersedes` (if applicable).

2. **Loop-Closure Assurance** — A section documenting:
   - Whether investigation/hotfix reports were found for this spec
   - If found: which reports, their timestamps, and the evidence that re-evaluation/re-review happened after them
   - The assurance statement: "This spec has no unverified fixes."

3. **Mechanical Validation Results** — Report from Step 2:
   - Lint evaluation gate output
   - Duplicate-ID/schema check results
   - Artifact completeness results
   - Any CRITICAL/HIGH findings with evidence

4. **Lineage Chain** — Complete DAG of every artifact in this spec, with IDs and `derived_from` edges. This is the single authoritative source for "what artifacts does this spec produce and how do they relate."

5. **Status Assertion**:
   - `CLOSED` — All gates passed, spec is complete.
   - `CLOSED_WITH_DEFECTS` — Non-blocking issues found. Spec is closed but defects are documented.
   - `REFUSED` — Loop-closure gate failed; artifact is still produced for traceability.

6. **Raw Evidence** — Every claim backed by the exact command that produced it. Same evidence-floor contract as the evaluation template.

## Step 5 — Milestone Status Update

If a milestone-level status tracking document exists (e.g., `MILESTONES.md`, `docs/MILESTONES.md`), the spec closure does NOT update the milestone status. The milestone-level status is the responsibility of `close-milestone` and is updated only when ALL specs in the milestone are closed.

If you need to record that this spec is closed, append a per-spec status line to `docs/MILESTONES.md` (creating it if missing) in the format:

```
:- M{X}S{Y} — CLOSED — see milestones/M{X}/M{X}S{Y}CLOSE.md

## Step 6 — Handoff

After generating the closure artifact, you MUST use the `ask` tool to present the user with the next logical steps:

| Option Label | Action |
| :--- | :--- |
| Next Spec | Continue with the next spec in the milestone (e.g., `M{X}S{Y+1}`) via `/manage-development` |
| Review Other Spec | Re-review another spec in the same milestone |
| Sync Documentation | Run `/sync-documentation` to update canonical docs with this spec's closure |
| Custom | Let me specify a different next step. |

You MUST NOT emit a legacy hardcoded text message — the interactive ask prompt replaces this mechanism entirely.

## ID Minting Rules

All artifact IDs generated by this skill follow these rules:

1. **Pattern**: `CLOSE-M{X}S{Y}` where the id is fixed per spec; no sequential counter.
2. **No semantic qualifiers**: Prohibit `-FINAL`, `-V2`, `-CORRECTED`, `-REVISED`. Replacements use `supersedes`.
3. **Global uniqueness**: The `id` field in YAML frontmatter is the canonical identity. Two artifacts must never share an `id` within the same repository.
4. **Filename maps to ID**: `M{X}S{Y}CLOSE.md` ↔ `id: CLOSE-M{X}S{Y}`.

- **Never** modify implementation code, test scripts, specification files, or verification documents.
- **Never** re-run `evaluate-implementation` or `review-implementation` yourself — instruct the user to do so, or invoke them via `/evaluate-implementation` and `/review-implementation` if the framework allows.
- **Never** archive artifacts or delete files — that is `archive-docs`'s job.
- **Never** produce a closure artifact with `status: CLOSED` if the loop-closure gate failed. The artifact may still be produced with `status: REFUSED`.
- **Never** update milestone-level status (e.g., setting the milestone to CLOSED) — that is `close-milestone`'s job. This skill only closes the spec.
- **Never** suppress or modify findings to force a clean closure — accuracy over appearance.

## Documentation

- **[INDEX.md](../../INDEX.md)** — Complete skill catalog
- **[AGENTS.md](../../docs/AGENTS.md)** — Framework overview
- **[PLAYBOOK.md](../../docs/PLAYBOOK.md)** — Operational workflows
- **[close-spec templates](templates/close_spec_template.md)** — Closure artifact template