backbone-conductor 0.1.0__tar.gz

backbone_conductor-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "outerarc-ai",
+  "interface": {
+    "displayName": "OuterArc AI"
+  },
+  "plugins": [
+    {
+      "name": "backbone-conductor",
+      "source": {
+        "source": "local",
+        "path": "./plugins/backbone-conductor"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

backbone_conductor-0.1.0/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.venv
+.backbone
+.pytest_cache
+.ruff_cache
+.coverage
+dist
+__pycache__
+.env*

backbone_conductor-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Report a reproducible problem in Backbone Conductor
+title: "bug: "
+---
+
+## What happened?
+
+Describe the behavior and its impact.
+
+## How to reproduce
+
+List the smallest reproducible steps, including the command or interface used.
+
+## Expected behavior
+
+Describe the result you expected.
+
+## Environment
+
+- Backbone Conductor version:
+- Python version and operating system:
+- Git version:
+- Interface used (CLI, HTTP, MCP, Codex plugin, or browser map):
+
+Include relevant error messages after removing tokens, credentials, private repository content, and personal data. For a security issue, follow [SECURITY.md](../../SECURITY.md) instead of opening a public issue.

backbone_conductor-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Propose a product or documentation improvement
+title: "feature: "
+---
+
+## Problem
+
+Which workflow is difficult, and who encounters it?
+
+## Proposed behavior
+
+Describe the observable result you would like.
+
+## Context
+
+Provide a short example and note any compatibility, privacy, or review implications.

backbone_conductor-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What changes
+
+Describe the user-visible behavior and why it is needed.
+
+## Verification
+
+List the checks run and their results. Note any checks that could not be run.
+
+## Compatibility and review
+
+Describe changes to public commands, schemas, Git history, authentication, or approval behavior. Link the relevant issue when one exists.

backbone_conductor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: '0.11.1'
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --group dev
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: BACKBONE_REQUIRE_LIVE_HTTP=1 uv run --no-sync pytest --cov=backbone_conductor --cov-fail-under=85 --cov-report=term-missing
+      - run: uv run --no-sync python scripts/evaluate.py
+      - run: uv run --no-sync python scripts/evaluate_git_merges.py
+      - run: uv run --no-sync python scripts/benchmark_mcp.py --clients 10
+      - run: uv run --no-sync python scripts/benchmark_sync.py --runs 3
+      - run: uv run --no-sync python scripts/benchmark_audit_history.py --updates 12 --page-size 5
+      - run: uv run --no-sync python examples/demo.py
+      - run: uv run --no-sync python examples/two_agent_demo.py
+      - run: uv run --no-sync python examples/two_agent_demo.py --mcp
+      - run: uv build
+      - run: uv run --no-sync python scripts/check_release.py
+  compose:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: '0.11.1'
+          python-version: '3.12'
+      - run: uv sync --locked --group dev
+      - run: uv run --no-sync python scripts/verify_compose.py
+  dsh-runtime:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: '0.11.1'
+          python-version: '3.12'
+      - run: uv sync --locked --group dev --extra dsh
+      - run: BACKBONE_REQUIRE_DSH_MCP=1 BACKBONE_REQUIRE_LIVE_HTTP=1 PYTHONPATH=src uv run --no-sync pytest tests/test_runtime.py::test_installed_sdk_starts_read_only_review_without_shell tests/test_runtime.py::test_installed_sdk_conflict_advice_with_local_mock_provider tests/test_prospective_eval.py::test_installed_sdk_freezes_semantic_study_with_local_mock_provider tests/test_runtime.py::test_installed_sdk_starts_member_mcp_without_model_call tests/test_runtime.py::test_installed_sdk_member_tools_and_in_process_history_with_local_mock_provider tests/test_runtime.py::test_installed_sdk_starts_coordinator_mcp_without_model_call tests/test_mcp_http.py::test_remote_dsh_member_preflight_sdk_and_mock_tool_call tests/test_tls_http.py::test_direct_https_requires_trusted_certificate_and_bearer_token -q

backbone_conductor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build and verify without uploading to PyPI
+        required: true
+        type: boolean
+        default: true
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: '0.11.1'
+          python-version: '3.12'
+      - run: uv sync --locked --group dev
+      - name: Require a version tag for a real release
+        if: ${{ inputs.dry_run == false && github.ref_type != 'tag' }}
+        run: |
+          echo 'A PyPI release must be dispatched from a version tag.' >&2
+          exit 1
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: BACKBONE_REQUIRE_LIVE_HTTP=1 uv run --no-sync pytest --cov=backbone_conductor --cov-fail-under=85
+      - run: uv run --no-sync python scripts/evaluate.py
+      - run: uv run --no-sync python examples/demo.py
+      - run: uv build
+      - name: Verify release archives
+        env:
+          RELEASE_TAG: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
+        run: uv run --no-sync python scripts/check_release.py --tag "$RELEASE_TAG"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+  publish:
+    needs: build
+    if: ${{ inputs.dry_run == false && github.ref_type == 'tag' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

backbone_conductor-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+coverage.xml
+dist/
+*.egg-info/
+.DS_Store
+.env
+.env.*
+!.env.example
+.dsh/
+backbone.db*

backbone_conductor-0.1.0/AGENTS.md

@@ -0,0 +1,16 @@
+# Repository guidance
+
+The implementation, tests, and published documentation in this repository define Backbone Conductor's behavior. Keep changes scoped to this project.
+
+## Implementation and verification
+
+- Python 3.12+, src layout, uv.lock. Install with `uv sync --locked --group dev`.
+- Core models and conflict rules do not depend on any agent runtime.
+- All state mutations go through Conductor and GitStore; do not write `.backbone` directly.
+- Keep Git audit commits separate from unrelated staged source changes.
+- Do not claim semantic checks passed when no model/human review occurred.
+- DSH review is advisory; task completion requires human approval and actual integration into the assigned branch.
+- Validate with `uv run ruff check .`, `uv run ruff format --check .`, `uv run pytest --cov=backbone_conductor --cov-fail-under=85`, `uv run python scripts/evaluate.py` and `uv run python examples/demo.py`.
+- If an environment hides editable `.pth` files, source tests can run with `PYTHONPATH=src .venv/bin/pytest`; verify the built wheel separately.
+
+See docs/IMPLEMENTATION.md for the current architecture and validation boundaries.

backbone_conductor-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First open-source release under OuterArc AI.
+
+- Coordinate intentions, decisions, task assignments, Git artifacts, and approvals in a Git-backed ledger.
+- Inspect decision lineage and intention lifecycles through read-only browser maps.
+- Use role-scoped CLI, HTTP, and MCP interfaces, including the repository's Codex plugin.
+- Verify submitted Git commits, target-branch integration, and approval anchors.
+- Audit ledger snapshots and reachable history; use optional DeepSeek Harness advice without delegating approval authority.
+
+For supported workflows and limitations, see the [documentation](docs/README.md).

backbone_conductor-0.1.0/CONFLICT_RULES.md

@@ -0,0 +1,20 @@
+# 确定性冲突规则
+
+| 规则 | 依据 | 严重级别 |
+| --- | --- | --- |
+| replace_vs_extend | 同符号分别声明 remove/replace 与 extend | remove critical，replace blocking |
+| symbol_scope_overlap | 活跃意图有共同符号，未被上一规则覆盖 | advisory |
+| dependency_conflict | 一个决策 depends_on 与另一个 removes_symbols 相交 | blocking |
+| resource_contention | 意图/任务声明或实际提交相同路径，或目录与子路径相交 | blocking |
+
+终态意图、撤销/替代决策、merged 任务不再产生新冲突。草稿和提议也参与预警。规则依据结构化声明，不能推断任意代码语义。
+
+冲突 ID 取决于规则、级别、双方和证据。重复扫描不重复创建；人工裁决仅沿用到完全相同证据。自动标记为不再适用的冲突重新出现时恢复阻塞。
+
+coordinate、accept_existing、override_existing、accept_risk 记录人工选择和理由并形成决策，本身不修改代码、意图或其他决策。advisory 不阻塞。
+
+制品路径来自固定 Git 提交的 diff；关闭 rename detection，同时检查移动前后路径。使用完整路径段匹配，src/auth 不匹配 src/author.py。全局决策没有 related_intents 时，其冲突适用于所有任务。
+
+运行 `python scripts/evaluate.py` 检查 24 个合成场景；其 precision/recall/F1 不证明真实项目检测率 ≥80%。
+
+另有 [Git 合并案例](evals/GIT_MERGE_CASES.md)，用公开项目的分支路径和 Git 文本冲突标签检查 `resource_contention`。这些案例只说明路径预警相对文本冲突的表现，不能推出意图级准确率。

backbone_conductor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to Backbone Conductor
+
+Thanks for helping improve Backbone Conductor. Please open an issue before substantial interface or storage changes so their compatibility and audit implications can be discussed.
+
+## Development setup
+
+Use Python 3.12 or newer, Git, and uv:
+
+```sh
+git clone https://github.com/outerarc-ai/backbone-conductor.git
+cd backbone-conductor
+uv sync --locked --group dev
+```
+
+Run the project checks before opening a pull request:
+
+```sh
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest --cov=backbone_conductor --cov-fail-under=85
+uv run python scripts/evaluate.py
+uv run python examples/demo.py
+```
+
+CI also runs Python 3.12/3.13, real HTTP and MCP integration tests, Compose deployment checks, example workflows, and package builds. If the local environment hides editable `.pth` files, run source tests with `PYTHONPATH=src .venv/bin/pytest` and verify the built wheel separately.
+
+## Pull requests
+
+- Keep protocol models and conflict rules independent of any agent runtime.
+- Route ledger changes through Conductor and GitStore; do not edit `.backbone/` files directly.
+- Keep metadata audit commits separate from unrelated staged source changes.
+- Include tests for behavior or compatibility changes, and update the relevant guide when a public command, interface, or boundary changes.
+- Describe user-visible behavior, validation performed, and any remaining limitation. Distinguish scripted checks from human review.
+
+The [implementation guide](docs/IMPLEMENTATION.md) explains the current architecture, and [docs/README.md](docs/README.md) indexes the rest of the documentation. The project uses the [MIT License](LICENSE).

backbone_conductor-0.1.0/DSH_INTEGRATION.md

@@ -0,0 +1,70 @@
+# DSH 集成
+
+通过可选的 `dsh` extra 安装 DeepSeek Harness SDK。`uv.lock` 固定依赖版本；模型建议不会改变 Backbone 的确定性检查或审批权限。
+
+DSHReviewer 将任务、意图、已接受决策和真实 diff 作为明确标记为不可信数据的 JSON 随请求提供，在一次性目录内以明确指定的 home 启动 DeepSeekHarness 的 sdk-minimal profile。运行时补丁禁用该 profile 默认的持久 bash/PowerShell 工具，并把文件策略设为 `read-only`；模型审查不需要本地命令或读取仓库。输出必须符合 SemanticReview Schema；非法输出、超时和未完成回合不会生成批准。调用结束关闭 runtime，再核对 Backbone 版本和制品 SHA，拒绝过期结果。成功审查的 `runtime` 字段记录从创建 SDK 客户端到关闭的 `elapsed_ms`、SDK 返回的 `session_id` 与 `finish_reason`，随建议一起进入 Git 审计。失败尝试不修改 Backbone 状态；这些指标不代表模型生成阶段的独立耗时。
+
+审查入口同样要求 DSH home 不为符号链接、由当前用户持有且权限为 0700，以保护其中的会话日志。
+
+可选 `--attempt-log` 记录通过任务和 diff 前置校验后的审查尝试结果。路径必须是仓库和 Git 目录外的绝对路径，父目录仅当前用户可访问（0700），日志文件为仅当前用户可读写的普通文件（0600）；命令会在调用模型前验证该位置。JSONL 事件包含任务 ID、模型/provider 名称、审阅前版本、制品 SHA、结果、阶段和总耗时；失败时另记错误**类型**。不包含提示词、代码 diff、令牌或 provider 原始错误内容。成功审查先写入 Git 审计，随后才记录 `committed` 事件；若这一步日志写入失败，命令会提示审查已提交，应先核对状态再重试。此文件是私有运行指标，不是 Backbone 审计提交，也不保证捕获进程崩溃或前置校验失败。
+
+```sh
+uv sync --locked --extra dsh
+mkdir -m 700 /absolute/private-review-metrics
+uv run backbone --repo /absolute/project review TASK_ID \
+  --dsh-home /absolute/isolated-dsh-home --model YOUR_MODEL \
+  --attempt-log /absolute/private-review-metrics/attempts.jsonl
+uv run backbone --repo /absolute/project review-stats \
+  --attempt-log /absolute/private-review-metrics/attempts.jsonl
+```
+
+`review-stats` 只读汇总该私有日志中的已记录尝试数、已提交数、失败阶段、记录内提交比例和总耗时中位数；这是日志样本的统计，不代表所有请求的真实成功率。旧版仅记录失败的日志会标出 `legacy_failure_records`，其提交比例返回 `null`。token 用量与费用返回 `null`，因为锁定 SDK 的 `RunResult` 没有稳定字段。指标不包含独立模型生成耗时，也不替代 Git 审计中的审查结果。
+
+需在本地配置 provider 凭据，不写入 Git。审查会向该 provider 发送任务和代码 diff；结果只作建议。补丁禁用默认 shell，但指定的 DSH home 若有自定义补丁，仍可能装载其他工具；请使用专用 home 和适当的运行账户。一次性目录与只读工具策略不限制 Harness 进程自身的 OS 权限或向 provider 发送数据。
+
+## 意图配对语义建议
+
+`backbone conflict advise INTENT_A INTENT_B --dsh-home /absolute/private-home --model YOUR_MODEL` 在实施前比较两份非终态意图。输入仅包含两份意图的计划字段、相关已接受决策、当前确定性冲突证据与观察到的账本版本，限 1 MB；不传代码 diff。返回 Schema 限定的 `conflict / compatible / uncertain` 建议、理由、证据和协调建议，并附输入 SHA-256、运行元数据与是否因并发账本变化而过期的标记。该入口只读，不会把模型建议写成 Backbone 冲突、解除阻塞或批准合并。调用会将这些协调数据发送给配置的 provider。此接口不提供经独立标注的语义准确率保证。
+
+## 受限协调代理
+
+`backbone conductor` 在本地仓库启动 DSH `sdk-minimal`，以一次性只读工作目录和私有补丁连接 `backbone mcp --coordinator`。该 MCP 服务**只**公开读取完整协调状态、创建 `conductor-agent` 作者的草稿意图、提出同作者的建议决策、检测确定性冲突、分派已接受意图、读取固定提交审查包六项工具。意图接受、决策接受、冲突仲裁、任务合并审批及远端同步均不在工具列表中；运行前独立 MCP 握手要求精确工具集合并读取状态，若权限扩大则拒绝启动模型。DSH 补丁禁用默认持久 shell，并将文件策略设为只读。模型不能通过这些工具完成需要人类审查的状态转换。
+
+```sh
+uv sync --locked --extra dsh
+uv run backbone --repo /absolute/project conductor \
+  --dsh-home /absolute/private-coordinator-home --model YOUR_MODEL \
+  --prompt "读取当前状态，提出待人审查的计划并分派已接受工作"
+```
+
+可用 `--ledger-branch backbone` 指定独立元数据分支，可用 `--session-id` 指定该仓库命名空间内的会话 ID，并用 `--prompts-file` 提供 JSON 字符串数组，在单次运行中连续执行多回合；锁定 SDK 在进程结束后不能恢复已持久化的同 ID 会话。DSH home 必须在仓库外，由当前用户持有且仅当前用户可访问（0700）；会话日志在该 home 中。调用模型时，协调状态和由 `inspect_task` 读取的代码审查包可能发送给所配置的 provider。MCP 子进程仍以运行者的 OS 权限访问本地仓库，DSH 工具策略不是 OS 隔离；专用 home 若装有额外插件，还需单独审查其能力。请以专用运行账户和合适的 Git 文件权限运行。模型输出的质量取决于所配置的 provider，应由使用者核对。
+
+## 成员代理接入
+
+`backbone dsh` 使用同一可选 SDK 的 `sdk-minimal` profile，在临时补丁中装载 `@deepseek-ai/dsh-mcp-client`，启动绑定 `--member` 的 Backbone stdio MCP 服务。调用模型前，Python 端另起一次 MCP 连接，核对初始化、工具列表、成员上下文，并拒绝管理员工具泄露。`--workspace` 必须是与协调仓库分开的现存目录，`--dsh-home` 必须位于两者之外；补丁把 DSH 工具写入策略设为 `workspace-write`，并在系统提示中要求通过 MCP 操作协调元数据。独立元数据分支可在 `dsh` 子命令前传入 `--ledger-branch backbone`。
+
+```sh
+uv sync --locked --extra dsh
+uv run backbone --repo /absolute/project dsh --member alice \
+  --workspace /absolute/separate-worktree \
+  --dsh-home /absolute/isolated-dsh-home --model YOUR_MODEL \
+  --prompt-file /absolute/task-prompt.txt
+```
+
+多回合时，`--prompts-file` 指向形如 `["读取我的任务", "检查刚才提出的方案"]` 的 JSON 文件，替代 `--prompt` 或 `--prompt-file`。返回值列出每一回合的完成状态、最终文本和耗时；同一会话中的后一回合可以看到前一回合的模型消息与 MCP 工具结果。也可使用 `--interactive` 按行输入新提示，每轮结果立即作为一行 JSON 写到 stdout；空行跳过，`:quit`、`:exit` 或 EOF 结束。交互会话仍使用同一 SDK 进程，退出后不能恢复旧会话。协调代理和远程成员同样支持这两种多回合方式。
+
+本地成员入口会创建或核对 DSH home：拒绝符号链接，要求它位于协调仓库和代码工作区之外、由当前用户持有且权限为 0700。此入口会实际向配置的 provider 发起模型请求；必须由操作者自行配置凭据。返回的会话 ID 带仓库与成员命名空间，可用 `--session-id` 指定该成员命名空间内的会话 ID；其他命名空间的 ID 会被拒绝。`--prompts-file` 接受 JSON 字符串数组，让本地或远程成员在同一 SDK 进程中连续执行多个回合并继承上下文。锁定 SDK 0.1.5rc1 在进程重启后对已持久化的同 ID 会话返回 `already exists`；Backbone 会明确提示此限制，保留旧日志，不会悄悄创建一个伪续接会话。DSH 最小 profile 的 shell 与 MCP 子进程仍以调用者的 OS 身份运行；`workspace-write` 限制模型工具的写入范围，但不构成完整的读取或网络隔离。MCP `--member` 是本地工具约束，不是不同自然人之间的认证。会话日志保存在指定的 DSH home；不要把凭据或敏感日志放入 Git。模型建议、工具调用和代码修改都不能替代人工复核及真实 Git 合并。
+
+远程成员入口改用已启用的 `/mcp` HTTPS 服务，无需本地协调仓库。`--mcp-url` 和 `--mcp-token-file` 必须同时指定；URL 只能是 HTTPS `/mcp`，回环测试地址可用 HTTP。令牌文件须由当前用户持有、权限为 0600、硬链接数为 1，且位于工作树和专用 DSH home 外；DSH home 须为当前用户持有的 0700 目录。可用 `--mcp-ca-file` 信任自签证书。正式 DSH MCP 客户端插件采用 `streamable-http` transport 与 Authorization header；调用模型前，独立的 Python MCP 会话以同一令牌验证实际成员身份与精确工具范围。一次性补丁为 0600，含本回合明文 bearer header，用完删除；指定的 DSH home、进程权限和运行日志仍须按敏感数据管理。会话 ID 按远程 URL 与成员命名空间绑定，令牌轮换后需更新私有文件并重启回合。
+
+```sh
+uv run backbone dsh --member alice \
+  --workspace /absolute/separate-worktree --dsh-home /absolute/private-dsh-home \
+  --mcp-url https://coordinator.example/mcp \
+  --mcp-token-file /absolute/private/alice.token \
+  --model YOUR_MODEL --prompt-file /absolute/task-prompt.txt
+```
+
+自动化检查覆盖 SDK 启动、MCP 工具范围、模拟 provider 调用和 Git 审计归属。这些检查不提供真实模型质量、费用或公网部署性能的保证。SDK `RunResult` 没有稳定的 token 用量与费用字段，因此 `review-stats` 不推算费用。
+
+依据：[DSH 官方 Python SDK](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md)、[SDK 入门](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md)、[DSH MCP 客户端](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md)及[跨进程会话恢复问题](https://github.com/deepseek-ai/deepseek-harness/discussions/6295)。MCP 服务端使用 [官方 MCP Python SDK v1](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x)，固定 `<2` 避免主版本 API 变化。

backbone_conductor-0.1.0/Dockerfile

@@ -0,0 +1,14 @@
+ARG PYTHON_IMAGE=python:3.12-slim
+FROM ${PYTHON_IMAGE}
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /opt/backbone
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir . \
+    && git config --system user.name 'Backbone Conductor' \
+    && git config --system user.email 'backbone@localhost' \
+    && git config --system safe.directory /workspace
+WORKDIR /workspace
+ENTRYPOINT ["backbone"]
+CMD ["--repo", "/workspace", "serve", "--host", "0.0.0.0", "--port", "8000", "--auth-file", "/run/secrets/backbone-http-tokens.json"]

backbone_conductor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BruceXcluding
+
+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.

backbone_conductor-0.1.0/MCP_API.md

@@ -0,0 +1,68 @@
+# MCP API 与 Agent 接入
+
+启动 `backbone --repo /absolute/repo mcp --member alice`，使用官方 MCP SDK 的 stdio 传输。stdout 仅用于协议。
+
+| 工具 | 参数 | 返回 |
+| --- | --- | --- |
+| get_my_task | member_id? | 任务、意图、约束、决策、冲突 |
+| create_intent | intent_data | draft 意图 |
+| log_decision | decision_data | proposed 决策 |
+| start_task | task_id, member_id? | in_progress 任务 |
+| fetch_artifact_branch | task_id, branch, expected_sha, member_id?, remote? | 从已配置 Git 远端获取指定提交的成员代码分支 |
+| rebase_task | task_id, expected_version, member_id? | 刷新目标分支与决策上下文 |
+| submit_artifact | artifact, member_id? | Git 证据、检查、冲突 |
+| check_backbone_sync | member_id?, since_version? | 当前版本、新增/撤回决策、阻塞冲突 |
+
+绑定成员时可省略 member_id；冒用其他成员或 author 会报错。artifact 至少含 intent_id、branch、summary，base_ref 默认为 main，且必须匹配任务目标分支。
+
+新仓库采用独立元数据分支时，在启动 MCP 服务的 `mcp` 子命令前加全局选项 `--ledger-branch backbone`；`--repo` 仍指向代码仓库。
+
+省略 `--member` 为本地管理员进程，额外暴露 dispatch_task、transition_intent、transition_decision、revert_decision、revise_intent、replace_intent、review_intent、cancel_task、detect_conflicts、resolve_conflict、inspect_task、merge_task、verify_audit_signatures、refresh_backbone、reconcile_backbone。`replace_intent` 接受 intent_id、字段 patch、author、reason 和 expected_version；旧意图须已接受且没有活跃任务。`review_intent` 接受 intent_id、accepted/rejected outcome、reviewer、rationale 和 expected_version；仅能审查他人草稿。`revert_decision` 需要 decision_id、author、rationale 和 expected_version，只能撤回已接受决策并留下审计证据。`verify_audit_signatures` 只检查最近 limit 个元数据提交并返回有效、未签名和无效数量。不得将其当作远程认证服务。
+
+`mcp --coordinator` 是单独的本地受限工具范围，只含 `get_coordination_state`、`create_intent`、`log_decision`、`detect_conflicts`、`dispatch_task` 和 `inspect_task`。创建的草稿意图与建议决策固定归属 `conductor-agent`；分派仍须事先由人接受意图。该范围不含 `review_intent`、`transition_intent`、`transition_decision`、`revert_decision`、`resolve_conflict`、`merge_task` 或远端同步；没有远程 HTTP 协调代理入口。可由 `backbone conductor` 的 DSH 运行器启动，运行前会核对精确工具列表及状态读取。它是本机 OS 账户内的工具限制，不是独立身份认证或进程隔离。
+
+工具 Schema 由 MCP tools/list 提供；领域 Schema 可由 `backbone schema` 或 HTTP `/schema` 获取。
+
+## Codex
+
+先安装本项目。替换两个绝对路径：
+
+```sh
+codex mcp add backbone -- /absolute/backbone-conductor/.venv/bin/backbone \
+  --repo /absolute/your-project mcp --member alice
+```
+
+或配置 stdio server：
+
+```toml
+[mcp_servers.backbone]
+command = "/absolute/backbone-conductor/.venv/bin/backbone"
+args = ["--repo", "/absolute/your-project", "mcp", "--member", "alice"]
+```
+
+配置已对照本机 CLI 和 [OpenAI 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) 核实。项目不会自动修改全局客户端设置。其他 stdio MCP 客户端可使用相同 command/args。
+
+Codex 插件将受限成员或协调者 MCP 与意图工作流程打包，安装与使用方法见 [Codex 插件指南](docs/CODEX_PLUGIN.md)。远端成员也可运行 `backbone mcp-remote-member --url https://coordinator.example.org:8443/mcp --member alice --token-file /private/alice.token`，将已认证的 HTTPS 成员 MCP 桥接为本机 stdio；启动前核对成员身份与精确八工具范围，每次调用从私有文件重新读取令牌。插件启动器使用环境变量配置同一桥接，不需要成员本地持有协调仓库。
+
+可选 DeepSeek Harness 成员代理可直接通过 `backbone dsh --member ... --workspace ... --dsh-home ... --model ... --prompt ...` 连接同一成员绑定服务；完整命令及运行边界见 [DSH_INTEGRATION.md](DSH_INTEGRATION.md)。
+
+## 远程成员接入
+
+`serve --auth-file /private/tokens.json --mcp-http` 在同一服务的 `/mcp` 开启无状态 Streamable HTTP。它只暴露上表八个成员工具；每个请求都用现有私有凭据文件核对 bearer 令牌，把 member_id 和 author 绑定到令牌 principal。管理员与审查者令牌不能进入该 MCP 端点，成员不能通过请求参数冒用其他成员。令牌原子轮换后立即生效，凭据文件损坏或权限不安全时端点返回 503。工具调用产生的 Git 审计提交记录已认证的 HTTP principal/role。
+
+远程客户端连接 `https://coordinator.example.org:8443/mcp`，发送 `Authorization: Bearer <成员令牌>`；启动时增加 `--mcp-allowed-host coordinator.example.org:8443`，使传输层接受该实际 Host header。该参数接受 Host 值，不接受 URL 或通配符。默认只接受本机回环地址。部署时应使用可信 HTTPS 或可信代理并隔离协调仓库的 OS 写权限；静态 bearer 令牌不是 OAuth 授权服务器，也不能证明令牌背后的自然人身份。此入口不主动向 Agent 会话推送任务，仍由客户端调用 `get_my_task` 拉取。
+
+没有可配置静态 bearer 的 MCP 客户端时，可用 `backbone member --url https://coordinator.example.org:8443 --token-file /private/path/alice.token tasks` 通过同一认证服务读取任务；后续 `start`、`updates`、`rebase`、`fetch`、`submit` 及提案命令见[远程成员 CLI](docs/OPERATIONS.md#远程成员-cli)。该 CLI 是人可直接使用的 HTTP 客户端，不改变 MCP 的工具范围或权限模型。
+
+ASGI 挂载与会话管理遵循 [官方 MCP Python SDK 的部署说明](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/run/asgi.md)；当前仅验证锁定的 MCP 1.x 版本。
+
+## 成员流程
+
+1. 获取任务，阅读约束与决策，调用 start_task。
+2. 在独立代码分支/worktree 实现，期间调用 check_backbone_sync。
+3. 提交并推送代码，调用 fetch_artifact_branch 传入功能分支和完整提交 SHA，再以返回的 tracking_ref 和相同 commit_sha 调用 submit_artifact。
+4. 阻塞冲突交给管理员裁决；通过后仍需人工审查和真正的 Git 合并。
+
+协调端保持在目标分支。get_my_task 是拉取接口；首版不主动向 Agent 会话推送消息。
+当 check_backbone_sync 返回 new_decisions 或 withdrawn_decisions，成员应执行 rebase_task，使用当前 version 作为 expected_version，再提交制品。提交后才发生的决策变化由管理员在 merge_task 的 rationale 中明确审查并记录。
+代码实际合入目标分支后，管理员须重新调用 `inspect_task`，从结果取 `version` 和 `git.target_sha`，作为 `merge_task` 的 `expected_version` 与 `expected_target_sha`；若审查后账本或目标分支变化，调用被拒绝并须重新审查。完成后 `inspect_task` 可用审批时保存的账本版本和目标 SHA 重读当时的审查包，并单独报告当前版本与当前目标 SHA；旧完成任务若没有结构化锚点，则明确拒绝伪装历史审查。

backbone_conductor-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: backbone-conductor
+Version: 0.1.0
+Summary: Git-native intent and decision coordination for coding agents
+Project-URL: Repository, https://github.com/outerarc-ai/backbone-conductor
+Project-URL: Documentation, https://github.com/outerarc-ai/backbone-conductor/tree/main/docs
+Project-URL: Issues, https://github.com/outerarc-ai/backbone-conductor/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: filelock<4,>=3.32.7
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<2,>=1.12
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: uvicorn<1,>=0.34
+Provides-Extra: dsh
+Requires-Dist: deepseek-harness-sdk<1,>=0.1; extra == 'dsh'
+Description-Content-Type: text/markdown
+
+# Backbone Conductor: Git-native coordination for coding work
+
+[![CI](https://github.com/outerarc-ai/backbone-conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/outerarc-ai/backbone-conductor/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/backbone-conductor.svg)](https://pypi.org/project/backbone-conductor/)
+[![Python](https://img.shields.io/pypi/pyversions/backbone-conductor.svg)](https://pypi.org/project/backbone-conductor/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[简体中文](README.zh-CN.md) · [Documentation](docs/README.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
+
+Backbone Conductor keeps intentions, decisions, assignments, and review evidence together in Git. Teams can agree on the work before implementation, compare submitted changes with the agreed scope, and record approval against the code that was actually merged. The core runs without a model provider.
+
+## Why Backbone Conductor
+
+- **Shared intent.** Record the purpose, constraints, affected symbols, and expected paths before work begins.
+- **Decision lineage.** Link decisions to intentions and inspect superseded or reverted decisions in a browser map.
+- **Verified delivery.** Tie each task to a specific Git commit, check its declared scope, and inspect the integrated target branch.
+- **Auditable review.** Record who approved a task, which ledger version they observed, and which target commit they reviewed.
+- **Flexible interfaces.** Use the CLI, HTTP API, MCP tools, or the repository's Codex plugin. A read-only lifecycle map connects intentions to tasks, artifacts, and approvals.
+
+Deterministic checks identify declared conflicts and Git-path overlap; they do not establish semantic correctness. Optional DeepSeek Harness advice is advisory. People remain responsible for decisions, code review, and Git integration.
+
+## Install
+
+Requires Python 3.12+ and Git:
+
+```sh
+python -m pip install backbone-conductor==0.1.0
+backbone --help
+```
+
+To run the examples from source, install [uv](https://docs.astral.sh/uv/) and use:
+
+```sh
+git clone https://github.com/outerarc-ai/backbone-conductor.git
+cd backbone-conductor
+uv sync --locked --group dev
+uv run python examples/demo.py
+uv run python examples/two_agent_demo.py --mcp
+```
+
+The examples create temporary repositories and do not change this checkout. Their participants and approvals are scripted demonstration data.
+
+## Start a project
+
+Run these commands in a Git repository that already has an initial commit:
+
+```sh
+backbone --repo /absolute/path/to/project init
+backbone --repo /absolute/path/to/project status
+backbone --repo /absolute/path/to/project serve
+```
+
+The local API is available at `http://127.0.0.1:8000/docs`. Open `/decision-map` to browse decision lineage and `/lifecycle-map` to follow intentions through assignments, Git artifacts, and approvals. Both views are read-only and support search, dragging, and zooming. Authenticated members see work within their role; reviewers and administrators see the complete graph.
+
+The typical workflow is:
+
+1. Propose an intention with scope and constraints; a reviewer accepts it.
+2. Assign a task and implement it in a Git branch.
+3. Submit the branch and exact commit as an artifact. Backbone checks scope, decisions, and blocking conflicts.
+4. Review the complete patch and merge the code into the target branch.
+5. Record approval against the observed ledger version and merged target commit.
+
+For Codex, the [plugin guide](docs/CODEX_PLUGIN.md) explains installation and role-bound MCP access. The [operations guide](docs/OPERATIONS.md) covers authenticated remote access, synchronization, and recovery.
+
+## Documentation
+
+| Guide | Contents |
+| --- | --- |
+| [Overview](docs/README.md) | Documentation index |
+| [Implementation](docs/IMPLEMENTATION.md) | Architecture and review boundaries |
+| [Operations](docs/OPERATIONS.md) | Deployment, credentials, synchronization, and recovery |
+| [MCP API](MCP_API.md) | Tool scopes and transports |
+| [Conflict rules](CONFLICT_RULES.md) | Deterministic checks |
+| [DSH integration](DSH_INTEGRATION.md) | Optional semantic advice |
+| [Validation](docs/VALIDATION.md) | Reproducible verification and evidence limits |
+| [Releasing](docs/RELEASING.md) | Package build and publishing process |
+
+Issues and pull requests are welcome. See [Contributing](CONTRIBUTING.md) for setup and review expectations. Backbone Conductor is released under the [MIT License](LICENSE).