From ca82081a8e394e58777ac44a052d1bc9f09f5d1e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 17:33:07 +0000 Subject: [PATCH] Replace the engineering standard with the version that has no operational notes Section 0 carried incident dates, the Netlify account's history and a list of repositories that were private. The canonical copy in Democracy-by-Design keeps the rules and the notes are kept privately. This is the same file. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_012Anbt5KBvEgZYcpeztabaU --- .claude/engineering-standards.md | 95 ++++++++++---------------------- 1 file changed, 30 insertions(+), 65 deletions(-) diff --git a/.claude/engineering-standards.md b/.claude/engineering-standards.md index 8fb8fe5..2d28f2a 100644 --- a/.claude/engineering-standards.md +++ b/.claude/engineering-standards.md @@ -13,65 +13,37 @@ everywhere else. ## 0. How the standard works with what these repositories already do -These rules come from decisions the owner has already made, and they shape how -the rest of this file is applied. - -**Ask first when the request is unclear or consequential.** The owner's -standing instruction is to ask clear clarifying questions before running code -when a request is ambiguous, when it names no target, or when the work would be -hard to undo. When the request is clear and the step is reversible and low -risk, do the work instead of stopping at a plan (section 17). - -**Deploys cost money, so changes are batched.** On 13 October 2026 the Netlify -team ran out of credits and all 35 of its sites went offline. Netlify charges -15 credits for every production deploy it publishes. A deploy preview, and a -build that is never published, cost nothing. So: - -- Work on the session's development branch and push there. Open a pull - request only when the owner asks for one, and never merge without being - asked. -- Build all day and publish once. Do not merge on your own judgement: the - owner merges, and nothing goes live before 20:00 IST. Do not use Firecrawl - where curl or a web search will do; its credits are paid for. -- Every site on the Netlify team has auto-publishing locked except - democracybydesign.in, which must be able to take a photograph down at once. - A merge builds but goes live only at 20:00 IST, once a day, when the "Publish - locked sites" workflow in Democracy-by-Design (`tools/publish-locked.py`) - publishes the newest finished build of each locked site. The script reads - the locked set from Netlify, not from a list. Running that workflow by hand, - with a site name, publishes at once. A green build is therefore not a live - change; say which one you have verified. -- A workflow that commits to the production branch on a schedule makes a - build each time. On a locked site that build is free until the next publish - window; on democracybydesign.in, or on a site someone unlocks, every such - commit is a paid deploy. -- Dependabot runs monthly, groups its updates into one pull request per - ecosystem and opens at most two at a time. A weekly stream of pull requests - invites a weekly stream of merges. - -**Hosting.** Porkbun is the registrar and nothing else; Netlify does hosting -and DNS (owner's rule, 12 October 2026). A few repositories also publish to -GitHub Pages, and their `CLAUDE.md` says so. Do not move a site between hosts +**Ask first when the request is unclear or consequential.** Ask clear +clarifying questions before running code when a request is ambiguous, names no +target, or would be hard to undo. When the request is clear and the step is +reversible and low risk, do the work instead of stopping at a plan (section 17). + +**Deploys cost money, so changes are batched.** A production deploy can be a +paid event. Work on a development branch, open a pull request only when asked, +and never merge without being asked. Gather related changes into one merge +rather than several. A deploy preview, and a build that is never published, cost +nothing. A green build is not a live change; say which one you have verified. +A workflow that commits to the production branch on a schedule makes a build +each time, so check what that costs before adding another. Dependency updates +should arrive monthly, grouped, a few at a time. + +**Hosting.** Keep the hosting a project has. Do not move a project between hosts unless asked. **Writing.** Everything a reader sees, including README files, documentation, -commit messages, issue text and the reports to the owner, follows the owner's -writing rules: plain full sentences with facts and sources; no em dashes; no -"X, not Y" or "not only... but also" constructions; no stock vocabulary -(robust, leverage, seamless, crucial, delve and the rest of the owner's list); -sentence-case headings; no emoji; no bold leads. Several repositories enforce -part of this in CI (`check-copy-tells.py`, `check_writing.py`, `BANNED` lists). -A check passing does not mean the prose is right. +commit messages, issue text and reports, uses plain full sentences with facts +and sources; no em dashes; no "X, not Y" or "not only... but also" +constructions; no stock vocabulary; sentence-case headings; no emoji; no bold +leads. Several repositories enforce part of this in CI. A check passing does not +mean the prose is right. **Websites talk about their subject, never about themselves.** No page tells a reader how it was built or researched ("read twice", "the build fails unless", -"generated by"). That belongs in `CLAUDE.md` and the research files (owner's -rule for every website, 14 October 2026). +"generated by"). That belongs in `CLAUDE.md` and the research files. **Numbers.** Never restate a count copied from another repository, a partial read, or prose that nothing checks. Take it from the source at build time, pin -it with a check, or stop stating it. Every repository that drifted did so this -way. +it with a check, or stop stating it. **Checks must be able to fail.** No `|| true`, `|| echo`, `2>/dev/null` hiding the reason, or `fail: false` on a gate. A long job that talks to third-party @@ -84,19 +56,12 @@ the commit says it was. opacity, a control no keyboard reaches, a row wider than a phone, and an `element.hidden` overridden by a `display` rule. After any change to colour, layout or the header, measure in a browser: axe at 390x844 and 1280x900 in both -colour schemes, and `scrollWidth` against `clientWidth`. Chromium is installed -in the cloud sandbox; it reaches localhost and not the internet, so stub CDN -scripts by route. - -**Privacy and law.** Most of these repositories are public. Fourteen were -private on 2026-10-19: Chromalie, Democracy-by-Design, INDIA-DATA, -IdealogWorks, WhoGaveTheOrder, WomenOnRecord, allthegoodstuff, -impactmojo-field-notes-pro, impactmojo-workshop-pro, makeitpop, -phototales-studio, pika-woodcraft, pinpointventures and storywell. A private -repository can be made public with one click, and everything in its history -goes with it, so treat every one as public: never commit a secret, a -personal email address that is not already the published contact, or -row-level personal data (names, EPIC numbers, phone numbers). No survivor or +colour schemes, and `scrollWidth` against `clientWidth`. + +**Privacy and law.** Treat every repository as public: a private repository can +be made public with one click and its whole history goes with it. Never commit a +secret, a personal email address that is not already the published contact, or +row-level personal data (names, ID numbers, phone numbers). No survivor or private person is named on a page. A licence, a privacy claim or a compliance claim that needs a decision goes to the owner; record it as outstanding rather than inventing it. @@ -316,8 +281,8 @@ Never say a feature was tested when it was read or inferred. The cloud session clones each repository shallow. A script that reads git history (a change log, a feed, a "last updated" date) either refuses to run or writes a different answer from CI, and a refusal can look like a clean diff. -Run `git fetch --unshallow` before trusting it. WhoGaveTheOrder's `build.js` -refused, and the empty diff was briefly read as a pass (2026-10-19). +Run `git fetch --unshallow` before trusting it. A script that refuses can leave +an empty diff, and an empty diff is not a pass. ## 7. CI/CD and dependencies