@davidorex/pi-workflows 0.6.1 → 0.9.0

package/schemas/resolution-assessment.schema.json

@@ -0,0 +1,36 @@
+{
+	"type": "object",
+	"required": ["resolved", "verdict", "resolution_summary", "evidence"],
+	"properties": {
+		"resolved": {
+			"type": "boolean",
+			"description": "true if the implementation addresses the gap's described root cause"
+		},
+		"verdict": {
+			"type": "string",
+			"enum": ["resolved", "partially_resolved", "not_resolved", "checks_failed"],
+			"description": "Categorical verdict"
+		},
+		"resolution_summary": {
+			"type": "string",
+			"description": "What was done and why it addresses (or fails to address) the gap — references specific changes"
+		},
+		"evidence": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["claim", "source"],
+				"properties": {
+					"claim": { "type": "string" },
+					"source": { "type": "string", "description": "File path, diff, or test output supporting the claim" }
+				}
+			},
+			"description": "Observable evidence supporting the verdict"
+		},
+		"unresolved_aspects": {
+			"type": "array",
+			"items": { "type": "string" },
+			"description": "Specific aspects of the gap that remain unaddressed (empty if fully resolved)"
+		}
+	}
+}

package/skills/pi-workflows/SKILL.md

@@ -78,7 +78,7 @@ Subcommands: `init`, `list`, `run`, `resume`, `validate`, `status`, `help`
 </keyboard_shortcuts>
 
 <bundled_resources>
-21 agents, 11 schemas, 14 workflows, 28 templates bundled.
+24 agents, 14 schemas, 14 workflows, 31 templates bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 

package/skills/pi-workflows/references/bundled-resources.md

@@ -1,13 +1,16 @@
 # Bundled Resources
 
-## agents/ (21 files)
+## agents/ (24 files)
 
 - `agents/architecture-designer.agent.yaml`
 - `agents/architecture-inferrer.agent.yaml`
+- `agents/audit-finding-verifier.agent.yaml`
 - `agents/audit-fixer.agent.yaml`
+- `agents/audit-results-router.agent.yaml`
 - `agents/code-explorer.agent.yaml`
 - `agents/decomposer.agent.yaml`
 - `agents/gap-identifier.agent.yaml`
+- `agents/gap-resolution-assessor.agent.yaml`
 - `agents/handoff-writer.agent.yaml`
 - `agents/investigator.agent.yaml`
 - `agents/pattern-analyzer.agent.yaml`
@@ -24,16 +27,19 @@
 - `agents/synthesizer.agent.yaml`
 - `agents/verifier.agent.yaml`
 
-## schemas/ (11 files)
+## schemas/ (14 files)
 
+- `schemas/audit-routing-manifest.schema.json`
 - `schemas/decomposition-specs.schema.json`
 - `schemas/execution-results.schema.json`
+- `schemas/finding-verification.schema.json`
 - `schemas/investigation-findings.schema.json`
 - `schemas/pattern-analysis.schema.json`
 - `schemas/phase.schema.json`
 - `schemas/plan-breakdown.schema.json`
 - `schemas/quality-analysis.schema.json`
 - `schemas/research-findings.schema.json`
+- `schemas/resolution-assessment.schema.json`
 - `schemas/structure-analysis.schema.json`
 - `schemas/synthesis.schema.json`
 - `schemas/verifier-output.schema.json`
@@ -55,7 +61,7 @@
 - `workflows/self-implement.workflow.yaml`
 - `workflows/typed-analysis.workflow.yaml`
 
-## templates/ (28 files)
+## templates/ (31 files)
 
 - `templates/analyzers/base-analyzer.md`
 - `templates/analyzers/macros.md`
@@ -67,11 +73,14 @@
 - `templates/analyzers/structure.md`
 - `templates/architecture-designer/task.md`
 - `templates/architecture-inferrer/task.md`
+- `templates/audit-finding-verifier/task.md`
 - `templates/audit-fixer/task.md`
+- `templates/audit-results-router/task.md`
 - `templates/decomposer/task.md`
 - `templates/explorer/system.md`
 - `templates/explorer/task.md`
 - `templates/gap-identifier/task.md`
