@picoai/tickets 0.3.0 → 0.4.0

package/.tickets/spec/AGENTS_EXAMPLE.md

@@ -7,6 +7,8 @@ The purpose of this bootstrap is to ensure an agent loads the canonical ticketin
 ### Required Behavior
 - First action: if your environment supports repo-local skills and `.tickets/skills/tickets/SKILL.md` exists, load that skill. Otherwise open and read `TICKETS.md`.
 - First response: briefly confirm understanding of the ticketing system before starting any implementation work.
+- Before interpreting planning language or creating tickets, consult `.tickets/config.yml` for repo-local defaults and semantic overrides.
+- When the human uses feature/phase/milestone/roadmap or custom repo terms, keep using their vocabulary in the conversation and translate it into the generic CLI planning fields internally.
 - Use the repo-local CLI (`npx @picoai/tickets`) as the integration surface for tickets and logs.
 - Before performing work on a ticket, validate it: run `npx @picoai/tickets validate` (or `npx @picoai/tickets validate --issues` + `npx @picoai/tickets repair`).
 - When logging via the CLI: use `npx @picoai/tickets log --machine` so logs are strictly structured.

package/.tickets/spec/TICKETS.md

@@ -40,8 +40,8 @@ This repository uses a repo-native ticketing system designed for **parallel, lon
 
 ## Spec version
 - `version`: 3
-- `version_url`: `version/20260317-tickets-spec.md`
-- Local file: `/.tickets/spec/version/20260317-tickets-spec.md`
+- `version_url`: `version/20260317-2-tickets-spec.md`
+- Local file: `/.tickets/spec/version/20260317-2-tickets-spec.md`
 
 Version definitions live under `/.tickets/spec/version/`. Each spec file is self-contained and ends with a diff from the previous version.
 
@@ -60,6 +60,7 @@ Repo artifacts:
 - `.tickets/config.yml`: authoritative repo-local machine-readable overrides
 - `.tickets/skills/tickets/SKILL.md`: repo skill projection with equivalent workflow semantics
 - `TICKETS.override.md`: optional narrative companion for human-only local policy
+- `/.tickets/derived/planning-index.json`: derived cache used by `list`, `plan`, and `graph`
 
 ## What this system is
 - A lightweight, Markdown-first ticket format stored under `/.tickets/`
@@ -96,6 +97,7 @@ Default `init` creates, if missing:
 - `npx @picoai/tickets status --ticket <id> --status doing`
 - `npx @picoai/tickets log --ticket <id> --summary "..." --machine --context "..."`
 - `npx @picoai/tickets claim --ticket <id>`
+- `npx @picoai/tickets list --ready --sort lane`
 - `npx @picoai/tickets plan --format json`
 - `npx @picoai/tickets graph --view portfolio`
 
@@ -138,6 +140,7 @@ By default:
 - `roadmap` -> `planning.horizon`
 
 Repos may override these mappings in `.tickets/config.yml` without changing the core CLI or validation invariants.
+Treat the list above as defaults. Agents should consult `.tickets/config.yml` before interpreting repo-specific planning language or creating tickets.
 
 ### Worked example
 
@@ -145,7 +148,7 @@ Repos may override these mappings in `.tickets/config.yml` without changing the
 ---
 id: 0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d
 version: 3
-version_url: "version/20260317-tickets-spec.md"
+version_url: "version/20260317-2-tickets-spec.md"
 title: "Feature Alpha"
 status: doing
 created_at: 2026-03-17T17:00:00Z
@@ -190,7 +193,7 @@ resolution: dropped
 Claim log example:
 
 ```json
-{"version":3,"version_url":"version/20260317-tickets-spec.md","ts":"2026-03-17T17:05:00Z","run_started":"20260317T170500.000Z","actor_type":"agent","actor_id":"agent:codex","summary":"Acquired claim 0191c2d3-...","event_type":"claim","written_by":"tickets","claim":{"action":"acquire","claim_id":"0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5d00","holder_id":"agent:codex","holder_type":"agent","ttl_minutes":60,"expires_at":"2026-03-17T18:05:00Z","reason":""}}
+{"version":3,"version_url":"version/20260317-2-tickets-spec.md","ts":"2026-03-17T17:05:00Z","run_started":"20260317T170500.000Z","actor_type":"agent","actor_id":"agent:codex","summary":"Acquired claim 0191c2d3-...","event_type":"claim","written_by":"tickets","claim":{"action":"acquire","claim_id":"0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5d00","holder_id":"agent:codex","holder_type":"agent","ttl_minutes":60,"expires_at":"2026-03-17T18:05:00Z","reason":""}}
 ```
 
 ## Ticket definition (`ticket.md`)
@@ -357,19 +360,25 @@ Primary commands:
 - `graph`
 
 Listing and reporting:
