@picoai/tickets 0.3.0 → 0.5.0

package/.tickets/spec/AGENTS_EXAMPLE.md

@@ -7,8 +7,14 @@ 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`).
+- Before moving a ticket to `done`, confirm the ticket's `## Acceptance Criteria` are met and its `## Verification` checks passed.
+- If those completion gates are not satisfied, ask the human whether to keep working or explicitly override the gates. Only move the ticket to `done` after that human decision.
+- Record `completion` metadata every time a ticket is moved to `done`.
+- When a human overrides incomplete completion gates, record that override in the ticket via `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...`.
 - When logging via the CLI: use `npx @picoai/tickets log --machine` so logs are strictly structured.
 - Respect `assignment.mode`, `agent_limits`, active advisory claims, and repo-local defaults in `.tickets/config.yml`.
 

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-4-tickets-spec.md`
+- Local file: `/.tickets/spec/version/20260317-4-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-4-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-4-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`)
@@ -243,6 +246,23 @@ Resolution:
 resolution: completed   # completed | merged | dropped
 ```
 
+Completion:
+```yaml
+completion:
+  acceptance_criteria: met   # met | not_met
+  verification: passed       # passed | failed | not_run
+```
+
+Human-approved completion override:
+```yaml
+completion:
+  acceptance_criteria: not_met
+  verification: not_run
+  overridden_by: "@product-owner"
+  override_reason: "Human approved closing this ticket without meeting the usual done gates."
+  override_at: 2026-03-17T18:30:00Z
+```
+
 Limits:
 ```yaml
 agent_limits:
@@ -268,6 +288,9 @@ custom:
 
 Rules:
 - `resolution` is only valid on terminal tickets (`done` or `canceled`)
+- `completion` is required on tickets with `status: done`
+- if `completion.acceptance_criteria != met` or `completion.verification != passed`, `completion.overridden_by`, `completion.override_reason`, and `completion.override_at` are required
+- override fields are only valid when the usual completion gates were not fully satisfied
 - `custom` is reserved for repo-local extensions not standardized by the spec
 - other relationship views are computed by tooling and must not be persisted in `ticket.md`
 
@@ -318,6 +341,7 @@ Conditional fields:
 
 Recommended fields:
 - `changes`
+- `completion`
 - `verification`
 - `tickets_created`
 - `created_from`
@@ -357,19 +381,28 @@ 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. Before setting a ticket to `done`, confirm the ticket's `## Acceptance Criteria` are met and its `## Verification` checks passed
+6. If those completion gates are not satisfied, stop and ask a human whether to keep working or explicitly override the gates
+7. When a human overrides incomplete completion gates, record that override in `ticket.md` and the status log via `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...`
+8. Respect `assignment.mode`, `agent_limits`, planning constraints, and active claims
+9. Use `status`, `log`, `claim`, `list`, `plan`, and `graph` through the CLI
+10. 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/20260205-tickets-spec.md

@@ -3,7 +3,7 @@
 - Version: 1
 - Version URL: `version/20260205-tickets-spec.md`
 - Released: 2026-02-05
-- Status: current
+- Status: superseded
 
 ## Definition (format only)
 This version defines the ticket and log formats used by this repo. It does not define workflow policy; see `TICKETS.md` for full workflow.

package/.tickets/spec/version/20260311-tickets-spec.md

@@ -3,7 +3,7 @@
 - Version: 2
 - Version URL: `version/20260311-tickets-spec.md`
 - Released: 2026-03-11
-- Status: current
+- Status: superseded
 
 ## Definition (format only)
 This version defines the ticket and log formats used by this repo. It does not define workflow policy; see `TICKETS.md` for full workflow.

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: superseded
+
+## 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-3-tickets-spec.md

