@nklisch/pi-agile-workflow 0.16.1 → 0.16.3

package/skills/gate-tests/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: gate-tests
 description: >
-  Test-quality gate that scans items bound to a release for test coverage gaps. Delegates the full
-  analysis to a deep test scanner agent which derives expected coverage from each bound item's
-  acceptance criteria (NOT from implementation code), maps existing test coverage, identifies gaps,
-  and returns findings. The orchestrator converts findings into gate_origin:tests items in
+  Test-quality gate focused on release-bound items that may follow relevant evidence into adjacent
+  interfaces and test systems. Derives useful coverage from contracts, risk, and bug history—not
+  line coverage—and identifies both valuable gaps and low-value tests worth removing. Delegates the
+  analysis to a deep test scanner agent, which maps existing coverage and
+  returns findings. The orchestrator converts findings into gate_origin:tests items in
   .work/active/. Auto-triggers during /agile-workflow:release-deploy.
 ---
 
@@ -24,16 +25,18 @@ in the release body.
 
 ## Core principle
 
-The gate's principle: **tests derive from specs, not implementations**. Each
-bound item's acceptance criteria IS the spec. The scanner verifies those
-criteria are covered, finds gaps, and returns them. It also checks the seams
-BETWEEN bound items — integration coverage where one item's output feeds
-another.
+The gate's principle: **tests must earn their upkeep**. Tests derive from
+stable contracts, meaningful risks, and regressions learned from real bugs—not
+from implementation shape or a demand to cover every line. Prefer important
+public interfaces and cross-item seams. Unit tests belong around genuinely
+complex isolated logic, not every wrapper or branch. The gate identifies both
+high-value gaps and duplicate, tautological, brittle, obsolete, or
+implementation-bound tests that should be removed.
 
-Tests derived from reading implementation code are tautological — they verify
-that the code does what the code does. Tests derived from specs verify what
-the code *should* do. That's where bugs live. The scanner brief enforces this
-discipline.
+Bound items are the focus, not a hard scan boundary. Follow concrete evidence
+into adjacent interfaces, shared test infrastructure, dependencies, or a whole
+test/check system when needed. Bind findings to the release only when materially
+relevant; route ambient discoveries to the unbound backlog.
 
 ## Trigger
 
@@ -90,8 +93,10 @@ test-design techniques to find gaps, and returns structured findings.
 **Brief template**:
 
 > You are conducting a test-quality gate for release `<version>`. Core
-> principle: **tests derive from specs, not implementations**. Each bound
-> item's acceptance criteria IS the spec.
+> principle: **tests must earn their upkeep**. Derive tests from stable
+> contracts, meaningful risk, and bug regressions—not implementation shape or
+> universal coverage. Acceptance criteria are evidence of intent, not a mandate
+> for one automated test per statement.
 >
 > Use read/search/shell tools as needed. Do not spawn nested sub-agents or implement
 > fixes.
@@ -143,32 +148,35 @@ test-design techniques to find gaps, and returns structured findings.
 >    - Implementation units / unit names
 >    - Public interface surface (functions, types, endpoints exposed)
 >
->    These four axes plus the explicit acceptance criteria form the spec.
+>    These axes and acceptance criteria describe candidate behavior. Rank them
+>    by consequence, stability, complexity, and demonstrated failure history
+>    before deciding that automated coverage is worthwhile.
 >
-> 2. **Map existing test coverage.** For each bound item, find tests that
+> 2. **Map existing test value and coverage.** For each bound item, find tests that
 >    reference its implementation. For files changed by item `<id>`, list all
 >    tests covering those files. For each test, identify which acceptance
->    criterion or behavioral contract it verifies. Cite file:line. Note any
->    tests that appear to mirror implementation step-by-step (tautological —
->    should be reworked or deleted). Do NOT read implementation bodies; only
->    test files and types. Read 2-3 key test files yourself to verify the map.
+>    criterion, interface, regression, or complex unit it protects. Cite
+>    file:line. Flag tests that mirror implementation step-by-step, duplicate
+>    stronger interface coverage, exercise trivial wrappers, or protect obsolete
+>    behavior; recommend deletion when removal preserves useful confidence.
+>    Read implementation only to establish complexity, interfaces, or whether a
+>    test is coupled to internals—not to invent an assertion target. Read 2-3
+>    key test files yourself to verify the map.
 >
