Metadata-Version: 2.5
Name: polaralias-rke
Version: 0.9.0
Summary: Repository Knowledge Engineering runtime with shared CLI and MCP operations.
Project-URL: Repository, https://github.com/polaralias/rke
Author: James Whelan / Polaralias
License: 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.
        
        "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.
        
        "Work" shall mean the work of authorship, whether in Source or Object form,
        made available under the License.
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that
        is based on (or derived from) the Work.
        
        "Contribution" shall mean any work of authorship intentionally submitted to
        Licensor for inclusion in the Work.
        
        "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 patent license to make, have made, use, offer to sell, sell,
        import, and otherwise transfer the Work.
        
        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.
        
        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.
        
        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 on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
        
        8. Limitation of Liability.
        
        In no event and under no legal theory shall any Contributor be liable to You
        for damages arising as a result of this License or out of the use or inability
        to use the Work.
        
        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.
        
        Copyright (c) 2026 James Whelan / Polaralias
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: tree-sitter-language-pack<2,>=1.20
Requires-Dist: tree-sitter<0.27,>=0.26
Description-Content-Type: text/markdown

# RKE

Repository Knowledge Engineering is an installable local runtime and methodology for understanding codebases, maintaining trustworthy documentation, and preserving engineering evidence across agent sessions.

RKE follows a documentation-driven-development principle: accepted behaviour and durable repository knowledge guide implementation, while source, tests and runtime evidence continuously verify that documentation remains true. RKE supplies the deterministic mechanics; the `engineering-workflow` skill supplies agent routing, judgement and lifecycle policy.

## Identity and boundaries

- **RKE** owns repository retrieval, structural analysis, knowledge bindings, documentation impact, causal change comprehension and workflow evidence.
- **Engineering Workflow (EWF)** is the agent-facing skill and the normal entry point for material engineering work.
- **OKF Tasks** remains an independent execution-record specification and CLI. RKE delegates strict task validation rather than copying its schema or lifecycle.
- **Doc-driven development** is the guiding principle. RKE is the methodology and toolchain that operationalises it.

The runtime is installed once per machine. Every operation selects its repository explicitly; state, indexes and receipts remain inside that repository. Tracked RKE knowledge bindings live under `.rke/`; EWF lifecycle state remains separate under `.engineering-workflow/`. One MCP process can serve multiple repositories without merging their evidence.

## Normal engineering journey

Use one installed runtime and one EWF entry point:

```text
activate → retrieve/trace → change → documentation assess → explain → apply → close
```

The agent chooses the smallest relevant operations for the work. Retrieval and traces guide inspection; they do not replace source verification. Documentation assessment and causal explanation operate on the actual Git delta, and apply validates agent-authored canonical knowledge before close accepts the exact-delta receipts.

## Install

```powershell
python -m pip install .
```

For development:

```powershell
python -m pip install -e .
```

Install the paired agent skill from the same release:

```powershell
npx skills add polaralias/rke --global --skill engineering-workflow
```

The runtime and skill are released together but remain separate installation surfaces: Python supplies stable executables; the skill installer places agent instructions where each supported host discovers them.

Installed commands:

- `rke` — canonical CLI for workflow, retrieval, structure, knowledge and documentation operations.
- `rke-mcp` — optional multi-repository MCP stdio adapter over the same operation registry.
- `rke-session-start`, `rke-pre-compaction`, and `rke-pre-push` — stable lifecycle-hook entry points.
- `rke-eval` — bounded model-behaviour evaluation; unlike deterministic tests, this consumes model usage.

## Examples

```powershell
rke activate --phase deliver --task-mode none --root C:\repos\service
rke context find "where are credentials hydrated" --root C:\repos\service
rke structure trace hydrateCredentials --direction both --root C:\repos\service
rke dissection assess --root C:\repos\service
rke documentation bootstrap --root C:\repos\service
rke handoff write --topic credential-runtime --summary "Provider path is mapped." --next-action "Run the integration test." --root C:\repos\service
rke handoff write --visibility shared --topic credential-runtime --summary "Provider path is mapped." --next-action "Run the integration test." --root C:\repos\service
rke coordination validate --manifest local-docs/worktrees.json --root C:\repos\service
rke publication scan --root C:\repos\service
rke documentation assess --base main --root C:\repos\service
rke change explain --base main --summary "Moved credential hydration behind the provider boundary." --root C:\repos\service
```