-- `list` can filter by planning fields, claim state, and readiness
-- `plan` reports rollups and ready queues
-- `graph` can render dependency, sequence, portfolio, or combined views
+- `list` is the broad queue/report view. Use it to filter and sort work across the repo.
+- `plan` is the operational board. Use it for ready work, in-progress work, blocked work, and group/checkpoint rollups.
+- `graph` is the structural map. Use it to inspect dependency, sequence, and containment relationships.
+
+Derived index:
+- `list`, `plan`, and `graph` maintain a derived planning index at `/.tickets/derived/planning-index.json`
+- the index is disposable cache state
+- the CLI rebuilds it automatically when ticket, log, config, or tool metadata changes
 
 ## Agent protocol
 
 Agents should:
 1. Load the repo skill if supported and present, otherwise read `TICKETS.md`
 2. Open the assigned ticket
-3. Validate before implementation
-4. Respect `assignment.mode`, `agent_limits`, planning constraints, and active claims
-5. Use `status`, `log`, `claim`, `plan`, and `graph` through the CLI
-6. If splitting work, create child tickets with copied minimum context and log `created_from`
+3. Consult `.tickets/config.yml` for repo-local defaults and semantic overrides before interpreting planning terms or creating tickets
+4. Validate before implementation
+5. Respect `assignment.mode`, `agent_limits`, planning constraints, and active claims
+6. Use `status`, `log`, `claim`, `list`, `plan`, and `graph` through the CLI
+7. If splitting work, create child tickets with copied minimum context and log `created_from`
 
 ## Safety and hygiene
 - Do not write secrets into tickets or logs

package/.tickets/spec/profile/defaults.yml

@@ -3,6 +3,8 @@ workflow:
 defaults:
   planning:
     node_type: work
+    lane: null
+    horizon: null
   claims:
     ttl_minutes: 60
 semantics:

package/.tickets/spec/version/20260317-2-tickets-spec.md

@@ -0,0 +1,106 @@
+# Ticket Format Spec (Version 3)
+
+- Version: 3
+- Version URL: `version/20260317-2-tickets-spec.md`
+- Released: 2026-03-17
+- Status: current
+
+## Definition (format and derived tooling contract)
+This version defines the ticket, repo config, log, and derived planning-index contracts used by this repo. Workflow policy and narrative guidance live in `TICKETS.md`.
+
+### Ticket front matter (required)
+- `id`: lowercase UUIDv7 string
+- `version`: format version (integer)
+- `version_url`: path to this definition (repo-local, relative to `.tickets/spec/`)
+- `title`: string
+- `status`: `todo|doing|blocked|done|canceled`
+- `created_at`: ISO 8601 UTC timestamp
+
+### Ticket front matter (optional)
+- `priority`: `low|medium|high|critical`
+- `labels`: list of strings
+- `assignment`: mapping
+- `dependencies`: list of ticket IDs
+- `blocks`: list of ticket IDs
+- `related`: list of ticket IDs
+- `planning`: mapping
+  - `node_type`: `work|group|checkpoint`
+  - `group_ids`: list of ticket IDs
+  - `lane`: string or null
+  - `rank`: positive integer or null
+  - `horizon`: string or null
+  - `precedes`: list of ticket IDs
+- `resolution`: `completed|merged|dropped|null`
+- `agent_limits`: mapping
+- `verification`: mapping
+- `custom`: mapping
+
+Rules:
+- `resolution` is only valid when `status` is terminal (`done` or `canceled`)
+- grouping is persisted only through `planning.group_ids`
+- sequencing is persisted only through `planning.precedes`
+- `planning.group_ids` may only reference `group` or `checkpoint` tickets
+- `planning.precedes` must not contain cycles
+- group/checkpoint containment must not contain cycles
+- duplicate `rank` values are invalid within the same peer set (`node_type`, sorted `group_ids`, `lane`, `horizon`)
+
+### Repo config (`.tickets/config.yml`)
+- `workflow.mode`: `auto|doc_first|skill_first`
+- `defaults.planning.node_type`: `work|group|checkpoint`
+- `defaults.planning.lane`: string or null
+- `defaults.planning.horizon`: string or null
+- `defaults.claims.ttl_minutes`: positive integer
+- `semantics.terms`: mapping from human-facing terms to generic planning primitives
+- `views`: repo-local reporting preferences
+
+Repo config may override defaults and human semantic mappings, but may not redefine CLI invariants, status values, or log schema.
+
+### Log entry (required)
+- `version`: format version (integer)
+- `version_url`: path to this definition (repo-local, relative to `.tickets/spec/`)
+- `ts`: ISO 8601 UTC timestamp
+- `run_started`: ISO 8601 UTC timestamp
+- `actor_type`: `human|agent`
+- `actor_id`: string
+- `summary`: short string
+- `event_type`: `status|work|claim`
+
+### Log entry (conditional)
+- `context`: non-empty list of strings when `event_type: work` and the entry is machine-written
+- `claim`: required mapping when `event_type: claim`
+  - `action`: `acquire|renew|release|override`
+  - `claim_id`: UUIDv7 string
+  - `holder_id`: string
+  - `holder_type`: `human|agent`
+  - `ttl_minutes`: positive integer for non-release events
+  - `expires_at`: ISO 8601 UTC timestamp for non-release events
+  - `reason`: optional string
+  - `supersedes_claim_id`: optional UUIDv7 string or null
+
+### Derived planning index (`/.tickets/derived/planning-index.json`)
+- The index is derived cache state, not source of truth.
+- The file is disposable and may be rebuilt at any time by the CLI.
+- Required metadata:
+  - `index_format_id`: fixed UUIDv7 identifying the derived index format
+  - `index_format_label`: readable label for the index format revision
+  - `tool.format_version`
+  - `tool.format_version_url`
+  - `source_state`
+- The CLI must rebuild the index when source files or embedded format/tool metadata no longer match.
+
+### Reporting semantics
+- `list` is the broad queue/report view.
+- `plan` is the operational state view for ready, active, blocked, and group rollups.
+- `graph` is the structural relationship view.
+- Repo-specific planning language remains authoritative only in `.tickets/config.yml`.
+
+### Extensions
+- Extensions are repo-local and must live under the `custom` key.
+- Tools should ignore unknown keys under `custom`.
+
+## Diff from previous version
+- Added planning-default overrides for `lane` and `horizon` in `.tickets/config.yml`.
+- Added global planning validation for missing references, invalid group targets, cycles, and rank conflicts.
+- Defined the derived planning index and its invalidation requirements.
+- Clarified the operational split between `list`, `plan`, and `graph`.
+- Clarified that repo-specific semantic mappings remain authoritative only in `.tickets/config.yml`.

