@caiqueoak/flow 0.5.2 → 0.6.0

package/README.md

@@ -44,15 +44,16 @@ Persist only pending, in_progress and completed. Ready/Blocked are derived exclu
 
 All commands use the local installation:
 
-| Command                                 | Purpose                                                                     |
-| --------------------------------------- | --------------------------------------------------------------------------- |
-| `npx --no-install flow init`            | Configure or add/refresh runtime integrations.                              |
-| `npx --no-install flow migrate`         | Atomic structural migration, followed by semantic reconciliation via /flow. |
-| `npx --no-install flow status`          | Progress and dependency/external blockers.                                  |
-| `npx --no-install flow validate`        | Artifact integrity, approvals, DAGs, traceability and deterministic gates.  |
-| `npx --no-install flow route --json`    | Next legal step and required context.                                       |
-| `npx --no-install flow graph`           | Regenerate dependency graph.                                                |
-| `npx --no-install flow trace W015-T003` | Resolve a task's implementation commit.                                     |
+| Command                                  | Purpose                                                                     |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `npx --no-install flow init`             | Configure or add/refresh runtime integrations.                              |
+| `npx --no-install flow migrate`          | Atomic structural migration, followed by semantic reconciliation via /flow. |
+| `npx --no-install flow status`           | Progress and dependency/external blockers.                                  |
+| `npx --no-install flow validate`         | Fast artifact integrity, approvals, DAGs and traceability checks.           |
+| `npx --no-install flow validate --gates` | Full validation, including configured deterministic project gates.          |
+| `npx --no-install flow route --json`     | Next legal step and required context.                                       |
+| `npx --no-install flow graph`            | Regenerate dependency graph.                                                |
+| `npx --no-install flow trace W015-T003`  | Resolve a task's implementation commit.                                     |
 
 Use `--help` for options; `--path` selects a project. Existing managed projects cannot change engineering through init; use /flow and approval. Older config is refused without mutation and must be migrated first. Update with your package manager, then rerun init to refresh integrations; there is no separate update/config/gates workflow command.
 

package/package.json

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

package/src/cli.mjs

