@picoai/tickets 0.2.0 → 0.4.0

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

@@ -0,0 +1,31 @@
+workflow:
+  mode: auto
+defaults:
+  planning:
+    node_type: work
+    lane: null
+    horizon: null
+  claims:
+    ttl_minutes: 60
+semantics:
+  terms:
+    feature:
+      field: planning.node_type
+      value: group
+      description: A feature is modeled as a group node containing related work.
+    phase:
+      field: planning.lane
+      description: A phase is modeled as a lane value that orders work at a coarse level.
+    milestone:
+      field: planning.node_type
+      value: checkpoint
+      description: A milestone is modeled as a checkpoint node with derived completion.
+    roadmap:
+      field: planning.horizon
+      description: A roadmap is modeled as a horizon value across groups and checkpoints.
+views:
+  plan:
+    sort_by:
+      - planning.lane
+      - planning.rank
+      - priority

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/.tickets/spec/version/20260317-tickets-spec.md

@@ -0,0 +1,82 @@
+# Ticket Format Spec (Version 3)
+
+- Version: 3
+- Version URL: `version/20260317-tickets-spec.md`
+- Released: 2026-03-17
+- Status: current
+
+## Definition (format only)
+This version defines the ticket, repo config, and log formats 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`
+
+### Repo config (`.tickets/config.yml`)
+- `workflow.mode`: `auto|doc_first|skill_first`
+- `defaults`: repo-local defaults
+- `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
+
+### Extensions
+- Extensions are repo-local and must live under the `custom` key.
+- Tools should ignore unknown keys under `custom`.
+
+## Diff from previous version
+- Added the generic planning model under `planning`.
+- Added `resolution` to represent terminal work outcomes.
+- Added `.tickets/config.yml` as the authoritative repo-local override surface.
+- Added `claim` log events and claim payload schema.
+- Clarified that the repo skill and `TICKETS.md` are equivalent workflow projections over the same base model.

package/README.md

@@ -1,78 +1,31 @@
 # @picoai/tickets
 
-## About TICKETS.md
+`@picoai/tickets` is a repo-native ticketing CLI.
 
-This repository specifies a repo-native ticketing workflow designed for **parallel, long-running agentic work** and normal human collaboration, without relying on external services or internet access.
+It gives a repository:
+- a documented workflow in `TICKETS.md`
+- a machine-readable override layer in `.tickets/config.yml`
+- append-only ticket logs for history
+- planning views built from simple shared primitives
+- optional claims to reduce duplicate work across agents
 
-**TICKETS.md** explains the workflow, file formats, and required tool usage for both humans and agents. If there is ever a conflict between this file and other docs, follow this file.
+The system is designed for teams that want ticket state to live in the repo, stay inspectable, and work the same way for humans and agents.
 
-## What this system is
+## Mental model
 
-- A lightweight, Markdown-first ticket format stored under `/.tickets/` in consumer repos.
-- A merge-friendly history model: **append-only JSONL run logs**, one file per run, per ticket.
-- A repo-local CLI (`npx @picoai/tickets`) that is the **single integration surface** for humans, agents, and IDE/agentic tooling.
+- `TICKETS.md` explains the workflow at the repo level
+- `.tickets/config.yml` holds repo-local defaults and semantic overrides
+- `.tickets/skills/tickets/SKILL.md` carries the same workflow for skill-capable environments
+- `ticket.md` holds the stable definition of a piece of work
+- JSONL logs hold append-only history
+- planning is expressed with a small generic model instead of hardcoded product vocabulary
+- claims are optional and advisory, not locks
 
-## What this is trying to do
+## Spec version
 
