fusion/docs/missions-completion-contract.md

Mission Completion Gate Contract

Status

• Decision date: 2026-05-30
• Task: FN-5718
• Depends on enforcement behavior from: FN-5715 (reference implementation of the trigger/recovery path)
• Scope: Product contract and implementation requirements only (no code changes in this task)
• Implementation status: Realized by FN-5733 (loop auto-pass advancement, mission/store guard telemetry, MissionManager label reconciliation)

Problem

Mission validation has had a recurring ambiguity: users can see feature acceptance text and milestone "completion criteria" text, but autopilot enforcement is actually driven by assertion linkage + validator outcomes. This document defines the canonical enforced gate so mission completion cannot silently stall or be misread.

Canonical Completion Gate (Enforced)

Decision

A feature is autopilot-complete only when its linked contract assertions are satisfied.

Canonical authored source and enforcement path:

1. MissionFeature.acceptanceCriteria is the canonical authored criteria text (authoring surface).
2. MissionStore must maintain a store-managed per-feature MissionContractAssertion derived from feature content, with text priority:
   • feature.acceptanceCriteria
   • feature.description
   • Verify implementation of: {feature.title}
3. The mission validator enforces completion using the feature's linked assertions (including its store-managed assertion and any additional linked milestone assertions).
4. Feature/slice/mission advance is gated by the validator outcome (or explicit no-assertions auto-pass behavior defined below).

Precedence and interpretation rules

• MissionFeature.acceptanceCriteria is the canonical authoring field for feature-level intent.
• The linked assertion set is the canonical enforcement set.
• Milestone MissionContractAssertion rows are additive contract rows. They are enforced only when linked to a feature.
• milestone.acceptanceCriteria is descriptive/informational milestone text and is not directly executed by the validator.

Worked examples

1. Feature has acceptance criteria; store-managed assertion linked; validator passes
   • Result: feature may move to done/passed and contribute to slice completion.
2. Feature has acceptance criteria; additive milestone assertion also linked; one linked assertion fails
   • Result: feature is not complete; no slice advance.
3. Feature has acceptance criteria visible, but no linked assertions (legacy FN-5696 shape)
   • Result: data inconsistency; must not be interpreted by operators as a separate enforced gate. Repair links (FN-5696 backfill) so enforcement matches displayed intent.

Enforced vs. Informational Surfaces

Surface	Category	Contract meaning
MissionFeature.acceptanceCriteria	Informational authoring source	Canonical authored feature criteria text; enforcement happens through derived/linked assertions
Store-managed per-feature MissionContractAssertion	Enforced	Primary validator gate for the feature
Additive milestone MissionContractAssertion (linked to feature)	Enforced	Additional validator gate for that linked feature
Additive milestone MissionContractAssertion (unlinked)	Informational until linked	Contract candidate, not yet a feature gate
milestone.acceptanceCriteria	Informational	Milestone summary/pass-bar text for humans; not directly validator-executed
MissionManager milestone-feature-acceptance-rollup UI (data-testid="milestone-feature-acceptance-rollup")	Informational display	Display-only rendering of feature acceptance text, not a separate enforcement mechanism

Zero-Assertion Behavior and FN-5696 Failure Shape

Zero-assertions runtime behavior (canonical FN-5738 path)

When a feature reaches completion trigger points and has zero linked assertions, mission execution must take exactly one canonical auto-pass path (not a silent stall and not a competing behavior):

• mark feature terminal as status="done", loopState="passed", lastValidatorStatus="passed",
• emit explicit observability/audit evidence with mission event code validation_auto_passed_no_assertions,
• continue normal slice/mission advancement checks idempotently (no duplicate re-fire on repeated recovery).

FN-5696 legacy shape clarification

A feature can show acceptance text while links are missing (legacy pre-repair data). This must be treated as a linkage/data integrity problem, not as proof that milestone text alone is enforced. Assertion authoring/backfill (FN-5696) is outside the execution loop; the loop must not synthesize mission_feature_assertions rows. The contract prevents ambiguity by separating:

• authored/informational text surfaces, from
• linked assertion enforcement surfaces.

Operators should use the mission assertion backfill operator path to restore expected store-managed linkage for FN-5696 legacy rows:

• Agent/tool: fn_mission_backfill_assertions with { missionId?, dryRun? } (defaults to dry-run).
• API: POST /api/missions/:missionId/backfill-assertions with body { dryRun?: boolean } (defaults to true).
• Run dry-run first, then apply (dryRun=false) once repaired rows look correct.
• This remediation is additive: it derives/links one store-managed assertion per unlinked feature so runtime enforcement uses validator-linked assertions rather than the zero-assertion auto-pass branch.

