deuk-agent-rule 1.0.13 → 2.2.1

package/bundle/rules/multi-ai-workflow.mdc

@@ -1,55 +1,105 @@
 ---
-description: Handoff format rules for multi-AI workflow
+description: Ticket format rules for multi-AI workflow
 alwaysApply: true
 ---
 
 # Multi-AI Workflow
 
+## HIGHEST PRIORITY RULE (Tone, Documentation & Formatting)
+Never use dramatic, exaggerated, or absolute language. When authoring any document or ticket, you MUST NEVER use expressions that emphasize dramatic effects or imply absolute completeness/perfection. Maintain a strictly factual, calm, dry tone at all times.
+HARD RULE: Never use Markdown word emphasis (bold **, italic *, etc.) in any generated content, including tickets, reports, and chat responses. Keep the text uniformly plain.
+
 ## Before starting work
 
-Before implementation, fixes, or other **substantive** changes to the repo:
+Before implementation, fixes, or other substantive changes to the repo:
 
-1. **Check persisted handoffs** in the locations described in `AGENTS.md` (**Handoff persistence**) — at minimum inspect **`.deuk-agent-handoff/`** and any project-specific internal paths for files related to the current task.
-2. **If `DeukAgentRules/handoff/LATEST.md` exists** (repo root–relative path: rules package cloned as top-level folder `DeukAgentRules`), **read it** before editing code, in addition to step 1.
-3. **Read** matching documents before editing code. If the user **pasted** a handoff in the chat, treat that as primary unless they say to follow on-disk files instead.
-4. Skip the scan only when no handoff locations exist, nothing matches the task, or the user tells you to ignore stored handoffs.
+1. Check persisted tickets in the locations described in AGENTS.md (Ticket persistence) — at minimum inspect .deuk-agent-ticket/ and any project-specific internal paths for files related to the current task.
+2. If .deuk-agent-ticket/TICKET_LIST.md exists, read it before editing code, then open only relevant topic files, in addition to step 1.
+3. Read matching documents before editing code. If the user pasted a ticket in the chat, treat that as primary unless they say to follow on-disk files instead.
+4. Skip the scan only when no ticket locations exist, nothing matches the task, or the user tells you to ignore stored tickets.
 
-## Receiving Handoff from Other Tools
+## Receiving Ticket from Other Tools
 
 When the user pastes a design or plan from another assistant or planning tool:
 
-1. Parse the **handoff format** (see `AGENTS.md`, heading **Handoff format**).
+1. Parse the ticket format (see AGENTS.md, heading Ticket format).
 2. Validate file paths exist before modifying.
 3. Execute changes as specified — do not redesign unless the user asks.
-4. Report back in the same handoff format for further iteration.
+4. Report back in the same ticket format for further iteration.
 
-## Producing Handoff for Other Tools
+## Producing Ticket for Other Tools
 
 When the user asks to prepare work for another tool:
 
-1. Output the handoff format with concrete file paths and change descriptions. When linking handoff files (Markdown `[label](path)` or path citations), use the **full path from the repository root** — never a bare filename.
+1. Output the ticket format with concrete file paths and change descriptions. When linking ticket files (Markdown [label](path) or path citations), use the full path from the repository root — never a bare filename.
 2. Include any constraints or dependencies.
 3. Do not include editor-specific instructions (token budgets, local rule file paths).
