docs: establish integrated project memory

.project-docs/00-brief/project-positioning.md

@@ -0,0 +1,37 @@
+# Project Positioning
+
+## One-line Positioning
+
+XQKqueue is a lightweight multi-project queueing and call-management system for scenic-area operations.
+
+## Primary Goal
+
+The project exists to let visitors take and track tickets, let staff call contiguous queue batches safely, let administrators operate and audit projects, and show public queue status on browser and Android large-screen clients.
+
+## Target Users / Consumers
+
+- Scenic-area visitors taking or checking tickets.
+- Front-line staff issuing tickets and calling queue batches.
+- Administrators configuring projects, users, history, and operational status.
+- On-site public displays consuming privacy-safe queue snapshots.
+
+## Non-goals
+
+- The Android display is not a general-purpose browser or an administrative client.
+- Public display and visitor APIs must not expose private ticket fields.
+- Client-side button state, polling, or audio is not an authority for queue writes.
+
+## Core Constraints
+
+- The Go service and PostgreSQL database are the sole write authority.
+- Ticket creation and call-next correctness is enforced at the service transaction boundary; retryable write endpoints use their documented idempotency and revision contracts.
+- Public screens must tolerate intermittent connectivity and disclose only allowlisted data.
+- The dedicated Android display must work without System WebView or a device TTS engine.
+
+## Quality Bar
+
+A good solution preserves FIFO and privacy invariants under concurrency, has observable loading/offline/error behavior, remains usable on the target 1920x1080 landscape display, and is covered by server, web, Android, and device-level acceptance checks proportionate to the change.
+
+## Last Reviewed
+
+2026-08-12

.project-docs/00-brief/success-criteria.md

@@ -0,0 +1,29 @@
+# Success Criteria
+
+## Project Success
+
+- Visitors can obtain and privately track valid tickets without duplicate or privacy regressions.
+- Staff can call the correct contiguous FIFO batch by ticket count or people count.
+- Administrators can configure projects and inspect operational/history data.
+- Browser and Android public displays show current batches and forecasts without exposing personal data.
+- The dedicated Android project screen announces each new number or range three times without relying on WebView or system TTS; the overview remains silent.
+
+## Task Completion Standard
+
+- Requested behavior is implemented at the correct authority boundary and regression-tested.
+- Relevant server, web, Android, packaging, and documentation checks pass.
+- User-visible binaries and their documented checksums match the verified build.
+- An independent read-only review reports no unresolved P0/P1 finding.
+- The task record and project documentation gate are complete before handoff.
+
+## Quality Checks
+
+- Server: `cd server && go test ./...` and, for database behavior, `scripts/test-postgres.sh` or `make smoke-real`.
+- Web: `pnpm --dir web test:run`, `pnpm --dir web typecheck`, and `pnpm --dir web build`.
+- Android: `android\\gradlew.bat clean testDebugUnitTest lintDebug assembleDebug` with `ANDROID_HOME` configured.
+- APK: verify version metadata, v1/v2 signature, embedded resources, and SHA-256 against `deliverables/android/SHA256SUMS.txt`.
+- Hardware-dependent display and audio changes require acceptance on the target television; host tests are necessary but not sufficient.
+
+## Last Reviewed
+
+2026-08-12

.project-docs/05-agent-entry/concurrent-task-gate.md

@@ -0,0 +1,30 @@
+# Concurrent Task Gate
+
+Complete this gate before the Planning Gate.
+
+## Invariants
+
+- One active task owns one worktree.
+- Concurrent tasks use different branches and worktrees.
+- Never stash, reset, move, delete, or adopt unknown work automatically.
+- Feature tasks write only their own task record and uniquely named supporting records.
+- Keep the active task record present until ownership is released.
+- Treat `start`, `touch`, `complete`, and `release` as serialized registry transactions; lock timeout or malformed registry state blocks the gate.
+- Feature-task write boundaries in this gate supersede legacy instructions to update shared or canonical project documents.
+
+## Required Output
+
+- Task ID:
+- Mode: Feature | Integration
+- Branch:
+- Worktree:
+- Base commit:
+- Ownership result: Claimed | Resumed | Isolated | Blocked
+- Other active local tasks:
+
+## Block Conditions
+
+- The worktree belongs to another active task and isolation did not succeed.
+- An unowned worktree contains staged, unstaged, or untracked changes.
+- No reliable committed base was selected for a new worktree.
+- The runtime cannot keep later Git and file operations rooted in the isolated worktree.

.project-docs/05-agent-entry/context-checklist.md

@@ -0,0 +1,15 @@
+# Context Checklist
+
+Before planning, confirm:
+
+- I know the task ID, mode, branch, worktree, base commit, and ownership result.
+- I read the active task record and know its scope.
+- I know what this project is and what it is not.
+- I treat current-state as the last integrated snapshot rather than live concurrent state.
+- I checked active decisions and the architecture overview.
+- I identified task-specific docs that need deeper reading.
+- I inspected other local task records through `task_context.py status --json`.
+- I assessed code overlap separately from semantic or decision conflict.
+- I reported missing peer records as unknown coordination state.
+- I can name unknown, stale, or conflicting information.
+- I know which updates remain task-scoped and which require Integration Gate.

.project-docs/05-agent-entry/integration-gate.md

