solo-builder-core 0.4.0__tar.gz

solo_builder_core-0.4.0/LICENSE

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

solo_builder_core-0.4.0/NOTICE.md

@@ -0,0 +1,39 @@
+# NOTICE — Open core vs. commercial Strix
+
+`solo-builder-core` is open source (MIT) and is meant to be run, forked, and
+audited freely. Its value — and what stays open — is the **verifiable proof**
+it produces: provenance attestations, replay packs, and bounded action-token
+receipts, all signed against the canonical Strix JWKS so an external auditor
+can verify what the agent did **without trusting us, you, or the runtime**.
+
+## What this package is
+
+A **local / self-hosted** governed shipping agent. The enforcement primitives
+it ships — `action_tokens.py`, `approvals.py`, `tool_policy.py`,
+`custody.py`, `anomaly_engine.py`, `evidence_store.py` — run in-process and
+are sufficient for a single operator governing their own agent locally.
+
+You can verify everything it emits using only open tooling:
+
+- the MIT `@strixgov/sdk` / `@strixgov/verifier` and the public JWKS, and
+- the offline Python auditor `strix-verify`.
+
+## What is **commercial Strix** (not this package)
+
+The **production control plane** is a separate, commercial product. It is not
+included here and is not reconstructable from this repository:
+
+- hosted, multi-tenant **policy decisions** and policy authority
+- multi-tenant **enforcement** and tenant isolation
+- hosted **evidence retention**, the Trust Center, and proof surfaces
+- signing-**key lifecycle** management, rotation, and revocation distribution
+- approval routing, SIEM/GRC integrations, and compliance evidence packaging
+
+In other words: this package lets you **produce and verify receipts** locally.
+Operating those receipts as governed, multi-tenant, enterprise infrastructure —
+with hosted policy authority and key management — is commercial Strix.
+
+> Open the proof; sell the control. The local enforcement here is a
+> self-hosted variant, not the production authority. If you are relying on
+> Strix for multi-tenant enforcement, hosted evidence, or key custody, that is
+> the commercial platform — talk to us.