-4. When the handoff must **persist** (user asks to save or document it, or it is the canonical next-step spec), **create or update** a Markdown file under **internal implementation documentation** (see `AGENTS.md`, **Handoff persistence**). Prefer **`DeukAgentRules/handoff/LATEST.md`** when this repo has a top-level **`DeukAgentRules/`** folder; otherwise prefer **`.deuk-agent-handoff/`**; `init` gitignores that directory by default. Use the same handoff template; do not place this in public README/landing unless the project explicitly treats this as its internal log. In Markdown links and backtick citations, use the **full path from the repository root** — never a bare filename.
-5. **After writing a persisted handoff**, in chat include **one dedicated line** with the full repo-root-relative path so the next session can open it unambiguously, for example: `Path: \`.deuk-agent-handoff/LATEST.md\`` (same path you used in the file). Repeat the full path in links elsewhere in the same message if helpful.
-6. **Optional first line inside the persisted file** (improves search and skim): `**Handoff (repo-relative):** \`path/from/repo/root.md\`` or the same path in an HTML comment on line 1.
-7. Write persisted handoff **content** in the **user's conversation language** unless they specify another language.
+4. When the ticket must persist (user asks to save or document it, or it is the canonical next-step spec), create or update a Markdown file under internal implementation documentation (see AGENTS.md, Ticket persistence). Prefer the unified .deuk-agent-ticket/ directory for both the index (TICKET_LIST.md) and the topic files; init gitignores .deuk-agent-ticket/ by default. Use the same ticket template; do not place this in public README/landing unless the project explicitly treats this as its internal log. In Markdown links and backtick citations, use the full path from the repository root — never a bare filename.
+5. After writing a persisted ticket, in chat include one dedicated line with the full repo-root-relative path so the next session can open it unambiguously, for example: `Path: .deuk-agent-ticket/sub/container-unified-20260329-120000.md` (same path you used in the file). Repeat the full path in links elsewhere in the same message if helpful.
+6. Optional last line inside the persisted file (improves search and skim): `<!-- Ticket (repo-relative): path/from/repo/root.md -->` on the very last line.
+7. Write persisted ticket content in the user's conversation language (e.g., Korean) unless they specify another language. When using Korean, follow the concise polite style (-요) as described in AGENTS.md.
+
+## Context Preservation (New Issues)
+
+If a new bug, unexpected error, or structural scope change arises during your work, DO NOT attempt to fix it within an endless conversational loop. This degrades the context window.
+Instead, immediately pause and Prioritize Creating a Ticket.
+- Document your findings and create a new .deuk-agent-ticket/ Markdown file.
+- This preserves the context safely and allows transparent multi-agent handoffs or manual rollbacks.
+
+## Custom Slash Commands & Chat Selection UI
+
+If the user's prompt starts with /ticket or /티켓 (with an optional keyword like DeukPack), immediately pause and perform the following:
+1. Fetch & Present (Rich UI Selection): Do not just list text. Automatically read .deuk-agent-ticket/TICKET_LIST.md and present the available open tickets using a Carousel (preferred for compatible agents like Antigravity) or a Markdown Table (fallback).
+   - Carousel Slide Format:
+     ```markdown
+     ## [Ticket ID] Title
+     Group: [Group] | Project: [Project]
+     [Open Ticket](full/path/to/ticket.md)
+     ```
+   - Table Format: Use a clearly formatted table with a separate column for the [Open](path) link.
+2. Read & Contextualize: If the user selects a ticket (by number or clicking the link), immediately read the ticket content and summarize the latest constraints and objectives.
+3. Wait for command: Briefly summarize the active ticket state and wait for the user's next command.
+
+## Selection Box (Agent Chat Interaction)
+
+When the user asks to "choose" or "select" a ticket in the chat, the agent must provide a Selection Box-like experience:
+- Interactive Listing: Provide a numbered listing using the Carousel or Table format above.
+- Direct Linkage: Ensure every listed item has a clickable repository-root-relative path.
+- No CLI output only: Never just point to ticket list CLI output; always render the human-readable selection UI directly in the chat window.
+
+## Persisted ticket vs plan UI (optional)
+
+Some environments show plan-style documents in a separate panel from ordinary Markdown tabs. Behavior varies by product version; when the user wants that experience in Cursor, you may mirror the same ticket body (Ticket format) under the workspace .cursor/plans/ directory using a .plan.md suffix, for example .cursor/plans/deuk-ticket.plan.md or .cursor/plans/deuk-ticket-<topic>.plan.md.
+
+- Canonical copy remains the unified .deuk-agent-ticket/ directory, where both the topic files and the TICKET_LIST.md index pointer are located. The .cursor/plans/ file is an optional duplicate for UI only.
+- Single source of truth: If both exist, keep their content in sync; updating one should update the other in the same turn when possible.
+- Version control: Treat .cursor/plans/ like other local-only tickets unless the team commits plans on purpose — align with .gitignore team policy.
+- For temporary tickets within a single session, write them inline in chat; when repeatedly referenced, shared across multiple agents, or recording risks, convert to an internal .md file. The default storage path is the local .deuk-agent-ticket/ directory; commit to the repository only when requested by the user or following established team conventions.
+
+## Definitive Multi-AI Workflow Cycles
 
