@caiqueoak/flow 0.3.3 → 0.4.0

package/README.md

@@ -38,7 +38,7 @@ Flow internally loads only the guidance needed for discovery, planning, build, r
 
 When authorized, Flow keeps a concise artifact model: product truth in `PRD.md`, engineering truth in `ENGINEERING.md`, decisions in `DECISIONS.md`, execution context in `STATE.md`, the canonical work-item DAG in `BACKLOG.yaml`, and a human-readable derived projection in `GRAPH.md`. Work items use `SPEC.md` plus `TASKS.yaml`. `SUMMARY.md` is not part of the model.
 
-In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute. Each Mermaid card contains only the work-item ID and canonical title. Every dependency arrow goes from dependency to dependent item and uses the color and line style of its source card.
+In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute. Each Mermaid card contains only the work-item ID and canonical title. Every dependency arrow goes from dependency to dependent item and uses the color and line style of its source card. `flow graph` deterministically regenerates this projection from `BACKLOG.yaml`, using straight Mermaid arrows only.
 
 ## Update
 
@@ -65,6 +65,7 @@ Use Conventional Commit prefixes in the PR title (and retained commits): `fix:`
 ```text
 flow init
 flow update
+flow graph
 flow --version
 flow --help
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {
@@ -10,6 +10,9 @@
   "bin": {
     "flow": "./src/cli.mjs"
   },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
   "files": [
     "src",
     "skills",

package/skills/flow/SKILL.md

@@ -47,7 +47,7 @@ Graph/control data is YAML:
 
 Do not create `SUMMARY.md`, completion logs, ad-hoc progress documents, handoff documents, reports, or any other new project artifact unless the developer explicitly requests or authorizes them. Completed `SPEC.md` files retain concise Overview and Validation sections.
 
-`GRAPH.md` is derived only. It must never become an independent source of truth and must be reconciled whenever work-item existence, title, dependencies, or status change. Before creating or changing it, read `references/graph.md` and follow that contract exactly; do not preserve an established style that conflicts with it.
+`GRAPH.md` is derived only. It must never become an independent source of truth. Whenever work-item existence, title, dependencies, or status change, update `BACKLOG.yaml` first and then run `flow graph --path .` to regenerate it. Never edit `GRAPH.md` manually. Before changing the backlog, read `references/graph.md` and follow that contract exactly.
 
 ## Work item model
 
@@ -132,7 +132,7 @@ Load only the reference needed for current state:
 5. Route to the minimal internal reference.
 6. Claim selected work before parallel execution.
 7. Continue planning, build, gates, review, fixes/reconciliation, and completion without another invocation.
-8. Recompute work-item states and readiness after every meaningful transition, synchronize `BACKLOG.yaml`, `STATE.md`, and `GRAPH.md`, and continue if ready work exists.
+8. Recompute work-item states and readiness after every meaningful transition, synchronize `BACKLOG.yaml`, run `flow graph --path .`, then synchronize `STATE.md`, and continue if ready work exists.
 9. Do not stop or return control merely to announce that a task/work item completed or to describe the next step. Stop only when developer input is required for a consequential decision, an external approval is required, an unrecoverable blocker prevents useful progress, or no ready work remains.
 
 When execution stops, report the stopping reason and the smallest relevant status summary. During uninterrupted execution, avoid progress-only messages.

package/skills/flow/references/graph.md

@@ -3,6 +3,18 @@
 Every Flow `GRAPH.md` must be a derived, human-readable projection of
 `.flow/BACKLOG.yaml`. It never becomes an independent source of truth.
 
+## Generation
+
+After every change to work-item existence, title, status, or dependencies, run:
+
+```text
+flow graph --path .
+```
+
+The command validates the backlog DAG and regenerates the complete file. Do
+not edit `GRAPH.md` directly. It always emits Mermaid with `curve: 'linear'`;
+do not replace that setting or introduce curved arrows.
+
 ## Card content
 
 Each Mermaid card contains exactly two lines:

package/src/cli.mjs

@@ -305,8 +305,14 @@ function update() {
   info(`Flow updated to ${latest.version}.`);
 }
 
+async function graph() {
+  const { writeGraph } = await import('./graph.mjs');
+  const result = writeGraph(projectRoot());
+  info(`Generated ${result.graphPath}`);
+}
+
 function help() {
-  info(`Flow ${VERSION}\n\nUsage:\n  flow init [--path <project>] [--runtime codex,claude]\n  flow update [--path <project>]\n  flow --version\n\nflow init creates only .flow/config.yaml and installs the project-local /flow skill for selected coding agents.\nIf .flow already exists, init only adds coding-agent integrations and exits without prompting when all built-in integrations are already configured.\nflow update updates the installation that provides the Flow CLI (project-local or global) and refreshes every configured project-local skill.\nThere is no flow install command and no automatic/background update mechanism.`);
+  info(`Flow ${VERSION}\n\nUsage:\n  flow init [--path <project>] [--runtime codex,claude]\n  flow update [--path <project>]\n  flow graph [--path <project>]\n  flow --version\n\nflow init creates only .flow/config.yaml and installs the project-local /flow skill for selected coding agents.\nIf .flow already exists, init only adds coding-agent integrations and exits without prompting when all built-in integrations are already configured.\nflow update updates the installation that provides the Flow CLI (project-local or global) and refreshes every configured project-local skill.\nflow graph deterministically projects .flow/BACKLOG.yaml into .flow/GRAPH.md. There is no flow install command and no automatic/background update mechanism.`);
 }
 
 try {
@@ -314,6 +320,7 @@ try {
   else if (hasFlag('--version') || hasFlag('-v')) info(VERSION);
   else if (args[0] === 'init') await initProject();
   else if (args[0] === 'update') update();
+  else if (args[0] === 'graph') await graph();
   else fail(`unknown command '${args[0]}'. Run flow --help.`);
 } catch (error) {
   if (error?.code === 'ABORT_ERR') {

package/src/graph.mjs

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+
+const KINDS = new Set(['feature', 'technical', 'maintenance']);
+const STATUSES = new Set(['completed', 'in_progress', 'pending', 'blocked']);
+
+export class GraphValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GraphValidationError';
+  }
+}
+
+function compareIds(left, right) { return left < right ? -1 : left > right ? 1 : 0; }
+function fail(message) { throw new GraphValidationError(message); }
+function requireString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) fail(`${label} must be a non-empty string.`);
+  return value;
+}
+function requireObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${label} must be a mapping.`);
+  return value;
+}
+
+function parseBacklog(text) {
+  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length) fail(`BACKLOG.yaml is invalid: ${document.errors[0].message}`);
+  const backlog = requireObject(document.toJS(), 'BACKLOG.yaml');
+  if (backlog.schema_version !== 1) fail('BACKLOG.yaml schema_version must be 1.');
+  requireString(backlog.source_of_truth, 'BACKLOG.yaml source_of_truth');
+  if (!Array.isArray(backlog.work_items)) fail('BACKLOG.yaml work_items must be a list.');
+
+  const ids = new Set();
+  const items = backlog.work_items.map((raw, index) => {
+    const label = `work_items[${index}]`;
+    const item = requireObject(raw, label);
+    const id = requireString(item.id, `${label}.id`);
+    if (ids.has(id)) fail(`BACKLOG.yaml contains duplicate work-item ID '${id}'.`);
+    ids.add(id);
+    const folder = requireString(item.folder, `${label}.folder`);
+    if (!KINDS.has(item.kind)) fail(`${label}.kind must be feature, technical, or maintenance.`);
+    const title = requireString(item.title, `${label}.title`);
+    if (!STATUSES.has(item.status)) fail(`${label}.status must be completed, in_progress, pending, or blocked.`);
+    if (!Number.isInteger(item.priority) || item.priority < 1) fail(`${label}.priority must be a positive integer.`);
+    if (!Array.isArray(item.depends_on)) fail(`${label}.depends_on must be a list.`);
+    const dependencySet = new Set();
+    for (const dependency of item.depends_on) {
+      requireString(dependency, `${label}.depends_on entry`);
+      if (dependency === id) fail(`Work item '${id}' cannot depend on itself.`);
+      if (dependencySet.has(dependency)) fail(`Work item '${id}' lists dependency '${dependency}' more than once.`);
+      dependencySet.add(dependency);
+    }
+    return { id, folder, kind: item.kind, title, status: item.status, priority: item.priority, depends_on: [...dependencySet] };
+  });
+  const byId = new Map(items.map((item) => [item.id, item]));
+  for (const item of items) for (const dependency of item.depends_on) {
+    if (!byId.has(dependency)) fail(`Work item '${item.id}' depends on unknown work item '${dependency}'.`);
+  }
+  return items;
+}
+
+function topology(items) {
+  const byId = new Map(items.map((item) => [item.id, item]));
+  const remaining = new Map(items.map((item) => [item.id, item.depends_on.length]));
+  const dependents = new Map(items.map((item) => [item.id, []]));
+  for (const item of items) for (const dependency of item.depends_on) dependents.get(dependency).push(item.id);
+  for (const ids of dependents.values()) ids.sort(compareIds);
+  const ready = items.filter((item) => item.depends_on.length === 0).map((item) => item.id).sort(compareIds);
+  const levels = new Map(ready.map((id) => [id, 0]));
+  const orderedIds = [];
+  while (ready.length) {
+    const id = ready.shift();
+    orderedIds.push(id);
+    for (const dependent of dependents.get(id)) {
+      levels.set(dependent, Math.max(levels.get(dependent) ?? 0, levels.get(id) + 1));
+      const count = remaining.get(dependent) - 1;
+      remaining.set(dependent, count);
+      if (count === 0) { ready.push(dependent); ready.sort(compareIds); }
+    }
+  }
+  if (orderedIds.length !== items.length) fail('BACKLOG.yaml work-item dependencies contain a cycle.');
+  const ordered = orderedIds.map((id) => byId.get(id)).sort((left, right) => (levels.get(left.id) - levels.get(right.id)) || compareIds(left.id, right.id));
+  return { ordered, byId };
+}
+
+function displayStatus(item, byId) {
+  if (item.status === 'completed') return 'complete';
+  if (item.status === 'in_progress') return 'active';
+  const derived = item.depends_on.every((id) => byId.get(id).status === 'completed') ? 'pending' : 'blocked';
+  if (item.status !== derived) fail(`Work item '${item.id}' is declared ${item.status} but derives as ${derived}.`);
+  return derived;
+}
+
+function escapeMermaid(text) {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+const CLASS_DEFINITIONS = [
+  '  classDef complete fill:#dcfce7,stroke:#16a34a,color:#14532d;',
+  '  classDef active fill:#dbeafe,stroke:#2563eb,color:#1e3a8a;',
+  '  classDef pending fill:#fef3c7,stroke:#d97706,color:#78350f;',
+  '  classDef blocked fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;'
+];
+const LINK_STYLES = {
+  complete: 'stroke:#16a34a,stroke-width:2px',
+  active: 'stroke:#2563eb,stroke-width:3px',
+  pending: 'stroke:#d97706,stroke-width:2px,stroke-dasharray:6 3',
+  blocked: 'stroke:#dc2626,stroke-width:2px,stroke-dasharray:2 3'
+};
+
+export function generateGraphMarkdown(backlogText) {
+  const items = parseBacklog(backlogText);
+  const { ordered, byId } = topology(items);
+  const statuses = new Map(ordered.map((item) => [item.id, displayStatus(item, byId)]));
+  const edges = ordered.flatMap((source) => ordered
+    .filter((target) => target.depends_on.includes(source.id))
+    .map((target) => ({ source: source.id, target: target.id, status: statuses.get(source.id) })));
+  const lines = [
+    '# Work-item dependency graph', '', '## Status', '',
+    '- <span style="color:#16a34a">Complete</span> — all work accepted.',
+    '- <span style="color:#2563eb">In progress</span> — active delivery path.',
+    '- <span style="color:#d97706">Pending</span> — all dependencies complete; ready to start.',
+    '- <span style="color:#dc2626">Blocked</span> — one or more dependencies remain incomplete.',
+    '', '```mermaid',
+    "%%{init: {'flowchart': {'curve': 'linear', 'nodeSpacing': 32, 'rankSpacing': 54}} }%%",
+    'flowchart TD'
+  ];
+  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('', ...CLASS_DEFINITIONS);
+  for (const status of ['complete', 'active', 'pending', 'blocked']) {
+    const ids = ordered.filter((item) => statuses.get(item.id) === status).map((item) => item.id);
+    if (ids.length) lines.push(`  class ${ids.join(',')} ${status};`);
+  }
+  for (const status of ['complete', 'active', 'pending', 'blocked']) {
+    const indices = edges.map((edge, index) => edge.status === status ? index : null).filter((index) => index !== null);
+    if (indices.length) lines.push(`  linkStyle ${indices.join(',')} ${LINK_STYLES[status]};`);
+  }
+  lines.push(
+    '```', '',
+    'Cards in the same vertical rank have no dependency between them and can be',
+    'worked in parallel. Arrow color and line style are inherited from the source',
+    'card: solid green for complete, solid blue for active, dashed yellow for',
+    'pending, and dotted red for blocked.', ''
+  );
+  return lines.join('\n');
+}
+
+export function writeGraph(projectRoot) {
+  const flowDir = path.join(projectRoot, '.flow');
+  const backlogPath = path.join(flowDir, 'BACKLOG.yaml');
+  if (!fs.existsSync(backlogPath)) fail(`Backlog not found: ${backlogPath}`);
+  const markdown = generateGraphMarkdown(fs.readFileSync(backlogPath, 'utf8'));
+  const graphPath = path.join(flowDir, 'GRAPH.md');
+  const temporaryPath = path.join(flowDir, `.GRAPH.md.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(temporaryPath, markdown, 'utf8');
+  fs.renameSync(temporaryPath, graphPath);
+  return { graphPath, markdown };
+}