chitty 0.1.0__tar.gz

chitty-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Publish release to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+
+      - name: Install Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Verify tag matches package version
+        shell: bash
+        run: test "v$(uv version --short)" = "${GITHUB_REF_NAME}"
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Check project
+        run: make check
+
+      - name: Build distributions
+        run: make build
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish verified distributions
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+          ignore-empty-workdir: true
+
+      - name: Download verified distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Generate PEP 740 attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+
+      - name: Publish to PyPI
+        run: uv publish

chitty-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.envrc
+__pycache__/
+node_modules/
+/dist/

chitty-0.1.0/AGENTS.md

@@ -0,0 +1,32 @@
+# Agents
+
+Chitty is a markdown-native task tracker. `PLAN.md` is the design; read it
+before changing behaviour, and update it when a decision changes.
+
+- `make install` once (Python deps including the `mcp` extra, and the pinned
+  prettier used by the round-trip tests).
+- `make check` (ruff, pyright, unittest) before every commit. `make format`
+  to fix formatting.
+- Tests use `unittest` and write real files in temp dirs; no filesystem
+  mocking. The formatter tests fail, never skip, if prettier or mdformat is
+  missing.
+- `cli.py` and `mcp.py` stay thin: behaviour lives in `store.py` and
+  `model.py` so the two front ends cannot diverge.
+- Releases: bump `version` in `pyproject.toml`, commit, then push a tag
+  `v<version>`. `.github/workflows/release.yml` checks, builds and publishes
+  to PyPI by trusted publishing (environment `pypi`).
+
+## Chitty
+
+Tasks live in `chitty/`. Use the `chitty` CLI (or MCP tools); do not hand-edit
+task files. `chitty --help` is the full command reference.
+
+- Work on one task per session. Start with `chitty show <ID>`.
+- Before writing code, write your approach with `chitty edit <ID> --plan` and
+  set `-s doing`. Wait for approval if the human asked for it.
+- Tick acceptance criteria as you meet them: `chitty edit <ID> --check N`
+  (numbers are shown by `chitty show`).
+- Record anything surprising with `--note`. Set `-s done` when every
+  criterion is ticked and the work is verified.
+- Found unrelated work? `chitty add` it (`-c human` if it needs a person).
+  Don't do it in this session.

chitty-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

chitty-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed Singleton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chitty-0.1.0/Makefile

@@ -0,0 +1,22 @@
+.PHONY: install check test format build
+
+install: ## install Python and node dev dependencies
+	uv sync --all-extras
+	npm ci
+
+check: ## lint, type-check and run the tests
+	uv run ruff format --check .
+	uv run ruff check --no-fix .
+	uv run pyright
+	uv run python -m unittest discover -s tests -t .
+
+test: ## run the tests
+	uv run python -m unittest discover -s tests -t .
+
+format: ## format and auto-fix Python code
+	uv run ruff check --exit-zero .
+	uv run ruff format .
+
+build: ## build the sdist and wheel into dist/
+	rm -rf dist
+	uv build

chitty-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: chitty
+Version: 0.1.0
+Summary: Markdown-native task tracker for repos worked on by humans and coding agents
+Project-URL: Homepage, https://github.com/Singletoned/chitty
+Project-URL: Issues, https://github.com/Singletoned/chitty/issues
+Author-email: Ed Singleton <ed@singletoned.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,markdown,mcp,task-tracker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.12
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Chitty
+
+Markdown-native task tracker for repos worked on by humans and coding agents.
+Put in a chitty; an agent (or you) picks it up; the file is the record.
+
+Each task is one markdown file with YAML frontmatter under
+`chitty/<context>/`, e.g. `chitty/tasks/TASK-12--add-search.md`. The files are
+the only state: no database, no index. The tool only ever changes the lines
+it means to, so prettier and mdformat leave its output alone and diffs stay
+small. See `PLAN.md` for the full design.
+
+## Install
+
+Not yet on PyPI. From a checkout:
+
+```sh
+uv tool install .                 # CLI
+uv tool install '.[mcp]'          # CLI plus `chitty mcp`
+```
+
+## Use
+
+```sh
+chitty init                       # chitty.toml, chitty/tasks/, AGENTS.md block
+chitty add "Add search" -d "Search titles and bodies." \
+    --ac "Matches title" --ac "Case-insensitive" -l cli
+chitty list
+chitty show 1                     # bare numbers mean the default context
+chitty edit 1 -s doing --plan "Use casefold()." --check 1
+chitty edit 1 --note "Safari needs a polyfill."
+chitty add "Rotate prod password" -c human -d "Needs a person."
+chitty move 1 human               # new ID there; references are rewritten
+chitty archive HUMAN-1
+chitty check                      # validate everything; non-zero on problems
+```
+
+Every command takes `--json`. `chitty --help` and `chitty <command> --help`
+are the reference.
+
+Contexts are configured in `chitty.toml`. Contexts in other repos (for
+posting tasks elsewhere) go in `~/.config/chitty/contexts.toml`:
+
+```toml
+[contexts.notes]
+repo = "~/notes"
+```
+
+## Develop
+
+```sh
+make install    # uv sync --all-extras; npm ci (pinned prettier)
+make check      # ruff, pyright, unittest
+make format
+```

