@nklisch/pi-agile-workflow 0.16.1 → 0.16.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agile-workflow",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner. See docs/VISION.md.",
-  "version": "0.16.1",
+  "version": "0.16.4",
   "author": {
     "name": "nklisch"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agile-workflow",
-  "version": "0.16.1",
+  "version": "0.16.4",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner.",
   "author": {
     "name": "nklisch"

package/docs/ARCHITECTURE.md

@@ -305,8 +305,11 @@ git log --since='1 day ago' -- .work/
 ## Foundation docs (rolling-forward principle)
 docs/ holds standing context: VISION.md, SPEC.md, ARCHITECTURE.md, etc.
 - Foundation docs describe the system's current state or intended future state
+- Future-state claims are valid before implementation exists; foundation docs
+  need not mention every capability
 - Never retain superseded behavior descriptions or versioned migration notes
-- When implementation changes a foundation-doc assertion, update the doc
+- Update only assertions that become false, stale, or contradictory; omission is
+  not drift
 - Git history is the audit trail; the doc carries the active truth
 ````
 
@@ -369,7 +372,10 @@ Advisory review follows risk in both direct and autopilot design. Independent
 review uses completeness/advisory before adversarial posture, is labeled
 cross-model only for a known different model class, and is non-blocking at
 design time. Final autopilot completion still requires the successful review
-path selected by the effective review weight.
+path selected by the effective review weight. The receiving orchestrator owns
+finding disposition: it verifies reviewer proposals in repository context,
+keeps only credible material current-cycle risks blocking, and parks valid
+lower-priority work in the unbound backlog.
 
 ### Queue selection algorithm
 
@@ -397,11 +403,12 @@ path selected by the effective review weight.
 7. Re-read substrate state after the production skill returns; it may already
    have completed review and eligible parent roll-up. Commit each item
    transition separately.
-8. If review bounced an item, treat its durable findings as the next
-   implementation input and keep cycling implementation → verification → review.
-   Bounce count is diagnostic history, never a stop condition. Recurring findings
-   trigger deeper root-cause/design diagnosis and fresh context where useful,
-   not a human handoff.
+8. If review bounced an item, treat only receiver-confirmed material blockers as
+   the next implementation input and keep cycling implementation → verification
+   → review. Park valid lower-priority findings unbound; they do not reopen the
+   scoped queue. Bounce count is diagnostic history, never a stop condition.
+   Recurring blockers trigger deeper root-cause/design diagnosis and fresh
+   context where useful, but repetition alone does not elevate severity.
 9. Goto 1 unless a stop condition applies.
 ```
 
@@ -500,6 +507,9 @@ session epoch:
 Code-design capsule:
 - Ports & Adapters: keep domain logic independent of DB/filesystem/HTTP/time/randomness.
 - Single Source of Truth: define growing variant sets once; derive downstream behavior.
+- Proportional rigor: validate real boundaries; add invariants, edge handling, and determinism only when context warrants them.
+- Code economy: prefer the shortest clear solution; test useful interfaces, complex units, and bug regressions.
+- Leave it simpler: eliminate unnecessary code, tests, checks, abstractions, and compatibility paths; ask before reducing guarantees.
 ...
 ```
 
@@ -548,15 +558,20 @@ Override via `gates_for_release` in `.work/CONVENTIONS.md`.
 
 ### Gate-as-item-producer pattern
 
-Each gate scans the bundle of items at `release_binding: <current-version>`
-and produces new items rather than emitting a pass/fail report:
+Each gate focuses on the bundle of items at
+`release_binding: <current-version>` and produces new items rather than
+emitting a pass/fail report. The bundle is a center of gravity, not a hard scan
+boundary: gates may follow concrete evidence into adjacent dependencies, shared
+infrastructure, or system-wide mechanisms. Findings caused by, exposed by, or
+materially relevant to the release bind to it; merely ambient discoveries go
+to the unbound backlog so the gate does not silently expand release scope.
 
 | Gate | What it scans | What it produces |
 |---|---|---|
 | `gate-security` | Bound items' code changes against security checklist | Items with `gate_origin: security`, tagged `[security]`, `release_binding` set |
-| `gate-tests` | Coverage of bound items' acceptance criteria | Items with `gate_origin: tests`, tagged `[testing]` for gaps |
-| `gate-cruft` | Dead code introduced or revealed by the bundle | Items with `gate_origin: cruft`, tagged `[cleanup]` |
-| `gate-docs` | Foundation-doc alignment with the bundle's behavior changes | Items with `gate_origin: docs`, tagged `[documentation]` — enforces rolling-foundation |
+| `gate-tests` | Useful coverage at stable interfaces, complex units, and bug regressions; low-value tests exposed by the bundle | Items with `gate_origin: tests`, tagged `[testing]` for valuable gaps or removals |
+| `gate-cruft` | Local or system-wide code, tests, checks, compatibility paths, and abstractions that may no longer earn their cost | Items with `gate_origin: cruft`, tagged `[cleanup]`; guarantee-reducing removals require user confirmation |
+| `gate-docs` | Existing foundation assertions that may be false, stale, or contradictory; omissions and unimplemented future claims are excluded | Items with `gate_origin: docs`, tagged `[documentation]` — enforces rolling-foundation |
 | `gate-patterns` | Reusable patterns that emerged in the bundle | Detailed pattern-skill files in `.agents/skills/patterns/` (single source of truth) with optional Claude mirror, the generated hook-loaded `.agents/rules/patterns.md` digest (slug+one-liner index pointing back at the skill, with banner + source hash), plus a tracking item with `gate_origin: patterns` |
 
 For gates that emit findings as items, placement flows through
@@ -605,7 +620,9 @@ parent, and dependency. Common patterns:
 - `work-view --help` for the full flag set
 
 Foundation docs in `docs/` describe the system's current state or intended
-future state, never the past; git history is the audit trail. The substrate
+future state, never the past; git history is the audit trail. Review existing
+assertions only: missing coverage and unimplemented future intent are not drift;
+flag only false, stale, or contradictory claims. The substrate
 itself is durable memory: record decisions, blockers, implementation
 discoveries, and review findings in item bodies instead of depending on chat
 history.
@@ -668,12 +685,16 @@ class is needed and allowed.
 
 Concrete model guidance lives in `skills/principles/references/models.md` and is
 resolved against current availability when selection matters. GPT-5.6 Luna is
-the implementation workhorse; Sol is preferred for design, review, complex code,
-and as the low-thinking bridge above Luna; Terra is a situational middle pick;
-and Claude Fable is a high-cost design, orchestration, and review specialist
-rather than the default implementer. These are capability recommendations, not
-fixed routing. Luna, Terra, Sol, and Codex share OpenAI lineage, so moving among
-them can provide fresh context but is not cross-model evidence.
+the cost-efficient routine implementation and fan-out workhorse; Sol is the
+quality-first general coding choice and remains preferred for design, review,
+and complex code; Terra is a situational middle pick. Sonnet 5 is the capable
+high-throughput Claude worker, Opus 4.8 the stable premium complex-coding and
+review default, and Fable 5 the high-cost escalation for the hardest ambiguous,
+long-running, orchestration, design, and review work. Model-specific prompting
+is conditional and symptom-driven rather than fixed boilerplate. These are
+capability recommendations, not fixed routing. Luna, Terra, Sol, and Codex share
+OpenAI lineage, so moving among them can provide fresh context but is not
+cross-model evidence.
 
 ### Bootstrap (user-invocable only)
 
@@ -730,7 +751,7 @@ neither substitutes inline self-approval for a required fresh-context lane.
 | `gate-security` | Security scan over bound items; produces items with `gate_origin: security` |
 | `gate-tests` | Test-coverage scan; produces gap items with `gate_origin: tests` |
 | `gate-cruft` | Dead-code scan; produces cleanup items with `gate_origin: cruft` |
-| `gate-docs` | Foundation-doc alignment; enforces rolling-foundation; produces doc-update items |
+| `gate-docs` | Assertion-only foundation-doc alignment; ignores omissions and unimplemented future claims; produces doc-update items |
 | `gate-patterns` | Pattern extraction; writes pattern skills (`.agents/skills/patterns/`), the generated `.agents/rules/patterns.md` digest, + tracking item with `gate_origin: patterns` |
 
 All five fire during `release-deploy`'s `quality-gate` stage in the order
@@ -741,7 +762,7 @@ configured in `CONVENTIONS.md` (default: security → tests → cruft → docs
 
 | Skill | Role | Notes |
 |---|---|---|
-| `principles` | Loads code-design + substrate-execution principles | Code-design (Ports & Adapters, SSOT, Generated Contracts, Fail Fast) carried from workflow; substrate-execution (item-IS-the-work, rolling-foundation, late-binding) added |
+| `principles` | Loads code-design + substrate-execution principles | Code-design includes clear boundaries, proportional rigor, code economy, useful tests, and continuous simplification; substrate-execution includes item-IS-the-work, rolling-foundation, and late-binding |
 | `research` | Investigate libraries/APIs | Carried; produces research docs in `docs/research/` (separate from `.work/`) |
 | `refactor-conventions-creator` | Create project-specific refactor conventions skill | Carried |
 

package/docs/PRINCIPLES.md

@@ -2,8 +2,8 @@
 
 The plugin's `principles` skill loads two distinct paradigms:
 
-- **Code-design principles** — Ports & Adapters, Single Source of Truth,
-  Generated Contracts, Fail Fast. Carried from the `workflow` plugin.
+- **Code-design principles** — clear boundaries and sources of truth,
+  proportional rigor, code economy, useful tests, and continuous simplification.
   These tell the agent how to write good code at design time and
   implementation time.
 - **Substrate-execution principles** — Item-IS-the-Work, Rolling-Foundation,
@@ -18,7 +18,7 @@ shapes how work moves through the system.
 
 # Part I — Code-Design Principles
 
-These four principles govern both architectural decisions and how code is
+These principles govern both architectural decisions and how code is
 written. Each section has guidance for design time and implementation time.
 
 ## 1. Ports & Adapters
@@ -213,21 +213,20 @@ If a generated type needs extending, use
 `type MyType = GeneratedType & { extra: string }` — extend the source of
 truth, don't replace it.
 
-## 4. Fail Fast (implementation only)
+## 4. Fail Fast—Where It Matters
 
-Catch bad data at the door, not three calls deep where the stack trace is
-useless. Validate inputs at the entry point of every function or system
-boundary.
+Catch bad data at real trust boundaries, not three calls deep. Validate
+untrusted input and required external contracts before domain logic runs. Add
+internal checks only where a violated precondition is plausible and
+consequential for this project.
 
 - At system boundaries (HTTP handlers, CLI args, external API responses,
-  config files): parse with Zod or equivalent before any logic runs
-- At internal function boundaries: assert preconditions at the top of the
-  function — guard clauses, not nested ifs
-- Prefer `throw`/`return early` over propagating bad state deep into call
-  chains
-- Errors should be loud and specific at the point of violation —
-  "expected positive number, got -3" beats a cryptic null reference five
-  layers down
+  config files): parse before logic runs
+- At internal boundaries: add guards when they protect a real invariant, not
+  mechanically at every function
+- Prefer early, specific failure when failure is part of the required contract
+- Do not manufacture exhaustive edge handling, invariants, retries, or firm
+  determinism that the project's scope and consequences do not need
 
 **Good:**
 ```typescript
@@ -250,6 +249,73 @@ function processOrder(input: any) {
 }
 ```
 
+## 5. Code Economy
+
+Short, direct code is a virtue when it stays clear. Prefer fewer concepts,
+layers, branches, options, and lines over speculative generality. Terse does not
+mean cryptic: simplify the model first, then its expression. Every abstraction
+or extension point must earn its maintenance cost in current scope.
+
+### At design time
+
+- Start with the most direct solution that satisfies the actual brief
+- Reject hypothetical flexibility without a current second use or committed need
+- Compare approaches by concepts removed as well as capabilities added
+
+### At implementation time
+
+- Delete obsolete paths and incidental machinery exposed by the change
+- Inline or consolidate before extracting another abstraction
+- Match rigor to the project's context rather than treating every codebase as
+  critical infrastructure
+
+## 6. Tests Earn Their Keep
+
+Tests are maintained code. Prioritize stable public interfaces, important seams,
+high-consequence behavior, and regressions learned from real bugs. Unit tests
+belong around genuinely complex isolated logic, not every wrapper, branch, or
+line. Coverage numbers are evidence, not goals.
+
+### At design time
+
+- Name the interface, risk, or regression each proposed test protects
+- Prefer one useful interface test over several implementation-bound unit tests
+- Do not require one automated test per unit, edge, or acceptance statement
+
+### At implementation time
+
+- Add regression tests when bugs reveal meaningful risk
+- Remove duplicate, tautological, brittle, obsolete, or low-value tests
+- Keep simple code simple when an isolated test adds no useful confidence
+
+## 7. Leave It Simpler
+
+Exploration, design, and implementation include an elimination pass. Look for
+code, tests, checks, abstractions, configuration, and compatibility paths the
+feature can make unnecessary. Fold safe cohesive cleanup into the task or create
+explicit cleanup/refactor stories; park broader opportunities.
+
+Question whole systems, not only local fragments. A validation layer, invariant
+system, test suite, compatibility mechanism, or defensive subsystem may no
+longer justify its cost. Removing behavior, guarantees, validation, determinism,
+compatibility, or safety is a product decision: explain the trade-off and ask
+the user rather than silently weakening it.
+
+### Review proportionality
+
+Reviewer output is evidence, not authority. The receiving agent verifies claims
+and judges their current-cycle risk against the repository's acceptance criteria,
+supported users and deployment shape, likelihood, blast radius, recoverability,
+safeguards, and delay cost. Credible material risks to required correctness,
+security, data, public contracts, acceptance, release safety, or trustworthy
+verification block. Valid lower-priority concerns are parked unbound; nits stay
+in review notes; unsupported advice is rejected with a brief rationale.
+
+A successful independent review path requires adjudicating every proposal, not
+implementing every suggestion. A rare severe case may still block, while a real
+corner case with negligible consequence need not. Reviewer labels, model
+strength, and repeated mention do not replace the receiving agent's judgment.
+
 ---
 
 # Part II — Substrate-Execution Principles
@@ -259,7 +325,7 @@ shape stage transitions, item bodies, foundation-doc evolution, and
 release binding. The agent applies these whenever operating on `.work/`
 or `docs/`.
 
-## 5. Item-IS-the-Work
+## 8. Item-IS-the-Work
 
 The unit of work is its file. The brief, the design, the implementation
 notes, and the review findings all accumulate in the item's body as
@@ -314,13 +380,15 @@ stages advance. Reading the file IS reading the state of the work.
 - [ ] Item body at completion is a complete record
 - [ ] Code does not reference item IDs; only logical concepts
 
-## 6. Rolling-Foundation
+## 9. Rolling-Foundation
 
 Foundation docs (`docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`,
-and any others) describe the project's vision (future-looking) and current
-intent — what is true now, OR what will be true once in-flight design lands.
-They roll forward in place as either evolves. No legacy comments. Git carries
-history; the doc carries truth.
+and any others) describe what is true now or the future state the project
+intends to reach. A future-state claim remains valid before implementation
+exists. Foundation docs are selective standing context, not an exhaustive
+inventory: silence about a capability is allowed. They roll forward when an
+assertion becomes false, stale, or contradictory. Git carries history; the doc
+carries truth.
 
 ### Two timing styles
 
@@ -336,9 +404,9 @@ Both are legitimate; the project picks one or mixes per change size:
 
 The discipline is identical in both styles: replace stale assertions in
 place, never accumulate "previously" / "in v1.x" / migration prose.
-`gate-docs` at release-deploy time is the backstop — it catches drift between
-intent (what the doc asserts) and reality (what code does) regardless of
-which timing style was used.
+`gate-docs` is an assertion-consistency backstop: it catches false, stale, or
+contradictory claims, but never treats missing coverage or merely unimplemented
+future intent as drift.
 
 ### What this forbids
 
@@ -352,14 +420,14 @@ which timing style was used.
 
 ### What this enables
 
-- A new contributor reads the doc and learns the system as it IS or as
-  it is meant to imminently become — not as it was
+- A new contributor reads the doc and learns the system as it is or as
+  it is intended to become — not as it was
 - Foundation docs stay short and current rather than growing with every
   change
 - `git log docs/<file>.md` shows every rolling-forward edit — perfect
   audit trail without bloating the doc
-- Discrepancies between intent and reality become bugs that `gate-docs`
-  surfaces, not historical artifacts to be reconciled mentally
+- False, stale, or contradictory assertions become bugs that `gate-docs`
+  surfaces; omissions and not-yet-implemented future claims do not
 
 ### At design time
 
@@ -368,8 +436,8 @@ which timing style was used.
   the update as part of scope)
 - For large-scope `scope` operations, design-first is the default —
   `scope` rolls foundation docs forward as part of the same operation
