opencode-skills-collection 4.1.2 → 4.1.4

package/bundled-skills/idea-to-blueprint/references/code-quality-and-review.md

@@ -0,0 +1,216 @@
+# Code quality, review and delivery metrics
+
+Contents: 1 Why this exists · 2 The two layers · 3 Layer 1 — automated gate · 4 Layer 2 — the review dimensions · 5 Test quality (not coverage) · 6 Reviewing agent-written code · 7 Delivery and codebase metrics · 8 Anti-metrics · 9 What to research and cite each run · 10 Where this lands in the blueprint · 11 Review checklist to embed verbatim
+
+## 1. Why this exists
+
+Every story in this blueprint is written by a coding agent in a fresh session and reviewed, usually once, by one human who did not write it and may not read every line. That is the exact condition under which quality problems become invisible: the code compiles, the tests are green, the demo works, and the defects are in the parts nobody looked at.
+
+So the blueprint does not say "write good code". It specifies, before any code exists:
+
+- what a machine checks on every change (Layer 1 — objective, non-negotiable, in `check`),
+- what a human looks for and in what order (Layer 2 — judgement, a fixed checklist),
+- how the system's health is measured over time (metrics that diagnose the *process*, never rank people),
+- and what is deliberately not measured, because measuring it makes the codebase worse.
+
+A reviewer who has to invent the standard at review time applies a different standard every time. A written standard is what makes "approved" mean something across ten sessions.
+
+## 2. The two layers
+
+Keep them strictly separated. It is the single highest-leverage rule in this file.
+
+| | Layer 1 — the gate | Layer 2 — the review |
+|---|---|---|
+| Who | CI / `check` | A human (and optionally an AI reviewer) |
+| What | Anything objectively decidable: format, lint, types, tests, coverage floor, schema drift, dependency audit, secret scan, bundle/query budgets, architecture rules | Design fit, boundaries, reversibility, failure behaviour, test *meaning*, security reasoning, copy and locale, naming |
+| Failure mode it prevents | Reviewers spending attention on things a machine decides better | Rubber-stamping, because the human has nothing specific to look for |
+| Rule | If a human is arguing about it and a machine could decide it, it belongs in Layer 1 by the next epic | If a machine could not decide it, it is never "fixed" by adding a linter rule |
+
+Anything objective that a reviewer has to remember is a Layer 1 gap, and it gets a story. Formatting arguments in a PR thread are a defect in the process, not in the code.
+
+## 3. Layer 1 — the automated gate
+
+`check` is one command, runs locally and in CI identically, and is the definition of "green". Specify in the blueprint, with the actual command and the expected runtime:
+
+1. **Format** — a formatter with zero configurable opinions left open; check mode in CI.
+2. **Lint** — strict rule set; warnings are errors in CI. Include correctness rules, not only style (unused results, floating promises/unawaited futures, exhaustive switch, no implicit any-equivalents).
+3. **Types** — the strictest mode the language offers, escape hatches banned by lint (`any`, `unwrap`, `!`, `# type: ignore`) or requiring an inline justification comment.
+4. **Tests** — unit + integration; e2e on the critical paths. Fast enough to run per-change (state the target, e.g. unit under 2 minutes).
+5. **Coverage floor** — a *floor to stop regressions*, not a target to chase (see §5 and §8).
+6. **Migration/schema drift check** — the schema in the repo matches what migrations produce; no divergence.
+7. **Dependency and secret checks** — vulnerability audit at a stated severity threshold, license check, lockfile committed and verified, secret scanning on the diff.
+8. **Architecture fitness functions** — the module-boundary and dependency-direction rules from the architecture section, enforced as tests (see `architecture-decisions.md` §6). Without these, boundaries erode silently across sessions.
+9. **Budgets** — whatever performance budget the product declares, asserted where it can be: query count per endpoint (N+1 guard), payload size, bundle size, p95 on a seeded dataset.
+10. **Accessibility and locale checks** where a UI exists — automated a11y rules on key screens, and a check that no user-visible string is hardcoded outside the copy/i18n catalogue.
+
+Two rules about the gate itself: **it never gets weakened to make a change pass** (weakening it is its own DR entry with a reason), and **a flaky test is a broken gate** — quarantine it in the same session with a story to fix it, never re-run until green.
+
+## 4. Layer 2 — the review dimensions
+
+In this order. The order is the point: it is roughly the cost of being wrong, and a reviewer who runs out of attention should run out of it at the bottom, not the top. Google's own review guidance leads with design for the same reason — a bug is cheap to fix relative to a wrong boundary.
+
+**D1. Does it do the specified thing?** Every AC of the story, checked against observable behaviour, not against the author's summary. Anything built that no AC asked for is scope leak: either an AC is missing (amend the blueprint) or the code is.
+
+**D2. Design and boundaries.** Does the change sit in the right module? Does it create a dependency the architecture forbids (fitness function should have caught it — if it did not, the rule is missing)? Is logic duplicated that already exists elsewhere? Is it the framework's blessed path or an invention? Cheap to fix in code, expensive to fix in structure.
+
+**D3. Reversibility.** Flag one-way doors explicitly: schema changes on populated tables, public API contracts, event formats, a new external dependency, anything that writes data in a shape that will be hard to migrate. One-way doors get more scrutiny and a DR entry; everything else gets less. Treating both the same is how teams end up slow *and* fragile.
+
+**D4. Failure and edge behaviour.** Walk the story's edge-case list against the code: empty, one, many, maximum, boundary; null/absent vs zero/empty-string; duplicate submission and idempotency; concurrent modification; dependency timeout, 5xx, partial response, slow response; offline mid-action; retry policy and whether retries are safe. The happy path is not where defects live.
+
+**D5. Test meaning.** See §5. Does the test fail if the behaviour breaks? Does it test behaviour or implementation? Would it survive a refactor?
+
+**D6. Security.** Input validated at the trust boundary; authorization checked per *object*, not just authentication at the door (an ID in a URL is not a permission); parameterised queries; output encoded for its sink; secrets not in code, logs or error payloads; PII not logged; upload type/size validated; rate limits on anything that costs money or sends messages; dependency added is one a human recognises (typosquat check). This dimension is non-optional on AI-written code — see §6.
+
+**D7. Behaviour at real scale.** Not "is it fast" but "what happens at 100× the current data". Query per loop iteration (N+1), missing index on a filtered/sorted column, unbounded result set with no pagination, whole-table load into memory, an operation that is O(n²) on something that grows.
+
+**D8. Observability.** Can this be diagnosed at 3am by someone who did not write it? Structured log at the decision points with a correlation ID, no PII; a metric for the outcome; errors reaching error tracking with enough context; health of any new dependency visible.
+
+**D9. Copy, locale and accessibility.** Strings come from the copy table by ID, not improvised; every state of the screen has its line; digits, dates, currency and direction follow the locale rules; focus order, labels, contrast, touch targets.
+
+**D10. Readability.** Naming that a stranger reads correctly; comments that explain *why*, not *what*; complexity that could be reduced without loss. Last on the list on purpose — it is real, but it is where review attention gets spent when the reviewer has no better checklist.
+
+**D11. Size and shape of the change.** Reviews of 200–400 changed lines are where defect detection is strongest; past roughly 400 lines detection falls off, and past 60–90 minutes of continuous reviewing it falls off again. This is a claim about the reader, not the author, so it survives the fact that an agent can produce 2,000 lines in a minute. If a story routinely produces more than that, the story is too big — split it in the blueprint.
+
+**The standard for approval** is not perfection: approve when the change definitively improves the system and carries no unacceptable risk, and file the rest as follow-ups. A review that blocks on preference is as expensive as a review that catches nothing.
+
+## 5. Test quality, not test coverage
+
+Coverage tells you a line executed. It does not tell you a test would notice if that line were wrong. The check that matters: *if I deliberately break this logic, does a test go red?* A test that passes against broken code is worse than no test, because it also blocks the refactor that would have removed it.
+
+Specify in the blueprint:
+
+- **Behaviour over implementation.** Tests assert observable outcomes (returned value, stored row, emitted event, rendered state, HTTP response), never internal call sequences or private structure. Heavy mocking of the unit's own collaborators is the usual tell.
+- **Real assertions.** A test that only asserts a type, a length, or "no exception thrown" is not a test. Enumerate the specific expected values.
+- **Red before green.** The story's tests are written to fail against the unimplemented behaviour and pass after; the session records that they were seen red. This is the cheapest possible mutation test.
+- **Mutation testing on the critical modules** where the stack has a maintained tool: pricing, permissions, validation, money, state machines. Mutation score on those modules is a far better signal than global coverage, and unlike coverage it does not reward padding. Verify tool availability for the chosen stack; if none exists, say so and rely on red-before-green plus targeted boundary tests.
+- **Determinism.** No wall-clock, no real network, no shared mutable fixtures, no ordering dependence, seeded randomness. Time and randomness are injected.
+- **Fixtures over inline literals** for anything reused, so a schema change breaks one file.
+- **The critical e2e paths are named** (3–5, no more) and kept green; everything else is unit and integration.
+
+Coverage still appears — as a floor in `check` that prevents silent regression, with the explicit note that raising the number is never a story goal.
+
+## 6. Reviewing code the agent wrote
+
+This blueprint's whole premise is that most code is machine-authored, which changes the defect profile rather than removing it. The published evidence is consistent enough to design around: security performance of generated code has stayed roughly flat while volume exploded — Veracode's 2026 report puts the security pass rate near 56% across 100+ models even as syntax correctness sits near 100%; GitClear's longitudinal analysis of hundreds of millions of changed lines shows duplication and short-term churn climbing while refactoring/code-reuse ("moved" code) collapses; and DORA's 2025 research finds AI raising throughput while delivery stability still degrades, with review capacity becoming the bottleneck. Verify the current figures each run (§9) — the shape of the finding matters more than the exact number, and the numbers move.
+
+Practical consequences to encode in the blueprint:
+
+1. **Syntactic confidence is not correctness.** The code will look idiomatic and be wrong about *your* system: a stale API signature, an invented parameter, a plausible library that does not exist, a config key that was renamed two versions ago. Every external symbol used in a story must trace to a version-pinned dependency listed in the stack section; anything else is a review stop.
+2. **Security is the first-class review dimension, not the last.** Assume generated code is untrusted input until checked. SAST/dependency scanning in `check` catches the mechanical classes; D6 catches authorization logic, which tooling cannot.
+3. **Duplication is the default failure.** The agent cannot see the helper you already have. Before writing, the session searches the repo for an existing implementation; the review asks "have I seen this function before?" A duplication detector in `check` is worth its cost.
+4. **Churn is the honesty metric.** Track what share of code is rewritten within ~2 weeks of merge. It is the number that tells you whether extra output is actually delivering, and it is the one that AI-assisted teams most often never look at.
+5. **A human is the author of record.** "The model wrote it" is not an explanation. Whoever merges owns it and must be able to explain the non-obvious decisions in it. If they cannot, the change is not ready — and that is the honest test of whether review is happening at all.
+6. **Annotate before review.** The session's handoff summary states what changed, what was deliberately not done, which ACs each part satisfies, and every deviation from the blueprint. Author-annotated changes review far better than raw diffs.
+7. **Review load is the real constraint.** More generated code does not mean more shipped value if it queues behind one reviewer. This is why stories are sized for a 200–400 line diff in the first place.
+
+## 7. Delivery and codebase metrics
+
+These diagnose the system, at team level, over time. Every one of them is a way of generating a *question*, never a verdict. Put in the blueprint only the ones the product will actually instrument, each with definition, data source, the epic that instruments it, and a starting target tagged `[ASSUMED]` when it is a guess.
+
+**Delivery (DORA).** The four keys — deployment frequency, lead time for changes, change failure rate, failed-deployment recovery time — plus rework rate, which DORA added in recent research, and reliability as a quasi-metric tied to stated SLOs. They earn their place by being counterbalanced: speed and stability cannot both be gamed at once. Confirm the current formulation and the current benchmark bands each run rather than quoting last year's.
+
+**Review process.** Time to first review (target: same working day), review cycles to merge (1–2 for ordinary work; more usually means the requirement was unclear, not that the code was bad), median diff size, reviewer distribution (concentration is a bus-factor and a bottleneck at once), and the share of changes merged with no substantive comment.
+
+**Codebase health.** Rework/churn rate (share of lines rewritten within ~2 weeks), duplication trend, revert and hotfix rate, escaped defects (found in production ÷ found by gate+review), flaky-test count, dependency vulnerabilities open by severity, `check` runtime (when it crosses the annoyance threshold people stop running it locally, and that is a leading indicator of everything else).
+
+**Experience.** For anything with a team: whether people can get a change to production without friction. The DX Core 4 framing — speed, effectiveness, quality, impact — exists to keep speed from being read alone, and its effectiveness dimension is deliberately survey-based because dashboards cannot see friction. For a solo builder plus agents this collapses to two honest questions per epic: what slowed this session down, and what did I have to guess?
+
+**Reading them.** Look at trends, not points. A metric moving is the start of an investigation, and the cause is almost always in the system — unclear requirements, an unrealistic staging environment, a slow gate, absent ownership — rather than in a person. Pair every number with one qualitative note; the number says something changed, the note says what it felt like.
+
+## 8. Anti-metrics — never in the blueprint
+
+Lines of code, commit count, PR count per person, story points as productivity, and coverage percentage as a goal. Goodhart's law is not a caveat here, it is the predicted outcome: each one is trivially satisfied in a way that makes the codebase worse — padded diffs, split commits, assertion-free tests written to touch lines.
+
+Two harder rules:
+
+- **No metric in this document is a measure of an individual.** DORA-style metrics are explicitly system- and team-level; applying them to a person converts a diagnostic into a target and destroys it. For a solo builder the same rule applies to self-flagellation: the metrics exist to find where the process leaks, not to grade the week.
+- **Self-reported speed is not speed.** Perceived productivity and measured productivity have been found to diverge, sometimes in the opposite direction, in AI-assisted work. If the blueprint claims a time saving, it has to be measured, or it is `[ASSUMED]`.
+
+If a stakeholder wants a single number, give them change failure rate next to deployment frequency, and refuse to reduce it further.
+
+## 9. What to research and cite each run
+
+Do not paste this file's figures into a blueprint. Verify, then cite with `S-nn` and a date:
+
+1. **The stack's actual quality tooling** — formatter, linter and rule set, typechecker strict flags, test runner, coverage tool, mutation-testing tool (does a maintained one exist for this language?), SAST/dependency audit, a11y checker, architecture-rule/fitness-function library, duplication detector. Current versions, maintained status, the exact commands. This is the single highest-value part of this track: it is what makes `check` real instead of aspirational.
+2. **Language and framework conventions** — the official style guide and the community-standard config, so the agent is not inventing conventions.
+3. **Security baseline for the category** — the current OWASP Top 10 (and API or mobile equivalents if relevant), plus category-specific requirements (payments, health, minors, personal data).
+4. **Current delivery-metric definitions and benchmarks** — the latest DORA formulation and performance bands; whether the four keys are still four where you are quoting them.
+5. **Current evidence on AI-authored code quality** — the most recent security-pass-rate and maintainability/churn figures, if the blueprint states any. State them with the year, or state none.
+6. **CI capability of the chosen host** — runners, cache, secrets, required checks, branch protection, and what a "required" gate can actually block on the plan the user has.
+
+## 10. Where this lands in the blueprint
+
+- **Section 13 (Tech Stack)** — the concrete tools and the `check` command, versions pinned, each with evidence.
+- **Section 14 (Quality)** — this file, made specific: the gate contents and runtime, test-quality rules, the named critical e2e paths, the review checklist (§11) verbatim, the metric table, the anti-metric list, the definition of "green" and of "done".
+- **Section 12 (Architecture)** — the fitness functions that enforce the boundaries.
+- **Epic 00** — stories that build the gate: every item in §3 that applies, plus the review checklist committed into the repo so it is present in every future session's context.
+- **Story DoD** — extended so a story is not done until the review checklist has been applied and the ACs each have a test that was seen red.
+- **Section 18 (Session Protocol)** — the agent self-reviews against §4 and §6 before handoff and reports the result in the handoff summary; the human then reviews with the same checklist. Two passes with one checklist beats two different standards.
+
+## 11. Review checklist to embed verbatim
+
+Put this in the blueprint (section 14) and in `AGENTS.md`/`CLAUDE.md` so both the agent and the human use the same list. Adapt the bracketed items to the product; do not shorten the list.
+
+```
+REVIEW CHECKLIST — apply to every story before it is marked DONE.
+Stop at the first unanswered item and fix it; do not batch.
+
+Gate
+[ ] `check` green on the whole repo, not just the changed files
+[ ] No gate rule weakened, skipped or ignored to make this pass (if it was: DR entry, reason)
+[ ] No new flaky test; any flake seen is quarantined with a follow-up story
+
+Correctness
+[ ] Every AC of this story is demonstrably met, verified against behaviour not description
+[ ] Nothing implemented that no AC asked for
+[ ] Every listed edge case is covered by a test or explicitly accepted with a reason
+
+Design
+[ ] Change sits in the module the architecture assigns it to; no forbidden dependency direction
+[ ] No logic duplicated from elsewhere in the repo (searched before writing)
+[ ] Framework's documented path used, not an invention
+[ ] One-way doors (schema on populated tables, public contracts, event formats, new dependency)
+    identified and recorded as a DR
+
+Tests
+[ ] Each AC maps to a named test; each was seen failing before implementation
+[ ] Tests assert concrete expected values, not types/lengths/no-throw
+[ ] Tests assert behaviour, not internal calls; they would survive a refactor
+[ ] Deterministic: no wall clock, no network, no order dependence, seeded randomness
+[ ] [Mutation score on <critical modules> not reduced]
+
+Failure behaviour
+[ ] Empty / one / many / max / boundary all specified and covered
+[ ] Dependency timeout, 5xx and partial response each have defined behaviour
+[ ] Repeat submission is idempotent where it must be; retries are safe
+[ ] Nothing is left in a half-written state on failure
+
+Security
+[ ] Input validated at the trust boundary
+[ ] Authorization checked per object, not only authentication
+[ ] Queries parameterised; output encoded for its sink
+[ ] No secret or PII in code, logs, error payloads or fixtures
+[ ] Rate limits on anything that costs money, sends a message, or can be brute-forced
+[ ] Every external symbol traces to a pinned dependency in the stack table; no invented APIs
+[ ] Any new dependency: recognised, maintained, license-compatible, DR entry written
+
+Scale
+[ ] No query inside a loop; no unbounded result set; indexes exist for filtered/sorted columns
+[ ] Behaviour at 100x current data is stated and acceptable
+
+Observability
+[ ] Decision points logged, structured, correlation ID present, no PII
+[ ] Outcome metric emitted; errors reach error tracking with context
+[ ] This change is diagnosable by someone who did not write it
+
+Copy, locale, accessibility [UI stories]
+[ ] All strings from the copy table by ID; every screen state has its line
+[ ] Digits, dates, currency, direction follow the locale rules
+[ ] Focus order, labels, contrast, touch targets checked
+
+Shape
+[ ] Diff is within [200–400] changed lines, or the story is split
+[ ] A human can explain every non-obvious decision in this change
+[ ] Handoff summary written: what changed, what was skipped, deviations, ACs satisfied
+```

