docs(plan): harden commandF V3.1 for evidence-bound decisions

Merged
TH
22d ago
+3870-0

Summary

Harden the commandF V3 planning candidate into a V3.1 implementation-ready planning package for evidence-bound interoperability decisions while preserving V2 as current execution authority.

Current review identity:

base: 18819c7fdaee618f4aa86c6c3279b1acb70ec9f2
head: 34b3a9c2b64bafd860a1a40df1c5a2c530c807db
branch: docs/commandf-v3-plan-research

Governance boundary

This PR is documentation/planning/provenance only. It does not:

  • supersede COMMAND_F_MASTER_ARCHITECTURE_V2.md;
  • authorize CF-17..CF-28 implementation by itself;
  • mutate an active CF/AF Spec Kit;
  • change product code, workflows, rulesets, Cargo manifests/lockfile, runtime dependencies, or current AF authority;
  • claim G01..G50 are implemented or closed;
  • make a model, donor repository, reviewer, or external score semantic authority.

Every future implementation unit still requires its own canonical Spec Kit, source/provenance qualification, deterministic validation, exact-head evidence, required independent review, guarded normal merge, and post-merge reconciliation.

V3 base package retained

The PR retains the existing V3 candidate documents:

  • docs/COMMAND_F_MASTER_ARCHITECTURE_V3_CANDIDATE.md
  • docs/COMMAND_F_PLAN_GAP_REVIEW_2026-09-12.md
  • docs/COMMAND_F_OPEN_SOURCE_QUALIFICATION_2026-09-12.md
  • docs/COMMAND_F_V3_EXECUTION_PLAYBOOK.md
  • docs/COMMAND_F_DISCOVERY_COVERAGE_2026-08-13.md

These preserve G01..G40, CF-17..CF-28 candidate build cards, 35/35 legacy interoperability-gap reconciliation, protocol coverage, source qualification, evidence truth classes, reproducibility, privacy, configuration/error semantics, and the post-CF-16 dependency graph.

V3.1 additions

docs/COMMAND_F_V3_1_DECISION_ASSURANCE_PLAN.md

Adds the missing formal decision layer:

  • proof is separate from probability/confidence;
  • deterministic truth class is separate from policy action;
  • completeness and evidence sufficiency are first-class;
  • INSUFFICIENT_EVIDENCE, UNSUPPORTED, INDETERMINATE, and abstention are valid outcomes;
  • Decision Envelope v1;
  • portable Consumer Contract v1;
  • selective oracle/runtime escalation;
  • source/evidence-bound Decision Receipt v1;
  • optional GAX-derived advisory scoring that is technically non-authoritative;
  • counterfactual sensitivity + irrelevant-edit stability;
  • CommandFBench-Decision centered on unsafe auto-allow risk at declared coverage;
  • G41..G50 with exact future owners and closure contracts.

docs/COMMAND_F_V3_1_IMPLEMENTATION_RUNBOOK.md

Turns V3.1 into a slice-level handoff:

  • Wave -1 verified-byte/bounded-input migration blockers;
  • CF-18 Decision Contract Foundation tasks;
  • CF-19 Consumer Contract tasks;
  • CF-20 selective evidence escalation;
  • CF-21 Decision Receipt/offline replay;
  • CF-22 evidence-derived TestGen/counterexamples;
  • CF-23 stable external surfaces;
  • CF-24 optional model/plugin capability boundary;
  • CF-25/26 common evidence integration;
  • CF-27 public evidence behavior;
  • CF-28 decision benchmark/model qualification;
  • shared assurance primitive backlog;
  • per-slice no-gap readiness checklist;
  • reconciled five-source donor application map.

docs/COMMAND_F_V3_1_COMPLETENESS_AUDIT_2026-09-29.md

Challenges the combined plan across authority, decision semantics, consumer identity, oracle failure, partial results, provenance, privacy, resource/integrity boundaries, replay, model authority, benchmark gaming, counterfactual behavior, protocol coverage, assurance duplication, and implementation handoff.

docs/COMMAND_F_V3_1_MECHANICAL_AUDIT_2026-09-29.md

Retains a structural audit of the current planning package. The bounded planning verdict is:

G01..G50 ownership: COMPLETE_FOR_REVIEWED_PLAN
G01..G50 closure contracts: COMPLETE_FOR_REVIEWED_PLAN
CF-17..CF-28 build-card continuity: COMPLETE_FOR_REVIEWED_PLAN
legacy 35-gap preservation: COMPLETE_FOR_REVIEWED_PLAN
donor map/provenance planning: COMPLETE_FOR_REVIEWED_PLAN
known unowned material planning concerns: NONE IDENTIFIED