-- Identify which foundation doc(s) need rolling forward; reading them
-  at design time prevents stale assumptions
+- Identify any existing foundation assertions the design changes or
+  contradicts; do not add coverage merely because the docs omit the capability
 - If a feature's design contradicts a foundation doc, EITHER the design
   is wrong OR the doc is. Resolve before designing the implementation.
 
@@ -383,22 +451,24 @@ which timing style was used.
   adjust whichever was wrong (implementation or assertion).
 - Replace stale assertions in place. Delete the old text. Never append
   "previously" / "in v1.x" / migration prose.
-- The `gate-docs` runs at release-deploy time and produces items for
-  any remaining drift — but the goal is to leave it nothing to find.
+- The `gate-docs` skill produces items only for remaining false, stale, or
+  contradictory assertions—not missing coverage or unimplemented future intent.
 
 ### Design checklist
 
-- [ ] Every assertion in SPEC and ARCHITECTURE reflects current code OR
-      imminent in-flight design (no stale assertions from cancelled work)
+- [ ] Every assertion in SPEC and ARCHITECTURE is true for the current or
+      intended-future state it claims (no stale assertions from superseded intent)
 - [ ] VISION.md reflects the project's current direction, not past direction
 - [ ] No "previously" / "originally" / "in v1.x" prose anywhere in `docs/`
