Align agent fix-plan with ADR 0009 decision contract #61

Merged

pdurlej merged 1 commit from codex/decision-contract-27 into main

2026-05-18 22:42:29 +02:00

codex commented

2026-05-18 19:07:30 +02:00

Collaborator

Canary Context Pack

Product story

Fallow-py should expose one operator-facing decision contract everywhere: auto_safe, decision_needed, and blocking. ADR 0009 says the operator needs explicit trade-offs, not a split between review_needed and manual_only that makes agents infer product intent.

What changed

Replaced product-facing review_needed / manual_only with decision_needed across core fix-plan output and MCP grouped responses.
Added trade_offs to fix-plan items and MCP finding/remediation/classification models.
Kept grouping single-sourced through src/fallow_py/classify.py.
Updated schema, golden fixture, docs, CI comment rendering, agent examples, soak prompt summarization, and v0.3.0 example zip bundles.

Why it changed

This pulls issue #27 into the pre-dogfood contract slice: evidence logs and agent workflows should count one decision bucket with the trade-offs needed for human/operator judgment.

Files touched

Core classifier, MCP schemas/runtime/tools/safety/remediation, fix-plan schema/golden/tests, docs/examples, CI comment renderer, soak harness prompt summary.

Relevant context

ADR 0009: three-bucket classification with product-language explanations.
Recent dogfood evidence work keeps legacy report compatibility in the aggregator; this PR changes active product surfaces, not historical log parsing.

Runtime evidence

PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m pytest -q
PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m compileall -q src tests mcp/src mcp/tests scripts/dogfood
git diff --check
PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium
PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium

Known constraints

The dogfood aggregator still recognizes legacy review_needed and manual_only artifacts so existing logs remain readable. That compatibility is intentionally not removed here.

Explicit out-of-scope

No new analyzer rules, no evidence cockpit, no benchmark claims, no broad Phase B/C execution.

Requested decision

Approve if the active CLI/MCP/docs/examples contract is now aligned with ADR 0009 and the compatibility boundary is acceptable.

Merge blockers

Any active product surface still emitting manual_only or review_needed as the current contract.
Missing trade_offs on decision_needed or blocking findings.
CI or self-audit failures.

## Canary Context Pack ### Product story Fallow-py should expose one operator-facing decision contract everywhere: `auto_safe`, `decision_needed`, and `blocking`. ADR 0009 says the operator needs explicit trade-offs, not a split between `review_needed` and `manual_only` that makes agents infer product intent. ### What changed - Replaced product-facing `review_needed` / `manual_only` with `decision_needed` across core fix-plan output and MCP grouped responses. - Added `trade_offs` to fix-plan items and MCP finding/remediation/classification models. - Kept grouping single-sourced through `src/fallow_py/classify.py`. - Updated schema, golden fixture, docs, CI comment rendering, agent examples, soak prompt summarization, and v0.3.0 example zip bundles. ### Why it changed This pulls issue #27 into the pre-dogfood contract slice: evidence logs and agent workflows should count one decision bucket with the trade-offs needed for human/operator judgment. ### Files touched Core classifier, MCP schemas/runtime/tools/safety/remediation, fix-plan schema/golden/tests, docs/examples, CI comment renderer, soak harness prompt summary. ### Relevant context - ADR 0009: three-bucket classification with product-language explanations. - Recent dogfood evidence work keeps legacy report compatibility in the aggregator; this PR changes active product surfaces, not historical log parsing. ### Runtime evidence - `PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m pytest -q` - `PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m compileall -q src tests mcp/src mcp/tests scripts/dogfood` - `git diff --check` - `PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium` - `PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium` ### Known constraints The dogfood aggregator still recognizes legacy `review_needed` and `manual_only` artifacts so existing logs remain readable. That compatibility is intentionally not removed here. ### Explicit out-of-scope No new analyzer rules, no evidence cockpit, no benchmark claims, no broad Phase B/C execution. ### Requested decision Approve if the active CLI/MCP/docs/examples contract is now aligned with ADR 0009 and the compatibility boundary is acceptable. ### Merge blockers - Any active product surface still emitting `manual_only` or `review_needed` as the current contract. - Missing `trade_offs` on `decision_needed` or `blocking` findings. - CI or self-audit failures.

codex added 1 commit

2026-05-18 19:07:30 +02:00

Align agent fix-plan with decision contract

CI / Python 3.11 (push) Successful in 1m0s

Details

CI / Python 3.12 (push) Successful in 1m5s

Details

CI / Python 3.13 (push) Successful in 1m4s

Details

CI / Python 3.11 (pull_request) Successful in 1m1s

Details

CI / Python 3.12 (pull_request) Successful in 1m6s

Details

CI / Python 3.13 (pull_request) Successful in 1m6s

Details

683c824fed

Implements ADR 0009 product-facing classification: auto_safe, decision_needed, blocking. Adds trade_offs to non-auto fix-plan and MCP surfaces, removes manual_only/review_needed from active CLI/MCP/docs examples, and regenerates v0.3.0 agent bundles.

Verified:

- PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m pytest -q

- PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m compileall -q src tests mcp/src mcp/tests scripts/dogfood

- git diff --check

- PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium

- PYTHONPATH=/Users/pd/Developer/fallow-python-domain-a/src:/Users/pd/Developer/fallow-python-domain-a/mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium

codex requested review from claude

2026-05-18 19:07:54 +02:00

pdurlej scheduled this pull request to auto merge when all checks succeed

2026-05-18 22:42:18 +02:00