@davidorex/pi-workflows 0.1.0

package/workflows/fix-audit.workflow.yaml

@@ -0,0 +1,217 @@
+name: fix-audit
+description: Fix audit findings grouped by related clusters
+version: "1"
+
+steps:
+  load:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        const auditsDir = '.project/audits';
+        const files = fs.readdirSync(auditsDir).filter(f => f.endsWith('.json')).sort();
+        const latestFile = files[files.length - 1];
+        const auditPath = auditsDir + '/' + latestFile;
+        const audit = JSON.parse(fs.readFileSync(auditPath, 'utf8'));
+        let conformance_reference = null;
+        try { conformance_reference = JSON.parse(fs.readFileSync('.project/conformance-reference.json', 'utf8')); } catch {}
+        console.log(JSON.stringify({ audit, conformance_reference, audit_path: auditPath }));
+      "
+    output:
+      format: json
+
+  cluster:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        import { execSync } from 'child_process';
+        const audit = JSON.parse(fs.readFileSync('.project/audits/' + fs.readdirSync('.project/audits').filter(f => f.endsWith('.json')).sort().pop(), 'utf8'));
+
+        // Filter to findings that still need fixing (code is source of truth)
+        const findings = audit.findings.filter(f => {
+          if (!f.fix) return false;
+          if (f.fix.verify_method === 'grep' && f.fix.verify_pattern) {
+            try {
+              execSync('grep -rn ' + JSON.stringify(f.fix.verify_pattern) + ' ' + f.locations.map(l => l.file).join(' '), { stdio: 'pipe' });
+              return true;  // pattern still matches — needs fixing
+            } catch { return false; }  // pattern gone — already fixed
+          }
+          // inspect findings: check resolution field, skip if already resolved
+          if (f.resolution && f.resolution.status === 'passed') return false;
+          return true;  // no automated check — include it
+        });
+
+        if (findings.length === 0) {
+          console.log(JSON.stringify({ tasks: [], message: 'All findings already resolved' }));
+          process.exit(0);
+        }
+
+        const visited = new Set();
+        const tasks = [];
+        for (const f of findings) {
+          if (visited.has(f.id)) continue;
+          const cluster = [f];
+          visited.add(f.id);
+          if (f.related) {
+            for (const rid of f.related) {
+              if (!visited.has(rid)) {
+                const r = findings.find(x => x.id === rid);
+                if (r) { cluster.push(r); visited.add(rid); }
+              }
+            }
+          }
+          const files = [...new Set(cluster.flatMap(c => c.locations).map(l => l.file))];
+          tasks.push({
+            name: cluster[0].id,
+            findings: cluster,
+            files,
+            principle: cluster[0].principle,
+            category: cluster[0].category,
+            severity: cluster.some(c => c.severity === 'error') ? 'error' : cluster[0].severity,
+            acceptance_criteria: cluster.map(c => {
+              if (c.fix && c.fix.verify_method === 'grep' && c.fix.verify_pattern) return 'grep pattern should not match: ' + c.fix.verify_pattern + ' in ' + c.locations.map(l=>l.file).join(', ');
+              return 'Fix: ' + (c.fix?.suggestion || c.description);
+            })
+          });
+        }
+        console.log(JSON.stringify({ tasks }));
+      "
+    output:
+      format: json
+
+  implement:
+    forEach: "${{ steps.cluster.output.tasks }}"
+    as: task
+    agent: audit-fixer
+    input:
+      task: "${{ task }}"
+      conformance_reference: "${{ steps.load.output.conformance_reference }}"
+    output:
+      format: json
+      schema: schemas/execution-results.schema.json
+      path: .project/fix-audit-results.json
+
+  route-results:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        const raw = JSON.parse(fs.readFileSync('.project/fix-audit-results.json', 'utf8'));
+        const items = Array.isArray(raw) ? raw : [raw];
+
+        const decisionsPath = '.project/decisions.json';
+        if (fs.existsSync(decisionsPath)) {
+          const d = JSON.parse(fs.readFileSync(decisionsPath, 'utf8'));
+          const existingIds = new Set(d.decisions.map(x => x.id));
+          for (const r of items) {
+            for (const dec of r.decisions || []) {
+              if (!existingIds.has(dec.id)) { d.decisions.push(dec); existingIds.add(dec.id); }
+            }
+          }
+          fs.writeFileSync(decisionsPath, JSON.stringify(d, null, 2) + '\n');
+        }
+
+        const gapsPath = '.project/gaps.json';
+        if (fs.existsSync(gapsPath)) {
+          const g = JSON.parse(fs.readFileSync(gapsPath, 'utf8'));
+          const existingIds = new Set(g.gaps.map(x => x.id));
+          for (const r of items) {
+            for (const issue of r.issues || []) {
+              const id = 'issue-' + issue.description.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50);
+              if (!existingIds.has(id)) {
+                g.gaps.push({ id, description: issue.description, status: 'open', category: 'issue', priority: issue.severity === 'critical' ? 'high' : issue.severity === 'error' ? 'medium' : 'low', source: 'agent' });
+                existingIds.add(id);
+              }
+            }
+          }
+          fs.writeFileSync(gapsPath, JSON.stringify(g, null, 2) + '\n');
+        }
+
+        const invPath = '.project/inventory.json';
+        if (fs.existsSync(invPath)) {
+          const inv = JSON.parse(fs.readFileSync(invPath, 'utf8'));
+          let maxTests = inv.test_count || 0;
+          for (const r of items) { if (r.test_count && r.test_count > maxTests) maxTests = r.test_count; }
+          if (maxTests > inv.test_count) { inv.test_count = maxTests; fs.writeFileSync(invPath, JSON.stringify(inv, null, 2) + '\n'); }
+        }
+
+        const statePath = '.project/state.json';
+        if (fs.existsSync(statePath)) {
+          const s = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+          const lastCommit = items.filter(r => r.commit_hash).pop()?.commit_hash;
+          if (lastCommit) s.last_commit = lastCommit;
+          const maxTests = Math.max(...items.map(r => r.test_count || 0));
+          if (maxTests > 0) s.test_count = maxTests;
+          s.session.last_action = 'fix-audit workflow: ' + items.length + ' tasks completed';
+          fs.writeFileSync(statePath, JSON.stringify(s, null, 2) + '\n');
+        }
+
+        console.log(JSON.stringify({ routed: items.length, decisions_added: items.reduce((s,r) => s + (r.decisions?.length || 0), 0), issues_added: items.reduce((s,r) => s + (r.issues?.length || 0), 0) }));
+      "
+    output:
+      format: json
+
+  verify:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        import { execSync } from 'child_process';
+        const auditPath = '.project/audits/' + fs.readdirSync('.project/audits').filter(f => f.endsWith('.json')).sort().pop();
+        const audit = JSON.parse(fs.readFileSync(auditPath, 'utf8'));
+        const results = [];
+        for (const finding of audit.findings) {
+          const fix = finding.fix;
+          if (!fix) { results.push({ id: finding.id, status: 'skipped', reason: 'no fix defined' }); continue; }
+          if (fix.verify_method === 'grep' && fix.verify_pattern) {
+            try {
+              execSync('grep -rn ' + JSON.stringify(fix.verify_pattern) + ' ' + finding.locations.map(l => l.file).join(' '), { encoding: 'utf8' });
+              results.push({ id: finding.id, status: 'failed', reason: 'pattern still matches' });
+            } catch { results.push({ id: finding.id, status: 'passed' }); }
+          } else {
+            results.push({ id: finding.id, status: 'needs_inspect', reason: fix.verify_method });
+          }
+        }
+        const passed = results.filter(r => r.status === 'passed').length;
+        const failed = results.filter(r => r.status === 'failed').length;
+        const inspect = results.filter(r => r.status === 'needs_inspect').length;
+        const total = results.length;
+        const status = failed === 0 ? (inspect > 0 ? 'passed_with_inspect' : 'passed') : 'gaps_found';
+        console.log(JSON.stringify({ status, score: passed + '/' + total, passed, failed, needs_inspect: inspect, results }));
+      "
+    output:
+      format: json
+      path: .project/fix-audit-verify.json
+
+  update-audit:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        const auditPath = '.project/audits/' + fs.readdirSync('.project/audits').filter(f => f.endsWith('.json')).sort().pop();
+        const verifyPath = '.project/fix-audit-verify.json';
+        let verifyResults;
+        try { verifyResults = JSON.parse(fs.readFileSync(verifyPath, 'utf8')); } catch { console.log(JSON.stringify({ updated: null, reason: 'cannot read verify output' })); process.exit(0); }
+        const audit = JSON.parse(fs.readFileSync(auditPath, 'utf8'));
+        for (const vr of verifyResults.results || []) {
+          const finding = audit.findings.find(f => f.id === vr.id);
+          if (finding) {
+            finding.resolution = { status: vr.status, verified_at: new Date().toISOString() };
+          }
+        }
+        const passed = (verifyResults.results || []).filter(r => r.status === 'passed').length;
+        audit.summary.resolved = passed;
+        fs.writeFileSync(auditPath, JSON.stringify(audit, null, 2) + '\n');
+        console.log(JSON.stringify({ updated: auditPath, resolved: passed, total: audit.findings.length }));
+      "
+    output:
+      format: json
+
+  check:
+    when: "${{ steps.update-audit.output.updated }}"
+    gate:
+      check: "test '${{ steps.verify.output.failed }}' = '0'"
+      onFail: fail
+
+completion:
+  message: |
+    Audit fix workflow completed.
+    Verification: ${{ steps.verify.output.status }} (${{ steps.verify.output.score }})
+  include:
+    - steps.verify.output.results

