Metadata-Version: 2.4
Name: ruche
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: A git-backed store for cross-cutting work items
Keywords: cli,git,work-items,issues,tasks
Author-email: Geoffrey Guéret <geoffrey@gueret.dev>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/ggueret/ruche/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ggueret/ruche#readme
Project-URL: Homepage, https://github.com/ggueret/ruche
Project-URL: Issues, https://github.com/ggueret/ruche/issues
Project-URL: Repository, https://github.com/ggueret/ruche.git

# ruche

A git-backed store for cross-cutting work items.

> **Status: early reservation release (v0.1.0).** Packaging, CI, and the test
> harness are in place. The commands parse but are not implemented yet; each one
> exits non-zero with "not yet implemented". Follow the roadmap below.

## What it is

ruche keeps work items (issues, tasks, decisions) inside your git repository,
next to the code they concern, instead of in a separate tracker. The store is
plain files committed to git. A derived SQLite + FTS5 index makes reads fast and
is always reconciled to `HEAD` before an index-backed read, while trust-critical
reads bypass it entirely.

One core, several faces: a Rust library (`ruche-core`), a command-line tool
(`ruche`), a Python package on PyPI, and (later) an MCP server.

```mermaid
flowchart TD
    core["ruche-core: store, index, merge driver, provenance"]
    cli["ruche (CLI)"]
    py["Python wheel (PyPI)"]
    mcp["ruche-mcp (planned)"]
    cli --> core
    py --> core
    mcp -. planned .-> core
```

## The hive

ruche means "hive" in French. The apian metaphor lives in the concepts and the
docs; the commands themselves stay plain English.

| Concept | Term |
| --- | --- |
| a work item | *alvéole* (cell) |
| an active item | *couvain* (brood) |
| closing an item | *operculer* (to cap a cell) |
| a graduating seed | *essaim* / *essaimer* (swarm) |
| the merge gate | *les gardiennes* (the guard bees) |
| propose, then apply | *la danse* (the waggle dance) |

## Install

Once published:

```sh
cargo install ruche      # the CLI
pip install ruche        # the CLI plus a thin Python binding
```

## Commands

`capture`, `search`, `board`, `get`, `update`, `note`, `triage` (`--apply`),
`decide` (`--apply`), `cap`, `swarm`, `context`, `scope rename`, `reindex`,
`doctor`, `migrate`, `init`, `merge-driver`.

## Roadmap

The intended stack, each piece added when it is built, not before:

- `gix` for git access
- `rusqlite` + FTS5 for the derived index
- `ulid` for ids
- `serde` plus a YAML crate for row frontmatter
- `rmcp` for the MCP face (`ruche-mcp`)
- `PyO3` + `maturin` for the PyPI wheel (already wired)

## Workspace layout

- `crates/ruche-core`: the library (store, index, write path, merge driver,
  provenance); module seams only for now.
- `crates/ruche`: the CLI, built on `ruche-core`.
- `crates/ruche-py`: the PyO3/maturin crate that builds the PyPI wheel.

## License

Dual-licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE),
at your option.

