Metadata-Version: 2.5
Name: whykit
Version: 0.3.2
Summary: Git-native evidence and decision ledger for teams and AI agents
Project-URL: Homepage, https://github.com/CometWeb-io/whykit
Project-URL: Documentation, https://github.com/CometWeb-io/whykit#readme
Project-URL: Source, https://github.com/CometWeb-io/whykit
Project-URL: Changelog, https://github.com/CometWeb-io/whykit/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/CometWeb-io/whykit/issues
Project-URL: Security, https://github.com/CometWeb-io/whykit/blob/main/SECURITY.md
Author-email: Maciej Zmitrukiewicz <hello@cometweb.io>
Maintainer-email: Maciej Zmitrukiewicz <hello@cometweb.io>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: adr,agents,audit-trail,decision-log,decision-records,evidence,git,knowledge-base,markdown,mcp,obsidian,provenance
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: mcp
Requires-Dist: mcp<2.4,>=2.2; extra == 'mcp'
Description-Content-Type: text/markdown

# WhyKit

**The layer that remembers why.**

> Git-native evidence and decision ledger for teams and AI agents.

WhyKit keeps sources, decisions, their reasoning, and review events together in
plain Markdown and Git. It gives people and tools a shared, inspectable record of
what is known, what was decided, and what still needs checking.

![WhyKit links evidence to a decision, then checks its structure and review date.](https://raw.githubusercontent.com/CometWeb-io/whykit/v0.3.2/docs/media/overview.svg)

**Python 3.11+ · No runtime dependencies · Apache-2.0**

**Status:** public alpha, available on [PyPI](https://pypi.org/project/whykit/). Source version: `0.3.2`.

[![CI](https://github.com/CometWeb-io/whykit/actions/workflows/ci.yml/badge.svg)](https://github.com/CometWeb-io/whykit/actions/workflows/ci.yml)

## 60-second quickstart

You need Python 3.11+ and [`uv` 0.13.4+](https://docs.astral.sh/uv/getting-started/installation/).
Install the latest published release, then create a vault in your own working
directory. No source checkout is needed.

<!-- quickstart:start -->
```bash
uv tool install whykit

# 1. Create a vault.
whykit init my-ledger

# 2. Register a source, then a decision that cites it.
whykit new --root my-ledger evidence \
  --source "Support ticket export, Q3" --type dataset \
  --location "https://example.com/exports/q3-tickets.csv" \
  --claims "Most onboarding tickets mention SSO"
whykit new --root my-ledger decision "Ship SSO before audit logs" \
  --owner Platform --status draft --source E-001

# 3. Check the vault and see what is due for review.
whykit lint --root my-ledger
whykit review --root my-ledger list --due-days 120
```
<!-- quickstart:end -->

If `whykit` is not found, run `uv tool update-shell` and open a new terminal.
Use `uv tool upgrade whykit` to update an existing installation. For development
or the optional Explorer, see [running from a checkout](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/guide.md#run-whykit-from-a-checkout).

What you should see:

```text
created E-001: 00-context/evidence-register.md
created D-001: 06-decisions/d-001-ship-sso-before-audit-logs.md
...
24 files — 0 error(s), 5 warning(s)
0 review(s) overdue or due by <date> (120 day(s) from <today>)
```

The vault now holds an evidence row (`E-001`), a decision record that cites it
(`D-001`), and a matching decision-log entry. The record is a draft until you
complete and [approve it](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/guide.md#approve-a-decision). Four of
the warnings are the questions in the vault's `AGENTS.md` that only you can
answer (reply language, branching rule, tone-of-voice owner, safety rules).
The fifth, `decision.placeholder`, says the new record still holds the
scaffold's prompts: open it and write the real context, decision, rationale,
alternatives and consequences. Do both before you let an agent write in the
vault, or before you turn on the strict `ci` gate.

`--root` can go before or after the subcommand (`whykit new --root ../my-ledger
decision ...` and `whykit new decision ... --root ../my-ledger` both work).
Inside the vault directory you can drop `--root` altogether.

Next: write the real context and rationale into `06-decisions/d-001-*.md`,
preview and approve the completed record, `git init` the vault, and commit it.
Choose a complete workflow:

- [Import an ADR, review changed evidence and export public data](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/tutorials/review-and-export.md): keep source provenance, find the affected decision and retain its review warning in a filtered export.
- [Record, check and supersede a decision](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/tutorials/record-and-supersede.md): replace an accepted choice without rewriting its reasoning.
- [Gate pull requests in GitHub Actions](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/tutorials/gate-pull-requests.md): check changes against a trusted Git baseline.

## Why WhyKit

Teams can find old documents but rarely tell which evidence supported a
decision, what replaced an earlier choice, or when anyone last checked that the
reasoning still holds. WhyKit makes those links explicit and checks them:

```text
source (E-001) → decision (D-001) → dated review events
```

Use that record to answer three questions: which decision applies, which
sources support it, and what needs review when an input changes. Public exports
keep permitted records and their known warnings while filtering non-public data.

- **Evidence stays traceable.** Each source gets a stable ID and a location a
  person can inspect.
- **Accepted reasoning stays intact.** You supersede a decision instead of
  rewriting it, and CI rejects a diff that edits accepted reasoning.
- **Reviews have dates.** Every approved decision carries a `review_by` date,
  and overdue ones fail the strict gate.
- **The same rules run everywhere.** One `whykit.toml` drives local runs, CI,
  the pre-commit hook and agents, with a versioned JSON contract and a
  read-only MCP server for tools.

WhyKit checks structure and traceability, **not whether a source or conclusion
is true**. It is not an AI memory service, a vector database or an
access-control boundary; [Positioning](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/project-positioning.md) says when
plain ADRs are the better choice.

## Documentation

Start at the [documentation index](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/README.md). The most used pages:

- [Concepts](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/concepts.md): evidence, decisions, supersession and the review cycle.
- [How-to guides](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/guide.md): adopt existing Markdown, manage evidence, hand context to agents.
- [CI integration](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/ci.md) and [troubleshooting](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/troubleshooting.md).
- [Command reference](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/cli.md), [configuration](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/configuration.md) and [lint rules](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/rules.md).
- [Automation (JSON contract)](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/automation.md) and the [MCP server](https://github.com/CometWeb-io/whykit/blob/v0.3.2/docs/mcp.md).

The example vaults show the format at two scales: [tiny](https://github.com/CometWeb-io/whykit/blob/v0.3.2/examples/tiny/) and
the fully linked, fictional [Northline](https://github.com/CometWeb-io/whykit/blob/v0.3.2/examples/northline/).

[Contributing](https://github.com/CometWeb-io/whykit/blob/v0.3.2/CONTRIBUTING.md) · [Code of Conduct](https://github.com/CometWeb-io/whykit/blob/v0.3.2/CODE_OF_CONDUCT.md) ·
[Security policy](https://github.com/CometWeb-io/whykit/blob/v0.3.2/SECURITY.md) · [Release checklist](https://github.com/CometWeb-io/whykit/blob/v0.3.2/.github/RELEASE.md)

Copyright 2026 Maciej Zmitrukiewicz (hello@cometweb.io), licensed under
[Apache-2.0](https://github.com/CometWeb-io/whykit/blob/v0.3.2/LICENSE). [CometWeb](https://cometweb.io) is the product name, not
the copyright holder.
