prizmkit 1.1.153 → 1.1.155

package/bundled/skills/app-planner/references/rules/backend/fixed-rules.md

@@ -1,285 +1,130 @@
-# Fixed Rules — Complete Backend Fixed Rules
-
-> This file is read by the `backend-rules` skill in Phase 1 and injected directly into `backend-rules.md`.
-> These rules are industry consensus / best practices — **do not ask the user**.
-> Every rule includes RATIONALE so the AI understands intent, not just constraints.
-
----
-
-## F1. Project Structure
-
-### F1.1 Layered Architecture (Mandatory)
-
-- **Rule**: Must use one of the following layering patterns, and be consistent across the project:
-  - Classic three-tier: `controller → service → repository`
-  - DDD-style: `handler → usecase → repository` (Go) / `router → service → dao` (Node)
-- **Rule**: Upper layers must not bypass lower layers (controller must not call repository directly).
-- **Rule**: Each layer does only its own job — controller handles request validation and response formatting, service handles business logic, repository handles data access.
-- **RATIONALE**: Mixed layer boundaries are the #1 cause of backend code rot. When AI can't tell which layer does what, business logic scatters into controllers.
-
-### F1.2 Directory Conventions
-
-- **Rule**: The project root structure must clearly reflect the layering.
-- **Rule**: Shared utilities (utils) must be isolated from business code.
-- **Rule**: Config, constants, and type definitions are centrally managed.
-- **Forbidden**: Turning `utils/` into a dumping ground for anything without a clear home.
-- **RATIONALE**: The directory structure is the project's first piece of documentation. A new developer (including AI) should know where a function belongs just by reading it.
-
-### F1.3 Module Boundaries
-
-- **Rule**: Organize by business domain, not by technical layer (types/services/models cross-domain).
-- **Rule**: Modules communicate through explicit interfaces. Do not access another module's internal implementation directly.
-- **Forbidden**: Circular dependencies (module A imports B, B imports A).
-- **RATIONALE**: Technical-layer organization scatters code for a single feature across 4–5 directories. Changing one feature requires jumping across directories.
-- **Note on layering interaction with F1.1**: Organize by business domain at the top level. Within each domain directory, enforce the layering from F1.1 (e.g., user/controller/, user/service/, user/repository/). Do NOT create top-level controllers/, services/, repositories/ directories that span all domains.
-
----
-
-## F2. API Design
-
-### F2.1 REST Contract
-
-- **Rule**: URLs use plural nouns (`/users`, `/orders`), never verbs (forbid `/getUser`, `/createOrder`).
-- **Rule**: HTTP method semantics must be correct:
-  - `GET` — query, must not modify data
-  - `POST` — create
-  - `PUT` — full update
-  - `PATCH` — partial update
-  - `DELETE` — remove
-- **Rule**: Standard pagination params: `page` (1-based), `pageSize` (default 20, max 100).
-- **Rule**: Standard sorting params: `sortBy=field&sortOrder=asc|desc`.
-- **RATIONALE**: The API is a contract between frontend and backend. Inconsistent naming and parameter formats cause bugs in consumers.
-
-### F2.2 Status Codes
-
-- **Rule**: Use HTTP status codes strictly by semantics:
-  - `200` — query success
-  - `201` — create success
-  - `204` — delete success (no body)
-  - `400` — validation failure
-  - `401` — not authenticated
-  - `403` — forbidden
-  - `404` — resource not found
-  - `409` — resource conflict
-  - `422` — valid request format but business logic rejection
-  - `500` — unknown server error
-- **Forbidden**: Returning `200` for all errors with an error code in the body.
-- **RATIONALE**: HTTP status codes are standard signals for infrastructure (load balancers, monitoring, gateways). Bypassing them makes all observability useless.
-
-### F2.3 Error Response Format
-
-- **Rule**: All errors return a unified structure:
-  ```json
-  {
-    "error": {
-      "code": "USER_NOT_FOUND",
-      "message": "User not found",
-      "details": [],
-      "traceId": "abc-123"
-    }
-  }
-  ```
-- **Rule**: `code` uses UPPER_SNAKE_CASE with business semantics (`USER_NOT_FOUND`, not `ERR_001`).
-- **Rule**: `traceId` is generated at request entry and propagated through the entire call chain.
-- **RATIONALE**: A unified error format lets frontends and gateways write one error handler instead of per-endpoint if/else chains.
+# Backend Invariant Rules
 
-### F2.4 API Versioning
+POLICY_CLASS: invariant
 