package/workflows/gap-to-phase.workflow.yaml

@@ -0,0 +1,98 @@
+name: gap-to-phase
+description: Create a phase spec from a gap — loads gap context, enriches with project state, dispatches phase-author
+version: "1"
+
+input:
+  type: object
+  required: [gap_id]
+  properties:
+    gap_id:
+      type: string
+      description: ID of the gap to convert into a phase
+      source:
+        file: .project/gaps.json
+        array: gaps
+        filter: { status: open }
+        label: id
+        value: id
+
+steps:
+  load-gap:
+    command: |
+      node --experimental-strip-types -e "
+        import { readBlock } from './src/block-api.ts';
+        const gapId = process.argv[1];
+        const data = readBlock('.', 'gaps');
+        const gap = data.gaps.find(g => g.id === gapId);
+        if (!gap) { console.error('Gap not found: ' + gapId); process.exit(1); }
+        if (gap.status === 'resolved') { console.error('Gap already resolved: ' + gapId); process.exit(1); }
+        console.log(JSON.stringify({ gap }));
+      " '${{ input.gap_id }}'
+    output:
+      format: json
+
+  load-context:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        import path from 'path';
+        import { readBlock } from './src/block-api.ts';
+
+        const phases = [];
+        const phasesDir = '.project/phases';
+        if (fs.existsSync(phasesDir)) {
+          for (const f of fs.readdirSync(phasesDir).filter(f => f.endsWith('.json')).sort()) {
+            phases.push(JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf8')));
+          }
+        }
+
+        let architecture = {};
+        try { architecture = readBlock('.', 'architecture'); } catch {}
+        let conventions = {};
+        try { conventions = readBlock('.', 'conventions'); } catch {}
+        let gaps = { gaps: [] };
+        try { gaps = readBlock('.', 'gaps'); } catch {}
+        let inventory = {};
+        try { inventory = readBlock('.', 'inventory'); } catch {}
+
+        console.log(JSON.stringify({ phases, architecture, conventions, gaps: gaps.gaps.filter(g => g.status === 'open'), inventory }));
+      "
+    output:
+      format: json
+
+  author:
+    agent: phase-author
+    input:
+      intent: "Implement gap ${{ steps.load-gap.output.gap.id }}: ${{ steps.load-gap.output.gap.description }}"
+      gap: "${{ steps.load-gap.output.gap }}"
+      phases: "${{ steps.load-context.output.phases }}"
+      architecture: "${{ steps.load-context.output.architecture }}"
+      conventions: "${{ steps.load-context.output.conventions }}"
+      gaps: "${{ steps.load-context.output.gaps }}"
+      inventory: "${{ steps.load-context.output.inventory }}"
+    output:
+      format: json
+      schema: ../../.project/schemas/phase.schema.json
+
+  write-phase:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        const phase = JSON.parse(process.argv[1]);
+        const num = String(phase.number).padStart(2, '0');
+        const name = phase.name.toLowerCase().replace(/\s+/g, '-');
+        const filename = '.project/phases/' + num + '-' + name + '.json';
+        fs.mkdirSync('.project/phases', { recursive: true });
+        fs.writeFileSync(filename, JSON.stringify(phase, null, 2));
+        console.log(JSON.stringify({ path: filename, phase_number: phase.number, spec_count: (phase.specs || []).length }));
+      " '${{ steps.author.output | json }}'
+    output:
+      format: json
+
+completion:
+  message: |
+    Phase ${{ steps.write-phase.output.phase_number }} created: ${{ steps.write-phase.output.path }}
+    Specs: ${{ steps.write-phase.output.spec_count }}
+    From gap: ${{ input.gap_id }}
+  include:
+    - steps.author.output

package/workflows/parallel-analysis.workflow.yaml

@@ -0,0 +1,62 @@
+name: parallel-analysis
+description: Analyze a codebase from multiple angles concurrently, then synthesize findings
+version: "1"
+
+input:
+  type: object
+  required: [path]
+  properties:
+    path:
+      type: string
+      description: Path to analyze (file or directory)
+    focus:
+      type: string
+      description: Optional area of focus for the analysis
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  # These three steps have no mutual dependencies — they all depend only on
+  # 'explore'. The DAG will place them in the same execution layer and run
+  # them concurrently.
+  analyze-structure:
+    agent: structure-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  analyze-quality:
+    agent: quality-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  analyze-patterns:
+    agent: pattern-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  # This step depends on all three analyzers — it must wait for all to complete
+  synthesize:
+    agent: synthesizer
+    input:
+      structure: ${{ steps.analyze-structure.textOutput }}
+      quality: ${{ steps.analyze-quality.textOutput }}
+      patterns: ${{ steps.analyze-patterns.textOutput }}
+      focus: ${{ input.focus }}
+
+artifacts:
+  report:
+    path: latest-analysis.md
+    from: steps.synthesize.textOutput
+
+completion:
+  message: |
+    Present this code analysis report to the user. Highlight the most important
+    findings and any areas that need immediate attention.
+  include:
+    - steps.synthesize.textOutput

package/workflows/parallel-explicit.workflow.yaml

@@ -0,0 +1,42 @@
+name: parallel-explicit
+description: Demo of explicit parallel step syntax
+version: "1"
+
+input:
+  type: object
+  required: [path]
+  properties:
+    path:
+      type: string
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  analyzers:
+    parallel:
+      structure:
+        agent: structure-analyzer
+        input:
+          exploration: ${{ steps.explore.textOutput }}
+          path: ${{ input.path }}
+      quality:
+        agent: quality-analyzer
+        input:
+          exploration: ${{ steps.explore.textOutput }}
+          path: ${{ input.path }}
+
+  summary:
+    transform:
+      mapping:
+        structure: ${{ steps.analyzers.output.structure }}
+        quality: ${{ steps.analyzers.output.quality }}
+
+completion:
+  template: |
+    Analysis complete.
+
+    Structure: ${{ steps.analyzers.output.structure | json }}
+    Quality: ${{ steps.analyzers.output.quality | json }}

package/workflows/pausable-analysis.workflow.yaml

@@ -0,0 +1,44 @@
+name: pausable-analysis
+description: Multi-step analysis with deliberate pause point — demonstrates checkpoint/resume
+version: "1"
+
+input:
+  type: object
+  required: [path]
+  properties:
+    path:
+      type: string
+      description: Path to analyze
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  review-exploration:
+    pause: "Exploration complete. Review results, then press Ctrl+J or /workflow resume pausable-analysis to continue."
+
+  analyze-structure:
+    agent: structure-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  analyze-quality:
+    agent: quality-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  synthesize:
+    agent: synthesizer
+    input:
+      structure: ${{ steps.analyze-structure.textOutput }}
+      quality: ${{ steps.analyze-quality.textOutput }}
+
+completion:
+  message: |
+    Present this analysis report to the user.
+  include:
+    - steps.synthesize.textOutput

package/workflows/resumable-analysis.workflow.yaml

@@ -0,0 +1,42 @@
+name: resumable-analysis
+description: A multi-step analysis workflow that demonstrates checkpoint/resume
+version: "1"
+
+input:
+  type: object
+  required: [path]
+  properties:
+    path:
+      type: string
+      description: Path to analyze
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  analyze-structure:
+    agent: structure-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  analyze-quality:
+    agent: quality-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+
+  synthesize:
+    agent: synthesizer
+    input:
+      structure: ${{ steps.analyze-structure.textOutput }}
+      quality: ${{ steps.analyze-quality.textOutput }}
+
+completion:
+  message: |
+    Present this analysis report. Note whether this was a fresh run
+    or resumed from a prior checkpoint.
+  include:
+    - steps.synthesize.textOutput

package/workflows/self-implement.workflow.yaml

@@ -0,0 +1,63 @@
+name: self-implement
+description: Read project blocks, decompose into plans, implement, verify
+version: "1"
+
+input:
+  type: object
+  required: [phaseSpec, architecture, conventions]
+  properties:
+    phaseSpec:
+      type: object
+      description: Phase spec JSON block
+    architecture:
+      type: object
+      description: Architecture JSON block
+    conventions:
+      type: object
+      description: Conventions JSON block
+
+steps:
+  plan:
+    agent: plan-decomposer
+    input:
+      phase: "${{ input.phaseSpec }}"
+      architecture: "${{ input.architecture }}"
+      conventions: "${{ input.conventions }}"
+    output:
+      format: json
+      schema: schemas/plan-breakdown.schema.json
+
+  implement:
+    forEach: "${{ steps.plan.output.plans }}"
+    as: plan
+    agent: spec-implementer
+    input:
+      plan: "${{ plan }}"
+      architecture: "${{ input.architecture }}"
+      conventions: "${{ input.conventions }}"
+    output:
+      format: json
+      schema: schemas/execution-results.schema.json
+
+  verify:
+    agent: verifier
+    input:
+      criteria: "${{ input.phaseSpec.success_criteria }}"
+      step_output: "${{ steps.implement.output }}"
+    output:
+      format: json
+      schema: schemas/verifier-output.schema.json
+
+  check:
+    gate:
+      check: "echo '${{ steps.verify.output.status }}' | grep -q passed"
+      onFail: fail
+
+completion:
+  message: |
+    Self-implementation workflow completed.
+    Verification status: ${{ steps.verify.output.status }}
+    Score: ${{ steps.verify.output.score }}
+  include:
+    - steps.verify.output.gaps
+    - steps.verify.output.criteria_results

package/workflows/typed-analysis.workflow.yaml

@@ -0,0 +1,63 @@
+name: typed-analysis
+description: >
+  Codebase analysis with typed JSON data flow. Analyzers produce
+  schema-bound JSON. Synthesizer renders from typed data via templates.
+  Proves: YAML spec → template composition → typed output → template task → agent.
+version: "1"
+
+input:
+  type: object
+  required: [path]
+  properties:
+    path:
+      type: string
+      description: Path to analyze
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  analyze-structure:
+    agent: structure-analyzer
+    input:
+      exploration: ${{ steps.explore.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+      schema: schemas/structure-analysis.schema.json
+
+  analyze-quality:
+    agent: quality-analyzer
+    input:
+      exploration: ${{ steps.explore.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+      schema: schemas/quality-analysis.schema.json
+
+  analyze-patterns:
+    agent: pattern-analyzer
+    input:
+      exploration: ${{ steps.explore.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+      schema: schemas/pattern-analysis.schema.json
+
+  synthesize:
+    agent: synthesizer
+    input:
+      structure: ${{ steps.analyze-structure.output }}
+      quality: ${{ steps.analyze-quality.output }}
+      patterns: ${{ steps.analyze-patterns.output }}
+    output:
+      format: json
+      schema: schemas/synthesis.schema.json
+
+completion:
+  message: |
+    Present the analysis findings to the user.
+  include:
+    - steps.synthesize.output