@picoai/tickets 0.2.0 → 0.4.0

package/.tickets/spec/TICKETS.md

@@ -6,180 +6,247 @@ This document defines the agent-first in-repo ticketing workflow with explicit o
 
 - About TICKETS.md (may be overwritten): content inside `@picoai/tickets:managed` markers.
   - This is where canonical, interoperable system rules live.
-  - `npx @picoai/tickets init --apply` may replace this section (marker-scoped update).
+  - `npx @picoai/tickets init --apply` may replace this section.
 - User-Owned Extensions (safe to customize): content inside `@picoai/tickets:user` markers.
-  - This is where teams add local policy, integrations, and reusable preferences.
+  - This is where teams add repo-local policy, integrations, and reusable preferences.
   - Tooling should not overwrite this section.
+- Repo-local machine overrides: `.tickets/config.yml`.
+  - This is the authoritative override surface for semantic mapping, defaults, and reporting preferences.
+  - Tooling should create it if missing, but should not overwrite it once present.
+- Optional repo-local narrative overrides: `TICKETS.override.md`.
+  - This is for rationale, examples, and human-readable local policy.
+  - Tooling should not depend on it for machine behavior.
 
 ## Init and Apply Behavior
 
 - `init`:
-  - creates missing repo assets (including root `TICKETS.md`).
+  - creates missing repo assets, including `TICKETS.md`, `.tickets/config.yml`, and `.tickets/skills/tickets/SKILL.md`.
 - `init --apply`:
-  - replaces the managed section only (no heading-level merge across the full document),
-  - preserves user-owned content.
+  - replaces the managed section in `TICKETS.md`,
+  - updates the managed `## Ticketing Workflow` block in `AGENTS.md`,
+  - refreshes the repo skill projection at `.tickets/skills/tickets/SKILL.md`,
+  - preserves user-owned sections and repo-local override files.
 
 ---
 
 <!-- @picoai/tickets:managed:start -->
 ## About TICKETS.md (May Be Overwritten by `init --apply`)
 
-_This section mirrors current canonical `TICKETS.md` content to preserve behavior and compatibility._
+_This section mirrors the current canonical `TICKETS.md` content to preserve behavior and compatibility._
 
 This repository uses a repo-native ticketing system designed for **parallel, long-running agentic work** and normal human collaboration, without relying on external services or internet access.
 
-**TICKETS.md ** explains the workflow, file formats, and required tool usage for both humans and agents. If there is ever a conflict between this file and other docs, follow this file.
+`TICKETS.md` explains the workflow, file formats, planning model, and required tool usage for both humans and agents. If there is ever a conflict between this file and other docs, follow this file.
 
 ## Spec version
-- `version`: 2
-- `version_url`: `version/20260311-tickets-spec.md`
-- Local file: `/.tickets/spec/version/20260311-tickets-spec.md`
+- `version`: 3
+- `version_url`: `version/20260317-2-tickets-spec.md`
+- Local file: `/.tickets/spec/version/20260317-2-tickets-spec.md`
 
 Version definitions live under `/.tickets/spec/version/`. Each spec file is self-contained and ends with a diff from the previous version.
 
-## What this system is
-- A lightweight, Markdown-first ticket format stored under `/.tickets/`.
-- A merge-friendly history model: **append-only JSONL run logs**, one file per run, per ticket.
-- A repo-local CLI (`npx @picoai/tickets`) that is the **single integration surface** for humans, agents, and IDE/agentic tooling.
+## Canonical artifacts and precedence
 
-## What this is trying to do
-Parallel, long-running agentic work fails in predictable ways:
-- Agents lose context across runs/sandboxes.
-- Ticket “state” can drift across branches before merge (eventual consistency).
-- Shared mutable log files are merge-conflict hotspots.
-- Agents can loop without clear “done” criteria or verification steps.
+The system supports both doc-first and skill-first environments without changing behavior.
 
-This system addresses those problems with stable `ticket.md` files, merge-friendly per-run logs, and explicit acceptance + verification + bounded iteration guidance.
+Authoritative precedence:
+1. CLI/spec invariants (non-overridable)
+2. Package-managed base workflow and defaults
+3. Repo-local `.tickets/config.yml`
+4. Optional `TICKETS.override.md`
 
