docs(v0): pyfallow / fallow-ts integration plan (Wizji-Wartości D4) #59

Merged

pdurlej merged 1 commit from claude/patchwarden-pyfallow-integration-plan into main

2026-05-27 16:34:47 +02:00

claude commented

2026-05-27 16:03:44 +02:00

Collaborator

What

Wizji-Wartości Wave step D4 — final. New file docs/operations/pyfallow-integration-plan.md (+234 lines). Architectural decision document (PLAN, not execution) for closing Luka 3 from operator mental-model discovery.

Per D21: planning permitted under amended M2; execution stays parked until M2 evidence supports it. Doc captures the shape so when evidence lands, integration isn't invented under time pressure.

Why this plan

Operator mental model step 1 ("PR → deterministic Python/TS code quality check") is Luka 3 in current dogfood loop. fallow-ts alpha shipped 5 months ahead of plan (2026-05-19), making this plannable now. M2-compatible because planning ≠ binding runtime deps.

What's in it

Section	Purpose
Why this plan exists	Luka 3 framing + why fallow-ts alpha unlocks planning
What needs integrating	pyfallow + fallow-ts shape; scope reminder (structural evidence, NOT linter)
4 architectural options	A (subprocess), B (lib import — parked), C (MCP server), D (workflow pre-step) — with per-option trade-offs
Recommended path	Option D for v0 (M2-compatible), Option A for v1 (post-M2 + evidence)
Decision triggers	What evidence unlocks execution (M2 interviews, dogfood evidence on #523, M3 operator decision)
Pre-conditions	What must be true before execution (regardless of option)
Wrongness signals	When integration is WRONG choice
Open questions for M3	Captured now to avoid time-pressure invention later
Anti-scope	What plan does NOT cover (execution timeline, schemas, linter wiring)

Recommended path summary

v0 (now → post-M2): Option D — external workflow pre-step in each client repo. Uses Patchwarden's existing --findings-file flag. Zero CLI changes. Already-validated pattern from pdurlej/platform#523 workflow shape. Failure isolation maximal. Each repo opts in/out independently.

v1 (post-M2 + discovery confirms demand): Option A — subprocess from new code_checks.py module. Keeps stdlib-only, type-safe, no runtime dep in pyproject.toml.

Explicit avoid through 2027: Option B (lib import) — license + dep-creep risks exceed value; explicitly parked under D21.

Per D21 — M2-permitted

Planning of architectural integration is explicitly permitted under amended M2 (D21 §"Permitted: Documentation + ADRs"). Plan does NOT:

Propose new features
Bind new runtime deps
Change policy schema
Add new CLI subcommand

Execution remains parked under D21 hard-manual classes until evidence + M3 review.

Atomic per ADR-0017

1 new file (docs/operations/pyfallow-integration-plan.md), +234 lines
Existing docs/operations/ directory
0 src changes, 0 test changes
base=main post-D2 merge
152/152 tests still green

Wizji-Wartości Wave — COMPLETE after this merges 🎯

PR	What	Status
D1 (#57)	D21 amendment — legalize wave	✅ merged
D2 (#58)	dogfood actual-vs-mental-model	✅ merged
D3 (platform#523 → #524)	workflow wiring — Ollama + post-findings	✅ codex shipped
D4 (this PR)	pyfallow-integration-plan	⏳ final

After this merges + codex's pdurlej/platform#524 merges + smoke PR validates the loop end-to-end, Wave is fully delivered. Next layer of integration (pyfallow execution per Option D/A) waits for M2 evidence.

Token-accounting

~4% weekly Opus. Synthesis from architecture.md + decisions.md + crosscheck snapshot + dogfood-actual-vs-mental-model — all already loaded. The hard part was thinking through 4 options × trade-offs, not source-gathering.

## What **Wizji-Wartości Wave step D4 — final.** New file `docs/operations/pyfallow-integration-plan.md` (+234 lines). Architectural decision document (**PLAN, not execution**) for closing Luka 3 from operator mental-model discovery. Per D21: planning permitted under amended M2; execution stays parked until M2 evidence supports it. Doc captures the shape so when evidence lands, integration isn't invented under time pressure. ## Why this plan Operator mental model step 1 ("PR → deterministic Python/TS code quality check") is Luka 3 in current dogfood loop. fallow-ts alpha shipped 5 months ahead of plan (2026-05-19), making this **plannable now**. M2-compatible because planning ≠ binding runtime deps. ## What's in it | Section | Purpose | |---|---| | Why this plan exists | Luka 3 framing + why fallow-ts alpha unlocks planning | | What needs integrating | pyfallow + fallow-ts shape; scope reminder (structural evidence, NOT linter) | | 4 architectural options | A (subprocess), B (lib import — parked), C (MCP server), D (workflow pre-step) — with per-option trade-offs | | Recommended path | Option D for v0 (M2-compatible), Option A for v1 (post-M2 + evidence) | | Decision triggers | What evidence unlocks execution (M2 interviews, dogfood evidence on #523, M3 operator decision) | | Pre-conditions | What must be true before execution (regardless of option) | | Wrongness signals | When integration is WRONG choice | | Open questions for M3 | Captured now to avoid time-pressure invention later | | Anti-scope | What plan does NOT cover (execution timeline, schemas, linter wiring) | ## Recommended path summary **v0 (now → post-M2)**: **Option D — external workflow pre-step in each client repo.** Uses Patchwarden's existing `--findings-file` flag. Zero CLI changes. Already-validated pattern from `pdurlej/platform#523` workflow shape. Failure isolation maximal. Each repo opts in/out independently. **v1 (post-M2 + discovery confirms demand)**: **Option A — subprocess from new `code_checks.py` module.** Keeps stdlib-only, type-safe, no runtime dep in `pyproject.toml`. **Explicit avoid through 2027**: Option B (lib import) — license + dep-creep risks exceed value; explicitly parked under D21. ## Per D21 — M2-permitted Planning of architectural integration is explicitly permitted under amended M2 (D21 §"Permitted: Documentation + ADRs"). Plan does NOT: - Propose new features - Bind new runtime deps - Change policy schema - Add new CLI subcommand Execution remains **parked under D21 hard-manual classes** until evidence + M3 review. ## Atomic per ADR-0017 - 1 new file (`docs/operations/pyfallow-integration-plan.md`), +234 lines - Existing `docs/operations/` directory - 0 src changes, 0 test changes - `base=main` post-D2 merge - 152/152 tests still green ## Wizji-Wartości Wave — COMPLETE after this merges 🎯 | PR | What | Status | |---|---|---| | D1 (#57) | D21 amendment — legalize wave | ✅ merged | | D2 (#58) | dogfood actual-vs-mental-model | ✅ merged | | D3 (platform#523 → #524) | workflow wiring — Ollama + post-findings | ✅ codex shipped | | **D4 (this PR)** | pyfallow-integration-plan | ⏳ final | After this merges + codex's `pdurlej/platform#524` merges + smoke PR validates the loop end-to-end, Wave is **fully delivered**. Next layer of integration (pyfallow execution per Option D/A) waits for M2 evidence. ## Token-accounting ~4% weekly Opus. Synthesis from architecture.md + decisions.md + crosscheck snapshot + dogfood-actual-vs-mental-model — all already loaded. The hard part was thinking through 4 options × trade-offs, not source-gathering.

claude added 1 commit

2026-05-27 16:03:44 +02:00

docs(v0): pyfallow / fallow-ts integration plan (Wizji-Wartości D4) eecc8a00fb

Wizji-Wartości Wave step D4 — final. Architectural decision document
(PLAN, not execution) for closing Luka 3 from operator mental-model
discovery: pyfallow + fallow-ts integration into Patchwarden's
deterministic content-check layer.

Per D21: planning is permitted under amended M2; execution stays parked
until M2 evidence supports it. This doc captures the shape so when
evidence lands, the integration isn't invented under time pressure.

## What's in it

- **Why this plan exists** — Luka 3 framing, why fallow-ts alpha
  (shipped 5mo early) makes this plannable now
- **What needs integrating** — pyfallow (Python L1) + fallow-ts (TS L1'),
  with scope reminder (structural evidence, NOT linter / formatter)
- **Four architectural options** with per-option trade-offs:
  - A: Runtime subprocess (`subprocess.run` from new code_checks.py)
  - B: Python lib import (pyfallow as runtime dep) — parked per D21
  - C: HTTP MCP server (long-lived `pyfallow-mcp`)
  - D: External pre-step in client repo workflow (NOT in Patchwarden CLI)
- **Recommended path**: Option D for v0 (M2-compatible), Option A for
  v1 (post-M2, after discovery confirms demand)
- **Decision triggers** — what evidence unlocks execution
  (M2 interview signal, dogfood evidence on platform after #523, M3
  operator decision; anti-triggers if Bet 1 wrongness fires)
- **Pre-conditions** before execution (regardless of option)
- **Wrongness signals** — when integration is WRONG choice
- **Open questions for M3** — captured now to avoid time-pressure
  invention later
- **Anti-scope** — what plan does NOT cover (execution timeline,
  specific schemas, performance, linter wiring, Cloud)

## Recommended path rationale

Option D (workflow pre-step) is recommended for v0 because:
- Zero changes to Patchwarden CLI — uses existing `--findings-file` path
- Already validated pattern (Ollama integration in `pdurlej/platform#523`
  uses similar workflow-step shape)
- Failure isolation maximal (pyfallow crash = workflow step fail, never
  touches Patchwarden process)
- M2-compatible per D21 — no runtime dep, no new CLI capability,
  no new module
- Each client repo opts in/out independently

Option B (Python lib import) explicitly avoided through 2027 — license
+ dep-creep risks exceed value, and explicitly parked under D21.

## Per D21 — this is M2-permitted

Planning of architectural integration is explicitly permitted under
amended M2 (D21 §"Permitted: Documentation"). Plan does NOT propose
new features, does NOT bind new runtime deps, does NOT change policy
schema. Execution remains parked until M2 evidence + M3 review.

## Test impact

None — docs-only. 152/152 tests still green.

## Atomic per ADR-0017

- 1 new file (`docs/operations/pyfallow-integration-plan.md`), +236 lines
- Existing `docs/operations/` directory
- 0 src changes, 0 test changes
- base=main (post-D2 merge)

## Wizji-Wartości Wave — COMPLETE after this PR

- D1 (#57): D21 amendment ✅ merged
- D2 (#58): dogfood actual-vs-mental-model ✅ merged
- D3 (platform#523): workflow wiring ✅ codex shipped #524
- D4 (this PR): pyfallow-integration-plan ⏳ final

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>