@davidorex/pi-project-workflows 0.9.2 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davidorex/pi-project-workflows",
-	"version": "0.9.2",
+	"version": "0.10.1",
 	"description": "Pi extensions for structured project state, workflow orchestration, and behavior monitoring — single install for all three",
 	"license": "MIT",
 	"author": "David Ryan",
@@ -29,8 +29,8 @@
 		]
 	},
 	"dependencies": {
-		"@davidorex/pi-project": "^0.9.2",
-		"@davidorex/pi-workflows": "^0.9.2",
-		"@davidorex/pi-behavior-monitors": "^0.9.2"
+		"@davidorex/pi-project": "^0.10.1",
+		"@davidorex/pi-workflows": "^0.10.1",
+		"@davidorex/pi-behavior-monitors": "^0.10.1"
 	}
 }

package/skills/pi-behavior-monitors/SKILL.md

@@ -63,16 +63,20 @@ List patterns for a behavior monitor.
 </tools_reference>
 
 <commands_reference>
+<command name="/work-quality">
+On-demand work quality analysis
+</command>
+
 <command name="/monitors">
 Manage behavior monitors
 
-Subcommands: `on`, `off`, `help`, `fragility`, `response-style`
+Subcommands: `on`, `off`, `help`, `fragility`, `hedge`, `work-quality`
 </command>
 
 </commands_reference>
 
 <events>
-`session_start`, `session_switch`, `agent_end`, `turn_start`, `message_end`
+`session_start`, `agent_end`, `turn_start`, `message_end`, `turn_end`
 </events>
 
 <bundled_resources>
@@ -111,7 +115,7 @@ Built-in placeholders (always available, not in `classify.context`):
 - `every(N)` — Fire every Nth activation (counter resets when user text changes)
 - `tool(name)` — Fire only if specific named tool called since last user message
 
-**Events:** `message_end`, `turn_end`, `agent_end`, `command`
+**Events:** `message_end`, `turn_end`, `agent_end`, `command`, `tool_call`
 
 **Verdict Types:** `clean`, `flag`, `new`
 
