skill-system-tkt

What this skill does

# Skill System TKT

Single source of truth for all ticket operations across the skill system.

## Two Backends, One Lifecycle

```
Backend 1: Filesystem Bundles (tkt.sh)
  Project-level work management.
  Roadmap → Bundle → Tickets (YAML files in .tkt/)
  Use for: PM-driven decomposition, multi-agent bundles, review generation.

Backend 2: DB Durable Tickets (tickets.py)
  Session-level lifecycle management.
  Intake → Claim → Work → Block/Close (Postgres agent_memories)
  Use for: claim arbitration, session loops, scope enforcement, refresh.
```

Both backends share the same conceptual lifecycle:
```
OPEN → CLAIMED → IN_PROGRESS → DONE/BLOCKED/FAILED/CLOSED
```

## Core Concepts

```
Roadmap (project-level, maintained by PM Agent)
 └─ TKT Bundle (a unit of deliverable work)
     ├─ TKT-000  Integrate   (claimed by Main Agent — coordinates bundle)
     ├─ TKT-001  Worker      (claimed by any agent — actual work)
     ├─ TKT-002  Worker      (claimed by any agent — actual work)
     ├─ TKT-...  Worker      (can be added mid-flight)
     └─ TKT-A00  Audit       (spot-check ticket — random quality verification)
```

### Roles

| Role | Who | Responsibility |
|------|-----|----------------|
| **PM Agent** | Plan/Review agent | Interprets user intent → maintains roadmap → creates bundles → reviews results |
| **Main Agent** | Agent that claims TKT-000 | Coordinates the bundle, integrates outputs, closes TKT-000 when all work is done |
| **Worker Agent** | Any agent that claims a worker TKT | Executes the ticket's task, reports result |
| **Audit Agent** | Agent that claims TKT-A00 | Randomly spot-checks engineering quality across the project |

### Ticket States

```
OPEN → CLAIMED → IN_PROGRESS → DONE
                              → BLOCKED (needs new TKT or intervention)
                              → FAILED  (requires retry or escalation)
```

### Bundle Lifecycle

```mermaid
flowchart TD
    A[PM Agent: interpret user intent] --> B[Create TKT Bundle]
    B --> C[Agents claim tickets]
    C --> D{All worker TKTs DONE?}
    D -->|No| E[Continue / spawn new TKTs]
    E --> C
    D -->|Yes| F[Audit Agent: spot-check]
    F --> G[Main Agent: close TKT-000]
    G --> H[PM Agent: generate Review Bundle]
    H --> I[Review Agent + User discussion]
```

## BH Myelin Loop Contracts

### Review State Contract

In BH myelin loops, a review state is not a passive summary phase. It is ready for closure only after the agent has:

1. explained what the finished adventure actually showed;
2. identified which evidence is clean, dirty, missing, or blocked;
3. prepared next-direction options and a recommendation for Arthur;
4. stated which tempting next actions are intentionally held and why;
5. planted a gate ICD/GPD or WPT rows for the next decision surface instead of leaving it as prose.

If a review only describes results but does not ask Arthur to choose/gate the next direction, it is still active. Agents may recommend; Arthur decides phase transitions. A myelin-loop phase does not end until Arthur has answered the relevant gate ICD.

### Post-change PAT Contract

Any material change must be followed by PAT before the ticket or state is called done. Material changes include code, scripts, configs, prompts, policies, skills, WAG/cron behavior, ICD lint rules, EP routes, and artifact contracts.

PAT must exercise the changed surface directly. Minimal acceptable PAT is:

1. static/shape check for the edited file or schema;
2. direct invocation or contract check for the changed behavior when executable;
3. log, receipt, or query evidence showing the new path is live;
4. a WPT/inbox/memory receipt that records the evidence.

Self-report without a command, query, log, or artifact path is not PAT.

## Configuration

All runtime settings are in `config/tkt.yaml`. Config is the single source of truth — values in this document are documentation only.

See: `../../config/tkt.yaml`

## Data Model

### Filesystem Backend (.tkt/)