NO_KNOWN_UNOWNED_PLANNING_GAPS
READY_FOR_SPEC_KIT_SHAPING
NOT_CURRENT_EXECUTION_AUTHORITY
NOT_IMPLEMENTED

The audit explicitly rejects the impossible claim that a static plan can prove no future unknown will ever be discovered. Any new material concern not genuinely covered by an existing owner/closure contract must receive a new gap identity before affected implementation continues.

docs/COMMAND_F_V3_1_REVIEW_GOVERNANCE.md

Records the planned future V3 review stack:

  • repository deterministic/assurance gates;
  • Jev as required independent review input where applicable;
  • Alibaba Open Code Review as required external code-review workflow;
  • human disposition/protected merge authority;
  • CodeRabbit/Qodo/Cubic are not qualification evidence for future V3/V3.1 work.

Any conflicting current canonical reviewer topology must be reconciled by the future V3 migration gate rather than silently bypassed.

donors/commandf-v3_1-internal-pattern-sources-2026-09-29.yaml

Pins founder-controlled pattern sources:

  • GAX a1432dc81d48407c551b1b8ddefefa478a2cd33f — sufficiency/abstention/calibration/counterfactual patterns;
  • Ascout 06b763d8ffb09538b812fc0b007424b482531256 — receipt/status/completeness/source-binding patterns;
  • Sentrdel f5747319a50831ef7cee983d253c0ca5503c9a64 — evidence authority/reconciliation, explicit coverage gaps, contradiction, and lower-authority reasoning patterns;
  • Kernux 7e07035d8a29b234273fa84a496539cc685ad03e — provider-neutral capability/evidence-before-done patterns;
  • Cotra 0b56d8b95f69f5797fb8edf7871ec84b9013321c — bounded capability and explicit execution-state patterns.

All are PATTERN_ONLY at this planning stage. Code copying/porting still requires a slice-specific source-path/blob/license/rights/destination gate.

A broader founder-repository sweep also reviewed directly relevant ProtocolWISE, commandMed, and MESC/MedScale planning patterns. Their useful verification/abstention/reproducibility ideas are already represented by the selected source set and existing V3 architecture, so they were not added merely to increase donor count.

docs/COMMAND_F_PLAN_INDEX.md

Indexes V3.1 as the mandatory decision-assurance amendment to the V3 execution playbook without changing V2 authority or CF numbering. Existing literal V3 index contracts required by repository tests remain preserved.

Gap accounting

V3 gaps:    G01..G40 = 40 retained
V3.1 gaps:  G41..G50 = 10 added
Total:      50 explicit planning gaps

A gap is not closed by being planned. A newly discovered material concern with no genuine existing owner must receive a new gap identity before implementation proceeds; it may not disappear into prose.

Known migration blockers explicitly retained

Live issues #35, #36, #37, #38, and #40 represent verified-byte and bounded-input invariants that must be re-read and closed/audited before a future V3 production-trust claim. This PR does not silently repair or close them.

Newly surfaced dependency assurance blocker

Exact-head assurance on prior planning head 47d9fe9d2ef738833fc75ce3f5ac4a3b1b47566d surfaced RUSTSEC-2026-0285 against transitive rustls 0.23.43 (patched >=0.23.45). This is a real repository dependency failure, not a planning-document defect.

It is tracked separately as issue #99: fix(deps): remediate RUSTSEC-2026-0285 in transitive rustls.

PR #91 remains documentation-only; the advisory will not be hidden with a waiver or smuggled into this planning diff.

Exact-head CI state

No stale earlier-head validation is reused as merge qualification after the latest V3.1 edits.

Current exact head:

34b3a9c2b64bafd860a1a40df1c5a2c530c807db

Current pull-request workflow runs are in progress on this exact head:

  • ci run 36610660869;
  • af01-security run 36610660945;
  • af01-scorecard run 36610660888;
  • af01-assurance-proof run 36610660844;
  • cf06-oracle run 36610661032.

No success claim is made before they conclude. The prior-head RUSTSEC-2026-0285 failure remains a separately owned blocker (#99) even if another check state changes.

Any automatic CodeRabbit status is not treated as V3.1 qualification evidence. The planned Jev + Alibaba Open Code Review requirements apply to future V3/V3.1 governance after canonical migration reconciliation; current live governance remains authoritative until then.

Intent

After canonicalization and a later qualified migration gate, a future implementation agent should be able to identify the next dependency-eligible Spec Kit, know exactly which schemas/semantics must freeze first, know which failure/unsupported/abstention states are required, know which evidence closes the slice, and proceed without inventing hidden authority or silently dropping a gap.