-- **Rule**: APIs must indicate version in URL or Header (`/api/v1/users` or `Accept: application/vnd.api.v1+json`).
-- **Rule**: Breaking changes require a new version. Old versions must be maintained for at least one release cycle.
-- **RATIONALE**: Unversioned APIs cause widespread mobile/third-party client crashes on release.
+These blocks apply to every backend option exposed by Rules Configuration.
 
----
+**Selected-decision boundary:** language, runtime, framework, architecture, API style, API documentation, data technology, authentication scheme, cache, queue, deployment, testing depth, observability stack, dependency permission, caller analysis, and config permission belong to confirmed decisions and derivation rules. Do not encode one option here as universal behavior.
 
-## F3. Error Handling
+## I1. Structure and Ownership
 
-- **Rule**: All exceptions must be caught by a global exception filter and return a unified error response.
-- **Rule**: Business exceptions vs. system exceptions are separated — business exceptions return 4xx, system exceptions return 500.
-- **Forbidden**: Empty `catch(e) {}` blocks. If ignoring is truly necessary, comment why.
-- **Forbidden**: `catch(e) { throw new Error('something went wrong') }` that swallows the original stack trace.
-- **Rule**: Error logs must include traceId, user identifier, request method, and path.
-- **RATIONALE**: The biggest backend failure isn't "an error occurred" — it's "an error occurred and nobody knows".
+- Every module has an explicit owner and public boundary; internal implementation is not imported as an accidental API.
+- Dependency direction follows the selected architecture and remains free of unplanned cycles.
+- Business behavior has one authoritative implementation rather than duplicated branches across transports or entrypoints.
+- Rationale: ownership and acyclic dependencies are invariant; layer names are not.
 
----
+Inject into `{{ FIXED_RULES_STRUCTURE }}`.
 
-## F4. Security
+## I2. API Contract Integrity
 
-### F4.1 Input Validation (Mandatory)
+- Follow the selected API style consistently and document externally consumed requests, responses, errors, and compatibility expectations.
+- Validate untrusted inputs at the boundary before invoking business behavior.
+- Contract changes identify affected consumers and use the selected compatibility or versioning policy.
+- Do not apply HTTP-specific rules to non-HTTP transports unless an adapter explicitly owns that mapping.
 
-- **Rule**: All external inputs must be validated (body, query params, path params, headers, cookies).
-- **Rule**: Use a validation framework (Joi/Zod/Pydantic/validator), not hand-written if/else.
-- **Rule**: Validation failures return 400 with field-level error details.
-- **Forbidden**: Trusting data from the frontend to be directly stored or executed.
-- **RATIONALE**: Input validation is the first line of defense and the root cause mitigation for multiple OWASP Top 10 attacks.
-
-### F4.2 Authentication & Authorization
-
-- **Rule**: AuthN and AuthZ must be separated — middleware handles authentication, business logic handles authorization.
-- **Rule**: JWT tokens must have expiration (access token ≤ 15min, refresh token ≤ 7d).
-- **Rule**: Sensitive operations (delete, transfer, permission changes) require secondary confirmation.
-- **Forbidden**: Hardcoding tokens/secrets in source code.
-- **RATIONALE**: Separating AuthN and AuthZ allows independent security audits at each layer.
-
-### F4.3 General Protections
-
-- **Rule**: All external links/callback URLs must be validated against a whitelist to prevent Open Redirect.
-- **Rule**: File uploads must validate type (whitelist), size, and content magic bytes.
-- **Rule**: Passwords must use bcrypt/argon2 hashing. Forbid plaintext, MD5, or SHA1.
-- **Forbidden**: Exposing secrets, tokens, or passwords in error messages or logs.
-- **Forbidden**: Returning internal implementation details in responses (stack traces, SQL statements, framework versions).
-- **RATIONALE**: These are the most common security vulnerabilities. Not a question of "should we" — it's "you will be breached if you don't."
+Inject into `{{ FIXED_RULES_API }}`.
 
-### F4.4 Rate Limiting
+## I3. Error Integrity
 
-- **Rule**: All public API endpoints must have rate limiting. Forbid unlimited request rates.
-- **Rule**: Rate limit tiers: authentication endpoints (5 req/min), general API (100 req/min per user/IP), internal/admin endpoints (higher limits).
-- **Rule**: Rate limit headers: include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in responses.
-- **Rule**: Rate limit exceeded returns 429 Too Many Requests with Retry-After header.
-- **RATIONALE**: Without rate limiting, a single misbehaving client or a simple script-kiddie attack can take down your entire API.
+- Preserve original diagnostic context when translating an internal failure to a public error.
+- Separate expected domain failures from unexpected system failures.
+- Public errors expose no secrets, stack traces, query text, or private implementation details.
+- Never swallow a failure without an explicit, documented recovery path.
 
