@picoai/tickets 0.4.0 → 0.5.5

package/.tickets/spec/AGENTS_EXAMPLE.md

@@ -11,7 +11,13 @@ The purpose of this bootstrap is to ensure an agent loads the canonical ticketin
 - 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.
+- If the human asks to remove the tickets workflow from this repo, run `npx @picoai/tickets uninstall`.
+- Use `npx @picoai/tickets uninstall --all` only when the human explicitly asks to delete ticket directories and logs too.
 - Respect `assignment.mode`, `agent_limits`, active advisory claims, and repo-local defaults in `.tickets/config.yml`.
 
 ### Bootstrapping TICKETS.md

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-2-tickets-spec.md`
-- Local file: `/.tickets/spec/version/20260317-2-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.
 
@@ -148,7 +148,7 @@ Treat the list above as defaults. Agents should consult `.tickets/config.yml` be
 ---
 id: 0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d
 version: 3
-version_url: "version/20260317-2-tickets-spec.md"
+version_url: "version/20260317-4-tickets-spec.md"
 title: "Feature Alpha"
 status: doing
 created_at: 2026-03-17T17:00:00Z
@@ -193,7 +193,7 @@ resolution: dropped
 Claim log example:
 
 ```json
-{"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":""}}
+{"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`)
@@ -246,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:
@@ -271,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`
 
@@ -321,6 +341,7 @@ Conditional fields:
 
 Recommended fields:
 - `changes`
+- `completion`
 - `verification`
 - `tickets_created`
 - `created_from`
@@ -376,9 +397,12 @@ Agents should:
 2. Open the assigned ticket
 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`
+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/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

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

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-2-tickets-spec.md`
-- Local file in package assets: `.tickets/spec/version/20260317-2-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`
@@ -112,6 +114,17 @@ npx @picoai/tickets init [--examples] [--apply]
 - `--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
 
+### `uninstall`
+
+```bash
+npx @picoai/tickets uninstall [--all] [--yes]
+```
+
+- default: remove tickets-managed workflow files while keeping ticket directories and logs under `/.tickets/<ticket-id>/`
+- `--all`: also remove ticket directories and logs for a clean reset
+- `--yes`: skip interactive confirmation prompts
+- does not remove `@picoai/tickets` from `package.json` (run your package manager uninstall command separately)
+
 ### `new`
 
 ```bash

package/package.json

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

package/release-history.json

@@ -21,6 +21,20 @@
       "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"
+    },
+    {
+      "version": "0.5.0",
+      "commit": "66691ef",
+      "date": "2026-03-17",
+      "channel": "latest",
+      "notes": "Published to npm"
     }
   ]
 }