@caiqueoak/flow 0.5.1 → 0.5.3

package/README.md

@@ -38,7 +38,7 @@ PRD, engineering and plans use YAML frontmatter with `schema_version: 1`, `statu
 - `gates.yaml`: schema 1, command/builtin checks only; qualitative judgment remains review instructions.
 - `docs/graph.md`: deterministic derived projection; regenerate rather than hand-edit.
 
-Persist only pending, in_progress and completed. Ready/Blocked are derived from dependency edges and explicit blockers. Blockers use `{id, type: external_action|consequential_decision, description, status: unresolved|resolved}`. Only one mutating work item/task may be active across the project. Read-only analysis may be parallel; automatic concurrent worktrees are out of scope.
+Persist only pending, in_progress and completed. Ready/Blocked are derived exclusively from work-item dependency edges. Blockers use `{id, type: external_action|consequential_decision, description, status: unresolved|resolved}` as context for the agent to address within the work item; they do not change execution status. Only one mutating work item/task may be active across the project. Read-only analysis may be parallel; automatic concurrent worktrees are out of scope.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {

package/src/artifacts/backlog.mjs

@@ -120,13 +120,8 @@ export function validateAcyclic(items) {
 export function deriveExecutionStatus(item, byId) {
   if (item.state === 'completed') return { status: 'completed', reasons: [] };
   const incompleteDependencies = item.depends_on.filter((id) => byId.get(id)?.state !== 'completed');
-  const explicitBlockers = (item.blockers ?? []).filter((blocker) => blocker.status !== 'resolved');
-  if (incompleteDependencies.length || explicitBlockers.length) {
-    return {
-      status: 'blocked',
-      reasons: [...incompleteDependencies.map((id) => ({ type: 'dependency', ref: id })), ...explicitBlockers]
-    };
-  }
+  if (incompleteDependencies.length)
+    return { status: 'blocked', reasons: incompleteDependencies.map((id) => ({ type: 'dependency', ref: id })) };
   return { status: item.state === 'in_progress' ? 'in_progress' : 'ready', reasons: [] };
 }
 

package/src/commands/graph.mjs

@@ -22,6 +22,13 @@ const CLASSES = [
   '  classDef blocked fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;'
 ];
 
+const LINK_STYLES = {
+  completed: 'stroke:#16a34a,stroke-width:2px',
+  in_progress: 'stroke:#2563eb,stroke-width:3px',
+  ready: 'stroke:#d97706,stroke-width:2px,stroke-dasharray:6 4',
+  blocked: 'stroke:#dc2626,stroke-width:2px,stroke-dasharray:2 3'
+};
+
 export function generateGraphMarkdown(backlogText) {
   const { work_items: items } = parseBacklog(backlogText);
   const ordered = topologicalOrder(items);
@@ -39,10 +46,10 @@ export function generateGraphMarkdown(backlogText) {
     '',
     '## Status',
     '',
-    '- **Completed** — accepted work.',
-    '- **In Progress** — currently executing.',
-    '- **Ready** — pending work with all dependencies satisfied.',
-    '- **Blocked** — pending work with at least one incomplete dependency or explicit external blocker.',
+    '- 🟩 **Completed** — accepted work.',
+    '- 🟦 **In Progress** — currently executing.',
+    '- 🟨 **Ready** — pending work with all dependencies satisfied.',
+    '- 🟥 **Blocked** — pending work with at least one incomplete work-item dependency.',
     '',
     '```mermaid',
     "%%{init: {'flowchart': {'curve': 'linear', 'nodeSpacing': 32, 'rankSpacing': 54}} }%%",
@@ -51,6 +58,8 @@ export function generateGraphMarkdown(backlogText) {
   for (const item of ordered) lines.push(`  ${item.id}["${escapeMermaid(item.id)}<br/>${escapeMermaid(item.title)}"]`);
   lines.push('');
   for (const edge of edges) lines.push(`  ${edge.source} --> ${edge.target}`);
+  lines.push('');
+  edges.forEach((edge, index) => lines.push(`  linkStyle ${index} ${LINK_STYLES[statuses.get(edge.source)]};`));
   lines.push('', ...CLASSES);
   for (const status of ['completed', 'in_progress', 'ready', 'blocked']) {
     const ids = ordered.filter((item) => statuses.get(item.id) === status).map((item) => item.id);

package/src/commands/route.mjs

@@ -79,7 +79,7 @@ export function routeProject(root) {
   if (active && deriveExecutionStatus(active, byId).status === 'blocked')
     return {
       action: 'stop',
-      reason: 'external_action',
+      reason: 'dependency_blocked',
       work_item: active.id,
       details: deriveExecutionStatus(active, byId).reasons
     };

package/src/commands/status.mjs

@@ -14,7 +14,11 @@ export function runStatus({ args }) {
   const groups = new Map(['in_progress', 'ready', 'blocked', 'completed'].map((status) => [status, []]));
   for (const item of backlog.work_items) {
     const derived = deriveExecutionStatus(item, byId);
-    groups.get(derived.status).push({ ...item, reasons: derived.reasons });
+    groups.get(derived.status).push({
+      ...item,
+      reasons: derived.reasons,
+      blockers: item.blockers.filter((blocker) => blocker.status === 'unresolved')
+    });
   }
   const lines = [];
   for (const [status, items] of groups) {
@@ -23,8 +27,7 @@ export function runStatus({ args }) {
     for (const item of items) {
       const deps = item.reasons.filter((r) => r.type === 'dependency').map((r) => r.ref);
       lines.push(`  ${item.id} — ${item.title}${deps.length ? ` ← ${deps.join(', ')}` : ''}`);
-      for (const reason of item.reasons.filter((reason) => reason.type !== 'dependency'))
-        lines.push(`    ${reason.type}: ${reason.description} [${reason.id}]`);
+      for (const blocker of item.blockers) lines.push(`    blocker: ${blocker.description} [${blocker.id}]`);
     }
     lines.push('');
   }

package/src/shared/profiles.mjs

@@ -4,7 +4,12 @@ const text = fs.readFileSync(
   new URL('../../skills/flow/engineering/profiles/readability-first.md', import.meta.url),
   'utf8'
 );
-export const READABILITY_FIRST_PROFILE = parse(text.match(/^---\r?\n([\s\S]*?)\r?\n---/)[1]);
+export function parseProfileFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error('Missing YAML frontmatter in Flow profile.');
+  return parse(match[1]);
+}
+export const READABILITY_FIRST_PROFILE = parseProfileFrontmatter(text);
 export const ENGINEERING_PROFILES = {
   'readability-first': READABILITY_FIRST_PROFILE,
   [READABILITY_FIRST_PROFILE.id]: READABILITY_FIRST_PROFILE