esedre 0.1.8 → 0.1.9

package/README.md

@@ -8,7 +8,7 @@
 
 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE)
 [![Tests](https://img.shields.io/badge/Tests-100%25%20Passing-emerald.svg)](tests/)
-[![Website: www.arwam.com](https://img.shields.io/badge/Website-www.arwam.com-cyan.svg)](https://www.arwam.com)
+[![Website: arwam.com](https://img.shields.io/badge/Website-arwam.com-cyan.svg)](https://arwam.com)
 
 ---
 
@@ -115,10 +115,10 @@ Core day-to-day workflow commands for scoping, viewing, planning, and verifying
 | `list` | `ese list [-p\|--project <code\|all>] [-s\|--status <status>] [-t\|--type <type>] [--json]` | List roadmap tickets with optional filters. Defaults to the active project. |
 | `get` | `ese get <id> [--json]` | View ticket specifications, feature breakdown, comments, and SHA-1 hash. |
 | `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>]` | Create a new ticket with auto-sequential ID. Title strictly capped at 48 chars. |
+| `create` | `ese create --title "..." [-p\|--project <code>] [-t\|--type <type>] [--detail "<md>"] [--file <path>]` | Create a new ticket with auto-sequential ID and optional specification markdown. Title strictly capped at 48 chars. |
 | `update` | `ese update <id> [-s\|--status <status>] [-t\|--type <type>] [--title "..."] [--last-hash <h>]` | Update ticket status, type, or title with optimistic concurrency protection. |
 | `comment` | `ese comment <id> ["<text>"] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
-| `snapshot` | `ese snapshot [--project <code>] [--json]` | Generate lean projection `.esedre/snapshot.json` for zero-latency agent context. |
+| `snapshot`, `refresh` | `ese snapshot [--project <code>] [--json]` | Generate or refresh projection `.esedre/snapshot.json` for zero-latency agent context. |
 | `projects` | `ese projects [--json]` | List registered projects within authorized scope. |
 
 ### Service Daemon Commands
@@ -186,7 +186,7 @@ To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any
 - `esedre_list_tickets`: List tickets with optional project, status, category, or search filter.
 - `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, 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).
+- `esedre_create_ticket`: Mint new roadmap tickets with project code validation (up to 8 chars) and optional specification detail markdown.
 - `esedre_update_ticket`: Modify status, title, complexity, or effort with optimistic concurrency (`lastHash`).
 - `esedre_add_comment`: Append developer or LLM agent verification notes.
 
@@ -283,4 +283,4 @@ npm run build
 
 ## 📄 License
 
-[Mozilla Public License 2.0 (MPL-2.0)](LICENSE) © [ARWAM](https://www.arwam.com)
+[Mozilla Public License 2.0 (MPL-2.0)](LICENSE) © [ARWAM](https://arwam.com)

package/dist/esedre.mjs

@@ -9,7 +9,7 @@ import fs3 from "node:fs";
 import path3 from "node:path";
 
 // src/types.ts
-var CURRENT_ESEDRE_VERSION = "0.1.8";
+var CURRENT_ESEDRE_VERSION = "0.1.9";
 var EsedreConflictError = class extends Error {
   constructor(ticketId, currentHash, lastHash) {
     super(
@@ -1428,7 +1428,62 @@ ${formattedList}`
       projectId: targetLoc.project.id,
       project: targetLoc.project.code
     };
-    const detailMd = `# Ticket #${nextId}: ${meta.title}
+    const rawDetail = (input.detailMarkdown || input.detail)?.trim();
+    let detailMd;
+    if (rawDetail) {
+      if (/^#\s+[^\n]+/m.test(rawDetail)) {
+        let processed = rawDetail.replace(/^#\s+[^\n]+/m, `# Ticket #${nextId}: ${meta.title}`);
+        if (!/\*\*(?:Type|Category)\*\*:/i.test(processed)) {
+          const metaBlock = `
+**Category**: ${meta.category}  
+**Complexity**: ${meta.complexity}  
+**Estimated Effort**: ${meta.estimatedEffort}  
+`;
+          processed = processed.replace(/^(# Ticket[^\n]+\n)/m, `$1${metaBlock}`);
+        }
+        if (!/(?:##|###)\s*(?:Summary|Rationale)/i.test(processed)) {
+          const summaryBlock = `
+### Summary
+${input.summary || "Summary to be defined."}
+`;
+          processed = processed.replace(/^((?:# Ticket[^\n]+\n)(?:\*\*[^\n]+\n)*)/m, `$1${summaryBlock}`);
+        }
+        detailMd = processed.endsWith("\n") ? processed : `${processed}
+`;
+      } else {
+        const hasSummary = /(?:##|###)\s*(?:Summary|Rationale)/i.test(rawDetail);
+        const hasBreakdown = /(?:##|###)\s*Feature Breakdown/i.test(rawDetail);
+        let body = "";
+        if (!hasSummary) {
+          body += `### Summary
+${input.summary || "Summary to be defined."}
+
+`;
+        }
+        if (!hasBreakdown && !rawDetail.startsWith("#")) {
+          body += `### Feature Breakdown
+${rawDetail}
+
+### Technical Details & Architecture
+- Architecture specifications to be documented.
+
+### Open Questions & Decisions
+- None recorded at initialization.
+`;
+        } else {
+          body += `${rawDetail}
+`;
+        }
+        detailMd = `# Ticket #${nextId}: ${meta.title}
+**Category**: ${meta.category}  
+**Complexity**: ${meta.complexity}  
+**Estimated Effort**: ${meta.estimatedEffort}  
+
+${body.trim()}
+`;
+      }
+    } else {
+      detailMd = `# Ticket #${nextId}: ${meta.title}
 **Category**: ${meta.category}  
 **Complexity**: ${meta.complexity}  
 **Estimated Effort**: ${meta.estimatedEffort}  
@@ -1446,6 +1501,7 @@ ${input.summary || "Summary to be defined."}
 ### Open Questions & Decisions
 - None recorded at initialization.
 `;
+    }
     writeSafeFile(path3.join(ticketDir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
     writeSafeFile(path3.join(ticketDir, "detail.md"), detailMd);
     const created = await this.getTicket(`${targetLoc.project.code}-${nextId}`);
@@ -2066,6 +2122,7 @@ Status: ${ticket.meta.status}`;
             complexity: { type: "string", description: "Complexity (e.g. Low, Medium, High)" },
             effort: { type: "string", description: "Estimated effort (e.g. 2.0 - 4.0 hours)" },
             summary: { type: "string", description: "Initial feature summary" },
+            detail: { type: "string", description: "Initial specification, feature breakdown, or technical detail markdown" },
             author: { type: "string", description: "Submitting author name" }
           },
           required: ["title"]
@@ -2156,6 +2213,8 @@ Status: ${ticket.meta.status}`;
           complexity: args.complexity,
           estimatedEffort: args.effort,
           summary: args.summary,
+          detail: args.detail || args.detailMarkdown,
+          detailMarkdown: args.detailMarkdown || args.detail,
           submittedBy: args.author || "Agent"
         });
         return created;
@@ -2804,6 +2863,14 @@ exit /b %ERRORLEVEL%
 `;
 var WRAPPER_PS1 = `# Esedre Autonomous Ticketing & Project Planning Engine Wrapper (PowerShell)
 $ErrorActionPreference = "Stop"
+
+# Ensure UTF-8 console output and pipeline encoding on Windows
+try {
+    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    [Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+    $OutputEncoding = [System.Text.Encoding]::UTF8
+} catch {}
+
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 
 if (Get-Command "ese" -ErrorAction SilentlyContinue) {
@@ -2867,6 +2934,12 @@ REM Ese CLI short alias wrapper for Esedre (Windows CMD)
 call "%~dp0esedre.cmd" %*
 `;
 var ESE_WRAPPER_PS1 = `# Ese CLI short alias wrapper for Esedre (PowerShell)
+try {
+    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    [Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+    $OutputEncoding = [System.Text.Encoding]::UTF8
+} catch {}
+
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 & (Join-Path $scriptDir "esedre.ps1") @args
 exit $LASTEXITCODE
@@ -2878,7 +2951,9 @@ exec "$DIR/esedre" "$@"
 `;
 var HISTORIC_SKILL_HASHES = [
   "8611116c276fdfb598b965c716b251ce7c77c7f7",
-  "05f129fb6e06a18df00215af105567abcbf0bc67"
+  "05f129fb6e06a18df00215af105567abcbf0bc67",
+  "5d330ecf8fc96f383946e0351adb60378afa70f0",
+  "23716c9db561e52e5115dc364fe154d3a7bc1e23"
 ];
 var ESEDRE_SKILL_TEMPLATE = `---
 name: esedre
@@ -2889,9 +2964,18 @@ description: Tooling and workflow reference for interacting with the Esedre deve
 
 Esedre is the developer ticketing and LLM coding partner coordination platform. The engine codebase resides in the standalone repository \`aellinsar/esedre\` (\`../esedre\`), and operates on decoupled ticket repositories (such as \`aellinsar/esedre-data\` configured in \`.esedre/esedre.json\`). Interact with tickets via in-repo shell wrappers in \`.esedre/\` (\`.esedre/ese\`), or the global \`ese\` CLI.
 
-## 0. Instant Zero-Latency Context (\`.esedre/snapshot.json\`)
+## 0. Authoritative Ingress Hierarchy & Zero-Latency Context (\`.esedre/snapshot.json\`)
 
-Before querying tickets over the network or CLI, check \`.esedre/snapshot.json\` in the workspace root. It provides a local read-only projection containing all active and completed tickets, summaries, implementation plans, revision numbers, completion dates (\`completedAt\`), and staleness metrics (\`daysSinceUpdate\`).
+All ticket discovery, inspection, and state management strictly follow this positive ingress hierarchy:
+
+1. **Step 1 (Default for Read-Only Inspection) - Local Snapshot Projection**:
+   Always read \`.esedre/snapshot.json\` in the workspace root first. It provides an immediate, zero-latency local projection containing all active and completed tickets, summaries, implementation plans, revision numbers, completion dates (\`completedAt\`), and staleness metrics (\`daysSinceUpdate\`).
+2. **Step 2 (Dynamic Queries & State Mutations) - Esedre MCP Tools**:
+   Use first-class MCP tools when active in the session (\`esedre_list_tickets\`, \`esedre_get_ticket\`, \`esedre_get_plan\`, \`esedre_save_plan\`, \`esedre_update_ticket\`, \`esedre_add_comment\`).
+3. **Step 3 (Terminal & Script Fallback) - In-Repo CLI Wrapper**:
+   Use \`.esedre/ese\` (\`.esedre/ese get\`, \`.esedre/ese plan\`, \`.esedre/ese update\`, \`.esedre/ese snapshot\`, \`.esedre/ese refresh\`).
+4. **Storage Boundary**:
+   Backing ticket hubs (such as \`esedre-data\`) represent data storage managed by the engine. All agent interactions with roadmap tickets flow through the snapshot projection, MCP tools, or CLI wrappers.
 
 ## 1. Model Context Protocol (MCP) Tools
 
@@ -2903,7 +2987,7 @@ When Esedre MCP is active in your agent session (\`.agents/mcp_config.json\`), u
 | \`esedre_get_ticket\` | Full specification, summary, comments, revision & sha1 | \`ticketId\` (numeric e.g. \`96\` or compound e.g. \`Profe-96\`) |
 | \`esedre_get_plan\` | Active implementation plan markdown | \`ticketId\` (numeric or compound) |
 | \`esedre_save_plan\` | Save implementation plan markdown with OCC | \`ticketId\`, \`planMarkdown\`, \`lastHash\` |
-| \`esedre_create_ticket\` | Mint a new ticket with auto sequential ID | \`title\` (max 48 chars), \`type\`, \`project\`, \`effort\`, \`summary\` |
+| \`esedre_create_ticket\` | Mint a new ticket with auto sequential ID | \`title\` (max 48 chars), \`type\`, \`project\`, \`effort\`, \`summary\`, \`detail\` |
 | \`esedre_update_ticket\` | Update ticket attributes with OCC | \`ticketId\`, \`status\`, \`type\`, \`title\`, \`complexity\`, \`effort\`, \`inDevelopment\`, \`featureFlag\`, \`lastHash\` |
 | \`esedre_add_comment\` | Append developer or agent comment | \`ticketId\`, \`text\`, \`author\` |
 
@@ -2930,7 +3014,7 @@ Both \`esedre\` and \`ese\` work interchangeably:
 
 ### Create a Ticket
 \`\`\`bash
-.esedre/ese create --title "..." [-p|--project <code>] [-t|--type Feature] [--complexity Medium] [--effort "2.0 - 4.0 hours"] [--json]
+.esedre/ese create --title "..." [-p|--project <code>] [-t|--type Feature] [--complexity Medium] [--effort "2.0 - 4.0 hours"] [--detail "<md>"] [--file <path>] [--json]
 \`\`\`
 
 ### Update Ticket Status & Attributes
@@ -2949,6 +3033,7 @@ Both \`esedre\` and \`ese\` work interchangeably:
 ### Regenerate Snapshot
 \`\`\`bash
 .esedre/ese snapshot
+.esedre/ese refresh
 \`\`\`
 
 ### Server Lifecycle & Daemon Management
@@ -3300,6 +3385,18 @@ function configureWorkspace(targetDir, options = {}) {
   };
 }
 var initWorkspace = configureWorkspace;
+var ESEDRE_HUB_AGENTS_TEMPLATE = `# Agent Guidelines: esedre-data
+
+## 1. Role & Storage Boundary
+- **Backing Storage Repository**: \`esedre-data\` is a dedicated, decoupled data hub storing raw tickets, metadata manifests, and implementation plans managed by the Esedre engine.
+- **Authorized Ingress Channels**: Ticket discovery, read-only inspection, status updates, and plan authoring strictly ingress through the Esedre application layer in consuming project workspaces:
+  1. **Local Workspace Snapshot**: Check the consuming workspace's \`.esedre/snapshot.json\` first for instant, zero-latency read access to ticket summaries, plans, and statuses.
+  2. **Esedre MCP Tools**: Use \`esedre_get_ticket\`, \`esedre_list_tickets\`, \`esedre_get_plan\`, \`esedre_save_plan\`, and \`esedre_update_ticket\`.
+  3. **Esedre CLI**: Execute \`.esedre/ese get <id>\`, \`.esedre/ese list\`, or \`.esedre/ese plan\` from within the relevant project workspace.
+
+## 2. Ingress Redirection Protocol
+When inspecting or managing tickets for any project (such as \`Profe\`, \`Esedre\`, or \`Alce\`), navigate to that project's workspace and utilize its local \`.esedre/snapshot.json\`, Esedre MCP tools, or \`.esedre/ese\` CLI wrapper.
+`;
 function initHub(targetDir) {
   const resolved = path6.resolve(targetDir);
   if (!fs6.existsSync(resolved)) {
@@ -3317,9 +3414,16 @@ function initHub(targetDir) {
     fs6.writeFileSync(projectsJsonPath, "[]\n", "utf-8");
     projectsJsonCreated = true;
   }
+  const agentsMdPath = path6.join(resolved, "AGENTS.md");
+  let agentsMdCreated = false;
+  if (!fs6.existsSync(agentsMdPath)) {
+    fs6.writeFileSync(agentsMdPath, ESEDRE_HUB_AGENTS_TEMPLATE, "utf-8");
+    agentsMdCreated = true;
+  }
   return {
     projectsJsonCreated,
     projectsDirCreated,
+    agentsMdCreated,
     hubDir: resolved.replace(/\\/g, "/")
   };
 }
@@ -3885,7 +3989,7 @@ ${colors.bold}ROADMAP COMMANDS (Pair Programming & LLM Agents):${colors.reset}
   ${colors.bold}plan${colors.reset}        <id> [--file <path> | --set "<markdown>"] [--last-hash <sha1>] [--json]
                View or update implementation plan with optimistic concurrency control.
 
-  ${colors.bold}create${colors.reset}      --title "..." [-p|--project <code>] [-t|--type <type>] [--complexity <c>] [--effort "<e>"] [--summary "<s>"] [--json]
+  ${colors.bold}create${colors.reset}      --title "..." [-p|--project <code>] [-t|--type <type>] [--complexity <c>] [--effort "<e>"] [--summary "<s>"] [--detail "<md>"] [--file <path>] [--json]
                Mint a new roadmap ticket with sequential numeric ID.
 
   ${colors.bold}update${colors.reset}      <id> [-s|--status <status>] [-t|--type <type>] [--title "..."] [--complexity <c>] [--effort "<e>"] [--in-dev] [--flag <name>] [--last-hash <sha1>] [--force] [--json]
@@ -3894,7 +3998,7 @@ ${colors.bold}ROADMAP COMMANDS (Pair Programming & LLM Agents):${colors.reset}
   ${colors.bold}comment${colors.reset}     <id> ["<text>"] [--text "..."] [--author "..."] [--json]
                Append a research finding, test verification, or note to ticket history.
 
-  ${colors.bold}snapshot${colors.reset}    [--project <code>] [--json]
+  ${colors.bold}snapshot, refresh${colors.reset} [--project <code>] [--json]
                Generate lean read-only projection snapshot (.esedre/snapshot.json) for zero-latency agent context.
 
 ${colors.bold}SERVICE DAEMON COMMANDS:${colors.reset}
@@ -3938,6 +4042,8 @@ ${colors.bold}OPTIONS:${colors.reset}
   -t, --type <type>    Ticket type ('Feature', 'Platform', 'Tools', 'Idea', 'Bug').
   -s, --status <stat>  Ticket status ('Planned', 'In Development', 'Completed', 'Rejected').
   -q, --search <query> Case-insensitive substring search query.
+  --detail "<md>"      Specification markdown for ticket detail during create.
+  --file <path>        Path to markdown file for detail (create) or implementation plan (plan).
   --json              Output raw machine-readable JSON (strongly recommended for autonomous LLM coding agents).
   --last-hash <hash>  Optimistic concurrency control: last known sha1 hash of the ticket from 'get'.
   --force             Bypass optimistic concurrency last-hash conflict checks on writes.
@@ -4450,6 +4556,7 @@ ${colors.bold}Commands:${colors.reset}`);
         }
         return;
       }
+      case "refresh":
       case "snapshot": {
         const projectCode = flags["project"] || discovered.config?.projectCode;
         if (!projectCode) {
@@ -4656,12 +4763,27 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
             content = fs9.readFileSync(filePath, "utf-8");
           }
           await storage.savePlan(id, content, lastHash);
-          console.log(`${colors.green}\u2714 Implementation plan saved for Ticket #${id}${colors.reset}`);
+          if (isJson) {
+            const updated = await storage.getTicket(id);
+            console.log(JSON.stringify({
+              success: true,
+              ticketId: id,
+              project: updated?.projectDescriptor?.code || updated?.meta?.project || "UNASSIGNED",
+              planMarkdown: content,
+              sha1: updated?.sha1 || updated?.meta?.sha1
+            }, null, 2));
+          } else {
+            console.log(`${colors.green}\u2714 Implementation plan saved for Ticket #${id}${colors.reset}`);
+          }
           return;
         }
         const plan = await storage.getPlan(id);
         if (!plan) {
-          console.log(`${colors.dim}No implementation plan found for Ticket #${id}.${colors.reset}`);
+          if (isJson) {
+            console.log(JSON.stringify({ ticketId: id, planMarkdown: null }, null, 2));
+          } else {
+            console.log(`${colors.dim}No implementation plan found for Ticket #${id}.${colors.reset}`);
+          }
           return;
         }
         if (isJson) {
@@ -4694,6 +4816,21 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
           console.error(`${colors.red}Error: ${val.error}${colors.reset}`);
           process.exit(1);
         }
+        const detailArg = flags["detail"];
+        const fileArg = flags["file"];
+        let detailMarkdown = detailArg;
+        if (fileArg) {
+          const filePath = path9.resolve(fileArg);
+          if (!fs9.existsSync(filePath)) {
+            if (isJson) {
+              console.error(JSON.stringify({ error: `Detail file "${fileArg}" not found` }));
+            } else {
+              console.error(`${colors.red}Error: Detail file "${fileArg}" not found.${colors.reset}`);
+            }
+            process.exit(1);
+          }
+          detailMarkdown = fs9.readFileSync(filePath, "utf-8");
+        }
         const created = await storage.createTicket({
           title,
           type,
@@ -4702,7 +4839,9 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
           complexity,
           estimatedEffort,
           summary,
-          submittedBy
+          submittedBy,
+          detail: detailMarkdown,
+          detailMarkdown
         });
         if (isJson) {
           console.log(JSON.stringify(created, null, 2));

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "esedre",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Esedre: Developer roadmap, ticketing, and LLM coding partner coordination platform",
-  "homepage": "https://www.arwam.com",
+  "homepage": "https://arwam.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Aellinsar/esedre.git"