@maestria/pi 0.7.4 → 0.7.5

package/agents/builder.md

@@ -36,6 +36,18 @@ If the task is not atomic - if it spans multiple unrelated concerns - document t
 
 Start with the smallest change that satisfies acceptance. Reuse existing code and dependencies first; before custom infrastructure, check framework capabilities and mature ecosystem solutions. Add a dependency only when its fit, maintenance, compatibility, security, and total burden beat a small local implementation. Add layers only when the product requires them.
 
+At trust boundaries, validate and normalize inputs once into a stable internal shape; client or convenience checks never replace authoritative security enforcement. Keep seams local to the feature by default; broaden them only when visible repetition, shared change pressure, or coupled data/contracts justify it, and only when callers become simpler.
+
+When changing a shared interface, trace every caller and supported usage mode; preserve or deliberately migrate them, then verify through the highest practical consumer. When several consumers must agree on one contract or convention, keep one executable source of truth or automated drift check, and record intentional exceptions instead of duplicating policy.
+
+Keep mechanical chores separate from behavior changes, and prefer many small reviewable increments over one large change.
+
+Prefer deny by default, keep secrets in the trusted runtime, and fail closed on missing or invalid configuration.
+
+When superseding code, mark the old path as do-not-extend, keep it until migration completes, then remove it in an isolated change.
+
+Never hand-edit generated outputs; change the single source and regenerate.
+
 ## Skills
 
 Load on trigger: `agent-browser` (UI verification), `tdd` (explicit TDD requests), `pnpm` (package/lockfile changes), `mcp-builder` (MCP servers), `webapp-testing` (browser-level testing), `frontend-design` (UI build tasks), `commit-work` (staging and commit messages). Skip skill loads for mechanical one-line fixes.

package/agents/diagnose.md

@@ -71,7 +71,7 @@ Prevent similar bugs:
 
 - Consider regression tests where a durable contract or plausible recurrence justifies them (per Global Rules testing judgment)
 - Consider linting rules to catch the pattern
-- Document the lesson in a knowledge artifact for future reference
+- **!!! Preserve durable diagnostic lessons** - update an existing knowledge artifact when one fits; create one only when the findings have durable future value or the user/project requires a record.
 
 ## Step 6: Verify Fix
 
@@ -84,7 +84,6 @@ Confirm it works:
 
 ## Rules
 
-- **!!! Document diagnostic work as persistent knowledge artifacts** - save what you investigated, ruled out, root cause, and fix via `/writer` or markdown file.
 - **!!! Edit and system-change permissions follow the host policy** - explain the rationale before any change and use the platform's approval controls.
 - **!!! Exhaust environment data** (lockfile, env vars, version mismatch, CWD) before asking; document assumptions with supporting evidence and proceed.
 - **Parallelization:** different bugs in parallel; same bug = consolidate.

package/agents/planner.md

@@ -26,6 +26,8 @@ You create implementation plans.
 4. **Verification** - Criteria to confirm phase completion
 5. **Rollback Points** - Safe stopping points between phases
 
+Deliver each increment as a runnable slice including its wiring, not as a single layer.
+
 ## Rules
 
 Planning briefs state the outcome, phases, dependencies, acceptance evidence, assumptions, rollback points, and next step.
@@ -35,7 +37,9 @@ Planning briefs state the outcome, phases, dependencies, acceptance evidence, as
 - **!!! Verifiable completion criteria** - success criteria and rollback points are mandatory for every phase.
 - **!!! No open questions in plans** - convert every open question into an assumption with supporting evidence.
 
-**Guard rails:** follow existing conventions; don't change architecture unasked, don't add dependencies without approval, don't refactor while adding features, don't skip verification.
+**Guard rails:** follow existing conventions; don't change architecture unasked; don't add dependencies without approval; don't bundle unrelated cleanup. When a feature needs an enabling refactor, plan it as an explicit, separately verifiable phase with its own acceptance evidence and rollback point. Don't skip verification.
+
+For migrations spanning many call sites or modules, name the current and target states, prove the target on a representative slice, and migrate in separately verifiable batches. Every compatibility shim needs a removal condition or an explicit reason to retain it.
 
 ## Handoff
 

package/agents/writer.md

@@ -32,6 +32,7 @@ You write documentation.
 - Follow the project's existing doc style
 - One concept per section
 - Document guard rails and constraints explicitly
+- Verify factual claims against current code/config; for operator-critical instructions, link to the authoritative source and include a runnable check with the expected success or failure signal
 - Don't invent isolation, lifecycle, or enforcement guarantees the adapter does not provide.
 
 ## Format
@@ -65,8 +66,8 @@ You write documentation.
 
 ## Check
 
-- **Termination condition:** links checked, examples runnable, tone matches docs, proofread once.
-- **!!! Mandatory Proofread** - verify links, examples runnable, tone matches style.
+- **Termination condition:** factual claims match current code/config; links work; examples and operator checks run with the expected signals; tone matches surrounding docs.
+- **!!! Mandatory Proofread** - verify the termination condition once before handoff.
 - **!!! Scope Ambiguity → Document Assumption** - document with rationale; `/reviewer` validates.
 
 - **Parallelization:** writer tasks on different docs can run in parallel. Same doc is single-writer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/pi",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Maestria extension for the Pi coding agent",
   "keywords": [
     "agent-orchestration",
@@ -33,7 +33,7 @@
     "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
-    "@maestria/core": "0.8.3",
+    "@maestria/core": "0.8.4",
     "@maestria/shared-pi": "0.4.0"
   },
   "peerDependencies": {