@@ -19,7 +19,19 @@ const commands = {
 };
 
 function help() {
-  info(
+  const commandHelp = (message) =>
+    info(
+      message
+        .replace(
+          'validate   Check schemas, approvals, DAGs, traceability and deterministic gates.',
+          'validate   Check schemas, approvals, DAGs and traceability; --gates runs project checks.'
+        )
+        .replace(
+          'validate options: --json --pre-commit W015-T003',
+          'validate options: --json --gates --pre-commit W015-T003'
+        )
+    );
+  commandHelp(
     `Flow ${packageManifest.version}\n\nUse the project-local installation: npx --no-install flow <command>\n\nCommands:\n  init       Configure Flow and install/refresh local agent integrations.\n  migrate    Normalize older artifacts; /flow then reconciles legacy decisions.\n  status     Show progress and dependency/external blockers.\n  validate   Check schemas, approvals, DAGs, traceability and deterministic gates.\n  graph      Regenerate the derived work-item dependency graph.\n  route      Return the next repository-resumable agent step (--json available).\n  trace      Resolve W015-T003 to a HEAD-reachable commit with both Flow trailers.\n\nCommon options: --path <project>, --help, --version\ninit options: --runtime codex,claude --profile readability-first --existing-code improve|preserve\n  Readability First: reusable preferences for SRP, semantic naming, cohesion and simple vertical slices.\n  improve: recommend clearer structure while retaining behavior and external contracts.\n  preserve: retain consistent existing conventions unless a concrete problem warrants change.\n  Neither option authorizes refactoring; engineering changes require human approval.\nvalidate options: --json --pre-commit W015-T003\ntrace options: W015-T003 --json\n\nDiscovery → PRD approval → engineering approval → complete backlog → implementation-plan approval → serial implementation → review.\nUse /flow for agent workflows and engineering changes. Approved engineering.md is authoritative.\nUpdate the npm package with your package manager, then rerun init to refresh integrations.`
   );
 }

package/src/commands/gates.mjs

@@ -61,8 +61,11 @@ export function evaluateGates(root) {
   if (!fs.existsSync(file)) fail('gates.yaml does not exist.');
   const { gates } = parseGates(fs.readFileSync(file, 'utf8'));
   return gates.map((gate) => {
-    if (gate.kind === 'command') return runCommandGate(root, gate);
-    if (gate.kind === 'builtin') return runBuiltinGate(root, gate);
-    throw new Error(`Unsupported gate kind '${gate.kind}'.`);
+    const startedAt = performance.now();
+    let result;
+    if (gate.kind === 'command') result = runCommandGate(root, gate);
+    else if (gate.kind === 'builtin') result = runBuiltinGate(root, gate);
+    else throw new Error(`Unsupported gate kind '${gate.kind}'.`);
+    return { ...result, duration_ms: Math.round(performance.now() - startedAt) };
   });
 }

package/src/commands/trace.mjs

@@ -5,32 +5,46 @@ import { projectRoot } from '../shared/project-path.mjs';
 export function traceTask(root, qualifiedTaskId) {
   if (!/^W\d{3,}-T\d{3,}$/.test(qualifiedTaskId))
     fail(`invalid qualified task ID '${qualifiedTaskId}'. Expected W015-T003.`);
+  return traceTasks(root, [qualifiedTaskId]).get(qualifiedTaskId);
+}
+
+export function traceTasks(root, qualifiedTaskIds) {
+  for (const qualifiedTaskId of qualifiedTaskIds)
+    if (!/^W\d{3,}-T\d{3,}$/.test(qualifiedTaskId))
+      fail(`invalid qualified task ID '${qualifiedTaskId}'. Expected W015-T003.`);
+  const requested = new Set(qualifiedTaskIds);
+  const matches = new Map([...requested].map((task) => [task, []]));
   let output;
   try {
-    output = execFileSync(
-      'git',
-      ['log', 'HEAD', '--fixed-strings', `--grep=Flow-Task: ${qualifiedTaskId}`, '--format=%H%x1f%s%x1f%B%x1e'],
-      { cwd: root, encoding: 'utf8' }
-    );
+    output = execFileSync('git', ['log', 'HEAD', '--format=%H%x1f%s%x1f%B%x1e'], {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: 50 * 1024 * 1024
+    });
   } catch {
     fail('git history is unavailable; task traceability requires a Git repository.');
   }
-  const trailerPattern = new RegExp(`^Flow-Task:\\s*${qualifiedTaskId}\\s*$`, 'm');
-  const matches = output
+  for (const entry of output
     .split('\x1e')
     .filter(Boolean)
     .map((record) => {
       const [sha, subject, ...bodyParts] = record.replace(/^\n+|\n+$/g, '').split('\x1f');
       return { sha, subject, body: bodyParts.join('\x1f') };
+    })) {
+    const workItems = new Set([...entry.body.matchAll(/^Flow-Work-Item:\s*(W\d{3,})\s*$/gm)].map((match) => match[1]));
+    for (const match of entry.body.matchAll(/^Flow-Task:\s*(W\d{3,}-T\d{3,})\s*$/gm)) {
+      const task = match[1];
+      if (requested.has(task) && workItems.has(task.split('-')[0])) matches.get(task).push(entry);
+    }
+  }
+  return new Map(
+    [...requested].map((task) => {
+      const commits = matches.get(task);
+      if (!commits.length) return [task, { task, commits, status: 'missing' }];
+      if (commits.length > 1) return [task, { task, commits, status: 'ambiguous' }];
+      return [task, { task, commit: commits[0], commits, status: 'resolved' }];
     })
-    .filter(
-      (entry) =>
-        trailerPattern.test(entry.body) &&
-        new RegExp(`^Flow-Work-Item:\\s*${qualifiedTaskId.split('-')[0]}\\s*$`, 'm').test(entry.body)
-    );
-  if (!matches.length) return { task: qualifiedTaskId, commits: [], status: 'missing' };
-  if (matches.length > 1) return { task: qualifiedTaskId, commits: matches, status: 'ambiguous' };
-  return { task: qualifiedTaskId, commit: matches[0], commits: matches, status: 'resolved' };
+  );
 }
 
 export function runTrace({ args }) {

package/src/commands/validate.mjs

@@ -10,11 +10,14 @@ import { parseGates } from '../artifacts/gates.mjs';
 import { validateEngineeringDocument } from '../artifacts/engineering.mjs';
 import { validatePrdDocument } from '../artifacts/prd.mjs';
 import { validateImplementationPlan } from '../artifacts/implementation-plan.mjs';
-import { traceTask } from './trace.mjs';
+import { traceTasks } from './trace.mjs';
 import { generateGraphMarkdown } from './graph.mjs';
 import { evaluateGates } from './gates.mjs';
 
-export function validateProject(root, { preCommitTask = null, skipTrace = false } = {}) {
+export function validateProject(
+  root,
+  { preCommitTask = null, skipTrace = false, evaluateConfiguredGates = false, onGateResults } = {}
+) {
   const findings = [];
   const error = (code, message) => findings.push({ level: 'error', code, message });
   const flow = path.join(root, '.flow');
@@ -81,6 +84,7 @@ export function validateProject(root, { preCommitTask = null, skipTrace = false
   }
   const byId = new Map(backlog.work_items.map((item) => [item.id, item]));
   let activeTasks = 0;
+  const traceCandidates = [];
   for (const item of backlog.work_items) {
     const base = `work-items/${item.folder}`;
     const missing = ['spec.md', 'tasks.yaml'].filter((name) => !exists(`${base}/${name}`));
@@ -130,26 +134,32 @@ export function validateProject(root, { preCommitTask = null, skipTrace = false
         if (item.state !== 'pending' && plan.status !== 'approved') error('PLAN', `${item.id}: plan is not approved.`);
       }
     }
-    for (const task of tasks.tasks) {
-      if (task.state !== 'completed' || task.implementation !== 'commit' || skipTrace) continue;
-      const qualified = qualifiedTaskId(item.id, task.id);
-      if (qualified === preCommitTask) continue;
-      try {
-        if (traceTask(root, qualified).status !== 'resolved')
-          error('TRACE', `${qualified}: expected exactly one HEAD-reachable commit with both Flow trailers.`);
-      } catch (failure) {
-        error('TRACE', failure.message);
+    for (const task of tasks.tasks)
+      if (task.state === 'completed' && task.implementation === 'commit' && !skipTrace) {
+        const qualified = qualifiedTaskId(item.id, task.id);
+        if (qualified !== preCommitTask) traceCandidates.push(qualified);
       }
+  }
+  if (traceCandidates.length) {
+    try {
+      for (const [qualified, result] of traceTasks(root, traceCandidates))
+        if (result.status !== 'resolved')
+          error('TRACE', `${qualified}: expected exactly one HEAD-reachable commit with both Flow trailers.`);
+    } catch (failure) {
+      for (const qualified of traceCandidates) error('TRACE', `${qualified}: ${failure.message}`);
     }
   }
   if (activeTasks > 1) error('STATE', 'Only one mutating task may be active across the project.');
   if (exists('gates.yaml')) {
     try {
       parseGates(read('gates.yaml'));
-      if (!migrationPending)
-        for (const gate of evaluateGates(root))
+      if (!migrationPending && evaluateConfiguredGates) {
+        const gateResults = evaluateGates(root);
+        onGateResults?.(gateResults);
+        for (const gate of gateResults)
           if (gate.blocking && ['failed', 'unsupported'].includes(gate.status))
             error('GATE', `${gate.id}: ${gate.status}`);
+      }
     } catch (failure) {
       error('GATES', failure.message);
     }
@@ -160,12 +170,24 @@ export function validateProject(root, { preCommitTask = null, skipTrace = false
 }
 export function runValidate({ args }) {
   const index = args.indexOf('--pre-commit');
+  const includeGates = args.includes('--gates');
+  let gateResults = [];
   const findings = validateProject(projectRoot(args), {
     preCommitTask: index < 0 ? null : args[index + 1],
-    skipTrace: args.includes('--skip-trace')
+    skipTrace: args.includes('--skip-trace'),
+    evaluateConfiguredGates: includeGates,
+    onGateResults: (results) => {
+      gateResults = results;
+    }
   });
   if (args.includes('--json')) {
-    info(JSON.stringify({ valid: findings.length === 0, findings }, null, 2));
+    info(
+      JSON.stringify(
+        { valid: findings.length === 0, findings, ...(includeGates ? { gates: gateResults } : {}) },
+        null,
+        2
+      )
+    );
     if (findings.length) process.exitCode = 1;
     return;
   }

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