docs(v0): dogfood playbook — known classification limits (Swiss Cheese Layer 1) #56

Merged

pdurlej merged 1 commit from claude/patchwarden-dogfood-known-limits into main

2026-05-27 14:50:52 +02:00

claude commented

2026-05-27 14:43:08 +02:00

Collaborator

What

Closes Swiss Cheese Layer 1 gap (Scenariusz A z docs/operations/code-vs-vision-snapshot-2026-05-27.md).

This is PR C of 3 — completes the Swiss Cheese wave. Resolution not a code fix — content-aware secret scanning is pyfallow's domain, deferred to Q4 wiring per roadmap. Resolution here is operational: make the gap explicit so reviewing cousins know what the gate cannot guarantee and don't over-trust an eligible_clean verdict.

Code/docs changes

docs/operations/platform-dogfood.md (+43 lines):

1. "Last updated" stamp refreshed

Now reflects post-Swiss-Cheese hardening (#54 + #55 + this PR).

2. New section "Known classification limits"

Inserted before "When to break the loop". Three sub-parts:

a) Secret detection is by filename, not by content — explicit callout with concrete miss cases:

docs/api-tokens.md containing literal sk_live_… → passes safe_docs ❌
Token pasted into state/STATUS_NOW.md as debugging string ❌
Base64-encoded secrets in doc fixtures ❌
Inline comments in README.md containing access keys ❌

b) Resolution deferred to pyfallow integration — explains why (pyfallow's domain), where to track (roadmap Q4 2026), and what currently mitigates:

Iskra review (Step 9-10 of checklist)
Operator review (Step 11)
Small-diff discipline (Step 2 — <10 files, <200 lines)

c) Bottom line — "until pyfallow wires in, content-scanning trust lives in humans, not the deterministic gate. Do not treat eligible_clean on a docs PR as a guarantee that no sensitive content slipped through."

3. New sub-section "Other limits inherited from this design choice"

Adjacent acceptable v0 trade-offs (anchored back to P4 — keep the lane narrow):

No path-traversal protection
No bot-as-author check
No content drift between SHA verification

These are bounded by the W6d narrow-lane scope. Become risks only if scope widens.

Why this matters (Cagan tier-0 anchor discipline)

A playbook that only lists proven capabilities trains the next cousin to over-trust the gate. Listing what the gate cannot do is equally load-bearing — without it, a Sonnet sub-agent reviewing a W6d PR could plausibly think "Patchwarden returned eligible_clean, so the diff is safe end-to-end." That's the exact failure mode this section prevents.

It also makes the dogfood loop's actual security model legible: "deterministic gate covers structural classification; Iskra + operator review covers content." Without that legibility, operators might either over-trust (false confidence) or under-trust (refuse to use what's working).

Test impact

None — docs-only edit. 152/152 tests still green. Both file links verified to exist on main.

Atomic per ADR-0017

1 file edited (no new file), +43 lines, 0 deletions
0 src changes, 0 test changes
base=main, no stacking

Swiss Cheese wave — COMPLETE 🧀🛡️

PR	Layer	Status
#54 PR A	Layer 8 resolver hand-off	✅ merged
#55 PR B	Layer 6 architectural lint	✅ merged
THIS PR C	Layer 1 secret-by-filename doc	⏳ awaiting merge

After this merges, the three highest-priority Swiss Cheese gaps from the 2026-05-27 crosscheck are:

Closed in code (PR A + PR B)
Documented + mitigated by process (PR C)

The remaining lower-priority gaps stay on the snapshot as deferred items pending M3 refresh (2026-10-15).

NOT breaking M2 gate

Pure docs edit over existing playbook. No new feature, no new code. Per docs/decisions.md D16 + M2 milestone notes, documenting existing behavior is in-scope; this is exactly that.

Token-accounting

~1-2% weekly Opus (small docs edit, content I already had loaded from snapshot synthesis).

