6965915dbd
The basis for every project here was itself unversioned: no .git, no remote, no history. Changes to it had no diff and no revert, and two of its own guards could not run at all -- doc-claims.sh and doc-triggers.py both read git history, so the script written to catch documentation drift could not be run against the documents that define drift. This is the tree as it stands, including work that until now existed only as loose files on disk: WORK_CYCLE.md, TOOLS.md, the Portainer image-line fix in deploy.py, the status vocabulary corrected to the four words the conformance checker actually enforces, the Exempt: mechanism documented, and the Forgejo instance named in README.md. secrets.sh --tracked reports one candidate, migrate.sh:480. It is the comment documenting the three Postgres credential shapes that script redacts, with literal placeholders, and it is left alone deliberately: GUARDS.md section 2 is that a source-grep guard must tell code from the comment about code, and deleting an explanation to quiet a scanner is the failure it names. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| README.md | ||
README.md
Design
Status: Current
Owner: <who maintains this>
Last reviewed: <YYYY-MM-DD>
Governs: docs/design/**
Review trigger: Any new user-facing surface, or a change to the product's tone
What belongs here
What it should feel like, and the decisions behind that:
- Product decisions — what the user can do, in what order, and what happens when they get it wrong. The error states are design, not an afterthought.
- UI plans — screens, states, and what each one is for. Include the empty state and the loading state; they are the two most people see first and the two most often left undesigned.
- Copy — the actual words. Interface text is a design surface, and writing it late means writing it badly.
- Tone — how this product talks. One paragraph is enough, and it settles a hundred small arguments.
What does not belong here
- How it is built — that is
docs/architecture/ - Scope and audience — that is
docs/planning/PROJECT_PLAN.md
Include the rejected version
For any decision that was genuinely close, record what was not chosen and why. Without it, the same option gets proposed every few months and re-argued from nothing.