docs(v0): README — explicit "What works today" vs "What's planned" table #64

New issue

Closed

opened 2026-05-28 13:38:39 +02:00 by claude · 1 comment

claude commented

2026-05-28 13:38:39 +02:00

Collaborator

Goal

Close the single biggest reader-confusion gap identified in the 2026-05-28 Cloud Opus 4.6 repo review: any first-time visitor reading README.md + docs/vision.md will assume Patchwarden is a 6-layer system today. It isn't — it's a narrow CLI gate for docs-only PRs with the rest of the vision intentionally parked. The current README doesn't make that explicit at the top.

Why this matters

Cloud Opus 4.6 review, §II.1: "Repo wygląda bardziej jak product strategy deck z PoC niż jak narzędzie gotowe do instalacji."
docs/operations/dogfood-actual-vs-mental-model.md already says this honestly, but it lives three folders deep. The README is the first thing anyone reads.
Adding the table is documentation only, zero code change — D21-compatible defense against external misunderstanding.

Scope

1) Add a "Status today vs planned" section near the top of `README.md`

Place it directly after the project tagline and before any feature list. Shape:

## What works today (2026-05-28 evidence-confirmed) vs what's planned

| Capability | Today | Planned |
|---|---|---|
| Path-prefix classifier (`pr-check`) | ✅ Production on `pdurlej/platform` W6d lane | — |
| Reviewer-lane Ollama call (cloud or local) | ✅ Evidence-confirmed on `pdurlej/platform#527` (1m6s, real Ollama findings + comment posted by bot identity) | — |
| `post-findings --execute` → PR comment | ✅ Under dedicated `patchwarden` bot identity (id 9, scope `write:issue`) | — |
| Soft-fail detection on transport/unparseable | ✅ `resolve-findings` emits `soft_fail_review_unreliable` per PR #54 | — |
| Lane gating (live reviewer only on `safe_docs_status`) | ✅ Per platform workflow | — |
| pyfallow / fallow-ts deterministic content checks (Luka 3) | ❌ Not wired | 🟡 Parked under M2 evidence per D21 — see `docs/operations/pyfallow-integration-plan.md` |
| Forgejo webhook / service mode | ❌ Not built | 🟡 Parked — `pdurlej/patchwarden#31` prepares event parser |
| Cloud control plane (L3) | ❌ Not built | 🟡 Y2 per `docs/roadmap.md` |
| Auto-heal / OpenClaw integration (L4) | ❌ Not built | 🟡 Post-v0 |
| Iskra handoff automation | ❌ Manual | 🟡 Parked — requires new capability scoping |
| Style/linter integration (Ruff/Biome/ESLint) | ❌ Not in scope | ❌ Won't fix — client CI responsibility, not Patchwarden's |

> **Read this when you wonder how much is real:** `docs/operations/dogfood-actual-vs-mental-model.md` for the full coverage breakdown (~60% of operator's mental model evidence-confirmed as of 2026-05-28).

2) Link the new section from `docs/vision.md`

A single line near the top of vision.md pointing readers to the README section so the vision can stay aspirational while readers know where to find ground truth.

3) Operator-voice ("you click merge") preserved

Don't rewrite tone — Patchwarden's README is operator-voice per existing convention (docs/operations/platform-dogfood.md keeps the same style). Just add the table.

Acceptance criteria

New section appears in README.md, ideally between the tagline and any feature/install section.
Every "Today ✅" row links to concrete evidence (an issue/PR number, a test file, or a docs/operations file). No vague claims.
Every "Planned 🟡" row links to the doc that explains why it's parked (D21, roadmap, integration-plan, etc.).
docs/vision.md gets one sentence near the top: "For the realistic 'what works today' status, see the table in README.md."
No code changes; no test changes required. Sanity: PYTHONPATH=src python3 -m unittest discover tests still green.
The table is markdown-parseable in Forgejo's renderer (test by previewing on the PR).

No-go

❌ Do NOT delete or move the existing vision/strategy content — operator decision (D8): vision is locked until 2029. The README addition is status reality, not vision revision.
❌ Do NOT add aspirational rows to "Today" — only verifiable, evidence-linked claims. If unsure whether something works today, it's "Planned".
❌ Do NOT change ADR/D-decision text — those are immutable.
❌ Do NOT modify the README's existing operator-voice tone.

Spec sources

README.md — current state
docs/vision.md — for the cross-link
docs/operations/dogfood-actual-vs-mental-model.md — coverage breakdown to link from the table footer
docs/operations/platform-dogfood.md — "What IS proven" / "What is NOT proven" rows are the source of truth for the table content
docs/operations/code-vs-vision-snapshot-2026-05-27.md — Bet 2 ratio (~70% evidence-confirmed as of 2026-05-28)
docs/decisions.md D21 (M2 gate amendment) — context for why some items are parked
2026-05-28 Cloud Opus 4.6 repo analysis, §II.1 "Przepaść między dokumentacją a kodem"

Status flow

ready-for-agent → agent claims → PR → operator review → merge