package/bundled-skills/idea-to-blueprint/references/design-minimal.md

@@ -0,0 +1,96 @@
+# Design direction, flows and screens — minimal by default
+
+Contents: 1 Reference vs chosen direction · 2 Minimal pattern catalog (do / don't) · 3 User flow format · 4 Screen inventory format · 5 Design tokens format · 6 RTL rules · 7 Accessibility baseline · 8 Persona-driven design decisions
+
+## 1. Reference vs chosen direction
+
+**User gave a reference** (Figma, screenshots, a product, a brand kit): extract and document — colours, type, spacing rhythm, component shapes, navigation model, tone of imagery. Keep what serves the personas; note every deviation you make and why (usually usability, RTL, contrast, or minimalism). The build sessions need the tokens, not a link to a Figma they cannot open.
+
+**No reference**: choose, don't defer. Default direction unless research says otherwise:
+- Mobile-first, single-column, generous spacing, one primary action per screen.
+- Standard components from a well-documented, actively maintained design system verified this session (RTL support and accessibility documented), themed lightly — no custom component library in v1.
+- Neutral palette with one accent for primary actions and semantic colours for states; high contrast; no gradients or decorative illustration in v1 unless the category demands warmth (then one illustration style, used sparingly).
+- Typography: one Persian/Latin-capable font family, 4–5 sizes, two weights.
+- Motion: functional only (state transitions ≤ 200 ms), respects reduced-motion.
+State the chosen direction in the Decision brief in one line so the user can object once.
+
+## 2. Minimal pattern catalog
+
+Do (default choices):
+- **List → detail** for any collection; no dashboards in v1 unless the persona's job *is* monitoring.
+- **One primary action per screen**, sticky at the bottom on mobile; secondary actions as text buttons or in an overflow menu.
+- **Progressive disclosure**: show the 3–5 fields most people need; "advanced" behind one toggle.
+- **Forms**: single column; labels above fields; inline validation on blur and on submit; the submit button disabled only for *impossible* states, otherwise enabled and showing errors; numeric keyboards for numeric fields; phone-first auth where the market expects it.
+- **Wizard only when a form exceeds ~7 fields or has dependent steps**; show progress; allow back without loss.
+- **Optimistic UI + Undo** for reversible actions; **consequence-stating dialog** for irreversible ones.
+- **Empty, loading, error, offline states designed for every list and screen** — they are screens, not afterthoughts.
+- **Search + 1–2 filters** rather than complex filter panels; recent items where it saves a search.
+- **Bottom sheet** on mobile for pickers and short actions; full screen for anything that needs more than one decision.
+- **Tabs ≤ 4**, otherwise a list.
+- **Onboarding = do the first real task**, with inline guidance; no multi-screen tour; ask for permissions (notifications, location) at the moment they are needed, with the reason.
+- **Skeletons** for < 1 s loads; text status for longer.
+- **Consistent destructive colour and placement**; destructive actions never the default focus.
+
+Don't (in v1 unless a persona demands it): carousels for content that matters, hover-only affordances, custom gestures, infinite settings screens, modal-on-modal, disabled buttons without explanation, icons without labels for primary actions, confirmations for reversible actions, sign-up before showing value, dark patterns of any kind (pre-checked upsells, hidden cancel).
+
+## 3. User flow format
+
+```
+### F-03 — <Flow name> (P1)
+**Job** — what the persona is trying to get done, in one line.
+**Trigger** — how they arrive (deep link from SMS, home screen, notification).
+**Preconditions** — logged in? has data? feature flag?
+**Steps**
+| # | Screen | User does | System responds | Copy | Notes |
+|---|---|---|---|---|---|
+| 1 | SCR-03 | enters phone | validates, sends code | CP-SCR03-1,4 | ≤ 11 digits |
+| 2 | … | | | | |
+**Decision points** — at step n: if <condition> → branch A (steps …) else → branch B.
+**Failure branches** — for each step: what can fail (from edge cases), what the user sees (copy IDs), how they recover, what is persisted.
+**Exit** — where the flow ends and what state the system is in.
+**Success metric** — M-x.y; time-to-complete target `[ASSUMED]` if hypothetical.
+**Benchmark note** — which best-in-class behaviour this adopts (S-nn) and what we do differently.
+```
+
+Flows to include for most products: first run / onboarding, sign-in and re-authentication, the core loop (per persona), money flows (pay, refund, receipt), recovery flows (forgot/lost access, offline, session expired), notifications and their deep links, account settings and deletion, admin/back-office core tasks, error and empty first-use states as flows where they are non-trivial.
+
+Keep flows to the **minimum number of steps** that still respects the persona's decision points; count steps and taps and state them — that number becomes an acceptance criterion.
+
+## 4. Screen inventory format
+
+```
+| ID | Screen | Purpose (one line) | Personas | Entry points | Primary action | States covered | Copy IDs | Edge cases |
+```
+Then one paragraph per screen: layout summary (what is above the fold on a 360-px-wide phone), components used (from the design system by name), the single primary action, secondary actions, what changes per persona/role, and what the screen looks like in each state (empty / loading / error / offline / success / permission-denied where relevant).
+
+Screens are counted: a product with 40 screens in v1 has a scope problem — revisit section 2 before writing copy for all of them.
+
+## 5. Design tokens format
+
+```
+Colour: bg, surface, text-primary, text-secondary, accent, accent-text, success, warning, danger, border, focus-ring — as hex, with contrast ratios noted against their usual backgrounds.
+Type: font families (Persian, Latin, mono) with self-hosted files and license; scale (display, h1, h2, body, small, caption) with size/line-height/weight; Persian line-height factor.
+Spacing: base unit and scale (4/8/12/16/24/32/48).
+Radius, elevation/shadow levels, border widths.
+Breakpoints: mobile ≤ 600, tablet ≤ 1024, desktop.
+Component list: from the design system, with the props/variants allowed in v1 (e.g., Button: primary/secondary/text/danger; sizes md/lg).
+Iconography: set name and license; which icons flip in RTL (arrows, back, send) and which do not (clock, search, play).
+Motion: durations, easing, reduced-motion behaviour.
+```
+
+## 6. RTL rules (when the product language is RTL)
+
+- The document direction is `rtl` at the root; layout mirrors via logical properties (start/end), never left/right.
+- Directional icons flip; symmetric and semantic icons do not; media controls follow platform norms (verify).
+- Numbers and Latin tokens are isolated (bidi) inside RTL text; phone numbers and codes render LTR as a unit.
+- Progress and sliders fill from the start (right) side; back buttons point right; carousels (if any) advance to the left.
+- Test every screen with long Persian strings (Persian runs ~20–30 % longer than English in many labels) and with mixed content.
+- Fonts: confirm the chosen font covers Persian digits and the ZWNJ renders as zero width in the target browsers.
+
+## 7. Accessibility baseline
+
+Reference the current accessibility standard and level after verifying its version this session. Non-negotiables for every UI story's AC-7: text contrast ≥ 4.5:1 (3:1 for large text and UI components), touch targets ≥ 44×44 px, visible focus ring, full keyboard operability on web, labels for every input and icon button, live regions for async errors/success, no information by colour alone, `prefers-reduced-motion` respected, text resizable to 200 % without loss, meaningful page titles and headings order, form errors associated to fields. Screen-reader language attribute set to the product language so pronunciation is right.
+
+## 8. Persona-driven design decisions
+
+For each persona sheet trait, write the design consequence in section 9 (the same way §2 of the UX writing guide does for copy): low-end device → lightweight pages, no heavy media, offline tolerance for reads; poor network → optimistic UI, retry with backoff, small payloads; busy shop floor → large targets, high contrast, two-tap core action; older or low-vision users → larger base font, simpler navigation; admin power user → dense tables, keyboard shortcuts, bulk actions. These consequences become acceptance criteria (performance budgets, tap counts, target sizes) rather than adjectives.

package/bundled-skills/idea-to-blueprint/references/edge-case-catalog.md

@@ -0,0 +1,239 @@
+# Edge-case catalog
+
+How to use: for every story, walk each category below and ask the question. If it applies, either reference the global register entry (`EC-<CAT>-nn` in section 15 of the blueprint) with the story-specific expected behaviour, or add a story-level case. Then make sure at least one AC or test covers it. "Not applicable" is a valid answer; "didn't think of it" is not.
+
+Category codes: INPUT · AUTH · DATA · TIME · NET · DEV · CONC · PAY · FILE · MSG · PERM · SEARCH · BIZ · INT · OPS · L10N · SEC · A11Y · IR (Iran-specific) · BOT (messenger bots) · ADMIN
+
+## INPUT — input and validation
+- EC-INPUT-01 Empty / whitespace-only / only ZWNJ or invisible characters → treated as empty; field-level error; no request.
+- EC-INPUT-02 Maximum length reached / exceeded on paste → hard limit enforced client and server; counter shown; truncation policy explicit.
+- EC-INPUT-03 Invisible or control characters pasted (zero-width, RTL marks, tabs) → stripped or rejected before validation.
+- EC-INPUT-04 Emoji, combining marks, unusual scripts in names/text → stored and rendered correctly; length counted in graphemes.
+- EC-INPUT-05 HTML/script/SQL-looking input → escaped on output, parameterised queries; never executed; shown back verbatim as text.
+- EC-INPUT-06 Leading zeros, plus signs, spaces, dashes in numeric identifiers (phone, card, code) → normalised by one shared function; original never stored.
+- EC-INPUT-07 Persian/Arabic-Indic digits in numeric fields → normalised to Latin before validation and storage.
+- EC-INPUT-08 Arabic ي/ك vs Persian ی/ک in text → normalised for storage and search; display as Persian.
+- EC-INPUT-09 Boundary values (0, -1, max int, 1 over the limit, exactly the limit) → explicit expected results.
+- EC-INPUT-10 Duplicate submission of the same content (same title twice) → rule stated: allowed, merged, or rejected with copy.
+- EC-INPUT-11 Autofill/autocorrect altering input (browser filling email into phone) → validation catches, error names the field.
+- EC-INPUT-12 Decimal and thousands separators in money/quantity fields (Persian ٫ ٬ vs , .) → accepted and normalised.
+
+## AUTH — identity, sessions, OTP
+- EC-AUTH-01 OTP wrong code n times → attempt limit, lockout duration, copy with remaining attempts.
+- EC-AUTH-02 Double tap / double submit → single request (button disabled while pending, server idempotency).
+- EC-AUTH-03 Resend before cooldown → blocked client-side; server-enforced; copy shows seconds.
+- EC-AUTH-04 Code expired then entered → specific error, offer new code; old code invalid after new one issued.
+- EC-AUTH-05 Session expires mid-action (in a form, mid-payment) → draft preserved; re-auth then return to the same step.
+- EC-AUTH-06 Same account on two devices → policy: allowed with device list, or single-session with kick-out notice.
+- EC-AUTH-07 Phone number recycled by operator / user changes number → account recovery path and ownership rules.
+- EC-AUTH-08 Deep link opened while logged out → land on login, then continue to the target.
+- EC-AUTH-09 Role or permissions changed while logged in → effective on next request; UI refreshes; no stale privileged actions.
+- EC-AUTH-10 Account deleted then same phone/email signs up → clean new account; old data not resurrected (retention rule).
+- EC-AUTH-11 Brute force on OTP or password → rate limits per number and per IP; monitoring alert.
+- EC-AUTH-12 Sign-in via a channel the user no longer controls (old email) → recovery requires the current primary channel.
+
+## DATA — data and state
+- EC-DATA-01 First use, no data → designed empty state with one action.
+- EC-DATA-02 Exactly one item (no plural, no "others") → copy and layout handle singular.
+- EC-DATA-03 Thousands of items → pagination or virtualisation; response size limit; sort stable.
+- EC-DATA-04 Pagination boundaries (exactly page size, last page, item deleted while paging) → no duplicates/gaps; cursors preferred.
+- EC-DATA-05 Sort ties → deterministic secondary key.
+- EC-DATA-06 Soft-deleted or archived referenced items → how they display in lists, details, exports.
+- EC-DATA-07 Orphaned records after deletion → cascade or restrict policy per relation; tested.
+- EC-DATA-08 Long text in short layouts → truncation with full text on tap; no overflow breaking RTL layout.
+- EC-DATA-09 Migration on live data → backfill plan, reversible, tested against a dump.
+- EC-DATA-10 Very long lists in exports (CSV/Excel) → streaming; Persian text encoding correct (UTF-8 with BOM if Excel is a target — verify).
+- EC-DATA-11 Duplicate detection rules (same phone twice, same product name) → stated per entity.
+- EC-DATA-12 Stale data on screen after another actor changes it → refresh policy; conflict copy.
+
+## TIME — dates, calendars, time zones
+- EC-TIME-01 Jalali month lengths and Esfand leap year → library verified; tests for the current and next two years.
+- EC-TIME-02 Month/year boundaries in reports ("this month" at 23:59 on the last day) → boundaries computed in Asia/Tehran, stored UTC.
+- EC-TIME-03 Week starts Saturday; "this week", weekly reports and pickers follow it.
+- EC-TIME-04 DST policy of the target zone (verify current) → no assumptions; tests around historic transitions if any.
+- EC-TIME-05 Holidays and closed days (official calendar source verified) → scheduling and reminders respect them.
+- EC-TIME-06 Device clock wrong → server time is authoritative for expiries; relative times computed from server timestamps.
+- EC-TIME-07 Relative time wording ("۳ دقیقه پیش" vs absolute after 24 h) → one rule.
+- EC-TIME-08 Cross-year ranges and reports spanning Nowruz → correct year labels.
+- EC-TIME-09 Expiry exactly at boundary (expires_at == now) → inclusive/exclusive stated.
+
+## NET — network and connectivity
+- EC-NET-01 Offline at load → cached read view or explicit offline screen; nothing spinning forever.
+- EC-NET-02 Offline at submit → draft kept locally; clear copy; retry when back or manual retry.
+- EC-NET-03 Request timed out but server completed it → idempotency keys so retry does not duplicate; client reconciles.
+- EC-NET-04 Very slow network (2G-class) → payload budgets; skeletons; timeouts with retry; images lazy and sized.
+- EC-NET-05 Partial upload / interrupted download → resumable or restart with clear copy; no half-written records.
+- EC-NET-06 Server returns 5xx / maintenance → friendly copy, retry, status not blaming the user; error tracked.
+- EC-NET-07 API version mismatch (old client, new server) → graceful message, forced update policy for native apps.
+- EC-NET-08 Captive portal / blocked host (CDN or fonts blocked in the market) → self-hosted assets; no functional dependency on foreign CDNs.
+- EC-NET-09 Retry storms → exponential backoff with jitter; max attempts.
+
+## DEV — devices, browsers, platform
+- EC-DEV-01 Small screens (≤ 360 px) and large text settings (200 %) → no clipped primary actions.
+- EC-DEV-02 Low-memory Android → no huge lists in memory; images downscaled.
+- EC-DEV-03 Browser back/forward and refresh mid-flow → state restored or explicit restart with no data loss.
+- EC-DEV-04 Multiple tabs / app instances → last write wins or conflict notice; session shared correctly.
+- EC-DEV-05 Notification permission denied → in-app fallback; copy explains how to enable later.
+- EC-DEV-06 Dark mode / high contrast OS settings → respected or explicitly forced with reason.
+- EC-DEV-07 Keyboard covering the primary button on mobile → layout scrolls; button reachable.
+- EC-DEV-08 Old browser/webview versions common in the segment (verify) → feature detection, polyfills, or supported-browsers copy.
+- EC-DEV-09 Clipboard and share APIs unavailable → fallback UI.
+- EC-DEV-10 PWA install prompt behaviour differs per browser → tested on the segment's browsers; manual install instructions copy.
+
+## CONC — concurrency and idempotency
+- EC-CONC-01 Two actors edit the same record → optimistic locking (version field) and conflict copy.
+- EC-CONC-02 Double-click on create/pay → idempotency key; one record; UI disables while pending.
+- EC-CONC-03 Race on limited inventory/slots → transactional check-and-decrement; clear "just sold out" copy.
+- EC-CONC-04 Webhook arrives before the local record is committed → retry/queue; eventual consistency handled.
+- EC-CONC-05 Background job runs twice (scheduler overlap) → idempotent jobs; lock or unique key.
+- EC-CONC-06 Ordering of events out of sequence (status updates) → monotonic status machine; ignore stale transitions.
+
+## PAY — payments and money
+- EC-PAY-01 Gateway redirect never returns (user closes browser after paying) → server-side verification via callback/inquiry; order reconciled; receipt on next visit.
+- EC-PAY-02 Callback missing, delayed or duplicated → idempotent handler; inquiry job for pending payments; duplicate callbacks ignored.
+- EC-PAY-03 Amount mismatch between request and callback → payment rejected, flagged, alert; user copy: nothing charged / contact support.
+- EC-PAY-04 Gateway down or rejects merchant → alternative gateway policy or explicit "temporarily unavailable" with retry; order kept pending with expiry.
+- EC-PAY-05 Refunds (full, partial, failed refund) → API availability verified; manual fallback process documented; copy for each state.
+- EC-PAY-06 Currency unit and rounding (Toman vs Rial; no decimals) → one conversion function; tests on boundaries; labels always shown.
+- EC-PAY-07 Expired invoice / price changed since checkout began → re-quote with copy; no silent charge of a new amount.
+- EC-PAY-08 Partial payment / wallet + gateway combinations → state machine explicit.
+- EC-PAY-09 Fee and VAT display rules → who pays fees; shown before confirmation.
+- EC-PAY-10 Receipts and audit trail → immutable record; downloadable; matches the gateway reference ID.
+- EC-PAY-11 Test/sandbox vs production credentials mixed up → startup validation refuses sandbox keys in production.
+- EC-PAY-12 Sanctions or blocked service for the market (foreign gateways/processors) → excluded by decision record; verified at build.
+
+## FILE — files and media
+- EC-FILE-01 Oversized file → client-side pre-check and server limit; copy with the limit.
+- EC-FILE-02 Unsupported or mislabeled type (extension vs magic bytes) → server validates content; rejected with copy.
+- EC-FILE-03 Image orientation (EXIF), HEIC/HEIF from iPhones, very large dimensions → normalised, converted, resized.
+- EC-FILE-04 Persian/Unicode filenames and spaces → stored under generated keys; original name kept for display.
+- EC-FILE-05 Malware or harmful content → scanning policy or restriction of types; never executed/served inline unsafely.
+- EC-FILE-06 Storage quota reached / storage service down → clear copy; upload queued or blocked; no dangling references.
+- EC-FILE-07 Deleting a file referenced elsewhere → reference check or tombstone.
+- EC-FILE-08 Slow upload progress and cancel → progress shown; cancel leaves no partial record.
+
+## MSG — SMS, email, push, in-app messaging
+- EC-MSG-01 Provider accepts but never delivers → resend policy; alternative channel; delivery status if the provider offers it.
+- EC-MSG-02 Wrong or unreachable number → bounce handling; copy asking to check the number.
+- EC-MSG-03 Persian SMS length (Unicode segments) → templates tested against the provider's segment limit; no cut-off codes.
+- EC-MSG-04 Duplicate sends (job retried) → dedupe key per message intent.
+- EC-MSG-05 Quiet hours / night sends → schedule window per persona; urgent exceptions listed.
+- EC-MSG-06 Opt-out / unsubscribe → honoured immediately; transactional vs marketing distinction.
+- EC-MSG-07 Email in spam / not delivered → SPF/DKIM verified in ops; in-app copy of the message.
+- EC-MSG-08 Push token expired or app uninstalled → token cleanup; no error shown to other users.
+- EC-MSG-09 Template placeholders unfilled ("{name}") → render-time validation; test for every template.
+- EC-MSG-10 Rate limits at provider → queue with backoff; alert when backlog grows.
+
+## PERM — permissions, privacy, roles
+- EC-PERM-01 Role × action matrix enforced server-side, not just hidden in UI → tests per role per endpoint.
+- EC-PERM-02 Direct object access by ID (another tenant's record) → 404/403 policy; tests.
+- EC-PERM-03 Admin acting on behalf of a user → audit log entry with actor, target, reason.
+- EC-PERM-04 PII in logs, error tracking, analytics → redaction rule; tests that scan log output.
+- EC-PERM-05 Data export and deletion on request → complete, within stated time; cascades documented.
+- EC-PERM-06 Consent for notifications/analytics → recorded with timestamp; revocable.
+- EC-PERM-07 Retention limits (OTP codes, sessions, logs, backups) → stated and enforced by jobs.
+- EC-PERM-08 Screenshots/previews containing sensitive data (link previews, notification previews) → masked where the platform allows.
+
+## SEARCH — search and lists
+- EC-SEARCH-01 Persian normalisation (ی/ک, ZWNJ vs space, diacritics, Arabic vs Persian forms) → indexed and queried normalised.
+- EC-SEARCH-02 Zero results → copy with suggestion; filters visible; clear-all.
+- EC-SEARCH-03 Typos and partial words → tolerance policy stated (prefix, fuzzy) with limits.
+- EC-SEARCH-04 Numbers searched with Persian digits → normalised.
+- EC-SEARCH-05 Very common query (single letter) → minimum length or debounce; performance bound.
+- EC-SEARCH-06 Results changing while browsing → stable pagination cursors.
+
+## BIZ — business rules and lifecycle
+- EC-BIZ-01 Plan/quota limit reached mid-action → copy before the action when predictable; graceful block otherwise.
+- EC-BIZ-02 Subscription expires mid-session → grace behaviour; read-only vs blocked; copy.
+- EC-BIZ-03 Downgrade with data over the new limit → policy (read-only, archive, delete after notice).
+- EC-BIZ-04 Cancel/return after fulfilment started → state machine; who can do it; copy.
+- EC-BIZ-05 Time-based cutoffs (order before 20:00) → server time, Asia/Tehran, copy shows the deadline.
+- EC-BIZ-06 Price or catalogue changes while a cart/session is open → re-validation at checkout; copy.
+- EC-BIZ-07 Minimums and maximums (order minimum, max quantity) → shown before, enforced server-side.
+- EC-BIZ-08 Multi-tenant boundaries (a restaurant sees only its data) → tenant scoping in every query; tests.
+
+## INT — integrations and third parties
+- EC-INT-01 Service down → fallback per integration card; user copy; degraded mode.
+- EC-INT-02 API changed / deprecated endpoint → version pinned; contract tests against sandbox; alert on schema drift.
+- EC-INT-03 Rate limits → client-side limiter; backoff; queue.
+- EC-INT-04 Sandbox vs production behaviour differences → documented; staging uses sandbox; production smoke checklist.
+- EC-INT-05 Secrets rotation → config reload or restart procedure; no secrets in repo; tests that config loads.
+- EC-INT-06 Service blocked for the market or by sanctions → excluded or re-verified at build (`[VERIFY-AT-BUILD]`).
+- EC-INT-07 Webhook signature invalid or replayed → verify signature and timestamp; reject replays.
+- EC-INT-08 Partial success in batch calls → per-item status handled.
+
+## OPS — operations and deployment
+- EC-OPS-01 Missing or invalid environment variable → app refuses to start with a clear message (fail fast).
+- EC-OPS-02 Migration fails mid-deploy → transactional migrations or documented rollback; deploy aborted; health check fails loudly.
+- EC-OPS-03 Rollback to previous release with a newer schema → backward-compatible migrations for one release.
+- EC-OPS-04 Backups: taken, encrypted, restore tested → restore drill is a story in an ops epic.
+- EC-OPS-05 Disk/log growth → rotation and retention.
+- EC-OPS-06 Alerting on error rate, latency, queue backlog, failed jobs → thresholds stated.
+- EC-OPS-07 Seed data in production by mistake → guarded scripts.
+- EC-OPS-08 Time drift between servers → NTP; tokens tolerate small skew.
+- EC-OPS-09 Health endpoint reports dependencies (DB, cache, provider) → used by the platform.
+
+## L10N — localisation and RTL
+- EC-L10N-01 RTL layout: mirrored icons, logical properties, scroll direction → visual tests on key screens.
+- EC-L10N-02 Mixed-direction strings (Persian + Latin + digits) → bidi isolation; punctuation stays in place.
+- EC-L10N-03 Longer Persian strings → no truncation of primary actions; wrapping rules.
+- EC-L10N-04 Plural forms and counters → Persian pluralisation rules; "۱ مورد" vs "۵ مورد".
+- EC-L10N-05 Digit rendering (Persian vs Latin) consistent per the decision record → tests on every formatted number.
+- EC-L10N-06 Font missing/blocked → self-hosted; fallback stack; ZWNJ renders zero-width.
+- EC-L10N-07 Date/number/currency formatting through one utility → no ad-hoc formatting in components.
+- EC-L10N-08 Untranslated strings leak (English fallback) → test that every key has product-language copy from the copy table.
+
+## SEC — security baseline
+- EC-SEC-01 Injection (SQL, command, template) → parameterised/ORM, no string concatenation; tests.
+- EC-SEC-02 XSS and unsafe HTML → output encoding; CSP; sanitiser for rich text if any.
+- EC-SEC-03 CSRF for cookie-based sessions → tokens or same-site cookies; tests.
+- EC-SEC-04 Broken access control → EC-PERM-01/02 tests per endpoint.
+- EC-SEC-05 Secrets in repo/logs/client bundle → scanning in CI; env only.
+- EC-SEC-06 Dependency vulnerabilities → audit in `check` or CI; policy for updating.
+- EC-SEC-07 Brute force and enumeration (does this phone exist?) → uniform responses and timing where it matters; rate limits.
+- EC-SEC-08 Security headers and TLS → configured at the edge; verified in an ops story.
+- EC-SEC-09 File upload as attack vector → EC-FILE-02/05.
+- EC-SEC-10 Session fixation/hijack → rotate on login; secure cookie flags; short-lived tokens with refresh.
+
+## A11Y — accessibility
+- EC-A11Y-01 Screen reader: labels, roles, announcements for async changes → per screen.
+- EC-A11Y-02 Keyboard-only (web): focus order, trap in dialogs, escape closes → tests.
+- EC-A11Y-03 Colour-only meaning (status by colour) → icon or text as well.
+- EC-A11Y-04 Text scaling 200 % → layout holds.
+- EC-A11Y-05 Motion sensitivity → reduced motion respected.
+- EC-A11Y-06 Timeouts (OTP expiry, session) → warning and extension where feasible.
+- EC-A11Y-07 Error identification → associated with the field, announced.
+
+## IR — Iran-specific (load when users are Iranian; verify each at research and at build)
+- EC-IR-01 Users on VPN → IP geolocation unreliable; never gate features by IP country; language from settings, not IP.
+- EC-IR-02 Mobile prefixes and operators → validation by format (11 digits, 09…) not by a hard-coded operator list; MVNOs exist.
+- EC-IR-03 National ID check digit → validated when collected; copy explains why it is needed; not required unless a business rule demands it.
+- EC-IR-04 Postal code (10 digits) and address structure → fields and validation as the category norm.
+- EC-IR-05 Foreign CDNs, fonts, analytics, maps blocked or slow → self-hosted assets; domestic or self-hosted alternatives; no functional dependency on blocked hosts.
+- EC-IR-06 Payment through licensed gateways only; e-commerce trust seal requirement flagged as OQ → checkout copy and flows match the gateway's redirect/callback model.
+- EC-IR-07 Currency volatility → prices editable quickly by the business persona; no hard-coded prices; historical prices kept on orders.
+- EC-IR-08 Weekend Thursday/Friday and official holidays → scheduling, "next business day" logic, support-hours copy.
+- EC-IR-09 App distribution → PWA install path and/or domestic Android stores; update strategy without Play Services if unavailable.
+- EC-IR-10 Messenger channel availability (Telegram under filtering, domestic messengers) → channel chosen by research; fallback to SMS for critical messages.
+- EC-IR-11 Persian text in SMS → Unicode segment limits; codes never split across segments.
+- EC-IR-12 Hosting reachability → domain, DNS, TLS and hosting reachable without VPN; verified at build.
+- EC-IR-13 Foreign services with sanctions clauses in ToS → excluded or explicitly risk-accepted in a DR.
+- EC-IR-14 Jalali everywhere in UI, UTC in storage → single conversion utility; leap-year tests.
+
+## BOT — messenger bots (when the product is or includes a bot)
+- EC-BOT-01 Unknown command / free text → helpful fallback with the main options; never silent.
+- EC-BOT-02 Message edits/deletes, stickers, voice, forwarded messages → handled or politely declined.
+- EC-BOT-03 Group vs private chat behaviour → explicit policy.
+- EC-BOT-04 Platform rate limits and flood control → queue; backoff.
+- EC-BOT-05 Webhook downtime → missed updates recovered on restart (offset/polling policy).
+- EC-BOT-06 Long conversations and state expiry → state machine with timeouts; "start over" always available.
+- EC-BOT-07 Keyboard buttons with stale state (user taps an old button) → validate state; explain.
+- EC-BOT-08 Blocked bot / user left → cleanup; no repeated failed sends.
+- EC-BOT-09 Multiple languages in one chat → language preference per user.
+
+## ADMIN — back-office
+- EC-ADMIN-01 Bulk actions partially failing → per-row result; nothing silently skipped.
+- EC-ADMIN-02 Destructive admin actions → consequence dialog; audit; undo window where feasible.
+- EC-ADMIN-03 Impersonation / support view → read-only by default; audited.
+- EC-ADMIN-04 Exports with PII → access controlled; logged.
+- EC-ADMIN-05 Filters returning huge result sets → limits; async export.