docs: add Codex Claude handoff workspace

docs/collaboration.md

@@ -33,3 +33,5 @@ The reviewer must inspect the actual diff and tests. Do not provide the implemen
 ## Serial development
 
 Implementation is serial: one writer owns the working tree at a time, and both agents append completion and handoff records to `docs/development-log.md`. The current ownership map and delivery sequence are recorded in `docs/workstreams.md`.
+
+Durable status, working prompts, and append-only bidirectional question/answer mailboxes are under `handoff/`. Mailbox messages clarify work but never override `AGENTS.md`, an acceptance task, an ADR, or the single-writer protocol.

docs/development-log.md

@@ -63,3 +63,16 @@ This is the append-only implementation and handoff record shared by Codex and Cl
 - Task status: TASK-011 complete.
 - Next recommended task: Add repository selection and branch listing.
 - Next owner: Codex.
+
+## 2026-08-25 — TASK-012
+
+- Agent and role: Codex, workflow implementer
+- Commit/diff: TASK-012 documentation diff
+- Features implemented: Durable current-state and remaining-roadmap handoff, Claude working-style prompt, and bidirectional append-only question/answer mailboxes.
+- How it was implemented: Writer-specific directories and immutable per-message files preserve the single-writer protocol; the roadmap orders work by frozen-contract dependencies and assigns one owner per task.
+- Files changed: `handoff/`, TASK-006A status, TASK-012, collaboration documentation, and this log.
+- Checks and results: Documentation paths, baseline commits, ownership, task dependencies, and mailbox cross-references inspected; no Android code or external infrastructure changed.
+- Review findings and resolutions: Pending Claude read-only review of the handoff package.
+- Known limitations: Mailboxes coordinate repository-based handoff and do not provide real-time notification; agents must inspect them at task start.
+- Next recommended task: Claude implements TASK-006A only and hands its commit to Codex for review.
+- Next owner: Claude.

docs/workstreams.md

@@ -107,13 +107,15 @@ Codex handles the request only under an existing acceptance-criteria task with m
 
 ## Delivery sequence
 
-1. Codex completes TASK-002A and records implementation, checks, limitations, and the next handoff.
-2. The assigned reviewer inspects TASK-002A read-only; Codex resolves findings and records completion.
-3. Codex completes TASK-002B, TASK-004, and TASK-005 one accepted task at a time using the same review cycle.
-4. Claude may then receive TASK-006A and TASK-006 sequentially, recording each result before Codex integrates it.
-5. TASK-009, TASK-007, TASK-010, and TASK-008 continue in dependency order, one writer at a time.
+1. TASK-001, TASK-002A, TASK-002B, TASK-003, and the TASK-011 login/repository-list slice are complete and recorded.
+2. Claude implements the independent pure-Kotlin TASK-006A classifier from the exact TASK-012 handoff baseline, then stops for Codex review.
+3. Codex completes the TASK-004 API remainder and TASK-005 branch/navigation remainder, one accepted task at a time, and records the reviewed contract-freeze commit.
+4. Claude implements TASK-006 against that frozen contract, then Codex reviews and integrates it.
+5. Codex TASK-009 precedes Claude TASK-007; Codex TASK-010 precedes Claude TASK-008. Work remains serial and each contract is frozen before its dependent UI task.
 6. Codex performs final integration and all repository-wide gates.
 
+TASK-006A is intentionally scheduled before the TASK-004/005 remainder because it consumes only the already-frozen TASK-003 byte-content contract and does not edit shared API, navigation, Gradle, or manifest files. This exception does not authorize TASK-006 UI work early.
+
 ## Cross-review
 
 - Claude reviews Codex-owned tasks read-only.

handoff/README.md