Created 2026-05-28 by claude (Patchwarden dedicated thread) after Cloud Opus 4.6 review surfaced the gap. Atomic enough for any cousin (e.g. Cloud Opus 4.6 via Antigravity) to pick up — pure docs, zero code risk.

## Goal Close the **single biggest reader-confusion gap** identified in the 2026-05-28 Cloud Opus 4.6 repo review: any first-time visitor reading `README.md` + `docs/vision.md` will assume Patchwarden is a 6-layer system today. It isn't — it's a narrow CLI gate for docs-only PRs with the rest of the vision intentionally parked. The current README doesn't make that explicit at the top. ## Why this matters - Cloud Opus 4.6 review, §II.1: *"Repo wygląda bardziej jak product strategy deck z PoC niż jak narzędzie gotowe do instalacji."* - `docs/operations/dogfood-actual-vs-mental-model.md` already says this honestly, but it lives three folders deep. The README is the first thing anyone reads. - Adding the table is **documentation only, zero code change** — D21-compatible defense against external misunderstanding. ## Scope ### 1) Add a "Status today vs planned" section near the top of `README.md` Place it directly after the project tagline and before any feature list. Shape: ```markdown ## What works today (2026-05-28 evidence-confirmed) vs what's planned | Capability | Today | Planned | |---|---|---| | Path-prefix classifier (`pr-check`) | ✅ Production on `pdurlej/platform` W6d lane | — | | Reviewer-lane Ollama call (cloud or local) | ✅ Evidence-confirmed on `pdurlej/platform#527` (1m6s, real Ollama findings + comment posted by bot identity) | — | | `post-findings --execute` → PR comment | ✅ Under dedicated `patchwarden` bot identity (id 9, scope `write:issue`) | — | | Soft-fail detection on transport/unparseable | ✅ `resolve-findings` emits `soft_fail_review_unreliable` per PR #54 | — | | Lane gating (live reviewer only on `safe_docs_status`) | ✅ Per platform workflow | — | | pyfallow / fallow-ts deterministic content checks (Luka 3) | ❌ Not wired | 🟡 Parked under M2 evidence per D21 — see `docs/operations/pyfallow-integration-plan.md` | | Forgejo webhook / service mode | ❌ Not built | 🟡 Parked — `pdurlej/patchwarden#31` prepares event parser | | Cloud control plane (L3) | ❌ Not built | 🟡 Y2 per `docs/roadmap.md` | | Auto-heal / OpenClaw integration (L4) | ❌ Not built | 🟡 Post-v0 | | Iskra handoff automation | ❌ Manual | 🟡 Parked — requires new capability scoping | | Style/linter integration (Ruff/Biome/ESLint) | ❌ Not in scope | ❌ Won't fix — client CI responsibility, not Patchwarden's | > **Read this when you wonder how much is real:** `docs/operations/dogfood-actual-vs-mental-model.md` for the full coverage breakdown (~60% of operator's mental model evidence-confirmed as of 2026-05-28). ``` ### 2) Link the new section from `docs/vision.md` A single line near the top of vision.md pointing readers to the README section so the vision can stay aspirational while readers know where to find ground truth. ### 3) Operator-voice ("you click merge") preserved Don't rewrite tone — Patchwarden's README is operator-voice per existing convention (`docs/operations/platform-dogfood.md` keeps the same style). Just add the table. ## Acceptance criteria - New section appears in `README.md`, ideally between the tagline and any feature/install section. - Every "Today ✅" row links to concrete evidence (an issue/PR number, a test file, or a docs/operations file). No vague claims. - Every "Planned 🟡" row links to the doc that explains why it's parked (D21, roadmap, integration-plan, etc.). - `docs/vision.md` gets one sentence near the top: *"For the realistic 'what works today' status, see the table in `README.md`."* - No code changes; no test changes required. Sanity: `PYTHONPATH=src python3 -m unittest discover tests` still green. - The table is markdown-parseable in Forgejo's renderer (test by previewing on the PR). ## No-go - ❌ Do NOT delete or move the existing vision/strategy content — operator decision (D8): vision is locked until 2029. The README addition is **status reality**, not vision revision. - ❌ Do NOT add aspirational rows to "Today" — only verifiable, evidence-linked claims. If unsure whether something works today, it's "Planned". - ❌ Do NOT change ADR/D-decision text — those are immutable. - ❌ Do NOT modify the README's existing operator-voice tone. ## Spec sources - `README.md` — current state - `docs/vision.md` — for the cross-link - `docs/operations/dogfood-actual-vs-mental-model.md` — coverage breakdown to link from the table footer - `docs/operations/platform-dogfood.md` — "What IS proven" / "What is NOT proven" rows are the source of truth for the table content - `docs/operations/code-vs-vision-snapshot-2026-05-27.md` — Bet 2 ratio (~70% evidence-confirmed as of 2026-05-28) - `docs/decisions.md` D21 (M2 gate amendment) — context for why some items are parked - 2026-05-28 Cloud Opus 4.6 repo analysis, §II.1 "Przepaść między dokumentacją a kodem" ## Status flow `ready-for-agent` → agent claims → PR → operator review → merge --- Created 2026-05-28 by claude (Patchwarden dedicated thread) after Cloud Opus 4.6 review surfaced the gap. Atomic enough for any cousin (e.g. Cloud Opus 4.6 via Antigravity) to pick up — pure docs, zero code risk.

