// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
= Substantial Completion Protocol
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
v1.0, 2026-04-07
:toc:
:toclevels: 4

== Overview

The **Substantial Completion Protocol** is triggered when major work reaches a
milestone point requiring finalization, audit, and preparation for release or
publication. This protocol extends the link:../../../publication-pre-flight/PREFLIGHT.adoc[Publication Pre-Flight Standard]
with session management and state capture capabilities.

== Pre-Conditions

[cols="1,3"]
|=== 
| Condition | Verification Method

| CRG Grade B+ or higher 
| Check link:../../../component-readiness-grades/COMPONENT-READINESS-GRADES.md[Component Readiness Grades]

| RSR Compliance 
| Run `rsr-audit.sh` - must pass

| Active session exists 
| `SESSION.a2ml` present in repo root

| No critical Hypatia findings 
| `.hypatia/cache.json` shows zero critical issues

| All proofs verified 
| `echidna verify` returns clean
|=== 

== Procedure

=== Phase 1: Session Finalization

[cols="1,3,1,1"]
|=== 
| Step | Action | Success Criteria | Rollback

| 1.1 
| Capture current session state 
| `SESSION.a2ml` updated with completion timestamp 
| Restore from backup

| 1.2 
| Run pre-flight checklist 
| All link:../../../publication-pre-flight/PREFLIGHT.adoc[Pre-Flight] items pass 
| Fix failures or abort

| 1.3 
| Verify CRG evidence 
| `crg-verify.sh` confirms grade B+ requirements met 
| Document gaps

| 1.4 
| Execute RSR audit 
| `rsr-audit.sh --strict` passes 
| Fix compliance issues
|=== 

=== Phase 2: Quality Assurance

[cols="1,3,1,1"]
|=== 
| Step | Action | Success Criteria | Rollback

| 2.1 
| Static analysis sweep 
| `panic-attack assail --critical` returns clean 
| Fix critical issues

| 2.2 
| Proof verification 
| `echidna verify --all` shows 0 admitted 
| Complete missing proofs

| 2.3 
| Test suite validation 
| `just test --coverage` shows ≥90% coverage 
| Add missing tests

| 2.4 
| Benchmark validation 
| `just bench` results match paper claims ±5% 
| Update claims or fix benchmarks
|=== 

=== Phase 3: Documentation Finalization

[cols="1,3,1,1"]
|=== 
| Step | Action | Success Criteria | Rollback

| 3.1 
| Update README 
| Version, date, and status reflect current state 
| Revert to previous version

| 3.2 
| Verify inline annotations 
| `inline-annotations/extractor` finds no missing @trust/@contract 
| Add missing annotations

| 3.3 
| Generate SBOM 
| `just sbom` produces complete software bill of materials 
| Fix missing dependencies

| 3.4 
| Update CHANGELOG 
| All changes since last release documented 
| Add missing entries
|=== 

=== Phase 4: Session Closure

[cols="1,3,1,1"]
|=== 
| Step | Action | Success Criteria | Rollback

| 4.1 
| Create session archive 
| `SESSION-ARCHIVE-YYYYMMDD.tar.gz` created 
| Delete archive file

| 4.2 
| Update VeriSimDB 
| Session octad created with `status:completed` 
| Delete octad

| 4.3 
| Emit completion signal 
| `groove emit session.completed` succeeds 
| Manual signal cleanup

| 4.4 
| Generate handover report 
| `HANDOVER-REPORT.md` created with next steps 
| Delete report
|=== 

== Post-Conditions

[cols="1,3"]
|=== 
| Condition | Verification

| Session state archived 
| `SESSION-ARCHIVE-*.tar.gz` exists in `.session_archive/`

| VeriSimDB updated 
| `verisimdb query session:latest` shows completed status

| All audit trails complete 
| `just audit-trail` generates clean report

| Next session prepared 
| `NEXT-SESSION.k9` exists with planned work

| Repository in clean state 
| `git status` shows no uncommitted changes
|=== 

== Recovery Procedures

=== If Pre-Flight Fails

