219 lines
12 KiB
Markdown
219 lines
12 KiB
Markdown
# 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<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
|
||
|
||
> **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 <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.
|