+- `templates/gap-resolution-assessor/task.md`
 - `templates/handoff-writer/task.md`
 - `templates/investigator/task.md`
 - `templates/phase-author/task.md`

package/templates/audit-finding-verifier/task.md

@@ -0,0 +1,59 @@
+Verify whether the following audit findings have been resolved.
+
+## Audit Findings
+
+{% for finding in audit.findings %}
+### Finding: {{ finding.id }}
+
+**Description**: {{ finding.description }}
+**Severity**: {{ finding.severity | default("unspecified") }}
+**Category**: {{ finding.category | default("unspecified") }}
+**Principle**: {{ finding.principle | default("unspecified") }}
+
+**Locations**:
+{% for loc in finding.locations %}
+- `{{ loc.file }}` {% if loc.line %}line {{ loc.line }}{% endif %} {% if loc.description %} — {{ loc.description }}{% endif %}
+{% endfor %}
+
+{% if finding.fix %}
+**Fix suggestion**: {{ finding.fix.suggestion | default("none") }}
+{% endif %}
+
+{% if finding.resolution and finding.resolution.status == 'passed' %}
+*Previously marked as resolved — re-verify.*
+{% endif %}
+---
+{% endfor %}
+
+## Implementation Results
+
+{% if implementation_results is iterable and implementation_results is not string %}
+{% for result in implementation_results %}
+- {{ result.spec_name | default(result.name | default("task")) }}: {{ result.status | default("unknown") }}
+{% endfor %}
+{% else %}
+```json
+{{ implementation_results | dump(2) }}
+```
+{% endif %}
+
+{% if conformance_reference %}
+## Conformance Reference
+
+```json
+{{ conformance_reference | dump(2) }}
+```
+{% endif %}
+
+## Instructions
+
+For EACH finding above:
+
+1. Read the code at the referenced location(s)
+2. Determine if the finding's described issue is addressed
+3. Record your verdict: `passed`, `failed`, or `needs_inspect`
+4. Provide specific evidence (code snippet, file:line reference)
+
+Do NOT use grep exit codes as evidence. Read the code and assess whether the issue described in the finding is genuinely resolved.
+
+Produce JSON output with a `findings` array containing one entry per finding, plus summary statistics.

package/templates/audit-results-router/task.md

@@ -0,0 +1,37 @@
+Review the audit fix results and produce a routing manifest.
+
+## Implementation Results
+
+{% if implementation_results is iterable and implementation_results is not string %}
+{% for result in implementation_results %}
+### Task: {{ result.spec_name | default(result.name | default("unnamed")) }}
+
+- Status: {{ result.status | default("unknown") }}
+{% if result.decisions %}
+- Decisions: {{ result.decisions | length }}
+{% endif %}
+{% if result.issues %}
+- Issues flagged: {{ result.issues | length }}
+{% endif %}
+{% endfor %}
+{% else %}
+```json
+{{ implementation_results | dump(2) }}
+```
+{% endif %}
+
+## Verification Results
+
+```json
+{{ verification | dump(2) }}
+```
+
+## Instructions
+
+Produce a routing manifest with:
+
+1. **decisions** — validated decisions from implementation results (with complete id, description, rationale fields)
+2. **new_gaps** — genuine issues that should be tracked (with stable id, description, status: "open", category, priority)
+3. **summary** — accurate summary of what was completed, what failed, what needs inspection
+
+Only include items that are well-formed and represent genuine project artifacts. Do not route items that are missing required fields or describe hypothetical concerns.

package/templates/gap-resolution-assessor/task.md