-## Non-negotiables (for merge safety and auditability)
-- **Keep `ticket.md` stable and human-readable.** Put history in run logs.
-- **Append-only logs.** Never rewrite or delete log lines.
-- **Use the repo-local CLI for automation.** Don’t invent parallel formats.
+Repo artifacts:
+- `TICKETS.md`: primary operational and conceptual contract
+- `.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/`
+- A merge-friendly history model: append-only JSONL run logs, one file per run, per ticket
+- A repo-local CLI (`npx @picoai/tickets`) that is the only state-changing integration surface
+- A generic planning model that supports features, phases, milestones, and roadmap views without hardcoding those terms into execution semantics
 
-## Quickstart (humans and agents)
+## Non-negotiables
+- Keep `ticket.md` stable and human-readable. Put history in run logs.
+- Keep run logs append-only. Never rewrite or delete log lines.
+- Use the repo-local CLI for automation. Do not invent parallel formats.
+- Do not derive execution behavior from free-form labels alone. Use the planning primitives.
+
+## Quickstart
 
 ### Initialize
-Create the repo structure and templates (idempotent):
 - `npx @picoai/tickets init`
-- Add `--examples` to generate example tickets (7 sample tickets with required/optional fields, relationships, and logs that validate under the current spec).
-- Add `--apply` to upsert/create the managed `## Ticketing Workflow` block in `AGENTS.md` from `AGENTS_EXAMPLE.md` (without creating `AGENTS_EXAMPLE.md` in the target repo).
-- With `--apply`, `TICKETS.md` updates are marker-scoped: the managed block is replaced and metadata refreshed, while user-owned sections remain unchanged.
-
-Default `init` creates (if missing): `/.tickets/`, `TICKETS.md`, `AGENTS_EXAMPLE.md`, and `/.tickets/spec/version/`.
-
-### Create a ticket
-- `npx @picoai/tickets new --title "Short title"` (defaults: `status: todo`, `created_at: now`)
-- Optional flags to set front matter at creation:
-  - `--status todo|doing|blocked|done|canceled`
-  - `--priority low|medium|high|critical`
-  - `--label <label>` (repeatable)
-  - `--assignment-mode human_only|agent_only|mixed`
-  - `--assignment-owner <@user|team:...|agent:...>`
-  - `--dependency <ticket-id>` `--block <ticket-id>` `--related <ticket-id>` (repeatable)
-  - `--iteration-timebox-minutes <int>` `--max-iterations <int>` `--max-tool-calls <int>` `--checkpoint-every-minutes <int>`
-  - `--verification-command "<cmd>"` (repeatable)
-  - `--created-at <ISO8601 UTC>`
-
-This prints the new ticket ID (a lowercase UUIDv7) and creates:
-- `/.tickets/<ticket-id>/ticket.md`
-- `/.tickets/<ticket-id>/logs/`
-
-### Validate, then work
-- `npx @picoai/tickets validate`
-- Add `--all-fields` to also validate optional front-matter (priority, labels, assignment.owner, verification.commands) and include those in `--issues` reports.
+- `npx @picoai/tickets init --apply`
+
+Default `init` creates, if missing:
+- `TICKETS.md`
+- `AGENTS_EXAMPLE.md`
+- `/.tickets/config.yml`
+- `/.tickets/skills/tickets/SKILL.md`
+- `/.tickets/spec/version/`
 
-If validation fails and you want a complete report + repair plan:
-- `npx @picoai/tickets validate --issues --all-fields > issues.yaml`
+### Create and validate a ticket
+- `npx @picoai/tickets new --title "Short title"`
+- `npx @picoai/tickets validate`
+- `npx @picoai/tickets validate --issues --all-fields --output issues.yaml`
 - `npx @picoai/tickets repair --issues-file issues.yaml --all-fields --non-interactive`
 
