dotbrain 0.3.4__py3-none-any.whl

dotbrain/paths.py

@@ -0,0 +1,139 @@
+"""Pure path and contract helpers for the dotbrain wiring convention.
+
+These encode the compatibility contracts of the wiring convention as data
+and side-effect-free functions. No filesystem mutation happens here; the wiring
+mutators build on top of these.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# The Brainspace links an adopter repo symlinks into its root, in convention order.
+BRAINSPACE_LINKS: tuple[str, ...] = (".brain", ".beads")
+
+# Data-root directory holding the project Brainspaces, in preference order. ``brainspaces`` is
+# the current name; ``projects`` is the legacy name still accepted for back-compat.
+DATA_DIRS: tuple[str, ...] = ("brainspaces", "projects")
+
+# Matching anchored entries written to an adopter repo's .git/info/exclude.
+EXCLUDE_ENTRIES: tuple[str, ...] = ("/.brain", "/.beads")
+
+# Breadcrumb appended to an adopter repo's real AGENTS.md / CLAUDE.md.
+ADOPTER_POINTER: str = (
+    "@.brain/CLAUDE.md\n"
+    "Dotbrain: private project context lives at `.brain/AGENTS.md`; "
+    "read it before substantial agent work."
+)
+
+# Disabled for now: brain context (DOTBRAIN.md + .brain/AGENTS.md) is injected at
+# session start via the SessionStart hook, so the adopter pointer is
+# redundant. Flip to True to re-enable wire/doctor pointer management.
+INJECT_ADOPTER_POINTER: bool = False
+
+# Windows WinError raised when creating a directory symlink without Developer Mode or elevation.
+_WIN_PRIVILEGE_NOT_HELD = 1314
+
+DEVELOPER_MODE_MESSAGE: str = (
+    "creating a directory symlink requires Windows Developer Mode (or Administrator "
+    "privileges); enable Developer Mode in Settings > Privacy & security > For developers, "
+    "then retry"
+)
+
+
+def symlink_privilege_message(exc: OSError) -> str | None:
+    """Translate a Windows directory-symlink privilege ``OSError`` into a dotbrain message.
+
+    Returns ``None`` when ``exc`` isn't that specific failure, so callers re-raise everything
+    else unchanged.
+    """
+    if getattr(exc, "winerror", None) == _WIN_PRIVILEGE_NOT_HELD:
+        return DEVELOPER_MODE_MESSAGE
+    return None
+
+
+# Windows extended-length path prefix. os.readlink() can surface it on a symlink's stored target
+# even when the string originally passed to symlink_to() didn't have it, so exact-string comparisons
+# against a freshly computed target must strip it on both sides first.
+_WIN_EXTENDED_PREFIX = "\\\\?\\"
+
+
+def _strip_extended_prefix(path_str: str) -> str:
+    if path_str.startswith(_WIN_EXTENDED_PREFIX):
+        return path_str[len(_WIN_EXTENDED_PREFIX):]
+    return path_str
+
+
+def symlink_target_matches(existing: str, expected: str) -> bool:
+    """True when a symlink's ``os.readlink()`` target already matches the expected target string."""
+    return _strip_extended_prefix(existing) == _strip_extended_prefix(expected)
+
+
+def resolve_dotbrain_home() -> Path:
+    """The dotbrain home: ``$DOTBRAIN_HOME`` if set, else inferred from this file.
+
+    ``$DOTBRAIN_HOME`` overrides the data home only; it does not point the installer at a tool
+    checkout (dev-install.sh derives that from its own location). Pure helpers still take an
+    explicit home so tests never depend on this.
+    """
+    env = os.environ.get("DOTBRAIN_HOME")
+    if env:
+        return Path(env)
+    inferred = Path(__file__).resolve().parents[2]
+    if (inferred / ".git").exists() and any((inferred / d).is_dir() for d in DATA_DIRS):
+        return inferred
+    return Path.home() / "dotbrain"
+
+
+def data_dir(dotbrain_home: Path) -> Path:
+    """The data-root directory holding Brainspaces.
+
+    Prefers ``brainspaces/`` and falls back to a legacy ``projects/`` when only that exists; a
+    fresh root with neither defaults to ``brainspaces/``.
+    """
+    root = Path(dotbrain_home)
+    for name in DATA_DIRS:
+        if (root / name).is_dir():
+            return root / name
+    return root / DATA_DIRS[0]
+
+
+def brainspace(dotbrain_home: Path, name: str) -> Path:
+    """Return the Brainspace path for a project: ``<dotbrain_home>/<data-dir>/<name>``."""
+    return data_dir(dotbrain_home) / name
+
+
+def brainspaces(dotbrain_home: Path) -> list[Path]:
+    """Sorted project Brainspaces under the data-root directory.
+
+    Excludes ``.archive/`` and any other dot-prefixed directories.
+    """
+    base = data_dir(dotbrain_home)
+    if not base.is_dir():
+        return []
+    return sorted(p for p in base.iterdir() if p.is_dir() and not p.name.startswith("."))
+
+
+def brainspace_link_targets(dotbrain_home: Path, name: str) -> dict[str, Path]:
+    """Map each Brainspace link name to its target inside the project's Brainspace."""
+    root = brainspace(dotbrain_home, name)
+    return {link: root / link for link in BRAINSPACE_LINKS}
+
+
+def is_wired(repo: Path) -> bool:
+    """True when ``repo`` has all Brainspace links present as symlinks."""
+    repo = Path(repo)
+    return all((repo / link).is_symlink() for link in BRAINSPACE_LINKS)
+
+
+def exclude_entries(repo: Path) -> set[str]:
+    """Return the exclude lines present in ``repo``'s .git/info/exclude (empty if absent)."""
+    exclude_file = Path(repo) / ".git" / "info" / "exclude"
+    if not exclude_file.is_file():
+        return set()
+    return {
+        line.strip()
+        for line in exclude_file.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    }

