# PROJECT-WORKFLOW.md — Commits, Reports, and README Updates

**Binding for all agents working this repo.**  
Read alongside `.cursor/AGENTS.md` and `.cursor/BUILD-PLAN.md`.

**Last updated:** 2026-07-10

---

## Overview

Three rituals keep this research repo auditable and reproducible:

| Ritual | When | Output |
|--------|------|--------|
| **Commit** | After each logical module or phase milestone | Conventional Commits on `master` |
| **Progress report** | After each **large** milestone (phase complete, major eval run, go/no-go attempt) | `report/YYYY-MM-DD-<slug>.md` + update `report/README.md` |
| **README results update** | After each **validated** result (passed GATE, credible ablation, certificate with evidence) | Update root `README.md` with figures, metrics, replication steps |

Do not skip reports for large progress. Do not add unvalidated numbers to the public README.

---

## 1. Git commit workflow

### When to commit

Commit when the user asks, or when you finish a **logical unit of work**:

- One BUILD-PLAN commit block (e.g. A2 config, C1 surgery)
- A phase-grouped batch (e.g. all Phase B files)
- A bugfix or doc update that stands alone
- A validated result + its report + README update (single commit or small sequence)

**Do not** create empty commits. **Do not** commit `results/` adapter weights or large binaries (gitignored).

### Commit message format (Conventional Commits)

```
<type>(<scope>): <imperative summary ≤ 72 chars>

<optional body — what and why, not file list>
```

| Type | Use for |
|------|---------|
| `feat` | New capability (module, script, eval) |
| `fix` | Bug fix |
| `test` | Tests only |
| `docs` | README, report, paper, `.cursor/` docs |
| `chore` | Configs, deps, tooling |
| `refactor` | No behavior change |

**Scope examples:** `carve`, `stats`, `gate`, `synthetic`, `eval`, `infra`, `oss`, `plan`

**Do not** add `Co-authored-by: Cursor` or similar trailers unless the user requests it.

### Phase-grouped commit sequence

Follow `.cursor/BUILD-PLAN.md` commit messages when implementing. Group by phase when batching:

```
docs(plan): ...
fix(cursor): ...
feat(infra): Phase A — ...
feat(synthetic): Phase B — ...
feat(carve): Phase C — ...
feat(gate): Phase D — ...
feat(eval): Phase E — ...
chore(configs): ...
docs(oss): ...
docs(report): YYYY-MM-DD progress report
docs(readme): add validated Syn-2Cap results and figures
```

### Windows / GPG signing

This machine may hang on GPG/passkey signing. **Always use:**

```powershell
git add <files>
git -c commit.gpgsign=false commit -m "feat(carve): summary" -m "Optional body line."
```

PowerShell does not support bash heredocs. Use multiple `-m` flags for body paragraphs.

### Pre-commit checklist

```
[ ] git status — only intended files staged
[ ] pytest tests/ -q (or relevant subset) passes
[ ] No secrets, .env, or results/*.safetensors staged
[ ] Commit message matches Conventional Commits
[ ] If large milestone: progress report written (see §2)
[ ] If validated result: README updated (see §3)
```

### Push

Only push when the user explicitly asks. Suggested remote repo name: `carve-lora`.

---

## 2. Progress report workflow

### Trigger — write a report after **large progress**

Examples of large progress:

- Phase A–H milestone completed
- Full `run_full_eval.py` or Syn-2Cap go/no-go run finished
- First real LLM end-to-end CARVE run (pass or fail)
- Founder OS or TOFU/WMDP eval completed
- Major refactor or algorithm change

**Do not** write a report for every small commit or trivial fix.

### File naming

```
report/YYYY-MM-DD-<short-slug>.md
```

Examples:

- `report/2026-07-10-project-progress-report.md`
- `report/2026-07-15-syn2cap-qwen-go-no-go.md`
- `report/2026-07-22-founder-os-adapter-run.md`

### Report template

Copy structure from `report/TEMPLATE-progress-report.md`. Every report must include:

1. **Executive summary** (3–5 sentences)
2. **What was done** (commits, modules, runs)
3. **Test status** (`pytest` count)
4. **Eval / metrics** (FE, RF, US, GATE decision) — label proxy vs behavioral
5. **Artifacts** (paths under `results/` and `report/assets/`)
6. **What went right / wrong**
7. **Phase completion table** (vs BUILD-PLAN)
8. **Next steps** (ordered)

### Figures and data

- Copy **small** plots (PNG/SVG) from `results/` into `report/assets/` with dated names: `report/assets/<metric>_<run_id>.png`
- Reference gitignored raw data by path only; do not commit large tensors
- Tables of metrics may live inline in the report markdown

