# pidex-planner Rules Index

Last updated: 2026-05-18 (PROC-NEW-7-1)

## Active Rules

| Rule | File | PROC-NEW | Summary |
|------|------|----------|---------|
| Structural Code Search Default | [../shared/structural-code-search.md](../shared/structural-code-search.md) | PROC-AST-GREP-1 | Prefer ast-grep for structural code searches; use rg for literal text and document the chosen search evidence |
| Provider-Safe Defensive Review Language | [../shared/provider-safe-defensive-review-language.md](../shared/provider-safe-defensive-review-language.md) | PROC-PROVIDER-SAFE-1 | Frame authorized local reviews as concrete defensive invariants; compact refusal recovery preserves findings and gates |
| Package Manager Equivalence | [../shared/package-manager-equivalence.md](../shared/package-manager-equivalence.md) | PROC-PACKAGE-MANAGER-1 | Use detected package-manager equivalents; pnpm native/default, npm compatibility, yarn/bun unsupported; avoid lockfile type changes and npx auto-downloads |
| Greenfield JS/TS Package Manager Default | [greenfield-js-package-manager-default.md](greenfield-js-package-manager-default.md) | PROC-PACKAGE-MANAGER-2 | New PIDEX-generated JS/TS projects default to pnpm; existing unknown projects require package-manager clarification |
| Epic Label vs Semver Disambiguation | [epic-label-semver-disambiguation.md](epic-label-semver-disambiguation.md) | PROC-NEW-SEMVER-1 | Plans must distinguish roadmap epic labels from package semver/tag lanes and record release-lane semantics |
| Release-Artifact Milestone Owner + Gate Binding | [release-artifact-owner-gate-binding.md](release-artifact-owner-gate-binding.md) | PROC-NEW-94-1 | Release-artifact/version milestones must declare owner + target gate + closure proof before Stage 2 |
| Artifact Authority Test Matrix | [artifact-authority-test-matrix.md](artifact-authority-test-matrix.md) | 1 | Resolver/path authority plans must include runtime-root, test override, fixture-isolation matrix with validation rows |
| Cross-Lane Synthesis Checkpoint | [cross-lane-synthesis-checkpoint.md](cross-lane-synthesis-checkpoint.md) | 029-PI-1 | Structural contract plans with multi-lane findings must merge overlaps/conflicts into one synthesis table before G1 close |
| Format/Footer Contradiction Scan | [format-footer-contradiction-scan.md](format-footer-contradiction-scan.md) | 029-PI-2 | Plans changing output-format/footer/last-line rules must contradiction-scan impossible pairs before critic/implementer route |
| G1 Dirty Release-Artifact Ownership Slice | [g1-dirty-release-artifact-ownership-slice.md](g1-dirty-release-artifact-ownership-slice.md) | 027-PI-2 | If intake has dirty release artifacts, plan must declare artifact owner, commit slice, inclusion scope, and validation proof before implementation routing |
| Artifact Existence Preflight for Gate Context Contracts | [artifact-existence-preflight.md](artifact-existence-preflight.md) | 026-1 | Plans referencing gate-consumed artifact paths must include existence preflight before validation run |
| Release-Lane Taxonomy Collision Handling | [release-lane-taxonomy-collision-handling.md](release-lane-taxonomy-collision-handling.md) | 026-3A | Plans with naming/ID overlap across streams must declare canonical release lane metadata and collision check |
| User Preview Requirement | [user-preview-requirement.md](user-preview-requirement.md) | UI-PREVIEW | Plans must declare UI involvement and whether post-devops user preview is required before G4 |
| UI Intent Boundary and Existing UI Parity | [ui-intent-boundary-parity.md](ui-intent-boundary-parity.md) | UI-INTENT-PARITY | Existing-screen UI plans must declare must-preserve/may-change/forbidden changes and parity mapping |
| UI Label Source Contract | [ui-label-source-contract.md](ui-label-source-contract.md) | PIPELINE-ANALYST-1A | Repeated/hierarchical/status UI plans must bind visible labels to source-of-truth fields/constants |
| Binding-ID Validation References | [binding-id-validation-references.md](binding-id-validation-references.md) | PIPELINE-ANALYST-1B | Validation/AC rows must cite load-bearing binding table IDs verbatim to prevent prose drift |
| Atomic Transition + Artifact-Gate Acceptance Tests | [atomic-transition-artifact-gate-acceptance-tests.md](atomic-transition-artifact-gate-acceptance-tests.md) | 020-1 | Route transitions consuming prior artifacts must declare atomic gate + artifact-path acceptance tests |
| Release Authority + Pass/Waiver Stanza | [release-authority-pass-waiver-stanza.md](release-authority-pass-waiver-stanza.md) | 4 | High-risk release plans must include fixed authority split and blocker pass/waiver stanza |
| Fixture Derivation | [fixture-derivation.md](fixture-derivation.md) | X1 | Derive domain entity IDs from existing fixture files; never invent identifiers or use developer-internal names in user-visible fixtures |
| Playwright Smoke AC | [playwright-smoke-ac.md](playwright-smoke-ac.md) | UI-smoke | UI plans must name Playwright Browser-Level Smoke as explicit AC row |
| UI Pattern Source Contract | [ui-pattern-source-contract.md](ui-pattern-source-contract.md) | UI-PATTERN-SOURCE | UI plans that match/reuse existing UI must bind source pattern, parity checklist, screenshot matrix, and browser flow |
| UI Screenshot Matrix Contract | [ui-screenshot-matrix-contract.md](ui-screenshot-matrix-contract.md) | UI-SCREENSHOT-MATRIX | UI plans declare exact screenshot states, viewports, evidence, and artifact directory |
| Mobile UI Contract | [mobile-ui-contract.md](mobile-ui-contract.md) | MOBILE-UI-CONTRACT | Mobile-relevant UI plans specify viewport, touch, keyboard, safe-area, overlay, and evidence expectations |
| UI Accessibility Baseline | [ui-accessibility-baseline.md](ui-accessibility-baseline.md) | UI-A11Y-BASELINE | Interactive UI plans specify labels, keyboard/focus, announcements, contrast, and touch-target evidence |
| Execution Profile Contract | [execution-profile-contract.md](execution-profile-contract.md) | EXECUTION-PROFILE | Plans declare risk profile and skipped-agent safety before implementation; declaration only, no routing automation |
| Retro Mode Contract | [retro-mode-contract.md](retro-mode-contract.md) | RETRO-MODE | Plans declare none/mini/full retro mode and post-retro handoffs |
| Value Statement / Scope Alignment | [value-statement-scope-alignment.md](value-statement-scope-alignment.md) | 35a | Any broad claim in the Value Statement ("all X", "zero Y") must be fully enumerated in the Scope table — or the Value Statement must be narrowed to named items |
| Branch State Verification | [branch-state-verification.md](branch-state-verification.md) | 35b | Before writing a plan that references a branch from a prior plan, run `git branch --list` to confirm the branch still exists |
| MSW Handler Scope Audit | [msw-handler-scope-audit.md](msw-handler-scope-audit.md) | 36a | Plans adding both a new API route and MSW handler must document global-vs-test-local scope |
| CLI Spawn PATH Invariant | [cli-spawn-path-invariant.md](cli-spawn-path-invariant.md) | 36c | Plans spawning external CLI from Vite/Node must document explicit PATH construction as plan invariant |
| .env.local Credential Conflict Check | [env-credential-conflict-check.md](env-credential-conflict-check.md) | 36d | Plans spawning CLI with native auth must audit .env.local for placeholder values that shadow native credentials |
| Multi-Spawn Version Tag Strategy | [multi-spawn-tag-hold.md](multi-spawn-tag-hold.md) | 39a | Spawn B plans must include a "Version Tag Strategy" section (Hold / Pre-release / Force-move); final tag must not be pushed until all Spawns complete |
| UUID Read-First on Skeleton Pre-Creation | [uuid-skeleton-read-first.md](uuid-skeleton-read-first.md) | 39b | Before pre-creating any output skeleton (Rule 9b), read plan frontmatter and copy UUID verbatim — never generate a fresh UUID |
| Version Bump: apps/web-only (Post-Plan D) | [version-bump-post-plan-d.md](version-bump-post-plan-d.md) | 41a | Since Plan D, bump only apps/web/package.json for feature releases; do NOT bump root package.json unless §Version Policy Exception section present |
| Exports Map S0 Sub-task | [exports-map-s0-subtask.md](exports-map-s0-subtask.md) | 42b | When a plan adds a new module under a package with an explicit exports map (e.g., packages/core/package.json), the exports update must appear as a named S0 sub-task — not a risk entry |
| waitFor Re-Query Constraint | [waitfor-requery-constraint.md](waitfor-requery-constraint.md) | 43a | Timing-fix plans using `waitFor` must state explicitly: DOM element refs MUST be queried inside the callback, never closed over from outside |
| Timing-Fix AC Full-Suite Runs | [timing-fix-ac-full-suite-runs.md](timing-fix-ac-full-suite-runs.md) | 43b | Timing/flake-fix plans must include an AC row requiring 4 consecutive full-suite runs with 0 failures — 1 run is insufficient |
| MSW Test-Local Registration Sub-Task | [msw-test-local-registration.md](msw-test-local-registration.md) | 44a | When plan chooses test-local MSW scope, the implementing slice must name the test file and server.use() sub-task explicitly — AP citation alone is not sufficient |
| Derived Display Value Assertions | [derived-display-assertions.md](derived-display-assertions.md) | 44b | Plans introducing derived display values (count badges, stats, computed labels) must include a V-matrix AC row asserting the derived value against known test-controlled input |
| Option A/B Sufficiency Gate | [option-ab-sufficiency-gate.md](option-ab-sufficiency-gate.md) | 45a | When plan revision defers Option B as "cleanup/later," add an Option A Sufficiency Check table and verify each required runtime condition before declaring Option A sufficient |
| Playwright Smoke Baseline (Live Data) | [live-data-smoke-baseline.md](live-data-smoke-baseline.md) | 45b | V-matrix rows testing whether a specific action caused data to appear must specify clean-storage baseline: assert count=0 before trigger, assert count=N after |
| Orchestrator CRITICAL-Finding Log Entry | [orchestrator-critical-finding-log.md](orchestrator-critical-finding-log.md) | 47-1 | When orchestrator resolves a critique CRITICAL via briefing note (Path A), append a one-line changelog entry to the plan doc before spawning the implementer |
| HA Domain Derivation Guard | [ha-domain-derivation-guard.md](ha-domain-derivation-guard.md) | 47-3 | Plans filtering HA entities by domain must state derivation method in §Assumptions and include a near-match V-matrix guard row |
| Consumer Audit for Entity Mutations | [consumer-audit.md](consumer-audit.md) | 49-2 | Plans adding callbacks/props to shared entity components must audit all consumers (grep all files rendering the entity) and wire each YES row |
| Adapter Lazy-Init Requirement | [adapter-lazy-init-requirement.md](adapter-lazy-init-requirement.md) | 50-1 | New service adapters reading env vars must specify lazy config loading (on first use) as an architecture invariant — eager module-level loading causes dev server crashes |
| LLM Infra Prompt Context | [llm-infra-prompt-context.md](llm-infra-prompt-context.md) | 50-2 | Plans with LLM-driven infra actions must include an "ENVIRONMENT FACTS" subsection in the system prompt spec (service names, IPs, installed tools) |
| Tool Registry Naming Table | [tool-registry-naming-table.md](tool-registry-naming-table.md) | 50-3 | Plans introducing a tool registry must include a binding table: tool registry key, adapter method, description — exact key strings must match dispatch object and system prompt |
| External API Endpoint Verification | [external-api-endpoint-verification.md](external-api-endpoint-verification.md) | 50-4 | Plans calling real external APIs must include an EV-X sub-task in S0/S1 to curl-verify endpoint URL, HTTP method, and response shape before any dependent slice |
| Concurrency Ordering Pseudocode | [concurrency-ordering-pseudocode.md](concurrency-ordering-pseudocode.md) | 50-5 | Plans with ordering invariants ("X before Y") must include a BINDING pseudocode block at the route-handler level — prose alone is insufficient for TOCTOU/concurrency constraints |
| Protocol Pseudocode Binding | [protocol-pseudocode-binding.md](protocol-pseudocode-binding.md) | 50-6 | Pseudocode defining a message protocol must be labelled BINDING CONTRACT or NON-BINDING EXAMPLE; "ILLUSTRATIVE ONLY" is prohibited on load-bearing protocol specs |
| Status Enum UI Affordance Audit | [status-enum-ui-audit.md](status-enum-ui-audit.md) | 50-7 | Plans adding/changing status values on UI-rendered entities must include a complete Status Enum Audit table with a non-empty UI Affordance column for every status value |
| TDD Budget Multiplier | [tdd-budget-multiplier.md](tdd-budget-multiplier.md) | 51-1 | Plans with ≥8 new tests in one spawn must use `(test_count × 2.5) + impl_overhead + version_overhead` formula |
| Gate G9 Applicability Declaration | [g9-applicability-declaration.md](g9-applicability-declaration.md) | 51-2 | Testing Strategy must declare G9 required or not applicable; absence defaults to required |
| Plan Pre-Submission Checklist | [plan-pre-submission-checklist.md](plan-pre-submission-checklist.md) | 53-2 | Self-audit checklist before critic submission: WHAT-not-HOW ACs, BD-* naming, AC-N format, scope table, env var naming |
| Screenshot Artifact Directory Contract | [screenshot-artifact-directory-contract.md](screenshot-artifact-directory-contract.md) | 54-3 | Plans requiring screenshots must bind a single project-local artifact dir (default `.playwright/`) and enforce `.gitignore` coverage |
| Route Security Contract Table | [route-security-contract-table.md](route-security-contract-table.md) | 61-1 | Plans adding/changing API routes must include compact Route Security Contract table (status, sanitized outward error string, non-leak proof) |
| API Security Match Boundary Table | [api-security-match-boundary-table.md](api-security-match-boundary-table.md) | PROC-NEW-7-1 | API-security plans with matcher/risk branches must include non-match boundary matrix and branch-specific action/category mapping |
| Monorepo Migration Pre-Checks | [monorepo-migration-prechecks.md](monorepo-migration-prechecks.md) | extracted | Plans moving code across directory/runtime cwd boundaries must audit path-sensitive primitives before implementation |
| Third-Party Registry Check | [third-party-registry-check.md](third-party-registry-check.md) | extracted | Plans adding exact third-party packages must verify active/canonical registry name/version |
| Multi-Slice Budget Risk | [multi-slice-budget-risk.md](multi-slice-budget-risk.md) | PROC-7 | Plans >4 slices or >30 estimated tool-calls need split/spawn/risk strategy and spawn markers |
| Structural Route-Contract Table (Pre-Critic) | [structural-route-contract-table.md](structural-route-contract-table.md) | 019-1 | Structural route-graph plans must include full role-edge/skip/terminal route-contract table before critic handoff |
| Table UI Checklist + Copy Semantics Contract | [table-ui-copy-contract.md](table-ui-copy-contract.md) | UI-TABLE-COPY | Table/list UI plans bind layout constraints; agent/audit/AI copy must match actual deterministic vs LLM behavior |
| Plan Lint Preflight | [plan-lint-preflight.md](plan-lint-preflight.md) | 69-2 | Plans with profiles/skips/retro/version/G9 triggers must lint enum, retro consistency, release coherence, G9 applicability, and artifact path uniqueness before critic handoff |
| UI-Heavy Profile + Designer Preflight | [ui-heavy-profile-designer-preflight.md](ui-heavy-profile-designer-preflight.md) | UI-HEAVY-PREFLIGHT | UI-heavy plans must use supported profile enum, keep designer active, and retain security separately when API/data surfaces are touched |
| Degraded Badge Contract Table | [degraded-badge-contract-table.md](degraded-badge-contract-table.md) | 74-1 | Plans with degraded/unknown semantics must ship one canonical status→badge/copy/aria/fallback table; alternates forbidden |

| Layout Parity Exact Element Reference | [layout-parity-element-ref.md](layout-parity-element-ref.md) | 034-2 | Layout parity tasks must specify exact element path (route → element + class list), not just page name |
| Seed Data as Plan Prerequisite | [seed-data-prerequisite.md](seed-data-prerequisite.md) | 034-3 | Multi-step nav plans must declare seed data as explicit prerequisite with idempotent setup script |
| Migration Contract Matrix | [migration-contract-matrix.md](migration-contract-matrix.md) | PROC-NEW-88-1 | Migration handoffs MUST include endpoint response-shape + action-contract matrix before implementation routing |
| Collection Completeness AC for Parser-Heavy Plans | [collection-completeness-ac.md](collection-completeness-ac.md) | PROC-NEW-92-2 | Parser-heavy plans must include AC + validation rows proving per-item collection validation and item-level rejection paths |
| Release-Coherence Matcher Grammar | [release-coherence-matcher-grammar.md](release-coherence-matcher-grammar.md) | PROC-NEW-1 | Terminal-close/release-coherence plans must define matcher grammar, negative examples, and AC evidence before critic handoff |
## How to use

Read this index at task start. Load specific rule files when relevant to current task.