-## Persisted handoff vs plan UI (optional)
+The core philosophy of this project dictates a strict separation of 'Reasoning' and 'Execution' via boundary tickets. The definitive workflow cycle is:
 
-Some environments show **plan-style documents** in a separate panel from ordinary Markdown tabs. Behavior varies by product version; when the user wants that experience in **Cursor**, you may **mirror** the same handoff body (Handoff format) under the workspace **`.cursor/plans/`** directory using a **`.plan.md`** suffix, for example `.cursor/plans/deuk-handoff.plan.md` or `.cursor/plans/deuk-handoff-<topic>.plan.md`.
+1. Explore & Plan (Reasoning AI): High-reasoning agents (e.g., Gemini, Claude) explore the codebase, research constraints, and propose an implementation plan. 
+2. Decision (User): The user actively reviews and approves the plan.
+3. Persist Ticket (Handoff): The reasoning agent explicitly writes the approved plan into a .deuk-agent-ticket/ Markdown file.
+4. Execution (Coding AI): IDE execution agents (e.g., Cursor, Windsurf) read the single ticket and strictly execute the code without deviating from the constraints.
+5. Self-Verification (Post-Test Artifact Risk Analysis - MANDATORY): Testing is NOT the final step. After tests are completed, the agent MUST automatically perform a risk analysis on the resulting artifacts (e.g., compiled binaries, generated bundles, final configurations) before reporting to the user:
+   - Do the generated artifacts introduce missing schemas, memory leaks, or unintended coupling?
+   - Are there structural corruptions or unintended side effects in the generated output?
+   - This step must be executed proactively; do not wait for the user to prompt for post-test analysis.
+   - If any risk is identified, document it in the ticket before reporting — do not silently suppress it.
+6. Report & Close: Present the final artifact risk analysis to the user. If verified successful, clear the queue by running npx deuk-agent-rule ticket close --topic <topic>. If unexpected issues arise, revert to Phase 1 (Explore) to amend the ticket.
 
-- **Canonical copy** remains **`.deuk-agent-handoff/`** or **`DeukAgentRules/handoff/LATEST.md`** (portable, matches `AGENTS.md`). The `.cursor/plans/` file is an **optional duplicate** for UI only.
-- **Single source of truth:** If both exist, keep their **content in sync**; updating one should update the other in the same turn when possible.
-- **Version control:** Treat `.cursor/plans/` like other local-only handoffs unless the team commits plans on purpose — align with `.gitignore` team policy.
 
-## Role: Execution
+## Agent Role Awareness
 
-In this workflow the agent's primary role is **execution** — applying concrete changes across multiple files. For design, analysis, or planning, defer to the user's chosen tool when they indicate.
+If you are operating inside an IDE (Cursor, Windsurf), you are strictly in Phase 4 (Execution). Do not attempt to over-engineer or explore completely out of bounds. Follow the Markdown ticket constraints strictly. If large-scale exploration or breaking structural changes are needed during execution, pause and instruct the user to revert to Phase 1 (Explore & Plan).
 
 ## Cost awareness (effective use of context)
 