-Parallel, long-running agentic work fails in predictable ways:
-- Agents lose context across runs/sandboxes.
-- Ticket state can drift across branches before merge (eventual consistency).
-- Shared mutable log files are merge-conflict hotspots.
-- Agents can loop without clear done criteria or verification steps.
-
-This system addresses those problems with stable `ticket.md` files, merge-friendly per-run logs, and explicit acceptance + verification + bounded iteration guidance.
-
-## Spec Version
-
-- `version`: 2
-- `version_url`: `version/20260311-tickets-spec.md`
-- Local file in package assets: `.tickets/spec/version/20260311-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.
-
-## Quickstart: Initialize a Repo
-
-Assuming `@picoai/tickets` is already installed in your target repo:
-
-```bash
-npx @picoai/tickets init
-```
-
-This bootstraps ticketing assets in the target repository by creating:
-- root `TICKETS.md`
-- root `AGENTS_EXAMPLE.md`
-- root `/.tickets/spec/version/` with version definition files
-
-Optional apply mode:
-
-```bash
-npx @picoai/tickets init --apply
-```
-
-`--apply` updates managed sections while preserving user-owned content:
-- updates the managed block in root `TICKETS.md`
-- creates or updates the `## Ticketing Workflow` block in root `AGENTS.md`
-- does not create `AGENTS_EXAMPLE.md` when applying directly to `AGENTS.md`
-
-## Package Overview
-
-Repo-native ticketing CLI for Markdown-first, append-only ticket workflows.
-
-## Release Provenance
-
-- Latest npm release: `@picoai/tickets`
-- Published from commit: `74b0378`
-- Append-only release ledger: `packages/tickets/release-history.json`
-
-Check current release posture locally:
-
-```bash
-npm run release:status --workspace @picoai/tickets
-```
-
-Recommended process:
-- after an npm publish succeeds, append a new entry to `packages/tickets/release-history.json`
-- use `npm run release:status --workspace @picoai/tickets` to see whether HEAD is ahead of the last recorded npm release and whether the package version still needs a bump
+- `version`: 3
+- `version_url`: `version/20260317-2-tickets-spec.md`
+- Local file in package assets: `.tickets/spec/version/20260317-2-tickets-spec.md`
 
 ## Install
 
@@ -89,180 +42,183 @@ npx @picoai/tickets --help
 ## Quickstart
 
 ```bash
-npm install @picoai/tickets
 npx @picoai/tickets init
-npx @picoai/tickets init --apply
-npx @picoai/tickets new --title "Short title"
+npx @picoai/tickets new --title "Feature Alpha" --node-type group --lane build --horizon current
 npx @picoai/tickets validate
+npx @picoai/tickets plan --format json
 ```
 
-## Command Reference
+`init` creates, if missing:
+- `TICKETS.md`
+- an `AGENTS.md` workflow block when used with `--apply`
+- `.tickets/config.yml`
+- `.tickets/skills/tickets/SKILL.md`
+- `.tickets/spec/version/`
+
+## Planning model
+
+The planning model is intentionally small. The CLI works from these fields:
+
+```yaml
+planning:
+  node_type: work | group | checkpoint
+  group_ids: []
+  lane: null
+  rank: null
+  horizon: null
+  precedes: []
+resolution: null # completed | merged | dropped
+```
 
-Use `npx @picoai/tickets <command> --help` for full command help.
+How to think about them:
+- `node_type`: what kind of thing this ticket is
+- `group_ids`: which larger buckets this ticket belongs to
+- `lane`: a broad ordered track such as a phase or stream
+- `rank`: order within a lane or peer set
+- `horizon`: a planning bucket such as current, next, or later
+- `precedes`: sequence edges without turning everything into a hard dependency
+- `resolution`: terminal outcome when work was completed, merged away, or dropped
 
-### `init`
+Default semantic mapping:
+- `feature` -> `planning.node_type=group`
+- `phase` -> `planning.lane`
+- `milestone` -> `planning.node_type=checkpoint`
+- `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
 
-Initialize ticketing structure and templates.
+Claims are optional advisory leases recorded in ticket logs.
 
 ```bash