@@ -0,0 +1,15 @@
+# Integration Gate
+
+Use this gate to promote completed task facts into canonical project memory.
+
+## Requirements
+
+- Run in an exclusively owned integration worktree.
+- Hold the repository integration lock.
+- Verify the task commits being integrated are present.
+- Review source task records, task-prefixed supporting records, promotion candidates, and semantic conflicts in read-only mode.
+- Write integration notes only to the integration task's own task record or `{task_id}__<slug>.md` supporting records.
+- Ask before changing architecture direction, product behavior, or accepted decisions.
+- Record source task or merge commits under `Integrated Through` in `current-state.md`.
+
+Do not resolve meaningful document conflicts with `ours`, `theirs`, or union merge rules.

.project-docs/05-agent-entry/memory-index.md

@@ -0,0 +1,23 @@
+# Memory Index
+
+Use this as the high-density entry point after the Concurrent Task Gate establishes task identity and worktree ownership.
+
+## Startup Set
+
+- Active task: `.project-docs/30-worklog/tasks/{task_id}.md`
+- Project identity: `.project-docs/00-brief/project-positioning.md`
+- Integrated state: `.project-docs/30-worklog/current-state.md`
+- Decision list: `.project-docs/10-decisions/decision-index.md`
+- System shape: `.project-docs/20-architecture/system-overview.md`
+
+## Recall Pointers
+
+- Evidence-heavy bugs, experiments, investigations: `.project-docs/50-evidence/evidence-index.md`
+- Workflow lessons and repeated agent mistakes: `.project-docs/60-reflection/reflection-index.md`
+- Pending promises, loops, timed follow-ups: `.project-docs/80-commitments/commitments.md`
+- Integrated stale items: `.project-docs/90-maintenance/stale-items.md`
+- Task-scoped conflicts: `.project-docs/90-maintenance/conflicts/{task_id}__<slug>.md`
+
+## Loading Rule
+
+Keep this file short. Add shared pointers only during Integration Gate. Feature tasks keep their working context and promotion candidates in their own task record.

.project-docs/05-agent-entry/planning-gate.md

@@ -0,0 +1,66 @@
+# Planning Gate
+
+A coding agent must complete this gate after the Concurrent Task Gate and before writing an implementation plan.
+
+## Peer Scope Check
+
+Run `task_context.py status --json`. For each other owner, read only the peer task record at `Path(owner.worktree) / owner.task_record`. Use its `Scope`, `Intent And Constraints`, and `Promotion Candidates` sections to assess overlap.
+
+Do not inspect or modify arbitrary uncommitted files in another task's worktree. Report a missing or unreadable peer record as unknown coordination state; do not silently treat it as no overlap. Code-path overlap alone is a warning. Block when semantic decisions conflict or unresolved overlap could change the plan.
+
+## Required Output
+
+```md
+## Project Context Loaded
+
+Task context:
+- Task ID:
+- Mode:
+- Branch:
+- Worktree:
+- Base commit:
+- Other active local tasks:
+- Overlap or semantic-conflict assessment:
+
+Read:
+- {file path}
+
+Relevant understanding:
+- Project goal:
+- Current integrated focus:
+- Active task scope:
+- Active constraints:
+- Decisions affecting this task:
+- Evidence, reflections, or commitments affecting this task:
+- Files or modules likely involved:
+- Unknowns, stale docs, or conflicts:
+
+Gate result:
+- Passed or Blocked
+```
+
+## Pass Criteria
+
+The gate passes only when:
+
+- task identity and worktree ownership are resolved
+- the active task record exists and matches the owner task ID
+- required documents were read
+- task-relevant decisions were checked
+- relevant evidence, reflection, and commitment indexes were checked when applicable
+- other active local task scopes were assessed
+- stale, unknown, or conflicting context was called out
+- the plan respects project positioning and constraints
+
+## Block Criteria
+
+Block planning when:
+
+- worktree ownership is unresolved
+- an unowned worktree is dirty and has not been explicitly adopted by a human
+- required worktree isolation failed or later operations cannot remain rooted there
+- required documents are missing or a concurrency upgrade is incomplete
+- current integrated state conflicts with the user request
+- an existing decision appears to be violated
+- semantic decisions conflict across active tasks
+- the task changes project positioning or architecture without human confirmation

.project-docs/05-agent-entry/read-before-coding.md

@@ -0,0 +1,7 @@
+# Read Before Coding
+
+Before editing code, verify that the implementation plan passed both the Concurrent Task Gate and Planning Gate. Confirm the task ID, branch, worktree, owner, and active task record still match.
+
+If the plan is stale, ownership changed, or new peer scope affects the plan, return to `read-before-planning.md`. Keep every later file and Git operation rooted in the owned worktree.
+
+Read the source files directly related to the target modules. Record feature progress, discovered constraints, verification, and promotion candidates in `.project-docs/30-worklog/tasks/{task_id}.md`; leave canonical project memory to Integration Gate.

.project-docs/05-agent-entry/read-before-planning.md

@@ -0,0 +1,24 @@
+# Read Before Planning
+
+Before writing any coding plan, follow this order:
+
+1. Run the Concurrent Task Gate.
+2. Read memory-index.md.
+3. Read the active task record at `.project-docs/30-worklog/tasks/{task_id}.md`.
+4. Read project-positioning.md.
+5. Read current-state.md as the integrated snapshot.
+6. Read decision-index.md and system-overview.md.
+7. Inspect other locally active task scopes.
+
+Then read additional files when relevant:
+
+- Architecture or refactor task: `.project-docs/20-architecture/module-map.md` and `.project-docs/20-architecture/data-flow.md`
+- Product or behavior task: `.project-docs/40-domain/business-rules.md` and `.project-docs/00-brief/success-criteria.md`
+- Ambiguous terms: `.project-docs/40-domain/glossary.md`
+- Decision-sensitive task: referenced accepted ADRs in `.project-docs/10-decisions/`
+- Evidence-heavy bug, investigation, or experiment: `.project-docs/50-evidence/evidence-index.md`
+- Repeated workflow issue, skipped gate, or skill/script candidate: `.project-docs/60-reflection/reflection-index.md`
+- Follow-up, loop, timed check, or restart-point task: `.project-docs/80-commitments/commitments.md`
+- Suspicious integrated context: `.project-docs/90-maintenance/stale-items.md`
+
+Treat shared files as the last integrated snapshot, not as live state from concurrent feature tasks. Do not write a plan until both the Concurrent Task Gate and Planning Gate pass.

