feat(context-engine): D3 P2 — pure attribution planner (Context-Used trailer → consequence plan)

[ProtocolWarden]

What

context_engine/attribution.py — the D3 P2 pure, dry-run-only attribution planner: plan_attribution(root, ...) -> AttributionPlan, deciding which merged commit proves which injected cold-memory item useful. Precision over recall: every ambiguity resolves to do-not-attribute.

The §4.1 link predicate (ALL must hold, else a machine-readable rejection)

1. Explicit citation — the commit carries a Context-Used: <slug> git trailer (exact match). Attribution is never inferred from temporal proximity.
2. Path corroboration — ≥1 changed file matches ≥1 of the item's paths globs, with surface_cold's EXACT matcher semantics (route._glob_to_regex + the same leading-./ normalization). Cited-but-no-overlap ⇒ cited_no_path_overlap (probable mis-cite).
3. Existence + reachability by construction — candidate commits come ONLY from git log origin/<default> (bounded --since the earliest injection ts, --grep prefilter), so every candidate sha resolves and is an ancestor of the merged default branch.
4. Causal ordering — author-date ≥ the slug's earliest injection ts from the P0 cold_slugs ledger (feat(context-engine): D3 P0-A — surface cold-item slug + record injected slugs (attribution substrate) #44). A slug never recorded as injected can NEVER attribute (never_injected).
5. Same repo/anchor — only root's own git repo and ledger are ever consulted.

Scope guards: cold-tier candidates only (§3.3 — no promoted-item feedback loop; warm/hot citations reject not_cold_tier) and write-once (already_attributed). Multiple qualifying commits ⇒ the earliest (author-date, then sha) wins — first proof of usefulness, deterministic on append-only merged history. One commit citing many slugs evaluates each slug independently.

tests_green is resolved for the attributed sha via an injectable seam over P1 ci_status.resolve_ci_status (#45); github_repo/token are caller-supplied — either absent ⇒ verbatim "unknown" (the valid §3.5 Phase-A value). Recorded exactly as returned: True | False | "unknown", never coerced, never defaulted True; nonstandard seam values degrade to "unknown", never True.

Guarantees

• ZERO writes — pure planner; the CLI is dry-run only (no --apply exists here at all; no --token on argv). P3 wires the writer through cold.write_item under the reviewed --apply boundary.
• Never raises — any unexpected failure ⇒ empty plan (plan_consolidation's fail-soft idiom).
• No env reads — all config caller-supplied (ci_status.py's pattern); git seams are bounded subprocess calls matching pseudo_operator/committed.py.
• No caller wired — ships standalone, fully unit-tested.

Red-team test matrix (tests/test_attribution.py, 31 tests, all seams faked)

§3 attack / property	test
happy path ⇒ (slug, sha, True)	test_happy_path_plans_slug_sha_green
§3.1 temporal coincidence (no trailer ⇒ nothing)	test_same_window_commit_without_trailer_attributes_nothing
§3.1 cited before injection	test_cited_before_injection_rejected
unparseable commit date ⇒ fail-closed	test_unparseable_commit_date_rejected_fail_closed
earliest injection ts is the guard	test_earliest_injection_ts_is_the_time_guard
§3.2 confounding: cites one of two slugs	test_commit_citing_one_of_two_injected_slugs_credits_only_it
§3.2 confounding: cites both, overlaps one	test_commit_citing_both_but_overlapping_one_credits_only_it
matcher semantics = surface_cold	test_glob_matching_uses_surface_cold_semantics
never_injected	test_cited_but_never_injected_rejected, test_empty_ledger_never_queries_commits
§3.6 forged sha / seam contract	test_default_git_seam_parses_only_wellformed_cited_records, test_default_git_seams_fail_closed_on_git_error, test_planner_only_sees_commits_the_merged_default_listing_returned
§3.5 racing CI ⇒ "unknown", never True	test_pending_ci_plans_unknown, test_nonstandard_ci_value_degrades_to_unknown_never_true, test_default_ci_seam_without_repo_or_token_is_unknown
CI False recorded verbatim	test_ci_false_recorded_verbatim
§4.4 write-once	test_already_attributed_item_skipped
§3.3 cold-only scope	test_warm_tier_cited_item_is_out_of_scope, test_cited_slug_with_no_item_rejected_unknown_slug
earliest-commit determinism	test_multiple_qualifying_commits_earliest_wins, test_equal_author_dates_break_ties_on_sha, test_earliest_nonqualifying_commit_does_not_block_later_qualifier
never raises (each seam throwing)	test_planner_never_raises_throwing_{commit,files,ci}_seam_yields_empty_plan
malformed ledger tolerated	test_malformed_ledger_lines_are_skipped_not_fatal
purity (byte-identical tree)	test_planning_writes_nothing, test_missing_context_dir_yields_calm_empty_plan
CLI dry-run	test_main_dry_run_prints_and_exits_zero, test_render_lists_attributions_and_rejections

Verification

Full suite 463 pass (432 base + 31 new); ruff check . clean; custodian audit 0 findings.

🤖 Generated with Claude Code