B13: Drop `manual_only` from classification namespace + add mandatory explainability #27

New issue

Open

opened 2026-05-05 03:01:40 +02:00 by claude · 0 comments

claude commented

2026-05-05 03:01:40 +02:00

Collaborator

Ticket B13 (post-operator-review, 2026-05-05)

Operator decision (chat 2026-05-05, recorded as ADR 0009 in forthcoming sister PR to decisions/): drop manual_only from classification namespace; rename review_needed to decision_needed; add mandatory explainability for decision_needed and blocking findings.

Why

Quoting operator:

"Manual_only nie jest dobre. Bo jeśli mamy AI [który pomaga] człowiekowi, który nie umie ogarniać tak jak ja — to co mi da manual_only? To jest tak, że prosisz wiesz, który jest niekompetentny, żeby podjął decyzję. Równie dobrze możesz rzucić tą monetą."

Pyfallow's mission is deterministic governance for non-technical operator. Asking that operator to make decisions on findings that pyfallow itself doesn't classify is asking the operator to flip a coin — antithetical to the mission.

Scope

Three-bucket classification in src/pyfallow/classify.py: auto_safe / decision_needed / blocking
Rename review_needed → decision_needed everywhere (core, MCP, tests, schemas, JSON output formats, agent-fix-plan output)
Migrate existing manual_only findings: each rule that previously routed to manual_only either (a) now routes to decision_needed with explanation, or (b) is dropped from the analyzer entirely if it's not a real finding category.
Mandatory explainability field on Finding: every decision_needed and blocking finding must have trade_offs: list[str] (or similar) that explains options the operator can take. Schema-enforced (Pydantic).
Drift test updated to match new namespace. Test fails fast if anyone re-introduces manual_only.
Wire format change documented in CHANGELOG. Breaking change vs 0.3.0a2. Bump to 0.3.0a3 (or higher if accumulated with other Phase B work).

Phase context

Phase B execution is gated on dogfood evidence (per ADR 0008 + ADR 0009). This ticket is high priority because operator's strategic decision specifically calls it out — but execution waits until evidence accumulates that the new namespace is needed (other Phase B items might surface different concerns first).

Reference

ADR 0009 (forthcoming) — full decision context with operator's voice quoted
Issue #4 (B1: Iterative Tarjan) — Phase B sequencing context

## Ticket B13 (post-operator-review, 2026-05-05) Operator decision (chat 2026-05-05, recorded as ADR 0009 in forthcoming sister PR to `decisions/`): drop `manual_only` from classification namespace; rename `review_needed` to `decision_needed`; add **mandatory explainability** for `decision_needed` and `blocking` findings. ## Why Quoting operator: > "Manual_only nie jest dobre. Bo jeśli mamy AI [który pomaga] człowiekowi, który nie umie ogarniać tak jak ja — to co mi da `manual_only`? To jest tak, że prosisz wiesz, który jest niekompetentny, żeby podjął decyzję. Równie dobrze możesz rzucić tą monetą." Pyfallow's mission is deterministic governance for non-technical operator. Asking that operator to make decisions on findings that pyfallow itself doesn't classify is asking the operator to flip a coin — antithetical to the mission. ## Scope 1. **Three-bucket classification** in `src/pyfallow/classify.py`: `auto_safe` / `decision_needed` / `blocking` 2. **Rename** `review_needed` → `decision_needed` everywhere (core, MCP, tests, schemas, JSON output formats, agent-fix-plan output) 3. **Migrate** existing `manual_only` findings: each rule that previously routed to `manual_only` either (a) now routes to `decision_needed` with explanation, or (b) is dropped from the analyzer entirely if it's not a real finding category. 4. **Mandatory explainability field** on `Finding`: every `decision_needed` and `blocking` finding must have `trade_offs: list[str]` (or similar) that explains options the operator can take. Schema-enforced (Pydantic). 5. **Drift test** updated to match new namespace. Test fails fast if anyone re-introduces `manual_only`. 6. **Wire format change** documented in CHANGELOG. Breaking change vs `0.3.0a2`. Bump to `0.3.0a3` (or higher if accumulated with other Phase B work). ## Phase context Phase B execution is gated on dogfood evidence (per ADR 0008 + ADR 0009). This ticket is high priority because operator's strategic decision specifically calls it out — but execution waits until evidence accumulates that the new namespace is needed (other Phase B items might surface different concerns first). ## Reference - ADR 0009 (forthcoming) — full decision context with operator's voice quoted - Issue #4 (B1: Iterative Tarjan) — Phase B sequencing context

claude added the

phase:b

severity:high

area:engineering

labels

2026-05-05 03:01:40 +02:00

claude referenced this issue

2026-05-05 03:09:42 +02:00

ADRs 0009-0011 + edits to 0001/0003/0006/0007/0008 (operator review 2026-05-05) #30

claude referenced this issue from a commit

2026-05-05 03:09:42 +02:00

Add ADRs 0009-0011 + edits to 0001/0003/0006/0007/0008 (operator review 2026-05-05)