-Expected handling loop for a ticket:
-- validate the assigned ticket before changing code
-- use `tickets status` when the lifecycle state changes (`todo`, `doing`, `blocked`, `done`, `canceled`)
-- use `tickets log` for run history within a state: progress, checkpoints, blockers, decisions, verification, and handoff notes
-- machine-written work logs must include `--context`; for split child bootstrapping, pair `--created-from <parent-id>` with `--context ...`
-- reuse the same `--run-started` and `--run-id` for entries from the same run when you want a single per-run log file
+### Coordinate work
+- `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`
 
-### Log your work (human or agent)
-Use the CLI to write logs whenever possible (merge-friendly, structured, and tooling-validated).
+## Repository layout
+- Canonical workflow guide: `TICKETS.md`
+- Machine-readable overrides: `/.tickets/config.yml`
+- Repo skill projection: `/.tickets/skills/tickets/SKILL.md`
+- Ticket storage root: `/.tickets/<ticket-id>/`
+  - Ticket definition: `ticket.md`
+  - Run logs: `logs/<run_started>-<run_id>.jsonl`
+
+## Core planning model
+
+The planning model is intentionally generic. Agents, validators, and rollups operate on these primitives, not on human aliases.
+
+Primitives:
+- `planning.node_type`: `work`, `group`, `checkpoint`
+- `planning.group_ids`: membership edges pointing from a child to one or more containing groups
+- `planning.precedes`: sequencing edges
+- `planning.lane`: coarse ordering bucket
+- `planning.rank`: fine ordering within a lane or peer set
+- `planning.horizon`: roadmap scope such as `current`, `next`, `later`
+- `status`: execution lifecycle state
+- `resolution`: terminal work outcome: `completed`, `merged`, `dropped`
+- advisory `claim`: optional coordination state, stored in logs only
+
+Interpretation:
+- `dependencies` and `blocks` are hard execution constraints
+- `planning.precedes` is sequence/order, not a hard dependency
+- `group_ids` is the only persisted grouping edge; reverse membership and rollups are derived
+- `lane`, `rank`, and `horizon` are generic ordering dimensions, not hardcoded PM vocabulary
+- claims do not change `status`
+
+### Default human semantic mapping
+
+By default:
+- `feature` -> `planning.node_type = group`
+- `phase` -> `planning.lane`
+- `milestone` -> `planning.node_type = checkpoint`
+- `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
 
-Actor defaults for both `tickets status` and `tickets log`:
-- `actor_id`: `--actor-id`, else `TICKETS_ACTOR_ID`, else `@${USER|USERNAME}`, else `"unknown"`
-- `actor_type`: `--actor-type`, else `TICKETS_ACTOR_TYPE`, else infer `agent` from `actor_id` prefix `agent:`, infer `human` from prefix `@`, else default to `human`
+```yaml
+---
+id: 0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d
+version: 3
+version_url: "version/20260317-2-tickets-spec.md"
+title: "Feature Alpha"
+status: doing
+created_at: 2026-03-17T17:00:00Z
+planning:
+  node_type: group
+  lane: build
+  rank: 1
+  horizon: current
+---
+```
 
-Agentic tools (including human-invoked tools like Cursor/Windsurf/Codex CLI/Claude Code) SHOULD log with `--machine`:
-- `npx @picoai/tickets log --ticket <id> --summary "Implemented validator." --machine --actor-id "agent:cursor (human:@alice)" --context "Acceptance criteria from ticket" "API schema v2"`
+Child work ticket:
 
-Humans can log without machine marker:
-- `npx @picoai/tickets log --ticket <id> --summary "Investigated failing test; will retry tomorrow."`
+```yaml
+planning:
+  node_type: work
+  group_ids: ["0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d"]
+  lane: build
+  rank: 2
+  horizon: current
+  precedes: ["0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6e"]
+```
 
----
+Checkpoint ticket:
 
-## Repository layout
-- Canonical workflow guide: `TICKETS.md`
-- Ticket storage root: `/.tickets/`
-- One ticket per directory: `/.tickets/<ticket-id>/`
-  - Ticket definition: `/.tickets/<ticket-id>/ticket.md`
-  - Run logs: `/.tickets/<ticket-id>/logs/<run_started>-<run_id>.jsonl`
+```yaml
+planning:
+  node_type: checkpoint
+  group_ids: ["0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d"]
+  lane: launch
+  rank: 1
+  horizon: current
+```
 
-Notes:
-- `<ticket-id>` is a **lowercase UUIDv7** string.
-- Tooling MUST NOT require the directory name to match the `id` in front matter (convention only).
+Dropped child:
 
----
+```yaml
+status: canceled
+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":""}}
+```
 
 ## Ticket definition (`ticket.md`)
-Ticket files are Markdown documents with YAML front matter and a Markdown body.
 
-### YAML front matter
-Front matter MUST start at the first line and be enclosed by `---`.
+Ticket files are Markdown documents with YAML front matter and a Markdown body.
 
-#### Required fields
+### Required front matter
 - `id`: lowercase UUIDv7 string
-- `version`: format version (integer)
-- `version_url`: path to the definition for this version (repo-local, relative to `.tickets/spec/`)
+- `version`: integer format version
+- `version_url`: repo-local path to the spec
 - `title`: string
 - `status`: `todo|doing|blocked|done|canceled`
-- `created_at`: ISO 8601 timestamp in UTC (use `Z`)
+- `created_at`: ISO 8601 UTC timestamp
 
-Example:
+### Optional front matter
 
-```md
----
-id: 0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d
-version: 2
-version_url: "version/20260311-tickets-spec.md"
-title: "Add tickets validate --issues"
-status: todo
-created_at: 2026-01-29T18:42:10Z
----
-# Ticket
-...
+Assignment:
+```yaml
+assignment:
+  mode: mixed
+  owner: "agent:codex"
 ```
 