----
-
-## F5. Database
-
-**Note**: These rules assume a relational database (PostgreSQL/MySQL). If the project uses MongoDB (selected in Q8), some rules (migration files, SELECT syntax) do not apply. Document-specific rules are in the derived rules section.
-
-- **Rule**: Connection pool must be reasonably sized (default ≤ CPU cores × 2). Connections must have timeouts.
-- **Rule**: All migration files must be versioned, reversible, and committed to the repository.
-- **Rule**: Queries must use parameterized queries or ORM-provided safe methods. Forbid string-concatenated SQL.
-- **Rule**: Bulk operations (>1000 rows) must be batched.
-- **Forbidden**: Executing single-row SQL inside loops (use batch insert/update instead).
-- **Forbidden**: SELECT without LIMIT.
-- **Forbidden**: `SELECT *` (specify columns explicitly).
-- **RATIONALE**: The database is the component where a single failure has the largest blast radius in a backend system. One bad query can bring down the entire service.
+Inject into `{{ FIXED_RULES_ERROR }}`.
 
----
+## I4. Security Baseline
 
-## F6. Observability
+- Authenticate and authorize at explicit trust boundaries; do not trust caller-supplied identity or role data.
+- Keep credentials and secrets outside source control and redact sensitive values from logs and errors.
+- Validate callback, redirect, upload, and deserialization boundaries against an allowlisted contract.
+- Store passwords only with a current password-hashing construction.
+- Scheme-specific token, session, OAuth, and API-key rules come from `{{ auth_rules }}`.
 
-- **Rule**: Logs must be structured (JSON format), containing: `timestamp`, `level`, `message`, `traceId`, `userId`, `path`, `method`.
-- **Rule**: Expose at least two endpoints: `GET /health` (liveness) and `GET /health/ready` (readiness).
-- **Rule**: Key business operations must be instrumented (registration, login, payment, order creation, etc.).
-- **Forbidden**: Using `console.log` as a substitute for structured logging.
-- **RATIONALE**: A microservice without structured logging is a black box. Troubleshooting goes from minutes to hours.
+Inject into `{{ FIXED_RULES_SECURITY }}`.
 
-### F6.2 Distributed Tracing
+## I5. Abuse Protection
 
-- **Rule**: Every incoming request must generate or propagate a traceId. traceId is passed in X-Trace-Id header.
-- **Rule**: All downstream calls (database, cache, message queue, external APIs) must carry the traceId.
-- **Rule**: Use W3C Trace Context standard (traceparent header) for cross-service propagation.
-- **Forbidden**: Generating a new traceId mid-request chain (breaks distributed traces).
-- **RATIONALE**: traceId is the thread that ties together every log line and span for a single request across microservices. Without it, troubleshooting distributed systems is guesswork.
+- Identify public or expensive operations that require quotas, backpressure, idempotency, or rate protection.
+- Derive concrete limits from product risk and deployment capacity instead of imposing one universal number.
+- Rejection behavior is observable and does not disclose sensitive internals.
 
-### F6.3 Health Check Endpoints
+Inject into `{{ FIXED_RULES_RATE_LIMITING }}`.
 
-- **Rule**: GET /health (liveness) — returns 200 if the process is alive. No dependency checks.
-- **Rule**: GET /health/ready (readiness) — returns 200 if all critical dependencies are available (database, cache, message queue). Returns 503 if any critical dependency is unreachable.
-- **Rule**: Health checks must be lightweight (< 50ms). Forbid running expensive queries or external API calls.
-- **RATIONALE**: Kubernetes and load balancers use these endpoints to decide whether to route traffic or restart the pod. A slow /health creates cascading failures.
+## I6. Data Access Safety
 
----
+- Use the selected data technology's safe parameter binding or query construction mechanism.
+- Bound potentially unbounded reads and writes or document the controlled batch/stream contract.
+- Keep transactions or equivalent atomic units short and free of unrelated external waits.
+- Relational and document-specific modeling rules belong to the selected data derivation blocks.
 
-## F7. Configuration Management
+Inject into `{{ FIXED_RULES_DATABASE }}`.
 
-- **Rule**: Configuration has three tiers — code defaults < environment variables < config files (by priority).
-- **Forbidden**: Committing any secrets, tokens, or passwords to Git.
-- **Rule**: All environment-specific config (database connections, Redis addresses, third-party API keys) injected via environment variables.
-- **Rule**: Must have a `.env.example` file listing all required environment variables with descriptions (use placeholders for values).
-- **RATIONALE**: Separating config from code is a 12-Factor App principle and a security baseline.
+## I7. Observability Integrity
 
