Add commercial evidence approval command materialization status

Author: ammarheidari

README.md

@@ -76,7 +76,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Commercial evidence artifact intake | Phase 38 foundation-complete: artifact intake target identity, artifact source registration, SHA-256 digest coverage, redaction review, completeness evaluation, dossier reporting, promotion handoff, execution-to-dossier bridge, status reporting, and final validation are available, binding a stable intake id, reviewer identity, UTC receipt time, run-scoped dossier root, concrete source paths, unique retained dossier paths, retained digests, trace-bearing artifact approvals, explicit intake blockers, retained Markdown summary, digest-covered handoff, end-to-end intake assembly, and intake readiness status to a governed execution run; real artifact files are still required before commercial publication |
 | Commercial evidence file verification | Phase 39 foundation-complete: retained file evidence item verification, retained file manifest coverage, file verification blocker reporting, retention ledger modeling, integrity sealing, publication attachment planning, verified promotion gating, command planning, status reporting, final validation, and documentation alignment are available, checking file existence, non-empty size, SHA-256 validity, digest match, UTC observation time, unique retained paths, promotion-required handoff coverage, explicit verification blockers, reviewer identity, immutable retention, UTC retention windows, minimum duration, deterministic aggregate ledger digests, sealed ledger attachment coverage, trace-bearing redaction approval, commercial readiness report presence, explicit promotion approval, workflow-ready verification command order, and readiness status separation; real retained file evidence remains required before commercial publication |
 | Commercial evidence filesystem execution | Phase 40 foundation-complete: filesystem observation, manifest execution, verification report execution, artifact writing, ledger execution, seal execution, publication attachment execution, promotion execution, command materialization, status reporting, documentation, and final validation are complete, reading retained files from disk, computing real SHA-256 digests, reporting file existence and size, supporting retained-path-to-local-path overrides, building retained file manifests from real observations, exposing blocker-aware retained file reports from filesystem evidence, writing retained Markdown/TSV verification artifacts, creating retention ledgers from filesystem-backed reports, sealing those ledgers with deterministic aggregate SHA-256 digests, creating release dossier attachments with redaction approval gates, evaluating reviewer-approved promotion gates, and writing ordered execution scripts; commercial publication still requires a real approved commercial run |
-| Approved commercial run publication handoff | Phase 41 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, and approval audit trail are available, binding package version, source commit, operator identity, UTC run timing, retained artifact root, filesystem-backed promotion execution, verified report, ready ledger/seal/attachments, redaction approval, promotion approval, release/security/operations reviewer approvals, UTC approval timestamps, checklist digest coverage, retained Markdown report output, report SHA-256 digest coverage, approved package references, requested publication channel, requester identity, UTC handoff time, explicit publish intent, channel version policy, handoff blocker reporting, and digest-covered audit lifecycle events; command materialization, status reporting, and final validation remain |
+| Approved commercial run publication handoff | Phase 41 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, approval audit trail, command materialization, and interim status reporting are available, binding package version, source commit, operator identity, UTC run timing, retained artifact root, filesystem-backed promotion execution, verified report, ready ledger/seal/attachments, redaction approval, promotion approval, release/security/operations reviewer approvals, UTC approval timestamps, checklist digest coverage, retained Markdown report output, report SHA-256 digest coverage, approved package references, requested publication channel, requester identity, UTC handoff time, explicit publish intent, channel version policy, handoff blocker reporting, digest-covered audit lifecycle events, and ordered approval workflow scripts; documentation and final validation remain |
 
 ## Requirements
 

docs/PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md

@@ -107,6 +107,21 @@ This unit gives release operators actionable blockers before package publication
 
 This unit gives the approval path a retained audit chain that can be reviewed before package publication proceeds.
 
