@picoai/tickets 0.1.0 → 0.2.0

package/.tickets/spec/TICKETS.md

@@ -31,9 +31,9 @@ This repository uses a repo-native ticketing system designed for **parallel, lon
 **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.
 
 ## Spec version
-- `version`: 1
-- `version_url`: `version/20260205-tickets-spec.md`
-- Local file: `/.tickets/spec/version/20260205-tickets-spec.md`
+- `version`: 2
+- `version_url`: `version/20260311-tickets-spec.md`
+- Local file: `/.tickets/spec/version/20260311-tickets-spec.md`
 
 Version definitions live under `/.tickets/spec/version/`. Each spec file is self-contained and ends with a diff from the previous version.
 
@@ -63,7 +63,7 @@ This system addresses those problems with stable `ticket.md` files, merge-friend
 ### 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).
+- 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.
 
@@ -94,14 +94,25 @@ If validation fails and you want a complete report + repair plan:
 - `npx @picoai/tickets validate --issues --all-fields > 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
+
 ### Log your work (human or agent)
 Use the CLI to write logs whenever possible (merge-friendly, structured, and tooling-validated).
 
+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`
+
 Agentic tools (including human-invoked tools like Cursor/Windsurf/Codex CLI/Claude Code) SHOULD log with `--machine`:
-- `npx @picoai/tickets log --ticket <id> --actor-type agent --actor-id "cursor (human:@alice)" --summary "Implemented validator." --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"`
 
 Humans can log without machine marker:
-- `npx @picoai/tickets log --ticket <id> --actor-type human --actor-id "@alice" --summary "Investigated failing test; will retry tomorrow."`
+- `npx @picoai/tickets log --ticket <id> --summary "Investigated failing test; will retry tomorrow."`
 
 ---
 
@@ -137,8 +148,8 @@ Example:
 ```md
 ---
 id: 0191c2d3-4e5f-7a8b-9c0d-1e2f3a4b5c6d
-version: 1
-version_url: "version/20260205-tickets-spec.md"
+version: 2
+version_url: "version/20260311-tickets-spec.md"
 title: "Add tickets validate --issues"
 status: todo
 created_at: 2026-01-29T18:42:10Z
@@ -225,7 +236,8 @@ Recommended transitions:
 - `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 --log`
+- `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.
 
 ---
 
@@ -254,7 +266,12 @@ Required fields:
 - `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: [...]}`
@@ -274,7 +291,7 @@ Validation strictness:
 
 Example machine-written entry:
 ```json
-{"version":1,"version_url":"version/20260205-tickets-spec.md","ts":"2026-01-29T18:50:00Z","run_started":"20260129T184210.123Z","actor_type":"agent","actor_id":"codex-cli (human:@alice)","summary":"Implemented tickets validate --issues.","context":["Inputs: AC from ticket, API schema v2"],"verification":{"commands":["npx @picoai/tickets validate"],"results":"pass"},"written_by":"tickets"}
+{"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):
@@ -287,11 +304,15 @@ To keep state consistent and merge-friendly, agents and agentic tools SHOULD use
 - 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 --log`
+- 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`
 
 ---
 
@@ -328,10 +349,15 @@ 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. Plan minimally: determine the smallest change set that satisfies the acceptance criteria.
-4. Implement within limits.
-5. Verify using the ticket's verification steps (or reasonable defaults if absent).
-6. Log the run:
+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).
@@ -409,6 +435,7 @@ repairs:
 - `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.
 
 ---
 

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

@@ -0,0 +1,38 @@
+# Ticket Format Spec (Version 2)
+
+- Version: 2
+- Version URL: `version/20260311-tickets-spec.md`
+- Released: 2026-03-11
+- Status: current
+
+## 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.
+
+### 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
+
+### 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`
+
+### Log entry (conditional)
+- `context`: non-empty list of strings when `event_type: work` and the entry is machine-written
+
+### Extensions
+- Extensions are repo-local and must live under the `custom` key.
+- Tools should ignore unknown keys under `custom`.
+
+## Diff from previous version
+- Added required `event_type` to log entries.
+- Clarified that `context` is required for machine-written `work` entries, not for every log entry.

package/README.md

@@ -24,9 +24,9 @@ This system addresses those problems with stable `ticket.md` files, merge-friend
 
 ## Spec Version
 