----
+- Errors and key operations carry enough correlation context to diagnose one request, job, or message without logging secrets.
+- Logging format and collection topology follow the selected observability decision.
+- Health signals distinguish process liveness from dependency readiness when the deployment environment consumes both.
 
-## F8. Async & Message Queues
+Inject into `{{ FIXED_RULES_OBSERVABILITY }}`.
 
-- **Rule**: Message handlers must be idempotent — replaying the same message produces no side effects.
-- **Rule**: Async tasks must have timeout handling, retry strategy (exponential backoff), and dead letter queues.
-- **Rule**: Message bodies must contain a unique id (for deduplication) and traceId (for tracing).
-- **Rule**: Retry count and interval must have upper limits (e.g., max 3 retries, intervals 1s/5s/15s).
-- **RATIONALE**: The biggest async system problem isn't "messages got lost" — it's "messages got processed twice and double-charged the customer."
+## I8. Trace Continuity
 
-### F8.4 Message Delivery Semantics
+- Preserve an existing correlation or trace context across supported downstream boundaries.
+- Do not silently replace caller-provided valid trace context mid-operation.
+- Distributed tracing is enabled only when selected or required by the deployment; otherwise preserve local correlation identifiers.
 
-- **Rule**: Explicitly document the delivery guarantee for each queue/topic: at-most-once, at-least-once, or exactly-once.
-- **Rule**: At-least-once (default for most systems): consumers must be idempotent.
-- **Rule**: Dead letter queues (DLQ) must be configured. Failed messages route to DLQ after max retries.
-- **Rule**: DLQ messages must have a replay/inspect mechanism. Forbid silently discarding failed messages.
-- **RATIONALE**: The difference between at-least-once and exactly-once is the difference between "customer charged once" and "customer charged twice."
+Inject into `{{ FIXED_RULES_TRACING }}`.
 
-### F8.5 Graceful Shutdown
+## I9. Configuration Safety
 
-- **Rule**: Application must handle SIGTERM gracefully: stop accepting new requests, finish in-progress requests (with timeout), close database connections, flush logs.
-- **Rule**: Shutdown timeout must be configured (default 30s). Kubernetes terminationGracePeriodSeconds must exceed this.
-- **Rule**: In-flight async tasks must complete or be re-queued before shutdown.
-- **Forbidden**: Hard-exit on SIGTERM (SIGKILL should be the fallback, not the default).
-- **RATIONALE**: Deployments and pod restarts should not cause failed requests or lost data. Graceful shutdown is a basic operational requirement.
+- Separate secrets from non-secret configuration and document required configuration without committing secret values.
+- Validate required configuration before serving work.
+- Config modification permission comes only from `{{ ai_config_rule }}`; this invariant does not forbid an authorized change.
 
----
+Inject into `{{ FIXED_RULES_CONFIG }}`.
 
-## F9. Testing
+## I10. Async Safety
 
-- **Rule**: Testing has three tiers — unit tests (service layer), integration tests (API endpoints + database), E2E (critical business flows).
-- **Rule**: External dependencies (database, Redis, third-party APIs) must be mocked in unit tests.
-- **Rule**: Integration tests use a test database or testcontainers. Test data is cleaned before and after each run.
-- **Rule**: Coverage baseline: service layer ≥ 80%, controller layer ≥ 60%.
-- **Forbidden**: Tests sharing mutable state (global variables / shared database rows).
-- **RATIONALE**: Backend regression risk is far higher than frontend (one data corruption is irreversible). Tests are the only safety net.
+- Every asynchronous side effect defines ownership, timeout/cancellation behavior, and duplicate-delivery handling where applicable.
+- Do not claim queue semantics when no queue was selected.
+- Queue-specific retry, ordering, and dead-letter rules come from `{{ mq_rules }}`.
 
----
+Inject into `{{ FIXED_RULES_ASYNC }}`.
 
-## F10. AI Vibecoding Baseline Constraints (project-agnostic, always active)
+## I11. Message Delivery Integrity
 
-### F10.1 Search First
-- **Rule**: Before generating a new module, AI must search existing code to check for similar functionality.
-- **Rule**: Before writing SQL/migrations, AI must read existing migration files and schema.
+- When messaging is selected, document delivery semantics and make consumers safe for the selected duplicate/retry model.
+- Failed messages remain observable and recoverable according to the selected queue capability.
+- Render an explicit not-applicable statement when messaging is not selected.
 
