adra 0.4.0__tar.gz

adra-0.4.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Felipe Santibáñez-Leal
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adra-0.4.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: adra
+Version: 0.4.0
+Summary: ADRA — Adversarial Dev Review Agent: a deterministic-first, adversarial-validation engine for the software lifecycle (PR review, validation/refutation experiments, auto-docs, human escalation).
+Author: Felipe Santibáñez-Leal
+License: Apache-2.0
+Keywords: llm,agent,code-review,adversarial-validation,llm-as-judge,devops,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: llm
+Requires-Dist: pydantic-ai-slim[anthropic,google,groq,openai]<2,>=1; extra == "llm"
+Provides-Extra: github
+Requires-Dist: httpx>=0.27; extra == "github"
+Provides-Extra: azuredevops
+Requires-Dist: httpx>=0.27; extra == "azuredevops"
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.30; extra == "databricks"
+Provides-Extra: azure
+Requires-Dist: azure-identity>=1.17; extra == "azure"
+Requires-Dist: azure-monitor-query>=1.3; extra == "azure"
+Provides-Extra: all
+Requires-Dist: pydantic-ai-slim[anthropic,google,groq,openai]<2,>=1; extra == "all"
+Requires-Dist: httpx>=0.27; extra == "all"
+Requires-Dist: databricks-sdk>=0.30; extra == "all"
+Requires-Dist: azure-identity>=1.17; extra == "all"
+Requires-Dist: azure-monitor-query>=1.3; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: pydantic-ai-slim[anthropic]<2,>=1; extra == "dev"
+Requires-Dist: databricks-sdk>=0.30; extra == "dev"
+Requires-Dist: azure-identity>=1.17; extra == "dev"
+Requires-Dist: azure-monitor-query>=1.3; extra == "dev"
+Dynamic: license-file
+
+# ADRA — Adversarial Dev Review Agent
+
+> A **client-agnostic, deterministic-first, adversarial-validation engine** that supports
+> the software lifecycle: it reviews PRs, designs and runs validation/refutation
+> experiments, writes documentation back, and **escalates to a human** exactly where a
+> senior engineer would. Governed by **LLM-as-Judge + a blocking adversarial critic**,
+> grounded by **deterministic tools**, with **immutable provenance**. Runs **offline with
+> no API key**.
+
+`pip install adra` · Python ≥ 3.11 · Apache-2.0 · status: `v0.04.000`
+
+---
+
+## What's different
+
+The AI-code-review market splits in two, and both miss the same spot:
+
+- **Reviewers** (CodeRabbit, Greptile, Qodo, Korbit, Sourcery, Bito) feed linters into an
+  LLM, but the **model's prose is the verdict** — hallucinated and "consistently-stated-
+  but-false" findings leak through; the deterministic signals are inputs, never the gate.
+- **Autonomous coders** (Devin, OpenHands, SWE-agent, Sweep) *write* code and treat
+  "tests pass" as success rather than adversarially trying to prove the change **wrong**.
+
+ADRA occupies the gap: a **deterministic spine** (git / CI / static analysis / SQL probes)
+that *grounds* a **blocking adversarial critic** whose job is to **refute**, not bless, each
+artifact — every finding carrying its evidence, with disciplined **human escalation** when
+nothing deterministic backs the verdict. Existing tools generate opinions; ADRA generates
+proofs and refutations, and escalates when it can't.
+
+## The six capabilities
+
+| Skill | What it does |
+|---|---|
+| `code_review` | Review a diff: language/leak scan + test-discoverability + exact CI command + semantic findings |
+| `pr_eval` | Evaluate a PR: merge-base health → `bundle validate` → conformance → verdict + PR body |
+| `experiment` | Hypothesis-driven validation experiment: SQL-warehouse probes + synthesis |
+| `improve` | Minimum-functional improvement proposal (prune filler, smallest safe diff) |
+| `document` | Turn a run record into a PR page / experiment page / methodology-history row |
+| `decide` | Route analysis: candidate routes + trade-offs + recommendation — **human-owned** |
+
+Each skill is the same loop, differing only by its domain prompt and deterministic tools.
+
+## Why deterministic-first
+
+Tools (`git`, the exact CI command, `bundle validate`, language scan, SQL probe) run
+**first** and become both the grounding the model may not contradict and the evidence in
+the provenance log. Because the deterministic floor carries the verdict, the whole loop
+runs — and the test suite passes — **offline with no API key**. Connecting a real provider
+adds the semantic layer on top.
+
+## Architecture
+
+```
+intake ─▶ plan ─▶ ground (deterministic tools) ─▶ generate ─▶ CRITIC ─┐
+                                                      ▲   revise ◀──────┘
+                                                      └── accepted / escalate ─▶ artifacts + run record
+```
+
+- `adra/state.py` — the typed **domain model** (`Severity`, `Finding`, `ToolResult`,
+  `CriticVerdict`, `RunState`). One contract end to end.
+- `adra/rubric.py` — the shared adversarial **rubric** (criteria as typed data); drives both
+  the deterministic critic and the critic prompt, so "what we check" never drifts.
+- `adra/orchestrator.py` — the hand-rolled, **framework-free** state machine.
+- `adra/critic.py` — deterministic red-team pass (rubric-driven) + LLM semantic attacks.
+- `adra/judge.py` — rubric scoring with **swap-and-average** + reference anchoring.
+- `adra/llm.py` — the tiny ADRA-owned `ChatModel` seam: `mock` (offline) | any real provider
+  via **pydantic-ai** (`provider:model`, config-only). No LangChain/LangGraph.
+- `adra/tools/` — each returns a `ToolResult` (git / CI / bundle / lang / discovery / sql).
+- `adra/skills/` — the `Skill` base + the six skills.
+- `adra/clients/` — client governance suites (the bundled fictional **Northwind Data
+  Platform**); selectable via `ADRA_CLIENT_DIR`.
+- `adra/provenance.py` — the immutable run record (the deep change-history layer).
+- `cli/` — the `adra` command. `refs/` — annotated bibliography + papers. `docs/` — deep
+  docs + engine ADRs (`docs/adr/`).
+
+## Quickstart (offline, no key)
+
+```bash
+python -m venv .venv && . .venv/Scripts/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest -q                                            # 11 passing, fully offline
+python scripts/demo_offline.py                       # end-to-end demo, all six skills
+```
+
+Expected: the stale-base PR is **blocked + escalated** (12 commits behind, a notebook
+deletion, a `.yml → .yml.t` rename dropping a bundle resource, `bundle validate` failing);
+the language/leak review is **blocked**; the clean experiment / improve / document / decide
+runs are **accepted**.
+
+```bash
+adra review path/to.diff --ci-command 'python -m coverage run -m unittest discover -s . -p "test*.py"'
+adra decide "Raise the refresh cadence" "edit the shared CI template" "change it in the owning repo"
+```
+
+## Enable a real provider
+
+```bash
+pip install -e ".[llm]"                  # pydantic-ai; the seam is provider-agnostic
+export ANTHROPIC_API_KEY=...             # or put it in .env (any provider's key works)
+export ADRA_PROVIDER=anthropic           # adding a provider is config only: ADRA_PROVIDER / ADRA_MODEL / ADRA_MODEL_<ROLE>
+adra pr-eval --source task/123/x --repo /path/to/repo --external
+```
+
+`--external` (or `ADRA_ALLOW_EXTERNAL=1`) lets the tools actually run git / the CI command.
+Default is **dry-run / read-only**.
+
+## Client-agnostic grounding
+
+A *client* = a governance suite (conventions, ADRs, CI standards, glossary, incident cases)
+the engine grounds on. ADRA ships a complete, **fictional** client — **Northwind Data
+Platform** — under `adra/clients/synthetic/northwind/`. Point ADRA at any client:
+
+```bash
+export ADRA_CLIENT_DIR=/path/to/your/standards   # or Settings(client_dir=...)
+```
+
+The rubric references the suite by id and the prompts cite it — the engine code does not
+change per client.
+
+## Connectors & emulator
+
+The engine grounds through one connector `Protocol` so the same skills run against a real
+platform or a synthetic one:
+
+- **Real**: GitHub (PRs/reviews/issues/contents via a thin `httpx` REST v3 client), Azure DevOps
+  (REST 7.1), Databricks (`databricks-sdk` + bundles CLI), Azure (`azure-identity` + monitor / health).
+- **Emulator**: a self-contained platform (synthetic git repos + PRs + wiki + boards + CI +
+  a SQLite warehouse) so the full flow runs offline.
+
+> The GitHub, Azure DevOps, Databricks, and Azure connectors are **implemented**; the offline
+> emulator runs the full flow with no external calls. Each is enabled by its `pip install adra[...]`
+> extra and exercised read-only by default.
+
+## Security model
+
+Deterministic floor (tools are ground truth; the LLM cannot overturn a blocker) · read-only
+by default (writes require `--external` **and** explicit human confirmation) · human gates on
+PR create / push / merge and any risk claim · English-only + AI-authorship-leak scan on
+anything written to disk · immutable provenance for every run. The agent reads **untrusted**
+repo/PR/issue content — a dual-LLM / capability split + sandboxed, egress-filtered execution are
+planned for the connector phase (not yet implemented; OWASP LLM/Agentic Top-10).
+
+## Two-repo layout
+
+ADRA is the **public-destined OSS engine** (this repo) — no secrets, ever. A separate
+private **ADRA Console** (a private web app + backend) *consumes* this engine for
+experiments and real connections behind access control. The engine is the serious tool you
+can run anywhere with your own tokens; the console is the connected instance.
+
+## Extending
+
+- **New criterion:** add a `RubricItem` to `adra/rubric.py` (it shows up in the critic
+  prompt and, if `kind="deterministic"`, wire its check in `critic.py`).
+- **New capability:** add a `Skill` subclass + a `prompts/<skill>.md`, register it in
+  `adra/skills/__init__.py`, add a `Node`.
+- **New tool:** a function returning a `ToolResult`; call it from a skill's `ground`.
+- **New provider:** config only — set `ADRA_PROVIDER` / `ADRA_MODEL` / `ADRA_MODEL_<ROLE>`
+  (pydantic-ai resolves the `provider:model`); no new code.
+
+## Status
+
+`v0.04.000` — the engine is complete and green offline, and the GitHub / Azure DevOps / Databricks
+/ Azure connectors plus the offline emulator are implemented. Multi-industry synthetic clients and
+the web console are the next phases. Stays `0.x` while connectors are partly untested-live.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).
+
+## References
+
+`refs/` holds an annotated bibliography (`refs/README.md`) + BibTeX (`refs/references.bib`)
++ the core papers (ReAct, Reflexion, Self-Refine, Constitutional AI, LLM-as-judge bias,
+agentic security / CaMeL, NIST AI RMF, OWASP LLM/Agentic, provenance, code-review agents).