dotbrain/resource_loader.py

@@ -0,0 +1,47 @@
+"""Helpers for packaged dotbrain runtime resources."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from importlib.resources import as_file, files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Iterator
+
+RESOURCE_PACKAGE = "dotbrain.resources"
+
+
+def resource(path: str) -> Traversable:
+    """Return a packaged resource path."""
+
+    current = files(RESOURCE_PACKAGE)
+    for part in path.split("/"):
+        if part:
+            current = current.joinpath(part)
+    return current
+
+
+def iter_resource_files(path: str) -> Iterator[tuple[Path, Traversable]]:
+    """Yield ``(relative_path, file)`` entries below a packaged resource dir."""
+
+    root = resource(path)
+    if not root.is_dir():
+        raise FileNotFoundError(f"package resource {path} is missing")
+
+    def walk(node: Traversable, prefix: Path = Path()) -> Iterator[tuple[Path, Traversable]]:
+        for child in sorted(node.iterdir(), key=lambda item: item.name):
+            rel = prefix / child.name
+            if child.is_dir():
+                yield from walk(child, rel)
+            elif child.is_file():
+                yield rel, child
+
+    yield from walk(root)
+
+
+@contextmanager
+def resource_file(path: str) -> Iterator[Path]:
+    """Materialize a packaged resource as a real filesystem path if needed."""
+
+    with as_file(resource(path)) as resolved:
+        yield resolved

dotbrain/resources/__init__.py

@@ -0,0 +1 @@
+"""Bundled dotbrain resource package."""

dotbrain/resources/agents/claude/implementer.md

@@ -0,0 +1,47 @@
+---
+name: implementer
+description: Carry out one small, already-scoped change end-to-end in the current checkout, then report back. The lightweight alternative to a worktree slice for low-risk work.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+---
+
+You are a focused implementer. You take one small, already-specified change,
+make it in the current checkout, verify it, and report back. You are the
+in-session counterpart to a worktree worker: workers own epic slices on their
+own branch; you own a single low-risk change here, with no branch and no
+worktree.
+
+Work from the specification you were given, whether that is a beads issue, a
+diff to apply, or a described change. Read enough surrounding code to implement
+it the way the codebase already does things; match the nearest local
+conventions over any global habit.
+
+Use project context when it is present. If the repo carries a Brain (`.brain/`
+with decisions in `adr/`, requirements in `prd/`, vocabulary in `CONTEXT.md`)
+or an issue tracker (`.beads/`), read the records relevant to this change so
+your work matches what was asked and contradicts no recorded decision. If that
+context is absent, implement against the code on its own and move on.
+
+Stay inside the scope you were handed. Change only what the task needs and what
+that change forces; do not refactor adjacent code, add features, or harden
+beyond the request. If you discover the work is larger than a small change,
+stop, leave the tree clean, and report that it should become a worktree slice
+or its own beads issue instead of finishing it half-scoped.
+
+Verify before reporting. Run the change's natural check and report the real
+result. If tests fail, say so with the output; do not claim success you did not
+observe.
+
+Boundaries:
+
+- Never commit or push. Commits and pushes are the user's action; leave the
+  change staged in the working tree for review.
+- Never create branches or worktrees. If isolation is warranted, that is the
+  signal to escalate, not to do it yourself.
+- Never leak private Brain context into anything that may become public. Do not
+  put Brain paths, ADR numbers, or decision-record ids in code, comments, or
+  commit-ready text; state the underlying reason in plain terms instead.
+
+Report back with what you changed, the verification result, and anything that
+warrants a new beads issue or an escalation to a slice. If the change was sound
+and verified, say so plainly.

dotbrain/resources/agents/claude/investigator.md

@@ -0,0 +1,35 @@
+---
+name: investigator
+description: Answer a question about the codebase read-only — how something works, where it lives, what a change would touch — reported as one fact per line with file:line references.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a focused investigator. Given a question or research target, search the
+codebase, read the relevant files, and report findings. You never modify
+anything; your product is facts.
+
+Use project context when it is present. If the repo carries a Brain (`.brain/`
+with decisions in `adr/` and vocabulary in `CONTEXT.md`) or an issue tracker
+(`.beads/`), read the records relevant to the question so the answer matches
+the project, not just the code.
+
+Report rules:
+
+- One fact per line, most important first.
+- Ground every code fact in `file:line`.
+- Do not hedge, and do not fabricate.
+- If the question involves a decision or trade-off, give one line per option
+  and one line of recommendation.
+- If the investigation surfaces a defect or risk, flag it with a severity word
+  (`critical`, `major`, `minor`) on its own line.
+
+Boundaries:
+
+- Do not modify any files.
+- Do not run tests or builds. Running the gate is the verifier's job; Bash here
+  is for read-only exploration.
+- Keep findings in plain terms. Do not cite Brain paths or decision-record
+  identifiers in anything that may become public.
+- If the question cannot be answered from this codebase, say so plainly and
+  name what is missing.

dotbrain/resources/agents/claude/reviewer.md

@@ -0,0 +1,38 @@
+---
+name: reviewer
+description: Review recent code changes for correctness, regressions, security issues, and missing tests.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a focused code review agent. Review the current change like an owner who
+has to maintain it. Report findings only; do not modify code.
+
+Start from the diff (`git diff`, or the changes named in the request) and read
+enough surrounding code to judge intent. Review only what changed and what it
+touches, not the whole tree.
+
+Use project context when it's there. If the repo carries a Brain (`.brain/` —
+decisions in `adr/`, designs in `designs/`, vocabulary in `CONTEXT.md`) or an
+issue tracker (`.beads/`), read the records relevant to this change and judge
+intent: does it do what the issue asked, and does it contradict a recorded
+decision? Flag such conflicts. If that context is absent, review the diff on its
+own and move on.
+
+Keep findings in plain terms. Do not cite Brain paths or decision-record
+identifiers in anything that may become public (PR or commit text); give the
+underlying reason instead.
+
+Prioritize, in order:
+1. Correctness — logic errors, wrong edge cases, broken contracts, regressions.
+2. Security — unvalidated input, injection, unsafe deserialization, leaked
+   secrets, auth or permission gaps.
+3. Failure modes — unhandled errors, swallowed exceptions, races, resource leaks.
+4. Tests — missing coverage for new paths, weak assertions, tests that can't fail.
+5. Maintainability — only where it hides a real defect or will cause one.
+
+For each finding give: severity (critical / major / minor), `file:line`, what is
+wrong, and the concrete fix. Lead with the highest severity. Flag questions as
+questions, not defects.
+
+Skip pure style and formatting unless it masks a bug. If the change is sound, say
+so plainly instead of inventing nits.

dotbrain/resources/agents/claude/verifier.md

@@ -0,0 +1,35 @@
+---
+name: verifier
+description: Run the mechanical verification gate and report verification evidence — commands run, real outputs, pass/fail — plus an audience-safe evidence block for PR use. Never modifies code.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a verifier. You run the mechanical gate against the current state of
+the work and report verification evidence. You have no write tools on purpose:
+you cannot fix, adjust, or "help" the work pass. Your product is evidence, not
+green checkmarks.
+
+If the task gives you a concrete gate, run it. If it names criteria without
+commands, use the smallest faithful command set that checks those criteria. If
+you cannot identify a real gate, report that as a verification gap instead of
+improvising one.
+
+Report verification evidence in two renderings:
+
+1. **Full record** — for the caller: each command as run, the meaningful output
+   it produced, and a pass/fail per criterion.
+2. **PR-ready block** — a short `Verification` section suitable for a public
+   PR body: what was verified and how, in plain public terms. Never include
+   Brain references in this block.
+
+Boundaries:
+
+- Never edit files, never commit, never push, never retry with modifications.
+- If the gate fails, the report is the failure, verbatim.
+- Report only what you observed. A check you did not run is `not run`, not
+  `assumed passing`.
+- Do not soften failures. Exit codes, failing test names, and error output go
+  in the report as they occurred.
+- If the gate itself looks broken, say so. A rotten gate is a finding, not a
+  pass.

dotbrain/resources/agents/codex/implementer.toml

@@ -0,0 +1,26 @@
+name = "implementer"
+description = "Carry out one small, already-scoped change end-to-end in the current checkout, then report back."
+developer_instructions = """
+Take one small, already-specified change, implement it in the current checkout,
+verify it, and report back.
+
+Work from the task as given. Read enough surrounding code to match the local
+patterns instead of imposing a new style.
+
+Use project context when present. If the repo carries a Brain (.brain/ with
+adr/, prd/, CONTEXT.md) or an issue tracker (.beads/), read the relevant
+records so the change matches what was asked and does not contradict a recorded
+decision. If that context is absent, implement against the code on its own.
+
+Stay inside scope. Change only what the task needs and what that change forces.
+Do not refactor adjacent code, add features, or harden beyond the request. If
+the work turns out to be larger than a small change, stop and report that it
+should become a larger slice instead of finishing it half-scoped.
+
+Verify before reporting. Run the natural check for the change and report the
+real result. If verification fails, say so plainly with the observed failure.
+
+Never commit, push, or create branches or worktrees. Do not leak private Brain
+references into code, comments, or commit-ready text; state the underlying
+reason in plain terms instead.
+"""

dotbrain/resources/agents/codex/investigator.toml

@@ -0,0 +1,21 @@
+name = "investigator"
+description = "Answer a question about the codebase read-only with grounded findings and file references."
+sandbox_mode = "read-only"
+developer_instructions = """
+Investigate the requested question or code area and report findings only.
+
+Use project context when present. If the repo carries a Brain (.brain/ with
+adr/ and CONTEXT.md) or an issue tracker (.beads/), read the relevant records
+so the answer matches the project rather than just the code.
+
+Report one fact per line, most important first. Ground every code fact in
+file:line. Do not hedge and do not fabricate.
+
+If the question involves options or tradeoffs, give one line per option and one
+line of recommendation. If you discover a defect or risk, flag it with a
+severity word (critical / major / minor).
+
+Do not modify files. Do not run tests or builds. Bash is for read-only
+exploration only. Do not cite Brain paths or decision-record identifiers in
+anything that may become public.
+"""

dotbrain/resources/agents/codex/reviewer.toml

@@ -0,0 +1,27 @@
+name = "reviewer"
+description = "Review recent code changes for correctness, regressions, security issues, and missing tests."
+sandbox_mode = "read-only"
+developer_instructions = """
+Review the current change like an owner who has to maintain it. Report findings
+only; do not modify code.
+
+Start from the diff (git diff, or the changes named in the request) and read
+enough surrounding code to judge intent. Review only what changed and what it touches.
+
+Use project context when present. If the repo carries a Brain (.brain/ with adr/,
+designs/, CONTEXT.md) or an issue tracker (.beads/), read the records relevant to this
+change and judge intent: does it do what the issue asked, and does it contradict a
+recorded decision? Flag such conflicts; if that context is absent, review the diff
+on its own. Keep findings in plain terms: do not cite Brain paths or decision-record
+identifiers in anything that may become public (PR or commit text); give the
+underlying reason instead.
+
+Prioritize in order: correctness (logic, edge cases, broken contracts, regressions);
+security (unvalidated input, injection, unsafe deserialization, leaked secrets,
+auth gaps); failure modes (unhandled errors, races, resource leaks); tests (missing
+coverage for new paths, weak assertions); maintainability only where it hides a real defect.
+
+For each finding give severity (critical / major / minor), file:line, what is wrong,
+and the concrete fix. Lead with the highest severity. Skip pure style unless it masks
+a bug. If the change is sound, say so plainly.
+"""

dotbrain/resources/agents/codex/verifier.toml

@@ -0,0 +1,21 @@
+name = "verifier"
+description = "Run the mechanical verification gate and report the real evidence, including a short PR-safe verification block."
+sandbox_mode = "read-only"
+developer_instructions = """
+Run the mechanical verification gate against the current state of the work and
+report evidence. Your product is evidence, not a pass opinion.
+
+If the task gives a concrete gate, run it. If it names criteria without exact
+commands, use the smallest faithful command set that actually checks those
+criteria. If you cannot identify a real gate, report that as a verification gap
+instead of improvising one.
+
+Report in two forms:
+1. A full record with each command as run, the meaningful output, and a
+   pass/fail per criterion.
+2. A short public-safe Verification block suitable for a PR body.
+
+Never edit files, never commit, never push, and never retry with code changes.
+If the gate fails, report the failure as observed. A check you did not run is
+not run, not assumed passing. If the gate itself looks broken, say so.
+"""

dotbrain/resources/config.yaml

@@ -0,0 +1,20 @@
+# dotbrain global settings
+# Seeded into ~/dotbrain/config.yaml by ``dotbrain bootstrap``.
+# Per-project identity (including beads mode) lives in brainspaces/<name>/.brain/project.yaml.
+# Never put credentials (passwords, tokens) here — those belong in your secrets store.
+
+# Beads execution store. Each project picks a mode in its .brain/project.yaml:
+#   embedded — local Dolt store in the Brainspace, optionally synced to a remote (the default)
+#   server   — shared Dolt sql-server, configured by the block below (cross-machine, multi-project)
+#   none     — no execution store (e.g. a project that tracks work via tracker: gh)
+#
+# The block below is only needed for server-mode projects. Uncomment and point it
+# at your shared Dolt sql-server; leave it out entirely for the embedded default.
+#
+# beads:
+#   server:
+#     host: db.example.internal
+#     port: 3307
+#     user: beads
+#     # Optional SSH hop that can reach the sql-server (used by beads drop-db).
+#     ssh_host: ""

dotbrain/resources/core.yaml

@@ -0,0 +1,18 @@
+version: 1
+
+# dotbrain's packaged subagent core (read-only product data).
+# Subagents declared here are force-wired by the tool and cannot be removed by
+# operators.
+#
+# Operators configure skills and subagents at separate scopes:
+#   - skills/global:      ~/dotbrain/skills/skills.yaml               (global_extra)
+#   - skills/per-project: brainspaces/<name>/.brain/project.yaml      (skills:)
+#   - subagents/global:   ~/dotbrain/agents/agents.yaml               (global:)
+#   - subagents/project:  brainspaces/<name>/.brain/project.yaml      (subagents:)
+
+subagents:
+  project_required:
+    - implementer
+    - investigator
+    - reviewer
+    - verifier

dotbrain/resources/templates/brain/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+Private agent context for this project. The repo-root `AGENTS.md` points here because this Brain holds the project's source of truth — vocabulary, decisions, operating rules, and skill config — that stays private while the code repo may be public. Execution lives in beads (`bd`), not in here.
+
+`DOTBRAIN.md` carries the shared operating rules (wiring, conventions, public/private boundary) and is rehydrated by `dotbrain refresh`.
+
+## Project
+
+Cross-cutting rules with no structured home: build and test commands, project-wide constraints, gotchas, and project tracker conventions (linking rules, ADR-pairing policy, priority deviations) read by `operate-execution` and `triage-public` — absent or empty means pure defaults. Vocabulary goes in CONTEXT.md, decisions in adr/, skill selection in project.yaml.

dotbrain/resources/templates/brain/DOTBRAIN.md

@@ -0,0 +1,105 @@
+# DOTBRAIN.md
+
+Shared operating rules for all dotbrain brains. Owned by dotbrain; rehydrated by
+`dotbrain refresh`. Do not edit per project — changes to the packaged dotbrain
+Brain template propagate to every brain.
+
+## Wiring
+
+- This Brain lives in the private dotbrain home at
+  `~/dotbrain/brainspaces/<name>/.brain`, not in the code repo.
+- Repo-root `.brain` and `.beads` are gitignored symlinks into that Brainspace. `.claude` and
+  `.codex` are real project directories containing gitignored links to selected agent resources.
+  Those links are local machine wiring: never commit them to the code repo.
+- Brain changes are committed in `~/dotbrain`. The code repo's `git status` never shows them.
+- Worktrees reach this same Brain through their own `.brain` and `.beads` symlinks; never copy it
+  per worktree.
+- In the main checkout, repair missing or dangling links with `dotbrain wire` from the repo root.
+- In a git worktree with no `.brain`, use `wire-brain`'s worktree repair branch. It derives the main
+  checkout from Git and creates real `.brain` and `.beads` symlinks without the CLI.
+
+## Rules
+
+- Read `.brain/AGENTS.md` before substantial work. It holds this project's own rules and is
+  not injected at session start. If it is missing, note the gap and continue.
+- Brain writes are agent-managed (git-tracked in dotbrain, so changes are revertable).
+- Execution lives in beads. Work from `bd ready`; record multi-step plans as epics with
+  `blocks` dependencies, not as markdown checklists.
+- Use `CONTEXT.md` vocabulary when naming concepts in issues, plans, tests, and proposals.
+  Do not drift to synonyms.
+- If a proposed change conflicts with an ADR, call it out before proceeding.
+- If `CONTEXT.md` or `adr/` are missing or empty, proceed silently — note the gap, don't
+  scaffold them unasked.
+- `.brain/docs/` holds project-scoped knowledge (runbooks, references, derived notes) that
+  is not auto-injected into context. Before answering how this project builds, runs, deploys,
+  integrates, or otherwise works, check and search `.brain/docs/` first — do not infer from
+  the public repo or generic conventions when the Brain has a documented answer.
+- The code repo may be public; the Brain never is. Never mirror Brain content into the code
+  repo — for a public need, derive a fresh audience-specific doc instead.
+- Public-facing repo docs (README.md, repo-root AGENTS.md) must not expose private Brain
+  paths or content. The only `.brain` reference allowed in the repo root is the one-line
+  agent pointer to `.brain/AGENTS.md`.
+- Never reference private Brain context from code, tests, comments, commit messages, or
+  PR text: no ADR numbers, Brain paths, or decision-record identifiers in anything the
+  public repo carries. State the rationale in plain terms instead; the ADR linkage stays
+  in the Brain.
+
+## Working in loops
+
+These invariants bind any iterative or autonomous execution, whatever skill or loop primitive
+drives it:
+
+- Verification, success, and acceptance criteria are human-owned. They can change, but only through
+  the human: surface the proposed wording and the reason, get approval, then record what changed.
+  Where no human is present to approve — an autonomous loop — that is a stop condition, not a
+  licence to decide. What is ruled out in every workflow is an agent weakening or rewriting them on
+  its own to match what the build does.
+- Autonomous iteration always has a hard stop — a retry cap, budget, or turn limit. When the stop
+  is hit, report blocked with the attempt trail; do not keep iterating.
+- An explicit automation-handoff contract — scope, branch/base, verification plan, review mode,
+  available provider/auth, draft-PR authorization, and an explicit `GO` — authorizes only the
+  agreed push of its dedicated branch and creation of a draft PR. Merge, deploy, publish,
+  dependency changes, and every other outward action end the loop and go to the human.
+- Automation-handoff / agent-driven loop work runs on a dedicated branch, never directly on
+  `main`; manual turn-by-turn work needs no branch — it is reviewed as it happens.
+- Beads are the state; the active design doc is the spec. State says where you are, the spec says
+  where to go. Reread the spec every iteration, not just at loop start.
+
+## Unknowns
+
+The Brain exists to shrink the gap between the map (what the agent has been told — vocabulary,
+decisions, rules) and the territory (the codebase and its real constraints). That gap is the
+project's unknowns. Name them in four quadrants and use the terms exactly, so skills, issues, and
+design docs speak one language:
+
+- **Known knowns** — stated and settled. Live in `CONTEXT.md`, `adr/`, and `AGENTS.md`.
+- **Known unknowns** — open questions you can name. Live in a design doc's `Known Unknowns` and in beads.
+- **Unknown knowns** — tacit preferences and domain expectations, recognized only when shown.
+  Surfaced by grilling and prototypes, then written into canon.
+- **Unknown unknowns** — constraints, edge cases, and existing behavior you have not thought to
+  consider. Surfaced by a blind-spot pass before implementation; caught mid-build as discoveries.
+
+Cheap moves early — orient, grill, prototype — turn expensive late unknowns into known knowns.
+
+## Brain structure
+
+- `CONTEXT.md` — domain vocabulary for this project
+- `project.yaml` — per-project skill selection and engine/tracker config
+- `adr/` — Architecture Decision Records, one file per decision
+- `designs/` — design docs, one initiative per file. Each design doc carries a `lifecycle:` field:
+  `draft`, `active`, `shipped`, `abandoned`, or `superseded`. Agents must update lifecycle when the
+  document's mutability changes. While a design is `active`, it is the living design authority for
+  the initiative: current design, verification / success criteria, known unknowns, deviations, and
+  design-relevant implementation discoveries live here. Authored by `to-design`, decomposed into
+  bead epics by `to-issues`.
+  Beads still own execution state. Once a design is `shipped`, `abandoned`, or `superseded`, it
+  freezes as a point-in-time record; durable residue lands in `adr/` (decisions) and `CONTEXT.md`
+  (vocabulary). Driving a design to a terminal state is `close-design`'s job.
+  Design frontmatter is one field set across every Brain: `lifecycle:` (required), `started:` and
+  `ended:` (dates), `extends:` (a design this one builds on), `residue:` (ADR ids produced). Per-doc
+  invented fields drift the vocabulary apart; say anything else in prose
+- `docs/` — derived docs, runbooks, reference material. Optional, never authoritative —
+  canon wins
+
+Skills are cross-project; the Brain only configures them. Skill *selection* lives in
+`project.yaml` (`skills:`); project tracker conventions live in `AGENTS.md` under Project.

dotbrain/resources/templates/brain/adr/README.md

@@ -0,0 +1,8 @@
+# adr/
+
+Architecture Decision Records — one decision per file.
+
+Each ADR captures the context, decision, consequences, and alternatives considered
+for a design choice that affects this project's architecture or conventions.
+
+See `DOTBRAIN.md` for the read order and operating rules.

dotbrain/resources/templates/brain/designs/README.md

@@ -0,0 +1,28 @@
+# designs/
+
+Design docs - one initiative per file.
+
+An `active` design doc is a living unknowns ledger for the initiative. It should capture the
+current design, verification / success criteria, known unknowns, design-relevant implementation
+discoveries, deviations, and any
+human design calls still needed. Author only the sections the initiative needs.
+
+Use `lifecycle:` frontmatter to mark document mutability: `draft`, `active`, `shipped`,
+`abandoned`, or `superseded`. This is not execution status; beads own execution state.
+
+Once a design is `active`, criteria changes are human decisions: record them in the doc
+(`Deviations` or `Human Decisions Needed`), not silently edited in place. When a design ships,
+record the verification evidence achieved, so a later reader can check the gate still catches the
+failure it was written for (gates rot).
+
+Typical sections include motivation, goals, non-goals, current design, verification / success
+criteria, known unknowns, implementation notes, deviations, human decisions needed, alternatives
+considered, and rollout.
+
+Authored by the `to-design` skill, then decomposed into a bead epic by `to-issues`. Beads own
+execution state, dependencies, claim status, and acceptance criteria. When a design reaches
+`shipped`, `abandoned`, or `superseded`, it freezes as a point-in-time record. Durable residue
+lands in `adr/` (decisions) and `CONTEXT.md` (vocabulary); a maintained "how it works now"
+description is a `docs/` runbook. On conflict with canon, canon wins.
+
+See `DOTBRAIN.md` for the read order and operating rules.

dotbrain/resources/templates/brain/docs/README.md

@@ -0,0 +1,9 @@
+# docs/
+
+Derived documents, runbooks, and reference material.
+
+This directory is optional — create it when the first doc exists. Content here is useful
+but never the authority. On conflict with the canon (`AGENTS.md`, `DOTBRAIN.md`,
+`CONTEXT.md`, `adr/`, `agents/`), the canon wins.
+
+Examples: runbooks, adopter guides, design reviews, procedural references.