.project-docs/10-decisions/adr-001-native-android-display.md

@@ -0,0 +1,37 @@
+# ADR-001: Native Android large-screen application
+
+## Status
+
+Accepted
+
+## Date
+
+2026-08-12
+
+## Context
+
+The browser display worked on general computers but remained unreliable on the target Android television hardware because WebView and browser media behavior varied by vendor. The user approved replacing the APK's WebView presentation with native Android pages while retaining the service's public display APIs.
+
+## Decision
+
+The dedicated Android app renders its overview and project screens with Android Views and directly polls the public display API. It does not load the web application. The overview polls every five seconds and cannot create announcement state. A project screen polls its snapshot every three seconds and uses that same response for both UI and announcement detection.
+
+## Rationale
+
+This removes System WebView from the appliance runtime path, makes remote-control focus and lifecycle behavior explicit, and keeps the Go service as the authoritative source without duplicating queue rules in the app.
+
+## Consequences
+
+- Browser and Android presentation code are separate and must both be maintained.
+- The Android app depends on the public overview and snapshot DTOs.
+- Hardware-specific layout, audio routing, orientation, and lifecycle behavior still require target-device acceptance.
+
+## Supersedes
+
+- The previous Android WebView wrapper design.
+
+## Related
+
+- `android/app/src/main/java/cn/nianxx/queue/display/MainActivity.java`
+- `android/app/src/main/java/cn/nianxx/queue/display/DisplayApiClient.java`
+- `.project-docs/50-evidence/topics/20260811-native-display-f2456ea9__public-display-api.md`

.project-docs/10-decisions/adr-002-embedded-audio-announcements.md

@@ -0,0 +1,39 @@
+# ADR-002: Embedded audio announcements
+
+## Status
+
+Accepted
+
+## Date
+
+2026-08-12
+
+## Context
+
+System speech synthesis was absent or inconsistent on the target display devices. A first embedded eSpeak asset set produced unintelligible Mandarin. The repository already contained a prior Mandarin queue-announcement WAV set that the user confirmed was the intended project audio.
+
+## Decision
+
+Package the project’s legacy Mandarin prompt, digit, range, and suffix fragments in the APK. Parse and validate PCM WAV assets, compose the number or range locally, and stream each announcement three times using `AudioTrack` with media usage and transient audio focus. Do not announce the project name. Do not depend on system TTS.
+
+## Rationale
+
+Deterministic bundled PCM avoids browser autoplay and installed-voice dependencies while allowing the server to continue sending ordinary snapshot text and batch data.
+
+## Consequences
+
+- The APK contains and tests exactly 13 WAV resources.
+- The player must own FIFO ordering, cancellation, focus, and native track lifecycle safely.
+- The original generator, speaker, and separate redistribution license for the historical WAVs are not recorded; confirm ownership before distribution outside the project's authorized deployment scope.
+- Audio routing and intelligibility remain target-device acceptance items.
+
+## Supersedes
+
+- Android system TTS announcements.
+- The rejected eSpeak-generated Mandarin assets.
+
+## Related
+
+- `android/app/src/main/java/cn/nianxx/queue/display/QueueAnnouncementPlayer.java`
+- `android/app/src/main/java/cn/nianxx/queue/display/EmbeddedWavComposer.java`
+- `.project-docs/50-evidence/topics/20260811-native-display-f2456ea9__embedded-audio-assets.md`

.project-docs/10-decisions/adr-template.md

@@ -0,0 +1,33 @@
+# ADR-{number}: {decision title}
+
+## Status
+
+Proposed
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{context that made the decision necessary}
+
+## Decision
+
+{decision made}
+
+## Rationale
+
+{why this option was chosen}
+
+## Consequences
+
+- {positive or negative consequence}
+
+## Supersedes
+
+- {older ADR or decision, if any}
+
+## Related
+
+- {related doc or source file}

.project-docs/10-decisions/decision-index.md

@@ -0,0 +1,24 @@
+# Decision Index
+
+## Active Decisions
+
+| ID | Decision | Status | Date | Applies To | Detail |
+|---|---|---|---|---|---|
+| ADR-001 | Use native Android Views for the dedicated large-screen app | Accepted | 2026-08-12 | `android/` | [ADR](adr-001-native-android-display.md) |
+| ADR-002 | Compose embedded Mandarin WAV fragments and stream them through `AudioTrack` | Accepted | 2026-08-12 | Android project-screen announcements | [ADR](adr-002-embedded-audio-announcements.md) |
+
+## Superseded Decisions
+
+| ID | Decision | Superseded By | Date |
+|---|---|---|---|
+
+## Decision Criteria
+
+Create or update an ADR when a choice affects:
+
+- project positioning
+- architecture boundaries
+- public behavior
+- data model
+- long-term maintenance
+- user-facing workflow

.project-docs/20-architecture/data-flow.md