1. **Isolate issue**: `preflight-diagnose.sh` identifies failing component
2. **Document gap**: Add entry to `PREFLIGHT-GAPS.md`
3. **Rollback session**: `git checkout SESSION.a2ml`
4. **Create recovery branch**: `git checkout -b preflight-fix/YYYYMMDD`
5. **Address issue** in recovery branch
6. **Re-attempt protocol** after fix

=== If CRG Verification Fails

1. **Run detailed assessment**: `crg-assess.sh --verbose`
2. **Identify weak evidence**: Check `crg-assessment-report.json`
3. **Create evidence plan**: `EVIDENCE-PLAN.a2ml`
4. **Downgrade component**: Update `READINESS.md` to accurate grade
5. **Park or proceed**: Decide based on release urgency

=== If Emergency During Protocol

1. **Secure immediate state**: `emergency-secure.sh`
2. **Capture partial results**: `SESSION-PARTIAL.a2ml`
3. **Emit emergency signal**: `groove emit session.emergency`
4. **Create recovery point**: `git stash push -m "emergency-save"`
5. **Resume when possible**: `git stash pop`

== Integration with Existing Standards

[cols="2,3"]
|=== 
| Standard | Integration Point

| **Publication Pre-Flight** 
| This protocol incorporates and extends PREFLIGHT.adoc

| **Component Readiness Grades** 
| Requires CRG B+ as pre-condition, updates grades post-completion

| **Rhodium Standard Repositories** 
| Enforces RSR compliance as gate criterion

| **K9 Coordination** 
| Uses coordination.k9 for session signaling and state management

| **VeriSimDB** 
| Stores session completion octads for audit trail

| **Hypatia** 
| Validates session compliance and emits governance signals

| **PanLL** 
| Displays session completion status in dashboards
|=== 

== Machine Protocol

See link:PROTOCOL.k9[PROTOCOL.k9] for the K9 coordination format that
implements this checklist in machine-readable form.

== Session State Template

See link:STATE-template.a2ml[STATE-template.a2ml] for the A2ML format used
to capture session completion state.

== Verification Script

The `verify.sh` script automates as much of this protocol as possible:

[source,bash]
----
#!/usr/bin/env bash
# Automated Substantial Completion Verification

set -euo pipefail

# Phase 1: Session Finalization
./capture-session.sh
../../../publication-pre-flight/preflight-verify.sh
crg-verify.sh --require B+
rsr-audit.sh --strict

# Phase 2: Quality Assurance  
panic-attack assail --critical
just test --coverage --require 90
just bench --validate

# Phase 3: Documentation
just readme-validate
inline-annotations/extractor --verify
just sbom --generate
changelog-verify.sh

# Phase 4: Session Closure
create-session-archive.sh
db-update-session.sh --status completed
groove emit session.completed
generate-handover-report.sh

# Final verification
preflight-final-check.sh
echo "✅ Substantial Completion Protocol: PASSED"
----

== Compliance Checklist

[ ] Session state captured in A2ML format
[ ] Pre-flight checklist completed successfully
[ ] CRG grade B+ verified and documented
[ ] RSR compliance audit passed
[ ] All critical static analysis issues resolved
[ ] All proofs verified (0 admitted/sorry)
[ ] Test coverage ≥90% achieved
[ ] Benchmark results validated (±5% of claims)
[ ] README updated with current version/status
[ ] Inline annotations complete (@trust/@contract)
[ ] SBOM generated and complete
[ ] CHANGELOG updated with all changes
[ ] Session archive created and stored
[ ] VeriSimDB updated with session completion
[ ] Completion signal emitted to Groove
[ ] Handover report generated
[ ] Repository in clean git state
[ ] Next session plan created

== See Also

- link:../../../publication-pre-flight/PREFLIGHT.adoc[Publication Pre-Flight Standard]
- link:../../../component-readiness-grades/README.adoc[Component Readiness Grades]
- link:../../../rhodium-standard-repositories/COMPLIANCE_CHECKLIST.md[RSR Compliance Checklist]
- link:../../../k9-coordination-protocol/README.adoc[K9 Coordination Protocol]
