tix-cli 0.1.0__tar.gz

tix_cli-0.1.0/.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.1.0/.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.1.0/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.1.0/CLAUDE.md

@@ -0,0 +1,68 @@
+# 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>` → cd-and-set-TICKETS_DIR).
+
+**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 project-local autodiscovery. The `tix <project>` form is sugar that does `chdir` + sets `TICKETS_DIR` to `<project>/.claude/tickets` before the TUI imports.
+
+## 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.1.0/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.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: tix-cli
+Version: 0.1.0
+Summary: Keyboard-driven terminal ticket explorer for a tree of markdown briefs.
+Project-URL: Homepage, https://github.com/gitpancake/tix
+Project-URL: Repository, https://github.com/gitpancake/tix
+Project-URL: Issues, https://github.com/gitpancake/tix/issues
+Project-URL: Changelog, https://github.com/gitpancake/tix/blob/main/CHANGELOG.md
+Author: Henry Pye
+License: 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.
+License-File: LICENSE
+Keywords: curses,issue-tracker,markdown,tickets,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# tix
+
+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
+cd ~/code
+tix my-project           # browses ~/code/my-project/.claude/tickets
+TICKETS_DIR=./docs/tickets tix
+```
+
+## 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 project-local autodiscovery; pass `tix <project>` or set `TICKETS_DIR` explicitly.
+
+## 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.1.0/README.md

@@ -0,0 +1,146 @@
+# tix
+
+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
+cd ~/code
+tix my-project           # browses ~/code/my-project/.claude/tickets
+TICKETS_DIR=./docs/tickets tix
+```
+
+## 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 project-local autodiscovery; pass `tix <project>` or set `TICKETS_DIR` explicitly.
+
+## 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.1.0/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
+```

tix_cli-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tix-cli"
+version = "0.1.0"
+description = "Keyboard-driven terminal ticket explorer for a tree of markdown briefs."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "Henry Pye" }]
+keywords = ["tui", "tickets", "curses", "markdown", "issue-tracker"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console :: Curses",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development",
+  "Topic :: Terminals",
+]
+dependencies = []
+
+[project.scripts]
+tix = "tix.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/gitpancake/tix"
+Repository = "https://github.com/gitpancake/tix"
+Issues = "https://github.com/gitpancake/tix/issues"
+Changelog = "https://github.com/gitpancake/tix/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tix"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tix_cli-0.1.0/src/tix/__init__.py

@@ -0,0 +1,3 @@
+"""tix — keyboard-driven terminal ticket explorer for a tree of markdown briefs."""
+
+__version__ = "0.1.0"