# PRINCIPLES.md — how Sam operates > Source of truth for **how/why** decisions get made here, captured so they aren't > re-derived every session. Drawn from actual practice in evidence (recent work + > the two-repo audit), not aspiration. Items marked **[PROPOSED]** are implied by > practice but not explicitly confirmed by Sam — confirm or correct them. > > Companion: `ARCHITECTURE.md` (what exists). Update both **at the moment of > decision**, not later. Individual architectural decisions get an ADR in > `docs/adr/`. --- ## 1. Value / cost - **Free / low-cost first; pay up only where it actually buys something.** Evidence: marine **80W-90 GL-5** recommended over premium HPF Pro where the spec allows (both correct — it's a cost choice, not a spec choice); **aftermarket part crosses** preferred over used-OEM (e.g. water-pump kit 438592, Group 24/27 battery — not the overkill Group 31); architecture targeted at **Firebase / Cloudflare free tiers**. - **Maximize Claude Code; minimize spend.** [PROPOSED as a stated goal — the behavior is clearly in evidence, but confirm it as an explicit principle.] - Record the *value reasoning* on the page (e.g. "either is correct; annual change matters more than brand"), so the cheap-vs-premium call isn't re-litigated. ## 2. Tooling / workflow - **The multi-agent pattern** (in evidence from how sessions run): - **Sam** — judgment + physical-world action (measures, photos, buys parts, makes the calls only he can make). - **Planning chat** — orchestrator; writes the bounded CC prompts. - **Claude Code (CC)** — lands durable work in the substrate; commits. - **Specialty chats** — domain depth (taxes, bets, equipment specifics). - [PROPOSED: the exact four-way division above is inferred from observed roles — confirm the wording.] - **Substrate = durable memory; chats = ephemeral.** Anything that must survive the session lands in the repo. Chat memory is continuity only, never authoritative. - **`awareness-backlog.md` is the single cross-session board** (status + SAM-FILL punch-list + the SAMEING-NOW block). One board, not several. - **Record-where-relevant.** No fact left only in a chat: parts research → the asset page; decisions → here / ARCHITECTURE.md / an ADR; status → the backlog. - **Canonical URLs over local paths** when referencing prior work (per METHODOLOGY / the canonical-URL rule), so any chat can fetch it. ## 3. Engineering - **Verify primary sources before reasoning from secondary.** The costly lessons: the Yamaha **V6-vs-I4** mix-up, **QBI** tax figures, the Aceves **paint color**, and a **fabricated HIN** — each came from trusting a secondary/remembered value. Pin it to the OEM diagram / manual / registration / the actual file. - **Never invent values → `SAM-FILL`.** A measurement, part number, price, or year that isn't confirmed is marked SAM-FILL (or SAM-CONFIRM), never guessed. Over- flagging beats a wrong-but-confident value. - **Corrections are propagated plainly, not softened.** When something was wrong (ownership, a figure, a spec), fix it directly and say so — don't bury it. - **Check current state before building; build only what's missing.** Read the file / git log first. Several "build X" tasks turned out already-done — confirmed and skipped rather than duplicated. - **One canonical home per subject** (approved 2026-06-05). Each asset/customer/project lives in exactly ONE authoritative place, by **category + owner** — Sam's equipment → `/equipment//` + `my-equipment.json`; customer work → `/customer-jobs/` + `customer-jobs.json`; dossiers → `/index/equipment/.md`. Superseded versions get **archived** (`/archive/-/` + NOTE + a 301 redirect), never left live next to their replacement. New content lands in its right home from the start. CC scans for scatter as routine recon (like hub parity) and consolidates — archive-not-delete, flag ambiguous canonical-choices for Sam. Full rule in METHODOLOGY.md "Consolidation". ## 4. Safety / data - **PII never goes on a public or soft-fenced surface.** Customer/family/financial data (names+addresses, tax figures, account numbers) is not for the public site or the soft-fenced hub. (See `handoff-blocks/architecture/auth-soft-vs-hard.md`.) - **"Protected by a bug" is not protection.** A broken route or an obscure URL is not a security control (the cece-taxes guide was reachable; robots.txt only asks crawlers). Gate it or remove it. - **A takedown isn't done until the live URL 404s.** Deleting from git + pushing is necessary but not sufficient — verify the deployed/edge state (the takedown needed a Cloudflare cache purge to actually clear). - **Per-user data isolation is a foundation, not a switch.** It must exist before building more multi-user pages, not be retrofitted onto a leaky structure. - **Local commits only; no push by default; Sam authorizes pushes.** Outward/ hard-to-reverse actions (push, repo-visibility, history rewrite, cache purge, routing changes) are Sam's call. - **`deploy-log.json` is left untouched** (standing local-mod, never committed). ## 5. CC session hygiene - **Bounded scope:** one workstream per session; prompts roughly 150-300 lines; fresh session per workstream (avoids cross-contamination + collision on substrate writes). - **Substrate cwd pinned** and HEAD verified at session start. - **`-CheckConventions` before each commit** (syntax check, no duplicate functions, bump versions where the repo requires; validate JSON/HTML). - **Harness flake** ("[Tool result missing due to internal error]") → retry once, surface, continue. - **Serialize substrate-writing sessions** (one writer at a time) to avoid clobbering commits + the deploy-log diff. - Commit by **explicit path** (never `git add -A`) so unrelated files (deploy-log, other sessions' work) stay isolated. --- ## PROPOSED items needing Sam's confirmation - §1 "Maximize Claude Code; minimize spend" as an explicitly-stated goal. - §2 the exact four-way agent division (wording). — PRINCIPLES.md created 2026-06-02 by CC from observed practice + the two-repo audit. Correct anything that doesn't match how you actually want to operate.