-- [ ] When a feature changes behavior or direction, foundation docs update
-      in the same commit set as the change (code-first) or were preflight-
-      updated and are still accurate (design-first)
+- [ ] When a feature invalidates an existing foundation assertion, that
+      assertion updates in the same commit set (code-first) or was preflight-
+      updated and remains accurate (design-first)
+- [ ] No finding or edit was created solely because foundation docs omit a
+      capability or describe future intent not yet implemented
 - [ ] `git log docs/<file>.md` shows the audit trail; the doc shows the
       present
 
-## 7. Late-Binding
+## 10. Late-Binding
 
 Items advance stages when work actually completes. Releases bind items
 only when the user cuts a version. Foundation docs are not pre-decided

package/docs/SPEC.md

@@ -95,7 +95,9 @@ item kind as a starting heuristic. Low-risk stories can close from recorded
 green verification, while risky stories, features, and epics receive the
 fresh-context coverage allowed by the effective weight. Child completion may
 make a parent eligible for its own review, but never approves the parent by
-itself.
+itself. Fresh-reviewer findings are proposals: the receiving agent verifies and
+classifies them against repository context. Only credible material current-cycle
+risk blocks advancement; valid lower-priority findings are parked unbound.
 
 ### Questions and advisory review
 
@@ -125,7 +127,13 @@ convention, then `standard`:
   available for the highest-risk scopes.
 
 These levels state review intent and ceilings, not fixed reviewer counts or pass
