buildanchor 0.3.2__tar.gz

buildanchor-0.3.2/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

buildanchor-0.3.2/NOTICE

@@ -0,0 +1,12 @@
+BuildAnchor
+Copyright 2026 Tensilestream and BuildAnchor contributors.
+
+BuildAnchor is distributed under the Apache License, Version 2.0. Redistributions and
+derivative works must retain the LICENSE file, this NOTICE file, copyright notices, and
+required modification notices.
+
+"BuildAnchor", "Tensilestream", and associated logos and marks identify the upstream
+project. The Apache License does not grant permission to use those names or marks to
+brand a fork, imply endorsement, or present a derivative work as the official project.
+Descriptive references such as "based on BuildAnchor" are permitted when they are
+accurate and do not imply endorsement.

buildanchor-0.3.2/PKG-INFO

@@ -0,0 +1,453 @@
+Metadata-Version: 2.4
+Name: buildanchor
+Version: 0.3.2
+Summary: Local-first Build Truth and change validation for AI coding agents
+Author: Tensilestream & BuildAnchor contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/tensilestream/buildanchor
+Project-URL: Documentation, https://github.com/tensilestream/buildanchor#readme
+Project-URL: Repository, https://github.com/tensilestream/buildanchor.git
+Project-URL: Issues, https://github.com/tensilestream/buildanchor/issues
+Project-URL: Discussions, https://github.com/tensilestream/buildanchor/discussions
+Project-URL: Changelog, https://github.com/tensilestream/buildanchor/blob/main/CHANGELOG.md
+Keywords: ai-agents,ai-coding-assistant,build-system,build-validation,change-validation,code-intelligence,developer-productivity,developer-tools,local-first,mcp,polyglot-repository,repository-analysis,software-supply-chain,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+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
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == "tokens"
+Provides-Extra: dev
+Requires-Dist: tiktoken>=0.7; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/branding/buildanchor_project_shield.png" width="120" alt="BuildAnchor Logo">
+</p>
+ 
+# BuildAnchor
+
+[![CI](https://github.com/tensilestream/buildanchor/actions/workflows/ci.yml/badge.svg)](https://github.com/tensilestream/buildanchor/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Organization](https://img.shields.io/badge/org-Tensilestream-orange.svg)](https://github.com/tensilestream)
+
+BuildAnchor is an open-source, local-first **Build Truth and change-validation layer for AI coding agents** by [Tensilestream](https://github.com/tensilestream).
+
+Every time a coding agent guesses which test command to run, which Java runtime a repo targets, or whether to use `javax.persistence` or `jakarta.persistence`, it wastes tokens and risks making an incompatible change. BuildAnchor answers those questions in milliseconds — locally, offline, and with zero LLM calls — so the agent doesn't have to.
+
+## How it saves LLM tokens
+
+| Without BuildAnchor | With BuildAnchor |
+|---|---|
+| Agent reads `pom.xml`, `build.gradle`, `pyproject.toml`, `package.json`, … | Agent injects one ~150-token block from `build.llm_prompt` |
+| Agent guesses `javax.persistence` vs `jakarta.persistence` | BuildAnchor detects Spring Boot 3+ and flags the correct namespace |
+| Agent tries the wrong test command and wastes a turn repairing it | BuildAnchor proves the exact validated test command |
+| Agent silently uses the 2015 Rust edition | BuildAnchor warns and recommends edition 2021 |
+
+**Typical savings: 500–2000 tokens per agent invocation** on polyglot repositories.
+
+## Universal Kickstart by Ecosystem
+
+BuildAnchor works automatically across all major programming stacks without manual configuration. Run these from your project root:
+
+```bash
+# Initialize your project: auto-detects stack and writes AGENT.md rules
+buildanchor init
+
+# Get instant, zero-noise context to inject into your agent
+buildanchor llm-prompt --agent
+
+# Check if a package is already installed before adding duplicate dependencies
+buildanchor find --package express       # Node / TypeScript
+buildanchor find --package pydantic      # Python
+buildanchor find --package jackson       # Java / Kotlin
+
+# Run verified tests without guessing test runners or flags
+buildanchor cmd test
+```
+
+### Monorepo Intelligence & Targeted Test Scoping
+
+In multi-package repositories (Turborepo, Nx, pnpm/npm/yarn workspaces, Cargo, Maven multi-module, Gradle multi-project, Go workspaces, and Python monorepos), running the entire repository test suite wastes minutes and tokens, and frequently causes coding agents to fail. BuildAnchor detects monorepo topology and enables targeted, scoped testing:
+
+```bash
+# Discover all packages, directories, and categories (UI vs BACKEND vs SHARED)
+buildanchor modules
+
+# Run ONLY UI / frontend tests
+buildanchor cmd test --scope ui
+
+# Run ONLY backend / API / database tests
+buildanchor cmd test --scope backend
+
+# Target a specific package or directory
+buildanchor cmd test --scope @acme/web
+buildanchor cmd test --scope apps/api
+
+# Automatically detect and test ONLY packages modified in git diff
+buildanchor cmd test --changed
+```
+
+### Real-World Developer Tasks & Agent Prompts
+
+Below are generic prompts that work across the most common project types in the world:
+
+| Ecosystem | Common Generic Task | BuildAnchor Pre-Flight Command |
+|---|---|---|
+| **Node / TypeScript** | *"Add a JWT authentication middleware"* | `buildanchor plan --workspace . --objective "Add a JWT authentication middleware"` |
+| **Python (FastAPI / Django)** | *"Add an async health check route with DB ping"* | `buildanchor plan --workspace . --objective "Add an async health check route with DB ping"` |
+| **Java (Spring Boot)** | *"Add a REST controller with validation"* | `buildanchor plan --workspace . --objective "Add a REST controller with validation"` |
+| **Go** | *"Implement structured logging and graceful shutdown"* | `buildanchor plan --workspace . --objective "Implement structured logging and graceful shutdown"` |
+| **Rust** | *"Implement request rate limiting worker"* | `buildanchor plan --workspace . --objective "Implement request rate limiting worker"` |
+| **.NET (C#)** | *"Add an EF Core DbContext entity and migration"* | `buildanchor plan --workspace . --objective "Add an EF Core DbContext entity and migration"` |
+
+### Ready-to-Use Agent Prompt Templates
+
+Copy and paste these snippets into your agent's instructions (`.cursorrules`, `AGENT.md`, `CLAUDE.md`, or System Prompt):
+
+#### For Cursor / Windsurf / Copilot (`.cursorrules` or instructions):
+```markdown
+Before modifying build configs, adding dependencies, or running tests:
+1. Run `buildanchor preflight --agent` to inspect repository runtime truth.
+2. If adding an import or package, run `buildanchor find --package <name>` first to verify existing versions and import conventions.
+3. Run verified tests using `buildanchor cmd test`.
+4. After completing code changes, run `buildanchor validate-change --baseline HEAD`.
+```
+
+#### For Terminal Agents (Claude Code, Aider, OpenCodeInterpreter):
+```bash
+# In your agent prompt or slash-command:
+"Please implement [TASK]. First run `buildanchor plan --objective '[TASK]' --agent` to verify stack constraints and baseline, then write the code and run `buildanchor cmd test`."
+```
+
+## Recommended call sequence for agents
+
+```
+1. build.llm_prompt   →  inject into system prompt (150 tokens, zero risk)
+2. build.preflight    →  gate before touching build/dependency files
+3. [agent acts]
+4. build.validate_change  →  confirm the change is coherent
+5. build.repair_guidance  →  fix if invalid/inconclusive
+```
+
+Use `build.token_estimate` first if you want to see the cost of each tool before calling.
+
+## Ecosystem compatibility rules (catches what LLMs hallucinate)
+
+| Rule | Languages | What it catches |
+|---|---|---|
+| Jakarta namespace migration | Java, Kotlin | `javax.persistence/validation/servlet` → `jakarta.*` (Spring Boot 3+) |
+| Python packaging | Python | `setup.py`-only, deprecated `distutils`, `pkg_resources` → `importlib` |
+| Node ESM | JavaScript, TypeScript | `"main"` without `"exports"`, deprecated `request` package |
+| Go modules | Go | Pre-module layout (no `go.mod`) |
+| Rust edition | Rust | Edition 2015 → recommend 2021 |
+| Objective mismatch | All | JPA objective on a Node.js repo → explicit warning |
+
+It helps an agent follow this lifecycle:
+
+```text
+Inspect → Act → Validate → Repair → Validate again
+```
+
+BuildAnchor reports what a repository can prove about its build system, runtime, dependencies, compatibility constraints, and validation commands. It does not claim that a build passed unless an approved validation runner actually ran it.
+
+
+## Who this is for
+
+BuildAnchor is designed for:
+
+- Teams building AI coding agents that need repository-aware context before editing code.
+- Developer-platform and DevOps teams supporting many repositories and build systems.
+- Maintainers who want a repeatable pre-change check and evidence-backed change validation.
+- Security-conscious engineering teams that need local-first, bounded, auditable diagnostics.
+
+## What it saves
+
+BuildAnchor is intended to save investigation time and wasted validation cycles by answering the
+questions that usually slow down an automated or unfamiliar change: which build system is active,
+which runtimes and dependencies are present, which compatibility constraints matter, what changed,
+and which validation commands are appropriate. It reports evidence and uncertainty instead of
+guessing, so teams can compare its local latency with their own workflow before adopting it.
+
+It is a repository inspection and change-validation layer, not a replacement for the repository's
+build tool, test runner, CI system, or security sandbox.
+
+## Copyright and project identity
+
+BuildAnchor is copyright © 2026 Tensilestream and BuildAnchor contributors and is distributed
+under the Apache License, Version 2.0. Projects may use, modify, and include the code when they
+retain the required license, copyright, attribution, NOTICE, and modification notices.
+
+The BuildAnchor and Tensilestream names and marks identify the upstream project. A fork or
+derivative must not remove attribution, present the upstream code as entirely original, use the
+upstream name as its own product branding, or imply official endorsement. See
+[`TRADEMARKS.md`](TRADEMARKS.md) for the project identity policy.
+
+## Quick start
+
+### Install the CLI
+
+For a contributor checkout, install the local files globally with the platform installer:
+
+```bash
+./scripts/install.sh --local --global
+```
+
+From macOS/Linux without a checkout:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tensilestream/buildanchor/main/scripts/install.sh | bash
+```
+
+For Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/tensilestream/buildanchor/main/scripts/install.ps1 | iex
+```
+
+### Inspect another repository
+
+Once installed, BuildAnchor can be run from any directory:
+
+```bash
+buildanchor inspect --workspace /path/to/another/repository --format text
+cd /path/to/another/repository
+buildanchor context --workspace . --format json
+```
+
+### Contributor quick start
+
+To test the current checkout before installing a package:
+
+```bash
+uv sync
+uv run python -m unittest discover -s tests -v
+uv run buildanchor inspect --workspace /path/to/another/repository --format text
+```
+
+The platform installer below is for contributors who specifically need the current checkout
+exposed as a command outside `uv run`.
+
+### Run directly from the source checkout
+
+```bash
+uv sync
+uv run buildanchor inspect --workspace . --format text
+uv run buildanchor compatibility --workspace . --format json
+uv run buildanchor plan --workspace . --objective "Add a health check endpoint" --format json
+uv run buildanchor context --workspace . --format json
+uv run buildanchor validate-change --workspace . --baseline HEAD --format json
+# Execute the detected, bounded validation probes as an explicit opt-in:
+uv run buildanchor validate-change --workspace . --baseline HEAD --execute --format json
+```
+
+`uv sync` creates and manages the project virtual environment automatically. The current reference implementation uses Python 3.10+ and has no runtime dependencies.
+
+If `uv` is unavailable, the equivalent standard-library fallback is:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+buildanchor inspect --workspace . --format text
+```
+
+### Install the current checkout globally for development
+
+Run the installer from the repository root. It installs this checkout, including uncommitted
+source changes, globally for your user account:
+
+```bash
+./scripts/install.sh --local --global
+```
+
+On Windows PowerShell:
+
+```powershell
+.\scripts\install.ps1 -Local -Global
+```
+
+The script uses `pipx` or a user-scoped Python installation and does not clone or fetch the
+repository when run from a checkout. If a Python virtual environment is active, deactivate it
+first or install `pipx`; the script intentionally avoids turning a project virtual environment
+into a global installation.
+
+### One-command installers
+
+From a macOS or Linux shell, install the latest main branch with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tensilestream/buildanchor/main/scripts/install.sh | bash
+```
+
+When run from this checkout, the script installs the local source tree, including uncommitted
+changes. It does not clone or fetch the repository.
+
+Homebrew installation is reserved for a published formula/tap; it is not used by this local
+checkout installer because contributors need to test the files before pushing them.
+
+From Windows PowerShell, use:
+
+```powershell
+irm https://raw.githubusercontent.com/tensilestream/buildanchor/main/scripts/install.ps1 | iex
+```
+
+The bootstrap scripts use `pipx` or a user-scoped Python installation. Review the script before
+piping it to a shell in a restricted environment. Set `BUILDANCHOR_SOURCE_URL` to install from a
+pinned release archive or an internal mirror. The Homebrew formula is intended for a published
+tap, not for pre-push local testing.
+
+## Agent integration
+
+Start the MCP server with a bounded workspace:
+
+```bash
+buildanchor mcp --stdio --allow-root /path/to/repository
+```
+
+Available MCP tools:
+
+- `build.inspect`
+- `build.context`
+- `build.preflight`
+- `build.plan`
+- `build.change_impact`
+- `build.validate_change`
+- `build.repair_guidance`
+- `build.explain_dependency`
+
+`build.validate_change` is static by default. Pass `execute: true` and an optional `timeout` to run detected validation probes with `shell=False`, bounded output, and per-command timeouts. BuildAnchor reports each probe as `passed`, `failed`, `timed_out`, or `unavailable`; it never turns a missing baseline or missing tool into a pass.
+
+For automation, `validate-change` exits `0` for `valid`, `1` for `invalid`, `2` for `inconclusive`, and `3` for `blocked`.
+
+The compact context pack gives an agent authoritative facts first and evidence references on demand.
+
+Call `build.plan` or the SDK `plan()` method before the agent acts. The plan contains the objective, baseline digest, authoritative context, compatibility decisions, ordered steps, and validation gates. For example, a Spring Boot 3 repository using `javax.persistence` receives an evidence-backed recommendation to use `jakarta.persistence` and the `jakarta.persistence:jakarta.persistence-api` coordinate instead. Framework-managed versions are reported as managed rather than guessed.
+
+## HTTP integration
+
+```bash
+buildanchor serve --workspace . --listen 127.0.0.1:8787
+curl -X POST http://127.0.0.1:8787/v1/inspect \
+  -H 'content-type: application/json' \
+  -d '{}'
+```
+
+## Python SDK
+
+```python
+from buildanchor import BuildAnchorClient
+
+client = BuildAnchorClient(workspace=".")
+baseline = client.inspect()
+result = client.validate_change()
+```
+
+Use `AsyncBuildAnchorClient` for asynchronous orchestration or set `endpoint="http://127.0.0.1:8787"` for a remote HTTP server. See [`sdk/python/README.md`](sdk/python/README.md).
+
+## Java SDK
+
+Maven coordinates:
+
+```text
+com.buildanchor:buildanchor-sdk:0.1.0
+```
+
+```java
+try (BuildAnchorClient client = BuildAnchorClient.builder()
+        .workspace(Path.of("."))
+        .build()) {
+    BuildAnchorResponse baseline = client.inspect();
+    BuildAnchorResponse result = client.validateChange("HEAD");
+}
+```
+
+See [`sdk/java/README.md`](sdk/java/README.md).
+
+## GitHub and agent integration
+
+BuildAnchor needs a Git baseline for change validation. In a new checkout, create one before validating:
+
+```bash
+git add .
+git commit -m "baseline"
+buildanchor validate-change --baseline HEAD --execute --format markdown
+```
+
+For pull requests, use the base commit supplied by GitHub Actions:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: astral-sh/setup-uv@v6
+- run: uvx --from buildanchor buildanchor validate-change --baseline "${{ github.event.pull_request.base.sha }}" --execute --format sarif > buildanchor.sarif
+```
+
+To connect an agent through MCP, point it at a bounded checkout:
+
+```json
+{
+  "mcpServers": {
+    "buildanchor": {
+      "command": "buildanchor",
+      "args": ["mcp", "--stdio", "--allow-root", "/path/to/repository"]
+    }
+  }
+}
+```
+
+## Supported ecosystems
+
+The first MVP detects Maven, Gradle, Node, Python, Go, Rust, .NET, and generic build markers such as Make, CMake, Bazel, Swift Package Manager, Composer, Bundler, and pub. Static inspection is always explicit about unsupported, unavailable, and policy-blocked capabilities. Validation is intentionally two-stage: static Git/change analysis first, then explicit probe execution when the caller opts in.
+
+## Security model
+
+BuildAnchor is read-only and offline-capable by default. It contains workspace paths, uses fixed probe names, does not accept raw agent commands, limits output and execution, redacts credential-bearing values, and records evidence digests. Live resolution and validation should run only through an enterprise-approved sandbox and policy.
+
+Read [`SECURITY.md`](SECURITY.md) before enabling networked or executable probes.
+
+## Support and feedback
+
+Use [GitHub Discussions](https://github.com/tensilestream/buildanchor/discussions) for usage
+questions and design conversations. Use [GitHub Issues](https://github.com/tensilestream/buildanchor/issues)
+for reproducible bugs, installation problems, and feature requests. Use the private reporting
+channel described in [`SECURITY.md`](SECURITY.md) for vulnerabilities.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -v
+javac --release 17 -d /tmp/buildanchor-java-classes sdk/java/src/main/java/com/buildanchor/*.java
+```
+
+Run the local benchmark harness when changing inspection, context, or planning behavior:
+
+```bash
+uv run python benchmarks/benchmark_cli.py --iterations 20 --warmups 3 --format text
+```
+
+The benchmarks report local latency for a deterministic representative fixture. They are
+engineering baselines, not claims of guaranteed time saved for every repository or team.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development, testing, adapter, and release guidelines.
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).