Add release_decision.contribution_rules[] audit (v0.17)

[pengfei-threemoonslab]

Summary

• Adds release_decision.contribution_rules[] — a deterministic per-finding audit of how each finding contributed to the release decision. Exactly one row per report.findings entry, including suppressed. The (rule, category) pair documents which branch of the gate fired.
• Bumps report_schema_version 0.16 → 0.17. Documents the existing v0.8 classification as the new "Release decision truth table" in STABILITY.md — 10 rows + prose explainers covering baseline asymmetry and the exit-code-vs-decision split.
• No semantic change. decision, blockers[], review_items[], fail_policy.exit_code, and strict-mode exit are byte-identical to v0.16. The audit reflects existing behavior, it does not modify it.

What's in the audit

{
  "finding_id": "fp_f092940f62fbb012",
  "fingerprint": "fp_f092940f62fbb012",
  "check_id": "SHIP-POLICY-APPROVAL-MISSING",
  "category": "blocker",
  "rule": "policy_block_new",
  "rationale": "blocks_release=true and baseline_status=new; explicit policy blocker."
}

category enum: blocker | review_item | excluded
rule enum: policy_block_new | severity_block_new | policy_baseline_accepted | severity_baseline_accepted | review_required | sub_threshold | suppressed

Both enums inlined in docs/report-schema.v0.17.json so consumers can switch on them.

Why

Per the architecture review's M8 trust-hardening item: a reviewer reading the JSON should be able to predict the gate outcome for any finding without re-deriving the decision logic. The truth table in STABILITY.md is the contract; contribution_rules[] is the runtime witness that the gate followed it.

The audit is purely additive — defaults to [] for legacy reports loaded via explain-finding, so consumers never need an existence check. No new flags, no new exit codes, no behavior change.

Test plan

• All 1099 tests pass (was 1086 before; +13 truth-table cases + 2 invariants + 1 schema lock = 16 new tests)
• All 20 pre-existing test_release_decision.py tests still pass — no semantic regression
• ruff check clean on changed files
• python scripts/generate_schemas.py is idempotent (running twice produces no diff)
• All 4 sample expected reports regenerated; len(contribution_rules) == len(findings) invariant verified across all samples
• Schema lock test (test_v17_schema_requires_contribution_rules) freezes both enums and required keys
• CI passes

Files

Layer	Files
Domain	src/agents_shipgate/core/models.py (new ContributionRule, ContributionRuleName, field on ReleaseDecision, schema bump)
Decision	src/agents_shipgate/ci/release_decision.py (per-finding audit emission, helpers, comments documenting that the branching mirrors v0.16 exactly)
Schema	scripts/generate_schemas.py (pin required keys), docs/report-schema.v0.17.json (regenerated)
Tests	tests/test_release_decision.py (+16 tests), tests/test_reports.py (v0.17 lock test), tests/test_provenance_kind.py, tests/test_public_surface_contract.py (v0.16 → legacy pattern)
Contract	STABILITY.md (truth table + stable field), CHANGELOG.md, .well-known/agents-shipgate.json
Public surface (0.16 → 0.17)	README.md, AGENTS.md, llms.txt, llms-full.txt (regenerated), skills/agents-shipgate/SKILL.md, docs/{INDEX,examples,agent-contract-current,autofix-policy,baseline,report-reading-for-agents}.md
Samples	samples/{support_refund_agent,simple_openai_api_agent,simple_langchain_agent,simple_crewai_agent}/expected/report.json

🤖 Generated with Claude Code