Merge pull request #25 from escoffier-labs/feat/bootstrap-budget-doctor

feat: fail oversized bootstrap files

Author: solomonneas

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Built-in `brigade doctor` bootstrap budget checks that fail hard when installed bootstrap files exceed conservative byte limits.
 - `brigade run "<task>"`, a bounded aboyeur flow that asks one rostered orchestrator to plan assignments, dispatches worker CLIs in parallel, then asks the orchestrator to synthesize the final answer.
 - `.brigade/roster.toml` loading for cross-model agent rosters using the user's installed CLIs (`codex`, `claude`, or `ollama:<model>`). Claude is optional, not required.
 - `brigade roster init` and `brigade roster doctor` to scaffold a Codex/Ollama starter roster and validate roster syntax plus installed CLI availability.
@@ -41,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Dogfood handoff defaults now use `.codex/memory-handoffs/` for new Codex-driven local configs while preserving explicit configured inbox paths such as `.claude/memory-handoffs/`.
-- The roadmap now treats memory/bootstrap doctor checks as daily-readiness work, with bootstrap truncation as a hard failure to prevent.
+- Bootstrap truncation is now treated as a hard doctor failure to prevent by moving durable detail into memory cards before agents load context.
 - Dogfood runs now default to a 600 second per-agent timeout for practical daily repo reviews.
 - The managed gitignore block now treats `.brigade/dogfood.toml` and `.brigade/runs/` as local state.
 - Live smoke docs now keep Codex agent execution in a trusted repo cwd while writing temporary roster, artifacts, and handoff output under `/tmp`.

README.md

@@ -168,7 +168,7 @@ Use `--output-dir <path>` to pick the artifact directory, or `--no-artifacts` fo
 
 Use `brigade work status` as the quick daily dashboard for a repo. It reports the current branch, dirty files, dogfood readiness, configured dogfood paths, latest dogfood run, and extracted next step without starting a new orchestration. Use `brigade work doctor` to check whether the repo is ready for the daily loop: dogfood config, Codex CLI, local artifact paths, handoff inbox, ignore coverage, and latest run context. Use `brigade work resume` when returning to a repo; it shows the active or latest work session, latest dogfood run, extracted next step, and the suggested command to continue. `brigade work run` is the one-command daily loop: it starts a work session, runs `brigade dogfood`, ends the session, writes a work-session Memory Handoff by default, and prints a compact recap. Pass a task to override the default next-slice review, `--title` to name the session, `--no-handoff` to skip the work handoff, or `--dogfood-handoff` to also let the underlying dogfood run write its own handoff. `brigade work start "title"` opens a local work session under `.brigade/work/<id>/`, records the starting git and dogfood context, and writes `start.md`. `brigade work note "checkpoint"` appends a timestamped note to the active session without ending it. `brigade work end --note "what happened"` closes the active session, records ending context, and writes `end.md`. Add `--handoff` to also write a Memory Handoff for the closed session; it defaults to the configured dogfood handoff inbox or `.codex/memory-handoffs`.
 
-Memory and bootstrap readiness are part of the same operating-system health story. `brigade doctor` covers installed workspace structure today; the long-term daily-readiness path should include memory/bootstrap checks that fail before bootstrap files are truncated. Bootstrap truncation should be treated as a hard failure, not a cosmetic warning.
+Memory and bootstrap readiness are part of the same operating-system health story. `brigade doctor` checks installed bootstrap files against built-in hard byte budgets so overgrown files fail before agents load truncated context. Bootstrap truncation is treated as a hard failure to prevent, not a cosmetic warning; move durable detail into `memory/cards/` and keep bootstrap files as slim indexes.
 
 Inspect local work sessions with `brigade work list`, `brigade work latest`, or `brigade work show <session-id-or-path>`. Use `brigade work recap` for a compact summary of recent sessions, or add `--since YYYY-MM-DD` for a day-range recap.
 

src/brigade/doctor.py

@@ -15,6 +15,19 @@
 FAIL = "FAIL"
 MANUAL = "MANUAL"
 
+BOOTSTRAP_BUDGETS = {
+    "AGENTS.md": 12_000,
+    "CLAUDE.md": 6_000,
+    "MEMORY.md": 7_000,
+    "TOOLS.md": 10_000,
+    "USER.md": 8_000,
+    "SAFETY_RULES.md": 10_000,
+    "INSTALL_FOR_AGENTS.md": 8_000,
+    "SOUL.md": 8_000,
+    "IDENTITY.md": 4_000,
+    "HEARTBEAT.md": 5_000,
+}
+
 from .station import DoctorContext
 
 
@@ -115,6 +128,35 @@ def _check_workspace_files(target: Path) -> List[CheckResult]:
             results.append((OK, f"bootstrap: {name}", str(path)))
         else:
             results.append((WARN, f"bootstrap: {name}", f"not present at {path}"))
+    results.extend(_check_bootstrap_budgets(target))
+    return results
+
+
+def _check_bootstrap_budgets(target: Path) -> List[CheckResult]:
+    results: List[CheckResult] = []
+    for name, limit in BOOTSTRAP_BUDGETS.items():
+        path = target / name
+        if not path.exists():
+            continue
+        if not path.is_file():
+            results.append((FAIL, f"bootstrap-budget: {name}", f"not a file: {path}"))
+            continue
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            results.append((FAIL, f"bootstrap-budget: {name}", f"unreadable: {exc}"))
+            continue
+        detail = f"{size}/{limit} bytes"
+        if size > limit:
+            results.append(
+                (
+                    FAIL,
+                    f"bootstrap-budget: {name}",
+                    f"{detail}; over hard limit, split durable context into memory/cards before agents load it",
+                )
+            )
+        else:
+            results.append((OK, f"bootstrap-budget: {name}", detail))
     return results
 
 

tests/test_doctor.py

@@ -31,6 +31,35 @@ def test_doctor_reports_failures_on_empty_dir(tmp_target: Path, capsys):
     assert "[fail]" in out
 
 
+def test_doctor_fails_when_bootstrap_file_exceeds_budget(tmp_target: Path, capsys):
+    install_selection(
+        tmp_target,
+        Selection(depth="workspace", harnesses=["claude"], owner="claude", includes=[]),
+    )
+    limit = doctor_mod.BOOTSTRAP_BUDGETS["MEMORY.md"]
+    (tmp_target / "MEMORY.md").write_text("x" * (limit + 1))
+
+    rc = doctor_mod.run(target=tmp_target, harness="generic")
+    out = capsys.readouterr().out
+    assert rc == 1
+    assert "[fail]" in out
+    assert "bootstrap-budget: MEMORY.md" in out
+    assert "over hard limit" in out
+
+
+def test_doctor_reports_bootstrap_budget_ok(tmp_target: Path, capsys):
+    install_selection(
+        tmp_target,
+        Selection(depth="workspace", harnesses=["claude"], owner="claude", includes=[]),
+    )
+
+    rc = doctor_mod.run(target=tmp_target, harness="generic")
+    out = capsys.readouterr().out
+    assert rc == 0
+    assert "bootstrap-budget: AGENTS.md" in out
+    assert "bootstrap-budget: MEMORY.md" in out
+
+
 def test_doctor_openclaw_reports_manual_when_config_missing(tmp_target: Path, monkeypatch, capsys):
     install_selection(
         tmp_target,