# ${PROJECT_NAME} — Agent Context

> Patterns, gotchas, and orchestrator integration for AI agents working on this project.
> **Update this file** when you discover reusable patterns or non-obvious requirements.

## Hard Gates (Read First)

1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
3. Completion is forbidden at PR-open stage.
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.

## Codebase Patterns

<!-- Add project-specific patterns as you discover them -->
<!-- Examples: -->
<!-- - Use `httpx.AsyncClient` for external HTTP calls -->
<!-- - All routes require authentication via `Depends(get_current_user)` -->
<!-- - Config is loaded from environment variables via `settings.py` -->

## Common Gotchas

<!-- Add things that trip up agents -->
<!-- Examples: -->
<!-- - Remember to run migrations after schema changes -->
<!-- - Frontend env vars need NEXT_PUBLIC_ prefix -->
<!-- - Tests require a running PostgreSQL instance -->

## Quality Gates

**All must pass before any commit:**

```bash
${QUALITY_GATES}
```

## Testing Policy

1. Situational tests are the PRIMARY validation gate.
2. Baseline tests remain REQUIRED for all software changes.
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
4. Reference `~/.config/mosaic/guides/QA-TESTING.md`.

## PRD Requirement

1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
2. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context.
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and escalate only for high-impact uncertainty.
4. Reference `~/.config/mosaic/guides/PRD.md`.

## Task Tracking Contract

1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).

## Documentation Contract

Documentation is a hard delivery gate.
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).

Reference:
- `~/.config/mosaic/guides/DOCUMENTATION.md`
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`


## Token Budget Policy

1. If user plan or token limits are provided, they are HARD constraints.
2. Track estimated and used tokens for non-trivial execution.
3. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.

## Merge Strategy (Hard Rule)

1. Create short-lived branches from `main`.
2. Open PRs to `main` for delivery changes.
3. Do not push directly to `main`.
4. Merge PRs to `main` with squash strategy only.
5. Do not mark implementation complete until PR is merged.
6. Do not mark implementation complete until CI/pipeline status is terminal green.
7. Close linked issues/tasks only after merge + green CI.
8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.

## Container Release Strategy (When Applicable)

1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
4. Do not use `latest` or `dev` as deployment references.
5. Use blue-green by default; use canary only with automated metrics and rollback gates.

## Steered Autonomy Contract

1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, PR/repo operations, release/tag, and deployment when in scope.
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
3. Code review is agent-executed and REQUIRED for any source-code change.

## Mode Declaration Contract

1. First response MUST declare mode before any actions.
2. Orchestration mission: `Now initiating Orchestrator mode...`
3. Implementation mission: `Now initiating Delivery mode...`
4. Review-only mission: `Now initiating Review mode...`

## Orchestrator Integration

### Task Prefix
Use `${TASK_PREFIX}` as the prefix for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).

### Package/Directory Names
<!-- List key directories the orchestrator needs to know about -->

| Directory | Purpose |
|-----------|---------|
| `${SOURCE_DIR}/` | Main source code |
| `tests/` | Test files |
| `docs/scratchpads/` | Working documents |

### Worker Checklist
When completing an orchestrated task:
1. Read `docs/PRD.md` or `docs/PRD.json`
2. Read the finding details from the report
3. Implement the fix following existing code patterns
4. Run quality gates (ALL must pass)
5. Complete required documentation updates (if applicable)
6. Commit with: `git commit -m "fix({finding_id}): brief description"`
7. Report result as JSON to orchestrator

### Post-Coding Review
After implementing changes, code review is REQUIRED for any source-code modification.
For orchestrated tasks, the orchestrator will run:
1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

## Directory-Specific Context

<!-- Add sub-AGENTS.md files in subdirectories if needed -->
<!-- Example: -->
<!-- - `src/api/AGENTS.md` — API-specific patterns -->
<!-- - `src/components/AGENTS.md` — Component conventions -->

## Testing Approaches

<!-- Document how tests should be written for this project -->
<!-- Examples: -->
<!-- - Unit tests use pytest with fixtures in conftest.py -->
<!-- - Integration tests require DATABASE_URL env var -->
<!-- - E2E tests use Playwright -->
