moving

docs/briefs/2026-05-05-claude-md-amendment-invariants.md

@@ -0,0 +1,207 @@
+# CC Brief — CLAUDE.md Amendment: Code-Level Invariants
+
+**Brief ID:** `cc-claude-md-amendment-invariants-v1`
+**Date:** 2026-05-05
+**Author:** PM
+**Status:** READY (Marko ratifikovao 2026-05-05 "uradi to sve")
+**Stream:** Solo CC sesija (single commit, single PR)
+**Wall-clock:** 30-45 min CC implementation
+**Cost cap:** $5 hard / $3 halt / $1-2 expected (mostly file edit + lint + commit)
+**Authority chain:**
+- `decisions/2026-04-30-pre-launch-sprint-consolidation-LOCKED.md`
+- `decisions/2026-04-30-branch-architecture-opcija-c.md`
+- `feedback_repo_access_boundaries` (PM-Waggle-OS r/w, waggle-os read-only)
+- `feedback_sha_verification_discipline`
+- `feedback_dangling_commit_hygiene`
+- `feedback_integration_sprint_policy`
+- `feedback_external_contract_validation`
+- `feedback_cost_projection_real_anchoring`
+
+---
+
+## §0 — Šta ovaj brief radi
+
+Trenutni `D:\Projects\waggle-os\CLAUDE.md` definiše code-level discipline koja se uglavnom odnosi na test runtime, file naming i commit conventions. Ovaj brief dodaje **nove sekcije** koje formalizuju *git workflow invariants* koji su do sada postojali samo u memorijama PM-a (Cowork) i u briefs/ folderu.
+
+Razlog: kad CC sesija krene fresh, ona čita samo `CLAUDE.md` plus brief koji joj se paste-uje. Bez ovih invariants u CLAUDE.md, CC može da uradi tehnički validnu git operaciju (npr. merge feature grane u main) koja je strateški pogrešna (zaobilazi integration sprint policy).
+
+Cilj amendment-a je da CC bude **defensively correct** čak i kad operator zaboravi da paste-uje konkretan brief — sigurnosna mreža nivoa CLAUDE.md hvata ono što operator propusti.
+
+---
+
+## §1 — Akcija za CC
+
+CC mora izvršiti sledeće u jednom atomic commit-u:
+
+1. Otvoriti `D:\Projects\waggle-os\CLAUDE.md`
+2. Pronaći najprikladniju poziciju za novu sekciju (verovatno posle bilo koje postojeće "Workflow" ili "Conventions" sekcije; ako takva ne postoji, dodati pre "License" ili na kraj fajla).
+3. Ubaciti tačno sledeću sekciju (paste-ready Markdown ispod u §2).
+4. Verifikovati da ostali sadržaj `CLAUDE.md` ostaje neizmenjen.
+5. Commit sa porukom: `docs(claude-md): add git workflow invariants and CC defensive guardrails`
+6. Push na `feature/claude-md-invariants-amendment` granu (ne direktno main).
+7. Otvoriti PR ka `main` sa kratkim opisom: "Adds defensive guardrails for CC sessions: feature branch policy, OSS subtree split discipline, Track A merge gate, SHA verification, dangling commit hygiene, repo access boundaries. Authoring trace u briefs/2026-05-05-claude-md-amendment-invariants.md."
+8. Halt-and-PM ako bilo koji od ovih koraka fail.
+
+**NAPOMENA:** Ne mergeovati PR — to je Marko-side action posle review-a.
+
+---
+
+## §2 — Paste-ready Markdown sekcija
+
+Sledeći blok je egzaktan Markdown koji ide u `CLAUDE.md`. CC ne sme da modifikuje sadržaj — samo da ga ubaci na izabranu poziciju.
+
+```markdown
+## Git Workflow Invariants
+
+These invariants protect against silent strategic errors during code-level work. They apply to every CC session regardless of whether a specific brief was paste-uvan.
+
+### Feature branch policy
+
+Feature branches do not merge directly to `main`. Every feature branch must pass through an integration sprint that:
+
+1. Verifies cross-package boundary regression (per `feedback_external_contract_validation` — shared mutable state mutations require regression test that crosses module boundaries).
+2. Resolves any chronic CRLF/whitespace noise from Windows ↔ Linux mount (do not commit `M` entries that are pure line-ending differences).
+3. Updates relevant memory entries in PM-Waggle-OS (PM authoring task, not CC).
+
+If a CC session is asked to merge a feature branch directly to `main` without explicit reference to a closed integration sprint, halt-and-PM. Direct merge is acceptable only for `docs(...)` and `chore(...)` commits where there is no behavioral change.
+
+### Track A desktop binary merge gate
+
+`feature/apps-web-integration` (Track A apps/web) is the source for the Tauri 2.0 desktop binary. It does not merge to `main` while the app is in active polish phase. The merge gate is:
+
+1. A release candidate tag (`v0.1.0-track-a-rc<N>`) on the feature branch, push-ovan na origin.
+2. UI/UX review pass (per `strategy/ui-ux/...` artifacts in PM-Waggle-OS).
+3. E2E persona walkthrough green for at least one persona (Solo / Pro / outlier).
+4. Marko sign-off on the release candidate.
+
+If a CC session is asked to merge `feature/apps-web-integration` to `main` and any gate is missing, halt-and-PM.
+
+### OSS subtree split discipline
+
+The `oss-hive-mind-*-export` branches in this repo are not hand-edited. They are generated by `git subtree split` against the latest `feature/hive-mind-monorepo-migration` HEAD and pushed to the public `marolinik/hive-mind` repo as the corresponding package branches.
+
+If a CC session is asked to commit directly to any `oss-hive-mind-*-export` branch, halt-and-PM. The correct workflow is: edit in `packages/hive-mind-*` on the monorepo migration branch, then re-run subtree split to regenerate the export branch.
+
+If the npm script for subtree split is not findable in `package.json` or `scripts/`, halt-and-PM rather than improvise — incorrect subtree split corrupts public repo history.
+
+### SHA reference discipline
+
+Any SHA in a commit message, brief, decision memo, or doc must be verified at the time of authoring with `git rev-parse <branch>` or `git log --oneline <branch> -1`. SHA references "from memory" or "from prior conversation" are forbidden.
+
+When a doc cites a SHA, include the verification timestamp in a footnote or inline note, e.g., "verified 2026-05-05 via `git rev-parse main` = `ceeb601`".
+
+This applies to PM authoring as well — if a brief paste-uvan u CC sesiju cites a SHA that does not match current `git rev-parse` output, halt-and-PM rather than acting on stale reference.
+
+### Dangling commit hygiene
+
+Before any branch operation that may orphan commits (rebase, force-push, branch deletion, worktree cleanup), run:
+
+```
+git fsck --lost-found
+```
+
+If any dangling commit exists, create a `<sprint-name>-archive` branch pointing to the dangling commit and push to origin before proceeding. Loss of dangling commits during sprint closure is a recurring risk class — the rescue branch is cheap insurance.
+
+### Working tree CRLF noise
+
+This repo runs on Windows and Linux mounts simultaneously (Windows is operator's daily driver, sandbox containers run Linux). The result is chronic line-ending noise: `git status` regularly shows hundreds of `M` entries for files that have no real content change.
+
+The rule: `M` entries that are pure CRLF/whitespace differences must not be committed. CC sessions should filter these out:
+
+```powershell
+git status --short | Where-Object { $_ -notmatch "^\?\?" -and $_ -notmatch "^\s*M\s" }
+```
+
+If a CC session sees a clean `git diff --stat` (zero lines added/removed) but `git status` shows `M`, that is CRLF noise and should be ignored — do not run `git add -A` indiscriminately.
+
+### Repo access boundaries
+
+This repo (`waggle-os`) is read-write for code work. The following sister directories have different boundaries:
+
+- `D:\Projects\PM-Waggle-OS\` — owned by PM (Cowork). Briefs, decisions, memory mirror, evidence files. CC may read for context (when paste-uvan u sesiju) but should not write directly. PM authoring is not a CC task.
+- `D:\Projects\hive-mind\` — public OSS sister repo. CC writes only during Day 0 minus 1 push gate (per `briefs/2026-05-05-day-0-minus-1-runbook.md`). Otherwise read-only.
+
+If a CC session is asked to write to PM-Waggle-OS or to commit to hive-mind outside the Day 0 minus 1 window, halt-and-PM.
+
+### Decision memo discipline
+
+Any LOCKED decision (capital "L" status) must have a corresponding `decisions/<date>-<topic>.md` file in PM-Waggle-OS. CC does not author decision memos — that is PM authoring. But CC sessions that complete a sprint stage marked LOCKED in a brief should emit a halt signal:
+
+```
+HALT-AND-PM decision-memo-pending
+Sprint stage: <name>
+Brief reference: <brief filename>
+Recommended PM action: author decisions/<date>-<topic>.md before next CC sprint kicks off
+```
+
+This catches the missing-decision-memo gap that has occurred in past sprints.
+
+### Cost projection anchoring
+
+Per `feedback_cost_projection_real_anchoring`, cost caps in briefs are anchored on real model pricing × max_tokens × probe-validated empirical run, not generic LLM rule-of-thumb. CC sessions should not propose self-revised cost cap based on "this seems hard"; if a brief cap is exceeded, halt-and-PM with evidence of where the spend went, and PM either ratifies amendment or scopes back work.
+
+### Halt-and-PM message format
+
+When CC needs to stop and ask PM for direction, emit a structured message:
+
+```
+HALT-AND-PM <stage-id>
+Reason: <one line, concrete>
+Evidence: <file path or git command output reference>
+Risk if proceed: <what goes wrong if you don't stop>
+Recommended action: <what CC thinks PM should do>
+```
+
+This format is parsed by PM in next session and turned into a decision or amendment. Vague halts ("not sure what to do") are harder to act on than structured halts.
+```
+
+---
+
+## §3 — Acceptance criteria za CC
+
+Posle commit-a + push-a, CC mora verifikovati:
+
+1. **`CLAUDE.md` parses kao validni Markdown.** Pokrenuti basic linter ako postoji u repo (`npm run lint:docs` ili sličan), inače `mdformat --check` ili manual visual check da nema nezatvorenih code blokova.
+
+2. **PR otvoren.** `gh pr view feature/claude-md-invariants-amendment` mora vratiti uspešan output sa kreiranim PR-om.
+
+3. **Diff je samo amendment, ne menja postojeće.** `git diff main...feature/claude-md-invariants-amendment -- CLAUDE.md` mora pokazati samo dodate linije, nula uklonjenih linija u postojećem sadržaju.
+
+4. **PR description sadrži link na ovaj brief.** Da bi audit trail bio kompletan.
+
+---
+
+## §4 — Halt-and-PM signali
+
+1. **`CLAUDE.md` već sadrži sekciju "Git Workflow Invariants".** Indicira da je neko drugi već radio sličan amendment — halt-and-PM, treba reconciliation umesto duplikata.
+2. **PR auth fail.** GitHub `gh` CLI ne može da otvori PR — halt-and-PM da Marko proveri PAT.
+3. **Markdown parse error.** Ako linter padne, halt-and-PM sa konkretnom greškom.
+4. **Diff pokazuje uklonjene linije u postojećem `CLAUDE.md`.** Indicira slučajno overwrite — halt-and-PM, ne push.
+5. **Bilo koji error koji nije rate-limit ili auth.** Generalno halt-and-PM po default-u kad signal nije jasan.
+
+---
+
+## §5 — Wall-clock projection
+
+- §1 amendment edit: 5-10 min
+- §1 commit + push + PR: 5 min
+- §3 acceptance verifikacija: 5 min
+- Buffer za halt scenarije: 10-15 min
+
+**Ukupno:** 25-35 min realno, do 45 min sa headroom-om.
+
+**Cost projection:** $1-2 LLM tokens (CC reasoning + git ops + minor lint).
+
+---
+
+## §6 — Post-execution handoff
+
+Posle uspešnog acceptance-a:
+
+1. CC završava sa output-om `PR <broj> awaiting Marko review`.
+2. Marko otvara PR na GitHub-u, čita amendment, mergeuje (ili komentariše).
+3. Posle merge-a, sledeća PM sesija update-uje memoriju da se reflektuje da `CLAUDE.md` sad nosi git workflow invariants kao canonical reference.
+
+---
+
+**END BRIEF.** CC kreće u §1.