## What Closes Swiss Cheese **Layer 1** gap (Scenariusz A z `docs/operations/code-vs-vision-snapshot-2026-05-27.md`). This is **PR C of 3** — completes the Swiss Cheese wave. Resolution **not** a code fix — content-aware secret scanning is pyfallow's domain, deferred to Q4 wiring per roadmap. Resolution **here** is operational: make the gap **explicit** so reviewing cousins know what the gate cannot guarantee and don't over-trust an `eligible_clean` verdict. ## Code/docs changes `docs/operations/platform-dogfood.md` (+43 lines): ### 1. "Last updated" stamp refreshed Now reflects post-Swiss-Cheese hardening (#54 + #55 + this PR). ### 2. New section "Known classification limits" Inserted before "When to break the loop". Three sub-parts: **a) Secret detection is by filename, not by content** — explicit callout with concrete miss cases: - `docs/api-tokens.md` containing literal `sk_live_…` → passes safe_docs ❌ - Token pasted into `state/STATUS_NOW.md` as debugging string ❌ - Base64-encoded secrets in doc fixtures ❌ - Inline comments in `README.md` containing access keys ❌ **b) Resolution deferred to pyfallow integration** — explains why (pyfallow's domain), where to track (roadmap Q4 2026), and what currently mitigates: - Iskra review (Step 9-10 of checklist) - Operator review (Step 11) - Small-diff discipline (Step 2 — `<10` files, `<200` lines) **c) Bottom line** — *"until pyfallow wires in, content-scanning trust lives in humans, not the deterministic gate. Do not treat `eligible_clean` on a docs PR as a guarantee that no sensitive content slipped through."* ### 3. New sub-section "Other limits inherited from this design choice" Adjacent acceptable v0 trade-offs (anchored back to P4 — keep the lane narrow): - No path-traversal protection - No bot-as-author check - No content drift between SHA verification These are bounded by the W6d narrow-lane scope. Become risks only if scope widens. ## Why this matters (Cagan tier-0 anchor discipline) A playbook that **only** lists proven capabilities trains the next cousin to over-trust the gate. Listing what the gate **cannot** do is equally load-bearing — without it, a Sonnet sub-agent reviewing a W6d PR could plausibly think *"Patchwarden returned eligible_clean, so the diff is safe end-to-end."* That's the exact failure mode this section prevents. It also makes the dogfood loop's actual security model **legible**: "deterministic gate covers structural classification; Iskra + operator review covers content." Without that legibility, operators might either over-trust (false confidence) or under-trust (refuse to use what's working). ## Test impact **None — docs-only edit.** 152/152 tests still green. Both file links verified to exist on `main`. ## Atomic per ADR-0017 - 1 file edited (no new file), +43 lines, 0 deletions - 0 src changes, 0 test changes - `base=main`, no stacking ## Swiss Cheese wave — COMPLETE 🧀🛡️ | PR | Layer | Status | |---|---|---| | #54 PR A | Layer 8 resolver hand-off | ✅ merged | | #55 PR B | Layer 6 architectural lint | ✅ merged | | **THIS PR C** | Layer 1 secret-by-filename doc | ⏳ awaiting merge | After this merges, the **three highest-priority** Swiss Cheese gaps from the 2026-05-27 crosscheck are: - Closed in code (PR A + PR B) - Documented + mitigated by process (PR C) The remaining lower-priority gaps stay on the snapshot as deferred items pending M3 refresh (2026-10-15). ## NOT breaking M2 gate Pure docs edit over existing playbook. No new feature, no new code. Per [`docs/decisions.md`](../docs/decisions.md) D16 + M2 milestone notes, documenting existing behavior is in-scope; this is exactly that. ## Token-accounting ~1-2% weekly Opus (small docs edit, content I already had loaded from snapshot synthesis).

claude added 1 commit

2026-05-27 14:43:08 +02:00

docs(v0): dogfood playbook — known classification limits (Swiss Cheese Layer 1) 5b5455b314

Closes Layer 1 Swiss Cheese gap (Scenariusz A in
`docs/operations/code-vs-vision-snapshot-2026-05-27.md`). Resolution
**not** a code fix — content-aware secret scanning is pyfallow's
domain, deferred to Q4 wiring per roadmap. Resolution **here** is
operational: make the gap explicit so reviewing cousins know what the
gate cannot guarantee and don't over-trust an `eligible_clean` verdict.

This is **PR C of 3 defense-hardening PRs** spun off the 2026-05-27
crosscheck — completes the Swiss Cheese wave.

## What changes

`docs/operations/platform-dogfood.md`:

1. **"Last updated"** stamp now reflects post-Swiss-Cheese hardening
   (#54 resolver soft-fail detection + #55 D20 architectural lint).

2. **New section "Known classification limits"** before "When to break
   the loop":
   - **Secret detection is by filename, not by content** — explicit
     callout that `docs/api-tokens.md` with a literal token passes the
     gate today. Concrete examples (token in .md, in status marker, in
     README comment, base64-encoded fixture).
   - **Resolution deferred** to pyfallow integration; explains why
     (pyfallow's domain) and where to track (roadmap Q4 2026).
   - **Mitigations in current loop** — Iskra review (Step 9-10),
     operator review (Step 11), small-diff discipline (Step 2).
   - **Bottom line**: until pyfallow wires in, content-scanning trust
     lives in humans, not the deterministic gate. Do not treat
     `eligible_clean` on a docs PR as a guarantee that no sensitive
     content slipped through.

3. **"Other limits inherited from this design choice"** sub-section
   notes adjacent gaps that are acceptable v0 trade-offs for the
   narrow W6d lane but would become risks if scope widens:
   - No path-traversal protection
   - No bot-as-author check
   - No content drift between SHA

   Anchored back to P4 (focus enables shipping) — these are bounded
   by keeping the lane narrow.

## Why this matters

Per Cagan tier-0 anchor discipline: a playbook that **only** lists
proven capabilities trains the next cousin to over-trust the gate.
Listing what the gate **cannot** do is equally load-bearing — without
it, a Sonnet sub-agent reviewing a W6d PR could plausibly think
"Patchwarden returned eligible_clean, so the diff is safe end-to-end."
That's the failure mode this section prevents.

## Test impact

None. Docs-only edit. 152/152 tests still green.

## Atomic per ADR-0017

- 1 file edited (no new file), +43 lines, 0 deletions
- 0 src changes, 0 test changes
- `base=main`, no stacking on prior PRs

## Swiss Cheese wave — COMPLETE

| PR | Layer | Status |
|---|---|---|
| #54 PR A | Layer 8 resolver hand-off | ✅ merged |
| #55 PR B | Layer 6 architectural lint | ✅ merged |
| **THIS PR C** | Layer 1 secret-by-filename doc | ⏳ awaiting merge |

After this merges, the three highest-priority Swiss Cheese gaps from
the 2026-05-27 crosscheck are closed (PR A + PR B) or documented +
mitigated by process (PR C). The remaining lower-priority gaps stay
on the snapshot as deferred items pending M3 refresh.

## NOT breaking M2 gate

Pure docs edit over existing playbook. No new feature, no new code.
Per `docs/decisions.md` D16 + M2 milestone notes, documenting existing
behavior is in-scope; this is exactly that.

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