@caiqueoak/flow 0.3.2 → 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
 
@@ -48,9 +48,9 @@ Updates are explicit:
 flow update
 ```
 
-`flow update` detects how the active Flow CLI is installed. If the project contains `@caiqueoak/flow`, it updates that project dependency; if the CLI is globally installed, it updates the global package instead. It then refreshes `/flow` for every coding agent configured in `.flow/config.yaml` without modifying canonical project state.
+`flow update` updates the installation that provides the active CLI: the global package for `flow update`, or the project dependency for `npx flow update`. It uses npm's update operation and refreshes `/flow` for every coding agent configured in `.flow/config.yaml` without modifying canonical project state. If the project lockfile and the package on disk disagree, Flow safely reinstalls only its own package before updating.
 
-On Windows, npm is invoked through the command shell so `npm.cmd` can be executed correctly. When Flow is installed as a project dependency, `npx flow update` is equivalent.
+On Windows, npm is invoked through `cmd.exe` without Node's `shell: true` option, so `npm.cmd` executes without the `DEP0190` warning. When Flow is installed as a project dependency, `npx flow update` is equivalent.
 
 There is no background update check or automatic update mechanism.
 
@@ -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.2",
+  "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

@@ -54,9 +54,11 @@ function question(rl, message) {
 }
 
 function runNpm(npmArgs, options = {}) {
+  if (process.platform === 'win32') {
+    return execFileSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', npmCommand(), ...npmArgs], options);
+  }
   return execFileSync(npmCommand(), npmArgs, {
-    ...options,
-    shell: process.platform === 'win32'
+    ...options
   });
 }
 
@@ -190,17 +192,6 @@ async function initProject() {
   else { info(); info('Flow is ready. Open a configured coding agent and invoke /flow.'); }
 }
 
-function dependencySection(root) {
-  const file = path.join(root, 'package.json');
-  if (!fs.existsSync(file)) return '--save-dev';
-  try {
-    const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (pkg.dependencies?.[PACKAGE_NAME]) return '--save';
-    if (pkg.optionalDependencies?.[PACKAGE_NAME]) return '--save-optional';
-  } catch { /* use default */ }
-  return '--save-dev';
-}
-
 function containingNodeModules(packageRoot) {
   let current = path.resolve(packageRoot);
   while (true) {
@@ -211,44 +202,88 @@ function containingNodeModules(packageRoot) {
   }
 }
 
-function updatePlan(root) {
-  const projectPackageRoot = packagePath(root);
-  if (fs.existsSync(path.join(projectPackageRoot, 'package.json'))) {
-    return {
-      npmArgs: ['install', dependencySection(root), `${PACKAGE_NAME}@latest`],
-      cwd: root,
-      packageRoot: projectPackageRoot,
-      mode: 'project'
-    };
-  }
+function installedPackageVersion(packageRoot) {
+  const manifest = path.join(packageRoot, 'package.json');
+  if (!fs.existsSync(manifest)) return null;
+  return JSON.parse(fs.readFileSync(manifest, 'utf8')).version || null;
+}
+
+function lockedPackageVersion(root) {
+  const lockfile = path.join(root, 'package-lock.json');
+  if (!fs.existsSync(lockfile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(lockfile, 'utf8')).packages?.[`node_modules/${PACKAGE_NAME}`]?.version || null;
+  } catch { return null; }
+}
 
+function globalUpdatePlan(root) {
   try {
     const globalNodeModules = path.resolve(runNpm(['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim());
     const globalPackageRoot = path.join(globalNodeModules, '@caiqueoak', 'flow');
     if (path.resolve(ROOT).startsWith(`${globalNodeModules}${path.sep}`) && fs.existsSync(path.join(globalPackageRoot, 'package.json'))) {
       return {
-        npmArgs: ['install', '--global', `${PACKAGE_NAME}@latest`],
+        npmArgs: ['update', '--global', PACKAGE_NAME],
         cwd: root,
         packageRoot: globalPackageRoot,
         mode: 'global'
       };
     }
   } catch { /* fall through to local installation detection */ }
+  return null;
+}
+
+function updatePlan(root) {
+  const global = globalUpdatePlan(root);
+  if (global) return global;
 
   const nodeModules = containingNodeModules(ROOT);
   if (nodeModules) {
     const installRoot = path.dirname(nodeModules);
     return {
-      npmArgs: ['install', dependencySection(installRoot), `${PACKAGE_NAME}@latest`],
+      npmArgs: ['update', PACKAGE_NAME],
       cwd: installRoot,
       packageRoot: ROOT,
       mode: 'local'
     };
   }
 
+  const projectPackageRoot = packagePath(root);
+  if (fs.existsSync(path.join(projectPackageRoot, 'package.json'))) {
+    return {
+      npmArgs: ['update', PACKAGE_NAME],
+      cwd: root,
+      packageRoot: projectPackageRoot,
+      mode: 'project'
+    };
+  }
+
   fail('cannot determine how this Flow CLI was installed. Reinstall @caiqueoak/flow with npm, then run flow update again.');
 }
 
+function repairDivergentProjectInstall(plan) {
+  if (plan.mode === 'global') return;
+  const expected = lockedPackageVersion(plan.cwd);
+  const actual = installedPackageVersion(plan.packageRoot);
+  if (!expected || !actual || expected === actual) return;
+
+  const backup = path.join(plan.cwd, `.flow-update-backup-${process.pid}-${Date.now()}`);
+  info(`Repairing divergent ${PACKAGE_NAME} installation (${actual} on disk, ${expected} in package-lock.json)...`);
+  fs.renameSync(plan.packageRoot, backup);
+  try {
+    runNpm(['install'], { cwd: plan.cwd, stdio: 'inherit' });
+    if (installedPackageVersion(plan.packageRoot) !== expected) {
+      throw new Error(`npm install did not restore ${PACKAGE_NAME}@${expected}.`);
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    try {
+      fs.rmSync(plan.packageRoot, { recursive: true, force: true });
+      fs.renameSync(backup, plan.packageRoot);
+    } catch { /* preserve the original npm error below */ }
+    throw error;
+  }
+}
+
 function update() {
   const root = projectRoot();
   const config = readConfig(root);
@@ -257,8 +292,10 @@ function update() {
 
   const plan = updatePlan(root);
   info(`Updating ${PACKAGE_NAME} (${plan.mode} installation)...`);
-  try { runNpm(plan.npmArgs, { cwd: plan.cwd, stdio: 'inherit' }); }
-  catch { fail('npm update failed. Existing project state and installed skills were not intentionally removed.'); }
+  try {
+    repairDivergentProjectInstall(plan);
+    runNpm(plan.npmArgs, { cwd: plan.cwd, stdio: 'inherit' });
+  } catch { fail('npm update failed. Existing project state and installed skills were not intentionally removed.'); }
 
   if (!fs.existsSync(path.join(plan.packageRoot, 'package.json'))) fail(`updated package not found at ${plan.packageRoot}.`);
   const latest = JSON.parse(fs.readFileSync(path.join(plan.packageRoot, 'package.json'), 'utf8'));
@@ -268,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 {
@@ -277,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 };
+}