vt-c-5-finalize¶

Phase 5 - Final quality verification and merge readiness using the finalization-orchestrator. Runs security audit, migration checks, and compliance validation.

Plugin: core-standards
Category: Development Workflow
Command: /vt-c-5-finalize

Phase 5: Finalize - Quality Verification & Merge Readiness¶

Verify your code is safe to merge with security audits, migration checks, and compliance validation.

Workflow Position¶

/activate → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → [ /vt-c-5-finalize ] → /vt-c-complete
                                                                ▲ YOU ARE HERE
                                                                ↑ deliverable_types determines gate enforcement

Invocation¶

/vt-c-5-finalize                     # Standard finalization check
/vt-c-5-finalize --env production    # Specify environment
/vt-c-5-finalize --migration         # Include migration safety check

Intent Constraints¶

This skill MUST NOT: - Proceed without both .review-gate.md (status: PASS) and .test-gate.md (status: PASS) - Override a NO-GO decision without explicit user approval and documented rationale - Skip the security scan, even for urgent deployments - Modify any source code, tests, or configuration (verification only) - Downgrade the severity of any finding to achieve a GO decision

This skill MUST STOP and surface to the user when: - A finalization check returns an unexpected or ambiguous result - npm audit reveals critical vulnerabilities with no available fix - The review gate branch does not match the current branch - Migration safety analysis identifies potential data loss

Execution Instructions¶

This command invokes the finalization-orchestrator agent.

Step 0a: Read Phase Checkpoint¶

If .claude-checkpoint.md exists in the project root: 1. Read the file 2. Display: Resuming from checkpoint: {completed_phase} completed at {timestamp} 3. Display the "Context for Next Phase" section content 4. If next_phase is 4-review (review not yet completed): HARD BLOCK — display "Code review required before finalization. Run /vt-c-4-review first." and stop. 5. If next_phase doesn't match 5-finalize (other mismatch): warn (advisory, not blocking)

If no checkpoint exists: proceed silently.

Step 0: Review Gate Check (Mandatory)¶

Before any finalization work, verify that code review has been completed and passed.

Note: After this gate check passes, proceed to Step 0.5 before continuing.

Step 0.5: Project Registration Check¶

