issy 0.10.0 → 0.11.0

package/README.md

@@ -90,6 +90,7 @@ Once installed globally, you can run commands from your terminal:
 ```bash
 issy                          # Start the web UI
 issy list                     # List open issues (roadmap order)
+issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy create --title "Bug"     # Create an issue
 issy learn                    # Print AI-agent instructions
@@ -137,12 +138,15 @@ Opens a local read-only UI at `http://localhost:1554` for browsing issues.
 issy init                     # Create .issy/issues/ directory
 issy init --seed              # Create with a welcome issue
 issy list                     # List open issues (roadmap order)
+issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy search "auth"            # Fuzzy search
 issy read 0001                # View issue
 issy create --title "Bug" --after 0002    # Create issue after #0002
+issy create --title "Feature" --depends-on 0012,0035 --last  # Blocked by issues
 issy create --title "Bug" --body "Details here" --last  # Create with body content
 issy update 0001 --before 0003            # Reposition in roadmap
+issy update 0001 --depends-on 0012,0035   # Replace blockers
 issy update 0001 --body "New details"     # Replace body content
 issy close 0001               # Close issue
 issy reopen 0001 --after 0004 # Reopen and place in roadmap
@@ -175,6 +179,16 @@ issy list --sort priority     # Sort by priority instead
 issy list --sort created      # Sort by creation date
 ```
 
+The `Blk` column in `issy list` shows the count of currently open blockers. `-` means the issue is unblocked. Use `issy list --unblocked` to show only open issues that have no open blockers. Dependency IDs that do not match an existing issue are ignored.
+
+Issues can declare blockers with `depends_on`:
+
+```yaml
+depends_on: 0012, 0035
+```
+
+Roadmap placement is validated against open dependencies. An open issue must appear after every open issue it depends on, and `create`, `update`, or `reopen` fails if the requested position would put a blocked issue before one of its blockers.
+
 ### Hooks
 
 issy supports optional hook files in `.issy/` that inject context into stdout after successful operations. The file contents are printed directly, making them visible to AI agents in their command output.
@@ -226,6 +240,7 @@ scope: medium
 type: bug
 status: open
 order: a0
+depends_on: 0012, 0035
 created: 2025-01-15T10:30:00
 ---
 
@@ -243,6 +258,7 @@ session isn't established, causing a redirect loop.
 | `status` | `open`, `closed` |
 | `labels` | comma-separated (optional) |
 | `order` | fractional index key (managed by issy) |
+| `depends_on` | comma-separated blocking issue IDs (optional) |
 
 ## Configuration
 

package/dist/cli.js

@@ -355,6 +355,9 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
+  if (data.depends_on) {
+    lines.push(`depends_on: ${data.depends_on}`);
+  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -363,6 +366,79 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
+function parseDependencyIds(dependsOn) {
+  if (!dependsOn)
+    return [];
+  const seen = new Set;
+  const ids = [];
+  for (const token of dependsOn.split(/[,\s]+/)) {
+    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
+    if (!/^\d+$/.test(value))
+      continue;
+    const id = value.padStart(4, "0");
+    if (seen.has(id))
+      continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+function filterExistingDependencyIds(dependsOn, issues, excludeId) {
+  const existingIds = new Set(issues.map((issue) => issue.id));
+  const excludedId = excludeId?.padStart(4, "0");
+  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
+}
+function formatExistingDependencyIds(dependsOn, issues, excludeId) {
+  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
+}
+function getDependencyIssues(issue, issues) {
+  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
+  if (dependencyIds.length === 0)
+    return [];
+  const issueById = new Map(issues.map((i) => [i.id, i]));
+  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
+}
+function getBlockingIssues(issue, issues) {
+  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
+}
+function isIssueUnblocked(issue, issues) {
+  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
+}
+function compareIssuesByRoadmapOrder(a, b) {
+  const orderA = a.frontmatter.order;
+  const orderB = b.frontmatter.order;
+  if (orderA && orderB) {
+    if (orderA < orderB)
+      return -1;
+    if (orderA > orderB)
+      return 1;
+  }
+  if (orderA && !orderB)
+    return -1;
+  if (!orderA && orderB)
+    return 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function validateRoadmapDependencyOrder(issues) {
+  const openIssues = issues.filter((issue) => issue.frontmatter.status === "open").sort(compareIssuesByRoadmapOrder);
+  const positionById = new Map(openIssues.map((issue, index) => [issue.id, index]));
+  const violations = [];
+  for (const issue of openIssues) {
+    const issuePosition = positionById.get(issue.id);
+    if (issuePosition === undefined)
+      continue;
+    for (const dependency of getBlockingIssues(issue, issues)) {
+      const dependencyPosition = positionById.get(dependency.id);
+      if (dependencyPosition === undefined || dependencyPosition < issuePosition) {
+        continue;
+      }
+      violations.push(`#${issue.id} depends on #${dependency.id}`);
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`Roadmap dependency order invalid: ${violations.join("; ")}. Issues must be placed after all open issues they depend on.`);
+  }
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -419,17 +495,7 @@ async function getAllIssues() {
       content: body
     });
   }