adra-0.4.0/README.md

@@ -0,0 +1,174 @@
+# ADRA — Adversarial Dev Review Agent
+
+> A **client-agnostic, deterministic-first, adversarial-validation engine** that supports
+> the software lifecycle: it reviews PRs, designs and runs validation/refutation
+> experiments, writes documentation back, and **escalates to a human** exactly where a
+> senior engineer would. Governed by **LLM-as-Judge + a blocking adversarial critic**,
+> grounded by **deterministic tools**, with **immutable provenance**. Runs **offline with
+> no API key**.
+
+`pip install adra` · Python ≥ 3.11 · Apache-2.0 · status: `v0.04.000`
+
+---
+
+## What's different
+
+The AI-code-review market splits in two, and both miss the same spot:
+
+- **Reviewers** (CodeRabbit, Greptile, Qodo, Korbit, Sourcery, Bito) feed linters into an
+  LLM, but the **model's prose is the verdict** — hallucinated and "consistently-stated-
+  but-false" findings leak through; the deterministic signals are inputs, never the gate.
+- **Autonomous coders** (Devin, OpenHands, SWE-agent, Sweep) *write* code and treat
+  "tests pass" as success rather than adversarially trying to prove the change **wrong**.
+
+ADRA occupies the gap: a **deterministic spine** (git / CI / static analysis / SQL probes)
+that *grounds* a **blocking adversarial critic** whose job is to **refute**, not bless, each
+artifact — every finding carrying its evidence, with disciplined **human escalation** when
+nothing deterministic backs the verdict. Existing tools generate opinions; ADRA generates
+proofs and refutations, and escalates when it can't.
+
+## The six capabilities
+
+| Skill | What it does |
+|---|---|
+| `code_review` | Review a diff: language/leak scan + test-discoverability + exact CI command + semantic findings |
+| `pr_eval` | Evaluate a PR: merge-base health → `bundle validate` → conformance → verdict + PR body |
+| `experiment` | Hypothesis-driven validation experiment: SQL-warehouse probes + synthesis |
+| `improve` | Minimum-functional improvement proposal (prune filler, smallest safe diff) |
+| `document` | Turn a run record into a PR page / experiment page / methodology-history row |
+| `decide` | Route analysis: candidate routes + trade-offs + recommendation — **human-owned** |
+
+Each skill is the same loop, differing only by its domain prompt and deterministic tools.
+
+## Why deterministic-first
+
+Tools (`git`, the exact CI command, `bundle validate`, language scan, SQL probe) run
+**first** and become both the grounding the model may not contradict and the evidence in
+the provenance log. Because the deterministic floor carries the verdict, the whole loop
+runs — and the test suite passes — **offline with no API key**. Connecting a real provider
+adds the semantic layer on top.
+
+## Architecture
+
+```
+intake ─▶ plan ─▶ ground (deterministic tools) ─▶ generate ─▶ CRITIC ─┐
+                                                      ▲   revise ◀──────┘
+                                                      └── accepted / escalate ─▶ artifacts + run record
+```
+
+- `adra/state.py` — the typed **domain model** (`Severity`, `Finding`, `ToolResult`,
+  `CriticVerdict`, `RunState`). One contract end to end.
+- `adra/rubric.py` — the shared adversarial **rubric** (criteria as typed data); drives both
+  the deterministic critic and the critic prompt, so "what we check" never drifts.
+- `adra/orchestrator.py` — the hand-rolled, **framework-free** state machine.
+- `adra/critic.py` — deterministic red-team pass (rubric-driven) + LLM semantic attacks.
+- `adra/judge.py` — rubric scoring with **swap-and-average** + reference anchoring.
+- `adra/llm.py` — the tiny ADRA-owned `ChatModel` seam: `mock` (offline) | any real provider
+  via **pydantic-ai** (`provider:model`, config-only). No LangChain/LangGraph.
+- `adra/tools/` — each returns a `ToolResult` (git / CI / bundle / lang / discovery / sql).
+- `adra/skills/` — the `Skill` base + the six skills.
+- `adra/clients/` — client governance suites (the bundled fictional **Northwind Data
+  Platform**); selectable via `ADRA_CLIENT_DIR`.
+- `adra/provenance.py` — the immutable run record (the deep change-history layer).
+- `cli/` — the `adra` command. `refs/` — annotated bibliography + papers. `docs/` — deep
+  docs + engine ADRs (`docs/adr/`).
+
+## Quickstart (offline, no key)
+
+```bash
+python -m venv .venv && . .venv/Scripts/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest -q                                            # 11 passing, fully offline
+python scripts/demo_offline.py                       # end-to-end demo, all six skills
+```
+
+Expected: the stale-base PR is **blocked + escalated** (12 commits behind, a notebook
+deletion, a `.yml → .yml.t` rename dropping a bundle resource, `bundle validate` failing);
+the language/leak review is **blocked**; the clean experiment / improve / document / decide
+runs are **accepted**.
+
+```bash
+adra review path/to.diff --ci-command 'python -m coverage run -m unittest discover -s . -p "test*.py"'
+adra decide "Raise the refresh cadence" "edit the shared CI template" "change it in the owning repo"
+```
+
+## Enable a real provider
+
+```bash
+pip install -e ".[llm]"                  # pydantic-ai; the seam is provider-agnostic
+export ANTHROPIC_API_KEY=...             # or put it in .env (any provider's key works)
+export ADRA_PROVIDER=anthropic           # adding a provider is config only: ADRA_PROVIDER / ADRA_MODEL / ADRA_MODEL_<ROLE>
+adra pr-eval --source task/123/x --repo /path/to/repo --external
+```
+
+`--external` (or `ADRA_ALLOW_EXTERNAL=1`) lets the tools actually run git / the CI command.
+Default is **dry-run / read-only**.
+
+## Client-agnostic grounding
+
+A *client* = a governance suite (conventions, ADRs, CI standards, glossary, incident cases)
+the engine grounds on. ADRA ships a complete, **fictional** client — **Northwind Data
+Platform** — under `adra/clients/synthetic/northwind/`. Point ADRA at any client:
+
+```bash
+export ADRA_CLIENT_DIR=/path/to/your/standards   # or Settings(client_dir=...)
+```
+
+The rubric references the suite by id and the prompts cite it — the engine code does not
+change per client.
+
+## Connectors & emulator
+
+The engine grounds through one connector `Protocol` so the same skills run against a real
+platform or a synthetic one:
+
+- **Real**: GitHub (PRs/reviews/issues/contents via a thin `httpx` REST v3 client), Azure DevOps
+  (REST 7.1), Databricks (`databricks-sdk` + bundles CLI), Azure (`azure-identity` + monitor / health).
+- **Emulator**: a self-contained platform (synthetic git repos + PRs + wiki + boards + CI +
+  a SQLite warehouse) so the full flow runs offline.
+
+> The GitHub, Azure DevOps, Databricks, and Azure connectors are **implemented**; the offline
+> emulator runs the full flow with no external calls. Each is enabled by its `pip install adra[...]`
+> extra and exercised read-only by default.
+
+## Security model
+
+Deterministic floor (tools are ground truth; the LLM cannot overturn a blocker) · read-only
+by default (writes require `--external` **and** explicit human confirmation) · human gates on
+PR create / push / merge and any risk claim · English-only + AI-authorship-leak scan on
+anything written to disk · immutable provenance for every run. The agent reads **untrusted**
+repo/PR/issue content — a dual-LLM / capability split + sandboxed, egress-filtered execution are
+planned for the connector phase (not yet implemented; OWASP LLM/Agentic Top-10).
+
+## Two-repo layout
+
+ADRA is the **public-destined OSS engine** (this repo) — no secrets, ever. A separate
+private **ADRA Console** (a private web app + backend) *consumes* this engine for
+experiments and real connections behind access control. The engine is the serious tool you
+can run anywhere with your own tokens; the console is the connected instance.
+
+## Extending
+
+- **New criterion:** add a `RubricItem` to `adra/rubric.py` (it shows up in the critic
+  prompt and, if `kind="deterministic"`, wire its check in `critic.py`).
+- **New capability:** add a `Skill` subclass + a `prompts/<skill>.md`, register it in
+  `adra/skills/__init__.py`, add a `Node`.
+- **New tool:** a function returning a `ToolResult`; call it from a skill's `ground`.
+- **New provider:** config only — set `ADRA_PROVIDER` / `ADRA_MODEL` / `ADRA_MODEL_<ROLE>`
+  (pydantic-ai resolves the `provider:model`); no new code.
+
+## Status
+
+`v0.04.000` — the engine is complete and green offline, and the GitHub / Azure DevOps / Databricks
+/ Azure connectors plus the offline emulator are implemented. Multi-industry synthetic clients and
+the web console are the next phases. Stays `0.x` while connectors are partly untested-live.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).
+
+## References
+
+`refs/` holds an annotated bibliography (`refs/README.md`) + BibTeX (`refs/references.bib`)
++ the core papers (ReAct, Reflexion, Self-Refine, Constitutional AI, LLM-as-judge bias,
+agentic security / CaMeL, NIST AI RMF, OWASP LLM/Agentic, provenance, code-review agents).

