dotbrain 0.7.0__tar.gz → 0.9.0__tar.gz

{dotbrain-0.7.0 → dotbrain-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotbrain
-Version: 0.7.0
+Version: 0.9.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
@@ -159,9 +159,14 @@ and `.codex/`. Skills and Claude agents use symlinks; Codex agents use generated
 TOML files. Wiring a Git worktree connects it to the main checkout's existing Brainspace, so
 both use the same knowledge and tracker.
 
-At session start, the plugin hook supplies `DOTBRAIN.md`, the shared convention. The agent then
-reads the project's private rules and retrieves the context the task needs. Workflow skills
-guide how it consults that context and records what you work out together.
+At session start, the plugin hook supplies only `DOTBRAIN.md`, the shared convention.
+Public `AGENTS.md` routes making or reviewing changes to tracked root `RULES.md`, usable
+without a Brain. The lead or sole agent searches private retrospective findings for the task
+and passes relevant findings through assignments; the notebook is never injected.
+Fresh Brains seed private `AGENTS.md` for a small set of personal preferences and project
+rules, with `CLAUDE.md` as its alias. The agent reads it before substantial work; it is
+never injected. Wiring and refresh preserve user-owned context and existing pointers.
+Public `RULES.md` holds repository requirements; private preferences stay private.
 See [Session context](https://arminzou.github.io/dotbrain/session-context) for the loading sequence.
 
 Use `dotbrain projects list` to discover registered projects. Inside a wired checkout,
@@ -192,14 +197,19 @@ The loop closes in two places:
 - **During the work:** discoveries feed back into the active design and affected issues. An
   unexpected API constraint becomes a design question; once you settle it, the design and issues
   capture the decision before implementation continues.
-- **After review:** closing the design records the evidence and preserves useful decisions and
+- **After human merge and manual closeout:** closing the design records the evidence and preserves useful decisions and
   vocabulary in the Brain. The next initiative starts with that knowledge already available.
 
 The Brain holds durable knowledge, the design holds current intent, and Beads holds execution
 state. Each handoff lives in a document or tracker entry that another session or agent can
 consult to continue the work.
 
-You own the success criteria and the final review decision. Use the full loop when work spans
+You own success criteria, PR approval, merge, and release. Settle foreseeable decisions and the
+execution contract upfront; agents reuse complete applicable approval without another routine
+sign-off and work through checks, acceptance/UAT, and required reviews to a ready PR requesting
+your review. New scope, authority, or criteria decisions stop affected work with evidence and a
+recommendation. Limits survive resume. The design stays active until you invoke closeout;
+a PR closed without merge does not establish shipment. Use the full loop when work spans
 sessions or carries open questions; small changes can use just the steps they need.
 
 See [The workflow](https://arminzou.github.io/dotbrain/workflow) for a walkthrough and

{dotbrain-0.7.0 → dotbrain-0.9.0}/README.md

@@ -136,9 +136,14 @@ and `.codex/`. Skills and Claude agents use symlinks; Codex agents use generated
 TOML files. Wiring a Git worktree connects it to the main checkout's existing Brainspace, so
 both use the same knowledge and tracker.
 
-At session start, the plugin hook supplies `DOTBRAIN.md`, the shared convention. The agent then
-reads the project's private rules and retrieves the context the task needs. Workflow skills
-guide how it consults that context and records what you work out together.
+At session start, the plugin hook supplies only `DOTBRAIN.md`, the shared convention.
+Public `AGENTS.md` routes making or reviewing changes to tracked root `RULES.md`, usable
+without a Brain. The lead or sole agent searches private retrospective findings for the task
+and passes relevant findings through assignments; the notebook is never injected.
+Fresh Brains seed private `AGENTS.md` for a small set of personal preferences and project
+rules, with `CLAUDE.md` as its alias. The agent reads it before substantial work; it is
+never injected. Wiring and refresh preserve user-owned context and existing pointers.
+Public `RULES.md` holds repository requirements; private preferences stay private.
 See [Session context](https://arminzou.github.io/dotbrain/session-context) for the loading sequence.
 
 Use `dotbrain projects list` to discover registered projects. Inside a wired checkout,
@@ -169,14 +174,19 @@ The loop closes in two places:
 - **During the work:** discoveries feed back into the active design and affected issues. An
   unexpected API constraint becomes a design question; once you settle it, the design and issues
   capture the decision before implementation continues.
-- **After review:** closing the design records the evidence and preserves useful decisions and
+- **After human merge and manual closeout:** closing the design records the evidence and preserves useful decisions and
   vocabulary in the Brain. The next initiative starts with that knowledge already available.
 
 The Brain holds durable knowledge, the design holds current intent, and Beads holds execution
 state. Each handoff lives in a document or tracker entry that another session or agent can
 consult to continue the work.
 
-You own the success criteria and the final review decision. Use the full loop when work spans
+You own success criteria, PR approval, merge, and release. Settle foreseeable decisions and the
+execution contract upfront; agents reuse complete applicable approval without another routine
+sign-off and work through checks, acceptance/UAT, and required reviews to a ready PR requesting
+your review. New scope, authority, or criteria decisions stop affected work with evidence and a
+recommendation. Limits survive resume. The design stays active until you invoke closeout;
+a PR closed without merge does not establish shipment. Use the full loop when work spans
 sessions or carries open questions; small changes can use just the steps they need.
 
 See [The workflow](https://arminzou.github.io/dotbrain/workflow) for a walkthrough and

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/agent-team.md

@@ -218,11 +218,11 @@ delivery. The final integration review can supply it only with explicit coverage
 branch diff, all scoped items, interactions, and the active design at the exact final revision.
 Approval of only the latest group is insufficient. The reviewer must have authored none of the
 reviewed changes, but need not be fresh. Otherwise arrange a whole-branch review. Mechanical
-checks, the final human review record, and your merge gate remain.
+checks, the final human PR review, and your merge gate remain.
 A single-item branch reuses its item review only if it covers the whole final diff; otherwise it
 also needs a whole-branch review.
 A handoff also gets a non-blocking simplification pass when an independent reviewer is available;
-you decide what to do with its suggestions.
+the lead records finding dispositions within approved scope and returns new consequential decisions to you.
 
 ## When Something Stops
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/architecture.md

@@ -65,10 +65,11 @@ Each element of a Brain has one purpose:
 treeView-beta
   accTitle: The files and folders of a Brain
   .brain/
+    AGENTS.md ## private preferences and project rules
     CONTEXT.md ## domain vocabulary
     adr/ ## decision records
     designs/ ## one design doc per initiative
-    AGENTS.md ## this project's agent conventions
+    RETRO.md ## optional private retrospective findings
     DOTBRAIN.md ## shared convention, owned by dotbrain
     project.yaml ## runtime, tracker, skill selection
     docs/ ## derived runbooks and reference
@@ -77,10 +78,11 @@ treeView-beta
 
 | Element | Holds | Changes when |
 | --- | --- | --- |
+| `AGENTS.md` | Private preferences and project rules; `CLAUDE.md` is its alias | Working rules change |
 | `CONTEXT.md` | Domain vocabulary: the names issues, plans, and code use | A concept is named or sharpened |
 | `adr/` | Architecture Decision Records, one per decision | A hard-to-reverse choice with a real trade-off is made |
 | `designs/` | Design docs, one initiative per file | An initiative is planned, built, or closed |
-| `AGENTS.md` | This project's agent conventions | Working rules change |
+| `RETRO.md` | Optional private retrospective findings and evidence | A retrospective pass records findings |
 | `DOTBRAIN.md` | The shared convention, owned by dotbrain | `dotbrain refresh` updates it |
 | `project.yaml` | Runtime, tracker, skill, and subagent selection | You change what the project uses |
 | `docs/` | Derived runbooks and reference | Anytime; never authoritative |
@@ -91,8 +93,36 @@ real trade-off. An **active** design is the living authority for its initiative;
 **shipped**, **abandoned**, or **superseded** it freezes as a record, and what should outlive it
 moves to `adr/` and `CONTEXT.md`. [The workflow](workflow.md) walks through that lifecycle.
 
+Design authoring settles scope, acceptance/UAT and execution authority with the human.
+Decomposition investigates prerequisites and foreseeable decisions before unattended work; a
+settled graph may be entirely autonomous and needs no second routine task-set approval.
+Iteration validates and reuses the complete approved contract without repeat approval, retaining
+narrower instructions and remaining limits on resume. Missing or changed scope, authority or
+criteria decisions stop affected work with evidence and a recommendation; credentials being
+available never grants permission. Agents check provider permissions at execution entry without
+exposing secrets.
+
+Agent delivery completes with agreed work, required reviews and acceptance/UAT complete at the
+integrated revision, and a ready PR requesting human review. PR approval, target-branch merge and
+release stay human. The design and epic remain active until manually invoked `close-design`
+checks actual merge evidence for shipment; a closed-unmerged PR never proves shipment.
+REFLECT keeps design discoveries in the design and execution facts in Beads. It adds no
+retrospective checkpoint, second reflection report or merge polling.
+
 Brain writes are commits in the dotbrain home, so every change can be reviewed and reverted.
 
+Public repository `AGENTS.md` routes making or reviewing changes to tracked root `RULES.md`.
+These instructions remain usable without a Brain. Shared `DOTBRAIN.md` owns private retrieval:
+the lead or sole agent searches relevant retrospective findings during implementation or review
+preparation and passes them through existing assignments. Workers and reviewers reuse supplied
+findings; a missing notebook blocks nothing and triggers no scaffolding. Session start injects
+only shared conventions, never the notebook.
+
+Fresh Brains seed private `AGENTS.md` for a small set of personal preferences and project
+rules, with `CLAUDE.md` as its alias. The agent reads it before substantial work; it is
+never injected. Wiring and refresh preserve user-owned context and existing pointers.
+Public `RULES.md` holds repository requirements; private preferences stay private.
+
 ## Execution Lives in the Tracker
 
 Plans and tasks do not live in markdown checklists that go stale. They live in an **execution

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/cli-reference.md

@@ -8,7 +8,9 @@ for catalogs and project inspection. Empty lists, previews, and skipped work are
 Doctor shows problems and warnings first; use `doctor -v` to include every healthy check.
 Runtime activation and session uncertainty are informational, shown with `doctor -v` and in
 JSON; they do not count as passed checks. Missing registered hook files and failed plugin
-checks remain warnings.
+checks remain warnings. With `--all`, a project whose shared `.repo` checkout is absent on this
+machine is reported as skipped, not failed; a missing `.repo.local` checkout or an explicit
+`--project` still fails.
 Colors follow terminal capabilities; redirected output stays plain.
 
 Finite reports support `--json`: stdout contains one result with command, overall status,
@@ -94,7 +96,6 @@ dotbrain wire [OPTIONS]
 | --- | --- | --- |
 | `--repo` *path* | — | Checkout to attach; defaults to the current Git checkout. |
 | `--project` *text* | — | Select a named Brainspace. |
-| `--no-repo` | — | Create a Brain-only project; requires `--project`. |
 | `--skip-beads` | — | Create without a tracker. |
 | `--remote` *text* | — | Dolt remote for initial tracker creation. |
 | `--server-host` *text* | — | Dolt server host; defaults to config. |

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/configuration.md

@@ -94,10 +94,33 @@ skills:                       # extra skills for this project's workspaces
 | `beads.database` | project name | Server database name |
 | `skills` | `[]` | Skills linked into this project's workspaces |
 | `subagents` | `[]` | Project-only subagents in addition to the packaged subagents |
+| `retro.promotion.auto-deliver` | `false` | Skill-read setting: allow unattended commit/push/PR delivery of rule proposals |
+| `retro.promotion.destinations` | `[]` | Allowed existing public guides as repo-relative paths; a nonempty array is required for auto-delivery |
 
 `public-tracker` sets up public issue intake and contributor collaboration. It never mirrors the
 private work graph or turns private work into public issues; see the `triage-public` skill.
 
+`run-retro` reads its settings directly; they add no CLI delivery command. With auto-delivery
+disabled or unset, it updates private findings, discovers the repository's guidance conventions,
+and suggests a destination and rule for your decision. You can authorize an individual PR or
+enable standing delivery to an agreed destination, for example:
+
+```yaml
+# project.yaml — opt in only after agreeing on this repository's destination
+retro:
+  promotion:
+    auto-deliver: true
+    destinations:
+      - CONTRIBUTING.md
+      - docs/code-standards.md
+```
+
+Each destination must exist inside the repository. The skill selects the best fit per finding,
+amending existing guidance without copying a rule into every file. If scope is ambiguous or no
+allowed file fits, it suggests the choice to you. A new rules file needs explicit agreement;
+the skill never assumes a repository should adopt `RULES.md`. Approval and merge remain human-owned.
+Disabling auto-delivery leaves private capture and read-only reconciliation available.
+
 ::: info
 `dotbrain refresh` preserves project declarations byte-for-byte. Intentional Beads configuration
 updates preserve unrelated keys, unknown nested values, and explicit empty selections; YAML

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/glossary.md

@@ -33,9 +33,11 @@ agent-facing conventions. In dotbrain terms, the Brain is narrower than the full
 
 ### Brain-only project
 
-A project created without a code checkout, using `dotbrain wire --no-repo --project <name>`.
-It can still have an execution store. Add `--skip-beads` to create it without a tracker;
-tracker-free projects can also have wired checkouts.
+A retired kind of project with no code checkout. `dotbrain wire --no-repo` no longer exists: every
+project has a repository as its working home. That repository can be private and hold only
+documents. To migrate a Brain-only Brainspace, run `dotbrain wire --project <name>` from its new
+repository, or move the Brainspace out of `brainspaces/` to archive it. Add `--skip-beads` to
+create a project without a tracker.
 
 ### ADR
 
@@ -104,7 +106,7 @@ request you review. See [The workflow](workflow.md#_5-work-the-issues).
 
 ### Handoff workflow
 
-The workflow in which an agent continues within a contract you approved with an explicit `GO`,
+The workflow in which an agent continues within a contract you approved, with an explicit `GO` or by reusing an approved contract,
 until it finishes, reaches a human gate, or hits a hard stop. `iterate-design` runs it and delivers
 the work through a pull request that becomes ready for your review.
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/prompts.md

@@ -9,8 +9,8 @@ can send as they are, or adapt, for the common jobs. Each one says when to use i
 triggers, and where the step is explained.
 
 You do not have to name a skill: describing the job is usually enough for the agent to pick it.
-Naming the skill makes the choice certain. Two skills, `iterate-design` and `review-architecture`,
-never start on their own; invoke them explicitly, for example `/dotbrain:iterate-design` in Claude
+Naming the skill makes the choice certain. The skills `iterate-design`, `review-architecture`, `run-retro`,
+and `close-design` never start on their own; invoke them explicitly, for example `/dotbrain:iterate-design` in Claude
 Code.
 
 ## Set Up
@@ -139,7 +139,9 @@ execution is unavailable, the agent reports that and falls back to sequential ex
 
 **When:** the design is active, the work has a mechanical check, and you want the agent to carry
 on without you. It proposes a contract (scope, branch, checks, worker count, pull request
-delivery) and starts only after you reply `GO`. Merging stays with you. **Skill:**
+delivery, acceptance/UAT, reviews, provider/auth and finite limits) if approval is missing.
+It validates and reuses a complete applicable approved contract without repeat `GO`.
+PR approval, merge and release stay with you. **Skill:**
 `iterate-design`, explicit only. See [The workflow](workflow.md#_5-work-the-issues).
 
 ### Handoff: parallel execution
@@ -232,11 +234,11 @@ are `code` (correctness), `simplify`, and `readiness` (is a subsystem sound enou
 ### Close a design
 
 ```text
-The orders-pagination work is merged. Close the design: record the evidence and promote what should outlive it to ADRs and CONTEXT.md.
+/dotbrain:close-design The orders-pagination work is merged. Close the design: record the evidence and promote what should outlive it to ADRs and CONTEXT.md.
 ```
 
 **When:** an initiative ships, is abandoned, or is superseded. Also for sweeping designs that
-never closed out. **Skill:** `close-design`. See [The workflow](workflow.md#_7-close-the-design).
+never closed out. **Skill:** `close-design`, explicit only. See [The workflow](workflow.md#_7-close-the-design).
 
 ## Learn
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/session-context.md

@@ -13,8 +13,10 @@ sequenceDiagram
   participant B as .brain/
   A->>D: Session starts
   D-->>A: dotbrain convention (wired repos only)
-  A->>B: Read AGENTS.md, before substantial work
-  B-->>A: The project's own rules
+  A->>B: Read AGENTS.md before substantial work
+  B-->>A: Private project rules and preferences
+  A->>B: Lead searches task-relevant retrospective findings
+  B-->>A: Relevant findings for existing assignments
 ```
 
 The plugin registers one `SessionStart` hook that runs `dotbrain hook session-start`. It fires on
@@ -31,7 +33,9 @@ The project's own files are not injected:
 | File | Loaded how |
 | --- | --- |
 | `.brain/DOTBRAIN.md` | Injected by the hook |
-| `.brain/AGENTS.md` | Read by the agent; the convention tells it to |
+| `.brain/AGENTS.md` | Read before substantial work for private rules and preferences; never injected |
+| Public `AGENTS.md` and root `RULES.md` | Repository entry point routes making/reviewing changes to tracked rules, usable without a Brain |
+| `.brain/RETRO.md` | Lead or sole agent searches relevant findings during implementation or review preparation; passes them through assignments |
 | `.brain/CONTEXT.md`, `adr/`, `designs/` | Read by the agent when the work needs them |
 | `.brain/docs/` | Searched by the agent before it answers how the project works |
 | Beads workflow primer | Not injected by dotbrain; the agent runs `bd prime` when it needs it |
@@ -43,7 +47,7 @@ To have the Beads primer injected too, add Beads' own hook with `bd setup claude
 Dotbrain tests its session-start payload against a 10,000-byte budget. This budget comes from
 measured Claude Code behavior: 9,961 bytes reached the model, while 10,010 bytes were written to
 a file instead. It is not a verified limit for every runtime. `DOTBRAIN.md` has a bounded size;
-a project's `AGENTS.md` grows with the project. Injecting only the convention keeps the payload
+repository rules and retrospective notebooks grow with the project. Injecting only the convention keeps the payload
 within that budget.
 :::
 
@@ -69,7 +73,8 @@ example prompts, and how the lead coordinates their results.
 dotbrain ships packaged subagents. Claude Code receives them from the plugin as
 `dotbrain:<role>`, for example `dotbrain:worker`. Codex has no plugin agents, so `dotbrain wire`
 generates them into each wired checkout as `dotbrain-<role>`, for example `dotbrain-worker`.
-Each reads the Brain before acting:
+Each loads the authority relevant to its assignment; workers and reviewers reuse supplied findings
+without reading the whole retrospective notebook. A missing notebook blocks nothing and is not scaffolded:
 
 | Subagent | Does |
 | --- | --- |

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/skills.md

@@ -65,7 +65,8 @@ declaration stays unchanged. Removed owned links are pruned, while foreign entri
   durable results into `CONTEXT.md` and `adr/`.
 - **`find-unknowns`** — surface blind spots and tacit assumptions in unfamiliar territory before
   committing to a design.
-- **`close-design`** — drive a design doc to a terminal state: record evidence, promote residue to
+- **`close-design`** — manually drive a design doc to a terminal state: check actual PR merge
+  evidence for shipment, record evidence, promote residue to
   `adr/` and `CONTEXT.md`, close the epic.
 
 ## Execution
@@ -80,9 +81,29 @@ declaration stays unchanged. Removed owned links are pruned, while foreign entri
 
 ## Triage And Review
 
+- **`run-retro`** — explicitly review new or changed evidence, retaining private retrospective
+  findings, successful practices, and bounded progress. Invoke manually or through an external
+  agent-host job; scheduling belongs to the host. Public auto-delivery is off by default:
+  it discovers repository rules, standards, or contributor guidance and suggests a destination
+  and rule for your decision. Set `retro.promotion.auto-deliver: true` and an existing
+  repo-relative `destinations` array in private project configuration to authorize unattended
+  commit/push/PR delivery. Otherwise authorize individual proposals. It reads PR/merge state
+  read-only to reconcile acceptance; approval and merge remain human-owned.
+  Findings use plain Markdown entries in private `RETRO.md`, with a short review-progress
+  header and no duplicated YAML ledger. Evidence review is scoped, not an exhaustive audit
+  of every historical record edit. An adopted `RULES.md` uses `Rule` / `What to check` tables; other guides retain
+  their conventions. Rule proposals have run-retro's own
+  PR process and body, independent of the `pr` skill used for ordinary changes.
+  First use reads existing root guidance and referenced standards, records current HEAD as
+  a baseline, and stops without reviewing history. In repository scope with no rules or
+  standards file, it offers once, on the first pass until answered, to create `RULES.md` from requirements existing guidance
+  already states and delivers it as a PR; contributor scope never creates a file in the repo.
+  Later runs review forward within explicitly
+  selected contribution branches/PRs or a maintainer-selected integration branch, reusing shared
+  progress and current applicable guidance. Missing scope is reported instead of assumed.
 - **`review-gate`** — run a durable review gate (code, simplification, or readiness) and record the
-  outcome on the issue; a code review closes once you merge its pull request, and other reviews
-  close with you
+  outcome on the issue; the lead closes accepted reviews before PR merge after required exact-revision
+  evidence and finding dispositions. Human PR approval, merge and release remain separate
 - **`curate-project-context`** — find and repair stale, duplicated, misplaced, unreachable, or
   leaking context across the public project and private Brain
 - **`triage-public`** — classify public tracker items and promote ready work into private execution

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/troubleshooting.md

@@ -94,7 +94,9 @@ Yes. Set `DOTBRAIN_HOME` to the directory you want.
 
 ### Can I use dotbrain without a code repo?
 
-Yes. `dotbrain wire --no-repo --project <project>` creates a Brain-only Brainspace.
+Not anymore. Every project needs a repository as its working home, but it can be a private
+repository that holds only documents. To move an older Brain-only project onto one, run
+`dotbrain wire --project <project>` from that repository.
 
 ### How do I stop using dotbrain on a repo?
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/wiring.md

@@ -72,10 +72,6 @@ dotbrain wire
 dotbrain wire --repo ~/repos/my-app
 ```
 
-```bash [Brain only]
-dotbrain wire --no-repo --project research
-```
-
 :::
 
 `wire` creates or repairs:
@@ -146,8 +142,10 @@ tracker state. Named selection and `--all` use registered checkouts rather than
 ## Selection and reports
 
 Project commands default to the current wired checkout, including its subdirectories. Outside
-one, use `--project <name>`. Named selection respects `.repo.local` before `.repo`; Brain-only
-projects are valid for operations that do not need a checkout. Use `dotbrain projects list` and
+one, use `--project <name>`. Named selection respects `.repo.local` before `.repo`. A Brainspace with
+no registered checkout, such as an older Brain-only one, stays valid for operations that do not need
+a checkout; `doctor` warns about it, and `--all` asset linking skips it. Run
+`dotbrain wire --project <name>` from a repository to register one. Use `dotbrain projects list` and
 `dotbrain projects show` to inspect identities and resolved settings without remote probes.
 
 `--all` conflicts with `--project` and `--repo`. Applicable leaf commands accept `--home <path>`

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/workflow.md

@@ -99,6 +99,10 @@ criteria and `blocks` dependencies. "What can I work on next" is then a query in
 bd ready
 ```
 
+It investigates prerequisites and surfaces foreseeable human decisions with evidence and
+recommendations before unattended work. A settled design needs no second task-set sign-off;
+an entirely autonomous implementation graph is valid. Unresolved decisions block affected work.
+
 ## 5. Work the Issues
 
 `manage-work-graph` keeps the work graph: it files, links, and claims issues and closes them when
@@ -122,20 +126,23 @@ share no build outputs, databases, or ports. When you are directing the work, it
 split before starting, and you can change it.
 
 Either way, the work happens on a dedicated branch and reaches `main` through a pull request you
-review. The agent asks before pushing or opening that pull request, and lands work directly on
+review. The agent reuses complete applicable delivery approval, asks only for missing or changed
+authority before pushing or opening that pull request, and lands work directly on
 `main` only when you tell it to.
 
 **Or hand it off.** For an unattended run against an active design, `iterate-design` drives the
 agent's loop mode with a mechanical verifier and a hard stop. You approve a contract first: the
 scope, the branch, the checks, how many workers may run at once, and how the pull request is
-delivered. Then:
+delivered, provider/auth and PR authority, acceptance/UAT, reviews, and finite limits. A complete
+approved contract is validated and reused without repeat `GO`; an execution request alone grants
+no missing authority. Remaining limits and narrower instructions survive resume. Then:
 
 - At its first push it opens a draft pull request, and it pushes again after each accepted integration group.
 - When an issue fails its checks three times in a row, or needs your decision, only that issue and
   the issues waiting on it stop. Independent issues continue.
 - When the run stops blocked, it mentions you on the pull request, so you are notified.
 - When everything is done and reviewed, it marks the pull request ready and requests your review.
-  Merging stays with you.
+  PR approval, target-branch merge, and release stay with you.
 
 ## 6. Review
 
@@ -156,17 +163,23 @@ Reviews happen at two levels:
   The final integration review can supply this only with explicit whole-branch coverage at the
   exact final revision; approval of the latest group alone is insufficient. Otherwise arrange a
   whole-branch review. Later changes affecting coverage need refreshed evidence. A handoff
-  also runs a simplification pass. Its suggestions never block the pull request; you decide on
-  them alongside it.
+  also runs a simplification pass. Its suggestions never block the pull request; the lead records
+  dispositions within approved scope and returns new consequential decisions to you.
 
 `review-gate` runs these reviews in focused modes (correctness, simplification, or readiness) and
-records each outcome in the tracker. The agent never closes a review on its own judgment: it closes
-a code review's record once it sees you merge the reviewed pull request, and every other review
-waits for you.
+records each outcome in the tracker. Within approved authority, the lead closes accepted work and
+reviews before PR merge: required independent verdicts and acceptance/UAT evidence cover the exact
+integrated revision, blocking findings are resolved, and other findings have recorded dispositions.
+Simplify stays non-blocking and closes once every finding is applied, filed, or declined with a reason.
+Reviews gain no automatic human gate. Genuine human decisions still block affected work; review
+closure grants no PR approval, merge, or release authority.
 
 ## 7. Close the Design
 
-`close-design` moves the design to a terminal state. It records the evidence that the success
+You manually invoke `close-design` to move the design to a terminal state. For shipped work it
+checks the actual PR, target branch, merge commit and merge date; closed-unmerged never establishes
+shipment. A ready PR leaves the design and epic active. Work/review closure never invokes closeout
+automatically, and no merge polling is added. It records the evidence that the success
 criteria were met, promotes what should outlive the initiative into `adr/` and `CONTEXT.md`, and
 closes the epic. The next initiative starts with those decisions already in the Brain.
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/zh/agent-team.md

@@ -174,9 +174,9 @@ Worker 自己的测试是过程中的检查证据，不是独立验收。Lead
 HITL 中，lead 可以提出小改动的审阅豁免建议，问你是否同意。包含多个任务的分支，交付前需要独立的全分支代码审阅。
 最后一次集成审阅只有明确覆盖最终版本的整个分支 diff、所有范围内任务、交互和 active 设计，才能兼作最终代码审阅。
 只批准最后一组改动不够。Reviewer 必须没有编写任何被审阅的改动，但不必换新人；覆盖不全时另做全分支审阅。
-机械检查、最终人工审阅记录和你的合并门槛保持不变。
+机械检查、最终人工 PR 审阅和你的合并门槛保持不变。
 只有一个任务的分支，也只有在单任务审阅覆盖最终完整 diff 时才能复用；否则仍需全分支审阅。
-Handoff 在有独立 reviewer 可用时还会做一轮不阻塞交付的简化审阅，建议由你决定如何处理。
+Handoff 在有独立 reviewer 可用时还会做一轮不阻塞交付的简化审阅；lead 在已批准的范围内记录处理结果，新的重大决策交给你。
 
 ## 工作停下时 {#when-something-stops}
 

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/zh/architecture.md

@@ -61,10 +61,11 @@ Brain 里的每个部分各有一个用途：
 treeView-beta
   accTitle: The files and folders of a Brain
   .brain/
+    AGENTS.md ## private preferences and project rules
     CONTEXT.md ## domain vocabulary
     adr/ ## decision records
     designs/ ## one design doc per initiative
-    AGENTS.md ## this project's agent conventions
+    RETRO.md ## optional private retrospective findings
     DOTBRAIN.md ## shared convention, owned by dotbrain
     project.yaml ## runtime, tracker, skill selection
     docs/ ## derived runbooks and reference
@@ -73,19 +74,40 @@ treeView-beta
 
 | 部分 | 内容 | 何时变化 |
 | --- | --- | --- |
+| `AGENTS.md` | 私有偏好和项目规则；`CLAUDE.md` 是它的别名 | 工作规则变化时 |
 | `CONTEXT.md` | 领域术语：任务、计划和代码里用的名字 | 一个概念被命名或定义得更精确时 |
 | `adr/` | 架构决策记录（ADR），每个决策一条 | 做出一个难以撤回、有真实取舍的选择时 |
 | `designs/` | 设计文档，每项工作一个文件 | 一项工作被规划、实现或结束时 |
-| `AGENTS.md` | 本项目的 Agent 约定 | 工作规则变化时 |
+| `RETRO.md` | 可选的私有复盘发现和证据 | 复盘记录新发现时 |
 | `DOTBRAIN.md` | 共享约定，由 dotbrain 维护 | `dotbrain refresh` 更新它时 |
 | `project.yaml` | 运行时、任务跟踪、技能和子 Agent 的选择 | 你改变项目使用的东西时 |
 | `docs/` | 派生的操作手册和参考资料 | 随时；从不作为权威依据 |
 | `learning/` | 可选的个人学习工作区 | 你用 `teach-me` 学习项目时 |
 
+公开的仓库 `AGENTS.md` 会指引 Agent 在修改或审阅代码时读取根目录下、由 Git 跟踪的
+`RULES.md`；没有 Brain 也能照常使用。共享约定 `DOTBRAIN.md` 负责私有上下文的检索：
+lead 或独立工作的 Agent 在实现或审阅准备时搜索复盘笔记，把相关发现随任务分派传递。
+worker 和 reviewer 复用这些发现，不必通读笔记；笔记缺失不会阻塞工作，也不会因此自动创建。
+会话开始时只注入共享约定，不会注入复盘笔记。
+
+新建 Brain 会生成私有的 `AGENTS.md`，保存少量个人偏好和项目私有规则，
+`CLAUDE.md` 是它的符号链接。Agent 在开始实质工作前读取它，会话启动时不注入。
+wire 和 refresh 保留已有内容和上下文指针。仓库要求放在公开的 `RULES.md`，个人偏好保持私有。
+
 ADR 记录的是难以撤回、没有上下文会让人意外、并且经过真实取舍的决策。**active** 的设计是这项工作的
 权威依据；一旦变成 **shipped**、**abandoned** 或 **superseded**，它就冻结为一份记录，需要长期保留的内容
 转移到 `adr/` 和 `CONTEXT.md`。[工作流程](workflow.md)介绍了这个生命周期。
 
+写设计时，先与你敲定范围、验收/UAT 和执行权限。拆分任务前调查前置条件和可预见的决策；
+设计已定，就不必再为任务拆分单独确认，实现任务也可以全部自主完成。执行时核实并复用完整授权，
+恢复时保留更窄的指令和剩余次数、预算。遇到新的范围、权限或验收标准问题，先停下相关工作，
+带上证据和建议交给你决定。执行入口检查 provider 权限，不暴露凭据；有凭据不等于有授权。
+
+Agent 完成约定的工作、必要审阅和验收/UAT，证据覆盖准确的集成版本，再把 PR 标为 ready 并请求你审阅。
+PR 批准、合并到目标分支和发布仍由你决定。设计和 epic 保持 active，直到你手动调用 `close-design`；
+认定已交付前要核实真实合并证据，关闭但未合并的 PR 不算交付。REFLECT 仍把设计发现写回设计、执行事实
+写入 Beads，不增加复盘检查点、第二份反思报告或合并轮询。
+
 对 Brain 的写入都是 dotbrain 主目录里的提交，所以每次改动都可以审阅和撤回。
 
 ## 执行状态放在任务跟踪里 {#execution-lives-in-the-tracker}

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/zh/cli-reference.md

@@ -5,7 +5,8 @@
 面向人的输出会按目标对改动和问题分组，把主目录路径缩写成 `~`，并用表格展示目录和项目信息。空列表、预览和
 被跳过的操作都会明确显示。doctor 先显示问题和警告；用 `doctor -v` 可以包括所有健康的检查项。运行时激活状态和
 会话的不确定性属于参考信息，只在 `doctor -v` 和 JSON 中显示，不算作通过的检查。缺失的已注册 hook 文件和失败的
-插件检查仍然是警告。颜色会根据终端能力调整；重定向的输出保持纯文本。
+插件检查仍然是警告。使用 `--all` 时，如果项目共享的 `.repo` checkout 不在本机上，该项目显示为跳过而不是失败；
+`.repo.local` 指向的 checkout 缺失，或用 `--project` 明确选择时，仍然报错。颜色会根据终端能力调整；重定向的输出保持纯文本。
 
 一次性输出结果的命令支持 `--json`：stdout 包含一个结果，里面有命令、总体状态、每个目标的结果和错误。
 问题的严重级别有 `info`、`warning` 和 `error`；只有 warning 时不算失败。退出码 `0` 表示成功，`1` 表示操作失败或
@@ -89,7 +90,6 @@ dotbrain wire [OPTIONS]
 | --- | --- | --- |
 | `--repo` *path* | — | 要连接的 checkout；默认是当前的 Git checkout。 |
 | `--project` *text* | — | 选择一个指定的 Brainspace。 |
-| `--no-repo` | — | 创建只有 Brain 的项目；需要 `--project`。 |
 | `--skip-beads` | — | 创建时不带任务跟踪。 |
 | `--remote` *text* | — | 首次创建任务跟踪时使用的 Dolt remote。 |
 | `--server-host` *text* | — | Dolt 服务器主机；默认取自配置。 |

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/zh/configuration.md

@@ -91,10 +91,30 @@ skills:                       # extra skills for this project's workspaces
 | `beads.database` | 项目名 | 服务器上的数据库名 |
 | `skills` | `[]` | 链接到这个项目工作区的技能 |
 | `subagents` | `[]` | 在自带子 Agent 之外，只给这个项目用的子 Agent |
+| `retro.promotion.auto-deliver` | `false` | 由 skill 读取：允许自动提交、推送规则提案并创建 PR |
+| `retro.promotion.destinations` | `[]` | 允许修改的已有公开指南，相对仓库的路径数组；启用自动交付时不能为空 |
 
 `public-tracker` 用来设置公开的任务入口和与贡献者的协作。它从不镜像私有的工作图，也不会把私有工作变成
 公开任务；见 `triage-public` 技能。
 
+`run-retro` 直接读取这些设置，不增加 CLI 交付命令。自动交付未设置或关闭时，它更新私有发现，
+查找仓库已有的规则、标准或贡献指南，并建议文件位置和规则，由你决定是否创建 PR。
+你可以单独授权某个提案，也可以在确认仓库接受该位置后启用自动交付：
+
+```yaml
+# project.yaml — 先确认这个仓库接受该位置，再启用
+retro:
+  promotion:
+    auto-deliver: true
+    destinations:
+      - CONTRIBUTING.md
+      - docs/code-standards.md
+```
+
+各目标文件必须已存在于仓库内。skill 按发现的主题和适用范围选择最合适的文件，不把同一规则复制到所有文件。
+没有合适位置或归属不清时，它会建议位置，由你决定。新建规则文件需要明确同意；skill 不会默认要求仓库采用 `RULES.md`。
+PR 批准与合并仍由你决定。关闭自动交付后，私有记录和只读的合并状态核对照常进行。
+
 ::: info
 `dotbrain refresh` 会逐字节保留项目声明。有意更新 Beads 配置时，会保留不相关的键、未知的嵌套值和显式的
 空选择；这类显式更新可能会重新排版 YAML 注释。

{dotbrain-0.7.0 → dotbrain-0.9.0}/docs/zh/glossary.md

@@ -31,8 +31,10 @@ Brainspace 小。
 
 ### Brain-only project
 
-没有代码 checkout 的项目，用 `dotbrain wire --no-repo --project <name>` 创建。它仍然可以有执行存储。加上
-`--skip-beads` 可以创建一个没有任务跟踪的项目；没有任务跟踪的项目也可以连接 checkout。
+已经停用的项目类型，没有代码 checkout。`dotbrain wire --no-repo` 已经移除：每个项目都以一个仓库作为工作目录。
+这个仓库可以是私有的，只放文档。要迁移 Brain-only 的 Brainspace，在新仓库里运行
+`dotbrain wire --project <name>`；或者把 Brainspace 移出 `brainspaces/` 归档。加上 `--skip-beads` 可以创建一个
+没有任务跟踪的项目。
 
 ### ADR
 
@@ -91,7 +93,7 @@ dotbrain 的全局配置文件，通常在 `~/dotbrain/config.yaml`。它存放
 
 ### Handoff workflow
 
-Agent 在你用明确的 `GO` 批准的约定范围内继续工作，直到完成、遇到需要人来把关的关卡，或者触发硬性停止条件。
+Agent 在你批准的约定范围内继续工作（通过明确的 `GO`，或复用已批准的约定），直到完成、遇到需要人来把关的关卡，或者触发硬性停止条件。
 `iterate-design` 负责运行它，并通过一个转为 ready、等你审阅的 PR 交付工作。
 
 ### Execution mode