# CC Brief — CLAUDE.md Amendment: Code-Level Invariants > [!CAUTION] > **ARCHIVED / SUPERSEDED — DO NOT EXECUTE.** This brief predates `AGENTS.md` > as the sole operating contract. Its raw subtree/export publication guidance > is invalid; use `AGENTS.md` §7.5 and the curated-forward-port workflow. **Brief ID:** `cc-claude-md-amendment-invariants-v1` **Date:** 2026-05-05 **Author:** PM **Status:** ARCHIVED / SUPERSEDED (was READY and ratified 2026-05-05 under the superseded model) **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`) 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 > **CORRECTION (2026-08-22):** Raw `oss-hive-mind-*-export` refs are local > inspection artifacts only and must never be published. Author changes in the > private monorepo, run the fail-closed drift check, and prepare a reviewed > maintainer-curated forward-port in the OSS checkout. The historical text > below is retained only to explain the superseded decision. 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 ` or `git log --oneline -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 `-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/-.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: Brief reference: Recommended PM action: author decisions/-.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 Reason: Evidence: Risk if proceed: Recommended action: ``` 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 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.