Metadata-Version: 2.4
Name: emkeel
Version: 0.1.10
Summary: Adopt-and-thin SDLC governance framework
Author: EMillion Networking LTD
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Emkeel

**Adopt-and-thin SDLC governance for AI-assisted teams.** Emkeel turns a repo into a
governed project: every change flows ticket → branch → PR → deterministic CI gates →
human-approved merge → the ticket closes itself. `"done"` is a **computed fact**, never a
self-attested flag — enforcement lives server-side (CI + branch protection), out of the
agent's reach.

## Getting started

**You'll need:** Python 3.11+, [`pipx`](https://pipx.pypa.io) (`sudo apt install pipx` on
Debian/Ubuntu), `git`, a GitHub account, and a Jira account + a project.

1. **Install Emkeel** — use pipx (one method; see the note below):

   ```bash
   pipx install emkeel        # already have it? → pipx upgrade emkeel
   ```

2. **Open your project** in your editor — an existing repo, or a new empty folder.

3. **Run the guided setup:**

   ```bash
   emkeel onboard
   ```

   Paste its output to your AI coding agent (VS Code + Claude Code, Cursor, …) and it sets the
   repo up **in your language**, handing you the exact links for the steps only you can do
   (create secrets, turn on branch protection). Or follow the printed steps yourself.

## Managing Emkeel

| Action | Command |
| --- | --- |
| **Install** | `pipx install emkeel` |
| **Upgrade** (already installed) | `pipx upgrade emkeel` |
| **Check version / updates** | `emkeel version` |
| **Set up a repo** | `emkeel onboard` (AI-guided) · or `emkeel init` (manual, below) |
| **Remove from a repo** | `emkeel uninstall` (preview; add `--yes` to apply — keeps `emkeel-governance/`) |
| **Remove the tool** | `pipx uninstall emkeel` |

> **Use one install method.** With pipx, `pipx install emkeel` detects an existing install and
> tells you to `pipx upgrade emkeel` — so a re-run never makes a mess. **Don't mix** pipx with
> `pip --user`/venv; that creates shadowing, conflicting installs. No pipx available? A venv is
> idempotent too: `python3 -m venv .venv && . .venv/bin/activate && pip install -U emkeel`.
>
> **Updates are safe:** your repo's CI pins `emkeel~=0.MINOR.0` — it auto-takes patches and
> minors; a breaking major (e.g. `0.2.0`) is opt-in (you bump the pin).

## Manual setup (no AI)

```bash
# existing repo
emkeel init . --github-repo OWNER/REPO --jira-url https://you.atlassian.net --jira-project KEY

# new project
mkdir my-project && cd my-project && git init
emkeel init . --github-repo OWNER/REPO --jira-url https://you.atlassian.net --jira-project KEY
```

`emkeel init` is non-clobbering (add `--dry-run` to preview) and prints the exact links to
finish setup. Full guide: `docs/install.md`.

## What you get

- **Deterministic CI gates** (server-side, can't be skipped): every change links a ticket;
  features carry a spec with acceptance criteria; the full test suite runs on every PR.
- **AI review-assist** — a per-criterion verdict against the spec before you merge.
- **Auto-close** — merging transitions the linked Jira ticket to Done.
- **Clean separation** — governance artifacts live in one `emkeel-governance/` folder, never shipped.

See `docs/lifecycle.md` for the model.

---
Licensed under **Apache-2.0** — © 2026 EMillion Networking LTD (see `LICENSE` / `NOTICE`).