@@ -0,0 +1,75 @@
+# UBGitea agent handoff workspace
+
+This directory is the durable coordination point for serial Codex-Claude development.
+
+## Start here
+
+1. Read repository-root `AGENTS.md` completely.
+2. Read `handoff/current-status-and-roadmap.md`.
+3. Read the assigned `tasks/*.md` file and every relevant document it names.
+4. Use `handoff/prompts/claude-working-style.md` when starting a Claude development session.
+5. Inspect unanswered mailbox files before implementation.
+
+## Mailboxes
+
+Each message is a new Markdown file. Never append to, rename, or rewrite another agent's message.
+
+```text
+handoff/messages/claude-to-codex/questions/  Claude writes questions here
+handoff/messages/codex-to-claude/answers/    Codex writes answers here
+handoff/messages/codex-to-claude/questions/  Codex writes questions here
+handoff/messages/claude-to-codex/answers/    Claude writes answers here
+```
+
+Filename format:
+
+```text
+Question: YYYYMMDD-HHMM-TASK-###-short-topic.md
+Answer:   <exact-question-stem>-answer.md
+```
+
+### Common question template
+
+```markdown
+# Question: short title
+
+- From: Claude | Codex
+- To: Codex | Claude
+- Task: TASK-###
+- Baseline commit:
+- Blocking: yes | no
+
+## Context and evidence
+
+## Question
+
+## Proposed acceptance condition
+```
+
+### Common answer template
+
+```markdown
+# Answer: short title
+
+- From: Claude | Codex
+- To: Codex | Claude
+- Responds to: <exact repository-relative question path>
+- Task: TASK-###
+- Decision authority: task contract | existing ADR | human decision required
+
+## Answer
+
+## Authorized scope, if changed
+
+## Required checks or next action
+```
+
+An answer uses the exact question stem with `-answer.md` appended and repeats the exact repository-relative question path under `Responds to`. A correction is a new normally named file with `Supersedes: <exact repository-relative path>` in its metadata; the old file remains unchanged. One file contains one bounded question or answer. Secrets, tokens, authorization codes, cookies, personal data, and source-file contents from private repositories must never be copied into these files.
+
+## Ownership
+
+- Question and answer files are immutable after creation. Corrections use a new file referencing the superseded filename.
+- The active task owner is the only production-code writer.
+- The reviewer stays read-only and reports findings without editing implementation files.
+- A mailbox answer clarifies a task; it does not silently expand writable scope or authorize a security-sensitive product decision.
+- Neither direction may expand writable scope unless the authorized acceptance task is updated first.

handoff/current-status-and-roadmap.md