-  return issues.sort((a, b) => {
-    const orderA = a.frontmatter.order;
-    const orderB = b.frontmatter.order;
-    if (orderA && orderB)
-      return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-    if (orderA && !orderB)
-      return -1;
-    if (!orderA && orderB)
-      return 1;
-    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-  });
+  return issues.sort(compareIssuesByRoadmapOrder);
 }
 async function getOpenIssuesByOrder() {
   const allIssues = await getAllIssues();
@@ -496,6 +562,8 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
+  const existingIssues = await getAllIssues();
+  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -504,6 +572,7 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
+    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -514,8 +583,7 @@ async function createIssue(input) {
   const content = `${generateFrontmatter(frontmatter)}
 ${body}
 `;
-  await writeFile(join(getIssuesDir(), filename), content);
-  return {
+  const newIssue = {
     id: issueNumber,
     filename,
     frontmatter,
@@ -523,12 +591,17 @@ ${body}
 ${body}
 `
   };
+  validateRoadmapDependencyOrder([...existingIssues, newIssue]);
+  await writeFile(join(getIssuesDir(), filename), content);
+  return newIssue;
 }
 async function updateIssue(id, input) {
   const issue = await getIssue(id);
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
+  const allIssues = await getAllIssues();
+  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -540,6 +613,9 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
+    ...input.depends_on !== undefined && {
+      depends_on: dependsOn || undefined
+    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -547,12 +623,16 @@ ${input.body}
 ` : issue.content;
   const content = `${generateFrontmatter(updatedFrontmatter)}
 ${updatedContent}`;
-  await writeFile(join(getIssuesDir(), issue.filename), content);
-  return {
+  const updatedIssue = {
     ...issue,
     frontmatter: updatedFrontmatter,
     content: updatedContent
   };
+  if (input.order !== undefined || input.depends_on !== undefined || input.status === "open") {
+    validateRoadmapDependencyOrder(allIssues.map((current) => current.id === issue.id ? updatedIssue : current));
+  }
+  await writeFile(join(getIssuesDir(), issue.filename), content);
+  return updatedIssue;
 }
 async function closeIssue(id) {
   return updateIssue(id, { status: "closed" });
@@ -1953,17 +2033,7 @@ function createSearchIndex(issues) {
 function sortIssues(issues, sortBy) {
   const sortOption = sortBy.toLowerCase();
   if (sortOption === "roadmap") {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   } else if (sortOption === "priority") {
     const priorityOrder = {
       high: 0,
@@ -2017,17 +2087,7 @@ function sortIssues(issues, sortBy) {
   } else if (sortOption === "id") {
     issues.sort((a, b) => b.id.localeCompare(a.id));
   } else {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   }
 }
 function filterByQuery(issues, query) {
@@ -2039,6 +2099,14 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
+      } else if (statusValue === "unblocked") {
+        if (!isIssueUnblocked(issue, issues)) {
+          return false;
+        }
+      } else if (statusValue === "blocked") {
+        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
+          return false;
+        }
       }
     }
     if (parsed.qualifiers.priority) {
@@ -2126,7 +2194,23 @@ function typeSymbol(type) {
 }
 function formatIssueRow(issue) {
   const status = issue.frontmatter.status === "open" ? "OPEN  " : "CLOSED";
-  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${issue.frontmatter.title}`;
+  const blocked = issue.blockers > 0 ? String(issue.blockers) : "-";
+  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${blocked.padEnd(3)}  ${issue.frontmatter.title}`;
+}
+function printDependsOn(issue, issues) {
+  const dependencyIssues = getDependencyIssues(issue, issues);
+  if (dependencyIssues.length === 0)
+    return;
+  console.log(`  Depends on:  ${dependencyIssues.map((i) => `#${i.id}`).join(", ")}`);
+}
+function getDependsOnArg(values) {
+  const value = values["depends-on"];
+  return typeof value === "string" ? value : undefined;
+}
+async function resolveDependsOn(value, excludeId) {
+  if (value === undefined)
+    return;
+  return formatExistingDependencyIds(value, await getAllIssues(), excludeId);
 }
 async function resolvePosition(opts) {
   const openIssues = await getOpenIssuesByOrder();
@@ -2158,7 +2242,7 @@ function hasHelpFlag(commandArgs) {
 async function listIssues(options) {
   const allIssues = await getAllIssues();
   const queryParts = [];
-  if (!options.all)
+  if (!options.all && !options.unblocked)
     queryParts.push("is:open");
   if (options.priority)
     queryParts.push(`priority:${options.priority}`);
@@ -2170,17 +2254,23 @@ async function listIssues(options) {
     queryParts.push(`sort:${options.sort}`);
   if (options.search)
     queryParts.push(options.search);
-  const query = queryParts.join(" ") || "is:open";
-  const issues = filterByQuery(allIssues, query);
+  const query = queryParts.join(" ");
+  let issues = query ? filterByQuery(allIssues, query) : allIssues;
+  if (options.unblocked) {
+    issues = issues.filter((issue) => isIssueUnblocked(issue, allIssues));
+  }
   if (issues.length === 0) {
     console.log("No issues found.");
     return;
   }
   console.log(`
-  ID    Pri  Type  Status   Title`);
+  ID    Pri  Type  Status  Blk  Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow(issue));
+    console.log(formatIssueRow({
+      ...issue,
+      blockers: getBlockingIssues(issue, allIssues).length
+    }));
   }
   console.log(`
   Total: ${issues.length} issue(s)
@@ -2188,6 +2278,7 @@ async function listIssues(options) {
 }
 async function readIssue(id) {
   const issue = await getIssue(id);
+  const allIssues = await getAllIssues();
   if (!issue) {
     console.error(`Issue not found: ${id}`);
     process.exit(1);
@@ -2206,6 +2297,7 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
+  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2228,10 +2320,13 @@ async function searchIssuesCommand(query, options) {
   console.log(`
   Search results for "${query}":`);
   console.log(`
-  ID    Pri  Type  Status   Title`);
+  ID    Pri  Type  Status  Blk  Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow(issue));
+    console.log(formatIssueRow({
+      ...issue,
+      blockers: getBlockingIssues(issue, allIssues).length
+    }));
   }
   console.log(`
   Found: ${issues.length} issue(s)
@@ -2257,6 +2352,7 @@ async function createIssueCommand(options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
+      depends_on: await resolveDependsOn(options.dependsOn) || undefined,
       order
     };
     const issue = await createIssue(input);
@@ -2293,6 +2389,9 @@ async function updateIssueCommand(id, options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
+      ...options.dependsOn !== undefined && {
+        depends_on: await resolveDependsOn(options.dependsOn, id) || ""
+      },
       order
     });
     console.log(`Updated issue: ${issue.filename}`);
@@ -2341,6 +2440,7 @@ async function reopenIssueCommand(id, options) {
 }
 async function nextIssueCommand() {
   const issue = await getNextIssue();
+  const allIssues = await getAllIssues();
   if (!issue) {
     console.log("No open issues.");
     return;
@@ -2359,6 +2459,7 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
+  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2386,6 +2487,7 @@ Options:
 Commands:
   list                    List all open issues (roadmap order)
     --all, -a             Include closed issues
+    --unblocked           Only show open issues with no open blockers
     --priority, -p <p>    Filter by priority (high, medium, low)
     --scope <s>           Filter by scope (small, medium, large)
     --type, -t <t>        Filter by type (bug, improvement)
@@ -2410,6 +2512,7 @@ Commands:
     --scope <s>           Scope (small, medium, large)
     --type <t>            Type (bug, improvement)
     --labels, -l <l>      Comma-separated labels
+    --depends-on <ids>    Comma-separated blocking issue IDs
     --before <id>         Insert before this issue in roadmap
     --after <id>          Insert after this issue in roadmap
     --first               Insert at the beginning of the roadmap
@@ -2422,6 +2525,7 @@ Commands:
     --scope <s>           New scope
     --type <t>            New type
     --labels, -l <l>      New labels
+    --depends-on <ids>    Replace blocking issue IDs (empty clears)
     --before <id>         Move before this issue in roadmap
     --after <id>          Move after this issue in roadmap
     --first               Move to the beginning of the roadmap
@@ -2439,6 +2543,7 @@ Commands:
 
 Examples:
   issy list
+  issy list --unblocked
   issy list --priority high --type bug
   issy next
   issy learn
@@ -2462,6 +2567,7 @@ List all open issues in roadmap order.
 
 Options:
   --all, -a             Include closed issues
+  --unblocked           Only show open issues with no open blockers
   --priority, -p <p>    Filter by priority (high, medium, low)
   --scope <s>           Filter by scope (small, medium, large)
   --type, -t <t>        Filter by type (bug, improvement)
@@ -2474,6 +2580,7 @@ Options:
         args: args.slice(1),
         options: {
           all: { type: "boolean", short: "a" },
+          unblocked: { type: "boolean" },
           priority: { type: "string", short: "p" },
           scope: { type: "string" },
           type: { type: "string", short: "t" },
@@ -2551,6 +2658,7 @@ Options:
   --scope <s>           Scope: small, medium, large
   --type <t>            Type: bug, improvement (default: improvement)
   --labels, -l <l>      Comma-separated labels
+  --depends-on <ids>    Comma-separated blocking issue IDs
   --before <id>         Insert before this issue in roadmap
   --after <id>          Insert after this issue in roadmap
   --first               Insert at the beginning of the roadmap
@@ -2558,6 +2666,7 @@ Options:
 
 Examples:
   issy create --title "Fix login bug" --type bug --priority high --after 0002
+  issy create --title "Add export" --depends-on 0001,0002 --last
   issy create --title "Add dark mode" --last
 `);
         return;
@@ -2571,6 +2680,7 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
+          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2578,7 +2688,10 @@ Examples:
         },
         allowPositionals: true
       });
-      await createIssueCommand(values);
+      await createIssueCommand({
+        ...values,
+        dependsOn: getDependsOnArg(values)
+      });
       break;
     }
     case "update": {
@@ -2594,6 +2707,7 @@ Options:
   --scope <s>           New scope: small, medium, large
   --type <t>            New type: bug, improvement
   --labels, -l <l>      New labels (comma-separated)
+  --depends-on <ids>    Replace blocking issue IDs (empty clears)
   --before <id>         Move before this issue in roadmap
   --after <id>          Move after this issue in roadmap
   --first               Move to the beginning of the roadmap
@@ -2601,6 +2715,7 @@ Options:
 
 Examples:
   issy update 0001 --priority low --after 0003
+  issy update 0002 --depends-on 0001,0003
   issy update 0002 --title "Renamed issue" --first
 `);
         return;
@@ -2619,6 +2734,7 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
+          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2626,7 +2742,10 @@ Examples:
         },
         allowPositionals: true
       });
-      await updateIssueCommand(id, values);
+      await updateIssueCommand(id, {
+        ...values,
+        dependsOn: getDependsOnArg(values)
+      });
       break;
     }
     case "close": {

package/dist/main.js

@@ -366,6 +366,9 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
+  if (data.depends_on) {
+    lines.push(`depends_on: ${data.depends_on}`);
+  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -374,6 +377,79 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
+function parseDependencyIds(dependsOn) {
+  if (!dependsOn)
+    return [];
+  const seen = new Set;
+  const ids = [];
+  for (const token of dependsOn.split(/[,\s]+/)) {
+    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
+    if (!/^\d+$/.test(value))
+      continue;
+    const id = value.padStart(4, "0");
+    if (seen.has(id))
+      continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+function filterExistingDependencyIds(dependsOn, issues, excludeId) {
+  const existingIds = new Set(issues.map((issue) => issue.id));
+  const excludedId = excludeId?.padStart(4, "0");
+  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
+}
+function formatExistingDependencyIds(dependsOn, issues, excludeId) {
+  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
+}
+function getDependencyIssues(issue, issues) {
+  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
+  if (dependencyIds.length === 0)
+    return [];
+  const issueById = new Map(issues.map((i) => [i.id, i]));
+  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
+}
+function getBlockingIssues(issue, issues) {
+  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
+}
+function isIssueUnblocked(issue, issues) {
+  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
+}
+function compareIssuesByRoadmapOrder(a, b) {
+  const orderA = a.frontmatter.order;
+  const orderB = b.frontmatter.order;
+  if (orderA && orderB) {
+    if (orderA < orderB)
+      return -1;
+    if (orderA > orderB)
+      return 1;
+  }
+  if (orderA && !orderB)
+    return -1;
+  if (!orderA && orderB)
+    return 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function validateRoadmapDependencyOrder(issues) {
+  const openIssues = issues.filter((issue) => issue.frontmatter.status === "open").sort(compareIssuesByRoadmapOrder);
+  const positionById = new Map(openIssues.map((issue, index) => [issue.id, index]));
+  const violations = [];
+  for (const issue of openIssues) {
+    const issuePosition = positionById.get(issue.id);
+    if (issuePosition === undefined)
+      continue;
+    for (const dependency of getBlockingIssues(issue, issues)) {
+      const dependencyPosition = positionById.get(dependency.id);
+      if (dependencyPosition === undefined || dependencyPosition < issuePosition) {
+        continue;
+      }
+      violations.push(`#${issue.id} depends on #${dependency.id}`);
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`Roadmap dependency order invalid: ${violations.join("; ")}. Issues must be placed after all open issues they depend on.`);
+  }
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -430,17 +506,7 @@ async function getAllIssues() {
       content: body
     });
   }
-  return issues.sort((a, b) => {
-    const orderA = a.frontmatter.order;
-    const orderB = b.frontmatter.order;
-    if (orderA && orderB)
-      return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-    if (orderA && !orderB)
-      return -1;
-    if (!orderA && orderB)
-      return 1;
-    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-  });
+  return issues.sort(compareIssuesByRoadmapOrder);
 }
 async function getOpenIssuesByOrder() {
   const allIssues = await getAllIssues();
@@ -507,6 +573,8 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
+  const existingIssues = await getAllIssues();
+  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -515,6 +583,7 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
+    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -525,8 +594,7 @@ async function createIssue(input) {
   const content = `${generateFrontmatter(frontmatter)}
 ${body}
 `;
-  await writeFile(join(getIssuesDir(), filename), content);
-  return {
+  const newIssue = {
     id: issueNumber,
     filename,
     frontmatter,
@@ -534,12 +602,17 @@ ${body}
 ${body}
 `
   };
+  validateRoadmapDependencyOrder([...existingIssues, newIssue]);
+  await writeFile(join(getIssuesDir(), filename), content);
+  return newIssue;
 }
 async function updateIssue(id, input) {
   const issue = await getIssue(id);
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
+  const allIssues = await getAllIssues();
+  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -551,6 +624,9 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
+    ...input.depends_on !== undefined && {
+      depends_on: dependsOn || undefined
+    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -558,12 +634,16 @@ ${input.body}
 ` : issue.content;
   const content = `${generateFrontmatter(updatedFrontmatter)}
 ${updatedContent}`;
-  await writeFile(join(getIssuesDir(), issue.filename), content);
-  return {
+  const updatedIssue = {
     ...issue,
     frontmatter: updatedFrontmatter,
     content: updatedContent
   };
+  if (input.order !== undefined || input.depends_on !== undefined || input.status === "open") {
+    validateRoadmapDependencyOrder(allIssues.map((current) => current.id === issue.id ? updatedIssue : current));
+  }
+  await writeFile(join(getIssuesDir(), issue.filename), content);
+  return updatedIssue;
 }
 async function closeIssue(id) {
   return updateIssue(id, { status: "closed" });
@@ -1964,17 +2044,7 @@ function createSearchIndex(issues) {
 function sortIssues(issues, sortBy) {
   const sortOption = sortBy.toLowerCase();
   if (sortOption === "roadmap") {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   } else if (sortOption === "priority") {
     const priorityOrder = {
       high: 0,
@@ -2028,17 +2098,7 @@ function sortIssues(issues, sortBy) {
   } else if (sortOption === "id") {
     issues.sort((a, b) => b.id.localeCompare(a.id));
   } else {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   }
 }
 function filterByQuery(issues, query) {
@@ -2050,6 +2110,14 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
+      } else if (statusValue === "unblocked") {
+        if (!isIssueUnblocked(issue, issues)) {
+          return false;
+        }
+      } else if (statusValue === "blocked") {
+        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
+          return false;
+        }
       }
     }
     if (parsed.qualifiers.priority) {
@@ -2137,12 +2205,13 @@ var compact = markdown([
   "",
   "## Essential workflow",
   "",
-  "- List work: `issy list` or `issy list --all`.",
+  "- List work: `issy list`, `issy list --all`, or `issy list --unblocked`.",
   '- Search work: `issy search "query"` or `issy search "query" --all`.',
   "- Read before changing: `issy read <id>`.",
   "- Pick next work: `issy next`.",
   '- Create work: `issy create --title "..." --type bug|improvement --priority high|medium|low <position>`.',
-  "- Update work: `issy update <id> [options]`.",
+  '- Create blocked work: `issy create --title "..." --depends-on 0001,0002 <position>`.',
+  "- Update work: `issy update <id> [options]`, including `--depends-on <ids>` to replace blockers.",
   "- Close work: `issy close <id>` after the work is complete and verified.",
   "- Reopen work: `issy reopen <id> <position>`.",
   "",
@@ -2159,6 +2228,10 @@ var compact = markdown([
   "- When creating an issue and open issues already exist, include exactly one position flag: `--before <id>`, `--after <id>`, `--first`, or `--last`.",
   "- When reopening an issue and other open issues exist, include exactly one position flag.",
   "- Use dependency order: prerequisites first, dependent/user-facing work later. Use `--last` when placement is unclear.",
+  "- Use `depends_on` / `--depends-on` when an issue cannot start until specific blocking issues are closed.",
+  "- Roadmap placement is enforced against open dependencies: an open issue cannot be placed before an open issue it depends on.",
+  "- `issy list` shows a `Blk` column with open blocker counts; `-` means unblocked.",
+  "- `issy list --unblocked` shows only open issues with no open blockers.",
   "",
   "## Closing",
   "",
@@ -2242,6 +2315,17 @@ var topics = [
       "- Updating an issue: position flags are optional and reposition the issue when provided.",
       "- Never provide more than one position flag.",
       "",
+      "## Explicit blockers",
+      "",
+      "- Use `depends_on` when an issue cannot start until specific blocking issues are closed.",
+      '- Create blocked work with `issy create --title "..." --depends-on 0001,0002 --last`.',
+      "- Replace blockers with `issy update <id> --depends-on 0001,0003`.",
+      '- Clear blockers with `issy update <id> --depends-on ""`.',
+      "- Missing or malformed dependency IDs are ignored.",
+      "- Roadmap placement is enforced against open dependencies: an open issue cannot be placed before an open issue it depends on, and a blocker cannot be moved after open issues that depend on it.",
+      "- `issy list` shows a compact `Blk` column. `-` means unblocked; otherwise the value is the number of open blockers.",
+      "- `issy list --unblocked` shows only open issues with no open blockers.",
+      "",
       "## Choosing placement",
       "",
       "- Place prerequisites before dependent issues.",
@@ -2253,9 +2337,12 @@ var topics = [
       "## Useful commands",
       "",
       "- `issy list` shows open issues in roadmap order.",
+      "- `issy list --unblocked` shows open issues with no open blockers.",
       "- `issy next` shows the first open issue in roadmap order.",
       '- `issy create --title "..." --last` appends a new issue.',
+      '- `issy create --title "..." --depends-on 0001,0002 --last` creates an issue blocked by other issues.',
       "- `issy update <id> --before <other-id>` repositions an issue.",
+      "- `issy update <id> --depends-on 0001,0003` replaces blockers.",
       "- `issy reopen <id> --after <other-id>` reopens and places a closed issue."
     ])
   },
@@ -2272,6 +2359,7 @@ var topics = [
       "",
       "- `issy list`: list open issues in roadmap order.",
       "- `issy list --all`: include closed issues.",
+      "- `issy list --unblocked`: list open issues with no open blockers.",
       "- `issy list --priority high|medium|low`: filter by priority.",
       "- `issy list --scope small|medium|large`: filter by scope.",
       "- `issy list --type bug|improvement`: filter by type.",
@@ -2289,10 +2377,11 @@ var topics = [
       "",
       '- `issy create --title "Fix login bug" --type bug --priority high --after 0002`.',
       '- `issy create --title "Add dark mode" --type improvement --last --labels "ui, frontend"`.',
+      '- `issy create --title "Add export" --depends-on 0001,0002 --last`.',
       '- `issy create --title "Urgent fix" --first`.',
       '- `issy create --title "Fix crash" --body "## Problem\\n\\nApp crashes on startup." --last`.',
       "",
-      "Create options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--before`, `--after`, `--first`, `--last`.",
+      "Create options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--depends-on`, `--before`, `--after`, `--first`, `--last`.",
       "",
       "## Update",
       "",
@@ -2300,9 +2389,10 @@ var topics = [
       "- `issy update <id> --after 0003`.",
       "- `issy update <id> --first`.",
       '- `issy update <id> --labels "api, backend"`.',
+      "- `issy update <id> --depends-on 0001,0003`.",
       '- `issy update <id> --body "## Problem\\n\\nUpdated description."`.',
       "",
-      "Update options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--before`, `--after`, `--first`, `--last`.",
+      "Update options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--depends-on`, `--before`, `--after`, `--first`, `--last`.",
       "",
       "## Close and reopen",
       "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issy",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "AI-native issue tracking. Markdown files in .issues/, managed by your coding assistant.",
   "type": "module",
   "license": "MIT",
@@ -35,8 +35,8 @@
     "lint": "biome check src bin"
   },
   "dependencies": {
-    "@miketromba/issy-app": "^0.10.0",
-    "@miketromba/issy-core": "^0.10.0",
+    "@miketromba/issy-app": "^0.11.0",
+    "@miketromba/issy-core": "^0.11.0",
     "update-notifier": "^7.3.1"
   }
 }