Register the optional machine-wide MCP adapter once:

```powershell
codex mcp add rke -- rke-mcp
```

MCP operations require a `repository` path in each tool call. Use one or more `--allow-root <directory>` options when the server should be restricted to known workspace parents. `rke-mcp --root <repository>` remains available only as a compatibility mode for fixed-root clients.

Install repository routing and the pre-push closure gate with:

```powershell
rke host install --host codex --base main --root C:\repos\service
```

The gate lives at `.githooks/pre-push`; installation configures `core.hooksPath=.githooks`. An independently configured hook path is preserved unless the caller deliberately supplies `--force`. Codex user-level MCP activation remains a separate explicit command returned by the installer.

## Retrieval and structural scope

Repository retrieval uses BM25F and Git-backed content identity. Clean tracked files reuse Git object identity only after a batched, filter-aware content check; dirty, staged, untracked, uncertain and mismatched files are content-hashed by the indexer. Non-Git fallback traversal prunes dependency, vendor, archive and cache directories before descent. Known credential locations are omitted, secret-like values are redacted, and the response reports those boundaries without returning the values.

Structural operations detect package and source scopes automatically, cache graph shards and widen only when the first likely scope is insufficient. Use repeatable `--scope <relative-path>` options to override selection or combine scopes. Whole-repository analysis fuses bounded shards instead of rejecting a repository at an arbitrary file count. Tree-sitter is preferred; unavailable or inconclusive parsing returns a bounded agent-review packet with explicit confidence and uncertainty.

## Evaluation and release

The `0.9.x` line is the pre-1.0 dogfood series: its implementation and proposed public contract are feature-complete enough for real repository use, while compatibility findings may still produce pre-1.0 changes. RKE moves to `1.0.0` only after dogfood validates the stability contract; fixes discovered during that period ship as `0.9.x` releases.

`rke-eval` loads its packaged corpus without a repository-relative data dependency. It invokes a configured model and consumes model usage, so deterministic tests remain the default inner loop.

Run `python scripts/benchmark_freshness.py` to measure cold indexing, warm retrieval and one changed file across 1k, 10k and 50k tracked-file fixtures. Override the matrix with `--sizes`; the full default benchmark is intentionally kept out of routine CI.

`rke.__version__` is the only version source. Release Drafter prepares one serialized draft from that version. A matching `vX.Y.Z` tag runs the complete tests, separately clean-installs wheel and sdist, attests both artifacts, and submits them to PyPI through trusted publishing when the repository `pypi` environment is configured. Only a successful PyPI job promotes or creates the single public GitHub release, and that job receives explicit `GH_REPO` identity rather than depending on a checkout. Published tags are immutable.

## Preserved workflows

Query-to-Knowledge and Repository Change Comprehension remain distinct named concepts:

- **Query-to-Knowledge (QTK)** is a human clarification loop. It groups consequential questions, recommends answers with rationale, and keeps a hard `shared-understanding` gate open until the user and agent agree on an implementation target. It is not ordinary repository orientation.
- **Repository Change Comprehension (RCC)** reconstructs the causal behaviour of the final Git delta and records a bounded explanation receipt. It is not a changed-file summary.

The formerly separate repository-dissection, design/decomposition, session-alignment, local handoff/pickup, and worktree-coordination behaviours now live as deep journeys and shared RKE operations behind EWF. Tracker synchronization remains in OKF Tasks. Scenario and test planning are part of design acceptance rather than a second optional QA workflow.

## Source layout

- `src/rke/` — canonical runtime and shared operation registry.
- `skills/engineering-workflow/` — canonical EWF skill source, directly discoverable by standard skill installers.
- `skills/engineering-workflow/references/` — skill-only operating contracts, journeys, and opt-in extensions loaded through progressive disclosure.
- `docs/knowledge/` — canonical RKE project knowledge; it does not duplicate skill instructions.
- `tests/` — transport parity, retrieval, structure, lifecycle, documentation and security tests.
- `scripts/` — compatibility wrappers for the original source layout; installed consumers should use the console commands.

The copy of `engineering-workflow` in the Polaralias skills catalogue is a synchronized distribution mirror. Runtime implementation does not live in the skills repository.

The planned 1.x public-interface, repository-format, directory-ownership, deprecation, and runtime-to-skill promises are consolidated in [docs/compatibility.md](docs/compatibility.md).