-> 3. **Apply test-design techniques** for each acceptance criterion not
->    covered by tests:
->    - **Equivalence partitioning** — one test per valid partition, one per
->      invalid
->    - **Boundary value analysis** — for ranges: just-below, at, just-above
->    - **Decision table** — for criteria with multiple conditions, enumerate
->      combinations
->    - **State transition** — for state changes, test valid transitions and
->      verify invalid ones are rejected
+> 3. **Apply test-design techniques selectively** to high-value contracts not
+>    already covered. Use only the techniques justified by actual risk:
+>    - **Equivalence partitioning** — choose representative partitions where
+>      distinctions matter
+>    - **Boundary value analysis** — sample consequential range boundaries
+>    - **Decision table** — cover combinations with materially different outcomes
+>    - **State transition** — cover important valid transitions and invalid ones
+>      the contract promises to reject
 >    - **Error guessing (spec-driven)** — anything described as "should
 >      not", "must not", "invalid", "error", "reject"
 >
-> 4. **Adversarial coverage** — for each bound item, surface failure
->    expectations along these axes. If the item body or design doesn't
->    state the answer, the gap itself is a finding (`stage: drafting`,
->    `tags: [testing]`):
+> 4. **Risk review** — for each bound item, consider failure expectations along
+>    these axes only where the project's scope and consequences make them
+>    meaningful. Silence in the spec is not automatically a testing finding:
 >    1. Invalid input — when a caller passes invalid data, what should
 >       happen? (Reject? Fall back? Log and continue?)
 >    2. Missing config — when required configuration is absent, what's the
@@ -182,9 +190,8 @@ test-design techniques to find gaps, and returns structured findings.
 >    6. Interrupted operations — if a multi-step operation is interrupted,
 >       what's the expected end state?
 >
->    Where the spec is silent, produce either: (a) a `[testing]` story to
->    write the test once the spec is settled, or (b) a `[documentation]`
->    story to extend the spec with the missing assertion target.
+>    Where the spec is silent, emit a finding only when the missing contract is
+>    consequential for this project. Otherwise record that no test is warranted.
 >
 > 5. **Map e2e seams.** For items with `depends_on` chains, check whether
 >    the seam between them is tested:
@@ -197,16 +204,17 @@ test-design techniques to find gaps, and returns structured findings.
 >    feature's overall acceptance criteria are e2e-covered, not just
 >    per-story unit-covered.
 >
-> 6. **Classify gaps**:
+> 6. **Classify findings**:
 >    | Priority | Definition |
 >    |---|---|
->    | Critical | Acceptance criterion with no test |
->    | High | Boundary or error case from spec, no test |
->    | Medium | Valid partition or rule combination, no test |
->    | Low | Complementary coverage |
+>    | Critical | High-consequence public contract or known regression lacks protection |
+>    | High | Important interface, seam, or complex behavior lacks useful coverage |
+>    | Medium | Material confidence gain, but not release-critical |
+>    | Low | Ambient improvement or low-value test removal proposal |
 >
->    Also flag tautological tests found during step 2 — they need rework or
->    deletion.
+>    No finding is created merely because a line, branch, unit, edge, or
+>    acceptance statement lacks its own test. Also classify relevance as
+>    `Release-relevant` or `Ambient`, and flag low-value tests for deletion.
 >
 > **Output format** — return a single markdown document with:
 >
@@ -216,10 +224,12 @@ test-design techniques to find gaps, and returns structured findings.
 > ### Finding 1
 > - **Title**: <one-line: spec condition not covered>
 > - **Priority**: Critical | High | Medium | Low