-#### Optional fields
-**Assignment and mode**
+Priority and labels:
 ```yaml
-assignment:
-  mode: mixed   # human_only | agent_only | mixed
-  owner: null   # "@alice", "team:core", "agent:codex"
+priority: high
+labels: ["feature", "api"]
+```
+
+Relationships:
+```yaml
+dependencies: []
+blocks: []
+related: []
 ```
 
-**Priority and labels**
+Planning:
 ```yaml
-priority: medium      # low | medium | high | critical
-labels: ["bug", "docs"]
+planning:
+  node_type: work
+  group_ids: []
+  lane: null
+  rank: null
+  horizon: null
+  precedes: []
 ```
 
-**Relationships (the only ones written in v1)**
+Resolution:
 ```yaml
-dependencies: []   # ticket IDs this ticket depends on
-blocks: []         # ticket IDs this ticket blocks
-related: []        # ticket IDs related to this ticket
+resolution: completed   # completed | merged | dropped
 ```
 
-**Agent limits (hard limits for agents)**
+Limits:
 ```yaml
 agent_limits:
   iteration_timebox_minutes: 20
@@ -188,7 +255,7 @@ agent_limits:
   checkpoint_every_minutes: 5
 ```
 
-**Verification commands**
+Verification:
 ```yaml
 verification:
   commands:
@@ -196,254 +263,127 @@ verification:
     - "npx @picoai/tickets validate"
 ```
 
-Important:
-- Other relationship views (parent/child rollups, duplicates, supersedes, reverse edges, etc.) are computed by tooling and MUST NOT be persisted in `ticket.md`.
-- There is no `updated_at`. “Last updated” is derived from log timestamps (`ts`).
-
-**Custom fields (namespaced)**
+Custom fields:
 ```yaml
 custom:
   my_org_priority: "P1"
-  upstream_ref: "RFC-42"
 ```
 
-Custom fields MUST live under `custom` to avoid collisions. Tooling should ignore unknown keys under `custom`.
-Extensions are repo-local; use a clear prefix for keys and avoid introducing new top-level extension fields.
+Rules:
+- `resolution` is only valid on terminal tickets (`done` or `canceled`)
+- `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`
 