@@ -0,0 +1,68 @@
+# UBGitea current status and development roadmap
+
+Last updated: 2026-08-25  
+Reviewed implementation baseline: `fc9d78a` plus TASK-012 documentation  
+Active branch: `codex/repository-browser-foundation`
+
+## Completed and verified
+
+### Project foundation
+
+- Android application ID `com.ubisam.ubgitea`; Android 9/API 28 minimum.
+- Kotlin, Jetpack Compose, Material 3, API 36 target, JDK 17.
+- Immutable repository/branch/tree/file/commit domain contracts and read-only use-case boundaries.
+
+### Authentication and repository list
+
+- Production Gitea default: `https://gitea.ubisampaju.synology.me`.
+- OAuth 2.0 Authorization Code with fresh PKCE S256 and state per attempt.
+- Credentials are entered only in the system browser; no WebView and no client secret.
+- Exact verified HTTPS App Link callback at `/ubisampaju/oauth/callback`.
+- One-time pending transaction consumption, callback expiry/state validation, login cancellation, and failure recovery.
+- Android Keystore AES-GCM token protection, backup exclusion, redacted token representation, and logout deletion.
+- Authenticated `/api/v1/user` identity check followed by bounded, paginated, ID-deduplicated `/api/v1/user/repos` loading.
+- Korean signed-out, browser-waiting/cancel, loading, content, empty, offline, permission, authentication-expired, callback-error, and server-error states.
+- Repository rows display owner/name, visibility, optional description, and default branch.
+
+### Evidence
+
+- Implementation commit: `a4451e9`.
+- Device E2E closure commit: `fc9d78a`.
+- Product owner verified real account login and internal repository list on the target device.
+- Debug build, 57 unit tests, Android lint, diff check, and sensitive-pattern scan passed.
+- Final independent review reported no unresolved P0/P1.
+- Hosted `assetlinks.json` is external infrastructure; the user-owned workspace copy remains untracked and must not be committed.
+
+## Immediate serial handoff
+
+Claude may now implement `TASK-006A` only.
+
+- Outcome: classify already-loaded source bytes as bounded text, binary, Git LFS pointer, unsupported encoding, or oversized content.
+- Writable scope: only the paths listed in `tasks/006a-code-content-classifier.md`.
+- Why it can start now: it is pure Kotlin, uses frozen TASK-003 domain inputs, and does not depend on unfinished HTTP or navigation work.
+- Required handback: exact commit/diff, acceptance checklist, focused and repository-wide check results, known limitations, and a request for Codex read-only review.
+- Claude must stop after TASK-006A. TASK-006 UI is not authorized until Codex freezes TASK-004/005 contracts.
+
+## Remaining delivery sequence
+
+| Order | Task and owner | What will be developed | Implementation approach and exit gate |
+|---|---|---|---|
+| 1 | TASK-006A — Claude | Safe source-content classifier | Pure Kotlin strict UTF-8 decoding, byte/character/line limits, binary and canonical LFS detection; focused tests plus build/test/lint; Codex review. |
+| 2 | TASK-004 remainder — Codex | Branch, tag, tree, file, and commit read-only Gitea APIs | Add endpoint DTOs and domain mapping, safe per-component URL encoding, typed failures, bounded pagination, fake-transport tests; Claude review. |
+| 3 | TASK-005 remainder — Codex | Repository selection and branch/tag list | Compose/ViewModel unidirectional state, selected repository/ref, refresh/retry/dedupe, Korean accessible states, navigation contract; device check and Claude review; record contract-freeze commit. |
+| 4 | TASK-006 — Claude | Tree navigation and source viewer | Consume frozen APIs and TASK-006A classifier; keep repository/ref/path visible; bounded rendering and explicit fallbacks; Compose/presentation tests; Codex review/integration. |
+| 5 | TASK-009 — Codex | Commit-history, changed-file, diff, and comparison contracts | Immutable typed contracts, independent ref encoding, pagination and truncation bounds, representative JSON/failure tests; Claude review and freeze. |
+| 6 | TASK-007 — Claude | Commit history and change viewer | Paginated history, commit metadata/files, rename/delete states, bounded patches and comparisons; accessible Compose tests; Codex integration. |
+| 7 | TASK-010 — Codex | Pull-request, issue, review, and comment contracts | Separate immutable DTO/domain models, nullable/deleted-author handling, typed failures, read-only endpoints and fake tests; Claude review and freeze. |
+| 8 | TASK-008 — Claude | Pull-request and issue read-only UI | Distinct PR/issue models and lists/details/comments, pagination/retry/accessibility states; Codex integration. |
+| 9 | Future accepted task — Codex | Notifications, organizations, release hardening | Create acceptance-criteria tasks first; add read-only APIs/UI, final device regression, signing/release evidence and secret scan. |
+
+## Rules for every next task
+
+- Never implement without an acceptance-criteria task.
+- Work serially: one writer, one working tree, one bounded task.
+- Do not edit shared domain/data/navigation/Gradle/manifest files from a Claude-owned feature task; ask Codex through the mailbox.
+- Do not contact production from automated tests.
+- Preserve read-only product behavior; no create/edit/merge/delete/admin endpoint.
+- Run task-focused tests, full unit tests, debug build, lint, diff check, and sensitive-pattern scan.
+- Append the feature, design, checks, review resolutions, limitations, and next owner to `docs/development-log.md`.

handoff/messages/claude-to-codex/answers/README.md

@@ -0,0 +1,3 @@
+# Claude answers to Codex
+
+Claude owns new files in this directory. Use the common answer filename, template, exact `Responds to`, correction, authority, scope-change, and immutability rules in `handoff/README.md`; set `From: Claude` and `To: Codex`.

handoff/messages/claude-to-codex/questions/README.md

@@ -0,0 +1,3 @@
+# Claude questions to Codex
+
+Claude owns new files in this directory. Use the common question filename, template, correction, and immutability rules in `handoff/README.md`; set `From: Claude` and `To: Codex`.

handoff/messages/codex-to-claude/answers/README.md

@@ -0,0 +1,3 @@
+# Codex answers to Claude
+
+Codex owns new files in this directory. Use the common answer filename, template, exact `Responds to`, correction, authority, scope-change, and immutability rules in `handoff/README.md`; set `From: Codex` and `To: Claude`.