### Update `report/README.md`

After each new report, add a row to the index table:

```markdown
| [2026-07-15 Syn-2Cap Go/No-Go](./2026-07-15-syn2cap-qwen-go-no-go.md) | 2026-07-15 | Qwen2.5-1.5B 4-bit; FE/RF on held-out |
```

Keep the table sorted **newest first**.

### Commit the report

```powershell
git add report/
git -c commit.gpgsign=false commit -m "docs(report): add 2026-07-15 Syn-2Cap go/no-go report" -m "Phase C gate attempt on Qwen2.5-1.5B; FE/RF held-out metrics."
```

---

## 3. README results update workflow

### Trigger — update root `README.md` after **validated** results only

A result is **validated** when at least one applies:

- GATE decision `PROMOTE` on held-out probes (FE≥0.90, RF≥0.95, US≥0.98)
- Syn-2Cap go/no-go **passed** with behavioral metrics (not norm proxy)
- Separability certificate with reproduced commands (diagnostic-only is OK for § Results)
- Ablation showing CARVE Pareto-dominates Maat-SVD at matched cut budget
- Published replication package for a specific model/config

**Do not** put mock-model or `_perf_sim` proxy metrics in README as if they were real results. Label proxies clearly if mentioned at all.

### What to add to README

Use the **Results** section in root `README.md` (maintain chronologically, newest on top):

For each validated result block include:

1. **Title + date + run ID**
2. **One-line conclusion**
3. **Metrics table** (FE, RF, US, GATE decision)
4. **Figure(s)** from `report/assets/` — commit images, do not hotlink gitignored `results/`
5. **Architecture or pipeline diagram** (mermaid) if the result changes understanding
6. **Replicate this result** — exact commands, config path, hardware notes

Example block structure:

```markdown
### 2026-07-15 — Syn-2Cap go/no-go on Qwen2.5-1.5B (run: syn2cap_20260715)

| Metric | Value | Target | Pass |
|--------|-------|--------|------|
| FE | 0.92 | ≥0.90 | ✅ |
| RF | 0.96 | ≥0.95 | ✅ |

![Eigenvalue spectrum](report/assets/spectrum_syn2cap_20260715.png)

**Replicate:**
\`\`\`bash
pip install -e ".[dev]"
python scripts/run_carve.py --config configs/syn2cap_1.5b.yaml ...
pytest tests/test_synthetic_e2e.py -m gpu -v
\`\`\`
```

### Diagrams

- **Pipeline / architecture:** mermaid in README (no external deps)
- **Plots:** PNG in `report/assets/`, referenced from README
- **Ablation tables:** markdown tables; link to full `results/<run_id>/report.md` for detail

### Replication instructions

- Short path: inline under each result block in README
- Full path: extend `REPRODUCE.md` with a new section per major result
- Always include: install, config file, command, expected metric ranges, GPU/RAM requirements

### Commit README updates

```powershell
git add README.md REPRODUCE.md report/assets/
git -c commit.gpgsign=false commit -m "docs(readme): add validated Syn-2Cap Qwen results and spectrum figure"
```

---

## 4. End-to-end agent checklist (large milestone)

```
1. Implement / run experiment
2. pytest (and GPU tests if applicable)
3. Save artifacts → results/<run_id>/
4. Copy figures → report/assets/
5. Write report/YYYY-MM-DD-<slug>.md
6. Update report/README.md index
7. If validated → update README.md Results + REPRODUCE.md
8. Phase-grouped git commit(s) with --no-gpg-sign
9. Tell user: commit hash, report path, GATE decision
```

---

## 5. Quality gates (reminder)

| Gate | Condition | Report type |
|------|-----------|-------------|
| Phase complete | All BUILD-PLAN acceptance tests pass | Progress report |
| Phase C go/no-go | FE≥0.90, RF≥0.95, CARVE > Maat-SVD | Go/no-go report + README |
| GATE PROMOTE | Held-out verify passes | README results block |
| GATE RETRY/FAIL | Document honestly | Report only; no README hype |
| Flat λ spectrum | Certificate emitted | README may note "inseparable" + recommendation |

---

## 6. Related files

| File | Role |
|------|------|
| `.cursor/BUILD-PLAN.md` | Phase commit messages and acceptance tests |
| `.cursor/AGENTS.md` | Project structure and algorithm decision |
| `.cursor/claude.md` | Implementation details |
| `report/TEMPLATE-progress-report.md` | Copy for new reports |
| `report/README.md` | Report index |
| `REPRODUCE.md` | Full replication guide |
| `README.md` | Public face — validated results only |