diff --git a/AGENTS.md b/AGENTS.md index 4135bc5..8b89459 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,11 @@ kernel has no workspace or third-party runtime dependency. Toolkit and providers depend on kernel and their declared direct dependencies. No published distribution may import `conformance`. +Preset implementations are maintained in the independent `Ezio2000/jharness-tools` +repository. That external project may depend on the public kernel and toolkit APIs; +this repository must never depend on or import `jharness.tools`. Kernel remains +sufficient for applications that provide their own implementations through its ports. + Use immutable values, narrow async ports, pure policies, structural sharing, bounded concurrency, monotonic deadlines, and atomic model-order commits. Do not add runtime mutation hooks, schedulers, split persistence, reflection serialization, or duplicate diff --git a/CHANGELOG.md b/CHANGELOG.md index c1dbab6..02fc7a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Changed + +- Established `jharness-tools` as an independently versioned external project rather + than a fourth distribution in this repository. + ## [0.1.2] - 2026-07-15 ### Changed diff --git a/README.md b/README.md index 41ec0d1..1efae32 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,11 @@ from jharness.toolkit import ToolRegistry There is no `jharness-python` meta distribution and no `jharness_python` import. The repository name is only the source-management boundary. +Ready-to-use preset tool implementations are maintained separately in +[`Ezio2000/jharness-tools`](https://github.com/Ezio2000/jharness-tools). That project +is optional, independently versioned, and never a dependency of the kernel, toolkit, +or providers published from this repository. + ## Implemented Specification The exact specification tag, commit, and archive digest are recorded in @@ -59,3 +64,4 @@ uv run python benchmarks/runtime_smoke.py - [Provider adapters](docs/model-providers.md) - [Performance](docs/performance.md) - [Release process](docs/releasing.md) +- [Preset tools](https://github.com/Ezio2000/jharness-tools) diff --git a/docs/decisions/0010-external-tools-project.md b/docs/decisions/0010-external-tools-project.md new file mode 100644 index 0000000..dca8b1a --- /dev/null +++ b/docs/decisions/0010-external-tools-project.md @@ -0,0 +1,47 @@ +# ADR 0010: Independent Preset Tools Project + +Status: Accepted +Date: 2026-07-16 + +## Context + +JHarness needs curated tool implementations that applications may install instead of +implementing every capability themselves. Presets have a different change rate, +dependency surface, and release lifecycle from the stable runtime contracts. Adding +them to this repository would also turn a growing capability catalogue into a fourth +coordinated product distribution. + +The kernel must remain independently sufficient. Applications can implement every +kernel port themselves and must not need preset tools merely to construct or run an +agent. + +## Decision + +Maintain presets in the independent +[`Ezio2000/jharness-tools`](https://github.com/Ezio2000/jharness-tools) repository. +That repository owns the separately versioned `jharness-tools` distribution and the +`jharness.tools` child of the implicit PEP 420 namespace. + +`jharness-tools` is not a uv workspace member, product artifact, coordinated release, +or dependency of this repository. Its permitted dependency direction is: + +```text +jharness-tools -> jharness-toolkit -> jharness-kernel +jharness-tools --------------------> jharness-kernel +``` + +Kernel, toolkit, and providers never import or depend on `jharness.tools`. Installing +the external distribution does not automatically discover, register, or activate any +tool; applications explicitly construct the presets they choose and supply them +through kernel contracts. + +## Consequences + +- This repository continues to publish exactly the three distributions accepted by + ADR 0009. +- Presets can evolve and release without changing the coordinated Python SDK version. +- Preset-specific dependencies and security policies remain outside the kernel. +- Kernel retains stable extension ports and remains sufficient without auxiliary + packages. +- The installed `jharness` namespace may contain `jharness.tools`, but no wheel from + this repository owns that subtree. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 1ceb869..4429f67 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -8,6 +8,7 @@ This repository records only Python packaging and implementation decisions: | ADR | Decision | | --- | --- | | [0009](0009-product-distributions.md) | Publish exactly three Python product distributions. | +| [0010](0010-external-tools-project.md) | Maintain preset tools as an independent external project. | Changing a portable behavior starts in the specification repository. Python-only decisions update implementation, tests, examples, documentation, and package metadata diff --git a/docs/python-package-boundaries.md b/docs/python-package-boundaries.md index f994e76..8be1c8b 100644 --- a/docs/python-package-boundaries.md +++ b/docs/python-package-boundaries.md @@ -18,6 +18,12 @@ The product has exactly three published distributions: depend on `jharness-kernel` and `jharness-toolkit`, and is excluded from product builds and published artifact verification. +The optional [`jharness-tools`](https://github.com/Ezio2000/jharness-tools) project is +maintained in a separate repository. It is not a workspace project or coordinated +product distribution here. Its independently versioned distribution may depend on +the public kernel and toolkit APIs; the dependency never points back from this +repository to preset tools. + `jharness.kernel.diagnostics` and `jharness.kernel.wire` are subpackages of the kernel distribution. They are not separate manifests or versioned artifacts. @@ -38,6 +44,9 @@ Only the documented `jharness.*` roots are product interfaces. Source distributions, wheels, examples, tests, and documentation use those roots directly. +An installation may also contain the externally owned `jharness.tools` child package. +No artifact built by this repository owns or writes files into that subtree. + ## Dependency Graph ```text @@ -46,6 +55,9 @@ jharness.kernel └── jharness.providers conformance (development only) -> jharness.kernel, jharness.toolkit + +jharness.kernel -> jharness.tools (external) +jharness.toolkit -> jharness.tools (external) ``` The diagram points from a dependency to its dependent. `jharness.kernel` @@ -142,6 +154,8 @@ unrelated invariants out of one module even when that module is still small. `jharness.kernel.diagnostics` and use the kernel's pure change verifier. - Concrete Python tool adaptation, compiled JSON Schema validation, and tool execution decorators belong in `jharness.toolkit`. +- Ready-to-use preset tool implementations belong in the independent + `Ezio2000/jharness-tools` project, not in this workspace. - Provider HTTP/SSE transport and wire codecs belong in `jharness.providers`. - Fixture parsing, controlled doubles, behavior execution, and schema inventory belong in the development-only `conformance` project. @@ -192,6 +206,10 @@ External implementations depend on kernel ports. The kernel never discovers or imports them dynamically. Extension uses narrow protocols, pure strategies, and decorators. +The independently managed `jharness-tools` project is one such extension. Installing +it is optional and cannot cause this repository's runtime packages to discover or +activate tools automatically. + General hooks, service locators, plugin registries, execution schedulers, reflection serializers, and compatibility packages are outside the package architecture.