brichan 0.5.0__py3-none-any.whl

brichan-0.5.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: brichan
+Version: 0.5.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
+
+![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 not published to a package registry yet; the planned PyPI
+distribution name is `brichan` (`pip install brichan`), while the importable
+package stays `brida` and every console command keeps its existing name.
+Until it is published, build the wheel locally from this repository with 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
+```
+
+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.5.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+brichan-0.5.0.dist-info/licenses/LICENSE,sha256=9XdXK_INnKeX43x8WI6sIBknvaELPBF64IjF39Hkaas,1066
+brida/__init__.py,sha256=6TP3n7y8nk_HGMjPKHLpja53qNufdyO8a92fHnEscCk,68
+brida/lifecycle.py,sha256=A7XBRW6GuWtFKzTFqpiu0Eff4n6JhlUMvz4_8uphyjI,10932
+brida/project.py,sha256=Zi4tH0_V69VQJNNovB_--rDqVRAQEmI6ZBifx6glf0Y,1816
+brida/cli/__init__.py,sha256=-WeS-o4ivaNlUCWmEkRbq-qmyMGGWImHkpsSMGGfKBg,45
+brida/cli/_root.py,sha256=1MpUoMCJK51DieyE68-3Rq45wCIiQmGHWgmS1P4Zm84,708
+brida/cli/claude.py,sha256=rFkrKaLp5IXNk9GqbISs2YnVtq3szrInnFFHuZ9zHTA,1786
+brida/cli/codex.py,sha256=UGWzeE6CCtTT1x0B_sc0wqKDqTOPUDNx0RhSxjbSvzE,3903
+brida/cli/provider_commands.py,sha256=nvWFbFKR9dx9QixUt4BaRZF-kF6xqsVfGOhAAW0Nut4,14067
+brida/cli/runtime.py,sha256=_FVI1U5iWMwXEovWAD9BsUvrVxYkRtSCpBlHmyMpGbc,6129
+brida/contracts/__init__.py,sha256=Va71T-aZ4_6gsWQ1f2-MK11_cWUK-HlU2OJ5WW4wG8M,31
+brida/contracts/receipts/__init__.py,sha256=XLX3G9j2XSyo14tFLCxm_t6B0zFqCZyHkRHlBoFJH8M,340
+brida/contracts/receipts/discovery.py,sha256=LOvvHwv7JF3ARpUtKWzkdzRROlV8balNedsHqArsFwY,115
+brida/contracts/receipts/parser.py,sha256=ef8mCjPhyGpn7BYzPwhICHp3sPdKbakDkfwbcIsIlOs,127
+brida/contracts/receipts/schema.py,sha256=OXSBHmxvddvVZn0nuVKRHS_WQ3REMbJWfwzYj69RSf8,807
+brida/contracts/receipts/validation.py,sha256=Vt3AM1OwMDJ-BU25Xihxnf3Xp55QMD4AJod9hd7BiNM,35492
+brida/orchestration/__init__.py,sha256=zJ29vdNooU0vdsm39em21taAAqdXvAa_b4bmuw_wpEs,453
+brida/orchestration/herdr_client.py,sha256=x0aOSOZ3WZtxiH1beciztcYh5PK67F795VXJjxd4aJM,207
+brida/orchestration/layout.py,sha256=QJF6sdfj6P4pMtdCGrdD0AH52lErxlVVC66KqJAEUxE,154
+brida/orchestration/model_routing.py,sha256=ifdlYgtyZ_DEaOu5p1ILlvBODR5FxDij5ny6HMm0ljA,9092
+brida/orchestration/worker_launch.py,sha256=yk6l_jRcEOzYpF9-v_2LXMotLYvnDE13FoRdulu-qBU,15620
+brida/resources/__init__.py,sha256=7GEpLlpkVEZme8RnxNlCnLzD_uLikBA_88GEXx4spx8,40
+brida/resources/dogfood_v1/__init__.py,sha256=L78bUjJrs4arq1LDoO59UdiVY4xQ5jTbekraVBFs0A4,45
+brida/resources/dogfood_v1/config/model-routing.json,sha256=FiWJdemnKZVEu83WN4qX0B-w2I0BlJm17zJlSPiROag,710
+brida/resources/dogfood_v1/policy/bootstrap.md,sha256=_w8q-EIlZco5QeMNj_Ec0xZNfBKykaxMPhn2OJuG7OA,1094
+brida/resources/dogfood_v1/policy/identity.md,sha256=s9ITrFrsTJ4EAR8KXN_bWZi_2UbZ1sYX0XEnSQusRo0,846
+brida/resources/dogfood_v1/policy/memory-policy.md,sha256=T2aWpntloiiCNK962JNPhBMGRxjCgbb4XFaxJ-YLffA,647
+brida/resources/dogfood_v1/policy/operating-principles.md,sha256=9mgsHhpW_AWI3-bunGNnvkFJphkefzZs5O-6Frza_70,779
+brida/resources/dogfood_v1/project-memory/index.md,sha256=PhLkcqvVkfOeTTaKkDqkgpQHmvEmKY2efKE7z_F-L_k,149
+brida/resources/dogfood_v1/project-memory/main/current-state.md,sha256=edsLUKxloOFEsXmxx1XN8HlMwpPto7TOS4BUiOvi1HQ,163
+brida/resources/dogfood_v1/project-memory/main/decisions.md,sha256=7YFB4XErRSqtn8G_DkYLvDRVMET12PWyDZJWokjtJvI,91
+brida/resources/dogfood_v1/project-memory/main/overview.md,sha256=0ZSZvrBXixQucghtnPIHFzrUXBAQ8mGe6donHGDqtSA,182
+brida/resources/dogfood_v1/project-memory/main/references.md,sha256=QK-QLajcACshlEHGhDsAH_7BKX2PeTQ5eoABQ4Pd4LE,68
+brida/resources/dogfood_v1/project-memory/main/tasks.md,sha256=bTnFf-vkOb6hfbqtaNeYWwn0yhL5gQEz7DVH48fcDFk,196
+brida/resources/dogfood_v1/skills/herdr-orchestration/SKILL.md,sha256=Wn1R5chYYO8oZ2lABsOY7fX9TV7_u2Qiy-DStnQbIMs,1064
+brida/resources/dogfood_v1/skills/herdr-orchestration/references/commands.md,sha256=-aD6JS8M6aGl64fMm-m9VzOh3bMRLDDG_4m7xyVZ6Is,678
+brida/resources/dogfood_v1/skills/herdr-orchestration/references/task-packet.md,sha256=7nmPVPIveATBeqVuOYo0rPFmZzIvPKd3BUaSLwHmvo4,616
+brichan-0.5.0.dist-info/METADATA,sha256=cfqYf5K8eg59GUOszobjhBTGZkobaHOjULCkHKr7NIA,8026
+brichan-0.5.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+brichan-0.5.0.dist-info/entry_points.txt,sha256=9NZhQ3yZ70QED5FHpl0d4_gO75RJUDcI_DHnj41ml6s,253
+brichan-0.5.0.dist-info/top_level.txt,sha256=RJpGCwKsFy7LBiknV_FtTiR0OBrJXUR9XDDruQxH4AA,6
+brichan-0.5.0.dist-info/RECORD,,

brichan-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brichan-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+brida = brida.cli.runtime:main
+brida-claude = brida.cli.claude:main
+brida-codex = brida.cli.codex:main
+brida-herdr-agent-start = brida.orchestration.worker_launch:main
+brida-validate-receipts = brida.contracts.receipts.validation:main

brichan-0.5.0.dist-info/licenses/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.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+brida

brida/__init__.py

@@ -0,0 +1,3 @@
+"""Brida's importable orchestration core."""
+
+__version__ = "0.5.0"

brida/cli/__init__.py

@@ -0,0 +1 @@
+"""Stable Brida command-line entrypoints."""

brida/cli/_root.py

@@ -0,0 +1,23 @@
+"""Repository-root resolution shared by source and installed CLI adapters."""
+
+import os
+from pathlib import Path
+
+
+def repository_root() -> Path:
+    override = os.environ.get("BRIDA_ROOT")
+    if override:
+        return Path(override).resolve()
+
+    current = Path.cwd().resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / "AGENTS.md").is_file() and (candidate / "bin").is_dir():
+            return candidate
+
+    source_root = Path(__file__).resolve().parents[3]
+    if (source_root / "AGENTS.md").is_file():
+        return source_root
+    raise RuntimeError(
+        "cannot locate the Brida repository root; run inside the repository "
+        "or set BRIDA_ROOT"
+    )

brida/cli/claude.py

@@ -0,0 +1,58 @@
+"""Claude Code runtime adapter."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ._root import repository_root
+from brida import __version__
+from brida.orchestration.model_routing import (
+    RoutingError,
+    load_settings,
+    resolve_coordinator,
+)
+from .provider_commands import claude_command
+
+
+def command(argv: list[str], environment: dict[str, str]) -> list[str]:
+    root = repository_root()
+    settings = load_settings(repository=root, environment=environment)
+    compatibility_model = environment.get("BRIDA_CLAUDE_COORDINATOR_MODEL") or None
+    route = resolve_coordinator(
+        settings,
+        "claude",
+        model=compatibility_model,
+    )
+    return claude_command(route, argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    try:
+        os.chdir(repository_root())
+        resolved_command = command(arguments, os.environ)
+    except RoutingError as exc:
+        print(f"brida-claude: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        if arguments[:1] in (["--help"], ["-h"]):
+            print("usage: brida-claude [claude arguments...]")
+            print()
+            print(
+                "brida-claude is checkout-oriented: run it from within the "
+                "Brida source checkout, or with BRIDA_ROOT set. It is not "
+                "part of the Codex-first installed-project workflow."
+            )
+            return 0
+        if arguments[:1] in (["--version"], ["-V"]):
+            print(f"brida-claude {__version__}")
+            return 0
+        print(f"brida-claude: {exc}", file=sys.stderr)
+        return 2
+    os.execvp("claude", resolved_command)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

brida/cli/codex.py

@@ -0,0 +1,118 @@
+"""Codex runtime adapter."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ._root import repository_root
+from brida import __version__
+from brida.lifecycle import StateKind, inspect_project
+from brida.orchestration.model_routing import (
+    RoutingError,
+    load_settings,
+    resolve_coordinator,
+)
+from brida.project import ProjectPaths, ProjectError, project_paths
+from .provider_commands import codex_command, codex_project_command
+
+
+def command(
+    argv: list[str],
+    environment: dict[str, str] | None = None,
+) -> list[str]:
+    env = os.environ if environment is None else environment
+    root = repository_root()
+    settings = load_settings(repository=root, environment=env)
+    route = resolve_coordinator(settings, "codex")
+    return codex_command(route, argv, cwd=root)
+
+
+def project_command(
+    paths: ProjectPaths,
+    argv: list[str],
+    environment: dict[str, str] | None = None,
+) -> list[str]:
+    """Resolve a package-owned command for one initialized Git project."""
+
+    env = os.environ if environment is None else environment
+    inspection = inspect_project(paths)
+    if inspection.kind is not StateKind.HEALTHY:
+        raise RoutingError(
+            f"project state is {inspection.kind.value}: {inspection.detail}"
+        )
+    settings = load_settings(
+        paths.state_root / "config" / "model-routing.json",
+        environment=env,
+    )
+    route = resolve_coordinator(settings, "codex")
+    bootstrap_path = paths.state_root / "policy" / "bootstrap.md"
+    try:
+        bootstrap = bootstrap_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RoutingError(f"cannot read Brida bootstrap policy: {exc}") from exc
+    developer_instructions = (
+        f"{bootstrap.rstrip()}\n\n"
+        f"Target project root: {paths.project_root}\n"
+        f"Mutable Brida state root: {paths.state_root}\n"
+        "Use only package-owned Brida launchers; never execute target-repository "
+        "bin/brida-* wrappers."
+    )
+    return codex_project_command(
+        route,
+        argv,
+        cwd=paths.project_root,
+        developer_instructions=developer_instructions,
+        skill_path=paths.state_root / "skills" / "herdr-orchestration",
+    )
+
+
+def run_project(
+    paths: ProjectPaths,
+    argv: list[str],
+    environment: dict[str, str] | None = None,
+) -> int:
+    resolved_command = project_command(paths, argv, environment)
+    os.chdir(paths.project_root)
+    os.execvp("codex", resolved_command)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    try:
+        paths = project_paths()
+        if paths.state_root.exists():
+            return run_project(paths, arguments, os.environ)
+    except (ProjectError, RoutingError) as exc:
+        if not isinstance(exc, ProjectError):
+            print(f"brida-codex: {exc}", file=sys.stderr)
+            return 2
+        pass
+    try:
+        resolved_command = command(arguments, os.environ)
+    except RoutingError as exc:
+        print(f"brida-codex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        if arguments[:1] in (["--help"], ["-h"]):
+            print("usage: brida-codex [codex arguments...]")
+            print()
+            print(
+                "brida-codex is checkout-oriented: run it from within the "
+                "Brida source checkout (or with BRIDA_ROOT set), or inside a "
+                "Git project initialized with 'brida init --apply' for the "
+                "installed-project workflow."
+            )
+            return 0
+        if arguments[:1] in (["--version"], ["-V"]):
+            print(f"brida-codex {__version__}")
+            return 0
+        print(f"brida-codex: {exc}", file=sys.stderr)
+        return 2
+    os.execvp("codex", resolved_command)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())