@caiqueoak/flow 0.5.3 → 0.7.0

package/README.md

@@ -30,9 +30,9 @@ PRD, engineering and plans use YAML frontmatter with `schema_version: 1`, `statu
 ## Canonical artifacts
 
 - `config.yaml`: runtime/bootstrap preferences; installed package metadata owns version.
-- `docs/prd.md`: product truth; `docs/engineering.md`: approved engineering truth.
+- `docs/prd.md`: global, cross-work-item product truth and learner-visible constraints; `docs/engineering.md`: approved global technical/code/infra truth.
 - `backlog.yaml`: schema 2, W### IDs, W###-kebab-case folders, kinds, priority, dependency DAG and lifecycle.
-- `work-items/W###-slug/spec.md`: bounded scope and decisions; `tasks.yaml`: schema 1, work_item, local T### task DAG.
+- `work-items/W###-slug/spec.md`: bounded scope, delivery decisions, and acceptance for one work item; it references applicable PRD rules without redefining them. `tasks.yaml`: schema 1, work_item, local T### task DAG.
 - `implementation-plan.md`: human-approved implementation approach.
 - `state.yaml`: resume cursor and migration reconciliation status.
 - `gates.yaml`: schema 1, command/builtin checks only; qualitative judgment remains review instructions.
@@ -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.3",
+  "version": "0.7.0",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {

package/skills/flow/SKILL.md

@@ -10,12 +10,12 @@ description: Repository-resumable software delivery through discovery, approved
 Read invariants.md once per invocation. All Flow CLI commands MUST use the project-local installation: `npx --no-install flow`. If unavailable, stop and ask for local installation; never use a global executable or fetch a different package automatically.
 
 1. Run `npx --no-install flow route --json`.
-2. Read the returned instruction from this installed skill and every returned required_context file. Planning, implementation and review require rereading the FULL .flow/docs/engineering.md immediately before that step, including after resumption.
+2. Read the returned instruction from this installed skill and every returned required_context file. Planning, implementation and review require rereading the FULL `.flow/docs/engineering.md` immediately before that step, including after resumption. For a selected work item, use the PRD only for applicable global product rules and use its spec for the bounded delivery scope.
 3. Execute only the routed step, persist canonical artifacts and run its required checks.
 4. Route again. Continue until an actual human decision, external action, unrecoverable blocker or completion.
 
 If stopped for approval, present the exact proposal and ask explicitly. Never approve your own work or treat silence as consent. Human approval must be persisted with status: approved and approved_at: ISO timestamp in the approved document. Clear state.stop_reason only when the current message resolves its decision. Revisions require a new approval, not copying an old approved_at.
 
-Artifact owners: docs/prd.md product; docs/engineering.md engineering; backlog.yaml work-item DAG; work-items/W###-slug/spec.md scope; tasks.yaml task DAG; implementation-plan.md approved approach; state.yaml cursor; gates.yaml mechanical checks; docs/graph.md derived. Preserve completed history; changed completed scope becomes new maintenance work.
+Artifact owners: `docs/prd.md` owns global, cross-work-item product rules and learner-visible constraints; `docs/engineering.md` owns global technical, code, infrastructure, and pattern constraints; `backlog.yaml` owns the work-item DAG; `work-items/W###-slug/spec.md` owns only bounded scope, acceptance, and decisions for that work item, referencing applicable PRD rules without redefining them; `tasks.yaml` owns the task DAG; `implementation-plan.md` owns the approved approach; `state.yaml` owns the cursor; `gates.yaml` owns mechanical checks; `docs/graph.md` is derived. Preserve completed history; changed completed scope becomes new maintenance work.
 
 Engineering changes go through reconcile/step-01-reconcile.md: propose the change, obtain approval and invalidate affected plans. A profile is bootstrap input, never a second policy engine competing with approved engineering.

package/skills/flow/build/step-01-execute-task.md

@@ -1,6 +1,6 @@
 # Build — execute one approved task
 
-Read the FULL engineering.md, spec, tasks and approved current implementation plan. Verify current route and approval hashes before application edits. Persist both selected work item and task in_progress; no other mutating task may be active.
+Read the applicable global PRD rules, the FULL engineering.md, spec, tasks and approved current implementation plan. Verify current route and approval hashes before application edits. Persist both selected work item and task in_progress; no other mutating task may be active.
 
 Implement the bounded approved change for readability: semantic naming, mandatory SRP, low coupling, high cohesion, locality and justified complexity. If the approach must change materially, revise the plan and ask approval before continuing.
 

package/skills/flow/discovery/step-01-project.md

@@ -1,5 +1,5 @@
 # Discovery — define product
 
-Read current intent and existing product evidence. Create .flow/docs/prd.md as a coherent proposal, not architecture. Frontmatter: schema_version: 1, status: draft. Headings: # Product Requirements; ## Purpose; ## Users; ## Scope; ## Requirements; ## Constraints; ## Non-goals.
+Read current intent and existing product evidence. Create `.flow/docs/prd.md` as a coherent proposal for global, cross-work-item product rules and learner-visible constraints, not architecture or work-item implementation detail. Frontmatter: schema_version: 1, status: draft. Headings: # Product Requirements; ## Purpose; ## Users; ## Scope; ## Requirements; ## Constraints; ## Non-goals.
 
 Create state.yaml with schema_version: 1, execution.phase: discovery, active.work_item/task: null, stop_reason: null, migration.status: not_required. Do not create incomplete work-item folders or implement code. Present scope and ask PRD approval through the next routed step.

package/skills/flow/engineering/step-02-synthesize.md

@@ -2,7 +2,7 @@
 
 Read the approved PRD, config, full existing engineering evidence, repository tooling/contracts, profiles/readability-first.md and technology-defaults.md. Use existing_code_policy improve to critique accidental structure while preserving behavior; preserve gives consistent patterns stronger weight. Neither authorizes refactoring.
 
-Recommend a complete but proportional contract. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
+Recommend a complete but proportional technical contract. Keep global product behavior in the PRD and bounded delivery behavior in work-item specs; engineering records only the technical/code/infra constraints that realize them. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
 
 # Engineering
 

package/skills/flow/planning/step-01-plan-work-item.md

@@ -2,7 +2,7 @@
 
 Reread the FULL approved engineering.md and PRD. Decompose all known approved scope into bounded work items and dependencies; do not invent future scope. Create backlog.yaml schema_version: 2, work_items with id W###, folder W###-kebab-case, kind feature|technical|maintenance, title, state pending, priority positive integer, depends_on and blockers.
 
-Create EVERY known work-item folder with spec.md and tasks.yaml before implementation. Existing completed artifacts stay intact. Specs include ## Status, ## Goal, ## Scope, ## Non-goals, ## Requirements, ## Acceptance criteria, ## Decisions, ## Implementation, ## Final outcome, ## Validation and ## Follow-up. Tasks: schema_version: 1, work_item: W###, tasks with local T### IDs, title, state pending, depends_on, implementation commit|none. Preserve already completed task history.
+Create EVERY known work-item folder with spec.md and tasks.yaml before implementation. Existing completed artifacts stay intact. Each spec owns only its bounded scope, delivery decisions, and acceptance; reference applicable global PRD rules rather than copying or redefining them. Specs include ## Status, ## Goal, ## Scope, ## Non-goals, ## Requirements, ## Acceptance criteria, ## Decisions, ## Implementation, ## Final outcome, ## Validation and ## Follow-up. Tasks: schema_version: 1, work_item: W###, tasks with local T### IDs, title, state pending, depends_on, implementation commit|none. Preserve already completed task history.
 
 Structured blockers: id stable-kebab-case, type external_action|consequential_decision, description, status unresolved|resolved. Do not encode dependencies as external blockers.
 

package/skills/flow/planning/step-02-prepare-plan.md

@@ -1,6 +1,6 @@
 # Planning — draft an implementation plan
 
-Reread the FULL approved engineering.md, selected spec/tasks, affected code and tests. Write implementation-plan.md BEFORE application edits. Frontmatter: schema_version: 1, work_item: W###, status: draft, engineering_revision and spec_revision SHA256 of the exact UTF-8 files. Calculate with Node crypto; never guess.
+Reread the applicable global PRD rules, the FULL approved engineering.md, selected spec/tasks, affected code and tests. The PRD supplies product constraints; the spec supplies only this work item's bounded delivery scope. Write implementation-plan.md BEFORE application edits. Frontmatter: schema_version: 1, work_item: W###, status: draft, engineering_revision and spec_revision SHA256 of the exact UTF-8 files. Calculate with Node crypto; never guess.
 
 Use exact headings:
 

package/skills/flow/review/step-01-review-work-item.md

@@ -1,5 +1,5 @@
 # Review — verify delivery
 
-Reread FULL engineering.md, frozen scope, tasks and approved plan. Review acceptance, regressions, SRP, semantic naming, low coupling/high cohesion, vertical-slice locality and complexity ROI. Explain concrete defects, not stylistic alternatives. Run actual tests and npx --no-install flow validate; never write fake gate evidence.
+Reread applicable global PRD rules, FULL engineering.md, frozen scope, tasks and approved plan. Review acceptance, regressions, SRP, semantic naming, low coupling/high cohesion, vertical-slice locality and complexity ROI. Explain concrete defects, not stylistic alternatives. Run actual tests and npx --no-install flow validate; never write fake gate evidence.
 
 Defects become new fix tasks. Material approach changes require revised plan approval; never rewrite completed task history. Complete only after all tasks, acceptance, gates, qualitative review and traceability pass. Populate spec outcome/implementation/validation; synchronize backlog/state/graph, validate and route again.

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/route.mjs

@@ -94,7 +94,12 @@ export function routeProject(root) {
       reason: backlog.work_items.every((item) => item.state === 'completed') ? 'finished' : 'external_action'
     };
   const base = `work-items/${item.folder}`;
-  const context = ['.flow/docs/engineering.md', `.flow/${base}/spec.md`, `.flow/${base}/tasks.yaml`];
+  const context = [
+    '.flow/docs/prd.md',
+    '.flow/docs/engineering.md',
+    `.flow/${base}/spec.md`,
+    `.flow/${base}/tasks.yaml`
+  ];
   const tasks = parseTasks(read(`${base}/tasks.yaml`), { expectedWorkItem: item.id });
   const extra = { work_item: item.id, required_context: context };
   const prepare = () => step('work_item_plan_approval', 'planning/step-02-prepare-plan.md', extra);

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;
   }