@@ -0,0 +1,33 @@
+# Data Flow
+
+## Primary Flows
+
+| Flow | Source | Destination | Notes |
+|---|---|---|---|
+| Take ticket | Staff/visitor client | Go service -> PostgreSQL | Validates project/session and party size, enforces idempotency/rate limits as applicable, checks same-phone WAITING duplicates, encrypts personal data, increments session revision |
+| Call next | Staff client | Go service transaction -> PostgreSQL | Locks project/session, selects a contiguous FIFO prefix by ticket or people target, writes one call batch, updates tickets/revision, emits audit/event state |
+| Browser display | Browser route | `GET /api/display/overview` or `GET /api/display/{identifier}/snapshot` | Read-only privacy-safe projections; identifier accepts project code or compatible display token |
+| Android overview | `MainActivity` | `GET /api/display/overview` every 5 seconds | Renders project cards; no announcement coordinator exists |
+| Android project display | `MainActivity` | `GET /api/display/{identifier}/snapshot` every 3 seconds | One response updates UI and announcement detector; first snapshot establishes a silent baseline |
+| Android announcement | New current call batch | `AnnouncementCoordinator` -> embedded WAV composer -> `AudioTrack` | Number/range only, FIFO, three repetitions, canceled on pause or screen change |
+
+## State Ownership
+
+- PostgreSQL owns durable queue state; the queue-session revision is the recovery/version signal.
+- The Go service owns all mutations and public projection allowlists.
+- Web and Android clients own only presentation caches, polling lifecycle, and transient UI state. The service exposes authenticated staff SSE, but the current web client does not consume it.
+- Android `AnnouncementCoordinator` tracks only the current project-screen baseline/deduplication state and resets when the screen stops.
+
+## External Interfaces
+
+- Public display: `GET /api/display/overview`, `GET /api/display/{identifier}/snapshot`.
+- Public visitor: project listing, ticket creation, and private token status. The public phone lookup endpoint is a development/operational-test path and returns 404 in `APP_ENV=production` until replaced by OTP or an external identity provider.
+- Internal lookup: the same active-ticket phone lookup is restricted to private-network requests.
+- Staff/admin: separate authenticated route groups and cookies; staff queue reads/ticket creation/call-next, admin project/user/history APIs, and an authenticated staff SSE endpoint.
+- Implemented-but-unregistered: ticket transition and missed-ticket reissue handlers exist in source but have no `Server.Handler()` routes or current web integration; they are not part of the active external interface.
+- Android deep links: `https://queue.nianxx.cn/admin/display` and `https://queue.nianxx.cn/display/{identifier}`.
+- Android audio assets: `android/app/src/main/res/raw/voice_*.wav`.
+
+## Last Updated
+
+2026-08-12

.project-docs/20-architecture/module-map.md

@@ -0,0 +1,37 @@
+# Module Map
+
+## Source Layout
+
+| Path | Responsibility | Owner Notes |
+|---|---|---|
+| `server/cmd/api` | API process entry point | Keep startup configuration and lifecycle thin |
+| `server/internal/httpapi` | HTTP routes, authentication boundaries, queue transactions, public projections, history, events, and currently unregistered ticket-transition/reissue handlers | High-risk concurrency and privacy boundary; do not assume a handler is exposed without checking `Server.Handler()` |
+| `server/internal/domain` | Pure queue selection and display-number rules | Prefer deterministic unit tests |
+| `server/internal/model` | Persistent domain structures and constants | Coordinate changes with migrations |
+| `server/internal/database` | Database connection and maintenance/purge operations | Personal-data lifecycle is sensitive |
+| `server/internal/security` | Encryption, digests, password/session helpers | Never log or expose secrets/PII |
+| `server/migrations` | Ordered PostgreSQL schema changes | Production migrations precede API rollout |
+| `web/src/pages`, `components`, `hooks`, `lib` | Browser routes, presentation, state hooks, and API client | One application serves multiple role-specific surfaces |
+| `android/app/src/main/java/cn/nianxx/queue/display` | Native navigation, API client/parser, polling, Views, formatting, announcement state, WAV composition/playback | Overview must remain audio-free |
+| `android/app/src/main/res/raw` | The exact embedded Mandarin announcement fragments | Format and file set are regression-tested |
+| `deliverables/android` | Installable debug APK, checksum, and handoff notes | Must match the verified build output |
+| `scripts` | Database setup, seed, smoke, and integration-test orchestration | Do not run demo seed in production |
+
+## Dependency Direction
+
+- Clients depend on public/service contracts; they do not own queue transitions.
+- HTTP handlers may use domain, model, database, and security modules; pure domain code should not depend on transport/UI concerns.
+- Android Views consume parsed display models; announcement playback consumes validated call text and embedded assets.
+
+## Risky Or Sensitive Areas
+
+- `server/internal/httpapi/staff.go`: transactional queue writes, duplicate handling, FIFO selection, revisions, and audit.
+- `server/internal/httpapi/public.go`: privacy-safe public projections and public ticket protections.
+- `server/internal/httpapi/reissue.go` and ticket-transition logic: implemented business paths are currently not registered in `Server.Handler()` or wired in the web client; treat them as inactive until routes and integration tests are added.
+- `android/.../MainActivity.java`: screen-state, poller, and announcement lifecycle boundary.
+- `android/.../QueueAnnouncementPlayer.java` and `EmbeddedWavComposer.java`: cross-thread native audio lifecycle and asset validation.
+- `android/.../SingleLineFitTextView.java`: business-critical full range-number visibility across device fonts/densities.
+
+## Last Updated
+
+2026-08-12

.project-docs/20-architecture/system-overview.md

