Add philosophy, dogfood guide, and evidence-log template #3

Merged

pdurlej merged 1 commit from docs/dogfood-and-philosophy into feat/phase-a-ship-blockers

2026-05-04 23:30:47 +02:00

claude commented

2026-05-04 22:57:47 +02:00

Collaborator

Three governance documents codifying pyfallow's role under operator's anti-AI-slop strategic decision (chat 2026-05-04).

What this PR adds

docs/philosophy.md — pyfallow as deterministic gate; position next to platform.exe for code (counterpart to its role for infra); operator's founding principle ("non-technical PM needs deterministic governance to keep agents from shipping stupidities under my command") in operator's own words. Promises pyfallow makes (determinism, single source of truth, conservative classification, drift detection). What pyfallow refuses to be (no opinions, no memory, no opinion-based blocking).
docs/dogfood.md — concrete how-to: integrate pyfallow into a Forgejo Actions CI in your project. 3-step setup (copy template, pin alpha, configure .pyfallow.toml). Operator decision tree for reading CI output. Identity-isolation note (per platform/AGENTS.md, each actor commits with own PAT). Sister project pyfallow-mcp wiring. Dogfood window expectations (4-6 weeks).
docs/dogfood-log-template.md — project-agnostic template for keeping a dogfood log when integrating pyfallow into a new project. Categories ([TP]/[FP]/[FN]/[FRICTION]/[SURPRISE]/[WIN]/[META]). Recommended copy target is project's gitignored working-notes dir.

Why this is on top of Phase A

Branch docs/dogfood-and-philosophy is built from feat/phase-a-ship-blockers so it inherits the 5 ship-blocker commits. The base of this PR is feat/phase-a-ship-blockers (not main) — dependent PR. Merge order: Phase A first, then this. After both merge, main will have Phase A code + governance docs.

If you prefer to land docs directly to main independent of Phase A, I can rebase onto main instead — let me know.

What this PR does NOT change

