@caiqueoak/flow 0.3.1 → 0.3.3

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.
+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.
 
 ## 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.
 

package/package.json

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

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, dependencies, or status change. Preserve its established visual style and conventions while updating it.
+`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.
 
 ## Work item model
 
@@ -121,6 +121,7 @@ Load only the reference needed for current state:
 - Ready planned tasks: `references/build.md`
 - Completed implementation awaiting validation: `references/review.md`
 - Decision impact or inconsistent artifacts: `references/reconcile.md`
+- Creating or updating `GRAPH.md`: additionally load `references/graph.md`
 
 ## Orchestration loop
 

package/skills/flow/references/graph.md

@@ -0,0 +1,62 @@
+# `GRAPH.md` Rules
+
+Every Flow `GRAPH.md` must be a derived, human-readable projection of
+`.flow/BACKLOG.yaml`. It never becomes an independent source of truth.
+
+## Card content
+
+Each Mermaid card contains exactly two lines:
+
+```text
+<work-item ID>
+<work-item title>
+```
+
+Do not include status, priority, folder, dependency lists, or explanatory
+prose inside a card. The title is the canonical `title` value from
+`BACKLOG.yaml`.
+
+## Status derivation and colors
+
+Derive status from the backlog and dependencies after every meaningful state
+transition.
+
+| Status | Meaning | Card color | Outgoing arrow style |
+| --- | --- | --- | --- |
+| Complete | Work item is accepted and complete. | Green (`#16a34a`) | Solid green |
+| In progress | Work item has active execution. | Blue (`#2563eb`) | Solid blue, thicker |
+| Pending | Every dependency is complete and the item is ready to start. | Yellow (`#d97706`) | Dashed yellow |
+| Blocked | The item is neither complete nor in progress and one or more dependencies are incomplete. | Red (`#dc2626`) | Dotted red |
+
+Use matching fill, stroke, and readable text colors for cards. Every graph
+must include a titled status legend using these colors.
+
+## Dependencies and arrows
+
+- Draw one arrow for every `depends_on` relationship in `BACKLOG.yaml`.
+- The arrow goes from dependency to dependent item.
+- Every outgoing arrow inherits the color and line style of its source card.
+- Recalculate Mermaid `linkStyle` indexes whenever edges change; do not leave
+  a stale style assignment behind.
+- Do not add visual-only dependency edges to force layout.
+
+## Parallelism and layout
+
+- Items on the same vertical rank must have no dependency on one another and
+  are candidates for parallel work.
+- Keep independent, ready items on the same vertical rank where Mermaid can
+  represent the real dependency graph without artificial edges.
+- Do not represent blocked items as pending merely because they are planned;
+  dependency readiness determines their graph status.
+
+## Synchronization checklist
+
+When work-item state, existence, title, or dependencies change:
+
+1. Update `BACKLOG.yaml` first.
+2. Recompute derived statuses using the definitions above.
+3. Update `GRAPH.md`, including cards, arrows, styles, legend, and parallel
+   layout.
+4. Update `STATE.md` when the active path or next ready work changes.
+5. Verify that every backlog item appears exactly once and every dependency
+   appears exactly once in the graph.

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'));