-- `version`: 1
-- `version_url`: `version/20260205-tickets-spec.md`
-- Local file in package assets: `.tickets/spec/version/20260205-tickets-spec.md`
+- `version`: 2
+- `version_url`: `version/20260311-tickets-spec.md`
+- Local file in package assets: `.tickets/spec/version/20260311-tickets-spec.md`
 
 Version definitions live under `.tickets/spec/version/`. Each spec file is self-contained and ends with a diff from the previous version.
 
@@ -58,6 +58,22 @@ npx @picoai/tickets init --apply
 
 Repo-native ticketing CLI for Markdown-first, append-only ticket workflows.
 
+## Release Provenance
+
+- Latest npm release: `@picoai/tickets`
+- Published from commit: `74b0378`
+- Append-only release ledger: `packages/tickets/release-history.json`
+
+Check current release posture locally:
+
+```bash
+npm run release:status --workspace @picoai/tickets
+```
+
+Recommended process:
+- after an npm publish succeeds, append a new entry to `packages/tickets/release-history.json`
+- use `npm run release:status --workspace @picoai/tickets` to see whether HEAD is ahead of the last recorded npm release and whether the package version still needs a bump
+
 ## Install
 
 ```bash
@@ -92,7 +108,7 @@ Initialize ticketing structure and templates.
 npx @picoai/tickets init [--examples] [--apply]
 ```
 
-- `--examples`: generate example tickets and logs.
+- `--examples`: generate example tickets and logs that validate under the current spec.
 - `--apply`: update managed `TICKETS.md` + `AGENTS.md` sections and skip `AGENTS_EXAMPLE.md` output.
 
 ### `new`
@@ -149,6 +165,10 @@ Options:
 - `--non-interactive`
 - `--all-fields`
 
+Notes:
+- `repair` fixes ticket-file issues and basic log issues.
+- Basic log repairs cover missing/invalid `event_type` and invalid or missing `context` on machine-written work logs.
+
 ### `status`
 
 Update ticket status.
@@ -159,19 +179,30 @@ npx @picoai/tickets status --ticket <ticket> --status <status> [options]
 
 Options:
 - `--status <status>` (`todo|doing|blocked|done|canceled`)
-- `--log`
+- `--actor-type <human|agent>`
+- `--actor-id <id>`
+- `--context <items...>`
 - `--run-id <runId>`
 - `--run-started <runStarted>`
 
+Notes:
+- `status` always appends a machine-written status-change log entry.
+- include `--context` when the status transition depends on new context you want preserved in the audit trail.
+- `actor_id` default order: `--actor-id`, `TICKETS_ACTOR_ID`, `@${USER|USERNAME}`, `"unknown"`.
+- `actor_type` default order: `--actor-type`, `TICKETS_ACTOR_TYPE`, inferred from `actor_id` prefix (`agent:` -> `agent`, `@` -> `human`), then `human`.
+
 ### `log`
 
 Append a run log entry.
 
 ```bash
-npx @picoai/tickets log --ticket <ticket> --actor-type <human|agent> --actor-id <id> --summary "<text>" [options]
+npx @picoai/tickets log --ticket <ticket> --summary "<text>" [options]
 ```
 
 Options:
+- `--actor-type <human|agent>`
+- `--actor-id <id>`
+- `--context <items...>`
 - `--run-id <runId>`
 - `--run-started <runStarted>`
 - `--machine`
@@ -181,10 +212,16 @@ Options:
 - `--blockers <blockers...>`
 - `--tickets-created <tickets...>`
 - `--created-from <ticketId>`
-- `--context-carried-over <items...>`
 - `--verification-commands <commands...>`
 - `--verification-results <results>`
 
+Notes:
+- `log` records run details without changing ticket lifecycle state.
+- machine-written work logs require at least one `--context` item.
+- for split child bootstrapping, use `--created-from <parent-ticket-id>` together with `--context ...`.
+- `actor_id` default order: `--actor-id`, `TICKETS_ACTOR_ID`, `@${USER|USERNAME}`, `"unknown"`.
+- `actor_type` default order: `--actor-type`, `TICKETS_ACTOR_TYPE`, inferred from `actor_id` prefix (`agent:` -> `agent`, `@` -> `human`), then `human`.
+
 ### `list`
 
 List tickets with optional filters.
@@ -202,6 +239,9 @@ Options:
 - `--text <text>`
 - `--json`
 
+Notes:
+- `--text` searches the ticket title and Markdown body content.
+
 ### `graph`
 
 Generate dependency graph output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoai/tickets",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Repo-native ticketing CLI and assets for Markdown-first, append-only ticket workflows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "src",