@@ -205,9 +209,9 @@ A `.monitor.json` file conforms to `schemas/monitor.schema.json`:
     "on_flag": {
       "steer": "Fix the issue.",
       "write": {
-        "path": ".workflow/gaps.json",
+        "path": ".project/issues.json",
         "merge": "append",
-        "array_field": "gaps",
+        "array_field": "issues",
         "template": {
           "id": "monitor-{finding_id}",
           "description": "{description}",
@@ -238,7 +242,7 @@ A `.monitor.json` file conforms to `schemas/monitor.schema.json`:
 |-------|---------|-------------|
 | `name` | (required) | Monitor identifier. Must be unique across project and global. |
 | `description` | `""` | Human-readable description. Also used as command description for `event: command` monitors. |
-| `event` | `message_end` | When to fire: `message_end`, `turn_end`, `agent_end`, or `command`. |
+| `event` | `message_end` | When to fire: `message_end`, `turn_end`, `agent_end`, `command`, or `tool_call`. `tool_call` fires pre-execution and can block the tool. |
 | `when` | `always` | Activation condition (see below). |
 | `ceiling` | `5` | Max consecutive steers before escalation. |
 | `escalate` | `ask` | At ceiling: `ask` (confirm with user) or `dismiss` (silence for session). |
@@ -272,7 +276,7 @@ Non-main scopes can still write findings to JSON files.
 | `steer` | Message to inject into conversation. `null` = no steering. Only effective for `scope.target: "main"`. |
 | `write.path` | JSON file to write findings to. Relative paths resolve from `process.cwd()`, not from the monitor directory. |
 | `write.merge` | `append` (add to array) or `upsert` (update by matching `id` field). |
-| `write.array_field` | Which field in target JSON holds the array (e.g. `"gaps"`, `"findings"`). |
+| `write.array_field` | Which field in target JSON holds the array (e.g. `"issues"`, `"findings"`). |
 | `write.template` | Template mapping with `{finding_id}`, `{description}`, `{severity}`, `{monitor_name}`, `{timestamp}`. |
 | `write.schema` | Optional schema path for documentation. Not enforced at runtime. |
 | `learn_pattern` | If true, add new pattern to patterns file on `new` verdict. |
@@ -425,6 +429,14 @@ corrected response re-triggers monitors naturally for any remaining issues. Moni
 **Abort**: Classification calls are aborted when the agent ends (via `agent_end` event).
 Aborted classifications produce no verdict and no action.
 
+**Pre-execution blocking (tool_call)**: Monitors with `event: "tool_call"` fire before a
+tool executes. The handler receives the pending tool name and arguments, classifies them,
+and can return `{ block: true, reason }` to prevent execution. This is fundamentally
+different from post-hoc steering — the tool never runs. Classification failure is fail-open:
+if the side-channel LLM call errors, the tool is allowed to proceed. The pending tool call
+context (name + arguments) is available as `{{ tool_call_context }}` in classify templates.
+Dedup is not applied to tool_call monitors since each tool call is a distinct event.
+
 **Write action**: Relative `write.path` values resolve from `process.cwd()`, not from the
 monitor directory. Parent directories are created automatically. If the target file doesn't
 exist or is unparseable, a fresh object is created. The `upsert` merge strategy matches on
@@ -455,14 +467,14 @@ for other extensions or workflows to invoke classification directly.
 </commands>
 
 <bundled_monitors>
-Four example monitors ship in `examples/` and are seeded on first run. Each has a
+Five example monitors ship in `examples/` and are seeded on first run. Each has a
 Nunjucks classify template in `examples/<name>/classify.md` with iteration-aware
 acknowledgment support:
 
 **fragility** (`message_end`, `when: has_tool_results`)
 Watches for unaddressed fragilities after tool use — errors, warnings, or broken state the
 agent noticed but chose not to fix. Steers with "Fix the issue you left behind." Writes
-findings to `.workflow/gaps.json` under `category: "fragility"`. Excludes: none. Ceiling: 5.
+findings to `.project/issues.json` under `category: "fragility"`. Excludes: none. Ceiling: 5.
 12 bundled patterns across categories: avoidance (dismiss-preexisting, not-my-change,
 blame-environment, workaround-over-root-cause, elaborate-workaround-for-fixable),
 error-handling (empty-catch, happy-path-only, early-return-on-unexpected,
@@ -480,7 +492,7 @@ deflection (ask-permission, qualify-yesno, counter-question).
 
 **work-quality** (`command`, `when: always`)
 On-demand work quality analysis invoked via `/work-quality`. Analyzes user request, tool
-calls, and assistant response for quality issues. Writes findings to `.workflow/gaps.json`
+calls, and assistant response for quality issues. Writes findings to `.project/issues.json`
 under `category: "work-quality"`. Ceiling: 3.
 11 bundled patterns across categories: methodology (trial-and-error, symptom-fix,
 double-edit, edit-without-read, insanity-retry, no-plan), verification (no-verify),
@@ -493,6 +505,12 @@ generic or certainty-language message, steers to improve. Does not write finding
 are their own artifact. Ceiling: 3.
 6 bundled patterns across categories: missing-commit (no-commit), message-quality
 (generic-message, certainty-language, no-context), commit-safety (amend-not-new, force-push).
+
+**unauthorized-action** (`tool_call`, `when: has_tool_results`)
+Pre-execution blocker that classifies each pending tool call against user-directed scope.
+If the agent is about to execute a tool the user did not direct, the monitor blocks the
+tool call before execution rather than steering correction after the fact. Uses `tool_call`
+event with `{ block: true, reason }` return to prevent execution. Ceiling: 3.
 </bundled_monitors>
 
 <disabling_monitors>
@@ -523,6 +541,7 @@ should trigger a flag? Translate the user's description into concrete, observabl
 - Response content issues (trailing questions, lazy options, tone) → `turn_end`, `when: always`
 - Tool use issues (no commit, no test, bad edits) → `agent_end`, `when: has_file_writes` or `has_tool_results`
 - Post-action fragility (ignoring errors) → `message_end`, `when: has_tool_results`
+- Pre-execution blocking (unauthorized actions, dangerous commands) → `tool_call`, `when: has_tool_results` or `always`
 - On-demand analysis → `command`, `when: always`
 
 **Step 3: Choose context collectors.** What data does the classifier need to see?

package/skills/pi-project/SKILL.md

@@ -11,12 +11,12 @@ description: >
 <tool name="append-block-item">
 Append an item to an array in a project block file. Schema validation is automatic.
 
-*Append items to project blocks (gaps, decisions, or any user-defined block)*
+*Append items to project blocks (issues, decisions, or any user-defined block)*
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'gaps', 'decisions') |
-| `arrayKey` | string | yes | Array key in the block (e.g., 'gaps', 'decisions') |
+| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
+| `arrayKey` | string | yes | Array key in the block (e.g., 'issues', 'decisions') |
 | `item` | unknown | yes | Item object to append — must conform to block schema |
 </tool>
 
@@ -27,9 +27,9 @@ Update fields on an item in a project block array. Finds by predicate field matc
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'gaps', 'decisions') |
+| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
 | `arrayKey` | string | yes | Array key in the block |
-| `match` | object | yes | Fields to match (e.g., { id: 'gap-123' }) |
+| `match` | object | yes | Fields to match (e.g., { id: 'issue-123' }) |
 | `updates` | object | yes | Fields to update (e.g., { status: 'resolved' }) |
 </tool>
 
@@ -40,7 +40,7 @@ Read a project block file as structured JSON.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'gaps', 'tasks', 'requirements') |
+| `block` | string | yes | Block name (e.g., 'issues', 'tasks', 'requirements') |
 </tool>
 
 <tool name="write-block">
@@ -106,8 +106,8 @@ See references/bundled-resources.md for full inventory.
 | `conformance-reference` | Conformance Reference | `principles` | id, name, description?, rules (array) |
 | `decisions` | Decisions | `decisions` | id, decision, rationale, phase? (string|integer), status (string (decided|tentative|revisit|superseded)), context? |
 | `domain` | Domain Knowledge | `entries` | id, title, content, category (string (research|reference|domain-rule|prior-art|constraint)), source?, confidence? (string (high|medium|low)), related_requirements? (array), tags? (array) |
-| `gaps` | Gaps | `gaps` | id, description, status (string (open|resolved|deferred)), category (string (missing|incomplete|defect|improvement|technical-debt|question)), priority (string (low|medium|high|critical)), phase? (string|integer), resolved_by?, source? (string (human|agent|monitor|workflow)), details? |
 | `handoff` | Handoff | `current_tasks` |  |
+| `issues` | Issues | `issues` | id, title, body, location, status (string (open|resolved|deferred)), category (string (primitive|issue|cleanup|capability|composition)), priority (string (low|medium|high|critical)), package, source? (string (human|agent|monitor|workflow)), resolved_by? |
 | `phase` | Phase | `success_criteria` | criterion, verify_method (string (command|inspect|test)) |
 | `project` | Project Identity | `target_users` |  |
 | `rationale` | Design Rationale | `rationales` | id, title, narrative, related_decisions? (array), phase? (string|integer), context? |
@@ -124,10 +124,10 @@ See references/bundled-resources.md for full inventory.
 | `decisions` | `status` | decided, tentative, revisit, superseded |
 | `domain` | `category` | research, reference, domain-rule, prior-art, constraint |
 | `domain` | `confidence` | high, medium, low |
-| `gaps` | `status` | open, resolved, deferred |
-| `gaps` | `category` | missing, incomplete, defect, improvement, technical-debt, question |
-| `gaps` | `priority` | low, medium, high, critical |
-| `gaps` | `source` | human, agent, monitor, workflow |
+| `issues` | `status` | open, resolved, deferred |
+| `issues` | `category` | primitive, issue, cleanup, capability, composition |
+| `issues` | `priority` | low, medium, high, critical |
+| `issues` | `source` | human, agent, monitor, workflow |
 | `phase` | `status` | planned, in-progress, completed |
 | `phase` | `verify_method` | command, inspect, test |
 | `phase` | `status` | planned, in-progress, completed |

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

@@ -5,7 +5,7 @@
 - `defaults/blocks/conformance-reference.json`
 - `defaults/blocks/decisions.json`
 - `defaults/blocks/domain.json`
-- `defaults/blocks/gaps.json`
+- `defaults/blocks/issues.json`
 - `defaults/blocks/project.json`
 - `defaults/blocks/rationale.json`
 - `defaults/blocks/requirements.json`
@@ -16,8 +16,8 @@
 - `defaults/schemas/conformance-reference.schema.json`
 - `defaults/schemas/decisions.schema.json`
 - `defaults/schemas/domain.schema.json`
-- `defaults/schemas/gaps.schema.json`
 - `defaults/schemas/handoff.schema.json`
+- `defaults/schemas/issues.schema.json`
 - `defaults/schemas/phase.schema.json`
 - `defaults/schemas/project.schema.json`
 - `defaults/schemas/rationale.schema.json`

package/skills/pi-project-workflows/SKILL.md

@@ -34,7 +34,7 @@ Workflow orchestration extension for Pi
 Behavior monitors for pi that watch agent activity and steer corrections
 
 **Tools:** `monitors-status`, `monitors-inspect`, `monitors-control`, `monitors-rules`, `monitors-patterns`
-**Commands:** `/monitors`
+**Commands:** `/work-quality`, `/monitors`
 </extension>
 
 </included_extensions>