Slice Status and Mission Autopilot Advance Derivation

Autopilot may advance only when each active-slice feature is resolved under this contract:

• Feature with linked assertions: all linked assertions must pass.
• Feature with zero linked assertions: explicit auto-pass path completes it.
• Feature with failed/blocked validation: slice remains incomplete.
• Feature stranded without a task link in an active autopilot slice (taskId == null): startup + maintenance reconciliation must repair it (title-match link first, otherwise defined-status re-triage) so allDone remains reachable instead of stalling on never-triaged features.

Then:

1. All features resolved complete → slice flips to complete.
2. Completed active slice with pending next slice → next slice activates.
3. All milestone slices complete → milestone complete.
4. All mission milestones complete → mission complete.

This keeps completion logic deterministic and consistent with FN-5715 trigger/recovery behavior.

UI Reconciliation Requirements (for follow-on engineering task)

✅ Implemented in FN-5733 with MissionManager labels:

• Contract assertions (autopilot gate) + enforced indicator
• Feature acceptance criteria (informational) + not-enforced indicator
• warning badge when hasProseButNoAssertions === true

Target surface: packages/dashboard/app/components/MissionManager.tsx

1. Disambiguate labels

   • Use distinct wording for:
     • feature-authored acceptance text, and
     • milestone contract assertions.
   • Do not reuse "Completion criteria" to refer to both categories.
   • Required wording baseline (or semantically equivalent copy):
     • Feature rollup heading: Feature acceptance criteria (informational source)
     • Assertion list heading: Contract assertions (validator-enforced when linked)

2. Per-row enforcement indicator

   • Every displayed row in the assertions/criteria area must show whether it is:
     • Enforced gate (validator-blocking when linked), or
     • Informational (display-only).

3. Empty-state contract-correct copy

   • Replace the current implication that completion criteria are absent when assertion rows are empty.
   • Empty-state text must acknowledge when feature acceptance text exists but no assertion rows are defined/linked.
   • Required behavior:
     • If feature acceptance text exists but no assertion rows are present, show copy equivalent to: No contract assertions are linked yet. Feature acceptance criteria are present below and remain informational until assertions are linked.
     • If neither feature acceptance text nor assertions exist, show copy equivalent to: No feature acceptance criteria or contract assertions defined yet.

4. No button/mobile scope expansion

   • No button touch-target/mobile-reflow requirements (standing directive).

Engineering Acceptance Criteria (follow-on implementation)

✅ Implemented in FN-5733:

• Auto-pass path now advances loopState to passed and emits mission event code validation_auto_passed_no_assertions while preserving the validation:passed emit contract ("No assertions linked" summary).
• Milestone rollup/store guard now exposes hasProseButNoAssertions and emits warning mission event code milestone_missing_structured_assertions (debounced on transition into condition).
• MissionManager UI now distinguishes enforced assertion gate vs informational feature acceptance criteria.

1. Data/model contract

   • Preserve the canonical relationship: feature-authored criteria -> store-managed assertion -> linked assertion enforcement.
   • If any model/UI metadata is added for enforced-vs-informational badges, it must be backward compatible with existing mission rows.

2. Validator/loop behavior

   • Maintain FN-5715 invariants:
     • done mission-linked tasks with linked assertions trigger validation,
     • completion-trigger starts loop if needed,
     • startup recovery replays done-implementing features with unpassed assertions,
     • periodic self-heal maintenance replays the same recoverActiveMissions path so historically stranded implementing features recover without restart,
     • zero-linked-assertions path remains explicit canonical auto-pass.

3. UI behavior

   • Implement the Step-2 label reconciliation and per-row indicator requirements.
   • Ensure no shared ambiguous terminology remains between feature acceptance text and assertion rows.

4. Regression coverage

   • Add at least one regression test pinning the Goals-mission shape:
     • feature has acceptanceCriteria,
     • parent milestone has zero MissionContractAssertion rows / no links,
     • autopilot behavior is deterministic and observable (explicit auto-pass path, no silent stall).

5. Operational observability

   • Ensure mission/audit surfaces make no-assertions auto-pass and subsequent advance decisions queryable in logs/events.

Success Metric

For 30 days after the follow-on implementation ships:

• Primary metric: zero autopilot stalls of the FN-5715 class (done mission task + unresolved validation trigger gap) in production mission runs.
• Evidence source: mission audit/event stream (feature_completed, slice_completed, mission_completed) plus mission_validator_runs records showing:
  • explicit no-assertions auto-pass evidence (summary/reason path such as No assertions linked when no validator run is started), and
  • downstream advancement evidence without stalled active slices.

Follow-on Task Requirement

Implementation must land in a separate engineering task that references this document and FN-5715 as the enforcement baseline.