-recipes.
+recipes. A successful review path requires every proposed finding to be
+adjudicated, not implemented. The receiving orchestrator weighs acceptance
+criteria, supported users and deployment shape, likelihood, blast radius,
+recoverability, safeguards, and delay cost. It fixes or activates material
+current-cycle blockers, parks valid lower-priority concerns in the unbound
+backlog, and rejects unsupported advice with a rationale. Reviewer labels and
+repetition are evidence, not authority.
 
 ### Backlog item shape
 
@@ -204,6 +212,15 @@ backlog_staleness_days: 90
 The default `gates_for_release` order is fixed: **security → tests → cruft
 → docs → patterns**. Override only if the project has a justified reason.
 
+Release-bound items define each gate's focus, not a hard scan boundary. A gate
+may follow concrete evidence into adjacent dependencies, shared infrastructure,
+or system-wide mechanisms. Findings caused by, exposed by, or materially
+relevant to the release bind to it. Merely ambient discoveries must be written
+to the unbound backlog, so wider inspection does not silently expand release
+scope. Any cruft proposal that reduces behavior, validation, determinism,
+compatibility, safety, or another meaningful guarantee requires explicit user
+confirmation before it becomes active removal work.
+
 **`gate-refactor` is an opt-in gate** — not in the default list. Add it when your project has
 scan-rule libraries installed under `gate_refactor_scan_library_roots` (defaults:
 `{project}/.agents/skills/scan-*/SKILL.md`, then

package/docs/VISION.md

@@ -34,18 +34,20 @@ The plugin enforces three execution principles:
   review findings — all accumulate in the item's body as stages advance.
   Reading the file IS reading the state of work.
 - **Foundation docs roll forward.** `docs/VISION.md`, `docs/SPEC.md`,
-  `docs/ARCHITECTURE.md` describe current truth or intended future state.
-  When implementation changes what those docs assert, the docs update to
-  match the new truth. No retained descriptions of superseded behavior or
+  `docs/ARCHITECTURE.md` describe current truth or intended future state. They
+  are selective rather than exhaustive: omission is allowed, and a future-state
+  claim is valid before implementation exists. When an assertion becomes false,
+  stale, or contradictory, it updates to match the new truth. No retained
+  descriptions of superseded behavior or
   migration commentary. Git is the audit trail.
 - **Late-bind everything.** No upfront roadmap. No pre-populated stages.
   No pre-tagged release bindings. Items advance stages when work actually
   completes. Releases bind items only when the user cuts a version.
 
-The plugin's `principles` skill loads these alongside the code-design
-principles (Ports & Adapters, Single Source of Truth, Generated Contracts,
-Fail Fast) carried over from `workflow`. The two paradigms — substrate
-execution and code design — operate together during agile-workflow work.
+The plugin's `principles` skill loads these alongside code-design principles
+for clear boundaries, proportional rigor, code economy, useful tests, and
+continuous simplification. The two paradigms—substrate execution and code
+design—operate together during agile-workflow work.
 
 ## Who this is for
 
@@ -95,9 +97,14 @@ agile-workflow is complete enough to operate as the supported workflow engine:
 - Questions and advisory review are consequence-driven: routine reversible
   choices use recorded judgment; strategic or difficult-to-reverse choices get
   an explicit checkpoint; independent review scales through the project's
-  high-level review weight while preserving fresh-context deep review.
+  high-level review weight while preserving fresh-context deep review. Reviewer
+  findings remain proposals: the receiving orchestrator weighs actual repository
+  risk, blocks only on material current-cycle concerns, and parks valid
+  lower-priority work rather than forcing every suggestion into implementation.
 - Real releases move through scope → design → implement → review →
-  release-deploy on the substrate; gates produce durable findings, and the
+  release-deploy on the substrate; gates focus on bound work while following
+  relevant evidence into adjacent or system-wide code, distinguish release
+  findings from ambient backlog discoveries, and produce durable items. The
   release ships only after every bound item is terminal. Foundation docs roll
   forward, release binding stays late, and terminal retention keeps git as the
   audit trail without leaking obsolete authority.
@@ -106,7 +113,7 @@ The pattern proves itself when a fresh session in a substrate-bootstrapped repo
 picks up active work without re-feed; when direct production work and autopilot
 both finish decisively while respecting dependency, test-integrity, review, and
 parent-roll-up invariants; and when foundation docs five features later still
-describe the present without legacy comments.
+make true, noncontradictory current-or-future claims without legacy comments.
 
 ## Relationship to workflow
 

package/hooks/scripts/prompt-context.py

@@ -78,7 +78,10 @@ CAPSULES = {
             "Ports & Adapters: domain logic stays independent of DB/filesystem/HTTP/time/randomness.",
             "Single Source of Truth: growing variant sets have one registry; types, validation, routing, and display derive from it.",
             "Generated Contracts: boundary types come from schema/router/DB inference or generation instead of hand copies.",
-            "Fail Fast: unknown input is validated at system boundaries and internal preconditions are asserted early.",
+            "Proportional rigor: validate real boundaries; add invariants, edge handling, and determinism only when context warrants them.",
+            "Code economy: prefer the shortest clear solution and fewer concepts over speculative generality.",
+            "Useful tests: protect important interfaces, complex units, and bug regressions—not every line or surface.",
+            "Leave it simpler: when touching an area, eliminate unnecessary code, tests, checks, abstractions, and compatibility paths; ask before reducing guarantees.",
         ],
     },
     "dispatch_economy": {
@@ -92,6 +95,7 @@ CAPSULES = {
             "Agents are for breadth, isolation, fresh judgment, or independent write ownership.",
             "Parallelism follows ownership and dependency layers rather than item count.",
             "Dispatch rationale belongs in run notes or the item body when it affects bundling or wave width.",
+            "Gate scope: release-bound work is the focus, not a hard boundary; follow concrete evidence and route ambient findings to the unbound backlog.",
         ],
     },
     "advisory_review": {
@@ -104,6 +108,9 @@ CAPSULES = {
             "Cross-model peer review applies only when a different model class is available.",
             "Same-model review uses a fresh-context sub-agent rather than inline self-review.",
             "Stories fast-advance on verification; features and epics get deeper review.",
+            "Reviewer findings are proposals; the receiving orchestrator judges actual risk in repository context.",
+            "Only material current-cycle risk blocks completion; park valid lower-priority findings and continue.",
+            "Foundation docs may describe future intent: review existing claims only; omission or absent implementation is not drift.",
             "Advisory review is non-blocking during design, but final autopilot completion needs a successful review path.",
         ],
     },