package/README.md

@@ -24,8 +24,8 @@ The system is designed for teams that want ticket state to live in the repo, sta
 ## Spec version
 
 - `version`: 3
-- `version_url`: `version/20260317-tickets-spec.md`
-- Local file in package assets: `.tickets/spec/version/20260317-tickets-spec.md`
+- `version_url`: `version/20260317-2-tickets-spec.md`
+- Local file in package assets: `.tickets/spec/version/20260317-2-tickets-spec.md`
 
 ## Install
 
@@ -86,6 +86,7 @@ Default semantic mapping:
 - `roadmap` -> `planning.horizon`
 
 Repos can override those terms in `.tickets/config.yml` without changing core execution semantics.
+Treat the list above as defaults. Agents should consult `.tickets/config.yml` before interpreting repo-specific planning vocabulary.
 
 ## Claims
 
@@ -126,6 +127,12 @@ Planning options:
 - `--precedes <ticketId>` repeatable
 - `--resolution <completed|merged|dropped>`
 
+Behavior:
+- `--group-id` must reference an existing `group` or `checkpoint`
+- missing `lane` and `horizon` can be inherited from referenced parent groups when unambiguous
+- missing `rank` is assigned automatically when the lane is known
+- repo defaults for planning fields come from `.tickets/config.yml`
+
 ### `validate`
 
 ```bash
@@ -137,6 +144,7 @@ Validates:
 - machine-written log entries
 - claim event payloads
 - repo-local `.tickets/config.yml`
+- planning graph correctness such as missing references, cycles, and rank conflicts
 
 ### `status`
 
@@ -174,6 +182,8 @@ Additional filters:
 - `--claimed`
 - `--claimed-by <actorId>`
 - `--ready`
+- `--sort <ready|priority|lane|rank|updated|title>`
+- `--reverse`
 - `--json`
 
 ### `plan`
@@ -186,6 +196,7 @@ Reports ready work and derived group/checkpoint rollups.
 
 Use this when you want to answer:
 - what is ready now
+- what is already in progress
 - what is blocked
 - how a group or checkpoint is progressing
 
@@ -195,6 +206,16 @@ Use this when you want to answer:
 npx @picoai/tickets graph [--ticket <ticket>] [--view dependency|sequence|portfolio|all] [--format mermaid|dot|json]
 ```
 
+`graph` is the structural view. It shows dependency, sequence, and containment relationships, with planning metadata attached to each node.
+
+## Derived index
+
+`list`, `plan`, and `graph` maintain a derived planning index at `/.tickets/derived/planning-index.json`.
+
+- it is cache state, not source of truth
+- it is safe to delete
+- the CLI rebuilds it automatically when tickets, logs, repo config, or tool metadata change
+
 ## Assets shipped with this package
 
 - `.tickets/spec/TICKETS.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoai/tickets",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Repo-native ticketing CLI and assets for Markdown-first, append-only ticket workflows.",
   "license": "Apache-2.0",
   "type": "module",

package/release-history.json

@@ -14,6 +14,13 @@
       "date": "2026-03-11",
       "channel": "latest",
       "notes": "Published to npm"
+    },
+    {
+      "version": "0.3.0",
+      "commit": "b6862fb",
+      "date": "2026-03-17",
+      "channel": "latest",
+      "notes": "Published to npm"
     }
   ]
 }