@@ -0,0 +1,32 @@
+# System Overview
+
+## Current Architecture
+
+XQKqueue is a modular monolith. A Go HTTP service owns business rules and writes to PostgreSQL. One React/Vite application supplies staff, visitor, administrator, and browser-display routes. A separate native Android application consumes only privacy-safe public display endpoints for dedicated large screens.
+
+## Main Components
+
+| Component | Responsibility | Notes |
+|---|---|---|
+| Go service | Authentication, queue commands, public/read models, audit, maintenance, and HTTP transport | Standard-library router plus GORM; sole write authority |
+| PostgreSQL | Projects, sessions, tickets, call batches, users, idempotency, revisions, and audit history | Versioned SQL migrations |
+| React web application | Staff H5, visitor ticket/status pages, administrator UI, and browser display surfaces | REST writes and interval polling; the server SSE endpoint is not currently consumed by the web client |
+| Native Android display | Overview and project-specific public display UI, polling, offline state, and project-detail announcements | Android Views; no WebView or system TTS |
+| Delivery/scripts | Migrations, seed data, smoke tests, container/local startup, and APK handoff | Production must migrate before API start and must not run demo seed |
+
+## Important Boundaries
+
+- Queue selection, duplicate enforcement, ticket numbering, and revisions belong to the service transaction boundary, never a client.
+- Public DTOs are allowlisted projections and must never include encrypted or hashed personal fields.
+- Android overview and project screens are distinct states; only a valid project screen may create the announcement coordinator.
+- A project snapshot is the Android project screen's single source for both rendering and new-call detection.
+- Browser and Android displays may share API semantics, but neither should import or emulate privileged staff/admin behavior.
+
+## Related Decisions
+
+- [ADR-001: Native Android large-screen application](../10-decisions/adr-001-native-android-display.md)
+- [ADR-002: Embedded audio announcements](../10-decisions/adr-002-embedded-audio-announcements.md)
+
+## Last Updated
+
+2026-08-12

.project-docs/30-worklog/current-state.md

@@ -0,0 +1,46 @@
+# Current State
+
+This file is the integrated default-branch snapshot. Feature tasks record progress in `30-worklog/tasks/{task_id}.md` and propose canonical changes for the Integration Gate. Feature tasks must not rewrite this file; it changes only in integration mode.
+
+## Integrated Through
+
+- Source task `20260811-native-display-f2456ea9`, product commit `50ac5bddc4f747b88064051f9038fa026280ab4b`.
+
+## Current Focus
+
+The current focus is field acceptance and production hardening of the native Android display while preserving the existing web, API, and queue invariants.
+
+## Recently Completed
+
+- 2026-08-12: Replaced the Android WebView wrapper with native overview/project Views and direct public API polling.
+- 2026-08-12: Added project-detail-only, three-repeat embedded Mandarin WAV announcements through streaming `AudioTrack`; overview remains silent.
+- 2026-08-12: Added full-range single-line fitting so a batch such as `00010 至 00011` is not clipped, and produced debug APK 1.5.2.
+- 2026-08-12: Retained and verified the responsive browser display adjustments for short landscape screens.
+
+## In Progress
+
+- No product code change is currently in progress on the integrated branch.
+
+## Next Recommended Steps
+
+1. Install debug APK 1.5.2 on the target television and accept representative single/range audio plus full range-number rendering.
+2. Before formal production rollout, build a release-signed APK with the organization's long-lived signing key.
+3. Confirm the legacy WAV asset ownership/redistribution basis before distributing the APK outside the authorized project deployment.
+4. Revalidate landscape behavior before raising Android targetSdk to 37 because the current Android 16 compatibility property is temporary.
+
+## Open Questions / Blockers
+
+- Target-TV audio routing, font metrics, and final range rendering cannot be fully verified by host-side tests.
+- The historical WAV generator, speaker, and separate license record are unknown.
+- The checked-in installable is debug-signed and is not a final production release artifact.
+
+## Risky Areas
+
+- Queue writes and same-session transitions require transaction/row-lock/revision invariants.
+- Public projections must remain free of personal data.
+- Android audio focus, cancellation, and `AudioTrack` lifecycle are vendor-sensitive.
+- Android large-screen orientation behavior changes at targetSdk 37.
+
+## Last Updated
+
+2026-08-12

.project-docs/30-worklog/session-notes/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/30-worklog/task-history.md

@@ -0,0 +1,11 @@
+# Task History
+
+## Completed Tasks
+
+| Date | Task | Outcome | Docs Updated |
+|---|---|---|---|
+| 2026-08-12 | `20260811-native-display-f2456ea9` | Native Android display, embedded Mandarin announcements, range-fit regression fix, and APK 1.5.2 integrated in `50ac5bd` | Architecture, decisions, domain rules, evidence, reflection, commitments, current state |
+
+## Notes
+
+This is legacy integrated history. Feature tasks must not append here. Record new work in `30-worklog/tasks/{task_id}.md`; an integration workflow may render or summarize accepted history later.

.project-docs/30-worklog/task-template.md

@@ -0,0 +1,35 @@
+# Task: {title}
+
+## Identity
+
+- Task ID: {task_id}
+- Mode: {mode}
+- Branch: {branch}
+- Worktree: {worktree}
+- Base commit: {base_commit}
+- Owner: {owner}
+- Status: Planning
+
+## Scope
+
+- {scope}
+
+## Intent And Constraints
+
+- {intent_or_constraint}
+
+## Outcome
+
+- Not completed.
+
+## Verification
+
+- Not run.
+
+## Follow-ups
+
+- None recorded.
+
+## Promotion Candidates
+
+- None recorded.

.project-docs/30-worklog/tasks/20260812-finalize-native-display-7c23e18a.md

