tix-cli 0.1.0__tar.gz → 0.2.0__tar.gz

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/agent-state

@@ -0,0 +1 @@
+IDLE

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/ctx-cache

@@ -0,0 +1 @@
+1779238741:70407:27083

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/parent-cwd

@@ -0,0 +1 @@
+/Users/henrypye/Documents/code/tix

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/sessions/55972

@@ -0,0 +1 @@
+ACTIVE:Bash

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "enabledPlugins": {
+    "vercel@claude-plugins-official": false,
+    "claude-md-management@claude-plugins-official": false,
+    "skill-creator@claude-plugins-official": false
+  }
+}

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.claude/tmux-window

@@ -0,0 +1 @@
+02b-doc-driven-booking-audit

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.env.local.port

@@ -0,0 +1 @@
+PORT=3101

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/.git

@@ -0,0 +1 @@
+gitdir: /Users/henrypye/Documents/code/tix/.git/worktrees/02b-doc-driven-booking-audit

{tix_cli-0.1.0 → tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit}/CLAUDE.md

@@ -5,7 +5,7 @@
 `tix` is a keyboard-driven curses TUI over a tree of markdown ticket briefs. Stdlib-only Python. Single surface:
 
 - `src/tix/tui.py` — curses reader. Renders, filters, navigates, pickups.
-- `src/tix/__main__.py` — CLI router (default → TUI; `tix <project>` → cd-and-set-TICKETS_DIR).
+- `src/tix/__main__.py` — CLI router (default → TUI; `tix <project>` → resolve `~/.claude/tickets/<project>/`, fallback `./<project>/.claude/tickets/`; sets `TICKETS_DIR` before the TUI imports).
 
 **tix is a pure reader.** It does not write `status:` frontmatter. Users who want status auto-derived wire up their own script via `TIX_PRELOAD_HOOK`. That contract is load-bearing — do not bundle a reconciler.
 
@@ -27,7 +27,14 @@ Pre-migration title-case variants (`In Progress`, `Todo`, etc.) are kept as read
 
 ## TICKETS_DIR resolution
 
-Order: `$TICKETS_DIR` (explicit) → `~/.claude/tickets` (fallback). No project-local autodiscovery. The `tix <project>` form is sugar that does `chdir` + sets `TICKETS_DIR` to `<project>/.claude/tickets` before the TUI imports.
+Order: `$TICKETS_DIR` (explicit) → `~/.claude/tickets` (fallback). No in-binary project autodiscovery from cwd.
+
+The `tix <project>` form sets `TICKETS_DIR` via:
+1. `~/.claude/tickets/<project>/` if that dir exists (centralized layout — preferred)
+2. else `./<project>/.claude/tickets/` if that dir exists (legacy per-repo layout — `chdir` into `./<project>` before launch)
+3. else error
+
+Per-project autoswitch on `cd` lives in the user's shell, not tix. The README documents a zsh `chpwd` hook recipe for the centralized layout.
 
 ## Preload hook
 

{tix_cli-0.1.0 → tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit}/README.md

@@ -1,5 +1,9 @@
 # tix
 