-### F10.2 Dependency Control
-- **Rule**: AI must not modify `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` on its own.
-- **Rule**: If a new dependency is truly needed, AI must list: package name, version, reason, alternative comparison.
+Inject into `{{ FIXED_RULES_MESSAGE_DELIVERY }}`.
 
-### F10.3 Breaking Changes
-- **Rule**: Before modifying a shared module/utility/API contract, AI must list all callers.
-- **Rule**: Changing API response field names or types requires assessing frontend impact first.
+## I12. Shutdown Integrity
 
-### F10.4 Config Immutability
-- **Rule**: AI must not modify environment variables, database connection config, docker-compose, or CI/CD configuration on its own.
-- **Rule**: Adding a new environment variable in code must be accompanied by an update to `.env.example`.
-
-### F10.5 SQL Safety
-- **Rule**: All AI-written SQL must be parameterized queries.
-- **Forbidden**: AI generating string-concatenated SQL code.
+- Stop accepting new work before releasing resources.
+- Bound shutdown and preserve or requeue owned in-flight work where the runtime supports it.
+- Apply platform-specific signal and probe details through deployment derivation rules.
 
-### F10.6 Migration Files
-- **Rule**: AI generating a new migration must also produce the corresponding rollback migration.
-- **Forbidden**: Dropping columns or changing types in migrations (add-only, unless a rollback plan exists).
+Inject into `{{ FIXED_RULES_GRACEFUL_SHUTDOWN }}`.
 
-### F10.7 Context Honesty
-- **Rule**: When uncertain, AI must explicitly say "I'm not sure." Forbid inventing API paths, library versions, or database field names.
-- **Rule**: AI must read the latest file contents before modifying. Forbid generating diffs based on guesswork.
+## I13. Verification Integrity
 
----
+- Follow the selected testing depth; do not invent unapproved coverage thresholds or mandatory tiers.
+- Enabled tests are deterministic, isolated from production data, and assert behavior rather than implementation accidents.
+- A `not required yet` choice is recorded explicitly with its accepted risk rather than contradicted by unconditional test requirements.
 
-## Injection Instructions (for the AI executing this skill)
+Inject into `{{ FIXED_RULES_TEST }}`.
 
-Each chapter in this file corresponds to a `{{ FIXED_RULES_* }}` placeholder in the template:
+## I14. AI Change Safety
 
-| Chapter | Inject Into Placeholder | Template Section |
-|---------|------------------------|-------------------|
-| F1 Project Structure | `{{ FIXED_RULES_STRUCTURE }}` | §1 Project Structure |
-| F2 API Design | `{{ FIXED_RULES_API }}` | §2 API Design |
-| F3 Error Handling | `{{ FIXED_RULES_ERROR }}` | §3 Error Handling |
-| F4 Security | `{{ FIXED_RULES_SECURITY }}` | §4 Security (F4.1-F4.3 only; stop before F4.4) |
-| F4.4 Rate Limiting | `{{ FIXED_RULES_RATE_LIMITING }}` | §4 Security (F4.4 only, injected separately) |
-| F5 Database | `{{ FIXED_RULES_DATABASE }}` | §5 Database |
-| F6 Observability | `{{ FIXED_RULES_OBSERVABILITY }}` | §6 Observability (F6 + F6.3 only; stop before F6.2) |
-| F6.2 Distributed Tracing | `{{ FIXED_RULES_TRACING }}` | §6 Observability (F6.2 only, injected separately) |
-| F7 Configuration | `{{ FIXED_RULES_CONFIG }}` | §7 Configuration |
-| F8 Async & Queues | `{{ FIXED_RULES_ASYNC }}` | §8 Async & Queues |
-| F8.4 Message Delivery | `{{ FIXED_RULES_MESSAGE_DELIVERY }}` | §8 Async & Queues |
-| F8.5 Graceful Shutdown | `{{ FIXED_RULES_GRACEFUL_SHUTDOWN }}` | §8 Async & Queues |
-| F9 Testing | `{{ FIXED_RULES_TEST }}` | §9 Testing |
-| F10 AI Constraints | `{{ FIXED_RULES_AI_BASE }}` | §10 AI Behavior Constraints |
+- Read current code and search for existing ownership before creating duplicate modules or contracts.
+- Keep changes inside the requested scope and report uncertainty rather than inventing endpoints, fields, versions, or infrastructure.
+- Never expose secrets, weaken authorization, or bypass data safety merely to make a check pass.
+- Dependency, caller-analysis, and config permissions come only from their selected rule blocks.
 
