@caiqueoak/flow 0.5.0 → 0.5.2

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.0",
+  "version": "0.5.2",
   "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/migrate.mjs

@@ -27,9 +27,39 @@ function number(value) {
   if (!match) throw new Error(`Cannot normalize ID '${value}'.`);
   return match[0].padStart(3, '0');
 }
+function temporarySibling(file) {
+  const directory = path.dirname(file);
+  const base = path.basename(file);
+  let attempt = 0;
+  let temporary;
+  do {
+    temporary = path.join(directory, `.${base}.flow-migration-${process.pid}-${Date.now()}-${attempt++}`);
+  } while (fs.existsSync(temporary));
+  return temporary;
+}
+function sameEntry(from, to) {
+  return fs.realpathSync.native(from) === fs.realpathSync.native(to);
+}
 function move(from, to) {
   if (!fs.existsSync(from)) return;
-  if (fs.existsSync(to)) throw new Error(`Migration destination already exists: ${to}`);
+  if (path.resolve(from) === path.resolve(to)) return;
+  if (fs.existsSync(to)) {
+    if (!sameEntry(from, to)) throw new Error(`Migration destination already exists: ${to}`);
+    const temporary = temporarySibling(from);
+    fs.renameSync(from, temporary);
+    try {
+      fs.renameSync(temporary, to);
+    } catch (error) {
+      try {
+        fs.renameSync(temporary, from);
+      } catch (recoveryError) {
+        error.preserveRecoveryData = true;
+        error.recovery = { from, to, temporary, recoveryError };
+      }
+      throw error;
+    }
+    return;
+  }
   fs.mkdirSync(path.dirname(to), { recursive: true });
   fs.renameSync(from, to);
 }
@@ -136,7 +166,7 @@ function migrateStaged(root) {
   ])
     move(path.join(flow, old), path.join(flow, 'docs', next));
   if (fs.existsSync(path.join(flow, 'GRAPH.md'))) fs.unlinkSync(path.join(flow, 'GRAPH.md'));
-  if (oldFile.endsWith('BACKLOG.yaml')) fs.unlinkSync(oldFile);
+  if (oldFile.endsWith('BACKLOG.yaml')) move(oldFile, path.join(flow, 'backlog.yaml'));
   fs.writeFileSync(path.join(flow, 'backlog.yaml'), text);
   fs.writeFileSync(path.join(flow, 'docs', 'graph.md'), generateGraphMarkdown(text));
   const state = emptyState();
@@ -163,6 +193,7 @@ export function migrateProject(root) {
   const staging = fs.mkdtempSync(path.join(root, '.flow-migration-'));
   const backup = path.join(staging, 'backup');
   const staged = path.join(staging, '.flow');
+  let preserveStaging = false;
   try {
     fs.cpSync(flow, staged, { recursive: true });
     migrateStaged(staging);
@@ -174,9 +205,13 @@ export function migrateProject(root) {
       throw error;
     }
     return { unresolved: ['semantic reconciliation'], unchanged: false };
+  } catch (error) {
+    preserveStaging = Boolean(error?.preserveRecoveryData);
+    throw error;
   } finally {
     // Retain the original backup if even rollback failed; never delete the only copy.
-    if (!fs.existsSync(backup) || fs.existsSync(flow)) fs.rmSync(staging, { recursive: true, force: true });
+    if (!preserveStaging && (!fs.existsSync(backup) || fs.existsSync(flow)))
+      fs.rmSync(staging, { recursive: true, force: true });
   }
 }
 export function runMigrate({ args }) {

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/commands/validate.mjs

@@ -19,6 +19,7 @@ export function validateProject(root, { preCommitTask = null, skipTrace = false
   const error = (code, message) => findings.push({ level: 'error', code, message });
   const flow = path.join(root, '.flow');
   const exists = (relative) => fs.existsSync(path.join(flow, relative));
+  const hasExactRootEntry = (name) => fs.readdirSync(flow).includes(name);
   const read = (relative) => fs.readFileSync(path.join(flow, relative), 'utf8');
   let config;
   try {
@@ -36,7 +37,7 @@ export function validateProject(root, { preCommitTask = null, skipTrace = false
   )
     error('CONFIG', 'Invalid engineering bootstrap preferences.');
   for (const name of ['STATE.md', 'DECISIONS.md', 'SUMMARY.md', 'BACKLOG.yaml', 'PRD.md', 'ENGINEERING.md', 'GRAPH.md'])
-    if (exists(name)) error('LEGACY', `${name} must be migrated.`);
+    if (hasExactRootEntry(name)) error('LEGACY', `${name} must be migrated.`);
   let state;
   try {
     state = exists('state.yaml') ? parseState(read('state.yaml')) : null;

package/src/shared/profiles.mjs

@@ -4,7 +4,7 @@ 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(/^---\n([\s\S]*?)\n---/)[1]);
+export const READABILITY_FIRST_PROFILE = parse(text.match(/^---\r?\n([\s\S]*?)\r?\n---/)[1]);
 export const ENGINEERING_PROFILES = {
   'readability-first': READABILITY_FIRST_PROFILE,
   [READABILITY_FIRST_PROFILE.id]: READABILITY_FIRST_PROFILE