Ubisam-MobileGit/AGENTS.md

# UBGitea Engineering Contract

This file is the canonical instruction source for every coding agent. If another agent-specific file conflicts with this file, this file wins.

## Product

UBGitea is an Android client for the company Gitea instance.

- Gitea base URL: `https://gitea.ubisampaju.synology.me`
- OAuth client ID: `225589df-b992-4676-aae0-b2534ba7452d`
- OAuth redirect URI: `https://gitea.ubisampaju.synology.me/ubisampaju/oauth/callback`
- Authentication: OAuth 2.0 Authorization Code with PKCE (`S256`)
- Client secret: never required, requested, stored, logged, or committed

Treat the base URL and client ID as configuration, even while they have production defaults.

## Source of truth

Before work, read in this order:

1. `AGENTS.md`
2. The assigned file under `tasks/`
3. Relevant documents under `docs/`
4. Existing code and tests

Do not implement a feature without an acceptance-criteria task file. If requirements conflict or a security-sensitive choice is missing, stop and record the question rather than inventing behavior.

## Agent roles

Since 2026-09-28 the project is developed by Claude alone, directed by the human product owner. Earlier tasks and log entries that name Codex as owner or reviewer are historical; a status of "pending Codex review" now means "pending review" by the roles below.

### Claude — implementer and integrator

- Owns repository edits within the task's writable paths.
- Inspects existing code before changing it.
- Implements the smallest coherent change satisfying the task.
- Runs required checks and records evidence.
- Resolves review findings and keeps documentation synchronized.

### Reviewer — a separate Claude review session or the human product owner

- Reviews in a session that did not write the change, and stays read-only while reviewing.
- Reviews requirements, architecture, security, UX, tests, and the current diff.
- Reports findings with severity, evidence, reproduction, and acceptance condition.
- Uses `prompts/claude-review.md`.

### Human product owner

- Decides product behavior, branding, external infrastructure, and release approval.
- Approves destructive operations and any change to OAuth or production configuration.

## Single-writer protocol

- Only one session may write a file during a task.
- Two sessions must not edit the same working tree concurrently. A session running in a worktree writes only inside that worktree.
- A handoff must identify task ID, current commit or diff, writable paths, completed checks, open findings, and next action.
- Never accept a review based only on “looks good.” Use acceptance criteria and test evidence.
- Finished work is merged into `master`, so that a new worktree starts from the current application rather than an old snapshot.

## Required work cycle

1. Restate the task outcome and risks.
2. Inspect relevant files and current git status.
3. Plan a small change with explicit file ownership.
4. Implement.
5. Run the checks listed in the task.
6. Review the diff against acceptance criteria.
7. Ask the reviewer to inspect it.
8. Resolve findings and rerun checks.
9. Update task evidence and hand off.

## Android engineering rules

- Kotlin and Jetpack Compose are the default UI stack.
- Prefer unidirectional data flow and immutable UI state.
- Keep Android framework details at the edges of domain and data logic.
- Use coroutines with structured concurrency; do not use global scopes.
- Keep network DTOs separate from domain models.
- Never perform network or disk work on the main thread.
- All user-visible text belongs in string resources.
- Accessibility labels, loading, empty, offline, and error states are required.
- Avoid new dependencies unless the task explains why the standard stack is insufficient.

## Security invariants

- Use the system browser for OAuth; do not use WebView for credential entry.
- Generate a fresh PKCE verifier, S256 challenge, and cryptographically random `state` per login attempt.
- Reject missing or mismatched `state` and unexpected redirect URIs.
- Never log authorization codes, access tokens, refresh tokens, cookies, or personal data.
- Store tokens using Android Keystore-backed protection.
- Do not disable TLS validation or add trust-all certificates.
- Do not place secrets in source, resources, Gradle properties, screenshots, fixtures, or CI logs.
- Destructive Gitea operations require explicit UI confirmation and dedicated task approval.

## Verification gates

Before a task is complete, run all applicable checks:

- Gradle build
- Unit tests
- Android lint
- Static formatting/check task when configured
- Focused tests for changed behavior
- Secret scan or repository search for sensitive values
- Manual verification steps named by the task

If a check cannot run, record the exact reason and do not claim the task is complete.

## Review severity

- `P0`: credential exposure, data loss, remote compromise, or release blocker
- `P1`: broken primary flow, authorization flaw, crash, or serious regression
- `P2`: incorrect edge case, maintainability problem, missing important test
- `P3`: minor quality or consistency improvement

Each finding must include file and line, concrete impact, evidence, and the condition that closes it.

## Git discipline

- Preserve unrelated user changes.
- Keep commits focused on one task.
- Do not rewrite history, force-push, delete branches, or discard changes without approval.
- Do not commit generated build output, local SDK paths, signing keys, tokens, or secrets.
- Branch names use the `claude/` prefix. Existing `codex/` branches are historical.

## Definition of done

A task is done only when its acceptance criteria are met, required checks pass, no unresolved P0/P1 findings remain, documentation reflects material decisions, and a reviewer can reproduce the result from the recorded evidence.