@@ -0,0 +1,50 @@
+# Task: Finalize native display integration
+
+## Identity
+
+- Task ID: 20260812-finalize-native-display-7c23e18a
+- Mode: Integration
+- Branch: main
+- Worktree: D:\Datas\PythonProjects\XQKqueue
+- Base commit: 50ac5bddc4f747b88064051f9038fa026280ab4b
+- Owner: codex
+- Status: Complete
+
+## Scope
+
+- Promote the completed native Android display task into canonical project memory from product commit `50ac5bddc4f747b88064051f9038fa026280ab4b`.
+- Verify the integrated source, canonical decisions, architecture, domain rules, evidence pointers, follow-up commitments, build output, and repository state.
+- Obtain an independent read-only final review and push the resulting `main` branch to `origin`.
+
+## Intent And Constraints
+
+- Integration worktree and lock are exclusively owned by this task.
+- Source task records/evidence are read-only at this base.
+- Canonical updates must preserve confirmed behavior and distinguish target-device acceptance gaps from completed host verification.
+- No new product behavior is introduced by this documentation/push task.
+
+## Outcome
+
+- Promoted project positioning, completion criteria, two accepted Android decisions, system/module/data-flow architecture, integrated state/history, durable business rules/glossary, evidence/reflection indexes, commitments, and known missing context.
+- Full local verification, APK integrity checks, canonical-memory audit, independent final review, and documentation ownership gate passed. The documentation commit and remote push are the remaining mechanical handoff steps.
+
+## Verification
+
+- Verified source commit `50ac5bddc4f747b88064051f9038fa026280ab4b` is present on local `main`.
+- Confirmed this task's base is that source commit, so the historical source records are unchanged during canonical promotion.
+- Android: `clean testDebugUnitTest lintDebug assembleDebug` passed; 56 tests, zero failures/errors/skips, zero lint errors.
+- Web: 18 test files / 66 tests passed; typecheck and production build passed.
+- Server: `go test ./...`, `go vet ./...`, and `go build ./...` passed.
+- APK metadata: package `cn.nianxx.queue.display`, versionCode 9, versionName 1.5.2, minSdk 23, targetSdk 36; v1/v2 signature verification passed.
+- Build APK, deliverable APK, and declared checksum all match SHA-256 `0D56C10B8CE706893F3EA8E59B21329847517F56F7347ABEA127AB30C6C71D77`.
+- `check_project_docs.py` passed and `check_doc_drift.py --task-id 20260812-finalize-native-display-7c23e18a` passed before independent review.
+- Canonical-memory audit corrected two overbroad statements (ticket calling is "up to N" and the current web client polls rather than consuming SSE), narrowed mutation guarantees to implemented endpoint contracts, and recorded privacy-retention/session rules plus the unregistered transition/reissue source paths.
+- Independent final integration review: PASS; no actionable P0/P1 blocker.
+
+## Follow-ups
+
+- Target-TV field acceptance, production signing, legacy audio-rights confirmation, and targetSdk 37 landscape revalidation are recorded in canonical commitments.
+
+## Promotion Candidates
+
+- None. This Integration task applies the accepted promotion candidates directly to canonical memory.

.project-docs/40-domain/business-rules.md

@@ -0,0 +1,28 @@
+# Business Rules
+
+## Durable Rules
+
+- A queue ticket belongs to one project and one queue session and binds a fixed party size chosen at creation.
+- Ticket-number calling selects up to the first contiguous N waiting tickets in FIFO order.
+- People-count calling selects the longest contiguous FIFO prefix whose total party size does not exceed the target; tickets are never split or skipped, and the request fails if the first waiting ticket alone exceeds the target.
+- Same-phone duplicate protection in a project/session applies only while an existing ticket is `WAITING`. Once it has been called, that phone may take another ticket in the same session. A still-waiting duplicate requires explicit confirmation.
+- Login attempts remain allowed through the ninth failure in a ten-minute window. The tenth failure locks that limiter key for ten minutes; successful login clears the attempt state.
+- A project's current queue session is selected for the project's local business date and must be in `RUNNING` or `PAUSED` where read flows allow both; write operations apply their stricter project/session status rules.
+- Public phone lookup is an operational-test path only and is disabled with a 404 response in production; internal phone lookup is private-network-only.
+- Terminal ticket personal fields are scheduled for purge after 30 days; records older than 90 days are anonymized as a backstop. Maintenance runs in bounded transactions under a PostgreSQL advisory lock, and audit/session/idempotency retention is enforced from stored expiry fields.
+- Public display responses are read-only allowlisted projections and must not expose phone, name ciphertext/nonces, HMACs, private status tokens, or other personal fields.
+- `/admin/display` is an overview surface and never announces. Only `/display/{project-code-or-token}` may announce a new call.
+- Android establishes the first project snapshot as a silent baseline; only a subsequently changed call batch is announced.
+- Android announcements speak the called ticket number or first-to-last range, never the project name, and repeat the complete announcement three times in FIFO batch order.
+- A multi-ticket current batch displays its first and last number as a complete range such as `00010 至 00011`; it must not ellipsize or silently clip the endpoint.
+- Leaving a project screen or pausing the Android activity stops project polling and clears/stops current and queued announcements.
+- Ticket transition and missed-ticket reissue logic exists in the service source, including one-time tail reissue with revision/idempotency checks, but is not currently registered as an HTTP route or wired into the web UI; do not treat it as an active user-facing capability until that integration is implemented and tested.
+
+## Open Questions
+
+- Confirm whether the legacy Mandarin WAV assets are cleared for redistribution outside the current project's authorized deployment.
+- Confirm whether a future production APK will remain fixed to one service origin or needs managed environment configuration.
+
+## Last Reviewed
+
+2026-08-12