claude added the

labels

2026-05-28 13:38:40 +02:00

Iskra commented

2026-06-08 03:05:18 +02:00

Collaborator

{
"confidence": 5,
"effort_hint": "small",
"escalation": {
"kind": "patchwarden_review",
"reason": "README scope clarity should match Patchwarden product positioning and v0 boundaries."
},
"evidence_refs": [
{
"note": "Issue adds a README status table distinguishing what works today from planned vision.",
"type": "forgejo",
"value": "issue-title-body-labels-and-target-snapshot"
},
{
"note": "Body states first-time readers may mistake Patchwarden for a full six-layer system today.",
"type": "forgejo",
"value": "issue-body-reader-confusion"
},
{
"note": "Scope is documentation-only and places the status section near the top of README.",
"type": "forgejo",
"value": "issue-body-scope"
}
],
"impact": 3,
"judge_actor": {
"name": "iskra",
"runtime": "openclaw"
},
"judged_at": "2026-06-08T01:04:00Z",
"labels_to_apply": [
"judge/p3",
"judge/patchwarden-candidate"
],
"piotr_fit": "medium",
"priority": "p3",
"rationale_summary": "This is P3 Patchwarden cleanup because clearer README positioning prevents overclaiming without changing product capability.",
"reach": 3,
"recommended_next_action": "patchwarden_candidate",
"rerun_reason": "no_prior_judgment",
"schema": "openclaw.judge.v0",
"target": {
"kind": "issue",
"number": 64,
"repo": "pdurlej/patchwarden"
},
"target_snapshot": {
"body_hash": "sha256:62dacf38b429a92c31a9db23ad3378f2494e6242ff6f48e8c96be34047a67fc2",
"commit_count": null,
"evidence_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"head_sha": null,
"labels": [
"agent/gemini",
"area:v0-core",
"flow/ready",
"kind/chore",
"ready-for-agent",
"size/small"
],
"labels_hash": "sha256:774a329d1fb7c016cdd1761b040e2350a85a7bff7c9bc1f4c0388029f5e878b4",
"state": "open",
"title_hash": "sha256:248cf64ea3e0cb09876b09b534b6b4c7bec8913286df5bbe528b62e816ffb614",
"updated_at": "2026-05-28T14:04:54+02:00"
},
"top_caveat": "Keep the table honest and narrow so it clarifies v0 rather than marketing the parked vision."
}

{ "confidence": 5, "effort_hint": "small", "escalation": { "kind": "patchwarden_review", "reason": "README scope clarity should match Patchwarden product positioning and v0 boundaries." }, "evidence_refs": [ { "note": "Issue adds a README status table distinguishing what works today from planned vision.", "type": "forgejo", "value": "issue-title-body-labels-and-target-snapshot" }, { "note": "Body states first-time readers may mistake Patchwarden for a full six-layer system today.", "type": "forgejo", "value": "issue-body-reader-confusion" }, { "note": "Scope is documentation-only and places the status section near the top of README.", "type": "forgejo", "value": "issue-body-scope" } ], "impact": 3, "judge_actor": { "name": "iskra", "runtime": "openclaw" }, "judged_at": "2026-06-08T01:04:00Z", "labels_to_apply": [ "judge/p3", "judge/patchwarden-candidate" ], "piotr_fit": "medium", "priority": "p3", "rationale_summary": "This is P3 Patchwarden cleanup because clearer README positioning prevents overclaiming without changing product capability.", "reach": 3, "recommended_next_action": "patchwarden_candidate", "rerun_reason": "no_prior_judgment", "schema": "openclaw.judge.v0", "target": { "kind": "issue", "number": 64, "repo": "pdurlej/patchwarden" }, "target_snapshot": { "body_hash": "sha256:62dacf38b429a92c31a9db23ad3378f2494e6242ff6f48e8c96be34047a67fc2", "commit_count": null, "evidence_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "head_sha": null, "labels": [ "agent/gemini", "area:v0-core", "flow/ready", "kind/chore", "ready-for-agent", "size/small" ], "labels_hash": "sha256:774a329d1fb7c016cdd1761b040e2350a85a7bff7c9bc1f4c0388029f5e878b4", "state": "open", "title_hash": "sha256:248cf64ea3e0cb09876b09b534b6b4c7bec8913286df5bbe528b62e816ffb614", "updated_at": "2026-05-28T14:04:54+02:00" }, "top_caveat": "Keep the table honest and narrow so it clarifies v0 rather than marketing the parked vision." }

Iskra added the

judge/p3

judge/patchwarden-candidate

labels

2026-06-08 03:05:19 +02:00

Iskra referenced this issue from pdurlej/judging-claw

2026-06-08 03:05:19 +02:00

[Judging Claw] patchwarden_candidate for pdurlej/patchwarden#64 (p3) #66

claude referenced this issue from a commit

2026-06-08 18:20:35 +02:00

docs(v0): README status table — what works today vs planned (closes #64)

claude referenced this issue from a pull request that will close it,