@@ -0,0 +1,48 @@
+Assess whether the implementation resolves this gap.
+
+## Gap
+
+**ID**: {{ gap.id }}
+**Description**: {{ gap.description }}
+**Category**: {{ gap.category | default("unspecified") }}
+**Priority**: {{ gap.priority | default("unspecified") }}
+
+## Investigation Findings
+
+```json
+{{ investigation | dump(2) }}
+```
+
+## Implementation Results
+
+{% if implementation_results is iterable and implementation_results is not string %}
+{% for result in implementation_results %}
+### Spec: {{ result.spec_name | default("unnamed") }}
+- Status: {{ result.status | default("unknown") }}
+- Files changed: {{ result.files_changed | default([]) | join(", ") }}
+{% if result.commit_hash %}- Commit: {{ result.commit_hash }}{% endif %}
+{% endfor %}
+{% else %}
+```json
+{{ implementation_results | dump(2) }}
+```
+{% endif %}
+
+## Check Results
+
+- Status: {{ check_results.status }}
+{% if check_results.errors | length > 0 %}
+- Errors:
+{% for err in check_results.errors %}
+  - {{ err }}
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+1. Read the gap description above. Understand what root cause it identifies.
+2. Examine the implementation results — what files were changed and what was the stated work.
+3. Run `git diff HEAD~{{ implementation_results | length | default(1) }}` (or appropriate range) to see actual code changes.
+4. Judge: do the code changes address the root cause described in the gap?
+5. If tests failed or lint errors exist, the gap is NOT resolved regardless of code quality.
+6. Produce your assessment as JSON.

package/templates/handoff-writer/task.md

@@ -2,27 +2,37 @@ Capture a handoff snapshot for the project at `{{ path }}`.
 
 ## Current Project State
 
-{% if project_state.project is defined %}
+{% if project_state.blocks_status %}
+### Block Availability
+
+| Block | Available |
+|-------|-----------|
+{% for name, available in project_state.blocks_status %}
+| {{ name }} | {{ "yes" if available else "NO — absent" }} |
+{% endfor %}
+{% endif %}
+
+{% if project_state.project %}
 ### Project
 **{{ project_state.project.name | default("unnamed") }}** — {{ project_state.project.description | default("no description") }}
 Status: {{ project_state.project.status | default("unknown") }}
 {% endif %}
 
-{% if project_state.phases is defined and project_state.phases | length > 0 %}
+{% if project_state.phases and project_state.phases | length > 0 %}
 ### Phases
 {% for phase in project_state.phases %}
 - Phase {{ phase.number | default(loop.index) }}: {{ phase.name | default("unnamed") }} ({{ phase.status | default("unknown") }})
 {% endfor %}
 {% endif %}
 
-{% if project_state.blockSummaries is defined %}
+{% if project_state.blockSummaries %}
 ### Block Summaries
 {% for block in project_state.blockSummaries %}
 - **{{ block.name }}**: {{ block.count | default("?") }} entries
 {% endfor %}
 {% endif %}
 
-{% if project_state.gaps is defined %}
+{% if project_state.gaps %}
 ### Open Gaps
 {% for gap in project_state.gaps %}
 {% if gap.status == "open" %}
@@ -31,14 +41,14 @@ Status: {{ project_state.project.status | default("unknown") }}
 {% endfor %}
 {% endif %}
 
-{% if project_state.decisions is defined %}
+{% if project_state.decisions %}
 ### Recent Decisions
 {% for decision in project_state.decisions %}
 - {{ decision.id | default("?") }}: {{ decision.description | default(decision.title | default("no description")) }}
 {% endfor %}
 {% endif %}
 
-{% if project_state.recentCommits is defined %}
+{% if project_state.recentCommits %}
 ### Recent Commits
 {% for commit in project_state.recentCommits %}
 - `{{ commit.sha | default("?") | truncate(7, true, "") }}` {{ commit.message | default("no message") }}

package/templates/phase-author/task.md

@@ -8,6 +8,7 @@
 - Phase {{ phase.number }}: {{ phase.name }} ({{ phase.status }})
 {% endfor %}
 
+{% if architecture and architecture.modules %}
 ## Current Architecture
 
 {% for module in architecture.modules %}
@@ -20,13 +21,17 @@
 {{ loop.index }}. **{{ stage.stage }}**: {{ stage.description }}
 {% endfor %}
 {% endif %}
+{% endif %}
 