.project-docs/40-domain/glossary.md

@@ -0,0 +1,15 @@
+# Glossary
+
+| Term | Meaning | Notes |
+|---|---|---|
+| Project | A queueable scenic-area service/attraction with its own code, configuration, status, and sessions | Public display URLs normally use the project code |
+| Queue session | A project's operational queue for one business date | Owns next number and revision |
+| Queue ticket | One numbered party waiting for or receiving service | Party size is immutable after creation |
+| Call batch | One staff call action containing a contiguous set of tickets | Android announces first-to-last for a multi-ticket batch |
+| Overview display | Multi-project public display corresponding to `/admin/display` | Read-only and never announces |
+| Project display | One project's public display at `/display/{identifier}` | The only Android state allowed to announce |
+| Snapshot | Authoritative privacy-safe project display response | Drives both Android UI and announcement detection |
+| Display identifier | Project code or compatible public display token accepted by the snapshot endpoint | Overview navigation requires a non-empty project code |
+| Revision | Monotonic queue-session change marker | Supports event/poll recovery and freshness |
+| Experienced people | Displayed as the greater of the configured starting value and cumulative issued party size in the current project-local business-day session | Distinct from issued ticket count |
+| Announcement baseline | First snapshot accepted after entering/resuming a project screen | Stored silently to prevent replaying an old call |

.project-docs/50-evidence/evidence-index.md

@@ -0,0 +1,15 @@
+# Evidence Index
+
+Use this index for searchable, traceable evidence records.
+
+| Date | Topic | Status | Source | Detail |
+|---|---|---|---|---|
+| 2026-08-11 | Public display API contract used by the native app | Verified | Source code and tests | [Evidence](topics/20260811-native-display-f2456ea9__public-display-api.md) |
+| 2026-08-12 | Embedded Mandarin WAV provenance, mapping, format, and acceptance | Verified with known licensing gap | Git history, WAV inspection, ASR, tests | [Evidence](topics/20260811-native-display-f2456ea9__embedded-audio-assets.md) |
+| 2026-08-12 | Batch range endpoint clipping and fitted-text fix | Verified in host tests; target-TV acceptance pending | Production snapshot, code, Robolectric, APK checks | [Evidence](topics/20260811-native-display-f2456ea9__range-display-fit.md) |
+
+## When To Add Evidence
+
+Add a topic file when a task depends on logs, commits, test output, external docs, bug reproduction, experiments, or postmortem-level reasoning.
+
+Keep task progress in `30-worklog/`; keep reusable workflow lessons in `60-reflection/`.

.project-docs/50-evidence/topic-template.md

@@ -0,0 +1,35 @@
+# Evidence Topic: {short title}
+
+## Metadata
+
+- Date:
+- Status: Active | Resolved | Superseded | Stale
+- Scope:
+- Confidence: Fact | Inference | Hypothesis
+- Source:
+- Last verified:
+- Stale trigger:
+
+## Question
+
+What needed evidence?
+
+## Evidence
+
+- Commit:
+- Files:
+- Commands:
+- Logs:
+- External source:
+
+## Finding
+
+What does the evidence support?
+
+## Impact
+
+What future planning or implementation should this affect?
+
+## Open Items
+
+-

.project-docs/60-reflection/reflection-index.md

@@ -0,0 +1,13 @@
+# Reflection Index
+
+Use this index for second-order workflow lessons.
+
+| Date | Reflection | Trigger | Action | Detail |
+|---|---|---|---|---|
+| 2026-08-12 | Initializing project memory during a feature task can deadlock ownership-based drift checks | Initial canonical templates appeared as foreign task changes | Use an explicitly authorized Integration task to adopt the baseline; consider a first-install mode | [Case](cases/20260811-native-display-f2456ea9__initialization-drift-deadlock.md) |
+
+## When To Reflect
+
+Create a reflection only when work reveals a reusable lesson: skipped gates, repeated mistakes, durable debugging patterns, ineffective plans, human corrections, or candidates for new scripts or skills.
+
+Routine task completion belongs in `30-worklog/task-history.md`.

.project-docs/60-reflection/reflection-template.md

@@ -0,0 +1,54 @@
+# Reflection: {short title}
+
+## Trigger
+
+What happened?
+
+## Expected Behavior
+
+What should the agent or workflow have done?
+
+## Actual Behavior
+
+What happened instead?
+
+## Root Cause
+
+Classify the cause:
+
+- Missing trigger
+- Weak gate
+- Stale docs
+- Unclear ownership
+- Missing script
+- Human decision not promoted
+- Agent ignored context
+- Other:
+
+## Evidence
+
+- Commit:
+- Files:
+- Session/thread:
+- Command output:
+- Docs involved:
+
+## Lesson
+
+What should future agents learn?
+
+## Action
+
+Choose one:
+
+- Update docs
+- Update gate
+- Create script
+- Create/update skill
+- Add check/eval
+- Ask human to decide
+- No action
+
+## Promotion
+
+Should this become a rule, ADR, architecture note, task-history entry, skill change, or script?

.project-docs/60-reflection/skill-candidates.md

@@ -0,0 +1,11 @@
+# Skill Candidates
+
+Track repeated workflow lessons that may deserve a reusable skill, script, or stronger gate.
+
+| Date | Candidate | Evidence | Proposed Action | Status |
+|---|---|---|---|---|
+| 2026-08-12 | First-install ownership mode for `maintain-project-docs` | [Initialization drift deadlock](cases/20260811-native-display-f2456ea9__initialization-drift-deadlock.md) | Let an explicitly authorized Integration task claim initializer-created canonical templates without classifying them as foreign feature drift | Proposed; wait for recurrence or skill-maintainer review |
+
+## Promotion Rule
+
+If the same reflection pattern appears repeatedly or prevents a serious mistake, propose a skill update, new skill, script, or deterministic check.

