opencode-skills-collection 4.1.2 → 4.1.3

package/bundled-skills/idea-to-blueprint/references/session-protocol.md

@@ -0,0 +1,133 @@
+# Session protocol — one epic per fresh session
+
+Contents: 1 Why fresh sessions · 2 What must live in the repo · 3 Session lifecycle · 4 Gates (what "done" requires) · 5 Handoff summary format · 6 PROGRESS.md and DECISIONS.md · 7 Amending the blueprint from a session · 8 Recovery · 9 Claude Code vs Codex notes · 10 `[VERIFY-AT-BUILD]` re-check rule
+
+This section is copied (adapted to the product) into section 18 of the blueprint. Its files are in `assets/`.
+
+## 1. Why fresh sessions
+
+Long agent sessions accumulate drift: forgotten constraints, half-remembered decisions, context compression. Starting each epic in a clean session forces every needed fact to live in the repo, where it is versioned, greppable and reviewable. The cost is that nothing can be assumed to be remembered — so the protocol makes the repo the memory: the blueprint says *what*, PROGRESS.md says *where we are*, DECISIONS.md says *why*, and `check` says *whether it works*.
+
+## 2. What must live in the repo (created in Epic 00)
+
+```
+docs/BLUEPRINT.md      the full blueprint (this document)
+docs/PROGRESS.md       state: epic/story status, AC evidence, deviations, next preconditions
+docs/DECISIONS.md      decision records DR-nn (from the blueprint + those made during sessions)
+AGENTS.md              Codex entry point: points at the three docs and the protocol
+CLAUDE.md              Claude Code entry point: same content
+.env.example           every variable with a one-line meaning
+<check command>        one command that runs format + lint + typecheck + tests (documented in BLUEPRINT §13.4)
+```
+
+`AGENTS.md` and `CLAUDE.md` are identical in content and short (≤ 60 lines): where the docs are, the protocol in ten lines, the `check` command, the commit format, and the rule "if it's not in BLUEPRINT or PROGRESS, ask or record — don't assume".
+
+## 3. Session lifecycle
+
+**Boot (user)** — open a fresh session in the repo, paste the session prompt for the epic (Appendix A of the blueprint; generated from `assets/session-prompt.md`).
+
+**Orient (agent)**
+1. Read `AGENTS.md`/`CLAUDE.md`, then `docs/PROGRESS.md` entirely, then `docs/BLUEPRINT.md` sections 12–16, 18, 21 and the target epic in section 17 (and any flow/screen/copy sections the epic references).
+2. Verify preconditions: previous epics DONE in PROGRESS.md; `git status` clean on the main branch; `check` green on a clean tree; env vars listed in the epic's preconditions present locally; every `[VERIFY-AT-BUILD]` item the epic depends on re-checked (see §10) and the result recorded in PROGRESS.md.
+3. If a precondition fails: stop, report exactly what fails and the fix, do not start building. The user decides.
+
+**Plan (agent)**
+4. Restate the epic goal and the story list in ≤ 15 lines. List the ACs that are unclear or reference missing IDs (there should be none; if there are, they are blueprint defects → §7).
+5. Produce the session plan: story order, the tests to write per story (from the story's Tests block), the tasks, and the manual checks the user will need to do at the end. Estimate whether it fits the session; if not, propose which stories to defer to a follow-up epic `E03b` and record it in PROGRESS.md as a deviation.
+6. Wait for "go" unless the user pre-approved ("plan and build without stopping").
+
+**Build (agent)** — for each story in order:
+7. Create a branch `epic/E03` (once per epic) if not on trunk-only.
+8. Write the tests for the story's ACs first; run `check`; the new tests must fail.
+9. Implement the tasks; run `check` after each task or story; keep it green. Copy strings come from the copy table by ID — no improvised strings.
+10. Commit per story: `feat(auth): request OTP by phone [E02-S01]` (type/scope per BLUEPRINT §13.7). Record the story as DONE in PROGRESS.md with one evidence line per AC (test name, or manual-check result).
+11. Any decision not covered by the blueprint (a library detail, a schema nuance) → add `DR-nn` to DECISIONS.md in the same commit. Any AC that turns out wrong or impossible → §7, never a silent change.
+
+**Verify (agent)**
+12. Run the full `check`; run the epic-level tests (flow e2e) and the whole regression suite; run CI (push and wait, or run the CI script locally).
+12b. **Self-review.** Walk the review checklist (BLUEPRINT §14.4) over the epic's diff, story by story, and answer every item. Do this as if reviewing someone else's work: read the diff, not your memory of writing it. Fix what fails rather than noting it. Report the result in the handoff summary as `reviewed: <n> items, <n> fixed, <n> accepted with reason` — never as a bare ✔. This pass exists because the human reviewer sees a large diff produced quickly, and their attention is the scarcest resource in the whole process; anything you can catch here is worth ten times what it costs.
+12c. If the diff for any story exceeded the size limit in §14.4, say so explicitly in the handoff. It is a signal that the story was mis-sized in the blueprint, and it is worth an amendment for the next epic.
+13. Deploy to staging per BLUEPRINT §13.8 if the epic's DoD requires it; run the smoke checks; record results.
+14. Walk the epic's Definition of Done line by line; each line gets a ✔ with evidence or the epic is not done.
+
+**Handoff (agent)**
+15. Update PROGRESS.md: epic status, per-story status, AC evidence, deviations, accepted risks, `[VERIFY-AT-BUILD]` results, next epic's preconditions and any prep the user must do (credentials, accounts).
+16. Update DECISIONS.md and the blueprint Amendments log if anything changed.
+17. Final commit; merge to main if the branch policy says so; confirm CI green.
+18. Print the handoff summary (§5) and say explicitly: "Safe to terminate this session. Next: open a fresh session and paste the E04 prompt."
+
+**Terminate (user)** — close the session. Open a new one for the next epic. Repeat.
+
+## 4. Gates
+
+An epic is DONE only when all of these are true; the agent never marks DONE otherwise:
+
+- Every story DONE with an evidence line per AC (an automated test name that passes in `check`, or a recorded manual check with observation and date).
+- `check` green on the final commit; CI green.
+- Epic-level flow tests green; all previous epics' tests green (no regressions).
+- Staging smoke checks passed when required by the DoD.
+- The review checklist (§14.4) applied to every story, with the result recorded — not "reviewed", but which items failed and what was done.
+- No gate rule weakened, disabled or bypassed to reach green; if one was, a DR entry states why and a follow-up story restores it.
+- No `TODO`/`FIXME`/skipped tests introduced without a matching PROGRESS.md "accepted risk" line with reason and owner.
+- No new flaky test; any flake observed is quarantined with a follow-up story, never re-run until green.
+- PROGRESS.md, DECISIONS.md and (if needed) the Amendments log are updated and committed.
+
+If a gate cannot be met in the session, the epic stays IN PROGRESS with an exact list of what remains; the next session resumes it (§8). Partial is fine; pretending is not.
+
+## 5. Handoff summary format (≤ 20 lines)
+
+```
+## Handoff — E03 <Title> — <date>
+Status: DONE | IN PROGRESS (remaining: E03-S04 AC-3, AC-5; staging smoke)
+Stories: E03-S01 DONE · E03-S02 DONE · E03-S03 DONE · E03-S04 IN PROGRESS
+check: green (commit abc123) · CI: green · staging: deployed, smoke 3/3
+Self-review (§14.4): 4 items failed and fixed (missing object-level auth check on API-07; N+1 in
+  order list; two tests asserted only length; SCR-04 empty state used an improvised string).
+  1 accepted: duplication detector flags the two DTO mappers — kept, extraction is E05's job.
+Diff size: E03-S02 was 620 lines, over the 400 limit — story was mis-sized, amendment A-03 splits it.
+Deviations: E03-S02 AC-4 rate limit changed 5→10 per 10 min — see Amendment A-02, DR-07
+Accepted risks: none | E03-S03 EC-MSG-01 manual only until provider sandbox supports delivery status
+VERIFY-AT-BUILD: INT-sms reachable ✔ (2026-09-05); gateway sandbox ✔
+Decisions added: DR-07, DR-08
+Next epic E04 preconditions: create staging bucket; add STORAGE_KEY to .env; nothing else
+Manual checks for you: open staging SCR-03, request a code on your phone, confirm delivery < 30 s
+Safe to terminate. Next: fresh session, paste E04 prompt.
+```
+
+## 6. PROGRESS.md and DECISIONS.md
+
+Formats are in `assets/PROGRESS.md.template` and `assets/DECISIONS.md.template`. Principles:
+
+- PROGRESS.md is a **state file, not a diary**: current status per epic and story, evidence, deviations, risks, preconditions. Session logs are one line per session at the bottom (date, epic, outcome, commit).
+- Evidence lines are specific: `AC-3 ✔ api/auth_otp_request.test::provider_timeout_returns_503` or `AC-6 ✔ manual 2026-09-05 — Persian digits render on Chrome Android 128`.
+- DECISIONS.md holds `DR-nn` entries: context, options, decision, consequences, date, epic. Blueprint DRs are copied in at Epic 00 so there is one place to look.
+
+## 7. Amending the blueprint from a session
+
+The blueprint is the source of truth, so when reality disagrees with it, the blueprint changes — explicitly:
+
+1. Do not silently implement something different from an AC.
+2. Add an entry to the **Amendments log** (section 18 of the blueprint, table `A-nn | date | epic/story | what changed | why | approved by`).
+3. Edit the affected AC/copy/architecture text in place and mark it `(amended A-nn)`.
+4. If the change affects other epics, add a line to their preconditions.
+5. Scope additions are not amendments — they are new stories in a later epic; record the idea in PROGRESS.md "Parking lot" and move on.
+
+Ask the user before amending anything that changes user-visible behaviour, money, data retention or security; smaller technical amendments can be made and reported in the handoff.
+
+## 8. Recovery
+
+- **Session crashed or was terminated mid-epic**: the next session reads PROGRESS.md, runs `git status` and `git log`, inspects the epic branch, runs `check`, and resumes from the first story/AC without evidence. Uncommitted work is inspected and either committed with a WIP note or discarded, stated in PROGRESS.md.
+- **`check` red at boot**: the previous session violated a gate. Fix the red first as a hotfix story `E03-S00 — restore green` with its own evidence, then continue.
+- **Blueprint defect found** (missing ID, contradictory ACs): treat as §7; if blocking, stop and ask.
+- **Environment broken** (missing service, credentials expired): record in PROGRESS.md, report, stop.
+
+## 9. Claude Code vs Codex notes
+
+- Both read a root instructions file: Claude Code reads `CLAUDE.md`; Codex reads `AGENTS.md`. Keep both, identical in content, pointing at the docs.
+- Skills: Claude Code discovers `SKILL.md` folders under `.claude/skills/` (project) and `~/.claude/skills/` (personal); Codex discovers the same open skill format from its skills locations (`~/.codex/skills/`, `.codex/skills/`, and `.agents/skills/` in recent versions — confirm against the current Codex docs when installing). The session protocol does not depend on skills at build time; it depends only on the repo files.
+- Invocation: paste the session prompt as the first message in either tool. If the harness exposes an effort/thinking level, set it to the maximum for planning and verification steps.
+- Verification commands must be runnable by the agent without interaction (no prompts, no watch mode). Provide a `check` that exits non-zero on failure.
+
+## 10. `[VERIFY-AT-BUILD]` re-check rule
+
+Every item tagged `[VERIFY-AT-BUILD]` in the blueprint (service availability, sandbox status, prices, sanctions/blocking status, app-store policy, library latest patch) is listed in section 18 with the epic that first depends on it. At Orient time the agent re-checks the items its epic needs (a search or a request against the sandbox), records `✔ date` or `✘ date + what changed` in PROGRESS.md, and if ✘ stops and reports before building on it.

package/bundled-skills/idea-to-blueprint/references/stories-ac-tests.md

@@ -0,0 +1,194 @@
+# Stories, acceptance criteria, tests, DoD
+
+Contents: 1 Why the format is strict · 2 Story format · 3 Acceptance criteria rules · 4 Edge cases, tests, tasks · 5 Epic template · 6 Epic 00 Foundation contents · 7 Sizing · 8 Worked example · 9 Anti-example
+
+## 1. Why the format is strict
+
+A coding agent in a fresh session turns each acceptance criterion into a test and then into code. Anything the criterion leaves open, the agent decides silently. So criteria are written to be **testable without interpretation**: concrete inputs, concrete observable outputs, concrete copy IDs, concrete numbers. Adjectives ("fast", "clear", "appropriate", "properly") are defects.
+
+## 2. Story format
+
+```
+### E03-S02 — <Short imperative title>
+
+**Story** — As **P2 (<persona name>)**, I want <capability>, so that <outcome the persona cares about>.
+**Context** — 2–5 sentences: why this exists, what the persona is doing at that moment, what research/benchmark informed it (S-nn), which flow(s) and screen(s) it implements (F-03, SCR-07).
+**Scope** — In: … Out (handled in E05-S01 / non-goal): …
+**Acceptance Criteria**
+- AC-1 (happy path) Given … When … Then …
+- AC-2 (validation) …
+- AC-3 (failure/degraded) …
+- AC-4 (state edge) …
+- AC-5 (permissions) …
+- AC-6 (copy) …
+- AC-7 (accessibility) …
+- AC-8 (observability) …
+**Edge cases** — EC-xxx-nn references plus story-specific ones, each with expected behaviour.
+**Tests** — the tests that prove the ACs (see §4).
+**Tasks** — ordered implementation tasks E03-S02-T1… (see §4).
+**Story DoD** — the checklist that must be true before the story is marked DONE in PROGRESS.md.
+```
+
+Personas are referenced by ID and name; "As a user" is not allowed — if no persona fits, the persona list is incomplete, fix that first. Internal/technical work (migrations, CI) is written as a story for the **builder persona** (define one, e.g., `P0 — Builder (the coding agent / maintainer)`), so the format stays uniform and the linter stays happy.
+
+## 3. Acceptance criteria rules
+
+Each criterion is `Given <state> When <action> Then <observable result>` and:
+
+- Names concrete data ("a phone number of 11 digits starting with 09", "an order with 3 items totalling 450,000 Toman"), not categories.
+- Names the copy line shown (`CP-SCR07-4`), not "an error message".
+- Uses numbers for anything measurable: timeouts, limits, lengths, response times, retry counts, cooldowns.
+- Describes the observable result from the outside (HTTP status and body shape, screen state, stored record fields, emitted event, sent message), not the implementation ("uses a mutex").
+- Is independently testable — one behaviour per criterion; split compound criteria.
+
+Minimum coverage per story (skip a category only when it truly cannot apply, and say why in one word, e.g. "AC-5 permissions: n/a — public screen"):
+
+| Category | Must answer |
+|---|---|
+| Happy path | The main success case with concrete data |
+| Validation / negative | Empty, malformed, boundary, duplicate input → which copy line, which field, no state change |
+| Failure / degraded | Dependency down, timeout, offline mid-action → what the user sees, what is retried, what is persisted |
+| State edges | Empty state, single item, maximum, pagination boundary, concurrent modification, idempotent repeat |
+| Permissions / auth | Wrong role, expired session mid-action, unauthenticated deep link |
+| Copy | Which CP lines appear in which states (this is how UX writing becomes testable) |
+| Accessibility (UI stories) | Focus order, labels, contrast, touch target size, screen-reader text — as concrete checks |
+| Observability (backend stories) | Which log events (no PII), metrics, error-tracking events are emitted |
+| Data integrity | What is stored, with which fields, audit trail, soft-delete behaviour |
+| Locale (when relevant) | RTL rendering, digits, dates in Jalali with correct month lengths, currency label |
+
+## 4. Edge cases, tests, tasks, DoD
+
+**Edge cases.** Walk `edge-case-catalog.md` category by category for the story and list every applicable item as either a reference to a global `EC-*` (with any story-specific expected behaviour) or a new story-level item. If the list is empty, the story is trivial or you skipped the walk.
+
+**Tests.** For each AC name the test(s) that prove it, at the right level:
+
+```
+**Tests**
+- Unit: `<module>.<test_name>` — covers AC-2, AC-4 (pure validation and state logic)
+- Integration: `<test file>::<test_name>` — covers AC-1, AC-3, AC-8 (through the real DB/test double for the gateway)
+- E2E (only if this story is on a critical path listed in section 14): `<spec name>` — covers AC-1, AC-6
+- Manual (only what cannot be automated, e.g., real SMS delivery): step list, expected observation, who does it
+- Fixtures/data needed: …
+- Run: `<check command>` must be green; the new tests must fail before the implementation and pass after.
+```
+
+**Tasks.** Ordered, small, each naming the indicative files/modules and the test it makes pass:
+
+```
+**Tasks**
+- E03-S02-T1 Add `phone` validation to `ENT-User` schema + migration — proves AC-2
+- E03-S02-T2 Implement `POST /auth/otp/request` (API-04) with rate limit 5/10min — proves AC-1, AC-3
+- E03-S02-T3 Wire SCR-03 form states and copy CP-SCR03-1…6 — proves AC-6, AC-7
+- E03-S02-T4 Emit `auth.otp.requested` log event without phone number — proves AC-8
+```
+
+**Story DoD** (default; extend per story):
+- All ACs have passing automated tests (or a completed manual step recorded in PROGRESS.md with evidence).
+- Each of those tests was seen **failing before** the implementation and passing after; PROGRESS.md records that.
+- `check` is green on the whole repo — no gate rule weakened, skipped or ignored to get there (if one was, a DR says why).
+- The **review checklist** (blueprint section 14.4) has been applied end to end and every item answered; unanswered items are fixed, not batched.
+- Copy lines used match the copy table exactly (no improvised strings).
+- Edge cases listed are each covered by a test or explicitly marked "accepted risk" in PROGRESS.md with reason.
+- Every external symbol used traces to a pinned dependency in the stack table — no invented APIs, no unpinned imports.
+- No new dependency without a DR entry.
+- No logic duplicated from elsewhere in the repo (the session searched before writing).
+- Commit(s) reference the story ID.
+- PROGRESS.md updated: story DONE, AC evidence lines, and any deviation from the blueprint.
+
+## 5. Epic template
+
+```
+## Epic 03 — <Title>
+
+**Goal** (one line, outcome-oriented, in the user's language then English if bilingual)
+**Personas served** P1, P2
+**Depends on** E00, E01 (what specifically: tables, endpoints, components)
+**Preconditions for the session** — PROGRESS.md shows E00–E02 DONE; `check` green on clean `main`; env vars X, Y present; `[VERIFY-AT-BUILD]` items for this epic re-checked: INT-sms availability, …
+**Scope** — In: stories below. Out: … (where handled)
+**Flows and screens implemented** F-02, F-03; SCR-03, SCR-04
+**Data and API touched** ENT-User (new fields …), API-04, API-05
+**Risks specific to this epic** R-02 …
+**Stories**
+### E03-S01 — …
+### E03-S02 — …
+**Epic-level tests** — the integration/e2e run that proves the epic as a whole (the flow end to end), plus regression: all previous epics' tests still green.
+**Definition of Done**
+- All stories DONE with evidence in PROGRESS.md
+- Epic-level flow test(s) green; full `check` green; CI green on the merged branch
+- Deployed to staging and smoke-verified (list the 3 manual checks if UI)
+- PROGRESS.md: epic DONE, deviations recorded, next epic's preconditions confirmed
+- DECISIONS.md updated for any decision taken during the session
+- Blueprint Amendments log updated if any AC/scope changed
+**Session handoff checklist** — the ≤20-line summary the agent prints before the user terminates (format in session-protocol.md §5).
+```
+
+## 6. Epic 00 — Foundation: mandatory contents
+
+Epic 00 is where "no room for error" is manufactured. Its stories (builder persona) cover:
+
+1. Repository init with the chosen layout; language/runtime version pinned (version file); package manager lockfile committed.
+2. Formatter, linter (strict), typechecker (strict flags), test runner configured; `check` command that runs them all and fails on any warning class you decide is an error; documented expected runtime. Also in `check` from day one: coverage floor, dependency/vulnerability audit, secret scanning, and schema-drift check — every gate component listed in blueprint section 14.2 that applies.
+2b. **Module skeleton and fitness functions**: the empty modules from the architecture's module map, plus the architecture tests that enforce the dependency-direction and ownership rules, failing the build on violation. These exist *before* there is any feature code to violate them; retrofitting boundaries after three epics does not work.
+2c. **The review checklist** (blueprint section 14.4) committed to the repo at a fixed path and referenced from `AGENTS.md`/`CLAUDE.md`, so it is in every future session's context.
+3. Test layout with one example unit test, one integration test against a real test database (containerised or local), one e2e smoke test; factories/fixtures pattern established. Mutation testing configured on the critical modules if a maintained tool exists for the stack (blueprint section 14.3 says which, or says none exists).
+4. CI running `check` on every push and blocking merge on red; branch protection configured so the gate cannot be bypassed.
+5. `docs/BLUEPRINT.md` (this document), `docs/PROGRESS.md`, `docs/DECISIONS.md`, `AGENTS.md` and `CLAUDE.md` created from Appendix B; `.env.example` with every variable and a one-line meaning; secrets policy.
+6. Configuration loading with validation at startup (fail fast on missing/invalid env).
+7. Logging with a structured logger, request/correlation ID, PII redaction rule; error-tracking hook (verified service or self-hosted); health endpoint.
+8. Database with migration tooling; first migration; seed script for fixtures.
+9. Hello-world vertical slice: one screen or endpoint through all layers, with i18n/RTL plumbing if the product needs it (locale, direction, font loading, digit formatting, calendar utility), proving the whole stack end to end.
+10. Deployment skeleton to staging (build, run, migrate, health check), with the documented rollback step.
+11. Coding conventions file the agent reads every session (error handling, naming, module boundaries, "no `any`/no untyped", commit format).
+
+Every one of these has ACs and tests like any other story. Epic 00 is typically the largest epic; it can be split into E00a/E00b only if sessions are short.
+
+## 7. Sizing
+
+- Story: 0.5–3 hours of agent work including tests. Larger → split by AC groups.
+- Epic: 3–7 stories for a half-day session; 2–4 for short sessions. Never more than one flow's worth of new surface area per epic.
+- Sprint: 1–3 epics ending in a releasable or demonstrable increment.
+- Mark sizes S/M/L in the epic order table; the user picks session length accordingly.
+
+## 8. Worked example (good)
+
+```
+### E02-S01 — Request a one-time code by phone number
+
+**Story** — As **P1 (Restaurant owner, Tehran, mid-range Android, busy)**, I want to enter my mobile number and receive a one-time code, so that I can sign in without remembering a password.
+**Context** — Phone-first login is the norm in the benchmarked local products (S-09, S-11) and P1 rarely uses email. Implements F-01 steps 1–3 on SCR-03. SMS delivery through INT-sms (sandbox available [VERIFIED — S-16, 2026-09-05] [VERIFY-AT-BUILD]).
+**Scope** — In: number entry, validation, code request, resend cooldown, rate limiting, delivery via provider sandbox in tests. Out: code verification (E02-S02), account creation on first login (E02-S03).
+**Acceptance Criteria**
+- AC-1 (happy) Given SCR-03 is open and no code was requested for `09123456789` in the last 60 s, When the user submits `09123456789`, Then `POST /auth/otp/request` (API-04) returns 200 `{ "expires_in": 120, "resend_after": 60 }`, a 6-digit code is stored hashed with a 120 s expiry, the provider is called once with template `otp_v1`, and SCR-03 shows state "code-sent" with CP-SCR03-4.
+- AC-2 (validation) Given SCR-03, When the user submits `0912345678` (10 digits) or `+989123456789` or `۰۹۱۲۳۴۵۶۷۸۹` (Persian digits), Then Persian digits are normalised to Latin before validation, `+98` is normalised to `0`, a 10-digit input is rejected inline with CP-SCR03-2 under the field, no request is sent, and the submit button stays disabled until 11 valid digits are present.
+- AC-3 (failure) Given the provider returns HTTP 5xx or times out after 5 s, When the user submits a valid number, Then API-04 returns 503 `{ "error": "sms_unavailable" }`, no code is stored, SCR-03 shows CP-SCR03-6 with a retry action, and the error is reported to error tracking with the correlation ID and without the phone number.
+- AC-4 (state edge — rate limit) Given 5 requests for the same number in the last 10 minutes, When a 6th is submitted, Then API-04 returns 429 with `retry_after` seconds, the provider is not called, and SCR-03 shows CP-SCR03-7 including the remaining minutes in Persian digits.
+- AC-5 (permissions) n/a — public endpoint; AC-4 is the abuse control.
+- AC-6 (copy) Given each state of SCR-03 (idle, invalid, sending, code-sent, resend-cooldown, sms-unavailable, rate-limited), Then the exact copy from CP-SCR03-1…7 is shown, digits rendered as Persian digits, layout RTL.
+- AC-7 (accessibility) Given a screen reader, When focus enters the field, Then its label (CP-SCR03-1) is announced; inline errors are announced via a live region; the field has `inputmode="numeric"`; the primary button is ≥ 44×44 px.
+- AC-8 (observability) Given any outcome, Then one structured log event `auth.otp.requested` with `{ outcome, correlation_id, provider_latency_ms }` and no phone number is emitted; a counter `otp_requests_total{outcome}` increments.
+**Edge cases** — EC-INPUT-03 (invisible characters pasted → stripped before validation), EC-INPUT-07 (mixed Persian/Latin digits → normalised), EC-AUTH-02 (double tap submit → single request, button disabled while pending), EC-NET-04 (offline at submit → CP-SCR03-6 without provider call), EC-MSG-01 (provider accepts but never delivers → covered by resend after 60 s, no more than 3 resends per code), EC-IR-02 (number with operator prefix not in the known list → still accepted; operator list is not a validation rule).
+**Tests**
+- Unit: `auth/phone.test` — normalisePhone (Persian digits, +98, spaces, ZWNJ, invisible chars), isValidIranMobile — covers AC-2, EC-INPUT-03/07
+- Unit: `auth/otp_rate_limit.test` — 5-per-10-min window, retry_after computation — covers AC-4
+- Integration: `api/auth_otp_request.test` — success path with provider fake; provider 5xx/timeout; rate limit; idempotent double submit — covers AC-1, AC-3, AC-4, AC-8, EC-AUTH-02
+- E2E: `e2e/login.spec` step "request code" — covers AC-1, AC-6 (critical path #1 in section 14)
+- Manual: send one real code in staging to a test number; confirm delivery within 30 s; recorded in PROGRESS.md
+- Run: `make check` green; new tests red before implementation.
+**Tasks**
+- E02-S01-T1 `normalisePhone` + `isValidIranMobile` in `auth/phone` with unit tests
+- E02-S01-T2 OTP store: hashed code, expiry, attempt counter (ENT-OtpChallenge) + migration
+- E02-S01-T3 Rate limiter keyed by phone (5/10 min) using the shared store
+- E02-S01-T4 API-04 handler with provider client (INT-sms) and 5 s timeout; 503/429 mapping
+- E02-S01-T5 SCR-03 states and copy CP-SCR03-1…7, RTL, Persian digits, live region
+- E02-S01-T6 Log event + counter; error-tracking capture without PII
+**Story DoD** — default DoD + manual staging delivery check recorded.
+```
+
+## 9. Anti-example (what not to write, and why)
+
+```
+As a user I want to log in with my phone so that it's easy.
+AC: user enters phone, gets SMS, sees success message. Errors are handled properly.
+```
+
+Defects: no persona (voice and constraints unknown); "easy" is untestable; no number format, so the agent invents one; "success message" and "handled properly" leave copy and failure behaviour to the agent; no rate limit, so abuse is unspecified; no tests, so "done" is an opinion; no copy IDs, so the UX writing work is discarded at build time. Every one of these becomes a silent decision in a fresh session.

package/bundled-skills/idea-to-blueprint/references/ux-writing-guide.md

@@ -0,0 +1,128 @@
+# UX writing guide
+
+Contents: 1 Principles · 2 Voice from personas · 3 Message formulas · 4 Component copy states · 5 Copy table rules · 6 Terminology · 7 Persian pack · 8 Channel templates (SMS/email/push/bot) · 9 Review checklist
+
+## 1. Principles (outcome-driven)
+
+Copy exists to move a specific persona to a specific outcome with the least reading. Concretely:
+
+- **Say the outcome, not the mechanism.** "سفارش شما ثبت شد و تا ۲۰ دقیقه‌ی دیگر می‌رسد" beats "Order created successfully". The user wants to know what happens to them next.
+- **One idea per line.** Titles ≤ 6 words, body ≤ 2 short sentences, buttons 1–3 words.
+- **Verb-first CTAs that name the result**: «پرداخت ۴۵۰٬۰۰۰ تومان», «ارسال کد», «ذخیره‌ی تغییرات» — never «تأیید», «اوکی», «ادامه» alone when a specific verb exists.
+- **Errors: what happened + why (if useful) + what to do now.** Never blame; never expose internals; always leave an action. "کد وارد‌شده درست نیست. دوباره تلاش کنید یا کد جدید بگیرید." not "Invalid OTP".
+- **Confirmations describe the consequence**, not "are you sure?": «این آیتم برای مشتری‌ها هم حذف می‌شود. حذف کنم؟» with buttons «حذف» / «نگه‌داشتن».
+- **Empty states orient and offer one action**: what this place is for, what will appear here, one button that creates the first item.
+- **Success confirms the outcome and points to the next step**; don't celebrate ("🎉 Awesome!!!") — inform.
+- **Loading says what is happening** when it takes > 1 s ("در حال بررسی پرداخت…"); use skeletons for < 1 s.
+- **Reversible beats confirm**: prefer "done + Undo" for reversible actions; reserve dialogs for irreversible or costly ones.
+- **Consistency over cleverness**: one word per concept across the product (glossary), same sentence shape for the same kind of message.
+- **Numbers, dates, money, phone numbers are formatted by rule**, never ad hoc (see §7 for Persian).
+- **No filler**: «کاربر گرامی», "Please note that", "Oops!", "Successfully" add reading and no meaning.
+- **Write for the stressed reader**: the person seeing an error is already frustrated; the person paying is anxious. Short, calm, concrete.
+
+## 2. Voice from personas
+
+Derive voice per persona from the persona sheet, then write a tone matrix.
+
+| Persona trait (from section 5) | Copy consequence |
+|---|---|
+| Low tech comfort / reads slowly | Shorter lines, plain words, one action per screen, explicit next steps, no icons without labels |
+| Expert / high frequency | Terse labels, keyboard hints, fewer confirmations, dense tables allowed |
+| Under time pressure (shop floor, driving) | Front-load the key fact, large targets, minimal choices |
+| Anxious about money or data | Show amounts and consequences before the action, explicit "nothing was charged" on failure, receipts |
+| Formal expectation (B2B, older, official) | Formal register («شما», formal verbs), no jokes, no emoji |
+| Casual expectation (young consumers, community) | Warmer, lighter, still respectful; emoji only if the design direction allows and never in errors |
+| Screen-reader user | Every icon has text, every state change is announced, no meaning by colour alone |
+
+Tone matrix (write it in the blueprint):
+
+```
+| Moment | P1 <name> | P2 <name> | P3 <name> |
+| First run | … | … | … |
+| Core task success | … | … | … |
+| Validation error | … | … | … |
+| System failure | … | … | … |
+| Money moments | … | … | … |
+| Destructive action | … | … | … |
+| Notifications | … | … | … |
+```
+
+## 3. Message formulas
+
+- **Validation error (inline):** `<what is wrong in the field> + <how to fix>` — "شماره باید ۱۱ رقم و با ۰۹ شروع شود."
+- **Operation failure:** `<what didn't happen> + <state of their data/money> + <action>` — "پرداخت انجام نشد. مبلغی از حساب شما کم نشده است. دوباره تلاش کنید."
+- **Empty state:** `<what lives here> + <what to do first>` — "هنوز سفارشی ندارید. اولین آیتم منو را اضافه کنید تا مشتری‌ها بتوانند سفارش بدهند." + button «افزودن آیتم».
+- **Success:** `<outcome> + <next>` — "منو منتشر شد. مشتری‌ها با اسکن QR همین الان می‌بینند."
+- **Destructive confirm:** `<consequence, incl. who else is affected> + <question>` + buttons `<verb>` / `<keep>`.
+- **Permission/limit:** `<limit reached> + <how to proceed>` — "امروز ۵ بار کد گرفته‌اید. ۱۰ دقیقه‌ی دیگر دوباره تلاش کنید."
+- **Offline:** `<you're offline> + <what is saved> + <what happens when back>`.
+- **Session expired:** `<what happened> + <nothing lost> + <action>`.
+
+## 4. Component copy states
+
+Every component that shows text has these states specified when applicable: label, placeholder (an example, not a repeat of the label), helper text, inline error(s) — one per failure reason, disabled reason (tooltip or helper), loading, success, empty, counter/limit text. A button has: default, loading («در حال ارسال…»), done, disabled-with-reason. A list has: loading, empty (first use), empty (filtered — "no results for …"), error with retry, end-of-list.
+
+## 5. Copy table rules
+
+- One table per screen (`SCR-nn`) and one per channel (SMS, email, push, in-app notifications, bot). Every state in §4 for every component on the screen has a row — "error message" as a single row is not acceptable; enumerate variants.
+- Columns: `ID | Element | Copy (product language) | English gloss | Persona intent | State / variant | Max length | Notes`.
+- IDs `CP-SCRnn-k` are referenced from acceptance criteria; changing copy later means changing the row, not the ID.
+- Max length is a number derived from the layout (button width, SMS segment, push title limit); the AC tests truncation against it.
+- Persona intent is a half-line: what the reader is trying to do at that moment.
+- Variables in braces `{amount}`, `{minutes}`, with their formatting rule referenced (e.g., "{amount}: Toman, Persian digits, thousands separator ٬").
+- Pluralisation and gender: specify. Persian has no grammatical gender; English glosses avoid gendered pronouns.
+- Never leave copy to the build session; an improvised string in code is a defect (Story DoD).
+
+## 6. Terminology
+
+Build the product's UI glossary in section 21: one Persian term and one English term per concept, with rejected synonyms listed ("سفارش" — not "درخواست"; "منو" — not "فهرست"). Use loanwords that Persian users actually use in interfaces when they are dominant in the category (benchmark shows), otherwise Persian equivalents; decide once. The same applies to any product language.
+
+## 7. Persian pack (users in Iran or Persian-speaking)
+
+Typography and characters
+- Use Persian letters ی (U+06CC) and ک (U+06A9), never Arabic ي (U+064A) and ك (U+0643). Normalise user input too (edge case EC-INPUT-08).
+- Use ZWNJ (نیم‌فاصله, U+200C) correctly: «می‌روم», «کتاب‌ها», «سفارش‌های», «تأیید‌شده» — never a full space or nothing. Search must treat ZWNJ, space and none as equivalent.
+- Persian punctuation: «،» «؛» «؟» and «» for quotes; use «٬» (U+066C) as thousands separator and «٫» (U+066B) as decimal separator when showing Persian digits; a regular space before units («۴۵۰٬۰۰۰ تومان»).
+- Digits: decide once (DR) — Persian digits (۰–۹) in all human-facing text is the common expectation in the benchmarked category; Latin digits in codes users must type into other systems (tracking codes, OTP if typed cross-device?), IDs, and developer surfaces. Never mix within one number. Inputs accept both and normalise.
+- Mixed-direction text: wrap Latin tokens (emails, URLs, codes, brand names) in bidi isolation so punctuation does not jump; test with a string containing Persian + English + digits (EC-L10N-02).
+- Font: a well-maintained open Persian web font with Latin glyph coverage, self-hosted (foreign font CDNs may be blocked or slow from Iran — verify), with a fallback stack; line-height slightly larger than Latin defaults; avoid italics (Persian has none); use weight for emphasis.
+
+Register and tone
+- Default to «شما» and polite plural verb forms for all personas unless the persona sheet says casual («تو») is expected by the brand and the segment — and then use it consistently.
+- Plain, contemporary Persian; avoid heavy Arabic-derived formal vocabulary when a common Persian word exists («لطفاً دوباره تلاش کنید» not «مجدداً اقدام فرمایید»).
+- Drop honorific filler («کاربر گرامی»، «با تشکر از شکیبایی شما») unless a formal B2B persona expects it.
+- No exclamation stacking, no emoji in errors or money moments.
+
+Formats
+- Dates: Jalali in UI («۱۴۰۵/۰۶/۱۴» or «۱۴ شهریور ۱۴۰۵» — decide once), stored as UTC timestamps; Gregorian only where a foreign counterpart needs it. Relative dates («امروز»، «دیروز»، «۳ روز پیش») follow one rule. Month lengths (31/30/29–30 in Esfand) and leap years handled by a verified library, tested for the current and next year.
+- Times: 24-hour, Asia/Tehran, DST policy verified; show timezone only for cross-country cases.
+- Money: decide Toman vs Rial once (DR) and always label the unit; thousands separator; no decimals; for large sums the category may use «هزار تومان» shorthand — decide and be consistent.
+- Phone: display as «۰۹۱۲ ۳۴۵ ۶۷۸۹» (grouping decided once), accept «+98…», «0098…», Persian digits, spaces, dashes; store E.164.
+- Addresses: province, city, street, plaque («پلاک»), unit («واحد»), postal code (10 digits) — field order and labels as the category norm.
+- National ID (کد ملی): 10 digits, check-digit validated if collected; show why it is needed.
+- Week: Saturday is the first weekday; Friday is the weekend day (Thursday partial in many segments) — pickers, "this week" and scheduling copy follow this.
+
+Messaging realities
+- SMS in Persian is Unicode-encoded: segment length is far shorter than Latin SMS (verify provider's limits); OTP templates fit in one segment and lead with the code; include the app name; avoid links unless required.
+- Telegram is widely used under filtering; domestic messengers vary by segment — the channel choice comes from research, and copy is written per channel.
+
+## 8. Channel templates
+
+Provide rows for each channel with the same table format:
+
+- **SMS**: OTP (code first, app name, expiry), order/status updates (what changed + next), reminders; max length = one segment.
+- **Email** (if used): subject ≤ 50 chars, preheader, body, single CTA, plain-text variant.
+- **Push/in-app notification**: title ≤ 40 chars, body ≤ 90 chars, deep link target `SCR-nn`, quiet-hours rule.
+- **Bot messages** (Telegram/Bale/…): message text, keyboard button labels, fallback for unknown input, /start onboarding sequence.
+
+## 9. Review checklist for every copy table
+
+- Every state of every component on the screen has a row.
+- No adjectives about the system's own quality ("easily", "quickly", "seamlessly").
+- Every error names an action.
+- Every destructive confirm names the consequence and uses verb buttons.
+- Digits, dates, money, phone follow the format rules; variables carry a formatting reference.
+- Register consistent with the tone matrix for the persona(s) on this screen.
+- Max length set and realistic for the layout/channel.
+- Terms match the glossary; no synonyms.
+- English gloss present so the coding agent understands intent.