package/hooks/scripts/test_prompt_context.py

@@ -372,6 +372,22 @@ class RulesLoaderTest(unittest.TestCase):
         printed = out.getvalue()
         self.assertIn("Agile Workflow Principles", printed)
         self.assertIn("Code-design capsule", printed)
+        self.assertIn("Code economy", printed)
+        self.assertIn("Useful tests", printed)
+        self.assertIn("ask before reducing guarantees", printed)
+
+    def test_gate_prompt_emits_wider_scope_rule(self) -> None:
+        payload = self._payload(
+            session_id="gate-scope", cwd=str(self.root), prompt="gate the release items"
+        )
+        out = io.StringIO()
+        with mock.patch.object(
+            prompt_context.sys, "stdin", io.StringIO(json.dumps(payload))
+        ), mock.patch.object(prompt_context.sys, "stdout", out):
+            rc = prompt_context.main()
+        self.assertEqual(rc, 0)
+        self.assertIn("release-bound work is the focus, not a hard boundary", out.getvalue())
+        self.assertIn("ambient findings", out.getvalue())
 
     def test_main_sessionstart_emits_rules(self) -> None:
         (self.rules_dir / "a.md").write_text("Rule A body", encoding="utf-8")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-agile-workflow",
-  "version": "0.16.1",
+  "version": "0.16.4",
   "description": "Markdown-based work-tracking substrate for AI-driven projects.",
   "author": {
     "name": "nklisch"

package/scripts/work-view.sh

@@ -22,7 +22,7 @@
 set -euo pipefail
 
 # Kept in lockstep with plugin.json by scripts/bump-version.sh. Do not hand-edit.
-WORK_VIEW_VERSION="0.16.1"
+WORK_VIEW_VERSION="0.16.4"
 
 # ============================================================================
 # Version prelude (POSIX / bash 3.2 safe — runs BEFORE the Bash-4 guard)