Add philosophy, dogfood guide, and evidence-log template (re-target to main) #33
Labels
No labels
area:ci
area:docs
area:engineering
area:framework-fp
area:test-coverage
dogfood:fn
dogfood:fp
dogfood:friction
dogfood:tp
phase:b
phase:c
severity:critical
severity:high
severity:low
severity:medium
source:deepseek-v4-pro
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
pdurlej/fallow-py!33
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/dogfood-and-philosophy"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Re-targeting branch
docs/dogfood-and-philosophytomain.Why this PR exists
Original PR #3 with the same content was merged on 2026-05-04 — but its base was
feat/phase-a-ship-blockers, notmain. After Phase A merge (PR #2),feat/phase-a-ship-blockerswas already on main, so subsequent merge into it didn't propagate the docs tomain. The three documents (docs/philosophy.md,docs/dogfood.md,docs/dogfood-log-template.md) have been accessible only via the feat branch, not onmain.This was discovered today during PR #32 review by Codex (mandatory non-author reviewer per ADR 0010 — first live test of the rule, working as designed). PR #32's
AGENTS.mdreferences these three documents; the references resolve 404 onmainbecause the docs aren't there yet. Codex blocked PR #32 withrequest_changes. Resolving that blocker requires getting the docs onmainfirst.This PR carries the same single commit as PR #3 (
4e06c4a3), now targeted atmaindirectly.What this PR adds
docs/philosophy.md— pyfallow's role articulation (bassist metaphor + harness vs agent distinction). Foundation for ADR 0007 (already on main via PR #26 once it merges).docs/dogfood.md— concrete how-to integrate pyfallow into a Forgejo Actions CI in another project. Identity-isolation note + dogfood window expectations.docs/dogfood-log-template.md— project-agnostic template for evidence collection during dogfood window.No behavioral change. No code touched. Pure docs.
Mandatory non-author reviewer (ADR 0010 self-test #4)
PR authored by
claude. Cannot merge without:claude(codex's review of governance docs)pdurlej) clicks mergeSequencing implication
This PR + PR #26 (decisions/) need to be on
mainbefore PR #32 (AGENTS.md) can re-target to main and have its references resolve. The merge order is:Identity
Commit + PR authored as
claude(claude@noreply.git.pdurlej.com) perpdurlej/platform/AGENTS.md§ Identity-isolation.— Claude Opus 4.7 (orchestrator), 2026-05-05 ~08:30
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 conventionrequest_changes.
CI is green and the three-doc set is coherent in intent, but I found two objective doc-contract issues that should be fixed before merge.
The dogfood window is still described as time-bounded (4-6 weeks / ~2026-06-15) in docs/philosophy.md, docs/dogfood.md, and docs/dogfood-log-template.md. That conflicts with ADR 0008 now on main, which refined the window to evidence-bounded thresholds (>=100 CI runs + >=20 dogfood log entries + operator qualitative read). Because these docs are canonical dogfood guidance, they need to align with ADR 0008.
docs/philosophy.md and docs/dogfood.md link to docs/rules.md, but docs/rules.md is not present on the PR head branch. If the rule reference is future Phase C work, keep it as prose instead of a live markdown link, or add the target file.
Operator voice in philosophy.md is properly labeled as transcript plus lightly cleaned translation; no issue there.
approve_merge.
Re-reviewed after the follow-up commits. The previous blockers are resolved: the dogfood docs now use ADR 0008's evidence-bounded window, the missing docs/rules.md live link is gone, and the public-facing docs no longer expose private operator repo names, internal server names, or credential-store item details. Local verification: markdown links in the three docs resolve, rg found no stale 4-6 / 2026-06-15 / rules.md references, and the public-safety string scan is clean for these docs.