+{% if conventions and conventions.rules %}
 ## Conventions
 
 {% for rule in conventions.rules %}
 - {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
 {% endfor %}
+{% endif %}
 
+{% if gaps %}
 ## Current Gaps
 
 {% for gap in gaps %}
@@ -34,13 +39,16 @@
 - [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
 {% endif %}
 {% endfor %}
+{% endif %}
 
+{% if inventory %}
 ## Current Inventory
 
 - Step types: {{ inventory.step_types | length }}
 - Agent specs: {{ inventory.agent_specs | length }}
 - Schemas: {{ inventory.schemas | length }}
 - Tests: {{ inventory.test_count }}
+{% endif %}
 
 ## Instructions
 

package/workflows/create-handoff.workflow.yaml

@@ -3,52 +3,73 @@ description: Capture current work context for session resume
 version: "1"
 
 steps:
-  load-state:
-    command: |
-      node -e "
-        const fs = require('fs');
-        const path = require('path');
-        const projectDir = '.project';
-        const state = {};
-
-        // Read project identity
-        try { state.project = JSON.parse(fs.readFileSync(path.join(projectDir, 'project.json'), 'utf-8')); } catch {}
+  load-blocks:
+    block:
+      read: [project, gaps, decisions, tasks]
+      optional: [project, gaps, decisions, tasks]
+    output:
+      format: json
 
-        // Read phase files
-        try {
-          const phasesDir = path.join(projectDir, 'phases');
-          state.phases = fs.readdirSync(phasesDir).filter(f => f.endsWith('.json')).map(f => {
-            try { return JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf-8')); } catch { return null; }
-          }).filter(Boolean);
-        } catch { state.phases = []; }
+  load-phases:
+    block:
+      readDir: phases
+    output:
+      format: json
 
-        // Read block summaries
-        try {
-          state.gaps = JSON.parse(fs.readFileSync(path.join(projectDir, 'gaps.json'), 'utf-8'));
-        } catch {}
-        try {
-          state.decisions = JSON.parse(fs.readFileSync(path.join(projectDir, 'decisions.json'), 'utf-8'));
-        } catch {}
+  load-git:
+    command: |
+      node -e "
+        const { execSync } = require('child_process');
+        const git = {};
         try {
-          state.tasks = JSON.parse(fs.readFileSync(path.join(projectDir, 'tasks.json'), 'utf-8'));
-        } catch {}
-
-        // Recent git activity
+          git.recent_commits = execSync('git log --oneline -10', { encoding: 'utf-8' }).trim().split('\n');
+        } catch (e) {
+          git.recent_commits = [];
+          git.commits_error = e.message || 'git log failed';
+        }
         try {
-          const { execSync } = require('child_process');
-          state.recent_commits = execSync('git log --oneline -10', { encoding: 'utf-8' }).trim().split('\n');
-          state.changed_files = execSync('git diff --name-only HEAD~3 2>/dev/null || echo \"\"', { encoding: 'utf-8' }).trim().split('\n').filter(Boolean);
-        } catch { state.recent_commits = []; state.changed_files = []; }
-
-        console.log(JSON.stringify(state));
+          git.changed_files = execSync('git diff --name-only HEAD~3 2>/dev/null || echo \"\"', { encoding: 'utf-8' }).trim().split('\n').filter(Boolean);
+        } catch (e) {
+          git.changed_files = [];
+          git.files_error = e.message || 'git diff failed';
+        }
+        console.log(JSON.stringify(git));
       "
     output:
       format: json
 
+  assemble-state:
+    command: |
+      node -e "
+        const blocks = JSON.parse(process.argv[1]);
+        const phases = JSON.parse(process.argv[2]);
+        const git = JSON.parse(process.argv[3]);
+        console.log(JSON.stringify({
+          project: blocks.project,
+          phases: phases,
+          gaps: blocks.gaps,
+          decisions: blocks.decisions,
+          tasks: blocks.tasks,
+          recentCommits: git.recent_commits || [],
+          changedFiles: git.changed_files || [],
+          blocks_status: {
+            project: blocks.project != null,
+            gaps: blocks.gaps != null,
+            decisions: blocks.decisions != null,
+            tasks: blocks.tasks != null,
+            phases: phases.length > 0,
+            git_commits: !git.commits_error,
+            git_files: !git.files_error
+          }
+        }));
+      " '${{ steps.load-blocks.output | json }}' '${{ steps.load-phases.output | json }}' '${{ steps.load-git.output | json }}'
+    output:
+      format: json
+
   capture:
     agent: handoff-writer
     input:
-      project_state: ${{ steps.load-state.output }}
+      project_state: ${{ steps.assemble-state.output }}
       path: "."
     output:
       format: json

package/workflows/create-phase.workflow.yaml

@@ -11,28 +11,16 @@ input:
       description: Unstructured intent from conversation — what needs to be built and why
 
 steps:
+  load-phases:
+    block:
+      readDir: phases
+    output:
+      format: json
+
   load-context:
-    command: |
-      node --experimental-strip-types -e "
-        import fs from 'fs';
-        import path from 'path';
-        const phasesDir = '.project/phases';
-        let phases = [];
-        try {
-          phases = fs.readdirSync(phasesDir)
-            .filter(f => f.endsWith('.json'))
-            .map(f => JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf8')));
-        } catch {}
-        let arch = {};
-        try { arch = JSON.parse(fs.readFileSync('.project/architecture.json', 'utf8')); } catch {}
-        let conv = {};
-        try { conv = JSON.parse(fs.readFileSync('.project/conventions.json', 'utf8')); } catch {}
-        let gapsData = { gaps: [] };
-        try { gapsData = JSON.parse(fs.readFileSync('.project/gaps.json', 'utf8')); } catch {}
-        let inv = {};
-        try { inv = JSON.parse(fs.readFileSync('.project/inventory.json', 'utf8')); } catch {}
-        console.log(JSON.stringify({ phases, architecture: arch, conventions: conv, gaps: gapsData.gaps, inventory: inv }));
-      "
+    block:
+      read: [architecture, conventions, gaps, inventory]
+      optional: [architecture, conventions, gaps, inventory]
     output:
       format: json
 
@@ -40,32 +28,39 @@ steps:
     agent: phase-author
     input:
       intent: "${{ input.intent }}"
-      phases: "${{ steps.load-context.output.phases }}"
+      phases: "${{ steps.load-phases.output }}"
       architecture: "${{ steps.load-context.output.architecture }}"
       conventions: "${{ steps.load-context.output.conventions }}"
-      gaps: "${{ steps.load-context.output.gaps }}"
+      gaps: "${{ steps.load-context.output.gaps.gaps }}"
       inventory: "${{ steps.load-context.output.inventory }}"
     output:
       format: json
       schema: block:phase
 
-  write-phase:
+  compute-phase-path:
     command: |
-      node --experimental-strip-types -e "
-        import fs from 'fs';
+      node -e "
         const phase = JSON.parse(process.argv[1]);
-        const filename = '.project/phases/' + String(phase.number).padStart(2, '0') + '-' + phase.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '') + '.json';
-        fs.mkdirSync('.project/phases', { recursive: true });
-        fs.writeFileSync(filename, JSON.stringify(phase, null, 2) + '\n');
-        console.log(JSON.stringify({ path: filename, phase_number: phase.number, spec_count: phase.specs.length }));
+        const num = String(phase.number).padStart(2, '0');
+        const name = phase.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/g, '');
+        console.log(JSON.stringify({ path: 'phases/' + num + '-' + name }));
       " '${{ steps.author.output | json }}'
     output:
       format: json
 
+  write-phase:
+    block:
+      write:
+        name: phase
+        data: "${{ steps.author.output }}"
+        path: "${{ steps.compute-phase-path.output.path }}"
+    output:
+      format: json
+
 completion:
   message: |
-    Phase ${{ steps.write-phase.output.phase_number }} created at ${{ steps.write-phase.output.path }}
-    Contains ${{ steps.write-phase.output.spec_count }} specs.
+    Phase ${{ steps.author.output.number }} created at ${{ steps.write-phase.output.path }}
+    Contains ${{ steps.author.output.specs | length }} specs.
   include:
     - steps.author.output.success_criteria
     - steps.author.output.specs