-- Keep sessions **focused** — one clear objective per session when possible.
-- Prefer **concise** handoffs and replies: concrete paths, decisions, and diffs over narrative padding.
-- For read-only analysis, prefer **summaries** and scoped excerpts over dumping whole files; use lightweight review modes when the product offers them.
-- When producing handoffs for *other* tools, omit local-only tuning hints (see **Producing Handoff** above); still stay efficient in your own responses here.
+- Keep sessions focused — one clear objective per session when possible.
+- Prefer concise tickets and replies: concrete paths, decisions, and diffs over narrative padding.
+- For read-only analysis, prefer summaries and scoped excerpts over dumping whole files; use lightweight review modes when the product offers them.
+- When producing tickets for other tools, omit local-only tuning hints (see Producing Ticket above); still stay efficient in your own responses here.
+- Tone & Style: No hype, no exaggerations, no fake satisfaction. Keep responses entirely factual and calm. Crucially, when authoring any document or ticket, NEVER use expressions that emphasize dramatic effects or imply absolute completeness/perfection. When using Korean, follow the concise polite style (-요).

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "deuk-agent-rule",
-  "version": "1.0.13",
-  "description": "DeukAgentRules: generic AGENTS.md + .cursor rule templates with init/merge CLI (npm name: deuk-agent-rule).",
+  "version": "2.2.1",
+  "type": "module",
+  "description": "DeukAgentRules",
   "keywords": [
     "agents-md",
     "cursor-rules",
@@ -10,7 +11,7 @@
     "claude",
     "windsurf",
     "jetbrains",
-    "handoff",
+    "ticket",
     "deuk-family",
     "deukpack-ecosystem"
   ],

package/scripts/cli-args.mjs

@@ -0,0 +1,43 @@
+export function parseTicketArgs(argv) {
+  const out = { cwd: process.cwd(), dryRun: false, nonInteractive: false, limit: 20 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") out.cwd = argv[++i];
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--non-interactive") out.nonInteractive = true;
+    else if (a === "--topic") out.topic = argv[++i];
+    else if (a === "--group") out.group = argv[++i];
+    else if (a === "--project") out.project = argv[++i];
+    else if (a === "--content") out.content = argv[++i];
+    else if (a === "--from") out.from = argv[++i];
+    else if (a === "--ref") out.ref = argv[++i];
+    else if (a === "--limit") out.limit = Number(argv[++i]);
+    else if (a === "--latest") out.latest = true;
+    else if (a === "--path-only") out.pathOnly = true;
+    else if (a === "--print-content") out.printContent = true;
+    else if (a === "--all") out.all = true;
+    else if (a === "--status") out.status = argv[++i];
+  }
+  return out;
+}
+
+export function parseArgs(argv) {
+  const out = { cwd: process.cwd(), dryRun: false, backup: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") out.cwd = argv[++i];
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--backup") out.backup = true;
+    else if (a === "--non-interactive") out.nonInteractive = true;
+    else if (a === "--interactive") out.interactive = true;
+    else if (a === "--tag") out.tag = argv[++i];
+    else if (a === "--marker-begin") out.markerBegin = argv[++i];
+    else if (a === "--marker-end") out.markerEnd = argv[++i];
+    else if (a === "--agents") out.agents = argv[++i];
+    else if (a === "--rules") out.rules = argv[++i];
+    else if (a === "--cursorrules") out.cursorrules = argv[++i];
+    else if (a === "--append-if-no-markers") out.appendIfNoMarkers = true;
+    else if (a === "-h" || a === "--help") out.help = true;
+  }
+  return out;
+}

package/scripts/cli-init-commands.mjs