-> - **Bound item**: `<item-id>`
-> - **Acceptance criterion**: <quote the criterion>
-> - **Gap type**: missing test for valid partition / boundary / error case /
->   adversarial-spec-silent / e2e-seam / tautological-rework
+> - **Bound item**: `<item-id>` | none
+> - **Relevance**: Release-relevant | Ambient
+> - **Value protected**: public interface | seam | complex unit | bug regression | test removal
+> - **Contract / risk / regression evidence**: <quote or concrete evidence>
+> - **Gap type**: important-interface / complex-unit / bug-regression /
+>   e2e-seam / low-value-test-removal
 > - **Suggested test**:
 >   ```<lang>
 >   // Sketch of the test — name, scenario, assertion target.
@@ -241,14 +251,14 @@ test-design techniques to find gaps, and returns structured findings.
 > ```
 >
 > **Rules**:
-> - Derive tests from specs, NOT from implementation code. If you find
->   yourself reading a function body to decide what to verify, stop — go
->   back to the spec.
-> - Test the public interface, not internal implementation.
-> - Cite spec references in every finding. A finding without a spec
->   reference is testing an assumption, not a contract.
-> - Prioritize invalid input, error cases, boundary conditions.
-> - Audit only the bundle's items, not the whole repo.
+> - Derive assertion targets from contracts, risk, and bug history—not
+>   implementation steps. Implementation may establish complexity or coupling.
+> - Prefer public interfaces and meaningful seams over internal implementation.
+> - Cite a contract, demonstrated risk, bug regression, or concrete maintenance
+>   cost for every finding. No evidence means no test work.
+> - Do not chase universal edge, branch, line, or surface coverage.
+> - Bound items are the focus, not a hard boundary. Follow concrete evidence and
+>   record why out-of-bundle test systems were inspected.
 > - Skip already-tracked.
 >
 > **Test integrity findings** (additional pass — flag and surface as
@@ -259,8 +269,9 @@ test-design techniques to find gaps, and returns structured findings.
 >   assertions.
 > - Tests that were silenced rather than diagnosed: broad `skip` /
 >   `xfail` / `it.todo` with no linked backlog id or written reason.
-> - Tests deleted in the bundle's commits with no replacement coverage
->   for the same acceptance criterion. (Check `git log` of the bundle.)
+> - Tests deleted in the bundle's commits when the removal leaves an important
+>   interface, complex behavior, or known regression without useful protection.
+>   (Check `git log` of the bundle.)
 > - Tests whose assertion was rewritten to match new-but-undocumented
 >   behavior — i.e. the test was made to follow the code instead of the
 >   code being made to follow the spec.
@@ -289,7 +300,7 @@ stage: implementing       # critical/high
 tags: [testing]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: tests
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -300,9 +311,9 @@ updated: YYYY-MM-DD
 ## Priority
 Critical | High | Medium | Low
 
-## Spec reference
-Item: `<bound-item-id>`
-Acceptance criterion: <quote the criterion>
+## Value evidence
+Item: `<bound-item-id>` (or `none` for ambient findings)
+Contract / risk / regression / maintenance cost: <concrete evidence>
 
 ## Gap type
 <missing test for valid partition / boundary / error case / etc.>
@@ -316,6 +327,10 @@ Acceptance criterion: <quote the criterion>
 `<test-file-path>` (following project conventions)
 ```
 
+Release-relevant findings use the normal priority mapping and bind to the
+release. Ambient findings—including repository-wide low-value test systems
+merely discovered by the scan—go to the unbound backlog regardless of priority.
+
 Default priority -> placement mapping:
 - **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -327,8 +342,8 @@ Tautological tests get items too:
 # id: gate-tests-rework-<original-test-slug>
 # kind: story
 # tags: [testing, refactor]
-# Body describes which test is tautological and what spec behavior it should be
-# rewritten to verify (or marked for deletion).
+# Body describes why the test adds too little confidence for its upkeep and
+# whether it should be rewritten around a valuable contract or deleted.
 ```
 
 ### Phase 5: Commit
@@ -343,7 +358,8 @@ git commit -m "gate-tests: <N> coverage gaps for <version>"
 In conversation:
 - **Bundle**: `<version>` — `<N>` items audited
 - **Coverage gaps**: count by priority
-- **Tautological tests flagged**: count
+- **Low-value tests flagged for removal**: count
+- **Ambient findings**: count routed to unbound backlog
 - **Items created**: count, with new ids
 - **Already-tracked**: count of duplicates skipped
 
@@ -352,12 +368,11 @@ In conversation:
 - **The analysis happens in the scanner agent, not here.** Your job is bundle
   prep, dispatch, and item-writing. Don't replicate the scanner's contract
   extraction or coverage mapping.
-- The scanner brief enforces "specs not implementations". Don't substitute
-  your own judgment for findings.
-- Cite spec references in every item body. The scanner provides them.
-- Prioritize invalid input, error cases, boundary conditions — that's where
-  bugs hide and specs are most often undertested.
-- Audit only the bundle's items, not the whole repo.
+- The scanner brief enforces contract/risk/regression value over implementation
+  shape or coverage metrics. Don't substitute line-coverage pressure.
+- Cite the contract, risk, regression, or maintenance cost in every item body.
+- Release-bound items define focus, not a hard boundary. Follow concrete
+  evidence, but route ambient discoveries to the unbound backlog.
 - A failing test that exposes a real spec violation is the most valuable
   output. Don't sand it down — surface it as a Critical finding so the
   implementation gets fixed before shipping.

package/skills/implement/SKILL.md

@@ -169,7 +169,8 @@ In land mode:
    as-built reality (paths, interfaces, signatures).
 2. Validate — typecheck, lint, tests scoped to touched packages
    (`pnpm --filter`, `cargo -p`, `pytest <path>`).
-3. Fill test gaps for any meaningful behavior that lacks coverage.
+3. Fill high-value test gaps at stable interfaces, for complex logic, or for
+   demonstrated regressions; remove obsolete or low-value tests exposed by the work.
 4. Skip Phase 6 (no new code) and go straight to Phase 7 (notes — log
    "Land mode" explicitly), Phase 8 (verify), Phase 9 (commit + advance).
 
@@ -196,13 +197,19 @@ For code items:
 For each unit/file in the item's design:
 1. Write the code following the design's specifications — exact types, signatures,
    contracts
-2. Apply established patterns from the codebase
-3. Handle every error path the design specifies
-4. Write tests that verify behavior, not implementation
+2. Apply established patterns from the codebase without adding speculative layers
+3. Handle the error paths and guarantees the design actually requires
+4. Write tests only where they protect an important interface, complex unit, or
+   demonstrated regression; remove low-value tests the change makes obsolete
 5. Update module exports (index files) so new code integrates cleanly
+6. Run an elimination pass over the touched area: delete, inline, or consolidate
+   code, checks, abstractions, compatibility paths, and test machinery made
+   unnecessary by the implementation
 
-Take pride in the details: clean variable names, idiomatic control flow, meaningful
-error messages. Code that a future developer would read with appreciation.
+Safe behavior-preserving cleanup that is cohesive with the touched code is part
+of the task. Park larger or unrelated cleanup, and stop for a design decision
+before weakening behavior, guarantees, validation, compatibility, or safety.
+Prefer short, direct, readable code over a generalized framework.
 
 ### Phase 7: Update item body with implementation notes
 
@@ -213,7 +220,8 @@ Append (or update) an "Implementation notes" section in the item's body:
 - Execution capability: <choice and brief risk/scope rationale>
 - Review weight: <effective value and source: caller, project, or default>
 - Files changed: <list>
-- Tests added: <list>
+- Tests added/removed: <list and the interface, complexity, or regression value>
+- Simplification: <code, checks, abstractions, or compatibility paths removed/consolidated>
 - Discrepancies from design: <list with one-line explanation each, or "none">
 - Adjacent issues parked: <list of backlog ids if any, or "none">
 ```
@@ -294,6 +302,8 @@ In conversation:
 - If you discover a genuine design flaw, don't muscle through. Append a
   `## Implementation discovery` section, set stage back to `drafting`, and
   return. The design family will pick it up on the next pass.
-- Adjacent issues you notice get parked via `/agile-workflow:park`, not bundled.
+- Safe, cohesive simplification in the touched area belongs in the task. Park
+  larger, unrelated, or behavior-changing opportunities instead of silently
+  expanding scope.
 - Test integrity is non-negotiable: follow the project rules and worker posture;
   fix bad tests, park real production bugs, and never game tests.

package/skills/principles/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: principles
 description: >
-  agile-workflow principles — code-design (Ports & Adapters, Single Source of Truth, Generated
-  Contracts, Fail Fast) and substrate-execution (Item-IS-the-Work, Rolling-Foundation, Late-Binding).
+  agile-workflow principles — code-design (clear boundaries, proportional rigor, code economy,
+  useful tests, and continuous simplification) and substrate-execution (Item-IS-the-Work,
+  Rolling-Foundation, Late-Binding).
   Auto-loads when designing modules, defining interfaces, writing or implementing code, scoping work
   in the substrate, advancing stages, scoping releases, or any time the agile-workflow
   design/implement/review skills are active.
@@ -23,7 +24,7 @@ Each principle has guidance for design time and implementation time.
 
 # Part I — Code-Design Principles
 
-These four invariants stay active during design and implementation. Load
+These principles stay active during design and implementation. Load
 [references/code-design.md](references/code-design.md) when concrete mechanics,
 checklists, or examples are needed.
 
@@ -44,11 +45,35 @@ Boundary types derive from the schema, router, database model, or a generation
 step. Consumers import or infer that contract instead of maintaining hand-written
 copies.
 
-## 4. Fail Fast
+## 4. Fail Fast—Where It Matters
 
-Validate unknown input at system boundaries and assert internal preconditions at
-function entry. Reject invalid state early with specific errors instead of
-letting it fail deep in the call chain.
+Validate untrusted input and required external contracts at system boundaries.
+Add internal checks only when the project's actual risks justify them. Do not
+manufacture exhaustive invariants, edge handling, determinism, or defensive
+layers that the product's scope and consequences do not need.
+
+## 5. Code Economy
+
+Short, direct code is a virtue when it stays clear. Prefer fewer concepts,
+layers, branches, options, and lines over speculative generality. Match rigor to
+the project's context rather than engineering every codebase as critical
+infrastructure.
+
+## 6. Tests Earn Their Keep
+
+Test stable interfaces, important behavior, and regressions learned from real
+bugs. Unit-test genuinely complex units, not every wrapper, branch, or line.
+Tests are maintained code: remove duplicate, tautological, implementation-bound,
+or otherwise low-value tests when their upkeep exceeds the confidence they add.
+
+## 7. Leave It Simpler
+
+Exploration, design, and implementation include an elimination pass. In the
+area being touched, look for code, tests, checks, abstractions, compatibility
+paths, and complexity that the feature can make unnecessary. Fold safe,
+cohesive cleanup into the work or create explicit cleanup/refactor stories;
+park broader opportunities. Question whole systems when warranted, but ask the
+user before removing behavior, guarantees, validation, compatibility, or safety.
 
 ---
 
@@ -60,7 +85,7 @@ dispatch. The agent applies these whenever operating on `.work/` or `docs/`,
 and whenever choosing discovery or implementation dispatch during substrate
 work.
 
-## 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 stages advance. Reading the file IS reading the state of the work.
 
@@ -100,7 +125,7 @@ The unit of work is its file. The brief, the design, the implementation notes, a
 
 ---
 
-## 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.
 
@@ -152,7 +177,7 @@ The discipline is identical in both styles: replace stale assertions in place, n
 
 ---
 
-## 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 into a phase plan. Work happens, then commitments crystallize — not the other way around.
 
@@ -192,7 +217,7 @@ Items advance stages when work actually completes. Releases bind items only when
 
 ---
 
-## 8. Agent Dispatch Economy
+## 11. Agent Dispatch Economy
 
 Sub-agents are for breadth, isolation, independent judgment, or parallel
 implementation with clear write ownership. They are not a replacement for
@@ -363,12 +388,36 @@ for their owning stories.
   reason. A slow top-tier reviewer is not a failure until its appropriately
   sized timeout or mechanism reports failure.
 - **Strict completion:** final autopilot completion must clear a successful
-  review path and resolve or file accepted findings. At weights `light` through
+  review path and adjudicate every proposed finding. At weights `light` through
   `maximum`, that path must use a supported fresh-context reviewer; if it fails,
   the run is blocked rather than complete. At explicit weight `none`, documented
   implementation verification and acceptance evidence satisfy the path without
   independent review.
 
+## Recipient-owned finding disposition
+
+Reviewer output is evidence, not authority. The receiving agent orchestrating the
+run independently verifies each claim and assigns its disposition against the
+repository's actual context: acceptance criteria, supported users and deployment
+shape, likelihood, blast radius, recoverability, existing safeguards, and the
+cost of delaying the current work. A reviewer's `blocker` label never binds the
+receiver by itself, and disagreement is resolved by evidence rather than
+seniority or model strength.
+
+A finding blocks the current cycle only when the receiver judges it a credible,
+material risk to required correctness, security, data integrity, public
+contracts, acceptance criteria, release safety, or trustworthy verification.
+Fix those findings now or keep an active item that prevents completion. Park a
+valid concern below that bar in the unbound backlog with its risk rationale and
+continue; leave nits in review notes, and reject unsupported findings with a
+brief reason. Rarity alone does not make a case irrelevant, but a corner case's
+likelihood and consequence must justify its delivery cost. Repetition across
+review passes does not elevate severity by itself.
+
+A successful review path therefore means independent scrutiny ran when required
+and the receiving agent adjudicated the results. It does not mean every reviewer
+suggestion was implemented or promoted into the active queue.
+
 User instructions and project-level review/egress rules override defaults. Do
 not invoke an external peer mechanism when policy prohibits it. `--only-questions`
 is user alignment and therefore skips advisory review.
@@ -398,12 +447,17 @@ family (`gate-cruft`, `gate-security`, `gate-tests`, `gate-docs`,
 
 | Arg | Behavior |
 |---|---|
-| no arg / `--all` | Sweep the relevant scope (whole codebase, or release bundle for gates) |
+| no arg / `--all` | Sweep the relevant scope; release-bound items are a gate's focus, not a hard scan boundary |
 | `<path>` | Scope to that subtree |
 | `<NL scope>` | Interpret free text against the codebase; log the interpretation |
 | `<feature-id>` (where applicable) | Per-feature design mode (refactor-design, perf-design) |
 
 These skills *emit substrate items as findings* rather than gating pass/fail.
+For release gates, follow relevant evidence into adjacent dependencies, shared
+infrastructure, or system-wide mechanisms. Bind findings to the release only
+when they are caused by, exposed by, or materially relevant to it; route merely
+ambient discoveries to unbound backlog proposals so a gate does not silently
+expand release scope.
 
 ## Per-item design verbs
 

package/skills/principles/references/advisory-review.md

@@ -44,6 +44,12 @@ Always run completeness before attack:
    attack pass; completed artifacts may use the same bounded convergence shape.
    Verify concrete claims before accepting them.
 
+The receiving/orchestrating agent owns the verdict on every returned finding.
+Apply Part IV's material-risk threshold in repository context; do not inherit a
+reviewer's severity label. Fix or activate only current-cycle blockers, park
+valid lower-priority concerns in the unbound backlog, and reject unsupported
+claims with a reason.
+
 For deep or complex work, use a different model class for Phase 2 than Phase 1
 when two classes are available. Their disagreement is evidence to investigate,
 not a vote. For routine design, do not turn a focused advisory pass into a
@@ -58,7 +64,8 @@ Summarize evidence and decisions in the item body; never paste transcripts:
 - Invoked because: <risk or uncertainty>
 - Phase 1 — advisory/completeness: <reviewer class and useful gaps>
 - Phase 2 — adversarial: <reviewer class and failure modes>
-- Accepted: <adjustments with phase>
+- Fixed/active blockers: <material current-cycle risks and disposition>
+- Parked: <valid lower-priority concerns and risk rationale>
 - Rejected: <points and reasons with phase>
 - Skipped/degraded: <phase and reason, if any>
 ```

package/skills/principles/references/code-design.md

@@ -9,7 +9,10 @@ concrete boundary guidance, checklists, or examples.
 1. [Ports & Adapters](#1-ports--adapters)
 2. [Single Source of Truth](#2-single-source-of-truth)
 3. [Generated Contracts](#3-generated-contracts)
-4. [Fail Fast](#4-fail-fast)
+4. [Fail Fast—Where It Matters](#4-fail-fastwhere-it-matters)
+5. [Code Economy](#5-code-economy)
+6. [Tests Earn Their Keep](#6-tests-earn-their-keep)
+7. [Leave It Simpler](#7-leave-it-simpler)
 
 ## 1. Ports & Adapters
 
@@ -84,11 +87,13 @@ Checklist:
 - Generation or inference is part of the build path.
 - No hand-written type mirrors a schema, router, or database definition.
 
-## 4. Fail Fast
+## 4. Fail Fast—Where It Matters
 
-Validate unknown input at system boundaries before domain logic runs. Assert
-internal preconditions at function entry with specific guard errors and early
-returns; do not propagate invalid state into deeper call chains.
+Validate untrusted input and required external contracts at system boundaries
+before domain logic runs. Add internal guards when a violated precondition is
+plausible and consequential; do not turn every helper into a defensive boundary.
+The project decides how much invariant enforcement, edge handling, and
+determinism it actually needs.
 
 ```typescript
 function processOrder(input: unknown) {
@@ -105,3 +110,55 @@ function applyDiscount(order: Order, pct: number) {
 Boundary examples include HTTP handlers, CLI arguments, external API responses,
 and configuration files. Internal checks should report the violated
 precondition and received value whenever that is safe.
+
+Checklist:
+- Validate real trust boundaries and explicit contracts.
+- Match defensive rigor to failure consequences and project scope.
+- Do not add checks, retries, invariants, or determinism only because a more
+  general system might need them.
+
+## 5. Code Economy
+
+Prefer the shortest clear expression of the project's actual requirements.
+Every abstraction, option, layer, fallback, and branch creates maintenance cost;
+it must earn that cost in current scope rather than a hypothetical future.
+Terse does not mean cryptic: optimize for fewer concepts, then fewer lines.
+
+Checklist:
+- Choose the direct solution before a configurable framework.
+- Avoid extension points without a current second use or committed need.
+- Delete incidental machinery made obsolete by the change.
+
+## 6. Tests Earn Their Keep
+
+Automated tests are maintained code. Prioritize stable public interfaces,
+important cross-component seams, high-consequence behavior, and regression tests
+for real bugs. Unit tests belong around genuinely complex logic where isolated
+examples add confidence; simple wrappers and implementation details usually do
+not need their own tests.
+
+Checklist:
+- Name the interface, risk, or regression each test protects.
+- Prefer a useful interface test over several implementation-bound unit tests.
+- Do not chase line coverage or enumerate every possible surface by default.
+- Remove duplicate, tautological, brittle, or low-value tests when they no
+  longer justify upkeep.
+
+## 7. Leave It Simpler
+
+Treat elimination as part of feature work, not a separate activity reserved for
+refactors. During exploration and design, identify code, tests, checks,
+abstractions, compatibility paths, and configuration that the proposed feature
+can make unnecessary. During implementation, perform safe cohesive cleanup in
+the touched area and create explicit cleanup/refactor stories for larger work.
+
+Question whole systems as well as local fragments. Removing behavior,
+guarantees, validation, determinism, compatibility, or safety is a product
+choice: explain the trade-off and ask the user rather than silently weakening
+it.
+
+Checklist:
+- Record what the feature can delete or consolidate.
+- Prefer deletion and inlining before extraction or another abstraction.
+- Leave touched code simpler unless doing so would blur scope or alter behavior.
+- Park broader opportunities; ask before reducing meaningful guarantees.