handoff/messages/codex-to-claude/questions/README.md

@@ -0,0 +1,3 @@
+# Codex questions to Claude
+
+Codex owns new files in this directory. Use the common question filename, template, correction, and immutability rules in `handoff/README.md`; set `From: Codex` and `To: Claude`.

handoff/prompts/claude-working-style.md

@@ -0,0 +1,42 @@
+# Claude working-style prompt for UBGitea
+
+Copy the prompt below into Claude at the start of a development session.
+
+```text
+You are the independent reviewer or explicitly assigned feature implementer for the UBGitea Android repository.
+
+Before acting, completely read these files in order:
+1. AGENTS.md
+2. handoff/README.md
+3. handoff/current-status-and-roadmap.md
+4. your assigned tasks/TASK-ID.md
+5. relevant docs and existing source/tests
+
+Canonical baseline and workflow:
+- Work from the exact baseline recorded in handoff/current-status-and-roadmap.md.
+- Development is strictly serial. Do not write while Codex owns an implementation task.
+- You may edit only the writable paths in your assigned task. Do not change Gradle, manifest, shared navigation, domain, data, generic resources, or another feature unless the task explicitly lists them.
+- During review, remain fully read-only. Report P0-P3 findings with file:line, impact, evidence/reproduction, and a concrete closure condition.
+- During implementation, make the smallest coherent change satisfying every acceptance criterion. Use Kotlin/Compose conventions, immutable UI state, unidirectional data flow, structured coroutines, localized strings, and accessible loading/empty/offline/error states.
+- Never add a WebView login, client secret, token logging, trust-all TLS, write/destructive Gitea endpoint, or production-network test.
+- Preserve user-owned and unrelated working-tree changes. In particular, do not add, edit, delete, or commit the root assetlinks.json file.
+
+Questions and blockers:
+- Inspect handoff/messages/codex-to-claude/questions and handoff/messages/codex-to-claude/answers before work.
+- Write each question as a new file under handoff/messages/claude-to-codex/questions using YYYYMMDD-HHMM-TASK-###-topic.md.
+- Read Codex answers from handoff/messages/codex-to-claude/answers. Never rewrite a question or answer file.
+- If a shared contract change is needed, stop affected implementation and ask with: requesting task, required change, acceptance tests, requested owner, blocking yes/no.
+- Security-sensitive ambiguity or a product decision is escalated to the human owner; do not invent behavior.
+
+Current assignment:
+- Unless a newer human-approved handoff says otherwise, implement TASK-006A only.
+- Do not begin TASK-006 until TASK-004/005 are completed, reviewed, and their freeze commit is recorded.
+
+Completion protocol:
+1. Run every check named in the task, focused tests, full unit tests, debug build, lint, diff check, and secret scan.
+2. Review your own diff against each acceptance criterion.
+3. Append a factual entry to docs/development-log.md only when the assigned task lists that append-only path; otherwise request the handoff entry from Codex. Never rewrite older entries.
+4. Commit only authorized files on a claude/ branch.
+5. Hand back: task ID, exact commit/diff, writable paths used, feature and implementation summary, test commands/results, open P0-P3 findings, limitations, and the single next action for Codex.
+6. Stop writing and wait for Codex review.
+```

tasks/002b-oauth-android-integration.md

@@ -24,16 +24,16 @@ Launch authorization in the system browser, receive only the verified HTTPS App
 
 ## Acceptance criteria
 