-**Rendering rules**:
-1. Copy each chapter's full body (including RATIONALE) directly into the corresponding placeholder.
-2. RATIONALE must be preserved — it lets AI understand intent rather than follow mechanically.
-3. Keep the original markdown list structure. Do not rewrite as prose paragraphs.
+Inject into `{{ FIXED_RULES_AI_BASE }}`.
+
+## Injection Contract
+
+Copy each invariant block only into its named placeholder. If any invariant conflicts with a selected decision, fail generation and move the policy to a derivation block; never render both.

package/bundled/skills/app-planner/references/rules/backend/question-bank.md

@@ -11,14 +11,14 @@
 1. **Group order**: G1 → G2 → G3 → G4 → G5 → G6 → G7 → G8 → G9. Do not skip.
 2. **Shortcut commands** (respond immediately when user types these at any point):
    - `recommended` / `default` → skip current group, adopt all recommended options
-   - `all recommended` / `one-click` → skip all remaining groups, adopt all recommended options
+   - `all recommended` / `one-click` → explicit authorization to adopt each remaining applicable recommended option; ask any question whose recommendation is ambiguous for the selected stack
    - `strict` / `strictest` → adopt the strictest option for the current group
    - `skip` / `don't need this` → mark current group as N/A, note in output that "project does not require this yet"
    - `custom: xxx` → record user's custom content, do not match against options
 3. **Abbreviation recognition**: `A` / `a` / `1` all mean option A. `A,C` means multi-select (only for multi-select questions).
 4. **Follow-up rule**: If the user gives an answer outside the options (e.g., "I use Astro"), first confirm whether to classify as an "other" branch of an existing option before continuing.
 5. **Forbidden behaviors**:
-   - Must not make choices for the user before they explicitly answer.
+   - Must not make choices for the user before they explicitly answer, except concrete defaults covered by the user's explicit Quick/all-recommended authorization.
    - Must not fabricate user preferences to complete the answer set.
    - Must not output more than 3 questions in a single message.
 
@@ -100,7 +100,7 @@ Total: 20 questions.
 - **Maps to**: `{{ api_style }}` + `{{ api_rules }}`
 
 ### Q6. API Documentation
-- **Conditional logic**: If Q5 = GraphQL, auto-select B and skip Q6. If Q5 = gRPC, auto-select C and skip Q6. If Q5 = REST + gRPC hybrid, ask but note that REST endpoints default to A. Only ask Q6 directly when Q5 = RESTful.
+- **Conditional logic**: If Q5 = GraphQL, auto-select B and skip Q6. If Q5 = gRPC, auto-select C and skip Q6. Ask Q6 when Q5 = RESTful or REST + gRPC hybrid; for the hybrid, the answer governs the REST surface while Protobuf remains authoritative for gRPC.
 - **Options**:
   - A) OpenAPI/Swagger auto-generated **【Recommended for REST projects】**
   - B) GraphQL Schema (self-documenting) — auto-selected when Q5 = GraphQL
@@ -138,11 +138,11 @@ Total: 20 questions.
 
 ### Q9. Authentication Scheme
 - **Options**:
-  - A) JWT (stateless, suitable for APIs/microservices) **【Recommended】**
-  - B) OAuth2 + OIDC (third-party login/SSO)
-  - C) Session + Cookie (traditional web apps)
-  - D) API Key (service-to-service)
-- **Note**: Determines middleware selection and token management rules.
+  - A) JWT bearer tokens **【Recommended only for stateless API access with an explicit issuance, expiry, rotation, revocation, and audience model】**
+  - B) OAuth2 + OIDC **【Recommended for third-party login/SSO】**
+  - C) Server session + secure cookie **【Recommended for first-party browser applications】**
+  - D) API key or workload identity **【Recommended for constrained service-to-service access】**
+- **Note**: Determines identity, credential storage, revocation, middleware, and transport rules. There is no universal Quick default; infer from a confirmed client/trust model or ask.
 - **Maps to**: `{{ auth_scheme }}` + `{{ auth_rules }}`
 
 ---
@@ -151,20 +151,20 @@ Total: 20 questions.
 
 ### Q10. Caching
 - **Options**:
-  - A) Redis **【Recommended】**
+  - A) Redis **【Recommended when a shared/distributed cache or Redis capability is established】**
   - B) Memcached
   - C) In-memory cache (single instance only)
