Engineering assessment contract (DEC-010)

This page freezes the first-batch reuse mapping, compatibility surface, and AssessmentEnvelope contract for model-free engineering assessment. It does not authorize a second work/session authority, a general scheduler, a model client, or a new Decision object. Management intensity, claim admission, source write, and completion remain the existing protocols.

Verified against tip main at execution:

The design pack's older SHA is inventory history only. Every reuse claim below was re-checked against the verified main SHA above.

Machine-checkable companions live under tests/fixtures/assessment/contracts/.

1. Tip inventory and deltas

1.1 Already on tip main (reuse; do not reimplement)

1.2 Explicit deltas introduced by DEC-010

Historical EVO-010 / EVO-012 / EVO-034 semantics that landed as the management, prepare embedding, and status-action surfaces above are reused. DEC-010 does not open a second rule engine for those conclusions.

2. First-batch scope

First batch (through the DEC-2 explain loop) only:

1. Management assessment explanation — typed wrap of the existing ManagementDecision / assess receipt.
2. Action-rationale explanation — typed wrap of existing ActionGuidance produced for prepare response_view=action (and the matching status action card shape).

Out of first batch for the DEC-010 envelope itself (later DEC cards; keep layers as not_evaluated or field state=unsupported until implemented):

• Bounded fact-snapshot + source-quality labeling (DEC-011) — types and pure construction land in awr_core::fact_snapshot / awr_runtime::fact_snapshot; fixtures under tests/fixtures/assessment/signals/. WorkspaceFacts only via host supply or explicit collection; prepare does not run Git/AST/network.
• Typed AssessmentEnvelope compose + unknown/conflict semantics (DEC-012) — awr_core::assessment_envelope (compose_assessment_envelope / evaluate_assessment); fixtures under tests/fixtures/assessment/envelope/.
• Counterexample corpus (DEC-013)
• Composition pipeline (DEC-020) — awr_runtime::explanation_chain (compose_explanation_chain); binds five-layer explanations + advisories on existing prepare/assess judgments without a second adjudicator. CLI/MCP field injection is DEC-021 (assessment.explain on existing prepare/assess).
• Context packing / retention explain (DEC-030+)
• AUTO / model routing (never core)

3. Five semantic layers

Layers are independent. A layer that was not run returns not_evaluated. Missing evidence is unknown / missing, never false.

4. Facts, observations, and inference

Every signal in an envelope carries:

Tip mapping examples:

• ManagementObservation.* host fields → observation, basis=host_asserted, assess receipt observation_basis=host_assertion_not_independently_verified
• Runtime events (mcp.wait_created, work.handoff, session.resumed, non-terminal executions) → fact/observation with basis=runtime_recorded / reason basis runtime_history or runtime_recorded_state
• Source dependency / contract fingerprint mismatches → basis=source_projection / source_declared as appropriate
• required_actions / advisory suggestions → inference / advisory only; still require the next real admission check
• Omitted optional counters (active_elapsed_ms, completed_rework_cycles) → missing / listed in unknown_observations; never treated as zero risk

5. AssessmentEnvelope schema (frozen)

Schema id: awr-assessment-envelope-v1. Version: 1. First-batch assessment_profile: management_and_action_rationale.

{
  "schema_id": "awr-assessment-envelope-v1",
  "schema_version": 1,
  "assessment_profile": "management_and_action_rationale",
  "identity": {
    "project_id": null,
    "work_key": null,
    "work_id": null,
    "branch_id": null,
    "contract_fingerprint": null,
    "policy_id": "tip_management_v1",
    "policy_version": 1,
    "input_summary": null,
    "as_of": null,
    "verified_main_sha": "8fa6679981c823842282a0a4b5b79b9c7165b2a4"
  },
  "layers": {
    "work_readiness": {"status": "not_evaluated", "summary": null, "basis_refs": []},
    "execution_admission": {"status": "not_evaluated", "summary": null, "basis_refs": []},
    "context_completeness": {"status": "not_evaluated", "summary": null, "basis_refs": []},
    "delivery_observation": {"status": "not_evaluated", "summary": null, "basis_refs": []},
    "completion_validity": {"status": "not_evaluated", "summary": null, "basis_refs": []}
  },
  "assessments": [],
  "evidence_quality": {
    "required_fields": [],
    "observed_fields": [],
    "missing": [],
    "stale": [],
    "conflicting": [],
    "host_asserted_only": [],
    "unsupported": [],
    "coverage_note": "coverage is a field count ratio, not probability"
  },
  "advisory_actions": [],
  "limits": {
    "candidates": null,
    "scan_ops": null,
    "return_bytes": null,
    "time_budget_ms": null,
    "read_scope": "assessment_read_only",
    "omitted_count": 0
  },
  "management": null,
  "action_rationale": null,
  "legacy": {
    "compatible": true,
    "source_views": [],
    "omitted_fields": []
  },
  "unsupported_fields": {}
}

