From 8c9d37a2d0066a24d335efacc65198dd2c3e5f7d Mon Sep 17 00:00:00 2001 From: tdwd <111124579+tdwd@users.noreply.github.com> Date: Fri, 28 Aug 2026 18:35:12 +0200 Subject: [PATCH] Put the public-tree rule where a contributor meets it The rule that this tree is read by strangers lived only in the working instructions, which are deliberately not committed, so it reached nobody who cloned. It now opens docs/architecture.md, before the overview, because it governs every section below it: a rule met after 600 lines is a rule met too late. It states what a contributor must obey and nothing else. Write for a reader who knows nothing about another project; a push cannot be recalled, because an object stays fetchable by its hash after a force-push; and test fixtures are the usual leak rather than the obvious secrets, so invented names must still preserve the property under test. The same rule covers assets/, which is why the screenshots are taken against the workspace make demo builds. Closes backlog item 12, which was open on a decision rather than on work: how much of the uncommitted instructions belong in the published tree. The answer drawn here is the rule, never the measurement. --- docs/architecture.md | 23 +++++++++++++++++++++++ docs/backlog.md | 22 +++++++++++++--------- 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index f6510aa..91b758d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,6 +4,29 @@ How Deck is put together, and why the parts that look strange are the way they are. Most of it was learned by getting it wrong once, so each section states the trap as well as the rule. `README.md` is the user-facing guide. +## This tree is public + +Everything committed here is read by strangers: code, comments, these docs, +test fixtures and commit messages. A push cannot be recalled. An object stays +fetchable by its hash after a force-push, and a clone or a fork keeps it +whatever the branch later says, so the only reliable moment to catch something +is before it is pushed. + +Write for a reader who knows nothing about any other project. That rules out +other repositories' names, local paths, and commercial or organisational +reasoning. It also rules out describing an unfixed weakness, which is the worst +of the set: a comment saying where the validation is missing is a map to it, +and that holds when the code is your own. State the rule without the hole, and +put the hole somewhere private. + +**Test fixtures are the usual leak, not the obvious secrets.** A test needs +names, so give it invented ones chosen to preserve the property under test — +if the assertion is about column width, keep the lengths. A list borrowed +from the machine you wrote it on publishes every name on that machine. The +same rule covers `assets/`: the screenshots are taken against the throwaway +workspace `make demo` builds, because a capture of a real store shows the +name of every project in it. + ## Overview Deck is a Bubble Tea TUI that manages projects and sessions and hosts one diff --git a/docs/backlog.md b/docs/backlog.md index e576fab..1b097c3 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -184,12 +184,16 @@ Worth doing only if a review ever runs long enough that watching the number move tells you something a spinner does not. The measured runs so far finish in a few seconds. -## 12. A public-repo notice a cloner will meet - -`CLAUDE.md` carries the rule that this repository is public, that it is written -for a stranger, and that fixtures count. It is deliberately not committed, so -that rule reaches nobody who clones. - -A short section in `docs/architecture.md` would put it where the next -contributor meets it. Left open because it is a decision about how much of the -working instructions belong in the published tree, not an oversight. +## ~~12. A public-repo notice a cloner will meet~~ — done 2026-08-28 + +Shipped as **This tree is public** in `docs/architecture.md`, placed before +`## Overview` rather than at the end: it governs every section below it, and a +rule met after 600 lines is a rule met too late. + +The decision it was waiting on was how much of the uncommitted working +instructions belong in the published tree. The answer drawn here is *the rule, +never the measurement*. What a contributor must obey travels — write for a +stranger, fixtures count, a push cannot be recalled. What only describes this +machine or this history stays out, which is the same distinction the rule +itself asks a contributor to make. So the section gives the mechanism — an +object survives a force-push — and stops there.