-  - D) No caching needed
-- **Note**: Determines cache key conventions, expiry strategy, and penetration/avalanche protection rules.
+  - D) No caching needed **【Recommended until a measured cache use case exists】**
+- **Note**: Determines cache key, expiry, invalidation, and failure behavior. Quick mode must not add cache infrastructure solely because a cache option exists.
 - **Maps to**: `{{ cache }}` + `{{ cache_rules }}`
 
 ### Q11. Message Queue
 - **Options**:
-  - A) RabbitMQ
-  - B) Kafka **【Recommended: high-throughput/event sourcing】**
-  - C) Redis Stream/BullMQ (lightweight task queues)
-  - D) No message queue needed
-- **Note**: Determines async processing, idempotency, and retry strategy rules. B is the default recommendation for most projects. Choose C only for lightweight task needs.
+  - A) RabbitMQ **【Recommended for brokered work queues/routing requirements】**
+  - B) Kafka **【Recommended for confirmed high-throughput event streams or durable replay】**
+  - C) Redis Stream/BullMQ **【Recommended for an existing Redis-backed lightweight task need】**
+  - D) No message queue needed **【Recommended until an asynchronous delivery requirement exists】**
+- **Note**: Determines async processing, delivery semantics, idempotency, and retry behavior. Quick mode never provisions messaging without a confirmed workload.
 - **Maps to**: `{{ mq }}` + `{{ mq_rules }}`
 
 ### Q12. Containerization & Deployment
@@ -197,7 +197,7 @@ Total: 20 questions.
   - For Rust: A) Built-in test **【Recommended】** — B) proptest
 - **Maps to**: `{{ test_framework }}`
 
-### Q15. Mock Strategy
+### Q15. Mock Strategy (only ask if Q13 ≠ D)
 - **Options**:
   - A) Mock all external deps, use testcontainers or in-memory DB for database **【Recommended】**
   - B) Mock all external deps including database
@@ -211,18 +211,18 @@ Total: 20 questions.
 
 ### Q16. Logging
 - **Options**:
-  - A) Structured JSON logging + centralized collection (ELK/Loki) **【Recommended】**
-  - B) Structured logging + local files
-  - C) Simple text logs, good enough
-- **Note**: Determines log format and field specifications.
+  - A) Structured event logging + selected centralized collection **【Recommended for multi-instance production services】**
+  - B) Structured logging to the deployment's standard stream/file collector **【Recommended for small or platform-managed deployments】**
+  - C) Simple text logs (development-only)
+- **Note**: Determines log format and collection boundary without forcing one observability vendor.
 - **Maps to**: `{{ logging }}` + `{{ observability_rules }}`
 
 ### Q17. Monitoring & Tracing
 - **Options**:
-  - A) OpenTelemetry + Prometheus + Grafana **【Recommended】**
-  - B) Health check endpoints + system monitoring only
-  - C) Not needed yet
-- **Note**: Determines instrumentation and alerting rules.
+  - A) OpenTelemetry plus compatible metrics/visualization **【Recommended when distributed tracing or a managed telemetry pipeline is required】**
+  - B) Health/readiness signals + deployment monitoring **【Recommended baseline for a small service】**
+  - C) Not needed yet (explicit development risk acceptance)
+- **Note**: Determines instrumentation and alerting rules; it does not make one vendor stack universal.
 - **Maps to**: `{{ monitoring }}` + `{{ observability_rules }}`
 
 ---

package/bundled/skills/app-planner/references/rules/backend/question-manifest.json