-npx @picoai/tickets init [--examples] [--apply]
+npx @picoai/tickets claim --ticket <id>
+npx @picoai/tickets claim --ticket <id> --release
+npx @picoai/tickets claim --ticket <id> --force --reason "Taking ownership after timeout"
 ```
 
-- `--examples`: generate example tickets and logs that validate under the current spec.
-- `--apply`: update managed `TICKETS.md` + `AGENTS.md` sections and skip `AGENTS_EXAMPLE.md` output.
+Claims do not change ticket `status`.
+They exist to help multiple agents avoid overlapping work, not to act as hard locks.
 
-### `new`
+## Commands
 
-Create a new ticket.
+### `init`
 
 ```bash
-npx @picoai/tickets new --title "<title>" [options]
+npx @picoai/tickets init [--examples] [--apply]
 ```
 
-Options:
-- `--status <status>` (`todo|doing|blocked|done|canceled`, default `todo`)
-- `--priority <priority>` (`low|medium|high|critical`)
-- `--label <label>` (repeatable)
-- `--assignment-mode <mode>` (`human_only|agent_only|mixed`)
-- `--assignment-owner <owner>`
-- `--dependency <ticketId>` (repeatable)
-- `--block <ticketId>` (repeatable)
-- `--related <ticketId>` (repeatable)
-- `--iteration-timebox-minutes <minutes>`
-- `--max-iterations <count>`
-- `--max-tool-calls <count>`
-- `--checkpoint-every-minutes <minutes>`
-- `--verification-command <command>` (repeatable)
-- `--created-at <timestamp>`
-
-### `validate`
+- `--examples`: generate example tickets and logs that validate under the current spec
+- `--apply`: refresh managed `TICKETS.md`, the managed `AGENTS.md` workflow block, and repo skill content
 
-Validate ticket files and logs.
+### `new`
 
 ```bash
-npx @picoai/tickets validate [options]
+npx @picoai/tickets new --title "<title>" [options]
 ```
 
-Options:
-- `--ticket <ticket>`
-- `--issues` (machine-readable issues/repairs output)
-- `--output <file>` (write issues report to file)
-- `--all-fields` (include optional front-matter validation)
-
-### `repair`
+Planning options:
+- `--node-type <work|group|checkpoint>`
+- `--group-id <ticketId>` repeatable
+- `--lane <lane>`
+- `--rank <rank>`
+- `--horizon <horizon>`
+- `--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`
 
-Repair tickets from current validation state or an issues file.
+### `validate`
 
 ```bash