+## Unit 9 - Command Materialization And Interim Status
+
+`SigtranCommercialEvidenceApprovalCommands` materializes the approval handoff workflow:
+
+- Run target creation.
+- Approval checklist generation.
+- Reviewer approval recording.
+- Approval report writing.
+- Promotion package creation.
+- Publication handoff creation.
+- Handoff gate evaluation.
+- Approval audit trail writing.
+
+`SigtranCommercialEvidenceApprovalHandoffStatus` reports the first nine completed capabilities and keeps `status-final-validation-pending` as a blocker until the final unit completes.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE41_SUMMARY.md

@@ -12,7 +12,9 @@ Phase 41 prepares the SDK to move from filesystem-backed evidence verification i
 - Publication handoff that connects an approved promotion package to channel policy, requester identity, UTC handoff time, and explicit publish intent.
 - Publication handoff gate that reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval.
 - Approval audit trail that records digest-covered run target, checklist, manifest, report, package, handoff, and gate lifecycle events.
+- Approval command materialization that writes the ordered approval handoff workflow to a retained shell script.
+- Interim status reporting for nine completed approval handoff units, with final validation still pending.
 
 ## Readiness Position
 
-The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, and approval audit trail are available. Command materialization, status reporting, documentation, and final validation remain.
+The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, approval audit trail, command materialization, and interim status reporting are available. Documentation and final validation remain.

docs/PHASE_INDEX.md

@@ -45,7 +45,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 38 | Commercial evidence artifact intake | [Phase 38 Commercial Evidence Artifact Intake](PHASE38_COMMERCIAL_EVIDENCE_ARTIFACT_INTAKE.md), [Phase 38 Summary](PHASE38_SUMMARY.md) | Foundation complete; real artifact files still required |
 | 39 | Commercial evidence file verification | [Phase 39 Commercial Evidence File Verification](PHASE39_COMMERCIAL_EVIDENCE_FILE_VERIFICATION.md), [Phase 39 Summary](PHASE39_SUMMARY.md) | Foundation complete; real retained file evidence required |
 | 40 | Commercial evidence filesystem execution | [Phase 40 Commercial Evidence Filesystem Execution](PHASE40_COMMERCIAL_EVIDENCE_FILESYSTEM_EXECUTION.md), [Phase 40 Summary](PHASE40_SUMMARY.md) | Foundation complete; commercial publication requires real approved retained run |
-| 41 | Approved commercial run publication handoff | [Phase 41 Approved Commercial Run Publication Handoff](PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md), [Phase 41 Summary](PHASE41_SUMMARY.md) | In progress; approval audit trail complete |
+| 41 | Approved commercial run publication handoff | [Phase 41 Approved Commercial Run Publication Handoff](PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md), [Phase 41 Summary](PHASE41_SUMMARY.md) | In progress; command materialization and interim status complete |
 
 ## Current Commercial Gate
 

docs/SDK_ROADMAP.md

@@ -363,7 +363,7 @@ Status: Phase 40 is foundation-complete. Filesystem observation reads retained f
 - Record approval checklist, reviewer approvals, retained reports, promotion package, publication handoff, blocker gates, and audit trail.
 - Keep approval handoff separate from commercial publication: the SDK can prepare approval records, but publication remains blocked until a real approved run is retained.
 
-Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Publication handoff gate now reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval. Approval audit trail now records digest-covered lifecycle events for run target, checklist, manifest, report, package, handoff, and gate. Command materialization, status reporting, and final validation remain in progress.
+Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Publication handoff gate now reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval. Approval audit trail now records digest-covered lifecycle events for run target, checklist, manifest, report, package, handoff, and gate. Command materialization now writes the ordered approval workflow to a retained shell script. Interim status reporting now tracks nine completed capabilities and keeps final validation pending. Documentation and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -323,6 +323,8 @@
 Run("SIGTRAN commercial evidence publication handoff enforces channel version policy", SigtranCommercialEvidencePublicationHandoffEnforcesChannelVersionPolicy);
 Run("SIGTRAN commercial evidence publication handoff gate reports blockers", SigtranCommercialEvidencePublicationHandoffGateReportsBlockers);
 Run("SIGTRAN commercial evidence approval audit trail covers lifecycle", SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle);
