esedre 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to Esedre are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-10-15
+
+### Added
+- **TTL-Backed Advisory Ticket Leases (`ese lease`) (Ticket #69)**:
+  - Added ephemeral ticket lease storage (`projects/<Code>/tickets/<id>/lease.json`) providing TTL-backed mutual exclusion across concurrent LLM coding agents, subagents, CLI scripts, and multi-machine sessions without overwriting durable `meta.assignee`.
+  - Added `ese lease [claim|renew|release|list]` CLI commands (and top-level aliases `ese claim`, `ese renew`, `ese release`, `ese leases`), plus `--leased` and `--leased-by <holder>` filters on `ese list`.
+  - Added `esedre_claim_ticket`, `esedre_renew_lease`, `esedre_release_ticket`, and `esedre_list_leases` MCP tools with lease conflict detection (`EsedreLeaseConflictError` / JSON-RPC `-32001`).
+  - Added `activeLeases` summary array and per-ticket `lease` metadata to `.esedre/snapshot.json`.
+- **First-Class `Task Breakdown`, `Fix Breakdown`, and `Implementation Breakdown` Heading Aliases (Ticket #71)**:
+  - Extended `FilesystemStorageAdapter.parseDetailMarkdown` and `planParser.ts` to recognize `### Task Breakdown`, `### Fix Breakdown`, and `### Implementation Breakdown` as first-class aliases alongside `### Feature Breakdown`.
+  - Preserved indented sub-bullets under numbered breakdown items instead of prematurely terminating the breakdown list.
+  - Documented canonical `detail.md` section headings and bullet conventions in `ESEDRE_SKILL_TEMPLATE` (`.agents/skills/esedre/SKILL.md`).
+- **Windows PowerShell & CMD CLI Invocation Documentation and Lease Flag Parity (Ticket #72)**:
+  - Updated generated `.agents/skills/esedre/SKILL.md` to explicitly document `.\.esedre\ese.cmd` and `.\.esedre\ese.ps1` for Windows PowerShell/CMD environments alongside POSIX `.esedre/ese`.
+  - Standardized `--worker-id` / `--by`, `--system`, and `release --status` / `--notes` flags across CLI and MCP lease tools.
+- **Global Antigravity MCP Configuration Auto-Registration (Ticket #73)**:
+  - Extended `setupMcpConfig` (`ese init`, `ese upgrade`, `ese configure`) to automatically register and maintain the `esedre` MCP entry in `~/.gemini/config/mcp_config.json` with a resilient launcher that prefers `.esedre\esedre.cmd` when inside an initialized workspace and falls back to global `ese mcp`.
+- **Variadic Multi-Ticket Lookup in `ese get <id...>` (Ticket #75)**:
+  - Extended `ese get <id...> [--json]` to accept one or more positional ticket IDs, returning a single object for 1 ID, a JSON array when multiple IDs are requested with `--json`, or divider-separated human-readable summaries in text mode.
+- **`lastTicketId` High-Water Mark in `.esedre/snapshot.json` (Ticket #77)**:
+  - Added `lastTicketId` alongside `totalTickets` in the root of `.esedre/snapshot.json` so agents can inspect the highest allocated numeric ticket ID even when historical ticket numbers were skipped or removed.
+
+### Fixed
+- **`detail.md` Combined Technical Details & Open Questions Section Routing (Ticket #70)**:
+  - Fixed `FilesystemStorageAdapter.parseDetailMarkdown` and `planParser.ts` so `- **Technical Detail**:`, `- **Architecture**:`, and `- **Root Cause**:` bullets under `### Technical Details` or combined `### Technical Detail(s) & Open Questions` headings route to `technicalDetails[]` rather than leaking into `openQuestions[]`.
+- **In-Body `detail.md` Metadata Header Reconciliation on Partial Updates (Ticket #74)**:
+  - Centralized `reconcileDetailMetadataHeaders` in `FilesystemStorageAdapter` so partial metadata updates (`ese update --status`, `--complexity`, `--effort`, `--priority`, `--type`, `--milestone`, `--title`, and `ese lease claim/release`) keep inline metadata headers (both unbulleted `**Key**:` and bulleted `- **Key**:`) at the top of `detail.md` synchronized with `meta.json` and deduplicate redundant header lines.
+- **Duplicate `lease` Command Blocks in `ese --help` Output (Ticket #76)**:
+  - Removed 3 duplicate `lease` command help blocks from `printHelp()` in `bin/esedre.ts`.
+
+## [1.2.0] - 2026-10-09
+
+### Added
+- **MCP Ticket Listing Implementation Plan Hydration (`includePlan` and `hasPlan`) (Ticket #58)**:
+  - Extended `esedre_list_tickets` MCP tool to return `hasPlan: boolean` on all listed tickets, indicating whether an implementation plan exists on disk.
+  - Added optional `includePlan: boolean` parameter to `esedre_list_tickets` to hydrate full `planMarkdown` directly in ticket listings, eliminating redundant sequential `esedre_get_plan` tool calls when agents review multiple active tickets.
+  - Added unit test suite in `tests/mcpServer.test.ts` verifying `hasPlan` and `includePlan` behavior across multiple tickets.
+- **Comment File Input Option for CLI & MCP Tool (Ticket #62)**:
+  - Added `--file <path>` option to `ese comment` CLI command, reading verification notes directly from UTF-8 markdown or text files on disk.
+  - Bypasses Windows `cmd.exe` `%VAR%` parameter expansion and stripping, preserving percent signs (`100%`) and literal characters verbatim.
+  - Added priority precedence for `--file` over inline `--text` and positional arguments, with existence, regular file, and non-empty content validation.
+  - Added parity `file?: string` property to `esedre_add_comment` MCP tool, with automatic local file resolution and relaxed `required: ['ticketId']` schema constraint.
+  - Added comprehensive automated test suite in `tests/cliComment.test.ts` covering error handling, priority precedence, percent preservation, and MCP execution.
+
 ## [1.1.0] - 2026-10-02
 
 ### Added

package/README.md

@@ -41,6 +41,7 @@ LLM coding agents possess extraordinary implementation speed, but face a fundame
 5. **Optimistic Concurrency Control**: SHA-1 content hashing on all tickets and plans, preventing concurrent agents or humans from clobbering each other's edits.
 6. **Local Web Dashboard & Embeddable Component**: Run a visual dashboard with `ese start` to manage tickets in your browser, or embed `<esedre-planner>` into any web app without adding UI framework dependencies to your project.
 7. **Project Milestones & Umbrella Flags**: Group tickets into release deliverables with real-time completion progress and umbrella feature flag propagation.
+8. **Ticket Leases & Multi-Session Mutual Exclusion (`ese lease`)**: Ephemeral TTL-backed ticket leases (`lease.json`) prevent concurrent LLM agents, subagents, or multi-machine sessions from colliding on the same ticket without overwriting durable ticket assignees.
 
 ---
 
@@ -114,16 +115,17 @@ Core day-to-day workflow commands for scoping, viewing, planning, and verifying
 
 | Command | Usage | Description |
 |---|---|---|
-| `list` | `ese list [-p\|--project <code\|all>] [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority>] [-m\|--milestone <name>] [--blocked] [--linked-to <key>] [--json]` | List roadmap tickets with optional filters. Defaults to the active project. |
-| `get` | `ese get <id> [--json]` | View ticket specifications, feature breakdown, comments, links, and SHA-1 hash. |
+| `list` | `ese list [-p\|--project <code\|all>] [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority>] [-m\|--milestone <name>] [--blocked] [--leased] [--leased-by <holder>] [--linked-to <key>] [--json]` | List roadmap tickets with optional filters. Defaults to the active project. |
+| `get` | `ese get <id...> [--json]` | View ticket specifications, feature/task/fix breakdown, comments, links, active lease, and SHA-1 hash for one or more tickets. |
 | `plan` | `ese plan <id> [--set "<markdown>"] [--file <path>] [--last-hash <h>]` | Read or update the active implementation plan markdown. |
 | `create` | `ese create --title "..." [-p\|--project <code>] [-t\|--type <type>] [-P\|--priority <priority>] [-m\|--milestone <name>] [--detail "<md>"] [--file <path>]` | Create a new ticket with auto-sequential ID, optional priority, optional milestone, and specification markdown. Title strictly capped at 48 chars. |
-| `update` | `ese update <id> [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority\|none>] [-m\|--milestone <name\|none>] [--title "..."] [--detail "<md>"] [--file <path>] [--last-hash <h>]` | Update ticket status, type, priority, milestone, title, or specification markdown with optimistic concurrency protection. |
+| `update` | `ese update <id> [-s\|--status <status>] [-t\|--type <type>] [-P\|--priority <priority\|none>] [-m\|--milestone <name\|none>] [--title "..."] [--detail "<md>"] [--file <path>] [--last-hash <h>]` | Update ticket status, type, priority, milestone, title, or specification markdown with optimistic concurrency protection and header sync. |
+| `lease` | `ese lease [claim\|renew\|release\|list] [args...]` | Claim, renew, release, or list TTL-backed advisory ticket leases (aliases: `ese claim`, `ese renew`, `ese release`, `ese leases`). |
 | `link` | `ese link <sourceId> <relation> <targetId> [--author "..."]` | Establish a bi-directional link between two tickets. Relations: `relates-to`, `blocks`, `parent-of`, `duplicates`. |
 | `unlink` | `ese unlink <sourceId> <targetId> [--relation <relation>]` | Remove a bi-directional link between two tickets. |
 | `milestone` | `ese milestone [list\|get\|create\|update\|delete] [args...]` | Manage project milestones and umbrella feature flags with deliverables tracking. |
-| `comment` | `ese comment <id> ["<text>"] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
-| `snapshot`, `refresh` | `ese snapshot [--project <code>] [--json]` | Generate or refresh projection `.esedre/snapshot.json` for zero-latency agent context. |
+| `comment` | `ese comment <id> ["<text>"] [--file <path>] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
+| `snapshot`, `refresh` | `ese snapshot [--project <code>] [--json]` | Generate or refresh projection `.esedre/snapshot.json` (`totalTickets`, `lastTicketId`, `activeLeases`, `tickets`) for zero-latency agent context. |
 | `projects` | `ese projects [--json]` | List registered projects within authorized scope. |
 
 ### Service Daemon Commands
@@ -148,9 +150,9 @@ Commands for repository onboarding, central machine linking, and maintenance:
 | `configure` | `ese configure [add <path> \| remove <code\|path> \| set <k> <v>]` | Inspect or mutate central configuration (`~/.esedre/config.json`). Link external project repositories or data hubs. |
 | `rename-project` | `ese rename-project <oldCode> <newCode> [--name "<name>"]` | Rename a project code across directory storage paths, manifests, and tickets. |
 | `project set` | `ese project set <code> [--name "<name>"]` | Update metadata for an existing project (e.g. display name). |
-| `upgrade` | `ese upgrade [<path>] [--all \| -a] [--force \| -f]` | Upgrade workspace configuration schema, in-repo wrappers, and agent skills across current or all registered workspaces. |
+| `upgrade` | `ese upgrade [<path>] [--all \| -a] [--force \| -f]` | Upgrade workspace configuration schema, in-repo wrappers, workspace and global Antigravity MCP configs (`.agents/mcp.json`, `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json`), and agent skills across current or all registered workspaces, with 24 KB rule size checks. |
 
-> **Human vs LLM Agent Workflows**: Developer Administration commands (`init`, `configure`, `upgrade`) manage system-level repository linking and central machine configuration. They are intended for human developers during initial setup. Autonomous LLM coding partners operate within the authorized workspace scope using Roadmap and Service Daemon commands (`list`, `get`, `plan`, `create`, `update`, `comment`, `snapshot`, `start`, `status`).
+> **Human vs LLM Agent Workflows**: Developer Administration commands (`init`, `configure`, `upgrade`) manage system-level repository linking and central machine configuration. They are intended for human developers during initial setup. Autonomous LLM coding partners operate within the authorized workspace scope using Roadmap and Service Daemon commands (`list`, `get`, `plan`, `create`, `update`, `lease`, `comment`, `snapshot`, `start`, `status`).
 
 #### Linking External Repositories vs Data Hub Projects
 
@@ -199,18 +201,22 @@ To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any
 ```
 
 ### Registered Tools
-- `esedre_list_tickets`: List tickets with optional project, status, type, priority, milestone, isBlocked, linkedTo, or search filter.
-- `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, links, blocker status, and content hash (`sha1`).
+- `esedre_list_tickets`: List tickets with optional project, status, type, priority, milestone, isBlocked, leased, leasedBy, linkedTo, search, or includePlan filter.
+- `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, links, active lease, blocker status, and content hash (`sha1`).
 - `esedre_get_plan` & `esedre_save_plan`: Inspect and update implementation plans with optimistic concurrency (`lastHash`).
 - `esedre_create_ticket`: Mint new roadmap tickets with project code validation (up to 8 chars), optional priority, optional milestone, and specification detail markdown.
-- `esedre_update_ticket`: Modify status, title, type, priority, milestone, complexity, or effort with optimistic concurrency (`lastHash`).
+- `esedre_update_ticket`: Modify status, title, type, priority, milestone, specification detail (`detail`/`detailMarkdown`), complexity, or effort with optimistic concurrency (`lastHash`).
+- `esedre_claim_ticket`: Acquire an exclusive TTL-backed lease on a ticket (`In Development`) with conflict protection (`-32001`).
+- `esedre_renew_lease`: Extend the expiration TTL of an active ticket lease.
+- `esedre_release_ticket`: Release an active ticket lease and optionally transition status (`Completed`, `Planned`, etc.).
+- `esedre_list_leases`: List all active, unexpired ticket leases across authorized projects.
 - `esedre_link_ticket`: Establish a bi-directional link between two tickets (`relates-to`, `blocks`, `parent-of`, `duplicates`).
 - `esedre_unlink_ticket`: Remove a bi-directional relationship between two tickets.
 - `esedre_list_milestones`: List milestones and progress metrics for a project.
 - `esedre_get_milestone`: Retrieve milestone specifications, umbrella feature flag, and member tickets.
 - `esedre_create_milestone`: Create a project milestone with optional umbrella feature flag and target date.
 - `esedre_update_milestone`: Update milestone status, title, description, or umbrella feature flag.
-- `esedre_add_comment`: Append developer or LLM agent verification notes.
+- `esedre_add_comment`: Append developer or LLM agent verification notes with optional file path or inline text.
 
 ### Cross-Project Linked Issues & Dependencies
 
@@ -242,6 +248,15 @@ Esedre introduces first-class milestone management to group related tickets towa
   <img src="https://cdn.jsdelivr.net/npm/esedre/docs/assets/esedre-milestones.png" alt="Esedre Milestones & Deliverables Tracking" width="100%" />
 </p>
 
+### Ticket Leases & Multi-Agent Mutual Exclusion (`ese lease`)
+
+Esedre provides TTL-backed advisory ticket leases (`projects/<Code>/tickets/<id>/lease.json`) so concurrent LLM coding agents, subagents, CLI scripts, or multi-machine sessions can coordinate without colliding on the same ticket:
+
+- **Ephemeral vs. Durable Ownership**: Leases track active real-time execution (`holder`, `system`, `claimedAt`, `expiresAt`, `ttlMinutes`, `branch`, `pid`) without overwriting the ticket's durable `meta.assignee`.
+- **Automatic TTL Expiration & Completion Cleanup**: Leases default to a 60-minute TTL (`--ttl <minutes>`) and are automatically evicted once expired or when a ticket transitions to `Completed` or `Rejected`.
+- **Conflict Protection**: Claiming a ticket already held by another active worker throws `EsedreLeaseConflictError` (CLI exit `1`, MCP JSON-RPC `-32001`, REST HTTP `409 Conflict`) unless `--force` is passed. Re-claiming by the same holder idempotently renews the lease.
+- **CLI & MCP Parity**: Manage leases via `ese lease [claim|renew|release|list]` (or top-level aliases `ese claim`, `ese renew`, `ese release`, `ese leases`) and MCP tools (`esedre_claim_ticket`, `esedre_renew_lease`, `esedre_release_ticket`, `esedre_list_leases`).
+
 ### Resources
 - URI Scheme: `esedre://tickets/{id}` (MIME type: `text/markdown`)