-npx @picoai/tickets repair [options]
+npx @picoai/tickets validate [--ticket <ticket>] [--issues] [--output <file>] [--all-fields]
 ```
 
-Options:
-- `--ticket <ticket>`
-- `--all`
-- `--issues-file <file>`
-- `--interactive`
-- `--non-interactive`
-- `--all-fields`
-
-Notes:
-- `repair` fixes ticket-file issues and basic log issues.
-- Basic log repairs cover missing/invalid `event_type` and invalid or missing `context` on machine-written work logs.
+Validates:
+- ticket front matter and required sections
+- machine-written log entries
+- claim event payloads
+- repo-local `.tickets/config.yml`
+- planning graph correctness such as missing references, cycles, and rank conflicts
 
 ### `status`
 
-Update ticket status.
-
 ```bash
 npx @picoai/tickets status --ticket <ticket> --status <status> [options]
 ```
 
-Options:
-- `--status <status>` (`todo|doing|blocked|done|canceled`)
-- `--actor-type <human|agent>`
-- `--actor-id <id>`
-- `--context <items...>`
-- `--run-id <runId>`
-- `--run-started <runStarted>`
-
-Notes:
-- `status` always appends a machine-written status-change log entry.
-- include `--context` when the status transition depends on new context you want preserved in the audit trail.
-- `actor_id` default order: `--actor-id`, `TICKETS_ACTOR_ID`, `@${USER|USERNAME}`, `"unknown"`.
-- `actor_type` default order: `--actor-type`, `TICKETS_ACTOR_TYPE`, inferred from `actor_id` prefix (`agent:` -> `agent`, `@` -> `human`), then `human`.
+Always appends a machine-written status log entry.
 
 ### `log`
 
-Append a run log entry.
-
 ```bash
 npx @picoai/tickets log --ticket <ticket> --summary "<text>" [options]
 ```
 
-Options:
-- `--actor-type <human|agent>`
-- `--actor-id <id>`
-- `--context <items...>`
-- `--run-id <runId>`
-- `--run-started <runStarted>`
-- `--machine`
-- `--changes <files...>`
-- `--decisions <decisions...>`
-- `--next-steps <nextSteps...>`
-- `--blockers <blockers...>`
-- `--tickets-created <tickets...>`
-- `--created-from <ticketId>`
-- `--verification-commands <commands...>`
-- `--verification-results <results>`
-
-Notes:
-- `log` records run details without changing ticket lifecycle state.
-- machine-written work logs require at least one `--context` item.
-- for split child bootstrapping, use `--created-from <parent-ticket-id>` together with `--context ...`.
-- `actor_id` default order: `--actor-id`, `TICKETS_ACTOR_ID`, `@${USER|USERNAME}`, `"unknown"`.
-- `actor_type` default order: `--actor-type`, `TICKETS_ACTOR_TYPE`, inferred from `actor_id` prefix (`agent:` -> `agent`, `@` -> `human`), then `human`.
+Machine-written work logs require at least one `--context` item.
 
-### `list`
+### `claim`
+
+```bash
+npx @picoai/tickets claim --ticket <ticket> [--ttl-minutes <minutes>] [--force] [--reason <reason>]
+```
 
-List tickets with optional filters.
+### `list`
 
 ```bash
 npx @picoai/tickets list [options]
 ```
 
-Options:
-- `--status <status>`
-- `--priority <priority>`
-- `--mode <mode>`
-- `--owner <owner>`
-- `--label <label>`
-- `--text <text>`
+Additional filters:
+- `--node-type <nodeType>`
+- `--group <ticketId>`
+- `--lane <lane>`
+- `--horizon <horizon>`
+- `--claimed`
+- `--claimed-by <actorId>`
+- `--ready`
+- `--sort <ready|priority|lane|rank|updated|title>`
+- `--reverse`
 - `--json`
 
-Notes:
-- `--text` searches the ticket title and Markdown body content.
+### `plan`
 
-### `graph`
+```bash
+npx @picoai/tickets plan [--group <ticket>] [--horizon <horizon>] [--format table|json]
+```
 
-Generate dependency graph output.
+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
+
+### `graph`
 
 ```bash
-npx @picoai/tickets graph [options]
+npx @picoai/tickets graph [--ticket <ticket>] [--view dependency|sequence|portfolio|all] [--format mermaid|dot|json]
 ```
 
-Options:
-- `--ticket <ticket>`
-- `--format <format>` (`mermaid|dot|json`, default `mermaid`)
-- `--output <file>`
-- `--related` / `--no-related`
+`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` template source
+- `.tickets/spec/TICKETS.md`
 - `.tickets/spec/AGENTS_EXAMPLE.md`
-- `.tickets/spec/version/*`
-
-These are used by `init` to bootstrap target repositories.
-`init` writes `AGENTS_EXAMPLE.md` at the target repo root from the bundled template.
-With `--apply`, `init` upserts/creates the managed `## Ticketing Workflow` block in `AGENTS.md` (header-targeted, marker-free) and does not create `AGENTS_EXAMPLE.md` in the target repo.
-With `--apply`, `TICKETS.md` updates only the managed section (plus tool/spec/timestamp metadata) and preserves user-owned sections.
+- `.tickets/spec/profile/defaults.yml`
+- `.tickets/spec/version/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoai/tickets",
-  "version": "0.2.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",
@@ -12,6 +12,7 @@
     "src",
     "release-history.json",
     ".tickets/spec/AGENTS_EXAMPLE.md",
+    ".tickets/spec/profile",
     ".tickets/spec/version",
     ".tickets/spec/TICKETS.md",
     "README.md",

package/release-history.json

@@ -7,6 +7,20 @@
       "date": "2026-03-11",
       "channel": "latest",
       "notes": "Published to npm"
+    },
+    {
+      "version": "0.2.0",
+      "commit": "e1ed363",
+      "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"
     }
   ]
 }