Rules:

• null and unknown mean unset / not independently established. Do not substitute 0, false, or empty-success.
• assessments[].support ∈ supported | unknown | conflicting | unsupported.
• advisory_actions[].code must come from the frozen advisory set below (machine enums, not free-form scripts).
• unsupported_fields maps dotted paths → "unknown" for any profile field the implementation does not yet populate.
• Evaluation is read-only: no model, network, thread farm, or claim/completion side effects from producing an envelope.

5.1 Management object (reuse mapping)

Maps 1:1 from tip assess_management / ManagementDecision:

5.2 Action-rationale object

Maps from tip ActionGuidance / prepare action view / status action guidance:

6. Frozen reason codes and bases

6.1 Management reason code values (tip)

Host-assertion triggers from decide_management:

• multiple_outcomes
• scope_requires_planning
• handoff_or_collaboration
• deferred_wait
• plan_invalidated
• query_outcome_before_retry
• independent_work_units

Runtime / projection reasons from assess_management:

• unresolved_dependencies (basis=source_projection)
• work_contract_changed (basis=source_projection)
• persistent_wait (basis=runtime_history)
• work_handoff (basis=runtime_history)
• cross_session_resume (basis=runtime_history)
• execution_result_requires_query (basis=runtime_recorded_state)
• continuous_management_retained (basis=runtime_history)

Reason basis values observed on tip: host_assertion, runtime_history, source_projection, runtime_recorded_state.

6.2 Unknown observation field names

When absent on the host observation: single_outcome, bounded_scope, single_executor, no_deferred_wait, plan_valid, outcome_known, independently_schedulable_units.

6.3 Reevaluation signals

• active_elapsed_at_least_30_minutes (when active_elapsed_ms >= 30*60*1000)
• at_least_3_completed_rework_cycles (when completed_rework_cycles >= 3)

These request reassessment only; they do not auto-promote lightweight work.

6.4 Required / optional action strings

Always required (all modes):

• preserve_identity_intent_scope_and_current_state
• consume_required_context_and_hard_rules
• retain_completion_basis_and_actual_outcome
• check_source_versions_permissions_claims_and_request_identity

Additional when continuous:

• maintain_dependencies_and_ownership
• checkpoint_at_wait_handoff_interruption_and_phase_change
• maintain_next_action_wait_conditions_and_open_loops
• query_unknown_results_before_any_retry

Conditional:

• assess_unknown_management_facts (undetermined + unknowns)
• reevaluate_scope_plan_and_recovery_without_automatic_upgrade (reevaluation signals)

6.5 First-batch advisory action codes

Closed set for envelope advisory_actions (aligns to tip required actions / guidance; not executable scripts):

• continue_prepare_current_work
• query_original_operation_result
• collect_user_reply
• refresh_sources
• repair_required_materials
• inspect_claim_conflict
• request_human_review
• record_management_observations
• no_advisory

7. Read boundaries

Assessment reads may use:

• Already-authorized project store projections and event receipts
• The same read snapshot prepare/assess already opened
• Explicit caller-supplied host observations (labeled host-asserted)
• Fixture / frozen policy inputs for offline replay

Assessment reads must not:

• Open a model provider or any network scoring path
• Probe live OS processes to invent execution outcomes
• Run implicit git / AST / whole-repo scans beyond what prepare already did
• Mutate claims, sessions, sources, completion, or management records (recording observations remains the separate work manage mutation)
• Bypass source freshness / revision guards that the caller already faces
• Treat decision show content or markdown decision documents as this envelope

TOCTOU: an envelope is an explanation of a past snapshot. The next mutating operation must re-check permissions, claims, and source versions.

8. Legacy output compatibility

Capability id assessment.explain is wired in DEC-021 as an optional --explain / explain boolean on existing prepare/assess commands (orthogonal to response_view full/summary/action). Do not invent work assess-explain or similar for first batch.

9. Two read consumers

Both consumers remain read-only for assessment. Closing MCP does not end sessions. Unknown mutation outcomes still require querying the original request identity.

10. Unsupported fields → unknown

Any envelope field listed in the profile but not produced by the current implementation is emitted under unsupported_fields with value "unknown", or as a layer/assessment with status / support = not_evaluated / unsupported. Forbidden coercions:

• missing git diff ↛ changed_lines=0
• missing observation ↛ false risk absence
• unknown execution ↛ “safe to retry”
• rule score ↛ calibrated probability
• inference ↛ verified fact

11. Invariants