+    "release-history.json",
     ".tickets/spec/AGENTS_EXAMPLE.md",
     ".tickets/spec/version",
     ".tickets/spec/TICKETS.md",
@@ -18,6 +19,7 @@
   ],
   "scripts": {
     "tickets": "node ./bin/tickets.js",
+    "release:status": "node ./src/release-status.js",
     "test": "node --test",
     "test:cli": "node --test tests/tickets-cli.test.js",
     "pack:check": "npm pack --dry-run --cache /tmp/npm-cache-tickets"

package/release-history.json

@@ -0,0 +1,12 @@
+{
+  "package": "@picoai/tickets",
+  "releases": [
+    {
+      "version": "0.1.0",
+      "commit": "74b0378",
+      "date": "2026-03-11",
+      "channel": "latest",
+      "notes": "Published to npm"
+    }
+  ]
+}

package/src/cli.js

@@ -40,6 +40,52 @@ function hasErrors(issues) {
   return issues.some((issue) => issue.severity === "error");
 }
 
+function isValidActorType(value) {
+  return ["human", "agent"].includes(value);
+}
+
+function resolveActorId(explicitActorId) {
+  const candidate = explicitActorId ?? process.env.TICKETS_ACTOR_ID;
+  if (typeof candidate === "string" && candidate.trim()) {
+    return candidate.trim();
+  }
+
+  const localUser = process.env.USER ?? process.env.USERNAME;
+  if (typeof localUser === "string" && localUser.trim()) {
+    return `@${localUser.trim()}`;
+  }
+
+  return "unknown";
+}
+
+function resolveActorType(explicitActorType, actorId) {
+  const candidate = explicitActorType ?? process.env.TICKETS_ACTOR_TYPE;
+  if (typeof candidate === "string" && candidate.trim()) {
+    if (!isValidActorType(candidate.trim())) {
+      throw new Error("Invalid actor type. Use one of: human, agent");
+    }
+    return candidate.trim();
+  }
+
+  if (typeof actorId === "string") {
+    if (actorId.startsWith("agent:")) {
+      return "agent";
+    }
+    if (actorId.startsWith("@")) {
+      return "human";
+    }
+  }
+
+  return "human";
+}
+
+function normalizeContextItems(values) {
+  if (!Array.isArray(values)) {
+    return [];
+  }
+  return values.map((value) => String(value).trim()).filter(Boolean);
+}
+
 function printIssues(issues) {
   for (const issue of issues) {
     const location = issue.ticket_path ?? issue.log ?? "";
@@ -65,11 +111,14 @@ function buildRepairsFromIssues(issues, options = {}) {
   for (const issue of issues) {
     const code = issue.code;
     const ticketPath = issue.ticket_path;
-    if (!ticketPath) {
+    const logLocation = issue.log;
+    const logPath = logLocation ? String(logLocation).replace(/:\d+$/, "") : null;
+    if (!ticketPath && !logPath) {
       continue;
     }
 
-    const key = `${code}:${ticketPath}`;
+    const targetPath = ticketPath ?? logPath;
+    const key = `${code}:${targetPath}`;
     if (seen.has(key)) {
       continue;
     }
@@ -85,10 +134,31 @@ function buildRepairsFromIssues(issues, options = {}) {
       id: nextId,
       enabled: false,
       issue_ids: [issue.id ?? ""],
-      ticket_path: ticketPath,
     };
+    if (ticketPath) {
+      base.ticket_path = ticketPath;
+    }
+    if (logPath) {
+      base.log_path = logPath;
+    }
 
-    if (code === "MISSING_SECTION") {
+    if (["LOG_EVENT_TYPE_MISSING", "LOG_EVENT_TYPE_INVALID"].includes(code)) {
+      repairs.push({
+        ...base,
+        safe: true,
+        action: "set_log_event_type",
+        params: {},
+        optional: false,
+      });
+    } else if (["CONTEXT_INVALID", "CONTEXT_EMPTY", "CONTEXT_ENTRY_INVALID", "CONTEXT_MISSING"].includes(code)) {
+      repairs.push({
+        ...base,
+        safe: true,
+        action: "normalize_log_context",
+        params: {},
+        optional: false,
+      });
+    } else if (code === "MISSING_SECTION") {
       repairs.push({ ...base, safe: true, action: "add_sections", params: {}, optional: false });
     } else if (["VERSION_MISSING", "VERSION_INVALID"].includes(code)) {
       repairs.push({
@@ -678,6 +748,7 @@ function generateExampleTickets() {
       logs: [
         {
           summary: "Epic created and split into child tickets.",
+          context: ["Parent planning context for Feature Alpha", "Child tickets were split for parallel execution"],
           tickets_created: ["backend", "frontend", "testing", "docs"],
           next_steps: ["Coordinate release window", "Monitor blockers"],
         },
@@ -709,7 +780,7 @@ function generateExampleTickets() {
           summary: "Scaffolded API and outlined endpoints.",
           decisions: ["Using UUID primary keys", "Respond with JSON:API style"],
           created_from: "parent",
-          context_carried_over: ["Acceptance criteria from parent", "Release target"],
+          context: ["Acceptance criteria from parent", "Release target"],
         },
       ],
     },
@@ -732,7 +803,7 @@ function generateExampleTickets() {
           summary: "Waiting on API responses to stabilize.",
           blockers: ["Backend contract not finalized"],
           created_from: "parent",
-          context_carried_over: ["Design mocks v1.2", "API schema draft"],
+          context: ["Design mocks v1.2", "API schema draft"],
         },
       ],
     },
@@ -754,7 +825,7 @@ function generateExampleTickets() {
           summary: "Outlined E2E scenarios to automate.",
           next_steps: ["Set up test data fixtures"],
           created_from: "parent",
-          context_carried_over: ["Frontend flow chart", "Backend contract v1"],
+          context: ["Frontend flow chart", "Backend contract v1"],
         },
       ],
     },
@@ -776,7 +847,7 @@ function generateExampleTickets() {
           summary: "Preparing outline; waiting on test results.",
           blockers: ["Integration tests pending"],
           created_from: "parent",
-          context_carried_over: ["Feature overview", "Known limitations"],
+          context: ["Feature overview", "Known limitations"],
         },
       ],
     },
@@ -797,6 +868,7 @@ function generateExampleTickets() {
       logs: [
         {
           summary: "Drafted release checklist; waiting on test green.",
+          context: ["Release checklist draft", "Waiting on integration test completion"],
           next_steps: ["Book release window"],
         },
       ],
@@ -818,6 +890,7 @@ function generateExampleTickets() {
       logs: [
         {
           summary: "Blocked until backend fix lands.",
+          context: ["Regression repro identified", "Awaiting backend deployment before retry"],
           blockers: ["Awaiting backend deployment"],
         },
       ],
@@ -886,16 +959,17 @@ function generateExampleTickets() {
         actor_type: "agent",
         actor_id: "tickets-init",
         summary: logSpec.summary,
+        event_type: "work",
         written_by: "tickets",
       };
 
       for (const key of [
+        "context",
         "decisions",
         "next_steps",
         "blockers",
         "tickets_created",
         "created_from",
-        "context_carried_over",
       ]) {
         if (!(key in logSpec)) {
           continue;
@@ -935,8 +1009,11 @@ async function cmdInit(options) {
   const versionDir = path.join(repoBaseDir, "version");
   ensureDir(versionDir);
 
-  const specPath = path.join(versionDir, "20260205-tickets-spec.md");
-  writeTemplateFile(specPath, path.join(".tickets", "spec", "version", "20260205-tickets-spec.md"), apply);
+  const currentSpecPath = path.join(versionDir, "20260311-tickets-spec.md");
+  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260311-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 proposedPath = path.join(versionDir, "PROPOSED-tickets-spec.md");
   writeTemplateFile(proposedPath, path.join(".tickets", "spec", "version", "PROPOSED-tickets-spec.md"), apply);
@@ -1085,28 +1162,37 @@ async function cmdValidate(options) {
 async function cmdStatus(options) {
   const ticketPath = resolveTicketPath(options.ticket);
   const [frontMatter, body] = loadTicket(ticketPath);
+  const previousStatus = frontMatter.status;
+  const actorId = resolveActorId(options.actorId);
+  const actorType = resolveActorType(options.actorType, actorId);
+  const context = normalizeContextItems(options.context);
 
   frontMatter.status = options.status;
   writeTicket(ticketPath, frontMatter, body);
 
-  if (options.log) {
-    const runId = options.runId || newUuidv7();
-    const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
-    const entry = {
-      version: FORMAT_VERSION,
-      version_url: FORMAT_VERSION_URL,
-      ts: iso8601(nowUtc()),
-      run_started: runStarted,
-      actor_type: "human",
-      actor_id: "status-change",
-      summary: `Status set to ${options.status}`,
-      written_by: "tickets",
-    };
-
-    const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
-    appendJsonl(logPath, entry);
+  const runId = options.runId || newUuidv7();
+  const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const entry = {
+    version: FORMAT_VERSION,
+    version_url: FORMAT_VERSION_URL,
+    ts: iso8601(nowUtc()),
+    run_started: runStarted,
+    actor_type: actorType,
+    actor_id: actorId,
+    summary:
+      previousStatus === options.status
+        ? `Status reaffirmed as ${options.status}`
+        : `Status changed from ${previousStatus ?? "unknown"} to ${options.status}`,
+    event_type: "status",
+    written_by: "tickets",
+  };
+  if (context.length > 0) {
+    entry.context = context;
   }
 
+  const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
+  appendJsonl(logPath, entry);
+
   return 0;
 }
 
@@ -1114,16 +1200,26 @@ async function cmdLog(options) {
   const ticketPath = resolveTicketPath(options.ticket);
   const runId = options.runId || newUuidv7();
   const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const actorId = resolveActorId(options.actorId);
+  const actorType = resolveActorType(options.actorType, actorId);
+  const context = normalizeContextItems(options.context);
+  if (options.machine && context.length === 0) {
+    throw new Error("Machine-written work logs require at least one --context item");
+  }
 
   const entry = {
     version: FORMAT_VERSION,
     version_url: FORMAT_VERSION_URL,
     ts: iso8601(nowUtc()),
     run_started: runStarted,
-    actor_type: options.actorType,
-    actor_id: options.actorId,
+    actor_type: actorType,
+    actor_id: actorId,
     summary: options.summary,
+    event_type: "work",
   };
+  if (context.length > 0) {
+    entry.context = context;
+  }
 
   if (options.machine) {
     entry.written_by = "tickets";
@@ -1146,9 +1242,6 @@ async function cmdLog(options) {
   if (options.createdFrom) {
     entry.created_from = options.createdFrom;
   }
-  if (options.contextCarriedOver?.length) {
-    entry.context_carried_over = options.contextCarriedOver;
-  }
   if (options.verificationCommands?.length || options.verificationResults) {
     entry.verification = {
       commands: options.verificationCommands || [],
@@ -1226,6 +1319,24 @@ async function cmdRepair(options) {
         autoEnableSafe: !options.interactive,
       }),
     );
+
+    const logsDir = path.join(path.dirname(ticketPath), "logs");
+    if (!fs.existsSync(logsDir)) {
+      continue;
+    }
+    const logFiles = fs
+      .readdirSync(logsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+      .map((entry) => path.join(logsDir, entry.name))
+      .sort((a, b) => a.localeCompare(b));
+    for (const logFile of logFiles) {
+      repairs.push(
+        ...buildRepairsFromIssues(validateRunLog(logFile, false), {
+          includeOptional: options.allFields,
+          autoEnableSafe: !options.interactive,
+        }),
+      );
+    }
   }
 
   const changes = options.interactive
@@ -1364,17 +1475,24 @@ export async function run(argv = process.argv.slice(2)) {
     .description("Update ticket status")
     .requiredOption("--ticket <ticket>")
     .requiredOption("--status <status>")
-    .option("--log", "Write a status-change log entry")
+    .option("--actor-type <actorType>")
+    .option("--actor-id <actorId>")
+    .option("--context <items...>")
     .option("--run-id <runId>")
     .option("--run-started <runStarted>")
     .action(async (options) => {
       if (!STATUS_VALUES.includes(options.status)) {
         throw new Error(`Invalid --status. Use one of: ${STATUS_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,
-        log: Boolean(options.log),
+        actorType: options.actorType,
+        actorId: options.actorId,
+        context: options.context,
         runId: options.runId,
         runStarted: options.runStarted,
       });
@@ -1386,8 +1504,8 @@ export async function run(argv = process.argv.slice(2)) {
     .requiredOption("--ticket <ticket>")
     .option("--run-id <runId>")
     .option("--run-started <runStarted>")
-    .requiredOption("--actor-type <actorType>")
-    .requiredOption("--actor-id <actorId>")
+    .option("--actor-type <actorType>")
+    .option("--actor-id <actorId>")
     .requiredOption("--summary <summary>")
     .option("--machine")
     .option("--changes <files...>")
@@ -1396,11 +1514,11 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--blockers <blockers...>")
     .option("--tickets-created <tickets...>")
     .option("--created-from <ticketId>")
-    .option("--context-carried-over <items...>")
+    .option("--context <items...>")
     .option("--verification-commands <commands...>")
     .option("--verification-results <results>")
     .action(async (options) => {
-      if (!["human", "agent"].includes(options.actorType)) {
+      if (options.actorType && !isValidActorType(options.actorType)) {
         throw new Error("Invalid --actor-type. Use one of: human, agent");
       }
       process.exitCode = await cmdLog({
@@ -1417,7 +1535,7 @@ export async function run(argv = process.argv.slice(2)) {
         blockers: options.blockers,
         ticketsCreated: options.ticketsCreated,
         createdFrom: options.createdFrom,
-        contextCarriedOver: options.contextCarriedOver,
+        context: options.context,
         verificationCommands: options.verificationCommands,
         verificationResults: options.verificationResults,
       });

package/src/lib/constants.js

@@ -1,6 +1,6 @@
 export const BASE_DIR = ".tickets/spec";
-export const FORMAT_VERSION = 1;
-export const FORMAT_VERSION_URL = "version/20260205-tickets-spec.md";
+export const FORMAT_VERSION = 2;
+export const FORMAT_VERSION_URL = "version/20260311-tickets-spec.md";
 
 export const STATUS_VALUES = ["todo", "doing", "blocked", "done", "canceled"];
 export const PRIORITY_VALUES = ["low", "medium", "high", "critical"];

package/src/lib/listing.js

@@ -8,11 +8,11 @@ export function listTickets(filters) {
   const rows = [];
 
   for (const ticketPath of collectTicketPaths(null)) {
-    const [, frontMatter] = validateTicket(ticketPath);
+    const [, frontMatter, body] = validateTicket(ticketPath);
     if (!frontMatter || Object.keys(frontMatter).length === 0) {
       continue;
     }
-    if (!passesFilters(frontMatter, filters)) {
+    if (!passesFilters(frontMatter, body, filters)) {
       continue;
     }
 
@@ -30,7 +30,7 @@ export function listTickets(filters) {
   return rows;
 }
 
-function passesFilters(frontMatter, filters) {
+function passesFilters(frontMatter, body, filters) {
   if (filters.status && frontMatter.status !== filters.status) {
     return false;
   }
@@ -51,7 +51,7 @@ function passesFilters(frontMatter, filters) {
   }
   if (filters.text) {
     const text = String(filters.text).toLowerCase();
-    const haystack = `${frontMatter.title ?? ""}\n${frontMatter.description ?? ""}`.toLowerCase();
+    const haystack = `${frontMatter.title ?? ""}\n${body ?? ""}`.toLowerCase();
     if (!haystack.includes(text)) {
       return false;
     }

package/src/lib/repair.js

@@ -14,6 +14,7 @@ import {
   newUuidv7,
   nowUtc,
   parseIso,
+  readJsonl,
   writeTicket,
 } from "./util.js";
 
@@ -37,6 +38,7 @@ export async function applyRepairs(repairs, options = {}) {
     const action = repair.action;
     const params = repair.params ?? {};
     const ticketPath = repair.ticket_path;
+    const logPath = repair.log_path;
 
     if (action === "set_front_matter_field") {
       const field = params.field;
@@ -91,6 +93,18 @@ export async function applyRepairs(repairs, options = {}) {
       continue;
     }
 
+    if (action === "set_log_event_type") {
+      setLogEventType(logPath);
+      applied.push(`${logPath}: set event_type`);
+      continue;
+    }
+
+    if (action === "normalize_log_context") {
+      normalizeLogContext(logPath);
+      applied.push(`${logPath}: normalized context`);
+      continue;
+    }
+
     if (nonInteractive) {
       throw new Error(`Unsupported repair action ${action}`);
     }
@@ -147,6 +161,7 @@ function describeRepair(repair) {
   const action = repair.action;
   const field = repair.params?.field;
   const ticketPath = repair.ticket_path ?? "";
+  const logPath = repair.log_path ?? "";
   const value = repair.params?.value;
 
   if (action === "add_sections") {
@@ -185,6 +200,12 @@ function describeRepair(repair) {
   if (action === "normalize_verification_commands") {
     return ["Normalize verification.commands to strings, dropping invalid entries.", null];
   }
+  if (action === "set_log_event_type") {
+    return [`Set event_type in ${logPath} based on the log entry shape.`, null];
+  }
+  if (action === "normalize_log_context") {
+    return [`Normalize context in ${logPath} and synthesize a minimal fallback when required.`, null];
+  }
   return ["Apply repair", value];
 }
 
@@ -336,3 +357,56 @@ function normalizeVerificationCommands(ticketPath) {
   };
   writeTicket(ticketPath, frontMatter, body);
 }
+
+function setLogEventType(logPath) {
+  updateJsonl(logPath, (entry) => {
+    entry.event_type = inferLogEventType(entry);
+    return entry;
+  });
+}
+
+function normalizeLogContext(logPath) {
+  updateJsonl(logPath, (entry) => {
+    if (!Array.isArray(entry.context)) {
+      entry.context = [];
+    }
+    entry.context = entry.context.map((value) => String(value).trim()).filter(Boolean);
+
+    const machineEntry = entry.written_by === "tickets" || entry.machine === true;
+    const eventType = inferLogEventType(entry);
+    if (entry.event_type !== eventType) {
+      entry.event_type = eventType;
+    }
+    if (machineEntry && eventType === "work" && entry.context.length === 0) {
+      entry.context = buildFallbackContext(entry);
+    }
+    return entry;
+  });
+}
+
+function buildFallbackContext(entry) {
+  const items = [];
+  if (typeof entry.created_from === "string" && entry.created_from.trim()) {
+    items.push(`Handoff from parent ticket ${entry.created_from.trim()}.`);
+  }
+  if (typeof entry.summary === "string" && entry.summary.trim()) {
+    items.push(`Recovered from summary: ${entry.summary.trim()}`);
+  }
+  if (items.length === 0) {
+    items.push("Recovered context was unavailable during automated repair.");
+  }
+  return items;
+}
+
+function inferLogEventType(entry) {
+  if (typeof entry.summary === "string" && /^Status (changed|reaffirmed)\b/.test(entry.summary)) {
+    return "status";
+  }
+  return "work";
+}
+
+function updateJsonl(logPath, updateEntry) {
+  const entries = readJsonl(logPath);
+  const content = entries.map((entry) => JSON.stringify(updateEntry(entry))).join("\n");
+  fs.writeFileSync(logPath, `${content}\n`);
+}

package/src/lib/util.js

@@ -49,7 +49,11 @@ export function parseIso(value) {
   if (typeof value !== "string") {
     return null;
   }
-  const ts = Date.parse(value);
+  const basicMatch = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\.\d+)?Z$/.exec(value);
+  const normalized = basicMatch
+    ? `${basicMatch[1]}-${basicMatch[2]}-${basicMatch[3]}T${basicMatch[4]}:${basicMatch[5]}:${basicMatch[6]}${basicMatch[7] ?? ""}Z`
+    : value;
+  const ts = Date.parse(normalized);
   return Number.isNaN(ts) ? null : new Date(ts);
 }
 

package/src/lib/validation.js

@@ -360,6 +360,7 @@ export function validateRunLog(logPath, machineStrictDefault) {
     const loc = `${logPath}:${idx + 1}`;
     const machineEntry =
       machineStrictDefault || entry.written_by === "tickets" || entry.machine === true;
+    let eventType = null;
 
     for (const required of ["ts", "run_started", "actor_type", "actor_id", "summary"]) {
       if (!(required in entry)) {
@@ -372,6 +373,24 @@ export function validateRunLog(logPath, machineStrictDefault) {
       }
     }
 
+    if (!("event_type" in entry)) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "LOG_EVENT_TYPE_MISSING",
+        message: "event_type missing",
+        log: loc,
+      });
+    } else if (!["status", "work"].includes(entry.event_type)) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "LOG_EVENT_TYPE_INVALID",
+        message: "event_type must be status|work",
+        log: loc,
+      });
+    } else {
+      eventType = entry.event_type;
+    }
+
     if (!("version" in entry)) {
       issues.push({
         severity: machineEntry ? "error" : "warning",
@@ -459,6 +478,43 @@ export function validateRunLog(logPath, machineStrictDefault) {
       });
     }
 
+    if ("context" in entry) {
+      if (!Array.isArray(entry.context)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "CONTEXT_INVALID",
+          message: "context must be a list of strings",
+          log: loc,
+        });
+      } else {
+        if (machineEntry && eventType === "work" && entry.context.length === 0) {
+          issues.push({
+            severity: "error",
+            code: "CONTEXT_EMPTY",
+            message: "context must contain at least one item for machine-written work logs",
+            log: loc,
+          });
+        }
+        for (const item of entry.context) {
+          if (typeof item !== "string" || !item.trim()) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "CONTEXT_ENTRY_INVALID",
+              message: "context entries must be non-empty strings",
+              log: loc,
+            });
+          }
+        }
+      }
+    } else if (machineEntry && eventType === "work") {
+      issues.push({
+        severity: "error",
+        code: "CONTEXT_MISSING",
+        message: "context required for machine-written work logs",
+        log: loc,
+      });
+    }
+
     if (machineEntry && entry.written_by !== "tickets" && entry.machine !== true) {
       issues.push({
         severity: "error",

package/src/release-status.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+function packageRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function runGit(args) {
+  const result = spawnSync("git", args, {
+    cwd: packageRoot(),
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed`);
+  }
+  return result.stdout.trim();
+}
+
+export function summarizeReleaseStatus({
+  packageName,
+  currentVersion,
+  headCommit,
+  dirty,
+  latestRelease,
+}) {
+  const messages = [];
+  const publishedVersion = latestRelease?.version ?? "unknown";
+  const publishedCommit = latestRelease?.commit ?? "unknown";
+  const sameCommit = latestRelease ? headCommit === latestRelease.commit : false;
+  const sameVersion = latestRelease ? currentVersion === latestRelease.version : false;
+
+  if (!latestRelease) {
+    messages.push("No published release is recorded yet.");
+  } else if (sameCommit && sameVersion && !dirty) {
+    messages.push("HEAD matches the latest recorded npm release.");
+  } else {
+    if (!sameCommit) {
+      messages.push(`HEAD (${headCommit}) is ahead of the latest recorded release commit (${publishedCommit}).`);
+    }
+    if (!sameVersion) {
+      messages.push(
+        `Package version (${currentVersion}) differs from the latest recorded release version (${publishedVersion}).`,
+      );
+    } else if (!sameCommit) {
+      messages.push("Package version has not changed since the latest recorded npm release.");
+    }
+    if (dirty) {
+      messages.push("Working tree has uncommitted changes.");
+    }
+  }
+
+  let recommendation;
+  if (!latestRelease) {
+    recommendation = "Record the first published release after npm publish.";
+  } else if (dirty) {
+    recommendation = "Commit or discard local changes before deciding whether to publish.";
+  } else if (!sameCommit && sameVersion) {
+    recommendation = "If this work should ship, bump the package version before publishing.";
+  } else if (!sameCommit && !sameVersion) {
+    recommendation = "If tests and docs are ready, HEAD is a plausible publish candidate.";
+  } else {
+    recommendation = "No publish action is indicated by release provenance alone.";
+  }
+
+  return {
+    packageName,
+    currentVersion,
+    headCommit,
+    dirty,
+    latestRelease,
+    messages,
+    recommendation,
+  };
+}
+
+export function loadReleaseStatus() {
+  const root = packageRoot();
+  const packageJson = readJson(path.join(root, "package.json"));
+  const history = readJson(path.join(root, "release-history.json"));
+  const releases = Array.isArray(history.releases) ? history.releases : [];
+  const latestRelease = releases.length > 0 ? releases[releases.length - 1] : null;
+  const headCommit = runGit(["rev-parse", "--short", "HEAD"]);
+  const dirty = runGit(["status", "--short"]).length > 0;
+
+  return summarizeReleaseStatus({
+    packageName: packageJson.name,
+    currentVersion: packageJson.version,
+    headCommit,
+    dirty,
+    latestRelease,
+  });
+}
+
+export function formatReleaseStatus(status) {
+  const lines = [
+    `Package: ${status.packageName}`,
+    `Current version: ${status.currentVersion}`,
+    `Current HEAD: ${status.headCommit}`,
+    `Working tree dirty: ${status.dirty ? "yes" : "no"}`,
+  ];
+
+  if (status.latestRelease) {
+    lines.push(`Latest recorded npm release: ${status.latestRelease.version}`);
+    lines.push(`Latest recorded release commit: ${status.latestRelease.commit}`);
+    if (status.latestRelease.date) {
+      lines.push(`Latest recorded release date: ${status.latestRelease.date}`);
+    }
+  } else {
+    lines.push("Latest recorded npm release: none");
+  }
+
+  lines.push("");
+  lines.push("Status:");
+  for (const message of status.messages) {
+    lines.push(`- ${message}`);
+  }
+  lines.push(`- Recommendation: ${status.recommendation}`);
+  return `${lines.join("\n")}\n`;
+}
+
+async function main() {
+  try {
+    const status = loadReleaseStatus();
+    process.stdout.write(formatReleaseStatus(status));
+    process.exitCode = 0;
+  } catch (error) {
+    process.stderr.write(`${String(error.message ?? error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await main();
+}