@@ -0,0 +1,121 @@
+# Ticket Format Spec (Version 3)
+
+- Version: 3
+- Version URL: `version/20260317-3-tickets-spec.md`
+- Released: 2026-03-17
+- Status: superseded
+
+## 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`
+- `completion`: mapping
+  - `acceptance_criteria`: `met|not_met`
+  - `verification`: `passed|failed|not_run`
+  - `overridden_by`: string or null
+  - `override_reason`: string or null
+  - `override_at`: ISO 8601 UTC timestamp or null
+- `agent_limits`: mapping
+- `verification`: mapping
+- `custom`: mapping
+
+Rules:
+- `resolution` is only valid when `status` is terminal (`done` or `canceled`)
+- `completion` is only valid when `status` is `done`
+- if `completion.acceptance_criteria != met` or `completion.verification != passed`, `completion.overridden_by`, `completion.override_reason`, and `completion.override_at` are required
+- override fields are only valid when the usual completion gates were not fully satisfied
+- 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
+
+### Log entry (optional)
+- `completion`: mapping on `status` events when a done decision was recorded
+  - `acceptance_criteria`: `met|not_met`
+  - `verification`: `passed|failed|not_run`
+  - `overridden_by`: string or null
+  - `override_reason`: string or null
+  - `override_at`: ISO 8601 UTC timestamp 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 standardized `completion` metadata for recording whether acceptance criteria and verification passed before a ticket was moved to `done`.
+- Added explicit human-override fields for done tickets that were closed without fully satisfying the usual completion gates.
+- Allowed status log entries to mirror recorded `completion` decisions for auditability.

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

@@ -0,0 +1,120 @@
+# Ticket Format Spec (Version 3)
+
+- Version: 3
+- Version URL: `version/20260317-4-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`
+- `completion`: mapping
+  - `acceptance_criteria`: `met|not_met`
+  - `verification`: `passed|failed|not_run`
+  - `overridden_by`: string or null
+  - `override_reason`: string or null
+  - `override_at`: ISO 8601 UTC timestamp or null
+- `agent_limits`: mapping
+- `verification`: mapping
+- `custom`: mapping
+
+Rules:
+- `resolution` is only valid when `status` is terminal (`done` or `canceled`)
+- `completion` is required when `status` is `done`
+- if `completion.acceptance_criteria != met` or `completion.verification != passed`, `completion.overridden_by`, `completion.override_reason`, and `completion.override_at` are required
+- override fields are only valid when the usual completion gates were not fully satisfied
+- 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
+
+### Log entry (optional)
+- `completion`: mapping on `status` events when a done decision was recorded
+  - `acceptance_criteria`: `met|not_met`
+  - `verification`: `passed|failed|not_run`
+  - `overridden_by`: string or null
+  - `override_reason`: string or null
+  - `override_at`: ISO 8601 UTC timestamp 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
+- Tightened the `completion` contract so every `done` ticket must persist completion metadata.
+- Kept human-approved completion overrides as the supported path for closing tickets when usual done gates are not fully satisfied.

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

@@ -3,7 +3,7 @@
 - Version: 3
 - Version URL: `version/20260317-tickets-spec.md`
 - Released: 2026-03-17
-- Status: current
+- Status: superseded
 
 ## 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`.

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-4-tickets-spec.md`
+- Local file in package assets: `.tickets/spec/version/20260317-4-tickets-spec.md`
 
 ## Install
 
@@ -79,6 +79,8 @@ How to think about them:
 - `precedes`: sequence edges without turning everything into a hard dependency
 - `resolution`: terminal outcome when work was completed, merged away, or dropped
 
+Completion is tracked separately from terminal outcome, and it is required on every `done` ticket. A ticket should only be treated as done when its acceptance criteria are met and its verification checks pass. If a human explicitly wants to close a ticket without those gates passing, record that override in `completion` so the exception is visible in both `ticket.md` and the status log.
+
 Default semantic mapping:
 - `feature` -> `planning.node_type=group`
 - `phase` -> `planning.lane`
@@ -86,6 +88,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 +129,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 +146,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 +184,8 @@ Additional filters:
 - `--claimed`
 - `--claimed-by <actorId>`
 - `--ready`
+- `--sort <ready|priority|lane|rank|updated|title>`
+- `--reverse`
 - `--json`
 
 ### `plan`
@@ -186,6 +198,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 +208,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.5.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,20 @@
       "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"
+    },
+    {
+      "version": "0.4.0",
+      "commit": "93272fc",
+      "date": "2026-03-17",
+      "channel": "latest",
+      "notes": "Published to npm"
     }
   ]
 }