adra-0.4.0/adra/__init__.py

@@ -0,0 +1,36 @@
+"""ADRA — Adversarial Dev Review Agent.
+
+A client-agnostic, deterministic-first, adversarial-validation engine that supports the
+software lifecycle. It formalizes six capabilities a team runs informally under
+adversarial human direction:
+
+    code_review | pr_eval | experiment | improve | document | decide
+
+The design spine is *adversarial validation*: every generated artifact is passed through
+a blocking, tool-grounded adversarial critic before it is accepted, and every run emits
+an immutable provenance record (the deep change history). Deterministic tools
+(git / CI / SQL / static analysis) are ground truth; the LLM only adds what tools cannot
+settle. Connectors (GitHub / Azure DevOps / Databricks / Azure) and a self-contained
+offline emulator sit behind one Protocol, so the same engine runs against a real
+platform or a synthetic one.
+
+The package runs offline with a deterministic ``mock`` provider (no API key required)
+and switches to a real provider (e.g. Anthropic Claude) when its key is present.
+"""
+
+from adra.config import Settings, load_settings
+from adra.orchestrator import Orchestrator
+from adra.state import CriticVerdict, Finding, RunState, Severity, ToolResult
+
+__all__ = [
+    "Settings",
+    "load_settings",
+    "Orchestrator",
+    "Finding",
+    "Severity",
+    "ToolResult",
+    "CriticVerdict",
+    "RunState",
+]
+
+__version__ = "0.4.0"  # PEP 440 package version; display/tag version is v0.04.000 (see VERSION)