@@ -0,0 +1,65 @@
+import { join } from "path";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolveMarkers, resolveCursorrulesMarkers, applyAgents, applyRules, applyCursorrules, readBundleAgents } from "./merge-logic.mjs";
+import { ensureTicketDirAndGitignore } from "./cli-init-logic.mjs";
+import { loadInitConfig, writeInitConfig } from "./cli-prompts.mjs";
+
+export async function runInit(opts, bundleRoot) {
+  const markers = resolveMarkers(opts);
+  const agentsResult = applyAgents({
+    targetPath: join(opts.cwd, "AGENTS.md"),
+    bundleContent: readBundleAgents(bundleRoot),
+    markers, flavor: "init",
+    appendIfNoMarkers: opts.appendIfNoMarkers,
+    dryRun: opts.dryRun, backup: opts.backup,
+    agentsMode: opts.agents || "inject"
+  });
+  console.log(`AGENTS.md: ${agentsResult.action} (${agentsResult.mode || ""})`);
+
+  const ruleActions = applyRules({
+    bundleRulesDir: join(bundleRoot, "rules"),
+    targetRulesDir: join(opts.cwd, ".cursor", "rules"),
+    rulesMode: opts.rules || "prefix",
+    dryRun: opts.dryRun, backup: opts.backup
+  });
+  ruleActions.forEach(r => console.log(`rule ${r.action}: ${r.dest || r.src}`));
+
+  const crResult = applyCursorrules({
+    bundleRoot, cwd: opts.cwd,
+    markers: resolveCursorrulesMarkers({}),
+    cursorrulesMode: opts.cursorrules || "inject",
+    dryRun: opts.dryRun, backup: opts.backup
+  });
+  console.log(`.cursorrules: ${crResult.action} (${crResult.mode || ""})`);
+
+  ensureTicketDirAndGitignore(opts);
+}
+
+export function runMerge(opts, bundleRoot) {
+  const markers = resolveMarkers(opts);
+  const agentsResult = applyAgents({
+    targetPath: join(opts.cwd, "AGENTS.md"),
+    bundleContent: readBundleAgents(bundleRoot),
+    markers, flavor: "merge",
+    appendIfNoMarkers: opts.appendIfNoMarkers,
+    dryRun: opts.dryRun, backup: opts.backup,
+    agentsMode: opts.agents || "inject"
+  });
+  console.log(`AGENTS.md: ${agentsResult.action} (${agentsResult.mode || ""})`);
+
+  const ruleActions = applyRules({
+    bundleRulesDir: join(bundleRoot, "rules"),
+    targetRulesDir: join(opts.cwd, ".cursor", "rules"),
+    rulesMode: opts.rules || "skip",
+    dryRun: opts.dryRun, backup: opts.backup
+  });
+  ruleActions.forEach(r => console.log(`rule ${r.action}: ${r.dest || r.src}`));
+
+  const crResult = applyCursorrules({
+    bundleRoot, cwd: opts.cwd,
+    markers: resolveCursorrulesMarkers({}),
+    cursorrulesMode: opts.cursorrules || "inject",
+    dryRun: opts.dryRun, backup: opts.backup
+  });
+  console.log(`.cursorrules: ${crResult.action} (${crResult.mode || ""})`);
+}

package/scripts/cli-init-logic.mjs

