dotbrain 0.3.4__tar.gz → 0.4.0__tar.gz

{dotbrain-0.3.4 → dotbrain-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotbrain
-Version: 0.3.4
+Version: 0.4.0
 Summary: Wires project Brainspaces and skills into coding agents.
 Project-URL: Homepage, https://github.com/arminzou/dotbrain
 Project-URL: Repository, https://github.com/arminzou/dotbrain

{dotbrain-0.3.4 → dotbrain-0.4.0}/README.md

@@ -4,6 +4,8 @@
 
 # Dotbrain
 
+[![PyPI](https://img.shields.io/pypi/v/dotbrain)](https://pypi.org/project/dotbrain/)
+
 > Dotbrain keeps your project's context private and your code repo clean, and makes that discipline effortless.
 
 As an engineer, almost everything I build outgrows my private workspace. A side project I start
@@ -196,6 +198,11 @@ first so Dotbrain can create directory symlinks without Administrator privileges
 dotbrain home defaults to `%USERPROFILE%\dotbrain` (for example, `C:\Users\you\dotbrain`). Set
 `DOTBRAIN_HOME` only when you want to use a different location.
 
+Already have `uv` or `pipx` and just want the CLI? `uv tool install dotbrain` (or
+`pipx install dotbrain`, or plain `pip install dotbrain`) installs it from
+[PyPI](https://pypi.org/project/dotbrain/) — this skips `uv`/Beads provisioning, so follow up
+with `dotbrain bootstrap` and `dotbrain doctor`.
+
 See [docs/getting-started.md](docs/getting-started.md) for the full walkthrough, including how to
 install the CLI by hand and what to do if `marketplace add` trips over a Windows file lock.
 

{dotbrain-0.3.4 → dotbrain-0.4.0}/docs/cli-reference.md

@@ -61,6 +61,8 @@ Reference for the public `dotbrain` CLI.
 │ --scope            TEXT  global | project | all [default: all]               │
 │ --project          TEXT  Limit project linking to a single Brainspace by     │
 │                          name.                                               │
+│ --repo             TEXT  Checkout to link into (e.g. a linked worktree).     │
+│                          Requires --project and project scope.               │
 │ --help     -h            Show this message and exit.                         │
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -307,6 +309,8 @@ Reference for the public `dotbrain` CLI.
 │ --target           TEXT  claude-code | codex | all [default: all]            │
 │ --scope            TEXT  global | project | all [default: all]               │
 │ --project          TEXT  limit project scope to one Brainspace by name       │
+│ --repo             TEXT  Checkout to link into (e.g. a linked worktree).     │
+│                          Requires --project and project scope.               │
 │ --help     -h            Show this message and exit.                         │
 └──────────────────────────────────────────────────────────────────────────────┘
 ```

{dotbrain-0.3.4 → dotbrain-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dotbrain"
-version = "0.3.4"
+version = "0.4.0"
 description = "Wires project Brainspaces and skills into coding agents."
 requires-python = ">=3.11"
 license = "MIT"

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/__init__.py

@@ -4,4 +4,4 @@ A testable Python CLI for wiring repos into Brainspaces, seeding Brains, and
 managing skills. Exposes the workflow commands plus pure path/contract helpers.
 """
 
-__version__ = "0.3.4"
+__version__ = "0.4.0"

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/cli.py

@@ -504,6 +504,11 @@ def skills_link(
     project: Optional[str] = typer.Option(
         None, "--project", help="limit project scope to one Brainspace by name"
     ),
+    repo: Optional[str] = typer.Option(
+        None,
+        "--repo",
+        help="Checkout to link into (e.g. a linked worktree). Requires --project and project scope.",
+    ),
 ) -> None:
     """Link skills into agent runtimes.
 
@@ -516,11 +521,15 @@ def skills_link(
         raise typer.BadParameter(f"invalid --target: {target}")
     if scope not in {"global", "project", "all"}:
         raise typer.BadParameter(f"invalid --scope: {scope}")
+    if repo is not None and not project:
+        raise typer.BadParameter("--repo requires --project <name>")
+    if repo is not None and scope == "global":
+        raise typer.BadParameter("--repo applies to project scope only")
 
     root = paths.resolve_dotbrain_home()
     try:
         if scope in {"project", "all"}:
-            _link_projects_native(root, target, project)
+            _link_projects_native(root, target, project, Path(repo).resolve() if repo else None)
         if scope in {"global", "all"}:
             if project:
                 typer.echo("skill-link: warning: --project is ignored for global scope", err=True)
@@ -529,7 +538,9 @@ def skills_link(
         raise typer.BadParameter(str(exc)) from exc
 
 
-def _link_projects_native(root: Path, target: str, project: Optional[str]) -> None:
+def _link_projects_native(
+    root: Path, target: str, project: Optional[str], repo_override: Optional[Path] = None
+) -> None:
     workspaces = _AGENT_WORKSPACES[target]
     if project:
         brainspace = paths.brainspace(root, project)
@@ -544,7 +555,11 @@ def _link_projects_native(root: Path, target: str, project: Optional[str]) -> No
         skill_paths = skills.project_link_set(extras)
         declared_workspaces = brainspaces.active_agent_workspaces(brainspace, root)
         active_workspaces = tuple(ws for ws in workspaces if ws in declared_workspaces)
-        repo = adopter_repos.repo_for_brainspace(brainspace, root)
+        repo = (
+            repo_override
+            if repo_override is not None
+            else adopter_repos.repo_for_brainspace(brainspace, root)
+        )
         workspace_dirs, workspace_warnings = workflows.project_workspace_dirs(
             brainspace, repo, active_workspaces
         )
@@ -608,13 +623,23 @@ def agents_link(
         "--project",
         help="Limit project linking to a single Brainspace by name.",
     ),
+    repo: Optional[str] = typer.Option(
+        None,
+        "--repo",
+        help="Checkout to link into (e.g. a linked worktree). Requires --project and project scope.",
+    ),
 ) -> None:
     if target not in {"claude-code", "codex", "all"}:
         raise typer.BadParameter(f"invalid --target: {target}")
     if scope not in {"global", "project", "all"}:
         raise typer.BadParameter(f"invalid --scope: {scope}")
+    if repo is not None and not project:
+        raise typer.BadParameter("--repo requires --project <name>")
+    if repo is not None and scope == "global":
+        raise typer.BadParameter("--repo applies to project scope only")
 
     root = paths.resolve_dotbrain_home()
+    repo_override = Path(repo).resolve() if repo else None
     if scope in {"project", "all"}:
         brainspaces_to_link = [paths.brainspace(root, project)] if project else paths.brainspaces(root)
         if project and not brainspaces_to_link[0].exists():
@@ -623,9 +648,13 @@ def agents_link(
             names = subagents.project_link_set(config.load_project_subagents(root, brainspace.name))
             declared_workspaces = brainspaces.active_agent_workspaces(brainspace, root)
             active_workspaces = tuple(ws for ws in _AGENT_WORKSPACES[target] if ws in declared_workspaces)
-            repo = adopter_repos.repo_for_brainspace(brainspace, root)
+            target_repo = (
+                repo_override
+                if repo_override is not None
+                else adopter_repos.repo_for_brainspace(brainspace, root)
+            )
             workspace_dirs, workspace_warnings = workflows.project_workspace_dirs(
-                brainspace, repo, active_workspaces
+                brainspace, target_repo, active_workspaces
             )
             result = subagents.link_project_subagents(
                 root,
@@ -634,9 +663,9 @@ def agents_link(
                 names,
                 workspace_dirs=workspace_dirs,
             )
-            if repo is not None:
+            if target_repo is not None:
                 adopter_repos.reconcile_link_excludes(
-                    repo,
+                    target_repo,
                     linked=tuple(entry for entry in result.linked if entry.startswith((".claude/", ".codex/"))),
                     pruned=tuple(entry for entry in result.pruned if entry.startswith((".claude/", ".codex/"))),
                 )

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/claude/implementer.md

@@ -1,8 +1,9 @@
 ---
 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.
+description: Carry out one small, already-scoped change end-to-end in the current checkout, matching the project's Brain and conventions, and report the real result without claiming acceptance evidence.
 tools: Read, Grep, Glob, Edit, Write, Bash
 model: sonnet
+effort: medium
 ---
 
 You are a focused implementer. You take one small, already-specified change,
@@ -17,7 +18,7 @@ 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`)
+with decisions in `adr/`, designs in `designs/`, 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.
@@ -29,8 +30,10 @@ 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.
+result. That check is your own smoke test, not acceptance evidence: it does not
+stand in for the verifier's gate, and you do not claim a gate passed on its
+strength. If tests fail, say so with the output; do not claim success you did
+not observe.
 
 Boundaries:
 

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/claude/investigator.md

@@ -1,8 +1,9 @@
 ---
 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.
+description: Brain-aware, read-only investigation of the codebase that answers a question with file-anchored facts, using the project's Brain and beads for context and keeping findings free of private identifiers.
 tools: Read, Grep, Glob, Bash
 model: sonnet
+effort: medium
 ---
 
 You are a focused investigator. Given a question or research target, search the

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/claude/reviewer.md

@@ -1,7 +1,9 @@
 ---
 name: reviewer
-description: Review recent code changes for correctness, regressions, security issues, and missing tests.
+description: Brain-aware review of a change for correctness, regressions, security, and missing tests, reading the project's Brain and beads for intent and keeping findings free of private identifiers.
 tools: Read, Grep, Glob, Bash
+model: opus
+effort: high
 ---
 
 You are a focused code review agent. Review the current change like an owner who

dotbrain-0.4.0/src/dotbrain/resources/agents/claude/verifier.md

@@ -0,0 +1,42 @@
+---
+name: verifier
+description: Run the mechanical verification gate and return commit-stamped evidence — commands, output, pass/fail, and a public-safe Verification block — never an opinion and never an edit.
+tools: Read, Grep, Glob, Bash
+model: haiku
+effort: low
+---
+
+You are a verifier. You run the mechanical gate against the current state of
+the work and report verification evidence. You have no edit tools on purpose:
+you cannot fix, adjust, or "help" the work pass — Bash is for running the gate,
+including gates that write their own caches and artifacts. Your product is
+evidence, not green checkmarks.
+
+Work from the gate, not the whole project. 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.
+
+Stamp your evidence with the commit and environment it was produced for. When
+the same deterministic gate already has evidence for the current commit and a
+clean tree, say so rather than re-running it; a changed tree means a fresh run.
+Never treat an author's self-check as acceptance evidence.
+
+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-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/codex/implementer.toml

@@ -1,5 +1,7 @@
 name = "implementer"
-description = "Carry out one small, already-scoped change end-to-end in the current checkout, then report back."
+description = "Carry out one small, already-scoped change end-to-end in the current checkout, matching the project's Brain and conventions, and report the real result without claiming acceptance evidence."
+model = "gpt-5.6"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Take one small, already-specified change, implement it in the current checkout,
 verify it, and report back.
@@ -8,7 +10,7 @@ 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
+adr/, designs/, 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.
 
@@ -18,7 +20,9 @@ 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.
+real result. That check is your own smoke test, not acceptance evidence: it does
+not stand in for the verifier's gate, and you do not claim a gate passed on its
+strength. 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

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/codex/investigator.toml

@@ -1,5 +1,7 @@
 name = "investigator"
-description = "Answer a question about the codebase read-only with grounded findings and file references."
+description = "Brain-aware, read-only investigation of the codebase that answers a question with file-anchored facts, using the project's Brain and beads for context and keeping findings free of private identifiers."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
 Investigate the requested question or code area and report findings only.

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/agents/codex/reviewer.toml

@@ -1,5 +1,7 @@
 name = "reviewer"
-description = "Review recent code changes for correctness, regressions, security issues, and missing tests."
+description = "Brain-aware review of a change for correctness, regressions, security, and missing tests, reading the project's Brain and beads for intent and keeping findings free of private identifiers."
+model = "gpt-5.6"
+model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """
 Review the current change like an owner who has to maintain it. Report findings

dotbrain-0.4.0/src/dotbrain/resources/agents/codex/verifier.toml

@@ -0,0 +1,35 @@
+name = "verifier"
+description = "Run the mechanical verification gate and return commit-stamped evidence — commands, output, pass/fail, and a public-safe Verification block — never an opinion and never an edit."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "low"
+sandbox_mode = "workspace-write"
+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. You write nothing
+that changes the work; the sandbox is writable only so real gates — tests,
+builds, linters — can write their caches and artifacts.
+
+Work from the gate, not the whole project. You need the success criteria and the
+tree they run against; do not reread the design doc or explore beyond what the
+gate requires.
+
+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.
+
+Stamp your evidence with the commit and environment it was produced for. When
+the same deterministic gate already has evidence for the current commit and a
+clean tree, say so rather than re-running it; a changed tree means a fresh run.
+Never treat an author's self-check as acceptance evidence.
+
+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, with no Brain
+   paths, decision-record identifiers, or spec-ids.
+
+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-0.3.4 → dotbrain-0.4.0}/src/dotbrain/resources/templates/brain/DOTBRAIN.md

@@ -60,6 +60,8 @@ drives it:
   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.
+- A review gate is human-owned at close: an agent records the review's closeout and leaves the bead
+  open, never closing its own review. Closing is the human's, or `close-design`'s terminal transition.
 - 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

{dotbrain-0.3.4 → dotbrain-0.4.0}/src/dotbrain/updater.py

@@ -51,9 +51,20 @@ def _is_windows() -> bool:
 
 
 def _defer_install(command: list[str]) -> None:
-    """Run after this Windows launcher releases its executable lock."""
+    """Run detached, after this Windows launcher releases its executable lock.
+
+    The child must not share this process's console: otherwise its output and
+    lifetime bleed into the caller's shell, and the prompt looks hung until the
+    install finishes.
+    """
+    script = f"ping -n 2 127.0.0.1 >NUL & {subprocess.list2cmdline(command)}"
     subprocess.Popen(
-        ["cmd", "/c", f"ping -n 2 127.0.0.1 >NUL & {subprocess.list2cmdline(command)}"],
+        ["cmd", "/c", script],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=getattr(subprocess, "DETACHED_PROCESS", 0)
+        | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),
     )
 
 

dotbrain-0.3.4/src/dotbrain/resources/agents/claude/verifier.md

@@ -1,35 +0,0 @@
----
-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-0.3.4/src/dotbrain/resources/agents/codex/verifier.toml

@@ -1,21 +0,0 @@
-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.
-"""