+[![PyPI](https://img.shields.io/pypi/v/tix-cli.svg)](https://pypi.org/project/tix-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tix-cli.svg)](https://pypi.org/project/tix-cli/)
+[![License](https://img.shields.io/pypi/l/tix-cli.svg)](https://github.com/gitpancake/tix/blob/main/LICENSE)
+
 Keyboard-driven terminal ticket explorer for a tree of markdown briefs. Linear-like TUI, zero deps beyond the Python stdlib + an optional markdown pager.
 
 ```
@@ -46,11 +50,29 @@ tix
 Or point at a project tree:
 
 ```bash
-cd ~/code
-tix my-project           # browses ~/code/my-project/.claude/tickets
+tix my-project           # browses ~/.claude/tickets/my-project (centralized)
+                         # falls back to ./my-project/.claude/tickets (legacy)
 TICKETS_DIR=./docs/tickets tix
 ```
 
+For zsh users who want per-project `TICKETS_DIR` to follow `cd`, add this `chpwd` hook to `~/.zshrc`:
+
+```zsh
+autoload -U add-zsh-hook
+_tix_tickets_dir() {
+  local root base
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || { unset TICKETS_DIR; return; }
+  base=${root:t}
+  if [[ -d "$HOME/.claude/tickets/$base" ]]; then
+    export TICKETS_DIR="$HOME/.claude/tickets/$base"
+  else
+    unset TICKETS_DIR
+  fi
+}
+add-zsh-hook chpwd _tix_tickets_dir
+_tix_tickets_dir
+```
+
 ## Keys
 
 | Key | Action |
@@ -111,7 +133,7 @@ Full contract: [`docs/ticket-schema.md`](docs/ticket-schema.md).
 | `EDITOR` | `vi` | Used by `e` |
 | `PAGER` | `less` | Fallback when `glow` is absent |
 
-`TICKETS_DIR` resolves in this order: explicit env var → `~/.claude/tickets`. There is no project-local autodiscovery; pass `tix <project>` or set `TICKETS_DIR` explicitly.
+`TICKETS_DIR` resolves in this order: explicit env var → `~/.claude/tickets`. There is no in-binary project-local autodiscovery; pass `tix <project>` (resolves `~/.claude/tickets/<project>/` first, then `./<project>/.claude/tickets/` for legacy trees) or set `TICKETS_DIR` explicitly (e.g. via the `chpwd` hook above).
 
 ## Preload hook
 

tix_cli-0.2.0/.claude/worktrees/02b-doc-driven-booking-audit/src/tix/__main__.py

@@ -0,0 +1,38 @@
+"""tix CLI entry point.
+
+  tix                browse $TICKETS_DIR (default ~/.claude/tickets)
+  tix <project>      browse ~/.claude/tickets/<project>/ (centralized layout).
+                     Legacy fallback: ./<project>/.claude/tickets/
+"""
+import os
+import sys
+from pathlib import Path
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if argv and not argv[0].startswith("-"):
+        proj = argv.pop(0)
+        home_proj = Path.home() / ".claude" / "tickets" / proj
+        if home_proj.is_dir():
+            os.environ["TICKETS_DIR"] = str(home_proj)
+        else:
+            legacy = Path.cwd() / proj / ".claude" / "tickets"
+            if legacy.is_dir():
+                os.chdir(Path.cwd() / proj)
+                os.environ["TICKETS_DIR"] = str(legacy)
+            else:
+                print(
+                    f"tix: no ticket directory at {home_proj} (or {legacy})",
+                    file=sys.stderr,
+                )
+                return 1
+
+    from . import tui
+    sys.argv = ["tix", *argv]
+    return tui.main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/agent-state

@@ -0,0 +1 @@
+IDLE

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/ctx-cache

@@ -0,0 +1 @@
+1779238819:51627:26403

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/parent-cwd

@@ -0,0 +1 @@
+/Users/henrypye/Documents/code/tix

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/sessions/45189

@@ -0,0 +1 @@
+WAITING:input

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "enabledPlugins": {
+    "vercel@claude-plugins-official": false,
+    "claude-md-management@claude-plugins-official": false,
+    "skill-creator@claude-plugins-official": false
+  }
+}

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.claude/tmux-window

@@ -0,0 +1 @@
+03-easypost-client-mv

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.env.local.port

@@ -0,0 +1 @@
+PORT=3100

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.git

@@ -0,0 +1 @@
+gitdir: /Users/henrypye/Documents/code/tix/.git/worktrees/03-easypost-client-mv

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e . pytest ruff
+      - run: ruff check src tests
+      - run: pytest -q

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-18
+
+Initial public release.
+
+### Added
+- Curses TUI over a tree of markdown ticket briefs.
+- Keyboard-driven navigation, filter (`/`), edit (`e`), pickup → `wt` (`p`).
+- Sticky status pins: `i` (active), `d` (done), `x` (cancelled).
+- Move ticket between areas (`m`), copy slug (`y`), open Linear URL (`o`).
+- Split-pane preview with `glow` / `$PAGER` fallback.
+- `tix <project>` form: `chdir` into `./<project>` and set
+  `TICKETS_DIR=<project>/.claude/tickets`.
+- `TIX_PRELOAD_HOOK` env var — runs a user-supplied shell command before the
+  TUI launches so external tooling can derive `status:`. tix itself is a pure
+  reader.
+- Bundled `_TEMPLATE.md`, `_EPIC-TEMPLATE.md`, `_CHILD-TEMPLATE.md` accessible
+  via `importlib.resources` at `tix/templates/`.
+
+### Schema
+- Filename is the slug.
+- Epic = folder containing `_epic.md`.
+- Status vocab pinned: `active`, `open`, `draft`, `done`, `cancelled`.
+- Frontmatter parser is line-based (no PyYAML).
+
+[0.1.0]: https://github.com/gitpancake/tix/releases/tag/v0.1.0

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+## Project
+
+`tix` is a keyboard-driven curses TUI over a tree of markdown ticket briefs. Stdlib-only Python. Single surface:
+
+- `src/tix/tui.py` — curses reader. Renders, filters, navigates, pickups.
+- `src/tix/__main__.py` — CLI router (default → TUI; `tix <project>` → resolve `~/.claude/tickets/<project>/`, fallback `./<project>/.claude/tickets/`; sets `TICKETS_DIR` before the TUI imports).
+
+**tix is a pure reader.** It does not write `status:` frontmatter. Users who want status auto-derived wire up their own script via `TIX_PRELOAD_HOOK`. That contract is load-bearing — do not bundle a reconciler.
+
+## Invariants
+
+1. **No status writes from tix.** `i`/`d`/`x` sticky pins are the only mutation path, and even those just edit the ticket file's frontmatter directly — they never derive state from external signals.
+2. **Stdlib-only.** No PyYAML, no `rich`, no `prompt_toolkit`. Adds startup latency we don't accept. Frontmatter parser is intentionally line-based; preserve that contract.
+3. **Filename = slug.** Never derive a slug from frontmatter `id:` or filename munging. `path.stem` is authoritative.
+4. **Filesystem = DB.** No `.tix-cache`, no SQLite. `ACTIVE_LANES_FILE` is an *optional read-only* sidecar — tix consumes it if present (a preload hook might populate it) but never writes it itself.
+
+## Status vocab (pinned)
+
+`active`, `open`, `draft`, `done`, `cancelled`. Adding one requires changes in two places:
+
+- `tui.py` → `STATUS_META`, `FILTER_ORDER`
+- `docs/ticket-schema.md` → contract update
+
+Pre-migration title-case variants (`In Progress`, `Todo`, etc.) are kept as read-only aliases — don't extend that set.
+
+## TICKETS_DIR resolution
+
+Order: `$TICKETS_DIR` (explicit) → `~/.claude/tickets` (fallback). No in-binary project autodiscovery from cwd.
+
+The `tix <project>` form sets `TICKETS_DIR` via:
+1. `~/.claude/tickets/<project>/` if that dir exists (centralized layout — preferred)
+2. else `./<project>/.claude/tickets/` if that dir exists (legacy per-repo layout — `chdir` into `./<project>` before launch)
+3. else error
+
+Per-project autoswitch on `cd` lives in the user's shell, not tix. The README documents a zsh `chpwd` hook recipe for the centralized layout.
+
+## Preload hook
+
+`run_preload_hook()` reads `TIX_PRELOAD_HOOK` and runs it as a shell command before curses takes over. Output is captured. Failures are swallowed. This is the only extension point tix exposes — keep it minimal. Do not add an "after" hook or per-action hooks; users with that level of need should fork.
+
+## Editing rules
+
+- `tui.py` runs inside `curses.wrapper`. Anything that prints or raises can wreck the terminal. Wrap subprocess calls in `try/except (OSError, subprocess.SubprocessError)`.
+- Status bar rendering is hot. Don't read filesystem inside the render loop — `App.rebuild_rows()` is the bulk-read step.
+- `subprocess.run` w/ `wt`/`git` returns are mostly best-effort. Keep them that way — surfacing transient failures into the TUI is worse than hiding them.
+
+## Tests
+
+Fixture-driven under `tests/fixtures/tickets/`. No network. Run:
+
+```bash
+pytest -q
+```
+
+## Distribution
+
+- PyPI distribution name: `tix-cli`. Import name + executable: `tix`.
+- One console script: `tix`.
+- No native deps. `pipx install tix-cli` is the recommended install.
+- Templates ship in `src/tix/templates/` and are accessed via `importlib.resources` (or `tix.__file__`-relative paths) — never hardcode an install prefix.
+
+## Org-specific bits to keep configurable
+
+- `AREAS` in `tui.py` is currently a fixed list. **Don't hardcode org-specific area names** when extending — make it configurable via env or a config file before any new area lands.
+- `LINEAR_WORKSPACE` is the only external-tracker breadcrumb. No GitHub Issues / Jira integration creep — that belongs in a preload hook.
+
+## Non-goals
+
+- No remote sync.
+- No mouse support.
+- No realtime collab.
+- No bundled markdown renderer — defer to `glow` / `$PAGER`.
+- No bundled status reconciler — defer to `TIX_PRELOAD_HOOK`.

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Pye
+
+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.

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/README.md

@@ -0,0 +1,168 @@
+# tix
+
+[![PyPI](https://img.shields.io/pypi/v/tix-cli.svg)](https://pypi.org/project/tix-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tix-cli.svg)](https://pypi.org/project/tix-cli/)
+[![License](https://img.shields.io/pypi/l/tix-cli.svg)](https://github.com/gitpancake/tix/blob/main/LICENSE)
+
+Keyboard-driven terminal ticket explorer for a tree of markdown briefs. Linear-like TUI, zero deps beyond the Python stdlib + an optional markdown pager.
+
+```
+LANES                         STATE              CTX
+◐ P1 teams-error-mapping      active              74K
+○ P0 oauth-rotation-plan      open                —
+●    audit-logs-rollout       done                —
+```
+
+## Why
+
+- **The filesystem is the database.** A ticket *is* a markdown file. `grep`, `git log`, and `ls` all keep working.
+- **No SaaS, no auth, no network.** Runs entirely against a local tree.
+- **Linear-like keys.** `j/k`, `/` to filter, `Enter` to open, `p` to pick up into a `wt` lane.
+- **Pure reader.** tix never writes `status:` for you. If you want auto-status derivation, wire up your own preload hook (see below).
+
+## Install
+
+```bash
+pipx install tix-cli
+# or, in a venv:
+pip install tix-cli
+```
+
+Installs one console script: `tix`.
+
+### From source
+
+```bash
+git clone https://github.com/gitpancake/tix
+cd tix
+pipx install --editable .
+```
+
+## Quickstart
+
+```bash
+mkdir -p ~/.claude/tickets/spikes
+cp $(python -c 'import tix, pathlib; print(pathlib.Path(tix.__file__).parent / "templates" / "_TEMPLATE.md")') \
+   ~/.claude/tickets/spikes/my-first-ticket.md
+tix
+```
+
+Or point at a project tree:
+
+```bash
+tix my-project           # browses ~/.claude/tickets/my-project (centralized)
+                         # falls back to ./my-project/.claude/tickets (legacy)
+TICKETS_DIR=./docs/tickets tix
+```
+
+For zsh users who want per-project `TICKETS_DIR` to follow `cd`, add this `chpwd` hook to `~/.zshrc`:
+
+```zsh
+autoload -U add-zsh-hook
+_tix_tickets_dir() {
+  local root base
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || { unset TICKETS_DIR; return; }
+  base=${root:t}
+  if [[ -d "$HOME/.claude/tickets/$base" ]]; then
+    export TICKETS_DIR="$HOME/.claude/tickets/$base"
+  else
+    unset TICKETS_DIR
+  fi
+}
+add-zsh-hook chpwd _tix_tickets_dir
+_tix_tickets_dir
+```
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `↑` `↓` / `j` `k` | Move |
+| `Ctrl-U` `Ctrl-D` | Half page |
+| `g` `G` | Top / bottom |
+| `Enter` `→` `l` | Open in `glow` (or `$PAGER`) |
+| `Esc` `←` `h` | Collapse / back |
+| `/` | Filter |
+| `e` | Edit in `$EDITOR` |
+| `p` | Pickup → `wt <slug>` |
+| `i` | Pin status `active` |
+| `d` | Pin status `done` |
+| `x` | Pin status `cancelled` |
+| `m` | Move ticket to area |
+| `y` | Copy slug to clipboard |
+| `o` | Open Linear URL (if `linear:` set) |
+| `r` | Reload (re-runs preload hook if set) |
+| `?` | Help |
+| `q` | Quit |
+
+## Schema
+
+A ticket is a markdown file with YAML-ish line-based frontmatter:
+
+```markdown
+---
+status: open
+priority: P1
+area: integrations
+linear: PROJ-123
+---
+
+# teams-error-mapping
+
+## Context
+…
+
+## Acceptance criteria
+- [ ] …
+```
+
+Full contract: [`docs/ticket-schema.md`](docs/ticket-schema.md).
+
+- **Filename is the slug.** `teams-error-mapping.md`, never `PROJ-123.md`.
+- **Epic = folder.** A directory containing `_epic.md` is an epic; numbered children (`01-foo.md`, `02-bar.md`) are its stories.
+- **Status vocab is pinned:** `active`, `open`, `draft`, `done`, `cancelled`.
+
+## Configuration
+
+| Env | Default | Purpose |
+|---|---|---|
+| `TICKETS_DIR` | `~/.claude/tickets` | Root of the ticket tree |
+| `ACTIVE_LANES_FILE` | `~/.claude/active-lanes.json` | Optional sidecar map: slug → `{path, branch, repo, last_commit}`. Read by the TUI; tix never writes it. |
+| `LINEAR_WORKSPACE` | *(unset)* | Slug used to derive `linear:` URLs (`o` key) |
+| `TIX_PRELOAD_HOOK` | *(unset)* | Shell command run before launch. See below. |
+| `EDITOR` | `vi` | Used by `e` |
+| `PAGER` | `less` | Fallback when `glow` is absent |
+
+`TICKETS_DIR` resolves in this order: explicit env var → `~/.claude/tickets`. There is no in-binary project-local autodiscovery; pass `tix <project>` (resolves `~/.claude/tickets/<project>/` first, then `./<project>/.claude/tickets/` for legacy trees) or set `TICKETS_DIR` explicitly (e.g. via the `chpwd` hook above).
+
+## Preload hook
+
+tix doesn't write `status:` — that's deliberate. If you want statuses derived from external signals (live worktrees, feature branches, merged PRs, calendar events, anything), put a script on disk and point at it:
+
+```bash
+export TIX_PRELOAD_HOOK=~/bin/my-status-sync
+tix
+```
+
+The hook runs once before the TUI is drawn. Its stdout/stderr are discarded — curses is about to claim the screen, so the *next render* is the feedback, not the printed diff. The hook is best-effort: a missing or failing command never blocks launch.
+
+The `r` key in the TUI re-runs the hook and reloads.
+
+A reference implementation (filesystem + git + `gh`) lives in [gitpancake/.dotfiles](https://github.com/gitpancake/.dotfiles) as `claude/scripts/ticket-status-sync.py` — it derives `active` from live worktrees and `done` from merged PRs. Copy it, fork it, replace it.
+
+## Optional integrations
+
+- **`wt`** — if a `wt` command is on PATH, the `p` key suspends curses, runs `git fetch && git checkout main && git merge --ff-only && wt <slug>`, then resumes.
+- **`glow`** — preferred markdown pager for ticket preview. Falls back to `$PAGER` (default `less`).
+- **`gh`** — used by some preload hooks (not by tix itself).
+
+## Non-goals
+
+- No remote sync, no auth, no web UI.
+- No mouse support.
+- No notifications.
+- No bundled status reconciler — wire your own via `TIX_PRELOAD_HOOK`.
+
+## License
+
+MIT.

tix_cli-0.2.0/.claude/worktrees/03-easypost-client-mv/docs/ticket-schema.md

@@ -0,0 +1,124 @@
+# Ticket schema
+
+The contract between tix and your ticket tree. Read this before hand-editing
+anything under `$TICKETS_DIR` (default `~/.claude/tickets`).
+
+## The one rule
+
+**Filename is the slug.** A ticket file's stem *is* its identifier — never an
+external tracker ID, never an arbitrary number.
+
+```
+good:  oauth-rotation-plan.md
+bad:   PROJ-123.md
+bad:   DRAFT-7.md
+```
+
+`tix` and `ls` stay legible without opening any file. External IDs go in the
+optional `linear:` frontmatter field as a historical breadcrumb; nothing ever
+syncs.
+
+## Two kinds of thing
+
+| Kind | Lives at | Is |
+|---|---|---|
+| **Single ticket** | `<area>/<slug>.md` | One unit of change with acceptance criteria. |
+| **Epic** | `<area>/<epic-slug>/` | A folder: `_epic.md` plus ordered `NN-<child>.md` children. |
+
+A ticket lives in its area from creation — there is no staging folder. "Draft"
+is a *status*, not a location: a freshly-scoped ticket is `status: draft` until
+it's refined or picked up.
+
+**Epic-ness is structural.** A directory containing `_epic.md` *is* an epic.
+There is no separate registry — `find $TICKETS_DIR -name _epic.md` is the
+epic index, and it is never stale.
+
+## Areas
+
+The root is a small, fixed set of area buckets. This is what keeps the tree
+browsable instead of sprawling into one folder per epic.
+
+The default areas baked into `tix` are:
+
+- `integrations/`
+- `ops/`
+- `platform/`
+- `spikes/`
+- `tooling/`
+
+These names are intentionally generic. Pick whatever set suits your project — a
+future release will make `AREAS` configurable via env or a config file. For now
+edit `src/tix/tui.py`'s `AREAS` list if you fork.
+
+Add buckets deliberately. If you reach for a sixth, ask whether it's really an
+area or just an epic that belongs inside an existing one.
+
+## Frontmatter
+
+```yaml
+---
+status: open               # active | open | draft | done | cancelled
+priority: P1               # P0 | P1 | P2 | P3 (blank = unprioritized)
+area: integrations         # one of the configured areas
+linear: PROJ-123           # optional external-tracker breadcrumb
+parent: <epic-slug>        # only on epic children
+---
+```
+
+The parser is intentionally line-based — no PyYAML, no nesting. Keep each value
+on a single line.
+
+### Status vocab
+
+- `draft` — scoped, not yet refined. The cheapest possible "I might want this."
+- `open` — refined and ready to be picked up. Default for new well-formed tickets.
+- `active` — being worked. A reconciler can derive this from live worktrees or
+  branches; you can also pin it manually with `tix`'s `i` key.
+- `done` — shipped. A reconciler can derive it from merged PRs containing the
+  slug; you can also pin it with `d`. Sticky: a manual mark survives the next
+  reconciliation pass so research/ops tickets without a PR signal can still
+  close out.
+- `cancelled` — dropped. **Terminal** — trumps every derived signal until you
+  reopen it. Set/cleared with `x`.
+
+`tix` itself is a **pure reader** — it never writes `status:` for you. If you
+want statuses derived from external signals, wire your own reconciler via the
+`TIX_PRELOAD_HOOK` env var; it runs once before each TUI launch. A reference
+implementation (filesystem + git + `gh`) lives in
+[gitpancake/.dotfiles](https://github.com/gitpancake/.dotfiles) as
+`claude/scripts/ticket-status-sync.py` — derives `active` from worktrees and
+`done` from merged PRs. Fork, replace, or skip entirely.
+
+### Priority
+
+Hand-driven, unlike status. Buckets are `P0` (drop everything) → `P3`
+(eventually); blank sorts last. Within each group `tix` sorts by priority then
+status, so P0/P1 work bubbles to the top. Edit the frontmatter directly or use
+`+`/`−` from the TUI.
+
+## Epic shape
+
+```
+<area>/<epic-slug>/
+  _epic.md                # the durable, expansive brief
+  01-<child-slug>.md      # ordered child stories
+  02-<child-slug>.md
+```
+
+- **`_epic.md`** carries context, goal, epic-level acceptance criteria,
+  constraints, and an ordered story list.
+- **`NN-<child>.md` children** are the deep per-story detail. The `NN-` prefix
+  encodes execution order so `ls` and `tix` show the sequence.
+
+## Slug conventions
+
+Use a descriptive, kebab-cased phrase. Short enough to type, long enough to
+read at a glance. Avoid encoding state in the name — that's what `status:` is
+for.
+
+```
+good:  oauth-rotation-plan
+good:  webhook-replay-on-failure
+bad:   fix-the-thing
+bad:   work-in-progress-stuff
+```