@@ -0,0 +1,21 @@
+import { existsSync, appendFileSync, writeFileSync, mkdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { TICKET_DIR_NAME } from "./cli-ticket-logic.mjs";
+
+const GITIGNORE_TICKET_MARKER = "# deuk-agent-rule: ticket directory (local, not committed by default)";
+
+export function ensureTicketDirAndGitignore(opts) {
+  const ticketPath = join(opts.cwd, TICKET_DIR_NAME);
+  const gitignorePath = join(opts.cwd, ".gitignore");
+  const ignoreLine = TICKET_DIR_NAME + "/";
+
+  if (opts.dryRun) return;
+
+  mkdirSync(ticketPath, { recursive: true });
+
+  let gi = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+  if (!gi.includes(ignoreLine)) {
+    const block = "\n" + GITIGNORE_TICKET_MARKER + "\n" + ignoreLine + "\n";
+    appendFileSync(gitignorePath, block, "utf8");
+  }
+}

package/scripts/cli-prompts.mjs

@@ -0,0 +1,123 @@
+import { createInterface } from "readline";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const INIT_CONFIG_FILENAME = ".deuk-agent-rule.config.json";
+const INIT_CONFIG_VERSION = 1;
+
+export async function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+export async function askYesNo(question, defaultYes = true) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = (await ask(rl, question + (defaultYes ? " [Y/n]: " : " [y/N]: "))).trim().toLowerCase();
+    if (!ans) return defaultYes;
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export async function selectOne(rl, prompt, choices) {
+  console.log("\n" + prompt);
+  choices.forEach((c, i) => console.log(`  ${i + 1}) ${c.label}`));
+  while (true) {
+    const ans = (await ask(rl, `  Choice [1-${choices.length}]: `)).trim();
+    const idx = parseInt(ans, 10) - 1;
+    if (idx >= 0 && idx < choices.length) return choices[idx].value;
+  }
+}
+
+export async function selectMany(rl, prompt, choices) {
+  console.log("\n" + prompt + " (comma-separated numbers, or 'all')");
+  choices.forEach((c, i) => console.log(`  ${i + 1}) ${c.label}`));
+  while (true) {
+    const ans = (await ask(rl, `  Choices: `)).trim().toLowerCase();
+    if (ans === "all" || ans === "") return choices.map((c) => c.value);
+    const parts = ans.split(/[,\s]+/).map((s) => parseInt(s, 10) - 1);
+    if (parts.every((i) => i >= 0 && i < choices.length)) return parts.map((i) => choices[i].value);
+  }
+}
+
+export function loadInitConfig(cwd) {
+  const p = join(cwd, INIT_CONFIG_FILENAME);
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8"));
+    if (j.version !== INIT_CONFIG_VERSION) return null;
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+export function writeInitConfig(cwd, opts) {
+  const p = join(cwd, INIT_CONFIG_FILENAME);
+  const body = {
+    version: INIT_CONFIG_VERSION,
+    stack: opts.stack,
+    agentTools: opts.agentTools,
+    agentsMode: opts.agents ?? "inject",
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(p, JSON.stringify(body, null, 2) + "\n", "utf8");
+}
+
+export const STACKS = [
+  { label: "Unity / C#", value: "unity" },
+  { label: "Next.js + C#", value: "nextjs-dotnet" },
+  { label: "Web (React / Vue / general)", value: "web" },
+  { label: "Java / Spring Boot", value: "java" },
+  { label: "Other / skip", value: "other" },
+];
+
+export const AGENT_TOOLS = [
+  { label: "Cursor", value: "cursor" },
+  { label: "GitHub Copilot", value: "copilot" },
+  { label: "Gemini / Antigravity", value: "gemini" },
+  { label: "Claude (Cursor / Claude Code)", value: "claude" },
+  { label: "Windsurf", value: "windsurf" },
+  { label: "JetBrains AI Assistant", value: "jetbrains" },
+  { label: "All of the above", value: "all" },
+  { label: "Other / skip", value: "other" },
+];
+
+export async function runInteractive(opts) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("\nDeukAgentRules init — let's configure your workspace.\n");
+
+    const stack = await selectOne(rl, "What is your primary tech stack?", STACKS);
+    const tools = await selectMany(rl, "Which agent tools do you use?", AGENT_TOOLS);
+
+    const targetAgents = join(opts.cwd, "AGENTS.md");
+    let agentsDefault = "inject";
+    if (!existsSync(targetAgents)) {
+      agentsDefault = "inject"; // will append markers
+      console.log("\n  No AGENTS.md found — will create with markers.");
+    } else {
+      const content = readFileSync(targetAgents, "utf8");
+      const hasMarkers = content.includes("deuk-agent-rule:begin");
+      if (!hasMarkers) {
+        const choice = await selectOne(rl, "AGENTS.md exists but has no markers. How to apply?", [
+          { label: "Append managed block at the end (safe)", value: "inject" },
+          { label: "Overwrite entire AGENTS.md", value: "overwrite" },
+          { label: "Skip AGENTS.md", value: "skip" },
+        ]);
+        agentsDefault = choice;
+      }
+    }
+
+    opts.agents = opts.agents ?? agentsDefault;
+    opts.stack = stack;
+    opts.agentTools = tools;
+
+    console.log("\n  Stack : " + stack);
+    console.log("  Tools : " + (tools.join(", ") || "none"));
+    console.log("  AGENTS: " + opts.agents + "\n");
+  } finally {
+    rl.close();
+  }
+}

package/scripts/cli-ticket-commands.mjs

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { basename, join } from "path";
+import { toSlug, toRepoRelativePath, inferRefTitleAndTopic, resolveReferencedTicketPath } from "./cli-utils.mjs";
+import { TICKET_DIR_NAME, appendTicketEntry, rebuildTicketIndexFromTopicFilesIfNeeded, detectConsumerTicketDir } from "./cli-ticket-logic.mjs";
+
+import { createInterface } from "readline";
+import { selectOne } from "./cli-prompts.mjs";
+
+export async function runTicketCreate(opts) {
+  if (!opts.topic && !opts.ref) throw new Error("ticket create requires --topic or --ref");
+  
+  const inferred = opts.ref ? inferRefTitleAndTopic(opts) : null;
+  const topic = toSlug(opts.topic || inferred?.topic || "ticket");
+  const title = opts.topic || inferred?.title || "ticket";
+  const group = toSlug(opts.group || "sub");
+
+  let path, source;
+  if (opts.ref) {
+    path = resolveReferencedTicketPath(opts);
+    source = "ticket-reference";
+  } else {
+    let body = opts.content ? String(opts.content).replace(/\\n/g, '\n') : "";
+    if (!body && opts.from) body = readFileSync(join(opts.cwd, opts.from), "utf8");
+    const abs = join(opts.cwd, TICKET_DIR_NAME, group, `${topic}-${Date.now()}.md`);
+    mkdirSync(join(opts.cwd, TICKET_DIR_NAME, group), { recursive: true });
+    path = toRepoRelativePath(opts.cwd, abs);
+    const marker = `\n\n<!-- Ticket (repo-relative): ${path} -->\n`;
+    writeFileSync(abs, body.trimEnd() + marker, "utf8");
+    source = "ticket-create";
+  }
+
+  appendTicketEntry(opts.cwd, {
+    id: `ticket_${Date.now()}`,
+    title, topic, group, project: opts.project || "global",
+    createdAt: new Date().toISOString(), path, source
+  }, opts);
+}
+
+export async function runTicketList(opts) {
+  const ticketDir = detectConsumerTicketDir(opts.cwd);
+  if (!ticketDir) {
+    throw new Error("No ticket system found. Please run 'npx deuk-agent-rule init' first.");
+  }
+  const index = rebuildTicketIndexFromTopicFilesIfNeeded(opts.cwd, opts);
+  let rows = index.entries;
+  
+  if (!opts.all) {
+    const targetStatus = opts.status || "open";
+    rows = rows.filter(e => e.status === targetStatus);
+  }
+  
+  if (opts.group) rows = rows.filter(e => e.group === opts.group);
+  if (opts.project) rows = rows.filter(e => e.project === opts.project);
+  
+  console.log("#  STATUS  GROUP       PROJECT     CREATED                  TITLE");
+  rows.slice(0, opts.limit).forEach((e, idx) => {
+    const stat = (e.status === "closed" ? "[x]" : "[ ]").padEnd(7);
+    const safeTitle = String(e.title || e.topic || "").replace(/(\n|\\n)+/g, " ").slice(0, 50);
+    console.log(`${String(idx+1).padEnd(2)} ${stat} ${e.group.padEnd(10)} ${e.project.padEnd(11)} ${e.createdAt.padEnd(24)} ${safeTitle}`);
+  });
+}
+
+import { updateTicketEntryStatus } from "./cli-ticket-logic.mjs";
+
+export async function runTicketClose(opts) {
+  if (!opts.topic && !opts.latest) {
+    if (process.stdout.isTTY) {
+      const index = rebuildTicketIndexFromTopicFilesIfNeeded(opts.cwd, opts);
+      const choices = index.entries
+        .filter(e => e.status !== "closed")
+        .map(e => ({ label: `[${e.group}] ${e.title}`, value: e.topic }));
+      if (choices.length > 0) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+          opts.topic = await selectOne(rl, "Choose a ticket to close:", choices);
+        } finally {
+          rl.close();
+        }
+      } else {
+        throw new Error("No open tickets found to close.");
+      }
+    } else {
+      throw new Error("ticket close requires --topic or --latest");
+    }
+  }
+  opts.status = "closed";
+  const entry = updateTicketEntryStatus(opts.cwd, opts);
+  console.log(`ticket: closed -> ${entry.topic} (${entry.path})`);
+}
+
+export async function runTicketUse(opts) {
+  const index = rebuildTicketIndexFromTopicFilesIfNeeded(opts.cwd, opts);
+  
+  let targetTopic = opts.topic;
+  if (!targetTopic && !opts.latest) {
+    if (process.stdout.isTTY) {
+      const choices = index.entries
+        .map(e => ({ label: `${e.status === 'closed' ? '✓ ' : ''}[${e.group}] ${e.title}`, value: e.topic }));
+      if (choices.length > 0) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+          targetTopic = await selectOne(rl, "Choose a ticket to use:", choices);
+        } finally {
+          rl.close();
+        }
+      }
+    }
+  }
+
+  const found = opts.latest ? index.entries[0] : index.entries.find(e => e.topic.includes(targetTopic));
+  if (!found) throw new Error("No matching ticket found");
+  
+  if (opts.pathOnly) console.log(found.path);
+  else {
+    console.log(`Path: ${found.path}`);
+    if (opts.printContent) console.log("\n" + readFileSync(join(opts.cwd, found.path), "utf8"));
+  }
+}
+
+import { getLegacyMigrationCandidate, parseLegacyTicketMeta } from "./cli-ticket-logic.mjs";
+import { dirname } from "path";
+
+export async function runTicketMigrate(opts) {
+  const candidate = getLegacyMigrationCandidate(opts.cwd);
+  if (!candidate) {
+    console.log("ticket: no legacy LATEST.md migration candidate found");
+    return;
+  }
+
+  const { title, group, project } = parseLegacyTicketMeta(candidate.body);
+  const topic = toSlug(title);
+  const stamp = Date.now();
+  const relPath = join(TICKET_DIR_NAME, group, `${topic}-${stamp}.md`);
+  const absPath = join(opts.cwd, relPath);
+
+  if (opts.dryRun) {
+    console.log("ticket: would migrate -> " + relPath);
+  } else {
+    mkdirSync(dirname(absPath), { recursive: true });
+    const marker = `\n\n<!-- Ticket (repo-relative): ${relPath} -->\n`;
+    writeFileSync(absPath, candidate.body.trimEnd() + marker, "utf8");
+    console.log("ticket: migrated body -> " + relPath);
+
+    appendTicketEntry(opts.cwd, {
+      id: `ticket_migrated_${stamp}`,
+      title,
+      topic,
+      group,
+      project,
+      createdAt: new Date().toISOString(),
+      path: relPath,
+      source: "ticket-migrate",
+    }, opts);
+    if (existsSync(candidate.latestPath)) {
+      unlinkSync(candidate.latestPath);
+      console.log("ticket: deleted legacy LATEST.md");
+    }
+  }
+}