.project-docs/80-commitments/commitments.md

@@ -0,0 +1,14 @@
+# Commitments
+
+Track future-facing memory: promised follow-ups, unfinished loops, timed checks, and restart points.
+
+| Date | Commitment | Trigger / Due | Owner | Status | Next Action |
+|---|---|---|---|---|---|
+| 2026-08-12 | Accept APK 1.5.2 audio and full range rendering on the target television | Before production rollout | Product operator | Open | Exercise representative single/range calls and confirm media route, all digits, three repeats, and both range endpoints |
+| 2026-08-12 | Replace the debug-signed APK with an organization release-signed artifact | Before formal production distribution | Engineering / release owner | Open | Configure protected signing credentials, build release, and document upgrade path/checksum |
+| 2026-08-12 | Confirm legacy Mandarin WAV ownership/redistribution basis | Before distribution outside the authorized project deployment | Product owner / legal | Open | Locate original asset source or record written authorization |
+| 2026-08-12 | Revalidate landscape strategy for Android targetSdk 37 | Before raising targetSdk from 36 | Android maintainer | Open | Test target device and replace the temporary Android 16 compatibility assumption if needed |
+
+## Use
+
+Record only commitments that should affect future sessions. Routine next steps can stay in `30-worklog/current-state.md`.

.project-docs/90-maintenance/doc-update-policy.md

@@ -0,0 +1,42 @@
+# Doc Update Policy
+
+Use agent judgment and project context to decide what is durable. Do not use fixed keyword matching to decide whether information belongs in project memory.
+
+## Feature Task Writes
+
+Every repository-changing feature task updates `30-worklog/tasks/{task_id}.md`. Keep scope, intent, outcome, verification, follow-ups, and promotion candidates there.
+
+When separate evidence, reflection, commitment, conflict, or decision-proposal records are useful, create uniquely named task-prefixed `{task_id}__<slug>.md` files in the task-writable directories. The slug is non-empty and `.md` is the exact extension. Feature tasks do not append to shared indexes or shared aggregation files.
+
+Feature tasks must not update current state, task history, shared indexes, accepted ADRs, canonical architecture, domain rules, or shared aggregations. Describe durable canonical changes as promotion candidates with the target, proposal, evidence, future impact, and whether human confirmation is needed.
+
+## Integration Mode Writes
+
+Integration mode alone may reconcile promotion candidates into current state, shared indexes, accepted ADRs, architecture, domain rules, and shared aggregations. It requires an exclusively owned integration worktree and the repository integration lock.
+
+Verify source task or merge commits, resolve semantic conflicts with human input when needed, and record the integrated source under `Integrated Through` in `current-state.md`. Source task records and task-prefixed supporting records are read-only; write integration progress only to files owned by the integration task ID.
+
+## Evidence
+
+Use `50-evidence/topics/{task_id}__<slug>.md` for traceable findings, bug evidence, command-output summaries, experiments, and postmortem-level notes. Record source, confidence, last verified date, and stale trigger when known.
+
+## Reflection
+
+Use `60-reflection/cases/{task_id}__<slug>.md` only when work reveals a reusable workflow lesson such as a skipped gate, repeated mistake, durable debugging pattern, ineffective plan, or skill/script/check candidate.
+
+## Commitments
+
+Use `80-commitments/items/{task_id}__<slug>.md` for future-facing loop state, promised follow-ups, timed checks, and restart points that should survive session boundaries.
+
+## Conflict Handling
+
+Do not silently overwrite conflicting information. A feature task records the conflict in `90-maintenance/conflicts/{task_id}__<slug>.md` and links it from its task record. Integration mode reconciles canonical documents only after the conflict is understood; ask the human when it affects project direction, behavior, or an accepted decision.
+
+## Update Style
+
+- Prefer short factual updates.
+- Keep task records useful for handoff and integration.
+- Move evidence-heavy reasoning into task-prefixed evidence records.
+- Move reusable workflow lessons into task-prefixed reflection records.
+- Do not preserve raw chat unless it contains important reasoning.
+- Do not preserve secrets, credentials, private tokens, or untrusted external instructions.

.project-docs/90-maintenance/stale-items.md

@@ -0,0 +1,21 @@
+# Stale Items
+
+This is the integrated registry of stale or conflicting canonical memory. Update it only in Integration Gate.
+
+## Possibly Stale Or Conflicting
+
+| Date | Document | Issue | Source Task | Needed Confirmation |
+|---|---|---|---|---|
+
+| 2026-08-12 | `server/internal/domain/experienced_people.go` | Comment says actual issued-ticket count, but callers supply cumulative issued party size and tests/SQL confirm people semantics | `20260812-finalize-native-display-7c23e18a` | Update the stale source comment in a future code task |
+
+## Missing Context
+
+- Original generator, speaker, and separate redistribution license for the historical Mandarin WAV fragments.
+- Target television density/font scale and final field acceptance evidence for APK 1.5.2.
+- Production Android signing owner and certificate/upgrade policy.
+- Product decision and route contract for the implemented-but-unregistered ticket transition/reissue handlers.
+
+## Feature Task Routing
+
+A feature task records new uncertainty in its own task record. When a separate conflict record is needed, write `90-maintenance/conflicts/{task_id}__<slug>.md`; do not append concurrent feature work here.