@picoai/tickets 0.4.0 → 0.5.0

package/.tickets/spec/AGENTS_EXAMPLE.md

@@ -11,6 +11,10 @@ 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.
 - 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-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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoai/tickets",
-  "version": "0.4.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

@@ -21,6 +21,13 @@
       "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"
     }
   ]
 }

package/src/cli.js

@@ -8,6 +8,8 @@ import yaml from "yaml";
 import {
   ASSIGNMENT_MODE_VALUES,
   BASE_DIR,
+  COMPLETION_ACCEPTANCE_VALUES,
+  COMPLETION_VERIFICATION_VALUES,
   DEFAULT_CLAIM_TTL_MINUTES,
   FORMAT_VERSION,
   FORMAT_VERSION_URL,
@@ -34,6 +36,7 @@ import {
   loadTicket,
   newUuidv7,
   nowUtc,
+  parseIso,
   readTemplate,
   repoRoot,
   resolveTicketPath,
@@ -96,6 +99,102 @@ function normalizeContextItems(values) {
   return values.map((value) => String(value).trim()).filter(Boolean);
 }
 
+function hasCompletionOptions(options) {
+  return [
+    options.acceptanceCriteria,
+    options.verificationState,
+    options.overrideBy,
+    options.overrideReason,
+    options.overrideAt,
+  ].some((value) => value !== undefined);
+}
+
+function trimOptionalString(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized ? normalized : null;
+}
+
+function buildCompletionRecord(existingCompletion, options) {
+  const explicitCompletion = hasCompletionOptions(options);
+  if (!explicitCompletion) {
+    if (options.status !== "done") {
+      return null;
+    }
+    if (!existingCompletion || typeof existingCompletion !== "object" || Array.isArray(existingCompletion)) {
+      throw new Error("Completion data is required when --status done");
+    }
+    return existingCompletion;
+  }
+
+  if (options.status !== "done") {
+    throw new Error("Completion data is only valid when --status done");
+  }
+
+  const completion =
+    existingCompletion && typeof existingCompletion === "object" && !Array.isArray(existingCompletion)
+      ? { ...existingCompletion }
+      : {};
+
+  if (options.acceptanceCriteria !== undefined) {
+    completion.acceptance_criteria = options.acceptanceCriteria;
+  }
+  if (options.verificationState !== undefined) {
+    completion.verification = options.verificationState;
+  }
+  if (options.overrideBy !== undefined) {
+    completion.overridden_by = trimOptionalString(options.overrideBy);
+  }
+  if (options.overrideReason !== undefined) {
+    completion.override_reason = trimOptionalString(options.overrideReason);
+  }
+  if (options.overrideAt !== undefined) {
+    completion.override_at = options.overrideAt;
+  }
+
+  if (!COMPLETION_ACCEPTANCE_VALUES.includes(completion.acceptance_criteria)) {
+    throw new Error(
+      `Completion acceptance criteria must be one of: ${COMPLETION_ACCEPTANCE_VALUES.join(", ")}`,
+    );
+  }
+  if (!COMPLETION_VERIFICATION_VALUES.includes(completion.verification)) {
+    throw new Error(
+      `Completion verification state must be one of: ${COMPLETION_VERIFICATION_VALUES.join(", ")}`,
+    );
+  }
+
+  const overrideRequired =
+    completion.acceptance_criteria !== "met" || completion.verification !== "passed";
+  if (overrideRequired) {
+    if (!trimOptionalString(completion.overridden_by)) {
+      throw new Error(
+        "Human override approval is required when acceptance criteria are not met or verification did not pass",
+      );
+    }
+    if (!trimOptionalString(completion.override_reason)) {
+      throw new Error(
+        "Override reason is required when acceptance criteria are not met or verification did not pass",
+      );
+    }
+    if (completion.override_at === undefined || completion.override_at === null) {
+      completion.override_at = iso8601(nowUtc());
+    }
+    if (!parseIso(completion.override_at)) {
+      throw new Error("Override timestamp must be ISO8601 UTC");
+    }
+    completion.overridden_by = trimOptionalString(completion.overridden_by);
+    completion.override_reason = trimOptionalString(completion.override_reason);
+    return completion;
+  }
+
+  delete completion.overridden_by;
+  delete completion.override_reason;
+  delete completion.override_at;
+  return completion;
+}
+
 function groupIdSignature(groupIds = []) {
   return [...groupIds].sort((a, b) => a.localeCompare(b)).join(",");
 }
@@ -1052,18 +1151,24 @@ async function cmdInit(options) {
   const versionDir = path.join(repoBaseDir, "version");
   ensureDir(versionDir);
 
-  const currentSpecPath = path.join(versionDir, "20260317-2-tickets-spec.md");
-  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260317-2-tickets-spec.md"), apply);
+  const currentSpecPath = path.join(versionDir, "20260317-4-tickets-spec.md");
+  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260317-4-tickets-spec.md"), apply);
 
-  const previousCurrentSpecPath = path.join(versionDir, "20260311-tickets-spec.md");
+  const previousCurrentSpecPath = path.join(versionDir, "20260317-3-tickets-spec.md");
   writeTemplateFile(
     previousCurrentSpecPath,
-    path.join(".tickets", "spec", "version", "20260311-tickets-spec.md"),
+    path.join(".tickets", "spec", "version", "20260317-3-tickets-spec.md"),
     apply,
   );
 
-  const previousSpecPath = path.join(versionDir, "20260205-tickets-spec.md");
-  writeTemplateFile(previousSpecPath, path.join(".tickets", "spec", "version", "20260205-tickets-spec.md"), apply);
+  const previousSpecPath = path.join(versionDir, "20260317-2-tickets-spec.md");
+  writeTemplateFile(previousSpecPath, path.join(".tickets", "spec", "version", "20260317-2-tickets-spec.md"), apply);
+
+  const olderSpecPath = path.join(versionDir, "20260311-tickets-spec.md");
+  writeTemplateFile(olderSpecPath, path.join(".tickets", "spec", "version", "20260311-tickets-spec.md"), apply);
+
+  const legacySpecPath = path.join(versionDir, "20260205-tickets-spec.md");
+  writeTemplateFile(legacySpecPath, path.join(".tickets", "spec", "version", "20260205-tickets-spec.md"), apply);
 
   const proposedPath = path.join(versionDir, "PROPOSED-tickets-spec.md");
   writeTemplateFile(proposedPath, path.join(".tickets", "spec", "version", "PROPOSED-tickets-spec.md"), apply);
@@ -1115,6 +1220,8 @@ async function cmdNew(options) {
     planning.rank = inferNextRank(snapshot, planning);
   }
 
+  const completion = buildCompletionRecord(null, options);
+
   const frontMatter = {
     id: ticketId,
     version: FORMAT_VERSION,
@@ -1168,6 +1275,9 @@ async function cmdNew(options) {
     frontMatter.verification = { commands: options.verificationCommands };
   }
   frontMatter.planning = planning;
+  if (completion) {
+    frontMatter.completion = completion;
+  }
   if (options.resolution) {
     frontMatter.resolution = options.resolution;
   }
@@ -1259,12 +1369,24 @@ async function cmdStatus(options) {
   const actorId = resolveActorId(options.actorId);
   const actorType = resolveActorType(options.actorType, actorId);
   const context = normalizeContextItems(options.context);
+  const completion = buildCompletionRecord(frontMatter.completion, options);
 
   frontMatter.status = options.status;
+  if (options.status === "done" && completion) {
+    frontMatter.completion = completion;
+  } else {
+    delete frontMatter.completion;
+  }
+  if (!["done", "canceled"].includes(options.status)) {
+    delete frontMatter.resolution;
+  }
   writeTicket(ticketPath, frontMatter, body);
 
   const runId = options.runId || newUuidv7();
   const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const hasCompletionOverride =
+    completion &&
+    (completion.acceptance_criteria !== "met" || completion.verification !== "passed");
   const entry = {
     version: FORMAT_VERSION,
     version_url: FORMAT_VERSION_URL,
@@ -1274,14 +1396,17 @@ async function cmdStatus(options) {
     actor_id: actorId,
     summary:
       previousStatus === options.status
-        ? `Status reaffirmed as ${options.status}`
-        : `Status changed from ${previousStatus ?? "unknown"} to ${options.status}`,
+        ? `Status reaffirmed as ${options.status}${hasCompletionOverride ? " with human override" : ""}`
+        : `Status changed from ${previousStatus ?? "unknown"} to ${options.status}${hasCompletionOverride ? " with human override" : ""}`,
     event_type: "status",
     written_by: "tickets",
   };
   if (context.length > 0) {
     entry.context = context;
   }
+  if (options.status === "done" && completion) {
+    entry.completion = completion;
+  }
 
   const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
   appendJsonl(logPath, entry);
@@ -1695,10 +1820,31 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--horizon <horizon>")
     .option("--precedes <ticketId>", "Sequence successor ticket id", collectOption, [])
     .option("--resolution <resolution>")
+    .option("--acceptance-criteria <state>", "Completion acceptance state: met | not_met")
+    .option("--verification-state <state>", "Completion verification state: passed | failed | not_run")
+    .option("--override-by <actorId>", "Human who approved bypassing completion gates")
+    .option("--override-reason <reason>", "Why the ticket was closed without passing all completion gates")
+    .option("--override-at <timestamp>", "When the human override was approved (ISO8601 UTC)")
     .action(async (options) => {
       if (!STATUS_VALUES.includes(options.status)) {
         throw new Error(`Invalid --status. Use one of: ${STATUS_VALUES.join(", ")}`);
       }
+      if (
+        options.acceptanceCriteria &&
+        !COMPLETION_ACCEPTANCE_VALUES.includes(options.acceptanceCriteria)
+      ) {
+        throw new Error(
+          `Invalid --acceptance-criteria. Use one of: ${COMPLETION_ACCEPTANCE_VALUES.join(", ")}`,
+        );
+      }
+      if (
+        options.verificationState &&
+        !COMPLETION_VERIFICATION_VALUES.includes(options.verificationState)
+      ) {
+        throw new Error(
+          `Invalid --verification-state. Use one of: ${COMPLETION_VERIFICATION_VALUES.join(", ")}`,
+        );
+      }
       if (options.priority && !PRIORITY_VALUES.includes(options.priority)) {
         throw new Error(`Invalid --priority. Use one of: ${PRIORITY_VALUES.join(", ")}`);
       }
@@ -1749,6 +1895,11 @@ export async function run(argv = process.argv.slice(2)) {
         horizon: options.horizon,
         precedes: options.precedes,
         resolution: options.resolution,
+        acceptanceCriteria: options.acceptanceCriteria,
+        verificationState: options.verificationState,
+        overrideBy: options.overrideBy,
+        overrideReason: options.overrideReason,
+        overrideAt: options.overrideAt,
       });
     });
 
@@ -1773,6 +1924,11 @@ export async function run(argv = process.argv.slice(2)) {
     .description("Update ticket status")
     .requiredOption("--ticket <ticket>")
     .requiredOption("--status <status>")
+    .option("--acceptance-criteria <state>", "Completion acceptance state: met | not_met")
+    .option("--verification-state <state>", "Completion verification state: passed | failed | not_run")
+    .option("--override-by <actorId>", "Human who approved bypassing completion gates")
+    .option("--override-reason <reason>", "Why the ticket was closed without passing all completion gates")
+    .option("--override-at <timestamp>", "When the human override was approved (ISO8601 UTC)")
     .option("--actor-type <actorType>")
     .option("--actor-id <actorId>")
     .option("--context <items...>")
@@ -1782,12 +1938,33 @@ export async function run(argv = process.argv.slice(2)) {
       if (!STATUS_VALUES.includes(options.status)) {
         throw new Error(`Invalid --status. Use one of: ${STATUS_VALUES.join(", ")}`);
       }
+      if (
+        options.acceptanceCriteria &&
+        !COMPLETION_ACCEPTANCE_VALUES.includes(options.acceptanceCriteria)
+      ) {
+        throw new Error(
+          `Invalid --acceptance-criteria. Use one of: ${COMPLETION_ACCEPTANCE_VALUES.join(", ")}`,
+        );
+      }
+      if (
+        options.verificationState &&
+        !COMPLETION_VERIFICATION_VALUES.includes(options.verificationState)
+      ) {
+        throw new Error(
+          `Invalid --verification-state. Use one of: ${COMPLETION_VERIFICATION_VALUES.join(", ")}`,
+        );
+      }
       if (options.actorType && !isValidActorType(options.actorType)) {
         throw new Error("Invalid --actor-type. Use one of: human, agent");
       }
       process.exitCode = await cmdStatus({
         ticket: options.ticket,
         status: options.status,
+        acceptanceCriteria: options.acceptanceCriteria,
+        verificationState: options.verificationState,
+        overrideBy: options.overrideBy,
+        overrideReason: options.overrideReason,
+        overrideAt: options.overrideAt,
         actorType: options.actorType,
         actorId: options.actorId,
         context: options.context,

package/src/lib/constants.js

@@ -1,12 +1,14 @@
 export const BASE_DIR = ".tickets/spec";
 export const FORMAT_VERSION = 3;
-export const FORMAT_VERSION_URL = "version/20260317-2-tickets-spec.md";
+export const FORMAT_VERSION_URL = "version/20260317-4-tickets-spec.md";
 
 export const STATUS_VALUES = ["todo", "doing", "blocked", "done", "canceled"];
 export const PRIORITY_VALUES = ["low", "medium", "high", "critical"];
 export const ASSIGNMENT_MODE_VALUES = ["human_only", "agent_only", "mixed"];
 export const PLANNING_NODE_TYPES = ["work", "group", "checkpoint"];
 export const RESOLUTION_VALUES = ["completed", "merged", "dropped"];
+export const COMPLETION_ACCEPTANCE_VALUES = ["met", "not_met"];
+export const COMPLETION_VERIFICATION_VALUES = ["passed", "failed", "not_run"];
 export const CLAIM_ACTION_VALUES = ["acquire", "renew", "release", "override"];
 export const WORKFLOW_MODE_VALUES = ["auto", "doc_first", "skill_first"];
 export const GRAPH_VIEW_VALUES = ["dependency", "sequence", "portfolio", "all"];

package/src/lib/projections.js

@@ -32,6 +32,10 @@ export function renderRepoSkill(profile = loadDefaultProfile()) {
     "- Read `TICKETS.md` for the full repo contract when context is missing.",
     "- Consult `.tickets/config.yml` for repo-local defaults and semantic overrides before interpreting planning terminology or creating new tickets.",
     "- Validate assigned tickets before implementation with `npx @picoai/tickets validate`.",
+    "- Before setting a ticket to `done`, confirm the ticket's `## Acceptance Criteria` are met and its `## Verification` checks passed.",
+    "- If those completion gates are not satisfied, stop and ask a 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 the exception through `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...` so `ticket.md` and the status log both reflect it.",
     "- Use `npx @picoai/tickets status`, `log`, `claim`, `plan`, and `graph` instead of editing derived state manually.",
     "- When humans use terms like feature, phase, milestone, roadmap, or repo-specific equivalents, translate them through `.tickets/config.yml` and then call the generic CLI fields.",
     "- Respect repo overrides in `.tickets/config.yml` and any narrative guidance in `TICKETS.override.md` if present.",

package/src/lib/validation.js

@@ -4,6 +4,8 @@ import path from "node:path";
 import {
   ASSIGNMENT_MODE_VALUES,
   CLAIM_ACTION_VALUES,
+  COMPLETION_ACCEPTANCE_VALUES,
+  COMPLETION_VERIFICATION_VALUES,
   PLANNING_NODE_TYPES,
   PRIORITY_VALUES,
   RESOLUTION_VALUES,
@@ -298,6 +300,124 @@ export function validateTicket(ticketPath, allFields = false) {
     }
   }
 
+  if ("completion" in frontMatter) {
+    const completion = frontMatter.completion;
+    if (!completion || typeof completion !== "object" || Array.isArray(completion)) {
+      issues.push({
+        severity: "error",
+        code: "COMPLETION_INVALID",
+        message: "completion must be mapping",
+        ticket_path: ticketPath,
+      });
+    } else {
+      const acceptance = completion.acceptance_criteria;
+      const verification = completion.verification;
+      const overriddenBy = completion.overridden_by;
+      const overrideReason = completion.override_reason;
+      const overrideAt = completion.override_at;
+
+      if (!COMPLETION_ACCEPTANCE_VALUES.includes(acceptance)) {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_ACCEPTANCE_INVALID",
+          message: `completion.acceptance_criteria must be one of ${COMPLETION_ACCEPTANCE_VALUES.join("|")}`,
+          ticket_path: ticketPath,
+        });
+      }
+
+      if (!COMPLETION_VERIFICATION_VALUES.includes(verification)) {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_VERIFICATION_INVALID",
+          message: `completion.verification must be one of ${COMPLETION_VERIFICATION_VALUES.join("|")}`,
+          ticket_path: ticketPath,
+        });
+      }
+
+      if (frontMatter.status !== "done") {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_STATUS_INVALID",
+          message: "completion requires status done",
+          ticket_path: ticketPath,
+        });
+      }
+
+      const overrideRequired = acceptance !== "met" || verification !== "passed";
+      const hasOverrideBy = typeof overriddenBy === "string" && overriddenBy.trim();
+      const hasOverrideReason = typeof overrideReason === "string" && overrideReason.trim();
+      const hasOverrideAt = overrideAt !== undefined && overrideAt !== null;
+
+      if (overriddenBy !== undefined && overriddenBy !== null && typeof overriddenBy !== "string") {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_OVERRIDE_BY_INVALID",
+          message: "completion.overridden_by must be string or null",
+          ticket_path: ticketPath,
+        });
+      }
+
+      if (overrideReason !== undefined && overrideReason !== null && typeof overrideReason !== "string") {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_OVERRIDE_REASON_INVALID",
+          message: "completion.override_reason must be string or null",
+          ticket_path: ticketPath,
+        });
+      }
+
+      if (hasOverrideAt && !parseIso(overrideAt)) {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_OVERRIDE_AT_INVALID",
+          message: "completion.override_at must be ISO8601 UTC or null",
+          ticket_path: ticketPath,
+        });
+      }
+
+      if (overrideRequired) {
+        if (!hasOverrideBy) {
+          issues.push({
+            severity: "error",
+            code: "COMPLETION_OVERRIDE_BY_MISSING",
+            message: "completion.overridden_by required when completion gates are not fully satisfied",
+            ticket_path: ticketPath,
+          });
+        }
+        if (!hasOverrideReason) {
+          issues.push({
+            severity: "error",
+            code: "COMPLETION_OVERRIDE_REASON_MISSING",
+            message: "completion.override_reason required when completion gates are not fully satisfied",
+            ticket_path: ticketPath,
+          });
+        }
+        if (!hasOverrideAt) {
+          issues.push({
+            severity: "error",
+            code: "COMPLETION_OVERRIDE_AT_MISSING",
+            message: "completion.override_at required when completion gates are not fully satisfied",
+            ticket_path: ticketPath,
+          });
+        }
+      } else if (hasOverrideBy || hasOverrideReason || hasOverrideAt) {
+        issues.push({
+          severity: "error",
+          code: "COMPLETION_OVERRIDE_UNEXPECTED",
+          message: "completion override fields are only valid when acceptance criteria or verification are not fully satisfied",
+          ticket_path: ticketPath,
+        });
+      }
+    }
+  } else if (frontMatter.status === "done") {
+    issues.push({
+      severity: "error",
+      code: "COMPLETION_MISSING",
+      message: "completion required when status is done",
+      ticket_path: ticketPath,
+    });
+  }
+
   if ("agent_limits" in frontMatter) {
     if (!frontMatter.agent_limits || typeof frontMatter.agent_limits !== "object" || Array.isArray(frontMatter.agent_limits)) {
       issues.push({
@@ -910,6 +1030,122 @@ export function validateRunLog(logPath, machineStrictDefault) {
         log: loc,
       });
     }
+
+    if ("completion" in entry) {
+      const completion = entry.completion;
+      if (!completion || typeof completion !== "object" || Array.isArray(completion)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "LOG_COMPLETION_INVALID",
+          message: "completion must be mapping",
+          log: loc,
+        });
+      } else {
+        if (eventType !== "status") {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_EVENT_INVALID",
+            message: "completion is only valid on status events",
+            log: loc,
+          });
+        }
+
+        if (!COMPLETION_ACCEPTANCE_VALUES.includes(completion.acceptance_criteria)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_ACCEPTANCE_INVALID",
+            message: `completion.acceptance_criteria must be one of ${COMPLETION_ACCEPTANCE_VALUES.join("|")}`,
+            log: loc,
+          });
+        }
+
+        if (!COMPLETION_VERIFICATION_VALUES.includes(completion.verification)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_VERIFICATION_INVALID",
+            message: `completion.verification must be one of ${COMPLETION_VERIFICATION_VALUES.join("|")}`,
+            log: loc,
+          });
+        }
+
+        const overrideRequired =
+          completion.acceptance_criteria !== "met" || completion.verification !== "passed";
+        const hasOverrideBy =
+          typeof completion.overridden_by === "string" && completion.overridden_by.trim();
+        const hasOverrideReason =
+          typeof completion.override_reason === "string" && completion.override_reason.trim();
+        const hasOverrideAt = completion.override_at !== undefined && completion.override_at !== null;
+
+        if (
+          completion.overridden_by !== undefined &&
+          completion.overridden_by !== null &&
+          typeof completion.overridden_by !== "string"
+        ) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_OVERRIDE_BY_INVALID",
+            message: "completion.overridden_by must be string or null",
+            log: loc,
+          });
+        }
+
+        if (
+          completion.override_reason !== undefined &&
+          completion.override_reason !== null &&
+          typeof completion.override_reason !== "string"
+        ) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_OVERRIDE_REASON_INVALID",
+            message: "completion.override_reason must be string or null",
+            log: loc,
+          });
+        }
+
+        if (hasOverrideAt && !parseIso(completion.override_at)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_OVERRIDE_AT_INVALID",
+            message: "completion.override_at must be ISO8601 UTC or null",
+            log: loc,
+          });
+        }
+
+        if (overrideRequired) {
+          if (!hasOverrideBy) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "LOG_COMPLETION_OVERRIDE_BY_MISSING",
+              message: "completion.overridden_by required when completion gates are not fully satisfied",
+              log: loc,
+            });
+          }
+          if (!hasOverrideReason) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "LOG_COMPLETION_OVERRIDE_REASON_MISSING",
+              message: "completion.override_reason required when completion gates are not fully satisfied",
+              log: loc,
+            });
+          }
+          if (!hasOverrideAt) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "LOG_COMPLETION_OVERRIDE_AT_MISSING",
+              message: "completion.override_at required when completion gates are not fully satisfied",
+              log: loc,
+            });
+          }
+        } else if (hasOverrideBy || hasOverrideReason || hasOverrideAt) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "LOG_COMPLETION_OVERRIDE_UNEXPECTED",
+            message: "completion override fields are only valid when acceptance criteria or verification are not fully satisfied",
+            log: loc,
+          });
+        }
+      }
+    }
   });
 
   return issues;