Component brain instructions

CLAUDE.md

@@ -1,6 +1,6 @@
 # Mini-Brain Toolkit: Mini-Brain Files
 
-> V13, 2026-07-29.
+> V17, 2026-08-08.
 
 ---
 
@@ -11,12 +11,13 @@ All paths are relative to this repo root (`CLAUDE.md`'s directory). Before readi
 | Purpose | File |
 |---|---|
 | What a mini-brain is — principles, file set, lifecycle | `MBT_PATTERN.md` |
+| Layout convention for a brain whose knowledge divides into several components | `MBT_COMPONENTS.md` |
 | Procedure: create a new mini-brain | `MBT_CREATE_BRAIN.md` |
 | Procedure: check an existing mini-brain against the pattern | `MBT_CHECK_BRAIN.md` |
 | Research agenda — where the pattern could go, and how it compares to related work | `MBT_RESEARCH.md` |
 | Comparable systems — the second-brain / agent-memory landscape (read during the dream cycle's competitive-landscape pass) | `MBT_COMPARABLES.md` |
 | Cognitive-science grounding — biological models the pattern draws on (read during the dream cycle's biological-grounding pass) | `MBT_BIOLOGY.md` |
-| Problem definition, current state, goals | `MBT_SCOPE.md` |
+| Problem definition, the world it exists in, goals | `MBT_SCOPE.md` |
 | Technical approach, key design decisions | `MBT_APPROACH.md` |
 | Key implementation findings (invisible from the files) | `MBT_FINDINGS.md` |
 | Session log — why we chose what we chose | `MBT_LOG.md` (read from last `---`; large) |
@@ -26,7 +27,7 @@ All paths are relative to this repo root (`CLAUDE.md`'s directory). Before readi
 
 Only files in this table are current. `templates/` holds the base files `MBT_CREATE_BRAIN.md` copies; `archive/` holds source material and retired docs — ignore both unless asked.
 
-`working/` holds experiments and a work item's in-flight `<PREFIX>_*` docs. When a work item concludes, fold them into the canonical docs and **move** (not delete) them to `archive/`.
+`working/` holds experiments and a work item's in-flight `MBT_<WORK>_*` docs, where `<WORK>` is the item's slug. When a work item concludes, fold them into the canonical docs and **move** (not delete) them to `archive/`.
 
 ---
 
@@ -52,13 +53,14 @@ Only files in this table are current. `templates/` holds the base files `MBT_CRE
 | `MBT_APPROACH.md` | `MBT_SCOPE.md` only | A design legitimately responds to the problem it addresses — never reaching down into implementation. |
 | `MBT_FINDINGS.md` | *none* | Implementation decisions that did *not* shape the approach — downstream of it, so nothing upstream to cite. |
 | `MBT_PATTERN.md` | *none* | The canonical definition stands alone; it precedes the procedures that enact it and the research that extends it, and reaches down to neither. |
+| `MBT_COMPONENTS.md` | `MBT_PATTERN.md` only | An optional layout layer serves the definition it extends — upstream — and reaches down to no procedure. |
 | `MBT_RESEARCH.md` | *none* | The conclusions the two registries feed upward into; naming them would reach *downstream*, and it needs nothing else. |
 | `MBT_COMPARABLES.md` | `MBT_RESEARCH.md` only | A fact registry serves the conclusions it feeds; it may name that conclusions doc (upstream) and nothing else. |
 | `MBT_BIOLOGY.md` | `MBT_RESEARCH.md` only | Same, for the cognitive-science grounding registry. |
 
 Absent a declared exemption, full orthogonality holds; a different project would declare its own set. A permitted reference still follows the Cross-references rule above — cited by name, never by section number.
 
-**Maintenance-doc boundaries.** `MBT_DREAM_CYCLE.md` and the procedure docs `MBT_CREATE_BRAIN.md` / `MBT_CHECK_BRAIN.md` enact the pattern, so each may cite `MBT_PATTERN.md` as the definition it implements — but they do not reference one another, and naming the knowledge files they operate on is inherent to being a procedure, not a cross-reference. `MBT_SESSION_CLOSEOUT.md` governs the session logs — `MBT_LOG.md` and any open work item's working log — and references nothing else.
+**Maintenance-doc boundaries.** `MBT_DREAM_CYCLE.md` and the procedure docs `MBT_CREATE_BRAIN.md` / `MBT_CHECK_BRAIN.md` enact the pattern, so each may cite `MBT_PATTERN.md` and `MBT_COMPONENTS.md` as the definitions it implements. Any procedure that appends a log entry cites `MBT_SESSION_CLOSEOUT.md` as the entry-format authority; beyond that they do not reference one another, and naming the knowledge files they operate on is inherent to being a procedure, not a cross-reference. `MBT_SESSION_CLOSEOUT.md` governs the session logs — `MBT_LOG.md` and any open work item's working log — and references nothing else.
 
 **No harness memory.** Don't use the persistent memory feature. All persistent project information belongs in the markdown files in this directory.
 

MBT_APPROACH.md

@@ -1,6 +1,6 @@
 # Mini-Brain Toolkit: Technical Approach
 
-> V7, 2026-07-27.
+> V8, 2026-08-08.
 
 This document describes the approach for addressing the problems defined in `MBT_SCOPE.md`. It covers the strategic approach and key design decisions — not delivery sequence.
 
@@ -12,15 +12,15 @@ This document describes the approach for addressing the problems defined in `MBT
 
 The toolkit is itself a mini-brain, and its subject is the mini-brain pattern — exemplifying the pattern it defines is one of the goals in `MBT_SCOPE.md`. This is the load-bearing strategic choice: a toolkit that defined the pattern while not following it would be its own counterexample. Dogfooding makes the repo a worked example a reader can inspect end to end — the read index, the version headers, the append-only log, the orthogonal SCOPE/APPROACH split are all *demonstrated*, not just described — and it is the strongest available test that the templates and procedures are actually usable, because building the toolkit exercised them.
 
-The one wrinkle dogfooding creates is that two kinds of top-level knowledge file coexist: the toolkit's *own* brain (its problem, design, and findings) and the *pattern it defines* as a consumable product (the reference and the two procedures). The read index resolves this by grouping the two in blocks rather than interleaving them.
+The one wrinkle dogfooding creates is that two kinds of top-level knowledge file coexist: the toolkit's *own* brain (its problem, design, and findings) and the *pattern it defines* as a consumable product (the reference documents and the two procedures). The read index resolves this by grouping the two in blocks rather than interleaving them.
 
 ### 1.2 Distill from live exemplars, do not invent
 
 The pattern already works in production brains. The toolkit's job is to *capture* what those brains do, not to design a pattern from first principles. Every template and every procedure step is derived from the ground-truth exemplars — a content-stage brain and a mature brain — so the toolkit inherits conventions that survived real use rather than conventions that sounded good on paper. Where the exemplars carry project-specific detail (test suites, eval numbers, platform splits), the toolkit generalizes it to placeholders while preserving the mechanics that give the convention its value.
 
 ### 1.3 Separate the reference from the procedures
 
-The definition and the two procedures are split into three documents rather than one, matching the three goals in `MBT_SCOPE.md`: a standalone reference that says *what a mini-brain is and why*, and two procedure documents that say *how to build one* and *how to judge one*. A single combined document would be simpler to find, but it would fuse the neutral reference with two opposed procedures. The split mirrors how the live brains separate a standalone reference from action-oriented runbooks, and it pays off in two ways: each document stays small and loads only when its question is being asked, and establishment and assessment — genuinely different activities — don't get tangled in one document. The cost is three files where the reader must know which one they want, mitigated by the grouped read index. The definition lives in the reference alone, cited rather than restated, so it has exactly one home.
+The definition and the two procedures are split into separate documents rather than one, matching the goals in `MBT_SCOPE.md`: a standalone reference that says *what a mini-brain is and why* — a base definition plus an opt-in layout layer for brains whose knowledge divides into components, so a simple brain never loads conventions it doesn't use — and two procedure documents that say *how to build one* and *how to judge one*. A single combined document would be simpler to find, but it would fuse the neutral reference with two opposed procedures. The split mirrors how the live brains separate a standalone reference from action-oriented runbooks, and it pays off in two ways: each document stays small and loads only when its question is being asked, and establishment and assessment — genuinely different activities — don't get tangled in one document. The cost is more files where the reader must know which one they want, mitigated by the grouped read index. Each part of the definition lives in exactly one reference document, cited rather than restated, so it has exactly one home.
 
 ### 1.4 Templates as the single source of truth
 

MBT_CHECK_BRAIN.md

@@ -1,6 +1,6 @@
 # Mini-Brain Toolkit: Check an Existing Mini-Brain
 
-> V8, 2026-07-24.
+> V18, 2026-08-08.
 
 This document is the procedure for evaluating an existing mini-brain against the pattern and surfacing where it could improve — whether the brain was built from this toolkit or grew on its own.
 
@@ -14,6 +14,8 @@ This document is the procedure for evaluating an existing mini-brain against the
 
 Read the target's entrypoint first (`CLAUDE.md` or equivalent), then list the repo top-level and its `archive/`/`working/` dirs. Identify: the namespace token in use, which canonical docs exist, whether there's a session log, and what stage the brain is at (per `MBT_PATTERN.md`: seed / content / mature). Read the canonical docs' first lines (not their full bodies yet) to see version headers and purpose. This is a bounded, low-context pass — save heavy full-file reads for §3.
 
+**If the entrypoint carries a component registry**, the brain uses the component layer described in `MBT_COMPONENTS.md`. Note the hub token and every unit's directory and token, and list each unit's directory rather than the top level alone. Several checks below then run per unit instead of once. A brain with no registry is single-unit and everything runs as written.
+
 If the repo has no entrypoint and no namespaced docs, it may not be a mini-brain — or the path may be wrong. Say so and stop: report that the target doesn't look like a mini-brain, ask the user to confirm the location, and do nothing else — don't score it, and don't scaffold what's missing.
 
 ---
@@ -37,36 +39,44 @@ Walk the ten principles from `MBT_PATTERN.md` one at a time, in order. For each,
 
 Principles 9 and 10 are stage-3 machinery — mark them **not applicable** (not **absent**) for a seed or content-stage brain that legitimately doesn't need them yet. The signal is need, not a checkbox: a brain tracking many work items with no closeout ritual is a real gap; a small single-purpose brain without one is fine.
 
+Score a component-structured brain's principles 5 and 6 against the component layer, not against enumeration. Principle 5 is satisfied when a hub index, a doctype grammar and a registry together resolve every document — not when every document is listed. Principle 6 is satisfied by a token declared per unit, not by one token across the brain.
+
 ---
 
 ## 3. Verify substance, not just structure
 
-Structure can be present while the content rots. Spot-check the two things that decay silently — delegate the read-heavy parts to Explore agents so the active context stays free for judgment:
+Structure can be present while the content rots. Spot-check the things that decay silently — delegate the read-heavy parts to Explore agents so the active context stays free for judgment. The three set-level checks are the exception: a term collision, a duplicated question and a parent's overreach are each invisible to a reader holding one document, so those have to be read together by whoever is judging, not split across agents.
 
 - **SCOPE factual drift.** Pull a handful of falsifiable claims from the scope doc (class/tool/config names, counts, and especially *absence* claims like "no control does X") and check them against the actual codebase. Absence claims break silently when capabilities are added — prioritize them. Report claims that no longer hold.
+- **SCOPE drifted into status.** Find the section describing where things stand — headed "State of the Problem", "Current State" or similar — and ask what it actually describes: the world the problem exists in, or the project's own progress through it. Version numbers, test counts, release status, maturity labels, benchmarks and issue counts are the tell; they belong to the project, not to a problem that exists whether or not anything addresses it. A scope written this way looks well-researched and dates within weeks, so flag it as a rewrite rather than a trim — the content that should be there was never gathered. The heading itself is cosmetic: "Current State" invites the drift and is worth renaming when the section is next touched, but a section under that name whose content is right is not a finding.
 - **Re-derivable content.** Skim the canonical docs for passages that merely restate what the current code plainly shows. These are pruning candidates (principle 1) — the brain would be *more* trustworthy smaller.
+- **One term, one meaning.** Read the canonical documents as a set and watch for a word carrying two jobs — a domain term in one document borrowed as a generic in another. Each reading is defensible alone and the collision shows only side by side, so no single-file check finds it.
+- **Question ownership** (component brains). An open question belongs to exactly one unit: the one whose work would resolve it. The same question standing in a parent and a child means neither owns it, and the copies drift as the answer develops.
+- **Parent overreach** (component brains). A parent names what a child elaborates and stops. Where a parent explains *why* a child's problem is hard, or how it is solved, in its own words, that explanation belongs to the child — the tell is a passage equally at home in either document.
+- **Shape.** Ask of each unit whether its SCOPE still states one problem, or whether writing it honestly today would force two onto the page. A brain that should have split is internally consistent either way, so no structural check can see it; the tell is a unit that authored one target's documents first and ported a second against them.
 
 Also run the structural checks below; they're mechanical and catch the cheap, common failures.
 
 ### Structural checks
 
-1. **Read index ↔ disk** — every file in the read index exists; no top-level knowledge file is missing from the index (orphans).
+1. **Read index ↔ disk** — every file in the read index exists; no top-level knowledge file is missing from the index (orphans). *Component brain:* run that against the hub index and the hub's documents, then check the registry against disk both ways — every registered unit has a directory, every unit directory is registered, at every depth — and check grammar conformance: every unit carries the full doctype set, and any document beyond it appears in that unit's **Also holds** cell or its local index.
 2. **Version headers** — every canonical doc (except the exempt `*_LOG.md` / `*_TASKS.md`) opens with a well-formed `> V<N>, YYYY-MM-DD.` and no smuggled change-note.
-3. **Cross-references** — every mini-brain filename mentioned resolves to a current top-level file, not an `archive/` copy or a deleted file.
-4. **Namespace prefix** — every top-level knowledge file carries the namespace token (`ls *.md | grep -vE '^(CLAUDE|README)\.md$' | grep -v <PREFIX>` should return nothing).
+3. **Cross-references** — every mini-brain filename mentioned resolves to a current canonical file, not an `archive/` copy or a deleted file. *Component brain:* resolve against the unit that owns the token, not the repo root.
+4. **Namespace prefix** — every top-level knowledge file and every `working/` doc carries the namespace token (`find . working -maxdepth 1 -name '*.md' 2>/dev/null | grep -vE '/(CLAUDE|README)\.md$' | grep -v '/<PREFIX>_'` should print nothing — it tolerates a missing or empty `working/` and anchors the token to the start of the filename). *Component brain:* run it per unit against that unit's declared token, over the unit's own documents and its `working/` — never its `archive/`, where retired files legitimately keep the basename they were retired under and need not be markdown. Match the token exactly: a document belongs to the unit whose token its name begins with in full, longest match winning. Tokens nest as prefixes (`ORCHARD` inside `ORCHARD_PRESS`), so the prefix test above silently accepts a child's document sitting in its parent's directory. A brain seeded before working docs carried the brain token names its in-flight docs `working/<WORK>_*` by the then-current convention — treat that as adopt-when-touched guidance, not a violation, since renaming a live item's docs breaks the routing signals that match on those names.
 5. **Log discipline** — the session log is append-only and readable from its last separator (not required to be read whole); entries carry a date and session identifier.
+6. **Unit references** (component brains) — cross-unit references stay within the entrypoint's declared exemptions: a component's SCOPE may cite its parent's SCOPE, its APPROACH its parent's APPROACH, and any document may name its own sub-components — never their files. Any other reference to another unit or its files is a violation, sibling references above all. Logs and maintenance documents are exempt — a log records what a session touched, and a procedure names the files it operates on.
 
 ---
 
 ## 4. Report
 
 Produce a written assessment. Structure it:
 
-- **Summary** — the brain's stage, its namespace, and a one-line overall read (what kind of shape it's in).
+- **Summary** — the brain's stage, its namespace (or its unit tree and per-unit tokens, if component-structured), and a one-line overall read (what kind of shape it's in).
 - **What's working** — the principles it embodies well. Lead here.
 - **Principle scorecard** — the table from §2 with each verdict and note.
 - **Structural findings** — anything the §3 checks flagged, most-actionable first.
-- **Substance findings** — drifted SCOPE claims and pruning candidates, if any.
+- **Substance findings** — drifted SCOPE claims, a scope that has become a status report, cross-document inconsistencies, a unit whose scope no longer states one problem, and pruning candidates, if any.
 - **Recommended next steps** — ranked, concrete opportunities. Frame each as "this brain does X well but Y would help because …", tied to a principle. If a step is "adopt lifecycle machinery," name the specific machinery and point at the relevant `templates/` file.
 
 Keep it proportionate: a healthy brain gets a short report that says so. Reserve length for real, actionable gaps.