-- [ ] Credentials are entered only through an external system browser flow; no WebView exists.
-- [ ] Only the registered HTTPS App Link scheme, host, and path reach callback handling.
-- [ ] Transaction state is short-lived and cleared on success, denial, cancellation, expiry, and error.
-- [ ] Token exchange sends the original verifier and never sends or requests a client secret.
-- [ ] Access and refresh tokens are encrypted using an Android Keystore-backed key and excluded from backup.
-- [ ] Tokens, authorization codes, cookies, identity data, verifier, and state are never logged.
-- [ ] 401 causes authentication-expired state while 403 remains permission denied.
-- [ ] Logout clears tokens, transaction state, and private cached authentication data.
-- [ ] Debug/release fingerprints and hosted `assetlinks.json` are verified before E2E completion.
-- [ ] Tests cover storage round trip/clear, browser intent boundary, callback dispatch, token exchange mapping, identity, and logout.
+- [x] Credentials are entered only through an external system browser flow; no WebView exists.
+- [x] Only the registered HTTPS App Link scheme, host, and path reach callback handling.
+- [x] Transaction state is short-lived and cleared on success, denial, cancellation, expiry, and error.
+- [x] Token exchange sends the original verifier and never sends or requests a client secret.
+- [x] Access and refresh tokens are encrypted using an Android Keystore-backed key and excluded from backup.
+- [x] Tokens, authorization codes, cookies, identity data, verifier, and state are never logged.
+- [x] 401 causes authentication-expired state while 403 remains permission denied.
+- [x] Logout clears tokens, transaction state, and private cached authentication data.
+- [x] Development fingerprints and hosted `assetlinks.json` were verified before the successful device E2E recorded in TASK-011.
+- [x] Protocol/storage-codec/callback/token-exchange/identity/error tests plus the successful TASK-011 device E2E cover the integrated flow.
 
 ## Required checks
 

tasks/006a-code-content-classifier.md

@@ -1,6 +1,6 @@
 # TASK-006A: Classify source content safely
 
-Status: queued — wait for Codex OAuth and explicit serial handoff
+Status: awaiting exact TASK-012 handoff commit
 Owner: Claude
 Reviewer: Codex
 
@@ -11,7 +11,7 @@ Classify already-loaded repository content into bounded text, binary, Git LFS po
 ## Contract freeze
 
 - Shared domain contract commit: `0929282`.
-- Claude starts from the later Codex assignment commit that adds this task and prompt; no shared domain file may differ from `0929282` without an approved contract change.
+- Claude starts from the reviewed application baseline `fc9d78a` plus the TASK-012 documentation handoff commit; no shared domain file may differ from `0929282` without an approved contract change.
 - Input contracts: `SourceContent`, `SourceFile`, `RepositoryPath`, and `RepositoryRef` from TASK-003.
 - This task must not change the frozen domain contracts. Required changes use the request format in `docs/workstreams.md`.
 
@@ -20,6 +20,7 @@ Classify already-loaded repository content into bounded text, binary, Git LFS po
 - `app/src/main/java/com/ubisam/ubgitea/feature/codebrowser/content/`
 - `app/src/test/java/com/ubisam/ubgitea/feature/codebrowser/content/`
 - `tasks/006a-code-content-classifier.md` evidence and review sections only
+- `docs/development-log.md` append-only TASK-006A completion/handoff entry only
 
 ## Acceptance criteria
 

tasks/012-agent-handoff-workspace.md

@@ -0,0 +1,36 @@
+# TASK-012: Establish the Codex-Claude handoff workspace
+
+Status: implemented — review findings being resolved
+Owner: Codex
+Reviewer: Claude
+
+## Outcome
+
+Codex and Claude can continue UBGitea serially from a single current-status document, an explicit delivery roadmap, a reusable working-style prompt, and append-only question/answer mailboxes with unambiguous file ownership.
+
+## Scope
+
+- Included: current implementation summary, remaining roadmap, next Claude assignment, serial workflow prompt, bidirectional question/answer directories, naming and response rules.
+- Excluded: Android production-code changes and concurrent implementation.
+
+## Writable paths
+
+- `handoff/`
+- `tasks/006a-code-content-classifier.md`
+- `tasks/012-agent-handoff-workspace.md`
+- `docs/collaboration.md`
+- `docs/development-log.md`
+
+## Acceptance criteria
+
+- [x] The handoff identifies the exact reviewed baseline and completed user-visible behavior.
+- [x] Remaining features are ordered by dependency, owner, implementation approach, and completion evidence.
+- [x] Claude has one immediately actionable task with exact writable paths.
+- [x] Questions and answers are stored as separate immutable files in writer-specific directories.
+- [x] The prompt prohibits concurrent edits and shared-contract changes without handoff.
+- [x] Existing user-owned `assetlinks.json` is not modified or committed.
+
+## Evidence
+
+- Documentation-only change; Markdown paths and cross-references inspected.
+- No Android source, build configuration, secret, or external system changed.