brichan 0.6.0__tar.gz

brichan-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minh Tran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brichan-0.6.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: brichan
+Version: 0.6.0
+Summary: Repository-native AI Chief of Staff orchestration
+Author: Minh Tran
+License: MIT License
+        
+        Copyright (c) 2026 Minh Tran
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: ai,orchestration,codex,claude-code,chief-of-staff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Brichan
+
+[![PyPI version](https://img.shields.io/pypi/v/brichan.svg)](https://pypi.org/project/brichan/)
+[![Python versions](https://img.shields.io/pypi/pyversions/brichan.svg)](https://pypi.org/project/brichan/)
+[![License](https://img.shields.io/pypi/l/brichan.svg)](https://pypi.org/project/brichan/)
+
+Coding agents are very good at the work in front of them and very bad at
+remembering why it was asked for. Context lives in a chat window, so it is lost
+when the window closes; decisions are re-litigated, status is reconstructed from
+memory, and the record of what was actually verified never outlives the session.
+Running several agents at once makes this worse, not better, because nothing
+owns the state between them.
+
+This package introduces an AI Chief of Staff that sits above the coding agent
+rather than inside it. You give it a project goal; it keeps only the context
+that goal needs, hands bounded tasks to independent workers, checks the evidence
+they return, and records decisions and status as files in your repository —
+outside chat, where they survive the session.
+
+The distribution is named `brichan`. The importable package stays `brida`, and
+every console command keeps its existing `brida` / `brida-*` name.
+
+## Installation
+
+### PyPI
+
+To install Brichan, simply:
+
+```bash
+$ pip install brichan
+```
+
+Brichan runs on POSIX-compatible systems with Python 3.10 or newer. It has no
+runtime dependencies.
+
+### From source
+
+The repository ships an installer that builds a wheel and installs every console
+command into a dedicated environment. It can be invoked from any directory and
+does not activate or modify your project's virtual environment:
+
+```bash
+$ /absolute/path/to/brida/scripts/install-brida
+```
+
+By default it creates an environment at `$HOME/.local/share/brida/venv` and
+command symlinks in `$HOME/.local/bin`, selecting an available Python 3.10+
+interpreter with `pip`, `setuptools`, `venv`, and `wheel`. If the command
+directory is not on `PATH`, the installer prints the exact export to add to your
+shell profile.
+
+## Usage
+
+Brichan operates on an existing top-level Git repository. Initialization
+defaults to a dry run and performs zero writes, so you can preview the complete
+footprint before anything is created:
+
+```bash
+$ brida init --project /absolute/path/to/repository
+```
+
+Once the footprint looks right, apply it:
+
+```bash
+$ brida init --apply --project /absolute/path/to/repository
+```
+
+This creates only a versioned `.brida/` directory holding managed policy, model
+routing, Herdr skill resources, and mutable project memory. Repeating it against
+healthy state is idempotent. Your `AGENTS.md`, `CLAUDE.md`, `.codex/`, and
+provider configuration are left untouched.
+
+Diagnose and launch from any directory by naming the target explicitly:
+
+```bash
+$ brida status --project /absolute/path/to/repository
+$ brida doctor --project /absolute/path/to/repository
+$ brida run --project /absolute/path/to/repository -- <codex arguments>
+```
+
+From inside a healthy initialized repository, bare `brida` launches Codex
+directly:
+
+```bash
+$ brida
+```
+
+Arguments after `--` are forwarded to Codex. Option-looking text after `--` is
+treated as literal prompt content, so a prompt beginning with a dash cannot
+silently become a flag:
+
+```bash
+$ brida run --project /absolute/path/to/repository -- --review the auth module
+```
+
+Before the `--`, Brichan rejects native delegation, permission bypasses,
+cwd/scope widening, profiles, remote execution, and arbitrary Codex
+configuration. State diagnostics reject malformed, dangling, symlinked,
+inaccessible, or incompatible `.brida/` state rather than silently repairing it.
+Schema v1 has no automatic migration: a package-version change requires
+deliberate backup and reinitialization.
+
+### Coordinating workers
+
+Herdr is the worker control plane. Native runtime delegation stays disabled so
+worker ownership, evidence, and cleanup remain visible:
+
+1. You describe the outcome and constraints.
+2. Brichan reads only the project context that work needs.
+3. Brichan gives bounded tasks to independent workers through Herdr.
+4. Brichan verifies the results, records decisions and status, then reports back.
+
+Herdr is needed only when Brichan coordinates independent worker sessions.
+Project context is written to `projects/<project-slug>/` as a small set of
+Markdown files covering overview, current state, tasks, decisions, and
+references.
+
+Coordinator defaults and worker routes are settings-driven, so the coordinator
+and the implementation, review, planning, or scan workers may each use a
+different runtime.
+
+### Other console commands
+
+Installing `brichan` also provides:
+
+- `brida-codex` — resolves coordinator routing from a Brida source checkout (or
+  `BRIDA_ROOT`), or from an already-initialized project's `.brida/` state.
+- `brida-claude` — resolves only from a checkout or `BRIDA_ROOT`.
+- `brida-herdr-agent-start` — starts a Herdr worker session.
+- `brida-validate-receipts` — validates canonical handoff receipts.
+
+`brida-codex` and `brida-claude` are checkout-oriented and intended for
+development, not standalone installed-project launches. `--help` and `--version`
+work from any directory.
+
+## Contributing
+
+1. Fork it (https://github.com/minhtran3124/Brichan/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the validation suite (`make check`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+## License
+
+Brichan is available under the [MIT License](https://opensource.org/licenses/MIT).

brichan-0.6.0/README.md

@@ -0,0 +1,158 @@
+# Brichan
+
+![Brichan coordinating a team of AI workers](assets/brida-hero.png)
+
+Brichan is an AI Chief of Staff for Codex and Claude Code. Give it a project
+goal; it keeps the necessary context, coordinates independent workers through
+Herdr, checks their evidence, and records useful project state outside chat.
+Its existing runtime package and console commands remain `brida` and
+`brida-*` for compatibility.
+
+## Current dogfood scope
+
+The primary one-user dogfood path is now an installed Python package running
+inside an existing top-level Git repository. Installed-project mode currently
+supports Codex on POSIX-compatible systems with Python 3.10+. Herdr is needed
+only when Brida coordinates independent worker sessions.
+
+Brida is published to PyPI as `brichan`, while the importable package stays
+`brida` and every console command keeps its existing name:
+
+```bash
+pip install brichan
+```
+
+To install from this repository instead — for development, or to run a change
+that is not released yet — use the installer. It can be invoked from any
+directory and does not activate or modify the target project's virtual
+environment:
+
+```bash
+/absolute/path/to/brida/scripts/install-brida
+```
+
+By default, the script creates a dedicated environment at
+`$HOME/.local/share/brida/venv` and command symlinks in `$HOME/.local/bin`.
+It automatically selects an available Python 3.10+ interpreter with `pip`,
+`setuptools`, `venv`, and `wheel`, builds from a temporary source snapshot,
+and installs all Brida console commands. No virtualenv activation is
+required. If the command directory is not on `PATH`, the installer prints
+the exact export to add to the shell profile.
+
+## Initialize a project
+
+Preview the complete footprint before writing:
+
+```bash
+brida init --project /absolute/path/to/repository
+brida init --apply --project /absolute/path/to/repository
+```
+
+`init` defaults to dry-run and performs zero writes. `--apply` creates only a
+versioned `.brida/` directory containing managed policy, model routing, Herdr
+skill resources, and mutable project memory. Repeating it against healthy
+state is idempotent.
+
+Diagnose and launch from any directory with an explicit target:
+
+```bash
+brida status --project /absolute/path/to/repository
+brida doctor --project /absolute/path/to/repository
+brida run --project /absolute/path/to/repository -- <codex arguments>
+```
+
+From inside a healthy initialized repository, bare `brida` also launches
+Codex. The installed entrypoint:
+
+- leaves `AGENTS.md`, `CLAUDE.md`, `.codex/`, and provider configuration
+  untouched;
+- launches external `codex` directly at the target root and never executes
+  target-owned `bin/brida-*` wrappers;
+- injects package-owned Brida policy and Herdr skill discovery;
+- rejects native delegation, permission bypasses, cwd/scope widening, profiles,
+  remote execution, and arbitrary Codex configuration before `--`;
+- treats option-looking text after `--` as literal prompt content.
+
+State diagnostics reject malformed, dangling, symlinked, inaccessible, or
+incompatible `.brida/` state without silently repairing it. Schema v1 has no
+automatic migration: package-version changes require deliberate backup and
+reinitialization. See the
+[installed Codex dogfood guide](docs/guides/installable-dogfood.md) for the
+exact footprint, exit codes, safeguards, and compatibility boundary.
+
+## Checkout compatibility and development
+
+The original checkout workflow remains available for development and for
+Claude Code:
+
+```bash
+bin/brida
+bin/brida --runtime claude
+```
+
+From a checkout, `brida --help` and `brida --version` report Brida itself; a
+checkout has no project state to launch into. Name a runtime to reach its own
+help instead, with `brida --runtime codex --help` or `bin/brida-codex --help`.
+
+Checkout mode uses package-owned `bin/brida-*` wrappers. Installed-project mode
+does not. Coordinator defaults and worker routes are settings-driven, so the
+coordinator and implementation, review, planning, or scan workers may use
+different runtimes. See the [model-routing guide](docs/guides/model-routing.md)
+to change defaults, select a named route, or use a one-off override.
+
+The `brida-codex` and `brida-claude` console commands installed by `brichan`
+remain checkout-oriented: `brida-codex` resolves coordinator routing from a
+Brida source checkout (or `BRIDA_ROOT`) or from an already-initialized
+project's `.brida/` state, while `brida-claude` resolves only from a checkout
+or `BRIDA_ROOT`. Both are for development and checkout use, not standalone
+installed-project launches. `--help`/`--version` work from any directory; the
+[installed Codex dogfood guide](docs/guides/installable-dogfood.md) has the
+exact boundary.
+
+## How it works
+
+1. You describe the outcome and constraints.
+2. Brida reads only the project context needed for that work.
+3. Brida gives bounded tasks to independent workers through Herdr.
+4. Brida verifies results, records decisions and status, then reports back.
+
+Herdr is the worker control plane. Native runtime delegation stays disabled so
+worker ownership, evidence, and cleanup remain visible.
+
+Project context lives in `projects/<project-slug>/` as a small set of Markdown
+files for overview, current state, tasks, decisions, and references. Read the
+[project memory policy](docs/policy/memory-policy.md) for the contract.
+
+## Development
+
+Run the complete local validation suite before sharing a change:
+
+```bash
+make check
+```
+
+You can also run individual layers while iterating:
+
+```bash
+make test-unit
+make test-contract
+make test-integration
+make package-check
+```
+
+The importable implementation is in `src/brida/`; stable command wrappers are
+in `bin/` and `scripts/`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the change
+workflow and [the repository layout](docs/architecture/repository-layout.md)
+for module boundaries.
+
+## Learn more
+
+- [Model routing and worker launch settings](docs/guides/model-routing.md)
+- [Installed Codex dogfood](docs/guides/installable-dogfood.md)
+- [Documentation index](docs/index.md)
+- [Operating principles](docs/policy/operating-principles.md)
+- [Security policy](SECURITY.md)
+
+## License
+
+Brida is available under the [MIT License](LICENSE).

brichan-0.6.0/README_PYPI.md

@@ -0,0 +1,147 @@
+# Brichan
+
+[![PyPI version](https://img.shields.io/pypi/v/brichan.svg)](https://pypi.org/project/brichan/)
+[![Python versions](https://img.shields.io/pypi/pyversions/brichan.svg)](https://pypi.org/project/brichan/)
+[![License](https://img.shields.io/pypi/l/brichan.svg)](https://pypi.org/project/brichan/)
+
+Coding agents are very good at the work in front of them and very bad at
+remembering why it was asked for. Context lives in a chat window, so it is lost
+when the window closes; decisions are re-litigated, status is reconstructed from
+memory, and the record of what was actually verified never outlives the session.
+Running several agents at once makes this worse, not better, because nothing
+owns the state between them.
+
+This package introduces an AI Chief of Staff that sits above the coding agent
+rather than inside it. You give it a project goal; it keeps only the context
+that goal needs, hands bounded tasks to independent workers, checks the evidence
+they return, and records decisions and status as files in your repository —
+outside chat, where they survive the session.
+
+The distribution is named `brichan`. The importable package stays `brida`, and
+every console command keeps its existing `brida` / `brida-*` name.
+
+## Installation
+
+### PyPI
+
+To install Brichan, simply:
+
+```bash
+$ pip install brichan
+```
+
+Brichan runs on POSIX-compatible systems with Python 3.10 or newer. It has no
+runtime dependencies.
+
+### From source
+
+The repository ships an installer that builds a wheel and installs every console
+command into a dedicated environment. It can be invoked from any directory and
+does not activate or modify your project's virtual environment:
+
+```bash
+$ /absolute/path/to/brida/scripts/install-brida
+```
+
+By default it creates an environment at `$HOME/.local/share/brida/venv` and
+command symlinks in `$HOME/.local/bin`, selecting an available Python 3.10+
+interpreter with `pip`, `setuptools`, `venv`, and `wheel`. If the command
+directory is not on `PATH`, the installer prints the exact export to add to your
+shell profile.
+
+## Usage
+
+Brichan operates on an existing top-level Git repository. Initialization
+defaults to a dry run and performs zero writes, so you can preview the complete
+footprint before anything is created:
+
+```bash
+$ brida init --project /absolute/path/to/repository
+```
+
+Once the footprint looks right, apply it:
+
+```bash
+$ brida init --apply --project /absolute/path/to/repository
+```
+
+This creates only a versioned `.brida/` directory holding managed policy, model
+routing, Herdr skill resources, and mutable project memory. Repeating it against
+healthy state is idempotent. Your `AGENTS.md`, `CLAUDE.md`, `.codex/`, and
+provider configuration are left untouched.
+
+Diagnose and launch from any directory by naming the target explicitly:
+
+```bash
+$ brida status --project /absolute/path/to/repository
+$ brida doctor --project /absolute/path/to/repository
+$ brida run --project /absolute/path/to/repository -- <codex arguments>
+```
+
+From inside a healthy initialized repository, bare `brida` launches Codex
+directly:
+
+```bash
+$ brida
+```
+
+Arguments after `--` are forwarded to Codex. Option-looking text after `--` is
+treated as literal prompt content, so a prompt beginning with a dash cannot
+silently become a flag:
+
+```bash
+$ brida run --project /absolute/path/to/repository -- --review the auth module
+```
+
+Before the `--`, Brichan rejects native delegation, permission bypasses,
+cwd/scope widening, profiles, remote execution, and arbitrary Codex
+configuration. State diagnostics reject malformed, dangling, symlinked,
+inaccessible, or incompatible `.brida/` state rather than silently repairing it.
+Schema v1 has no automatic migration: a package-version change requires
+deliberate backup and reinitialization.
+
+### Coordinating workers
+
+Herdr is the worker control plane. Native runtime delegation stays disabled so
+worker ownership, evidence, and cleanup remain visible:
+
+1. You describe the outcome and constraints.
+2. Brichan reads only the project context that work needs.
+3. Brichan gives bounded tasks to independent workers through Herdr.
+4. Brichan verifies the results, records decisions and status, then reports back.
+
+Herdr is needed only when Brichan coordinates independent worker sessions.
+Project context is written to `projects/<project-slug>/` as a small set of
+Markdown files covering overview, current state, tasks, decisions, and
+references.
+
+Coordinator defaults and worker routes are settings-driven, so the coordinator
+and the implementation, review, planning, or scan workers may each use a
+different runtime.
+
+### Other console commands
+
+Installing `brichan` also provides:
+
+- `brida-codex` — resolves coordinator routing from a Brida source checkout (or
+  `BRIDA_ROOT`), or from an already-initialized project's `.brida/` state.
+- `brida-claude` — resolves only from a checkout or `BRIDA_ROOT`.
+- `brida-herdr-agent-start` — starts a Herdr worker session.
+- `brida-validate-receipts` — validates canonical handoff receipts.
+
+`brida-codex` and `brida-claude` are checkout-oriented and intended for
+development, not standalone installed-project launches. `--help` and `--version`
+work from any directory.
+
+## Contributing
+
+1. Fork it (https://github.com/minhtran3124/Brichan/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the validation suite (`make check`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+## License
+
+Brichan is available under the [MIT License](https://opensource.org/licenses/MIT).

brichan-0.6.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brichan"
+version = "0.6.0"
+description = "Repository-native AI Chief of Staff orchestration"
+# Generated from README.md by scripts/build_pypi_readme.py; see that module
+# for why the published description cannot just be README.md.
+readme = "README_PYPI.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [{name = "Minh Tran"}]
+keywords = ["ai", "orchestration", "codex", "claude-code", "chief-of-staff"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.scripts]
+brida = "brida.cli.runtime:main"
+brida-codex = "brida.cli.codex:main"
+brida-claude = "brida.cli.claude:main"
+brida-herdr-agent-start = "brida.orchestration.worker_launch:main"
+brida-validate-receipts = "brida.contracts.receipts.validation:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"brida.resources.dogfood_v1" = ["**/*"]

brichan-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+