chitty-0.1.0/PLAN.md

@@ -0,0 +1,397 @@
+# Chitty — plan
+
+Markdown-native task tracker for repos worked on by humans and coding agents.
+A clean-room reimplementation of the idea behind Backlog.md, in Python, with
+a file format that ordinary markdown tooling leaves alone and a much smaller
+surface area.
+
+Put in a chitty; an agent (or you) picks it up; the file is the record.
+
+## Principles
+
+- The files are the truth. No database, no index, no cache. A directory scan
+  is fast enough for thousands of tasks.
+- One task, one file, one writer at a time. No locking, no cross-branch
+  scanning, no automatic conflict repair. If you want a task from another
+  branch, merge the branch. IDs are sequential; task creation is expected to
+  be centralised (one agent or human), so we assume parallel branches don't
+  collide. `check` reports it if they do.
+- Simple first. Add complexity when real-world use shows it is needed, not
+  before.
+- Plain markdown. Every file must survive a round trip through the supported
+  formatters (below) without changing meaning. No HTML comments, no sentinel
+  markers, no numbering inside checklist text.
+- Loud errors. Malformed files are rejected with a path and a reason, never
+  silently repaired. `chitty check` is the compile step.
+- The tool carries the rules, not a prompt. Validation and `--help` are the
+  documentation; the agent instructions are ~20 lines and static.
+- Minimal diffs. The tool never touches a line it didn't change, and never
+  writes a file whose content would be unchanged.
+- No migrations in v1. The format is versioned (`format = 1` in config) so
+  one can be written later if ever needed.
+
+## Non-goals
+
+TUI. Web UI. Cross-branch task resolution. File locking. Format migrations.
+Remote/HTTP contexts (sync a directory instead). Subtask IDs (`24.1`).
+Milestones. Docs/decisions directories. Wizards. Shell completions (v1).
+Configurable statuses (v1). Moving tasks between repos. ID collision
+handling beyond reporting it.
+
+## Layout
+
+```
+repo/
+  chitty.toml
+  chitty/
+    tasks/                 default context
+      TASK-2--add-search.md
+      TASK-3--fix-login.md
+      archive/
+        TASK-1--bootstrap.md
+    human/                 another context
+      HUMAN-1--rotate-prod-password.md
+```
+
+`chitty/` is the backlog root; each context is a subdirectory. Archived
+tasks move to `<context>/archive/`. Nothing else lives under `chitty/`.
+
+A missing context directory is an empty context; it is created on first
+write. `init` creates `chitty/tasks/` only; `chitty/human/` appears the first
+time something is added to it. (Git doesn't track empty directories, so a
+freshly cloned repo may have none of them.)
+
+Root discovery (CLI and MCP alike): `CHITTY_ROOT` if set, otherwise walk up
+from the current directory to the first directory containing `chitty.toml`.
+Error if neither finds one.
+
+## IDs
+
+`<PREFIX>-<n>`, e.g. `TASK-13`.
+
+- `PREFIX` is the context's prefix: `[A-Z]+`, unique within a repo.
+- `n` is a positive integer, unpadded: `max(n over existing files in the
+  context, including archive) + 1`.
+
+Filename: `<ID>--<slug>.md`, or `<ID>.md` when the slug is empty. The slug
+is derived from the title at creation (lowercase, `[a-z0-9-]`, collapsed
+hyphens, max 60 chars; empty if the title has no ASCII alphanumerics) and is
+**not** updated when the title changes — it is there so `ls` is readable,
+nothing more. Slugs never contain `--`, so the ID is everything before the
+first `--`. The ID is not repeated in frontmatter.
+
+Collisions: task creation is expected to be centralised, so two branches
+creating the same ID is assumed not to happen in practice. If it does,
+`chitty check` reports the files involved; the human renames one and fixes
+references by hand. No tooling beyond that until real use shows it's
+needed. Likewise, moving the highest-numbered task out of a context lets
+its number be reused; accepted.
+
+Referencing: commands accept `TASK-13`, or bare `13` for the default
+context. Stored references (`depends_on`, `moved_from`) are always the full
+`PREFIX-n` form; shorthand is expanded before writing.
+
+## Task file
+
+```markdown
+---
+title: Add search to the task list
+status: todo
+labels:
+  - search
+  - cli
+priority: medium
+owner: ed
+depends_on:
+  - TASK-7
+  - HUMAN-1
+created: 2026-10-23
+---
+
+## Description
+
+Free markdown.
+
+## Acceptance Criteria
+
+- [ ] `chitty list --search` matches title and body
+- [x] Matching is case-insensitive
+
+## Plan
+
+Free markdown, written by the agent before implementing.
+
+## Notes
+
+Free markdown. Append-only by convention; not enforced.
+```
+
+Frontmatter schema (strict: unknown keys are an error):
+
+| key          | type               | required | notes                                        |
+|--------------|--------------------|----------|----------------------------------------------|
+| `title`      | string             | yes      | non-empty, single line                       |
+| `status`     | `todo\|doing\|done` | yes     | fixed in v1                                  |
+| `labels`     | list[string]       | no       | absent ≡ `[]`                                |
+| `priority`   | `low\|medium\|high` | no      | absent means unset                           |
+| `owner`      | string             | no       | free text; `human`, a name, an agent         |
+| `depends_on` | list[ID]           | no       | any context in the same repo                 |
+| `created`    | date               | yes      | ISO 8601 date, set once                      |
+| `moved_from` | ID                 | no       | set by `move`; the ID in the source context  |
+
+There is no `updated` field. Git records when a file changed; the field would
+add a line to every diff and conflict on every merge.
+
+YAML is loaded with every scalar as a string (no implicit typing), so
+`owner: no` is the string `"no"` and `status: on` fails validation as an
+unknown status rather than becoming `True`. Pydantic parses `created` from
+the string. When the tool *writes* a free-text field (`title`, `owner`,
+`labels`) it quotes anything YAML 1.1 or 1.2 would read as a non-string
+(`"no"`, `"2026-10-23"`, `"1e3"`), because other tools reading the file
+won't be as careful. `created` is a real date and is written unquoted.
+
+Body rules:
+
+- Sections are `##` headings. Recognised: `Description`, `Acceptance
+  Criteria`, `Plan`, `Notes`. Unrecognised `##` headings, any `#` heading,
+  and non-blank content before the first `##` are errors. Use `###` and below
+  inside a section for structure.
+- The parser is fence-aware: `##` inside a fenced code block is not a heading.
+- `Description` is required and non-empty.
+- `Acceptance Criteria` contains only a flat task list. An item starts with
+  `- [ ]`, `- [x]` or `- [X]` at column 0 and may continue on following
+  indented lines (formatters wrap long items). Blank lines between items are
+  allowed. Nested lists, unindented prose, and anything else in the section
+  are errors. Each item is one criterion, addressed by 1-based position in
+  the CLI; no numbers are stored in the text. The tool writes `- [x]`.
+- Everything else is free markdown.
+
+### Supported formatters
+
+The round-trip guarantee is tested against, and only claimed for:
+
+- `prettier` with default settings, and with `proseWrap: always`;
+- `mdformat` with the `mdformat-gfm` and `mdformat-frontmatter` plugins
+  (plain CommonMark mdformat turns `---` into a heading and escapes `[ ]`).
+
+Both are pinned to exact versions. If either is missing, the round-trip
+tests fail loudly; they are never skipped.
+
+"Survives" means the file still parses to the same task. Byte-for-byte
+no-op is only claimed for ordinary content: `mdformat-frontmatter`
+re-serialises YAML as 1.2 and drops the quotes the tool adds for 1.1
+readers (`"no"` becomes `no`), and mdformat renumbers ordered lists in free
+markdown.
+
+### Writing
+
+Serialisation is a patch over the original text, not parse-then-dump:
+
+- Frontmatter is split into one span per top-level key (the key's line plus
+  any indented lines under it). Changed keys have their span replaced, new
+  keys are appended in table order, removed keys have their span deleted.
+  Every other byte — comments, quoting, blank lines — is left alone.
+  Comment and blank lines belong to the key below them, so replacing a key
+  keeps the comment above it.
+- The body is split the same way, one span per `##` section. Only sections
+  the command changed are rewritten; new sections are appended in the
+  canonical order above.
+- Acceptance Criteria are patched per item, so formatter wrapping survives:
+  `--check`/`--uncheck` change only the bracket character, `--rm-ac`
+  deletes that item's lines, `--ac` appends one line.
+- Lists are written block-style (one item per line). Flow style is accepted
+  on read and left alone if the key isn't being changed.
+- If the resulting content equals the current content, the file is not
+  written.
+- `--note TEXT` appends `TEXT` as a new paragraph (preceded by a blank line)
+  to `## Notes`, creating the section if absent. No date prefix; include one
+  in the text if you want it.
+- All checklist indices in a single `edit` refer to the list as it was
+  before the command ran. `show` prints the numbers next to each criterion so
+  callers don't count.
+
+## Config
+
+`chitty.toml` at repo root (required; `chitty init` writes it):
+
+```toml
+format = 1
+default_context = "tasks"
+autocommit = false                     # if true, commit each write
+
+[contexts.tasks]
+prefix = "TASK"
+
+[contexts.human]
+prefix = "HUMAN"
+```
+
+Context directory is `chitty/<name>/`. Not configurable.
+
+User-level `~/.config/chitty/contexts.toml` (optional), for adding tasks to
+other repos or to a personal backlog:
+
+```toml
+[contexts.hypurrcube]
+repo = "~/src/hypurrcube"        # that repo's chitty.toml applies
+context = "tasks"                # optional; default is that repo's default_context
+
+[contexts.improvements]
+repo = "~/notes/improvements"    # any directory with a chitty.toml
+```
+
+Resolution of a context name: repo `chitty.toml` first, then user file.
+A name present in both is an error (no silent shadowing). A name in neither
+is an error naming both paths.
+
+## Dependencies
+
+`depends_on` may reference any context in the same repo (`TASK-3` blocked on
+`HUMAN-1` is the common case). Rules:
+
+- A reference to an ID that doesn't exist in the repo is a `check` error.
+- A reference to an archived task is fine; archived is not deleted.
+- `move` gives the task a new ID in the target context and rewrites every
+  reference to the old ID across the repo, reporting which files it touched.
+- User-level contexts are write targets only; nothing can depend on a task
+  in another repo. If you need to track it, write the foreign ID in your own
+  task's Notes.
+
+## CLI
+
+All commands take `--json` on reads (and on writes, printing the resulting
+task). Exit non-zero with a message on stderr for every error. No prompts,
+no wizards; every command is fully specifiable by flags.
+
+```
+chitty init [--prefix TASK]        write chitty.toml, chitty/tasks/, AGENTS.md block
+chitty add TITLE -d TEXT [-c CTX] [--ac TEXT]... [-l LABEL]... [-p PRIO]
+                 [--owner X] [--depends-on ID]...
+chitty list [-c CTX] [-s STATUS]... [-l LABEL]... [--owner X] [--search TEXT]
+                 [--archived | --all]
+chitty show ID
+chitty edit ID [--title T] [-s STATUS] [--add-label L]... [--rm-label L]... [-p PRIO]
+                 [--owner X] [--depends-on ID]... [--rm-depends-on ID]...
+                 [-d TEXT | --description-file F]
+                 [--ac TEXT]... [--rm-ac N]... [--check N]... [--uncheck N]...
+                 [--plan TEXT | --plan-file F] [--note TEXT]
+chitty move ID CTX                 CTX must be in this repo; new ID, sets moved_from
+chitty archive ID | chitty restore ID
+chitty check [-c CTX] [PATH]...    validate; non-zero on any error
+chitty path ID                     print the file path (for editors/agents)
+chitty mcp                         stdio MCP server (needs the mcp extra)
+```
+
+- `-c/--context` defaults to `default_context`. On `add`, a user-level
+  context name is accepted: the file is written into that repo's working
+  tree as an untracked file and nothing else happens there — no commit,
+  pull or push, and that repo's `autocommit` setting is ignored. Any
+  `--depends-on` is validated against the *target* repo. Post-and-forget.
+  On every other command, `-c` must name a context in this repo.
+- `-d` is required on `add`, because Description is required.
+- `ID` arguments accept `TASK-13`, or bare `13` for the default context.
+- `list` shows non-archived tasks by default; `--archived` shows only
+  archived; `--all` shows both. Default output is one line per task:
+  `TASK-12  doing   Add search to the task list  [cli,search]`.
+- `move` is within the current repo only. It gives the task the next number
+  in the target context and keeps the slug. There is no cross-repo move;
+  `add -c otherrepo` plus `archive` here is the explicit two-step version.
+
+## MCP
+
+`chitty mcp` runs a stdio server. Tools mirror the CLI one-to-one with the
+same names and argument names: `add`, `list`, `show`, `edit`, `move`,
+`archive`, `restore`, `check`, `path`. They return the same JSON
+the CLI prints with `--json`. One resource, `chitty://guide`, returning the
+same text as the AGENTS.md block. Tool descriptions state the rules (one
+task per session, write Plan before coding, tick criteria as you go).
+
+The `mcp` package pulls in starlette, uvicorn, httpx and friends, so it is an
+optional extra: `uv tool install 'chitty[mcp]'`. Agents with a shell can use
+the CLI with `--json` and need none of it. `chitty mcp` without the extra
+exits with an error saying so.
+
+## Agent instructions
+
+`chitty init` appends this block to `AGENTS.md` (creating it if absent),
+idempotently, keyed on the `## Chitty` heading:
+
+```markdown
+## Chitty
+
+Tasks live in `chitty/`. Use the `chitty` CLI (or MCP tools); do not hand-edit
+task files. `chitty --help` is the full command reference.
+
+- Work on one task per session. Start with `chitty show <ID>`.
+- Before writing code, write your approach with `chitty edit <ID> --plan` and
+  set `-s doing`. Wait for approval if the human asked for it.
+- Tick acceptance criteria as you meet them: `chitty edit <ID> --check N`
+  (numbers are shown by `chitty show`).
+- Record anything surprising with `--note`. Set `-s done` when every
+  criterion is ticked and the work is verified.
+- Found unrelated work? `chitty add` it (`-c human` if it needs a person).
+  Don't do it in this session.
+```
+
+That is the whole prompt. Statuses are fixed, so the block is always correct.
+
+## Stack
+
+- Python ≥ 3.12, packaged with `uv`; installed as `uv tool install chitty`,
+  tried with `uvx chitty`.
+- Runtime: `click`, `pydantic`, `pyyaml`. Frontmatter is split on `---` by
+  our own code; YAML is loaded with a loader that resolves every scalar as a
+  string. Optional extra `mcp`.
+- Dev: `ruff`, `pyright` (strict for `src/`, standard for tests; with
+  `types-PyYAML`), `unittest` (stdlib;
+  tests write real files in a temp dir and drive the CLI through
+  `click.testing.CliRunner`; no filesystem mocking), `prettier` and `mdformat`
+  with the plugins above for the round-trip tests.
+- `Makefile` following the mate conventions (`.PHONY` targets with `##`
+  descriptions): `make check` (ruff + pyright + tests), `make format`.
+- Git via `subprocess.run(..., check=True)`. Only used when `autocommit` is
+  on: `git add -- <paths> && git commit --only -m "chitty: <verb> <ID> <title>" -- <paths>`,
+  with all affected paths listed (two for `move`/`archive`/`restore`, more
+  when `move` rewrites references), so nothing the user had staged is swept
+  in. Failure is a loud error.
+
+## Module layout
+
+```
+src/chitty/
+  __init__.py
+  model.py       Task, Frontmatter, Criterion — parse/validate/serialise ONE file
+  ids.py         ID and filename parsing, slugs, next number, shorthand
+  config.py      RepoConfig, UserContexts — load + validate TOML
+  store.py       Context, find/list/read/write/move/archive
+  check.py       cross-file validation: parse errors, duplicate IDs,
+                 dangling or self depends_on
+  errors.py      ChittyError, the base of every user-facing error
+  git.py         optional autocommit
+  cli.py         click commands; thin, calls store/model, prints
+  mcp.py         tool definitions wrapping the same functions as cli.py
+                 (mcp ≥ 2: MCPServer, not FastMCP)
+  guide.md       the AGENTS.md block, as package data
+```
+
+`cli.py` and `mcp.py` contain no logic; both call the same functions in
+`store.py`/`model.py` so behaviour cannot diverge.
+
+## Build order
+
+1. `model.py` + `ids.py` + tests: parse, single-file validation, patch-style
+   serialisation, round-trip. Tests include: prettier (default and
+   `proseWrap: always`) and mdformat (with plugins) are no-ops on tool
+   output; a wrapped criterion is one criterion and ticking it doesn't
+   unwrap it.
+2. `config.py`, `store.py`: contexts, read/write/move/archive,
+   missing-directory-is-empty.
+3. `check.py`: duplicates and dangling references.
+4. `cli.py`: `init`, `add`, `list`, `show`, `edit`, `check`, `path`.
+5. `move`, `archive`/`restore`, user-level contexts.
+6. `autocommit`.
+7. `mcp.py` as the optional extra.
+8. Dogfood: track Chitty's own work in `chitty/` from step 4 onward.
+
+Steps 1–4 are a usable tool. Estimate for the whole list: 3–5k lines
+including tests.