• no_model_or_network_required
• source_first_single_work_authority
• reuse_existing_admission_and_completion
• unknown_is_not_false_or_zero
• evidence_coverage_is_not_probability
• no_second_decision_authority
• decision_show_not_occupied

12. DEC-011 fact snapshot (bound inputs)

Schema id: awr-fact-snapshot-v1. Pure build_fact_snapshot accepts fixed identity (project/work/branch, contract + source versions), as_of, scope, truncation/limits, and labeled FactSignal values. Same-snapshot entity version conflicts are rejected. Signal state / basis / classification distinguish missing, stale, conflicting, unsupported, host-asserted observations, and verified facts. Without a bound git diff, changed_lines and low-risk labels stay unset (never 0 / low). Runtime mapping reuses one prepared/assess read view (scan_ops=1) and does not recurse the repository.

Machine fixtures: tests/fixtures/assessment/signals/.

13. DEC-012 typed envelope compose (unknown / conflict)

Schema id remains awr-assessment-envelope-v1. Pure compose_assessment_envelope / evaluate_assessment accept fixed identity, versioned AssessmentPolicy, as_of, optional FactSnapshot, optional ManagementDecision / ActionGuidance, and labeled sub-assessments.

Machine fixtures: tests/fixtures/assessment/envelope/.

14. DEC-013 counterexample corpus and compare budgets

Pre-registers the offline counterexample corpus, baseline/candidate compare contract, performance budget slots, and statistics 口径 before the first candidate explain run. Reuses EVO-001 pre-registration method but counts separately; does not require EVO paid/dual-host experiments.

Metric families stay separate: structural correctness, runtime overhead, and advisory effectiveness. Model success rate, dollar savings, and semantic understanding are not derived from unmeasured data. Critical hard-constraint families (error retry, revoke, wrong task, evidence withdrawal, missing fields, delivery unknown, time budget) fail closed and are not offset by averages.

Envelope stack marker: tests/fixtures/assessment/envelope/manifest.json sets dec_013_started: true.

15. DEC-020 explanation chain (prepare / management binding)

Consumes the DEC-010..013 public bases (FactSnapshot, AssessmentEnvelope, counterexample corpus) and attaches a five-layer explanation chain on top of existing prepare/assess conclusions. EVO-012 still owns behavior fixes.

Machine tests: crates/awr-runtime/tests/explanation_chain.rs (acceptance + C01/C03/C07/C08/C15/P01 reuse).

Corpus marker: tests/fixtures/assessment/counterexamples/manifest.json sets dec_020_started: true.

16. DEC-021 optional CLI/MCP explanation delivery

Wires capability assessment.explain onto existing work prepare / work assess and MCP awr_work_prepare / awr_work_assess paths. Reuses DEC-020 explanation_chain / AssessmentEnvelope — no second adjudicator, no new top-level tool, and decision show remains unoccupied.

Machine tests: crates/awr-cli/tests/assessment_explain_cli.rs, crates/awr-mcp/tests/assessment_explain_mcp.rs, awr_runtime::assessment_explain unit tests.

Corpus marker: tests/fixtures/assessment/counterexamples/manifest.json sets dec_021_started: true.

17. DEC-022 offline replay, shadow compare, and one-click disable

Ships developer offline replay + shadow compare entry points and an advice delivery kill-switch on top of DEC-010..021 (FactSnapshot, AssessmentEnvelope, explanation_chain, optional explain). Reuses event/artifact-shaped snapshot JSON for bounded facts + rule hashes — no separate state DB. Assessment stays read-only: no model/network, missing fields stay missing, unknown ≠ false.

Capabilities: assessment.replay, assessment.shadow_compare, assessment.advice_mode.

Machine tests: crates/awr-runtime/tests/assessment_offline.rs, crates/awr-cli/tests/assessment_offline_cli.rs, crates/awr-runtime unit tests under assessment_replay / assessment_shadow.

Fixtures: tests/fixtures/assessment/replay/.

Corpus marker: tests/fixtures/assessment/counterexamples/manifest.json sets dec_022_started: true.

18. DEC-060 first-batch independent acceptance gate

Independently accepts the first model-free explanation closed loop. Cross-checks DEC-010..022 acceptance evidence item-by-item and counts eight first-batch items separately (010/011/012/013/020/021/022 + this gate). Reuses existing fixtures, offline replay, CLI/MCP explain, and kill-switch — no second assessment stack.

Corpus marker: tests/fixtures/assessment/counterexamples/manifest.json sets dec_060_started: true. evo_000_started / dec_040_started remain false.

19. Related pages

• Management intensity — classification rules hosts still follow
• Workflow prepare — prepare / completion preflight
• Daily work — status action queues
• Fixtures: tests/fixtures/assessment/contracts/, signals/, envelope/, mvp-acceptance/
• Benchmarks: docs/benchmarks/assessment.md