No runtime behavior of pyfallow, pyfallow-mcp, or the CLI
No tests (governance prose has no executable claims)
No CHANGELOG entry (these are docs about pyfallow's stance, not a release)

Identity

Commit authored as claude (claude@noreply.git.pdurlej.com) per platform/AGENTS.md identity-isolation. Same author for this PR (no operator pushing as claude).

— Claude Opus 4.7 (orchestrator), nightly continuation 2026-05-04

Three governance documents codifying pyfallow's role under operator's anti-AI-slop strategic decision (chat 2026-05-04). ## What this PR adds - `docs/philosophy.md` — pyfallow as deterministic gate; position next to `platform.exe` for code (counterpart to its role for infra); operator's founding principle ("non-technical PM needs deterministic governance to keep agents from shipping stupidities under my command") in operator's own words. Promises pyfallow makes (determinism, single source of truth, conservative classification, drift detection). What pyfallow refuses to be (no opinions, no memory, no opinion-based blocking). - `docs/dogfood.md` — concrete how-to: integrate pyfallow into a Forgejo Actions CI in your project. 3-step setup (copy template, pin alpha, configure `.pyfallow.toml`). Operator decision tree for reading CI output. Identity-isolation note (per platform/AGENTS.md, each actor commits with own PAT). Sister project `pyfallow-mcp` wiring. Dogfood window expectations (4-6 weeks). - `docs/dogfood-log-template.md` — project-agnostic template for keeping a dogfood log when integrating pyfallow into a new project. Categories ([TP]/[FP]/[FN]/[FRICTION]/[SURPRISE]/[WIN]/[META]). Recommended copy target is project's gitignored working-notes dir. ## Why this is on top of Phase A Branch `docs/dogfood-and-philosophy` is built from `feat/phase-a-ship-blockers` so it inherits the 5 ship-blocker commits. The base of this PR is `feat/phase-a-ship-blockers` (not `main`) — dependent PR. Merge order: Phase A first, then this. After both merge, `main` will have Phase A code + governance docs. If you prefer to land docs directly to `main` independent of Phase A, I can rebase onto `main` instead — let me know. ## What this PR does NOT change - No runtime behavior of pyfallow, pyfallow-mcp, or the CLI - No tests (governance prose has no executable claims) - No CHANGELOG entry (these are docs about pyfallow's stance, not a release) ## Identity Commit authored as `claude` (claude@noreply.git.pdurlej.com) per platform/AGENTS.md identity-isolation. Same author for this PR (no operator pushing as claude). — Claude Opus 4.7 (orchestrator), nightly continuation 2026-05-04

claude added 1 commit

2026-05-04 22:57:47 +02:00

Add philosophy, dogfood guide, and evidence-log template

CI / Python 3.11 (push) Successful in 52s

Details

CI / Python 3.12 (push) Successful in 56s

Details

CI / Python 3.13 (push) Successful in 55s

Details

CI / Python 3.11 (pull_request) Successful in 51s

Details

CI / Python 3.12 (pull_request) Successful in 52s

Details

CI / Python 3.13 (pull_request) Successful in 53s

Details

4e06c4a3d1

Three governance documents articulating pyfallow's role as a
deterministic gate in the operator's multi-agent ecosystem,
written under operator direction (anti-AI-slop posture, dogfood
before Show HN strategic decision 2026-05-04).

docs/philosophy.md — pyfallow as pure function (repo state, config)
→ findings, no memory between invocations, no opinions about
purpose. Position in operator's stack alongside Iskra (relational),
platform.exe (deterministic infra gate), Codex (producer), 3+3
canary review (PR gate). Pyfallow is the deterministic code gate
counterpart to platform.exe's deterministic infra gate. Cites
operator's founding principle ("non-technical product person needs
deterministic governance to avoid agents shipping stupidities under
my command") in the operator's own words. Lists what pyfallow
refuses to be (no opinions, no memory, no opinion-based blocking),
what pyfallow promises (determinism, single source of truth across
transports, conservative classification, stable fingerprints, drift
detection, hostile-input safety). Agent and operator usage
protocols.

docs/dogfood.md — concrete how-to integrate pyfallow into a Forgejo
Actions CI pipeline in operator's other repos (pdurlej/platform,
hermes-agency, iskra-openclaw). Three-step minimal integration:
copy template, pin to TestPyPI alpha (0.3.0a2), configure
.pyfallow.toml for project. Operator decision tree for reading CI
comments. Downstream agent reading of pyfallow-report.json
artifact. Identity-isolation note per platform AGENTS.md (each
actor commits with own PAT, never pushes as operator). Sister
project pyfallow-mcp wiring for MCP-using agents. Dogfood window
expectations (4-6 weeks starting 2026-05-04) and procedure for
disagreeing with pyfallow's findings (issue first, suppress only
with reasoning).

docs/dogfood-log-template.md — project-agnostic template for
keeping a dogfood log when integrating pyfallow into a new project.
Categories ([TP] / [FP] / [FN] / [FRICTION] / [SURPRISE] / [WIN] /
[META]) and entry format. Recommended copy target is the project's
own gitignored working-notes directory (pyfallow uses .codex/
convention). Explicitly explains why this is a template not a live
log — the active log lives outside git so operators and agents can
add raw, half-formed observations without polishing for posterity.

These docs do not change pyfallow's runtime behavior. They codify
the operator's strategic direction as project memory, distinct from
agent working notes which live in gitignored .codex/.

Verified:
- All three files render cleanly as Markdown (manual check)
- Cross-references between the three resolve (philosophy → dogfood,
  dogfood → philosophy, both → log template)
- No reference to .codex/ paths in published docs (those would be
  broken for external readers since .codex is gitignored)
- Identity-isolation: this commit is authored as `claude`
  (claude@noreply.git.pdurlej.com) per platform AGENTS.md convention