+Run("SIGTRAN commercial evidence approval command materializer writes script", SigtranCommercialEvidenceApprovalCommandMaterializerWritesScript);
+Run("SIGTRAN commercial evidence approval handoff status summarizes pending final validation", SigtranCommercialEvidenceApprovalHandoffStatusSummarizesPendingFinalValidation);
 Run("SIGTRAN status capabilities use domain documentation labels", SigtranStatusCapabilitiesUseDomainDocumentationLabels);
 Run("Native SCTP platform probe reports socket creation capability", NativeSctpPlatformProbeReportsSocketCreationCapability);
 Run("Native SCTP socket factory creates or reports unsupported platform", NativeSctpSocketFactoryCreatesOrReportsUnsupportedPlatform);
@@ -5741,6 +5743,49 @@ static void SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle()
     }
 }
 
+static void SigtranCommercialEvidenceApprovalCommandMaterializerWritesScript()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        SigtranCommercialEvidenceApprovalCommandPlan plan = SigtranCommercialEvidenceApprovalCommands.CreateDefaultPlan(
+            Path.Combine(tempRoot, "approval"),
+            "commercial-run-20260622-001");
+        SigtranCommercialEvidenceApprovalCommandMaterialization materialization = SigtranCommercialEvidenceApprovalCommands.WriteScript(
+            plan,
+            Path.Combine(tempRoot, "scripts", "commercial-evidence-approval.sh"),
+            DateTimeOffset.UtcNow);
+
+        Assert(materialization.IsReady, materialization.Describe());
+        Assert(materialization.ScriptExists, "approval command script should exist");
+        Assert(materialization.ScriptSizeBytes > 0, "approval command script should be non-empty");
+        Assert(materialization.IncludesRunId, "approval command script should include run id");
+        Assert(materialization.IncludesAllCommands, "approval command script should include every command");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static void SigtranCommercialEvidenceApprovalHandoffStatusSummarizesPendingFinalValidation()
+{
+    IReadOnlyList<string> capabilities = SigtranCommercialEvidenceApprovalHandoffStatus.GetCompletedCapabilities();
+    IReadOnlyList<string> blockers = SigtranCommercialEvidenceApprovalHandoffStatus.GetDefaultBlockers();
+
+    AssertEqual(9, SigtranCommercialEvidenceApprovalHandoffStatus.CompletedUnitCount, "approval handoff completed unit count");
+    AssertEqual(9, capabilities.Count, "approval handoff capability count");
+    Assert(capabilities.Contains("command-materialization"), "approval handoff status should include command materialization");
+    Assert(!capabilities.Contains("documentation"), "approval handoff status should keep documentation pending before final validation");
+    Assert(SigtranCommercialEvidenceApprovalHandoffStatus.ApprovalHandoffFoundationReady, SigtranCommercialEvidenceApprovalHandoffStatus.Describe());
+    Assert(!SigtranCommercialEvidenceApprovalHandoffStatus.RealApprovedCommercialRunReady, SigtranCommercialEvidenceApprovalHandoffStatus.Describe());
+    Assert(!SigtranCommercialEvidenceApprovalHandoffStatus.PackagePublicationReady, SigtranCommercialEvidenceApprovalHandoffStatus.Describe());
+    Assert(blockers.Contains("real-approved-commercial-run-required"), "approval handoff status should require a real approved run");
+    Assert(blockers.Contains("status-final-validation-pending"), "approval handoff status should keep final validation pending");
+}
+
 static SigtranCommercialEvidencePublicationHandoffGateResult CreateReadyCommercialEvidencePublicationHandoffGateResult(string tempRoot)
 {
     return SigtranCommercialEvidencePublicationHandoffGates.Evaluate(