@@ -1,9 +1,18 @@
 {
-  "schema_version": "app-planner-question-manifest-v1",
+  "schema_version": "app-planner-question-manifest-v2",
   "layer": "backend",
   "total_questions": 20,
   "_doc": "Machine-readable structure for backend question-bank.md. Question TEXT/options/Recommended/Notes are authoritative in question-bank.md; this file carries ONLY structure: group membership, quick-mode, question->placeholder mapping, and conditional logic. Keep Qids and group ids in sync with question-bank.md. The AI reads this as its asking checklist (Phase A) and self-check expected-set (Phase D).",
-  "_conditions": "required_if / auto_derived_when use simple expressions over recorded answers, e.g. 'Q5 == RESTful', 'Q13 != D', 'Q5 in [GraphQL, gRPC]'. options_vary_by names a prior answer that changes the OPTION LIST only (question is still asked; never affects required).",
+  "_conditions": "required_if / auto_derived_when use option IDs over recorded answers, e.g. 'Q5 in [A, D]' and 'Q13 != D'. options_vary_by names a prior answer that changes the OPTION LIST only (question is still asked; never affects required).",
+  "render_contract": {
+    "fixed_rules_policy": "invariants_only",
+    "selected_decision_precedence": true,
+    "quick_mode_requires_explicit_authorization": true,
+    "unmapped_option_policy": "semantic_fallback",
+    "not_applicable_policy": "explicit_statement",
+    "conflict_policy": "fail_generation",
+    "semantic_fallback_questions": ["Q1", "Q2", "Q3", "Q4", "Q5", "Q6", "Q7", "Q8", "Q9", "Q10", "Q11", "Q12", "Q13", "Q14", "Q15", "Q16", "Q17", "Q18", "Q19", "Q20"]
+  },
   "groups": [
     { "id": "G1", "topic": "Language & Runtime", "quick_mode": true },
     { "id": "G2", "topic": "Framework & Architecture", "quick_mode": true },
@@ -18,19 +27,19 @@
   "questions": [
     { "id": "Q1", "group": "G1", "topic": "Programming Language", "maps_to": ["language", "tech_stack_rules"], "required": true },
     { "id": "Q2", "group": "G1", "topic": "Runtime Version", "maps_to": ["runtime_version"], "required": true },
-    { "id": "Q3", "group": "G2", "topic": "Web Framework", "maps_to": ["framework", "tech_stack_rules"], "required": true, "options_vary_by": "Q1", "note_open_ended_when": "Q1 == Custom" },
+    { "id": "Q3", "group": "G2", "topic": "Web Framework", "maps_to": ["framework", "tech_stack_rules"], "required": true, "options_vary_by": "Q1", "note_open_ended_when": "Q1 == F" },
     { "id": "Q4", "group": "G2", "topic": "Architecture Pattern", "maps_to": ["architecture", "arch_rules"], "required": true },
     { "id": "Q5", "group": "G3", "topic": "API Style", "maps_to": ["api_style", "api_rules"], "required": true },
-    { "id": "Q6", "group": "G3", "topic": "API Documentation", "maps_to": ["api_docs"], "required": true, "required_if": "Q5 == RESTful", "auto_derived_when": "Q5 in [GraphQL, gRPC]" },
-    { "id": "Q7", "group": "G4", "topic": "ORM / Data Access", "maps_to": ["orm", "data_rules"], "required": true, "options_vary_by": "Q1", "note_open_ended_when": "Q1 == Custom" },
-    { "id": "Q8", "group": "G4", "topic": "Database", "maps_to": ["database"], "required": true },
+    { "id": "Q6", "group": "G3", "topic": "API Documentation", "maps_to": ["api_docs", "api_rules"], "required": true, "required_if": "Q5 in [A, D]", "auto_derived_when": "Q5 in [B, C]" },
+    { "id": "Q7", "group": "G4", "topic": "ORM / Data Access", "maps_to": ["orm", "data_rules"], "required": true, "options_vary_by": "Q1", "note_open_ended_when": "Q1 == F" },
+    { "id": "Q8", "group": "G4", "topic": "Database", "maps_to": ["database", "data_rules"], "required": true },
     { "id": "Q9", "group": "G5", "topic": "Authentication Scheme", "maps_to": ["auth_scheme", "auth_rules"], "required": true },
     { "id": "Q10", "group": "G6", "topic": "Caching", "maps_to": ["cache", "cache_rules"], "required": true },
     { "id": "Q11", "group": "G6", "topic": "Message Queue", "maps_to": ["mq", "mq_rules"], "required": true },
     { "id": "Q12", "group": "G6", "topic": "Containerization & Deployment", "maps_to": ["container", "deploy_rules"], "required": true },
     { "id": "Q13", "group": "G7", "topic": "Test Coverage Requirements", "maps_to": ["test_requirement", "test_rules"], "required": true },
     { "id": "Q14", "group": "G7", "topic": "Test Framework", "maps_to": ["test_framework"], "required": true, "required_if": "Q13 != D", "options_vary_by": "Q1" },
-    { "id": "Q15", "group": "G7", "topic": "Mock Strategy", "maps_to": ["mock_strategy", "test_rules"], "required": true },
+    { "id": "Q15", "group": "G7", "topic": "Mock Strategy", "maps_to": ["mock_strategy", "test_rules"], "required": true, "required_if": "Q13 != D", "auto_derived_when": "Q13 == D" },
     { "id": "Q16", "group": "G8", "topic": "Logging", "maps_to": ["logging", "observability_rules"], "required": true },
     { "id": "Q17", "group": "G8", "topic": "Monitoring & Tracing", "maps_to": ["monitoring", "observability_rules"], "required": true },
     { "id": "Q18", "group": "G9", "topic": "AI Permission to Add Dependencies", "maps_to": ["ai_dependency_rule"], "required": true },