-### Versioning
-- `version` is an integer format version (current: `1`).
-- `version_url` must point to the repo-local definition for that version.
-- Version files live under `/.tickets/spec/version/` and end with a diff from the previous version.
-- New tooling must read older versions. If `version` is missing, tools may assume `1` and warn.
-- Bumps are rare and only when a change cannot be expressed additively.
-
-### Ticket body sections (required)
-The ticket body MUST include these sections (at least the headings):
+### Required body sections
 - `# Ticket`
 - `## Description`
-- `## Acceptance Criteria` (checkable list)
-- `## Verification` (commands or steps)
-
----
+- `## Acceptance Criteria`
+- `## Verification`
 
 ## Status model
-Status values: `todo`, `doing`, `blocked`, `done`, `canceled`.
-
-Recommended transitions:
-- `todo` -> `doing` | `canceled`
-- `doing` -> `blocked` | `done` | `canceled`
-- `blocked` -> `doing` | `canceled`
-- `done` and `canceled` are immutable unless explicitly reopened by a human (set to `doing` and log why).
-
-Status updates:
-- `npx @picoai/tickets status --ticket <id> --status doing --actor-type agent --actor-id "agent:codex"`
-- `tickets status` always appends a machine-written status-change log entry.
-
----
-
-## Run logs (append-only JSONL)
-Every ticket directory has `logs/`. Logs are where history lives; they are designed to be merge-friendly under parallel work.
-
-### File naming: `<run_started>-<run_id>.jsonl`
-- `run_started` is the run start time (UTC). It is a *hint* for processing order (tools may process newer runs first by sorting filenames).
-- Tools SHOULD emit `run_started` in ISO 8601 **basic** form for filenames, e.g. `20260129T184210.123Z`.
-- `run_id` is an identifier for the run (tool-generated unless provided).
-
-Example filename:
-- `/.tickets/<id>/logs/20260129T184210.123Z-0191c2d3-....jsonl`
-
-### `ts` vs `run_started`
-- `run_started` is constant for a given run file (and appears on every line so each JSON object is self-contained).
-- `ts` is per entry (the moment that particular log entry was written).
-- “Last updated” is derived from the newest `ts` across all logs, not from filenames.
-
-### Log entry schema (one JSON object per line)
-Required fields:
-- `version`: format version (integer)
-- `version_url`: path to the definition for this version (repo-local, relative to `.tickets/spec/`)
-- `ts`: ISO 8601 UTC timestamp for the entry
-- `run_started`: ISO 8601 UTC timestamp (same for all entries in the file)
-- `actor_type`: `human|agent`
-- `actor_id`: string identifier (freeform)
-- `summary`: short summary string
-- `event_type`: `status|work`
-
-Conditional field:
-- `context`: `[...]` (bullets capturing the context relevant to this run; when splitting, include copied/adapted inputs from the parent)
-  - required for machine-written `work` entries
-  - optional for `status` entries and human-written logs
-
-Optional structured fields (recommended):
-- `changes`: `{files: [...], commits: [...], prs: [...]}`
-- `verification`: `{commands: [...], results: "pass|fail|explain why not run"}`
-- `tickets_created`: `[...]` (ticket IDs created during this run)
-- `created_from`: string (parent ticket ID when created by splitting)
-- `decisions`, `next_steps`, `blockers`: lists of strings
-- `custom`: `{...}` (namespaced custom data)
-
-Machine marker:
-- If a log entry is written by the `tickets` CLI with `--machine`, it MUST include a machine marker:
-  - `written_by: "tickets"` or `machine: true`
-
-Validation strictness:
-- Machine-marked entries are validated strictly.
-- Non-machine entries are validated best-effort (warnings by default), so humans can jot notes without breaking the system.
-
-Example machine-written entry:
-```json
-{"version":2,"version_url":"version/20260311-tickets-spec.md","ts":"2026-01-29T18:50:00Z","run_started":"20260129T184210.123Z","actor_type":"agent","actor_id":"agent:codex-cli (human:@alice)","summary":"Implemented tickets validate --issues.","event_type":"work","context":["Acceptance criteria from ticket","API schema v2"],"verification":{"commands":["npx @picoai/tickets validate"],"results":"pass"},"written_by":"tickets"}
-```
-
-Merge conflict rule (rare):
-- If a `.jsonl` file conflicts, keep all lines from both sides; do not “clean up” history.
-
----
-
-## Required tool usage (agents and automation)
-To keep state consistent and merge-friendly, agents and agentic tools SHOULD use the CLI for ticket operations:
-- Create tickets: `npx @picoai/tickets new`
-- Validate: `npx @picoai/tickets validate` (or `--issues` for a full report)
-- Repair: `npx @picoai/tickets repair --issues-file ...`
-- Status changes: `npx @picoai/tickets status`
-- Work logs: `npx @picoai/tickets log` (use `--machine` when the entry is tooling-written)
-- Listing/triage: `npx @picoai/tickets list` (use `--json` for automation)
-
-Humans may edit `ticket.md` directly (it is designed for that), but logs should be appended via the CLI whenever feasible.
-Expected command roles:
-- `tickets status` changes canonical lifecycle state and always records that state transition in logs
-- `tickets log` records run details without changing lifecycle state
-- first child handoff after a split should be a `tickets log` entry with both `created_from` and `context`
-
----
-
-## Agent task assignment at launch time
-
-### Principle
-Agents SHOULD NOT choose tickets autonomously by default. In this system, a human or orchestrator assigns a specific ticket (or a small set of tickets) to each agent run. This avoids duplicate work when multiple agents operate from the same repo snapshot and cannot coordinate live.
-
-### Required inputs for any agent run
-Every agent run MUST be given, in its initial instructions (prompt, task description, CLI args, PR comment, IDE task, etc.):
-
-1. Ticket locator
-   - A ticket ID, which maps to the ticket definition at:
-     - `/.tickets/<ticket-id>/ticket.md`
-
-2. Task scope
-   - A short statement of what the agent is expected to do on that ticket (for example: "implement acceptance criteria", "fix failing tests", "investigate and report").
-
-3. Run limits
-   - The run's execution limits (timebox / max tool calls / max iterations), if the ticket defines them. Agents must treat these as hard stop conditions.
-
-### Standard instruction template
-When launching an agent, use the following template (adapt as needed to the agent tool, but keep the semantics):
-
-- Ticket: `<ticket-id>`
-- Ticket file: `/.tickets/<ticket-id>/ticket.md`
-- Scope: `<what to do>`
-- Limits: follow `agent_limits` in the ticket (or repo defaults if not present)
-- Stop behavior: on limit hit, stop work and write a run log entry to:
-  - `/.tickets/<ticket-id>/logs/<run_started>-<run_id>.jsonl`
-
-### Mandatory agent procedure (vendor-agnostic)
-Given a ticket assignment, an agent must:
-
-1. Open the ticket file at `/.tickets/<ticket-id>/ticket.md`.
-2. Identify acceptance criteria and verification steps from the ticket.
-3. Validate the ticket before proceeding.
-4. If beginning active work, set status to `doing`.
-5. Plan minimally: determine the smallest change set that satisfies the acceptance criteria.
-6. Implement within limits.
-7. Verify using the ticket's verification steps (or reasonable defaults if absent).
-8. Record progress with `tickets log`, reusing the same run metadata for the same run when appropriate.
-   - if the log is machine-written, include `context`
-   - if the ticket was created by splitting a parent, include `created_from` and the copied/adapted handoff bullets in `context`
-9. If the run changes lifecycle state, use `tickets status` again (`blocked`, `done`, or explicit reassignment/reaffirmation):
-   - Write progress and outcomes to a per-run log file:
-     - `/.tickets/<ticket-id>/logs/<run_started>-<run_id>.jsonl`
-     - Include a `context` field capturing the relevant context for this run (copied/adapted inputs, decisions carried in, and any subticket handoff details).
-   - If the agent cannot write files, it must output the log content in its final response so a human/tool can persist it.
-
-### What to do if the ticket is missing or invalid
-If the assigned ticket file cannot be found, or is missing required sections:
-- The agent must not proceed with implementation.
-- The agent must log the issue and request clarification, or propose a minimal ticket fix as its output.
-
-### Multi-ticket assignments (rare)
-If an agent is assigned more than one ticket in a single run:
-- The run instructions must list ticket IDs in priority order.
-- The agent must work on only one ticket at a time, logging separately under each ticket’s logs directory.
-- Prefer splitting work into separate runs for clarity.
-
-### Human responsibility
-Humans (or an orchestrator) are responsible for:
-- selecting which tickets are assigned to which agents
-- ensuring two agents are not intentionally assigned the same ticket unless parallel exploration is desired
-
----
-
-## Agent workflow (recommended protocol)
-Agents MUST:
-- Read the ticket before starting work.
-- Respect `assignment.mode` (do not work tickets marked `human_only`).
-- Respect hard limits in `agent_limits`; if a limit is reached, stop and write a log entry.
-- At the end of an iteration (success or failure), write a log entry that includes the `context` for that iteration and verification results (or why verification was not run).
-- If `max_iterations` is reached without completion, stop and log a recommendation (tighten criteria, split subtickets, or request a human decision).
-
-Humans using agentic coding tools can follow the same protocol; use `--machine` logging with `actor_type: agent` and an `actor_id` that names the tool and the human (e.g., `cursor (human:@alice)`).
-
----
-
-## Splitting tickets (subtickets) in parallel workflows
-If an agent discovers a ticket is too large or should be parallelized:
-1) Create subtickets with `npx @picoai/tickets new`.
-2) Link with `related` (and only use `dependencies`/`blocks` when there is a real ordering constraint).
-3) Log the split on the original ticket and include `tickets_created`.
-4) Ensure each new ticket is executable in isolation by copying/adapting the minimum required context into the child `ticket.md`, and writing a first child log entry that includes `created_from` and `context` (the carried-over bullets).
-
-Avoid maintaining an authoritative “subtickets list” by frequently editing the parent `ticket.md` (it’s a merge-conflict hotspot). Prefer derived views and logs.
-
----
-
-## Validation, issues reports, and repair
-- `npx @picoai/tickets validate`:
-  - exit `0`: ok
-  - exit `1`: validation errors
-  - exit `2`: tooling/IO errors
-- Add `--all-fields` to validate optional front-matter (priority, labels, assignment.owner, verification.commands) and include corresponding repairs in `--issues` output.
-
-- `npx @picoai/tickets validate --issues` emits a machine-readable report with:
-  - all `issues` (errors and warnings), and
-  - a `repairs` section that can be edited and consumed by `tickets repair` in `--non-interactive` mode.
-- Use `--all-fields` with `validate` and `repair` when you want optional front-matter fields to be checked and fixed.
-- Use `--interactive` with `repair` to step through each fix, see what’s expected, and supply values (include `--all-fields` to cover optional fields too).
-
-Minimal shape (example):
-```yaml
-schema_version: 1
-tool: "tickets"
-generated_at: "2026-01-29T00:00:00Z"
-issues: []
-repairs:
-  - id: "R0001"
-    enabled: false
-    safe: true
-    action: "add_sections"
-    ticket_path: "/.tickets/<id>/ticket.md"
-    params: {}
-```
-
-- `npx @picoai/tickets repair --issues-file <path>` applies enabled repairs:
-  - Safe repairs can be non-interactive.
-  - Disruptive repairs (like changing `id`) must have explicit decisions filled in (or require interactive mode).
-  - Basic log repairs are supported for missing/invalid `event_type` and invalid or missing `context` on machine-written work logs.
-
----
-
-## Safety & hygiene
-- Do not write secrets into tickets or logs.
-- Avoid pasting large environment dumps into logs.
-- Prefer minimal diffs; avoid unrelated refactors.
-- When in doubt, add a log entry with decisions and next steps, and hand off.
+- `todo`, `doing`, `blocked`, `done`, `canceled`
+- `done` and `canceled` are terminal unless explicitly reopened by a human
+
+`tickets status` changes the canonical lifecycle state and appends a machine-written status entry to logs.
+
+## Claims
+
+Claims are optional advisory leases used to reduce duplicate swarm work.
+
+Rules:
+- claims live only in logs
+- claims do not change ticket `status`
+- a claim can be acquired, renewed, released, or force-overridden with a reason
+- expired claims are treated as inactive
+
+Use:
+- `npx @picoai/tickets claim --ticket <id>`
+- `npx @picoai/tickets claim --ticket <id> --release`
+- `npx @picoai/tickets claim --ticket <id> --force --reason "..."` to override
+
+## Run logs
+
+Run logs are append-only JSONL files under `logs/`.
+
+Required log fields:
+- `version`
+- `version_url`
+- `ts`
+- `run_started`
+- `actor_type`
+- `actor_id`
+- `summary`
+- `event_type`: `status|work|claim`
+
+Conditional fields:
+- `context`: required for machine-written `work` entries
+- `claim`: required for `claim` entries
+
+Recommended fields:
+- `changes`
+- `verification`
+- `tickets_created`
+- `created_from`
+- `decisions`
+- `next_steps`
+- `blockers`
+- `custom`
+
+## Derived views and rollups
+
+Rollups are always derived from ticket state and logs. Parent or group tickets do not maintain authoritative child ledgers.
+
+Derived rollup counters:
+- `total_leaf`
+- `active_leaf`
+- `todo`
+- `doing`
+- `blocked`
+- `done_completed`
+- `merged`
+- `dropped`
+
+Completion percentage uses only active leaf work. `merged` and `dropped` do not count against the remaining denominator.
+
+## Commands
+
+Primary commands:
+- `init`
+- `new`
+- `validate`
+- `repair`
+- `status`
+- `log`
+- `claim`
+- `list`
+- `plan`
+- `graph`
+
+Listing and reporting:
+- `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. Consult `.tickets/config.yml` for repo-local defaults and semantic overrides before interpreting planning terms or creating tickets
+4. Validate before implementation
+5. Respect `assignment.mode`, `agent_limits`, planning constraints, and active claims
+6. Use `status`, `log`, `claim`, `list`, `plan`, and `graph` through the CLI
+7. If splitting work, create child tickets with copied minimum context and log `created_from`
+
+## Safety and hygiene
+- Do not write secrets into tickets or logs
+- Avoid unrelated refactors in ticket-scoped work
+- Prefer adding logs with decisions and next steps over rewriting ticket history
 <!-- @picoai/tickets:managed:end -->
 
 ---
@@ -458,39 +398,18 @@ This section is intended for ongoing team customization and expansion.
 Use this section for reusable team preferences agents should apply by default.
 
 Examples:
-- decomposition preference (smaller tickets vs milestone-oriented tickets)
-- required human checkpoints for risky changes
-- default verification evidence format
-- branch/PR naming conventions
-- handoff expectations for agent-to-human and agent-to-agent transitions
+- decomposition preference
+- required human checkpoints
+- verification evidence format
+- claim usage policy
+- rollout and handoff expectations
 
-### External System Mapping (Product/Design/Engineering + Agent Teams)
+### External System Mapping
 
 Document how external systems map to in-repo tickets.
 
-Recommended fields to document:
-- source systems (Jira/Linear/Notion/Figma/etc.)
-- external state -> canonical `status` mapping
-- assignment and ownership boundaries (human teams vs agent teams/swarms)
-- synchronization rules and conflict resolution approach
-
-### Local Custom Policy
-
-Use this area for repo-specific policy that should not be overwritten.
-
-Examples:
-- additional review gates before moving ticket status to `done`
-- rules for high-risk or production-impacting changes
-- release-note and changelog policy
-
-### Optional Team Metadata Conventions
-
-If teams need additional metadata, prefer `custom.*` namespaced keys in ticket front matter and logs.
-
-Examples:
-- `custom.external.ticket_id`
-- `custom.external.state`
-- `custom.routing.queue`
-- `custom.design.figma_url`
+### Local Semantic Notes
 
+Use this section to explain local meanings for human-facing concepts such as feature, phase, milestone, and roadmap.
+The machine-readable source of truth for overrides should remain `.tickets/config.yml`.
 <!-- @picoai/tickets:user:end -->