Read TOOLKIT_ROOT/intake/projects.yaml (resolve TOOLKIT_ROOT from this skill's base directory)
Check if the current working directory appears in the projects list
If NOT registered and the project has a CLAUDE.md or .design-state.yaml:
Ask: "This project is not registered in the toolkit. Register now to enable cross-project scanning and journal aggregation?"
Options: Register now (invoke /vt-c-project-register) | Skip for now
If registered: continue silently

Step 0.7: Read Deliverable Types¶

Read deliverable_types from specs/[N]-feature/spec.md YAML frontmatter
If present and non-empty: use as-is
If missing: warn "No deliverable_types in spec frontmatter — defaulting to [code]" and treat as [code]
Display: "Deliverable types: {list}"

The detected types determine which gates are enforced and which finalization checks are run.

Read .review-gate.md from the project root

If file is missing:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: No Review Gate Found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Code review has not been run. Finalization requires a passing review.

Run /vt-c-4-review first, then retry /vt-c-5-finalize.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed with finalization.

If status: FAIL:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: Review Gate FAILED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The last code review did not pass.
Critical: [critical_count] | High: [high_count]

Fix the issues listed in the review, then re-run /vt-c-4-review.
Only after the review passes can /vt-c-5-finalize proceed.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed with finalization.

If branch doesn't match current branch:

⚠ Review gate was for branch '[gate-branch]' but you are on '[current-branch]'.
  The review may be stale. Consider re-running /vt-c-4-review on this branch.

Display warning but allow the user to decide whether to proceed.

If status: PASS and branch matches: Display confirmation and proceed.

✓ Review gate: PASS (reviewed [date] on branch [branch])
  Critical: 0 | High: [high_count] | Findings: todos/

Step 0b: Test Gate Check¶

After verifying the review gate, also verify that automated tests have passed.

When code is NOT in deliverable_types: Accept .test-gate.md with status: NOT_RUN. Display "Test gate: NOT_RUN (accepted — no code deliverables)" and proceed. If the file is missing entirely, this is also acceptable for non-code specs — display the same message and proceed.

When code in deliverable_types (existing behavior):

Read .test-gate.md from the project root

If file is missing:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: No Test Gate Found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Automated tests were not run. Finalization requires passing tests.

Run /vt-c-4-review first (which runs the test suite), then retry /vt-c-5-finalize.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed with finalization.

If status: FAIL:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: Test Gate FAILED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[failed] of [total] tests failed. Finalization requires all tests passing.

Fix failing tests and re-run /vt-c-4-review.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed with finalization.

If branch doesn't match current branch: Display warning (advisory, same as review gate).

If status: PASS and branch matches: Display confirmation and proceed.

✓ Test gate: PASS ([total] tests, [passed] passed, [duration])

Step 0c: Version Gate Check¶

When code is NOT in deliverable_types: Skip the version gate entirely. Display "Version gate: SKIPPED (no code deliverables)" and proceed to Step 0a.

When code in deliverable_types (existing behavior):

After verifying review and test gates, verify that plugin version bumps and changelogs are in order.

Run the version gate script using the Bash tool:
```
"$CLAUDE_PLUGIN_ROOT/scripts/check-finalize-versions.sh"
```
If $CLAUDE_PLUGIN_ROOT is not set, locate the script relative to this skill file at ../../scripts/check-finalize-versions.sh.
If output starts with VERSION_GATE: FAIL:

Auto-fix instead of blocking. Determine and apply the version bump automatically:

2a. Determine bump type:

# Check if new files were added under plugins/*/skills/ or plugins/*/agents/
git diff --name-status main...HEAD -- 'plugins/*/skills/' 'plugins/*/agents/'

- If any lines start with A (added): bump type = MINOR (new capability) - If only M (modified): bump type = PATCH (improvement/fix)

2b. Compute new version: - Read current version from plugins/registry.json (parse JSON, extract version for affected plugin) - For MINOR: increment middle number (3.21.0 → 3.22.0) - For PATCH: increment last number (3.21.0 → 3.21.1)

2c. Count current skills:

grep -c " -> " plugins/core-standards/.claude-plugin/skill-symlinks.manifest

2d. Apply auto-fix:

Update version in plugins/registry.json (Edit tool)
Update version AND skill count in plugins/{name}/.claude-plugin/plugin.json (Edit tool)
Generate CHANGELOG entry:
- Read active spec title from specs/[N]-feature/spec.md frontmatter (title: field)
- Read branch commits: git log main..HEAD --oneline
- Write a ## [new-version] - YYYY-MM-DD section at the top of plugins/{name}/CHANGELOG.md:
```
## [3.22.0] - 2026-03-24

### Added

- [Summarize from spec title and commit messages] (SPEC-NNN)
```
- If a section for this version already exists in CHANGELOG: skip CHANGELOG generation

Stage the changes:

git add plugins/registry.json plugins/*/plugin.json plugins/*/CHANGELOG.md

Commit:

git commit -m "chore: bump core-standards to [version] (SPEC-NNN)"

2e. Report and continue:

✓ Version auto-bumped: 3.21.0 → 3.22.0 (MINOR — new skill added)
  - plugins/registry.json updated
  - plugin.json updated (skills: 104 → 105)
  - CHANGELOG.md entry added

Continue finalization — do NOT stop or require re-run.

Exception — MAJOR bump: If the script output mentions breaking changes or the spec title contains "breaking" or "remove", do NOT auto-bump. Instead display:

⚠ Potential breaking change detected — manual version bump required.
  Review the changes and bump the MAJOR version manually if appropriate.

STOP only in this case.

If output starts with VERSION_GATE: WARN:

⚠ Version gate: WARN
  [List each WARNINGS line from script output]
  [List VERSION_CHANGES lines from script output]

Display warning but proceed with finalization.

If output starts with VERSION_GATE: PASS:
```
✓ Version gate: PASS
```
If VERSION_CHANGES lines are present, also display them:
```
✓ Version gate: PASS ([list VERSION_CHANGES summaries])
```
If the NOTE line says "No plugin code changes detected", display:
```
✓ Version gate: PASS (no plugin code changes)
```
If the script fails to run (command not found, Python3 missing, etc.):
```
⚠ Version gate: SKIPPED (script error — check-finalize-versions.sh not available)
```
Display warning but proceed. Do not block finalization due to script infrastructure issues.

Important: Save the VERSION_CHANGES output from this step for use in the TL;DR summary (Step 5).

Step 0a: Check for Spec-Driven Mode¶

If .specify/ directory exists:

Load constitution - .specify/memory/constitution.md for principles
Derive active spec from branch — check .active-spec file first, then parse branch name (feature/spec-NNN-* → SPEC-NNN), then look up specs_dir in .design-state.yaml
Read completion status from specs/[N]-feature/state.yaml
Load spec - specs/[N]-feature/spec.md for completeness verification

Display status:

✓ SpecKit detected - Constitution compliance verification enabled
• Finalization will verify constitution principles
• Spec coverage will be checked

If NO .specify/:

Standard finalization checks (no spec validation).

Step 1: Load Institutional Knowledge¶

Before finalization checks:

Load docs/solutions/patterns/critical-patterns.md - Check for known issues
Load docs/runbooks/ - Reference existing procedures
Check recent incidents that might affect this release
If SpecKit: Load constitution and spec from Step 0

Step 2: Run Finalization Checks¶

The finalization-orchestrator coordinates:

Check	Tool	Purpose
Repo Governance	/vt-c-repo-audit --ci-mode	Zero context bleed, LFS compliance
Dependency Audit	npm audit / bundle audit	Known vulnerabilities
Security Scan	security-sentinel	Final security review
Migration Safety	data-integrity-guardian	Zero-downtime migrations
Compliance	compliance-checklist	GDPR/SOC2 requirements

Step 2 (non-code): Content Finalization Checks¶

When non-code types present in deliverable_types, run these additional checks:

Link validation — All internal and external links in deliverables resolve correctly
Format verification — Consistent heading hierarchy, proper list formatting, no skipped heading levels
Placeholder detection — No TODO, FIXME, TBD, [fill in], or other placeholder content remains

When document or presentation in types, also run delivery checks (absorbed from kw-4-publish):

Delivery format checklist:
[ ] Correct file format (Markdown, PDF, PPTX as specified)
[ ] File names follow conventions
[ ] Version/date stamp present
[ ] Access permissions appropriate
Stakeholder readiness checklist:
[ ] Executive summary or key highlights prepared
[ ] Key points are prominent and easy to find
[ ] Next steps clearly identified

[ ] Stakeholder communication template generated:

Subject: [Deliverable name] — Ready for Review
Body: [Summary of what was delivered, key highlights, next steps]

Step 2a: Repo Governance Audit (if `.repo-manifest.yaml` exists)¶

Run /vt-c-repo-audit --ci-mode before other checks:

FAIL if any context bleed detected (context artifacts in deployable paths or build output)
FAIL if oversized untracked binaries found in deployable paths
WARN (non-blocking) for traceability gaps or stale sandbox files
SKIP if no .repo-manifest.yaml present

This is the "Finalization Auditor" from the Unified Repo Governance model — ensures zero leakage of design, prompt, or prototype files into the production bundle.

Step 2b: State Documentation Maintenance Gate (advisory)¶

Check whether UI state documentation may need updating based on changed files.

Check for state matrix existence: Look for 01-docs/deliverables/implementation-readiness/ui-state-matrix.md in the project. If the file does not exist → skip this step silently.
Get changed files:
```
git diff --name-only $(git merge-base HEAD main) HEAD
```
If the git command fails → display "State documentation check: SKIPPED (git diff unavailable)" and continue.
Grep for state-affecting patterns in changed file names and content:
Filename patterns: *state*, *State*, *guard*, *route*
Content patterns: enum.*State, interface.*State, type.*State, ngIf, ngSwitch, @if, @switch, [hidden], canActivate

If matches found (advisory, non-blocking):

State documentation advisory:
─────────────────────────────────────────────────────────────────
UI logic changes detected in {N} file(s). Verify that the state matrix
(01-docs/deliverables/implementation-readiness/ui-state-matrix.md)
is still current.

Changed files with state-affecting patterns:
• {file1}
• {file2}
─────────────────────────────────────────────────────────────────

If no matches found → continue silently.

Step 2.5: User Manual Build Gate¶

Skip silently if docs/user-manual/mkdocs.yml does not exist.

When docs/user-manual/mkdocs.yml exists:

Build the manual:

cd docs/user-manual && python3 -m mkdocs build --strict -d /tmp/user-manual-build-test 2>&1

If build fails (exit code != 0):

[FAIL] User Manual Build Gate
      docs/user-manual/ failed mkdocs build --strict:
      [error output]

BLOCK finalization — broken documentation must not ship.

If build succeeds:

[PASS] User Manual Build Gate — docs/user-manual/ builds successfully

If mkdocs is not installed (command not found):
```
[WARN] User Manual Build Gate — mkdocs not installed, skipping build validation
```
Continue without blocking — do not fail finalization due to missing local tooling.

Draft marker detection:

grep -rl "<!-- DRAFT" docs/user-manual/docs/**/*.md 2>/dev/null

If matches found, report as Medium severity (non-blocking):

[WARN] User Manual: N page(s) contain unreviewed draft content
      • docs/user-manual/docs/features/feature-a.md
      • docs/user-manual/docs/features/feature-b.md

Documentation coverage report:
Scan all specs/*/state.yaml files for docs_page fields
For each docs_page, check if the file exists

Report:

Documentation coverage: N/M features documented
  DOCUMENTED: feature-a, feature-b, feature-c
  MISSING: feature-d (specs/4-feature-d/state.yaml → docs/user-manual/docs/features/feature-d.md)
  ORPHANED: getting-started.md (no spec reference — manual addition)

Missing pages are reported as Low severity (advisory). Orphaned pages are informational only.

Step 3: Produce Finalization Report¶

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 5: Quality Verification & Merge Readiness
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Environment: [production/staging]
Branch: [current branch]
Last Commit: [commit hash and message]

Check Results:
─────────────────────────────────────────────────────────────────
[✓/✗] Dependency Security Audit
      • High vulnerabilities: X
      • Critical vulnerabilities: X

[✓/✗] Final Security Scan
      • Issues found: X

[✓/✗] Migration Safety (if applicable)
      • Migrations: X pending
      • Zero-downtime compatible: Yes/No

[✓/✗] Compliance Verification
      • GDPR: Compliant/Issues found
      • Data handling: Reviewed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3b: Built-In Security Review Gate¶

When code is NOT in deliverable_types: Skip the security review gate. Display "Security review: SKIPPED (no code deliverables)" and proceed to Step 4.

When code in deliverable_types (existing behavior):

After producing the finalization report, invoke the built-in /security-review command for a final automated security pass before the Go/No-Go decision.

Invoke /security-review scoped to the branch diff for a final security verification.
Fallback: If /security-review is not available (command not recognized or returns an error):
```
Warning: Built-in /security-review not available in this Claude Code version.
Relying on security-sentinel scan results only.
```
Log the warning and continue to Step 4. Do not block finalization due to tool unavailability.
Blocking behavior: If /security-review finds HIGH severity findings that are unresolved:
Add to blocking issues for the NO-GO decision
All HIGH findings must be enumerated individually (EC4)

Quality gates checklist item: Add to the finalization checklist:

[ ] Security review passed — /security-review HIGH findings resolved

Merge results: Include /security-review findings in the finalization report alongside the security-sentinel results from Step 2.

Step 4: Go/No-Go Decision¶

If GO:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DECISION: GO - Safe to Merge
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All checks passed. You may proceed with merging.

Rollback Plan:
─────────────────────────────────────────────────────────────────
Previous version: [version/vt-c-commit]
Rollback command: [specific rollback instructions]
Monitoring: Check [service] for errors post-merge

Post-Merge Steps:
1. Documentation sync (Step 4.5 — runs automatically next)
2. Monitor error rates for 15 minutes
3. Verify key user flows work
4. Check logs for unexpected errors

TIP: Pre-PR simplify ritual (optional):
  1. git commit (save current work)
  2. /simplify (run 3 parallel quality agents)
  3. git diff (review improvements)
  4. git commit -m "refactor: simplify" (commit improvements)
  See references/simplify-guide.md for focused mode and skip conditions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT: Merge PR to main
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After successful merge, Phase 6 (/vt-c-6-operate) covers:
• Bug investigation if issues arise
• Incident response procedures
• Continuous improvement

If NO-GO:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DECISION: NO-GO - Blocking Issues Found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Finalization blocked due to:

[List of blocking issues with details...]

Required Actions:
─────────────────────────────────────────────────────────────────
1. [Specific action to fix issue 1]
2. [Specific action to fix issue 2]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ACTION: Fix issues, then run /vt-c-5-finalize again
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommended: Address the blocking issues listed above, then re-run /vt-c-5-finalize.

Step 4.5: Documentation Sync (GO only)¶

Only execute this step if the decision was GO or GO WITH CAUTION.

4.5a: Capture change ledger entry

Invoke /vt-c-doc-sync --log to interactively record what changed: - What was added, modified, or removed - Why (the spec/feature that drove it) - Key files affected

This appends an entry to docs/change-ledger.md.

4.5b: Apply mechanical documentation fixes

Invoke /vt-c-doc-sync --fix to automatically update: - Component counts in README.md, docs/index.md, macros.py, plugin.json - Version references against plugins/registry.json - Deprecated terminology - What's New section (regenerated from change ledger) - MkDocs nav entries if needed

4.5c: Report result

Documentation Sync:
─────────────────────────────────────────────────────────────────
Change ledger: Entry added for [spec/feature name]
Counts updated: [N] files fixed
What's New: Regenerated
Remaining drift: [0 | N items — list them]

If /vt-c-doc-sync --fix reports remaining manual-fix items, list them as advisories (non-blocking — finalization continues).

Step 4.7: Non-code Delivery Summary¶

Only when non-code types present in deliverable_types.

Synthesize a delivery summary from journal entries and deliverable content:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Delivery Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Goals achieved:
• [goal 1 from spec, with status]
• [goal 2 from spec, with status]

Key decisions:
• [decision 1 from journal entries]
• [decision 2 from journal entries]

Lessons learned:
• [lesson 1 from journal entries]

Post-delivery actions:
─────────────────────────────────────────────────────────────────
1. Run /vt-c-consolidate to archive session learnings
2. Capture stakeholder feedback via /vt-c-journal "Feedback: ..."
3. Consider /vt-c-compound if this solved a reusable problem
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If no journal entries exist, base the summary on the spec goals and deliverable content only.

Step 4.8: Persist Finalize Gate in state.yaml¶

After the GO/NO-GO decision, persist the finalize result for committed audit trail:

Derive the active spec from the branch name (feature/spec-NNN-* → SPEC-NNN)
Look up specs_dir in .design-state.yaml
Read specs/[N]-feature/state.yaml

Add or update the finalize_gate section:

finalize_gate:
  status: GO|NO-GO
  date: "YYYY-MM-DD"
  version: "[bumped version or N/A]"
  checks_passed: N
  checks_failed: N

Write the updated state.yaml
Stage: git add specs/[N]-feature/state.yaml

If no active spec or no state.yaml: skip silently. If write is denied (context: fork): skip silently — the GO/NO-GO decision in the TL;DR output is sufficient for the current session.

Step 4.9: Write Phase Checkpoint¶

Write .claude-checkpoint.md to the project root: - completed_phase: 5-finalize - next_phase: complete - next_command: /vt-c-complete - branch: current git branch - active_spec: derived from branch or .active-spec - clear_recommended: false - clear_reason: "Completion is brief — merge and mark done" - Key Outcomes: GO/NO-GO decision, version bump, checks passed - Context for Next Phase: merge instructions, post-merge steps

Display the clear recommendation per the phase-checkpoint protocol.

Step 5: TL;DR Summary (Final Output)¶

This MUST be the absolute last output of the finalization check. Nothing may follow it. Max 10 lines between delimiters.

After ALL previous steps (including the GO/NO-GO decision and any file writes), output a concise summary using the format below. Fill in values from Steps 2–4.

If GO:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TL;DR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Decision: GO
Checks: [N] passed | [N] failed | [N] warnings
Constitution: COMPLIANT
Version: [VERSION_CHANGES from Step 0c, e.g. "core-standards 3.0.0 → 3.1.0 (MINOR)"]
Docs: Synced (change ledger + counts updated)
Branch: [branch-name]

Next: Merge PR to main
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If GO WITH CAUTION:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TL;DR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Decision: GO WITH CAUTION
Checks: [N] passed | [N] failed | [N] warnings
Constitution: COMPLIANT
Version: [VERSION_CHANGES from Step 0c, e.g. "core-standards 3.0.0 → 3.1.0 (MINOR)"]
Spec Coverage: [Z]% (some requirements pending)
Docs: Synced (change ledger + counts updated)
Branch: [branch-name]

Next: Merge PR to main, track pending requirements in backlog
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If NO-GO:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TL;DR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Decision: NO-GO
Checks: [N] passed | [N] failed | [N] warnings
Constitution: [COMPLIANT / VIOLATIONS]
Version: [VERSION_CHANGES from Step 0c, or "BLOCKED" if version gate failed]
Branch: [branch-name]

Blockers: [list of blocking issues]
Next: Address blockers, then re-run /vt-c-5-finalize
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If stale gates detected:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TL;DR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Decision: NO-GO (stale gates)
Branch: [branch-name]
Stale: [review-gate/test-gate] from branch [other-branch]

Next: Re-run /vt-c-4-review on current branch, then /vt-c-5-finalize
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Notes: - Omit the "Constitution" line if SpecKit is not active (no .specify/ directory) - Omit the "Blockers" line if there are no blocking issues - The "Version" line uses the VERSION_CHANGES from Step 0c. If no plugin changes were detected, use "No plugin changes". If the version gate was skipped, omit the line. - The TL;DR summarizes Steps 2–4; do not repeat the full report

Error Handling (context: fork)¶

This skill runs with context: fork — it executes as an isolated sub-agent that returns only its output to the parent conversation. Fork sub-agents CANNOT interact with the user.

Critical rules for fork context:

NEVER ask interactive questions. No "Would you like...?", no "Should I...?", no AskUserQuestion calls. The question will be swallowed, the sub-agent will die, and the parent conversation receives no output at all.
If a file write fails, report it inline and continue. Use this format:

Warning — file not persisted: Could not write {filename}. The full content is included in the output above. To persist, copy the content manually or re-run with write permissions.
Always produce the full formatted output as the primary deliverable. The formatted finalization report returned to the parent conversation is the primary output. File persistence is secondary. Complete all analysis, checks, and formatting BEFORE attempting any file writes.
Finalization report is the primary output: The GO/NO-GO decision with full check results MUST always be returned to the parent conversation as formatted text, regardless of whether any file writes succeed.

Finalization Checks Detail¶

Dependency Security Audit¶

Runs npm audit or bundle audit
Identifies known vulnerabilities in dependencies
Flags high/critical issues as blocking

Final Security Scan¶

Last-pass security review
Checks for any issues missed in Phase 4
Validates authentication/authorization

Migration Safety¶

If database migrations are pending: - Checks for zero-downtime compatibility - Validates rollback capability - Checks for data loss risks - Verifies large table handling

Compliance Verification¶

GDPR data handling review
SOC2 logging requirements
PII protection validation
Audit trail completeness

Constitution Compliance (When SpecKit Active)¶

If .specify/ exists, finalization checks include:

Constitution Verification¶

Constitution Compliance Check:
─────────────────────────────────────────────────────────────────
Verifying release meets .specify/memory/constitution.md principles...

[✓/✗] [Principle 1 from constitution]
[✓/✗] [Principle 2 from constitution]
[✓/✗] [Principle 3 from constitution]
...

Constitution Status: COMPLIANT / VIOLATIONS FOUND

Spec Coverage Verification¶

Spec Coverage Check:
─────────────────────────────────────────────────────────────────
Verifying specs/[N]-feature/spec.md requirements are implemented...

Total Requirements: X
Implemented: Y
Coverage: Z%

Unimplemented (if any):
• [Requirement not yet implemented]

Finalization Decision with SpecKit¶

GO with full spec compliance:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DECISION: GO - Spec Compliant
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All constitution principles respected
✓ Spec requirements implemented
✓ Standard checks passed

CAUTION with partial spec coverage:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DECISION: GO WITH CAUTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Constitution principles respected
⚠ Spec coverage: X% (some requirements pending)
✓ Standard checks passed

Pending requirements should be tracked in backlog.

Feature Flag Recommendation¶

For risky changes, consider:

TIP: Use feature flags for gradual rollout

The feature-flags skill provides patterns for:
• Percentage-based rollouts
• User segment targeting
• Kill switches for quick rollback

This allows deploying code with features disabled,
then gradually enabling for users.

Open Brain Capture (Optional)¶

After producing the Go/No-Go decision, if the capture_thought MCP tool is available, capture the finalization outcome.

When to capture: After every completed finalization (GO, NO-GO, or GO WITH CAUTION).

How: 1. Check if capture_thought tool is available. If not: skip silently. 2. Call capture_thought with:

thought: "Release decision: {GO/NO-GO/GO WITH CAUTION} for {spec title} on branch {branch}. Checks passed: {N}/{total}. Constitution: {COMPLIANT/VIOLATION}. Key concern: {top issue or 'none'}."

3. On timeout or error: log debug message and continue. Never fail the skill.

vt-c-5-finalize¶

Phase 5: Finalize - Quality Verification & Merge Readiness¶

Workflow Position¶

Invocation¶

Intent Constraints¶

Execution Instructions¶

Step 0a: Read Phase Checkpoint¶

Step 0: Review Gate Check (Mandatory)¶

Step 0.5: Project Registration Check¶

Step 0.7: Read Deliverable Types¶

Step 0b: Test Gate Check¶

Step 0c: Version Gate Check¶

Step 0a: Check for Spec-Driven Mode¶

Step 1: Load Institutional Knowledge¶

Step 2: Run Finalization Checks¶

Step 2 (non-code): Content Finalization Checks¶

Step 2a: Repo Governance Audit (if .repo-manifest.yaml exists)¶

Step 2b: State Documentation Maintenance Gate (advisory)¶

Step 2.5: User Manual Build Gate¶

Step 3: Produce Finalization Report¶

Step 3b: Built-In Security Review Gate¶

Step 4: Go/No-Go Decision¶

Step 4.5: Documentation Sync (GO only)¶

Step 4.7: Non-code Delivery Summary¶

Step 4.8: Persist Finalize Gate in state.yaml¶

Step 4.9: Write Phase Checkpoint¶

Step 5: TL;DR Summary (Final Output)¶

Error Handling (context: fork)¶

Finalization Checks Detail¶

Dependency Security Audit¶

Final Security Scan¶

Migration Safety¶

Compliance Verification¶

Constitution Compliance (When SpecKit Active)¶

Constitution Verification¶

Spec Coverage Verification¶

Finalization Decision with SpecKit¶

Feature Flag Recommendation¶

Open Brain Capture (Optional)¶

Step 2a: Repo Governance Audit (if `.repo-manifest.yaml` exists)¶