```
.tkt/
├── roadmap.yaml              # Project-level roadmap
├── bundles/
│   ├── B-001/
│   │   ├── bundle.yaml       # Bundle metadata
│   │   ├── TKT-000.yaml     # Integrate ticket
│   │   ├── TKT-001.yaml     # Worker ticket
│   │   ├── TKT-A00.yaml     # Audit ticket
│   │   └── review.yaml      # Generated after bundle closes
│   └── B-002/
│       └── ...
└── history.log               # Append-only event log
```

### DB Backend (agent_memories)

Durable tickets stored via `agent_memories` with metadata fields:
- `ticket_id`, `title`, `summary`, `status`
- `claimed_by_session`, `claimed_at`, `closed_at`
- `batch_id`, `queue_order`, `ticket_type` (WORKER/INTEGRATOR/AUDIT)
- `task_provenance` (workflow/verification/legacy)

## Operations

### Filesystem Bundle Operations (tkt.sh)

#### `init-roadmap`
Initialize the `.tkt/` directory and `roadmap.yaml` for a project.

```bash
bash "<this-skill-dir>/scripts/tkt.sh" init-roadmap --project "<name>"
```

#### `create-bundle`
PM Agent interprets user intent and creates a new TKT bundle with tickets.

```bash
bash "<this-skill-dir>/scripts/tkt.sh" create-bundle --goal "<goal>" [--track "<name>"] [--source-plan "<file>"] [--worktree] [--carryover B-001]
```

- `--track`: optional workstream label persisted to `bundle.yaml` (`track` field)
- `--source-plan`: optional source plan path persisted to `bundle.yaml` (`source_plan` field)
- `--worktree`: create `.worktrees/B-NNN` and persist `worktree_path` / `worktree_branch`
- `--carryover`: import worker tickets from another bundle's `carryover.yaml`

**Procedure**: `scripts/create-bundle.md`

#### `claim-ticket` (filesystem)

```bash
bash "<this-skill-dir>/scripts/tkt.sh" claim --bundle B-001 --ticket TKT-001 --agent "<agent-id>"
```

#### `update-ticket`

```bash
bash "<this-skill-dir>/scripts/tkt.sh" update --bundle B-001 --ticket TKT-001 --status done --summary "<result>" --evidence "<proof>"
bash "<this-skill-dir>/scripts/tkt.sh" update --bundle B-001 --ticket TKT-001 --status blocked --reason "<why blocked>"
```

- `--evidence` / `--evidence-file`: required when `--status done`; persisted to `result.evidence`
- `--reason`: required when `--status blocked`; persisted to `result.notes`
- valid transitions are enforced; `claim` handles `open|blocked -> claimed`
- every status change appends `transition_log[]` with `from`, `to`, `timestamp`, and `agent`

#### `add-ticket`

```bash
bash "<this-skill-dir>/scripts/tkt.sh" add --bundle B-001 --type worker --title "<title>" --description "<desc>" [--skills "skill-a,skill-b"] [--wave 2] [--qa-scenarios "run pytest,inspect output"]
```

- `--skills`: optional comma-separated skill names stored as YAML list metadata
- `--wave`: optional numeric wave value for execution ordering metadata
- `--qa-scenarios`: optional comma-separated QA checklist stored as YAML list metadata

#### `batch-update`

```bash
bash "<this-skill-dir>/scripts/tkt.sh" batch update --bundle B-001 --status done --evidence "proof" TKT-001 TKT-002
bash "<this-skill-dir>/scripts/tkt.sh" batch close --bundle B-001 --evidence "proof" TKT-001 TKT-002
```

- `batch update` applies the same update payload across multiple ticket ids
- `batch close` is a shortcut for `status=done` across multiple tickets
- `done` still requires `--evidence` or `--evidence-file`

#### `bundle-status`

```bash
bash "<this-skill-dir>/scripts/tkt.sh" status --bundle B-001
```

- includes each ticket's `transition_log` history in the JSON payload

#### `close-bundle`

```bash
bash "<this-skill-dir>/scripts/tkt.sh" close --bundle B-001 [--merge] [--no-memory]
```

Close-time gates:
- structural validation via `python3 spec/validate_repo_structural.py`
- optional `config/tkt.yaml` `close_gate.command`
- executable acceptance criteria (`{type: command, ...}` objects)
- command-based acceptance criteria execute as argv, not through a shell
- audit ticket must be claimed and `done`
- audit claimant must differ from any worker claimant
- worktree-backed bundles must be clean be