solo_builder_core-0.4.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: solo-builder-core
+Version: 0.4.0
+Summary: Strix Labs Shipping Factory CLI
+Author: Strix Labs
+License: MIT
+Project-URL: Homepage, https://www.strixgov.com
+Project-URL: Repository, https://github.com/Tarshann/solo-builder-core
+Project-URL: Documentation, https://github.com/Tarshann/solo-builder-core/blob/main/docs/MANUAL.md
+Project-URL: Changelog, https://github.com/Tarshann/solo-builder-core/blob/main/CHANGELOG.md
+Project-URL: Pricing, https://github.com/Tarshann/solo-builder-core/blob/main/commercial-launch/pricing/PRICING.md
+Project-URL: Security, https://github.com/Tarshann/solo-builder-core/blob/main/SECURITY.md
+Keywords: shipping-factory,solo-builder,strix-labs,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: tree-sitter==0.26.0
+Requires-Dist: tree-sitter-typescript==0.23.2
+Requires-Dist: tree-sitter-javascript==0.25.0
+Requires-Dist: requests>=2.31
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-frontmatter>=1.0
+Requires-Dist: cryptography>=42
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40; extra == "ai"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: completion
+Requires-Dist: argcomplete>=3.4; extra == "completion"
+Provides-Extra: linkedin
+Requires-Dist: openpyxl>=3.1; extra == "linkedin"
+Provides-Extra: governed-outbound
+Requires-Dist: fastapi<1,>=0.115; extra == "governed-outbound"
+Requires-Dist: httpx>=0.27; extra == "governed-outbound"
+Provides-Extra: governed-outbound-postgres
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "governed-outbound-postgres"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff==0.15.17; extra == "dev"
+Requires-Dist: mypy==1.20.2; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: requests-mock>=1.12; extra == "dev"
+Requires-Dist: types-requests==2.33.0.20260712; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260815; extra == "dev"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "dev"
+Requires-Dist: jsonschema>=4.20; extra == "dev"
+Dynamic: license-file
+
+# solo-builder-core — the Governed Shipping Agent
+
+> The only AI shipping agent that produces a cryptographic chain an
+> external auditor can verify offline.
+
+Every other coding agent records sessions. `solo-builder-core` produces
+**provenance attestations, replay packs, and bounded action tokens** —
+all signed against the canonical Strix JWKS — so an external auditor
+can verify what your agent did without trusting us, you, or the
+runtime.
+
+If your buyer is asking for SOC2 / HIPAA / FedRAMP-adjacent receipts,
+this is the only agent on the market that can hand them over.
+
+> See [`docs/POSITIONING.md`](docs/POSITIONING.md) for why we are not
+> in the Devin / Cursor / Claude-Code bucket, and
+> [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) for a control-by-control
+> mapping for auditors.
+
+> **Open core vs. commercial Strix.** This package is the open, self-hosted
+> agent: it **produces and verifies** signed receipts locally, and that proof
+> surface stays open (verify with the MIT `@strixgov/sdk` / `@strixgov/verifier`
+> + the public JWKS, or the `strix-verify` Python auditor). Its enforcement
+> modules (`action_tokens`, `approvals`, `tool_policy`, `custody`,
+> `anomaly_engine`) are a **local / self-hosted variant** — production
+> multi-tenant policy authority, hosted evidence retention, and signing-key
+> lifecycle are **commercial Strix**, not this repo. See [`NOTICE.md`](NOTICE.md).
+
+---
+
+## Product boundary — which part of this repo is the product
+
+This repository is four things at once, and the split is now **declared and
+CI-ratcheted** rather than left to archaeology:
+[`docs/PRODUCT-BOUNDARY.md`](docs/PRODUCT-BOUNDARY.md) (the declaration) +
+[`docs/product-boundary.json`](docs/product-boundary.json) (every top-level
+module, subpackage, and CLI command in exactly one bucket) +
+`tests/test_product_boundary.py` (re-derives both sets from the tree — the
+command set from the real argparse parser, never a prose list; a new module
+or command cannot land unclassified).
+
+- **PRODUCT** — what a customer or external developer runs: `/strix-wire` in
+  all its modes (hosted, offline `LOCAL_SIGNED_V1`, attestation-gated,
+  chained/DAG autonomy), the Local Reliance Gate (`solo reliance`), the
+  kernel client (`solo kernel`), envelope verification (`solo proof`), the
+  Strix Governance MCP server (`solo mcp serve`), the GSD-1 discovery
+  surfaces (`solo govern`), the buyer demos (`solo demo`), and the
+  `strix_personal` plugin core.
+- **SCHEMA AUTHORITY** — the ADR-001→032 reference implementations, frozen
+  wire contracts, and golden-vector corpora other repos conform to.
+  Contracts, not features; edits follow ADR discipline.
+- **INTERNAL TOOLING** — the shipping factory (`solo ship` and its orbit),
+  LinkedIn outbound, RCM tools, governed outbound, Mission Control / Bridge /
+  daemon, and this repo's own release governance. Real and governed, but not
+  the product — no public claim presents these as customer capabilities.
+- **UNCLASSIFIED** — two items, each carrying the question that settles it
+  (see the declaration §3–§4).
+
+Counts are derived from the tree by the test, never cited from prose.
+
+---
+
+## Quickstart
+
+```bash
+pip install -e .                        # or: pipx install solo-builder-core
+solo init --owner <you> --repo <repo>   # writes .solo.toml
+solo init --demo                        # OR: zero-API-key runnable demo
+export GITHUB_TOKEN=...                 # + NOTION_API_KEY / NOTION_DATABASE_ID if syncing
+solo status                             # see the factory floor
+```
+
+## The moat (read this first)
+
+| Capability | Status | Where |
+|---|---|---|
+| **Provenance attestations** — every PR carries a signed, hash-chained log of every governed action | shipped | `solo ship auto --pr` → [`src/solo_builder/provenance.py`](src/solo_builder/provenance.py) |
+| **Replay packs** — Ed25519-signed merkle-rooted bundle of every input + output across an eval suite | shipped | `solo eval run --attest` → [`src/solo_builder/replay.py`](src/solo_builder/replay.py) |
+| **Action tokens** — pre-signed, time-bounded, scope-limited authorizations for high-risk operations | shipped | `solo kernel approve` → [`src/solo_builder/action_tokens.py`](src/solo_builder/action_tokens.py) |
+| **External offline verifier** — auditors verify against `strixgov.com/.well-known/strix-jwks.json` | shipped | [`docs/VERIFIER.md`](docs/VERIFIER.md) |
+| **Adversarial eval suite** — refusal probes (secrets, force-push, curl-pipe-shell) scored on real kernel denies | shipped | `solo eval run --tools` → [`src/solo_builder/evals.py`](src/solo_builder/evals.py) |
+| **SoloShipBench** — public reproducible benchmark for the shipping path, signed scorecard per release | new | `solo eval run --suite soloshipbench` |
+| **Solo Bridge** — live oversight dashboard + approval surface | opt-in | `solo bridge start` → [`docs/BRIDGE.md`](docs/BRIDGE.md) |
+| **Tool marketplace** — signed, kernel-governed tools beyond the built-ins | opt-in | `solo tool install/list/publish` → [`docs/MARKETPLACE.md`](docs/MARKETPLACE.md) |
+| **Multi-agent personas** — architect / builder / reviewer / ops specialists | opt-in | `solo ship auto --persona-roster specialist` → [`docs/PERSONAS.md`](docs/PERSONAS.md) |
+| **Worktree isolation** — agent operates on `.solo/worktrees/<id>/`, never the live checkout | opt-in | `--worktree` on `ship auto`; `[agent] use_worktree` |
+| **Per-stage signed commits** — every stage is a commit, every revert is recorded | opt-in | `--stage-commits` + `solo ship rollback --stage` |
+| **MCP-compatible governed tools** — bring any MCP tool, get the audit chain for free | stdio / http / sse | [`mcp_adapter.py`](src/solo_builder/mcp_adapter.py) + [`mcp_http.py`](src/solo_builder/mcp_http.py) |
+| **Autonomy switch** — `review` / `assist` / `swarm` controls how aggressively the agent acts between gate checks | default: `review` | `--autonomy`; `[agent] autonomy` |
+| **Ant-mode daemon** — polls backlog, retries with exponential backoff, escalates after N attempts | opt-in via `swarm` | `solo daemon start/stop/status` |
+| **Multi-path racing** — runs N strategies in parallel and ships the winner | opt-in | `solo ship auto --race N` |
+| **Pheromone-weighted memory** — `{{MEMORY}}` injection prefers recent + successful entries | swarm only | `[agent] pheromone_decay_per_day`, `pheromone_amplify_factor` |
+| **Auto-decomposition** — swarm daemon splits oversized tickets and pauses parent for operator review | swarm only | `daemon:decomposed` label + comment |
+
+## Docs
+
+- [docs/POSITIONING.md](docs/POSITIONING.md) — what category solo-builder-core is in (and isn't)
+- [docs/COMPLIANCE.md](docs/COMPLIANCE.md) — auditor-facing control map
+- [docs/VERIFIER.md](docs/VERIFIER.md) — standalone JWKS verifier (one-command install)
+- [docs/BRIDGE.md](docs/BRIDGE.md) — live oversight dashboard
+- [docs/MARKETPLACE.md](docs/MARKETPLACE.md) — signed tool marketplace
+- [docs/PERSONAS.md](docs/PERSONAS.md) — multi-agent specialization
+- [docs/HOW_TO.md](docs/HOW_TO.md) — 12 task-oriented walkthroughs
+- [docs/FAQ.md](docs/FAQ.md) — ~25 recurring questions
+- [docs/ARCHITECTURE_REVIEW.md](docs/ARCHITECTURE_REVIEW.md) — design audit
+- [docs/CONTRACTS.md](docs/CONTRACTS.md) — ticket and Build Pack contracts
+- [docs/COMPETITOR_RESPONSE_PLAN.md](docs/COMPETITOR_RESPONSE_PLAN.md) — what we took from each competitor and why
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, testing conventions
+- [CLAUDE.md](CLAUDE.md) — agent / Claude Code reference for this repo
+
+## The one rule
+
+**If it can't be expressed as a shippable artifact (URL/build/job), it isn't "work" yet.**
+
+---
+
+## Features (the rest of the surface)
+
+Below the moat, the agent has all the table-stakes capabilities you'd
+expect — and a couple that solo-builder-core does better than the field.
+
+### Agent capabilities (all opt-in flags)
+
+- **`ship auto/plan --tools`** — kernel-governed tool-use loop. The agent calls `read`/`write`/`grep`/`glob`/`bash`/`web_fetch` during code-generation stages; every invocation is policy-evaluated by `KernelClient` before execution and recorded into `.solo/audit.jsonl`. See [`src/solo_builder/tools.py`](src/solo_builder/tools.py).
+- **`ship auto/plan --codebase-context`** — TF-IDF + symbol/heading-boosted retrieval over the working tree, injected as `{{CODEBASE_CONTEXT}}` in stage prompts. Stdlib-only, mtime-cached at `.solo/codebase-index.json`. See [`src/solo_builder/codebase_index.py`](src/solo_builder/codebase_index.py).
+- **`ship plan --parallel N`** — dependency-aware concurrent execution. Independent tickets run on N workers; budget refusals abort new dispatches; failed deps strictly block downstream. See [`src/solo_builder/parallel.py`](src/solo_builder/parallel.py).
+- **Multi-provider LLM client** — `AnthropicClient` (default) and `OpenAIClient` behind a `ModelRouter` that maps `tier ∈ {cheap, strong, premier}` to concrete models. Cheap stages route to Haiku/4o-mini, headline generation stays on Sonnet/4o, premier picks Opus. See [`src/solo_builder/llm.py`](src/solo_builder/llm.py).
+- **`solo ship verify --content-check`** — fetches the deployed proof URL, asserts substrings, optionally extracts checks from the ticket's Definition of Shipped. Uses the canonical Strix domain allow-list. See [`_verify_url_content`](src/solo_builder/commands/ship.py).
+- **`solo eval run` / `init` / `report`** — benchmark suite with adversarial probes (secret-write refusal, force-push refusal, curl-pipe-shell refusal). `--tools` scores governance via real kernel-deny counts. See [`src/solo_builder/evals.py`](src/solo_builder/evals.py).
+
+### Governance-leveraged differentiators (round 1)
+
+- **`solo ship auto --pr`** — emits a signed **AI contribution attestation** alongside a PR body containing the full hash-chained log of every governed action. Verifies against the canonical JWKS at `strixgov.com/.well-known/strix-jwks.json` via `@strixgov/verifier`. See [`src/solo_builder/provenance.py`](src/solo_builder/provenance.py). _Claim boundary (2026-06-09 gate review): a signature proves a key signed a defined payload; it does NOT by itself prove a human wrote the code, that the named agent alone produced the content, that no unrecorded tool influenced the result, or that the attested code equals the final merged code. Use "AI contribution attestation" — not "proven AI authorship" — until the diff/commit binding covers all of those._
+- **`solo kernel approve` → `solo ship deploy --kernel-token`** — operators pre-approve a bounded window during which the agent may execute a high-risk action class (deploy, env mutation). Four-gate verifier: signature, validity window, actor, action+scope. Tokens are canonical and identical inputs produce identical bytes — the same token verifies anywhere via the published JWKS. See [`src/solo_builder/action_tokens.py`](src/solo_builder/action_tokens.py).
+- **`solo eval run --attest pack.json` → `solo replay PACK`** — bundles every input + output across an eval suite into an Ed25519-signed merkle-rooted pack. External auditors run `solo replay --verify-only` (offline hash check) or `--fixtures DIR` (re-executes each fixture against a deterministic generator and asserts output_hash equality). Auditors verify against the canonical JWKS without trusting solo-builder-core. See [`src/solo_builder/replay.py`](src/solo_builder/replay.py).
+
+### Governance-leveraged differentiators (round 2)
+
+- **`solo agent register` → `solo ship auto --agents stage:name,...`** — governed specialist-agent registry. Specialist agents (plan / code / critique / deploy) each get their own Ed25519 keypair and kid; per-stage assignments thread into provenance so the PR body becomes a multi-author trail with cryptographic attribution. Naming note: this is a **registry** of locally-controlled agents, not a marketplace — "marketplace" is reserved for the day external publishers ship specialist agents through a Strix-side discovery surface, which requires supply-chain trust semantics (publisher identity, revocation, vulnerability response) that do not yet apply. See [`src/solo_builder/agent_registry.py`](src/solo_builder/agent_registry.py).
+- **Custody envelopes for outbound calls** — every external HTTPS call gets a signed request envelope + response envelope, hash-chained per stage. Optional service co-signatures (GitHub commit refs, Vercel deployment receipts) chain into the response side. An auditor can verify both halves independently against the canonical JWKS — closing the "the agent says it called Vercel" gap. See [`src/solo_builder/custody.py`](src/solo_builder/custody.py).
+- **`solo registry publish` / `solo registry scorecard`** — public attestation registry. **Vendors publish signed attestation-pack heads; buyers independently verify the published artifacts.** The registry stores (hash + signature + aggregate counters, no fixture bodies). Buyers `search` by policy / pass-rate, `follow` vendors, and `compose` side-by-side scorecards. Each composition verifies entry signatures against the supplied JWKS and rejects forgeries to a separate list. Scorecards preserve **per-entry verification state** (VERIFIED / INVALID / EXPIRED / REVOKED / UNVERIFIABLE / UNSIGNED / NOT_EVALUATED / INCOMPATIBLE_SCHEMA) rather than aggregating to a single green score. _Claim boundary (2026-06-09 gate review): the registry verifies **specific artifacts under defined schemas** — it does NOT establish a vendor's overall trustworthiness, and registry availability does NOT control historical verification (relying parties pin issuer keys + pack heads and verify offline)._ See [`src/solo_builder/registry.py`](src/solo_builder/registry.py).
+
+The competitive moat sits in all six governance-leveraged features: every other major coding agent (Devin, Cursor Agent, OpenHands, Claude Code, Copilot Workspace) can record sessions but none can produce a cryptographic chain that an external auditor can verify offline. solo-builder-core can because Strix's signing infrastructure already exists — and round 2 extends that asymmetry across agent boundaries, service boundaries, and vendor boundaries.
+
+## The Ship Cycle
+
+1. **Capture** → idea lands as a 🚢 Ship Ticket (GitHub issue).
+2. **Init** → `solo ship init <id> --scaffold` creates branch + Build Pack + starter artifact.
+3. **Build** → implement in `artifacts/<id>-<slug>/`. Use `solo ai spec/tasks` to expand docs.
+4. **Deploy** → `solo ship deploy <id> --close` deploys via a deploy adapter and auto-captures the proof URL.
+5. **Verify** → `solo ship verify <id>` HEAD-checks the proof URL.
+6. **Sync** → `solo sync` upserts Notion (and `--promote` pulls Notion-marked cards back into GitHub).
+
+Definition of Done: acceptance tests exist **and** verified proof-of-ship exists.
+
+---
+
+## CLI map
+
+| Command | What it does |
+| --- | --- |
+| `solo init` | Bootstrap `.solo.toml`, `.gitignore`, `.solo/` state dir |
+| `solo ship init <id>` | Branch + Build Pack (00–05) + optional template scaffold |
+| `solo ship deploy <id>` | Run a deploy adapter (vercel, railway, cloudflare, expo, github-pages, manual) |
+| `solo ship close <id> --proof <url>` | Validate ticket, verify URL, close with proof |
+| `solo ship verify <id>` | HEAD-check the proof URL (200 OK?) |
+| `solo ship rollback <id>` | Reopen a shipped ticket |
+| `solo ticket lint <id>` | Validate a ticket against the v1.x contract |
+| `solo ticket show <id>` | Pretty-print the parsed ticket |
+| `solo sync` | GH → Notion upsert; `--promote` for Notion → GH |
+| `solo status` / `solo next` | See open work; pick next queued (respects WIP limit) |
+| `solo resume <id>` | Check out the ship branch |
+| `solo metrics` | Cycle time, WIP, ship rate (optional `--json`) |
+| `solo ai spec\|tasks\|postmortem\|review <id>` | Claude-backed authoring helpers |
+| `solo account status` | Which mode you are in (offline / sandbox / connected), what it includes, what the next tier unlocks — see [`commercial-launch/pricing/PRICING.md`](commercial-launch/pricing/PRICING.md) |
+| `solo kernel evaluate <type>` | Ask the policy engine about a hypothetical action |
+| `solo kernel log --issue <id>` | Show audit log for an issue |
+| `--dry-run` | Runs on any mutating command |
+
+**Plans and pricing** ([`PRICING.md`](commercial-launch/pricing/PRICING.md)): Local and synthetic use only until a governed release is accepted. No production authorization claim.
+
+---
+
+## What the system guarantees
+
+- **GitHub** is execution truth; **Notion** is control plane.
+- **No close without verified proof** (CLI + optional CI gate).
+- **Build Packs are standardized** (`00-spec`, `01-architecture`, `02-tasks`, `03-tests`, `04-deploy`, `05-notes`).
+- **Idempotent sync** keyed by GitHub Issue URL.
+- **Label invariants** enforced by CI (one `status:*`, one `artifact:*`).
+- **Audit log** — every mutating command appends to `.solo/audit.jsonl`.
+- **Kernel governance** — every `init`/`deploy`/`close` gets a policy decision. Local stub runs when the service is unreachable.
+
+---
+
+## Config
+
+`.solo.toml` at the repo root. Any field can be overridden by env var:
+
+| Env var | Purpose |
+| --- | --- |
+| `GITHUB_TOKEN` / `GITHUB_REPO_OWNER` / `GITHUB_REPO_NAME` | GitHub API |
+| `NOTION_API_KEY` / `NOTION_DATABASE_ID` | Notion sync |
+| `KERNEL_URL` | Execution Kernel endpoint (default `https://www.strixgov.com`) |
+| `ANTHROPIC_API_KEY` | Enables real Claude calls for `solo ai ...` (offline fallback otherwise) |
+| `VERCEL_TOKEN` / `RAILWAY_TOKEN` / `CLOUDFLARE_API_TOKEN` | Deploy adapters |
+
+---
+
+## Deploy targets
+
+Page / Webapp → Vercel • Integration / Automation → Railway or Cloudflare Workers • App → Expo • Content → Manual • Simple pages → GitHub Pages. Override per-ticket via the `deploy_target` front-matter field or `solo ship deploy --target`.
+
+---
+
+## Templates
+
+Starter templates live in `templates/`:
+
+- `page/` — static HTML
+- `webapp/` — minimal `package.json`
+- `nextjs/` — Next.js 14 app-router
+- `cloudflare-worker/` — wrangler-ready Worker
+- `automation/` — Python script
+- `content/` — Markdown post scaffold
+- `chrome-extension/` — MV3 extension
+
+---
+
+## Prompts
+
+`prompts/` holds system prompts for the AI commands. Edit them to match your voice. `solo ai` uses these when `ANTHROPIC_API_KEY` is set; otherwise it falls back to deterministic offline templates so CI never requires a key.
+
+---
+
+**Version**: 1.2

solo_builder_core-0.4.0/README.md

@@ -0,0 +1,236 @@
+# solo-builder-core — the Governed Shipping Agent
+
+> The only AI shipping agent that produces a cryptographic chain an
+> external auditor can verify offline.
+
+Every other coding agent records sessions. `solo-builder-core` produces
+**provenance attestations, replay packs, and bounded action tokens** —
+all signed against the canonical Strix JWKS — so an external auditor
+can verify what your agent did without trusting us, you, or the
+runtime.
+
+If your buyer is asking for SOC2 / HIPAA / FedRAMP-adjacent receipts,
+this is the only agent on the market that can hand them over.
+
+> See [`docs/POSITIONING.md`](docs/POSITIONING.md) for why we are not
+> in the Devin / Cursor / Claude-Code bucket, and
+> [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) for a control-by-control
+> mapping for auditors.
+
+> **Open core vs. commercial Strix.** This package is the open, self-hosted
+> agent: it **produces and verifies** signed receipts locally, and that proof
+> surface stays open (verify with the MIT `@strixgov/sdk` / `@strixgov/verifier`
+> + the public JWKS, or the `strix-verify` Python auditor). Its enforcement
+> modules (`action_tokens`, `approvals`, `tool_policy`, `custody`,
+> `anomaly_engine`) are a **local / self-hosted variant** — production
+> multi-tenant policy authority, hosted evidence retention, and signing-key
+> lifecycle are **commercial Strix**, not this repo. See [`NOTICE.md`](NOTICE.md).
+
+---
+
+## Product boundary — which part of this repo is the product
+
+This repository is four things at once, and the split is now **declared and
+CI-ratcheted** rather than left to archaeology:
+[`docs/PRODUCT-BOUNDARY.md`](docs/PRODUCT-BOUNDARY.md) (the declaration) +
+[`docs/product-boundary.json`](docs/product-boundary.json) (every top-level
+module, subpackage, and CLI command in exactly one bucket) +
+`tests/test_product_boundary.py` (re-derives both sets from the tree — the
+command set from the real argparse parser, never a prose list; a new module
+or command cannot land unclassified).
+
+- **PRODUCT** — what a customer or external developer runs: `/strix-wire` in
+  all its modes (hosted, offline `LOCAL_SIGNED_V1`, attestation-gated,
+  chained/DAG autonomy), the Local Reliance Gate (`solo reliance`), the
+  kernel client (`solo kernel`), envelope verification (`solo proof`), the
+  Strix Governance MCP server (`solo mcp serve`), the GSD-1 discovery
+  surfaces (`solo govern`), the buyer demos (`solo demo`), and the
+  `strix_personal` plugin core.
+- **SCHEMA AUTHORITY** — the ADR-001→032 reference implementations, frozen
+  wire contracts, and golden-vector corpora other repos conform to.
+  Contracts, not features; edits follow ADR discipline.
+- **INTERNAL TOOLING** — the shipping factory (`solo ship` and its orbit),
+  LinkedIn outbound, RCM tools, governed outbound, Mission Control / Bridge /
+  daemon, and this repo's own release governance. Real and governed, but not
+  the product — no public claim presents these as customer capabilities.
+- **UNCLASSIFIED** — two items, each carrying the question that settles it
+  (see the declaration §3–§4).
+
+Counts are derived from the tree by the test, never cited from prose.
+
+---
+
+## Quickstart
+
+```bash
+pip install -e .                        # or: pipx install solo-builder-core
+solo init --owner <you> --repo <repo>   # writes .solo.toml
+solo init --demo                        # OR: zero-API-key runnable demo
+export GITHUB_TOKEN=...                 # + NOTION_API_KEY / NOTION_DATABASE_ID if syncing
+solo status                             # see the factory floor
+```
+
+## The moat (read this first)
+
+| Capability | Status | Where |
+|---|---|---|
+| **Provenance attestations** — every PR carries a signed, hash-chained log of every governed action | shipped | `solo ship auto --pr` → [`src/solo_builder/provenance.py`](src/solo_builder/provenance.py) |
+| **Replay packs** — Ed25519-signed merkle-rooted bundle of every input + output across an eval suite | shipped | `solo eval run --attest` → [`src/solo_builder/replay.py`](src/solo_builder/replay.py) |
+| **Action tokens** — pre-signed, time-bounded, scope-limited authorizations for high-risk operations | shipped | `solo kernel approve` → [`src/solo_builder/action_tokens.py`](src/solo_builder/action_tokens.py) |
+| **External offline verifier** — auditors verify against `strixgov.com/.well-known/strix-jwks.json` | shipped | [`docs/VERIFIER.md`](docs/VERIFIER.md) |
+| **Adversarial eval suite** — refusal probes (secrets, force-push, curl-pipe-shell) scored on real kernel denies | shipped | `solo eval run --tools` → [`src/solo_builder/evals.py`](src/solo_builder/evals.py) |
+| **SoloShipBench** — public reproducible benchmark for the shipping path, signed scorecard per release | new | `solo eval run --suite soloshipbench` |
+| **Solo Bridge** — live oversight dashboard + approval surface | opt-in | `solo bridge start` → [`docs/BRIDGE.md`](docs/BRIDGE.md) |
+| **Tool marketplace** — signed, kernel-governed tools beyond the built-ins | opt-in | `solo tool install/list/publish` → [`docs/MARKETPLACE.md`](docs/MARKETPLACE.md) |
+| **Multi-agent personas** — architect / builder / reviewer / ops specialists | opt-in | `solo ship auto --persona-roster specialist` → [`docs/PERSONAS.md`](docs/PERSONAS.md) |
+| **Worktree isolation** — agent operates on `.solo/worktrees/<id>/`, never the live checkout | opt-in | `--worktree` on `ship auto`; `[agent] use_worktree` |
+| **Per-stage signed commits** — every stage is a commit, every revert is recorded | opt-in | `--stage-commits` + `solo ship rollback --stage` |
+| **MCP-compatible governed tools** — bring any MCP tool, get the audit chain for free | stdio / http / sse | [`mcp_adapter.py`](src/solo_builder/mcp_adapter.py) + [`mcp_http.py`](src/solo_builder/mcp_http.py) |
+| **Autonomy switch** — `review` / `assist` / `swarm` controls how aggressively the agent acts between gate checks | default: `review` | `--autonomy`; `[agent] autonomy` |
+| **Ant-mode daemon** — polls backlog, retries with exponential backoff, escalates after N attempts | opt-in via `swarm` | `solo daemon start/stop/status` |
+| **Multi-path racing** — runs N strategies in parallel and ships the winner | opt-in | `solo ship auto --race N` |
+| **Pheromone-weighted memory** — `{{MEMORY}}` injection prefers recent + successful entries | swarm only | `[agent] pheromone_decay_per_day`, `pheromone_amplify_factor` |
+| **Auto-decomposition** — swarm daemon splits oversized tickets and pauses parent for operator review | swarm only | `daemon:decomposed` label + comment |
+
+## Docs
+
+- [docs/POSITIONING.md](docs/POSITIONING.md) — what category solo-builder-core is in (and isn't)
+- [docs/COMPLIANCE.md](docs/COMPLIANCE.md) — auditor-facing control map
+- [docs/VERIFIER.md](docs/VERIFIER.md) — standalone JWKS verifier (one-command install)
+- [docs/BRIDGE.md](docs/BRIDGE.md) — live oversight dashboard
+- [docs/MARKETPLACE.md](docs/MARKETPLACE.md) — signed tool marketplace
+- [docs/PERSONAS.md](docs/PERSONAS.md) — multi-agent specialization
+- [docs/HOW_TO.md](docs/HOW_TO.md) — 12 task-oriented walkthroughs
+- [docs/FAQ.md](docs/FAQ.md) — ~25 recurring questions
+- [docs/ARCHITECTURE_REVIEW.md](docs/ARCHITECTURE_REVIEW.md) — design audit
+- [docs/CONTRACTS.md](docs/CONTRACTS.md) — ticket and Build Pack contracts
+- [docs/COMPETITOR_RESPONSE_PLAN.md](docs/COMPETITOR_RESPONSE_PLAN.md) — what we took from each competitor and why
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, testing conventions
+- [CLAUDE.md](CLAUDE.md) — agent / Claude Code reference for this repo
+
+## The one rule
+
+**If it can't be expressed as a shippable artifact (URL/build/job), it isn't "work" yet.**
+
+---
+
+## Features (the rest of the surface)
+
+Below the moat, the agent has all the table-stakes capabilities you'd
+expect — and a couple that solo-builder-core does better than the field.
+
+### Agent capabilities (all opt-in flags)
+
+- **`ship auto/plan --tools`** — kernel-governed tool-use loop. The agent calls `read`/`write`/`grep`/`glob`/`bash`/`web_fetch` during code-generation stages; every invocation is policy-evaluated by `KernelClient` before execution and recorded into `.solo/audit.jsonl`. See [`src/solo_builder/tools.py`](src/solo_builder/tools.py).
+- **`ship auto/plan --codebase-context`** — TF-IDF + symbol/heading-boosted retrieval over the working tree, injected as `{{CODEBASE_CONTEXT}}` in stage prompts. Stdlib-only, mtime-cached at `.solo/codebase-index.json`. See [`src/solo_builder/codebase_index.py`](src/solo_builder/codebase_index.py).
+- **`ship plan --parallel N`** — dependency-aware concurrent execution. Independent tickets run on N workers; budget refusals abort new dispatches; failed deps strictly block downstream. See [`src/solo_builder/parallel.py`](src/solo_builder/parallel.py).
+- **Multi-provider LLM client** — `AnthropicClient` (default) and `OpenAIClient` behind a `ModelRouter` that maps `tier ∈ {cheap, strong, premier}` to concrete models. Cheap stages route to Haiku/4o-mini, headline generation stays on Sonnet/4o, premier picks Opus. See [`src/solo_builder/llm.py`](src/solo_builder/llm.py).
+- **`solo ship verify --content-check`** — fetches the deployed proof URL, asserts substrings, optionally extracts checks from the ticket's Definition of Shipped. Uses the canonical Strix domain allow-list. See [`_verify_url_content`](src/solo_builder/commands/ship.py).
+- **`solo eval run` / `init` / `report`** — benchmark suite with adversarial probes (secret-write refusal, force-push refusal, curl-pipe-shell refusal). `--tools` scores governance via real kernel-deny counts. See [`src/solo_builder/evals.py`](src/solo_builder/evals.py).
+
+### Governance-leveraged differentiators (round 1)
+
+- **`solo ship auto --pr`** — emits a signed **AI contribution attestation** alongside a PR body containing the full hash-chained log of every governed action. Verifies against the canonical JWKS at `strixgov.com/.well-known/strix-jwks.json` via `@strixgov/verifier`. See [`src/solo_builder/provenance.py`](src/solo_builder/provenance.py). _Claim boundary (2026-06-09 gate review): a signature proves a key signed a defined payload; it does NOT by itself prove a human wrote the code, that the named agent alone produced the content, that no unrecorded tool influenced the result, or that the attested code equals the final merged code. Use "AI contribution attestation" — not "proven AI authorship" — until the diff/commit binding covers all of those._
+- **`solo kernel approve` → `solo ship deploy --kernel-token`** — operators pre-approve a bounded window during which the agent may execute a high-risk action class (deploy, env mutation). Four-gate verifier: signature, validity window, actor, action+scope. Tokens are canonical and identical inputs produce identical bytes — the same token verifies anywhere via the published JWKS. See [`src/solo_builder/action_tokens.py`](src/solo_builder/action_tokens.py).
+- **`solo eval run --attest pack.json` → `solo replay PACK`** — bundles every input + output across an eval suite into an Ed25519-signed merkle-rooted pack. External auditors run `solo replay --verify-only` (offline hash check) or `--fixtures DIR` (re-executes each fixture against a deterministic generator and asserts output_hash equality). Auditors verify against the canonical JWKS without trusting solo-builder-core. See [`src/solo_builder/replay.py`](src/solo_builder/replay.py).
+
+### Governance-leveraged differentiators (round 2)
+
+- **`solo agent register` → `solo ship auto --agents stage:name,...`** — governed specialist-agent registry. Specialist agents (plan / code / critique / deploy) each get their own Ed25519 keypair and kid; per-stage assignments thread into provenance so the PR body becomes a multi-author trail with cryptographic attribution. Naming note: this is a **registry** of locally-controlled agents, not a marketplace — "marketplace" is reserved for the day external publishers ship specialist agents through a Strix-side discovery surface, which requires supply-chain trust semantics (publisher identity, revocation, vulnerability response) that do not yet apply. See [`src/solo_builder/agent_registry.py`](src/solo_builder/agent_registry.py).
+- **Custody envelopes for outbound calls** — every external HTTPS call gets a signed request envelope + response envelope, hash-chained per stage. Optional service co-signatures (GitHub commit refs, Vercel deployment receipts) chain into the response side. An auditor can verify both halves independently against the canonical JWKS — closing the "the agent says it called Vercel" gap. See [`src/solo_builder/custody.py`](src/solo_builder/custody.py).
+- **`solo registry publish` / `solo registry scorecard`** — public attestation registry. **Vendors publish signed attestation-pack heads; buyers independently verify the published artifacts.** The registry stores (hash + signature + aggregate counters, no fixture bodies). Buyers `search` by policy / pass-rate, `follow` vendors, and `compose` side-by-side scorecards. Each composition verifies entry signatures against the supplied JWKS and rejects forgeries to a separate list. Scorecards preserve **per-entry verification state** (VERIFIED / INVALID / EXPIRED / REVOKED / UNVERIFIABLE / UNSIGNED / NOT_EVALUATED / INCOMPATIBLE_SCHEMA) rather than aggregating to a single green score. _Claim boundary (2026-06-09 gate review): the registry verifies **specific artifacts under defined schemas** — it does NOT establish a vendor's overall trustworthiness, and registry availability does NOT control historical verification (relying parties pin issuer keys + pack heads and verify offline)._ See [`src/solo_builder/registry.py`](src/solo_builder/registry.py).
+
+The competitive moat sits in all six governance-leveraged features: every other major coding agent (Devin, Cursor Agent, OpenHands, Claude Code, Copilot Workspace) can record sessions but none can produce a cryptographic chain that an external auditor can verify offline. solo-builder-core can because Strix's signing infrastructure already exists — and round 2 extends that asymmetry across agent boundaries, service boundaries, and vendor boundaries.
+
+## The Ship Cycle
+
+1. **Capture** → idea lands as a 🚢 Ship Ticket (GitHub issue).
+2. **Init** → `solo ship init <id> --scaffold` creates branch + Build Pack + starter artifact.
+3. **Build** → implement in `artifacts/<id>-<slug>/`. Use `solo ai spec/tasks` to expand docs.
+4. **Deploy** → `solo ship deploy <id> --close` deploys via a deploy adapter and auto-captures the proof URL.
+5. **Verify** → `solo ship verify <id>` HEAD-checks the proof URL.
+6. **Sync** → `solo sync` upserts Notion (and `--promote` pulls Notion-marked cards back into GitHub).
+
+Definition of Done: acceptance tests exist **and** verified proof-of-ship exists.
+
+---
+
+## CLI map
+
+| Command | What it does |
+| --- | --- |
+| `solo init` | Bootstrap `.solo.toml`, `.gitignore`, `.solo/` state dir |
+| `solo ship init <id>` | Branch + Build Pack (00–05) + optional template scaffold |
+| `solo ship deploy <id>` | Run a deploy adapter (vercel, railway, cloudflare, expo, github-pages, manual) |
+| `solo ship close <id> --proof <url>` | Validate ticket, verify URL, close with proof |
+| `solo ship verify <id>` | HEAD-check the proof URL (200 OK?) |
+| `solo ship rollback <id>` | Reopen a shipped ticket |
+| `solo ticket lint <id>` | Validate a ticket against the v1.x contract |
+| `solo ticket show <id>` | Pretty-print the parsed ticket |
+| `solo sync` | GH → Notion upsert; `--promote` for Notion → GH |
+| `solo status` / `solo next` | See open work; pick next queued (respects WIP limit) |
+| `solo resume <id>` | Check out the ship branch |
+| `solo metrics` | Cycle time, WIP, ship rate (optional `--json`) |
+| `solo ai spec\|tasks\|postmortem\|review <id>` | Claude-backed authoring helpers |
+| `solo account status` | Which mode you are in (offline / sandbox / connected), what it includes, what the next tier unlocks — see [`commercial-launch/pricing/PRICING.md`](commercial-launch/pricing/PRICING.md) |
+| `solo kernel evaluate <type>` | Ask the policy engine about a hypothetical action |
+| `solo kernel log --issue <id>` | Show audit log for an issue |
+| `--dry-run` | Runs on any mutating command |
+
+**Plans and pricing** ([`PRICING.md`](commercial-launch/pricing/PRICING.md)): Local and synthetic use only until a governed release is accepted. No production authorization claim.
+
+---
+
+## What the system guarantees
+
+- **GitHub** is execution truth; **Notion** is control plane.
+- **No close without verified proof** (CLI + optional CI gate).
+- **Build Packs are standardized** (`00-spec`, `01-architecture`, `02-tasks`, `03-tests`, `04-deploy`, `05-notes`).
+- **Idempotent sync** keyed by GitHub Issue URL.
+- **Label invariants** enforced by CI (one `status:*`, one `artifact:*`).
+- **Audit log** — every mutating command appends to `.solo/audit.jsonl`.
+- **Kernel governance** — every `init`/`deploy`/`close` gets a policy decision. Local stub runs when the service is unreachable.
+
+---
+
+## Config
+
+`.solo.toml` at the repo root. Any field can be overridden by env var:
+
+| Env var | Purpose |
+| --- | --- |
+| `GITHUB_TOKEN` / `GITHUB_REPO_OWNER` / `GITHUB_REPO_NAME` | GitHub API |
+| `NOTION_API_KEY` / `NOTION_DATABASE_ID` | Notion sync |
+| `KERNEL_URL` | Execution Kernel endpoint (default `https://www.strixgov.com`) |
+| `ANTHROPIC_API_KEY` | Enables real Claude calls for `solo ai ...` (offline fallback otherwise) |
+| `VERCEL_TOKEN` / `RAILWAY_TOKEN` / `CLOUDFLARE_API_TOKEN` | Deploy adapters |
+
+---
+
+## Deploy targets
+
+Page / Webapp → Vercel • Integration / Automation → Railway or Cloudflare Workers • App → Expo • Content → Manual • Simple pages → GitHub Pages. Override per-ticket via the `deploy_target` front-matter field or `solo ship deploy --target`.
+
+---
+
+## Templates
+
+Starter templates live in `templates/`:
+
+- `page/` — static HTML
+- `webapp/` — minimal `package.json`
+- `nextjs/` — Next.js 14 app-router
+- `cloudflare-worker/` — wrangler-ready Worker
+- `automation/` — Python script
+- `content/` — Markdown post scaffold
+- `chrome-extension/` — MV3 extension
+
+---
+
+## Prompts
+
+`prompts/` holds system prompts for the AI commands. Edit them to match your voice. `solo ai` uses these when `ANTHROPIC_API_KEY` is set; otherwise it falls back to deterministic offline templates so CI never requires a key.
+
+---
+
+**Version**: 1.2