AGENTS.md · refactoringhq/tolaria

Sections

1. 1. Development Process
2. 2. Product Rules
3. 3. Reference
4. Stuck or blocked tasks

First lines (shown under the repo's AGPL-3.0 license)

# AGENTS.md — Tolaria App

## 1. Development Process

### Mandatory-rule exception protocol

Use an exception only when a required service or analyzer remains unavailable after one retry, or when satisfying the rule is technically impossible without increasing security or data-loss risk. The repository owner is the sole approver. Before proceeding, record the blocked command, evidence, affected files, risk, compensating check, approver, and an expiry of at most 72 hours in the Linear issue or final handoff; review and remove the exception within seven days. A preference, deadline, or failing quality gate is not sufficient exception criteria.

### Task tracking (Linear)

**Linear is the only live queue (cutover 2026-10-15).** Desktop work lives in team Tolaria (`TOL`), project **Tolaria Desktop**; mobile work in **Tolaria Mobile**; web work in project Tolaria Web. Do not create or move Todoist tasks. The old Todoist Tolaria project is legacy (its Draft section is being triaged separately); a completed Todoist card commented "Moved to Linear: TOL-n" points to its Linear issue.

**Linear** — workspace Refactoring, team Tolaria, issue key `TOL`.

- Workflow: **Backlog** (not ready) → **Open** (ready for an agent) → **To Rework** (review failed: read the latest review comment and fix only that; pick these **before** Open) → **In Progress** (claimed) → **In Review** (pushed, awaiting Luca's QA) → **Done** / **Canceled** / **Duplicate**.
- Claim an issue by moving it to In Progress only when a session actually starts work on it. At most one In Progress card per lane (Mac mini mobile: 1, agent-openai desktop: 1, agent-claude web: 2); release your current card (In Review, or back to Open with its Status line saying why) before claiming another; a card held only by "Waiting for main to go green" doesn't count. Never take another worker's In Progress issue; resume your own only when the card's Status line names your lane (e.g. "Codex (desktop) is working on it"). Re-read the issue after claiming and stop on a conflicting claim. Exception: follow the mandatory-rule exception protocol if Linear remains unavailable after one retry.
- Labels: type `Bug` / `Feature` / `Improvement`; `needs-luca` (only when a human decision or owner action is truly needed, always with a "Needs you" comment); `dubious` and `contributor-pr` (Backlog, awaiting Luca); Source group `Sentry` / `Canny` / `GitHub`. Exception: an unavailable Linear labeling service requires the same owner-approved exception protocol.
- No platform labels and no "blocked" label of any kind (Luca, 2026-10-23): the project decides the lane (Desktop → Codex on agent-openai, including Mac-specific work it can't test on Linux; Web → Claude Code on agent-claude; Mobile → the Mac mini). A stuck card goes back to Open with its Status line saying why and is retried on a later run with backoff; never label it as blocked.
- Reference the issue ID in commit messages, e.g. `fix: keep image width after restart (TOL-123)`.

### Linear comments (Luca, 2026-10-26)

Luca reads the comments, never the code. Each card gets at most three kinds of comment, in plain language:

1. **Status**: one comment per card, edited in place (never a new one). One line, e.g. `**Status:** Codex (desktop) is working on it`, `**Status:** Waiting for main to go green`, `**Status:** Didn't finish: <plain reason>. Retrying after 18:30 (Rome)`. Times are Rome local time.
2. **Ready for QA**: posted once, when the work is on main and all of CI is green. It contains:
   - `**Ready for QA: <short title>**`
   - `**What changed:**` 1–2 sentences, for the user.
   - `**Try it:**` 2–4 steps.
   - `**Proof:**` uploaded inline (see Proof before push).
   - `**Tested:**` one plain line.
   - `**Not tested:**` what wasn't tested, if anything (e.g. the macOS app from a Linux box).
3. **Needs you**: only when Luca has a decision to make. Give the question, the options and your recommendation in a few lines, and add `needs-luca`.

A failed QA, red CI or rework is a reply in the Ready for QA thread: `Didn't pass: <what went wrong>. Next: <what happens>`.

Never post start, claim or resume notices, heartbeats or no-progress checkpoints, retry or backoff counts, run IDs, commit hashes, file paths, log dirs, CodeScene, Codacy or coverage scores, raw logs, or UTC times. The full release record (checklist below) is an attached `release-record.md` file, not comment text.

Uploading: call the Linear `fileUpload` mutation, `PUT` the file to `uploadUrl` with the returned headers, then embed `assetUrl` (`![after](assetUrl)` for images, a link otherwise). On the Linux agent boxes the runner does this from the agent's `ready-for-qa.md`, `proof/` and `release-record.md`.

### Proof before push

No proof, no push. Collect proof before pushing; it goes inline in Ready for QA:

- UI change: before/after screenshots, or a short clip for interactions.
- Editor or serialization change: before/after `.md` round-trip files plus the regression test.
- Bug fix: the regression test's output failing before the fix and passing after.
- CI or infra change: a link to the green CircleCI run.

Risky areas also need a review of the diff by a fresh-context agent (a new session with no shared history) before push, and you fix what it finds. Risky areas are note save/serialization, sync/Git, the updater, and release/CI workflows. Luca never reviews code.

### Done gate (full CI)

Move a card to In Review only when every job in the CircleCI `validation` workflow on main for your commit is green, with none pending (web-gates and publish-mobile-alpha included). The same goes for "no change needed": check the current main. If main is red for another reason, keep the card In Progress with Status "Waiting for main to go green". If your commit broke main, fix it in one push or revert within ~30 min.

### Incidents

Every incident or revert adds a regression test. If it's a pattern, also add one line to this file.

- Web Playwright in WebKit (also the iPhone/iPad projects): the offline service worker can stall every later load of a page (a cancelled worker-served body, TOL-230; a navigation just as the new worker takes over, sharing.spec.ts). A spec that is not about offline read and hits such a stall blocks the worker (`serviceWorkers: "block"`, as sync-pill and sharing do) instead of retrying.

### Start working on a task

**Before writing a single line of code:** inspect the configured CodeScene project's current Hotspot and Average Code Health and compare them with `.codescene-thresholds`. Then capture the file-level Code Health score for every existing code file you intend to edit. If the project is already below the threshold, **stop and refactor first** — find the worst files with the MCP, improve them, commit, then start the task. If the gate cannot be restored, stop and obtain explicit repository-owner direction before starting feature work.

- Read task description and all comments fully
- For To Rework: Luca's latest comment, or the "Didn't pass" reply, tells you exactly what to fix
- Check `docs/adr/` for relevant architecture decisions before structural choices
- Check `docs/ARCHITECTURE.md` and `docs/ABSTRACTIONS.md` for relevant structural information
- For UI tasks: study app visual language and components first. Prioritize reusing existing components, assets, and variables over recreating them.
- If working on a Linear issue, set its Status line (create or edit it in place); never post a start comment

### Commits & pushes

- Local work may happen on `main`, in detached HEAD worktrees, or in other temporary local states. The production path is still direct-to-main: final verified work is pushed to `origin/main`, with no PR branch flow.
- Mobile foundation is integrated into main. New mobile work follows the same direct-to-main path; the historical foundation-branch fast lane is not the current delivery workflow.
- Commit every 20–30 min: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
- Pre-commit is a lightweight lint gate only. Pre-push runs the full check suite (build + tests + coverage + core Playwright smoke + CodeScene), preferably on three Chunk sidecar lanes for automatic test/coverage work: frontend lint/build/coverage, Rust coverage, and Playwright smoke. The goal is lower wall-clock time than local hooks while keeping each heavy gate isolated; keep local Playwright mainly for authoring, focused reproduction, or sidecar outages.
- CircleCI is the authoritative outer-loop CI/CD system. `.circleci/config.yml` owns validation, native cross-platform release builds, GitHub Release publication, and Pages publication.
- Any workflow or job that publishes GitHub Pages (today `deploy-docs.yml`, `release.yml` and CircleCI `publish-docs`) must build the site with `bash scripts/build-pages-site.sh <dir> [alpha-tag]`, the shared assembly that puts the tolaria.md landing at `/`, the docs, the release pages and the updater manifests (`latest.json`, `latest-canary.json`, `alpha/`, `stable/`) together and then verifies them. Never call `assemble-pages-site.sh` directly or hand-roll a Pages artifact; doing that once dropped the landing and made tolaria.md return 404. `scripts/verify-pages-site.test.sh` enforces this.
- **A task is NOT done until `git push origin main` succeeds.** If the hook blocks: read the error, fix it (clippy, tests, CodeScene, build), commit the fix, push again. If a verified push is impossible, stop and obtain explicit repository-owner direction; do not use `--no-verify` without that recorded approval.

### Mobile coding and release

The general coding, quality, localization, analytics, credentials and completion rules apply unchanged. Read the mobile sections of `docs/ARCHITECTURE.md` and `docs/ABSTRACTIONS.md`; ADRs 0247, 0263 and 0272 define OTA delivery and channel selection.

- Reuse `apps/mobile/src/components/ui` native primitives and `apps/mobile/src/ui` wrappers, not desktop DOM controls. Keep phone/tablet behavior on the shared controller/repository boundary. Run `pnpm mobile:lint`, `pnpm mobile:typecheck`, `pnpm mobile:test` and focused mobile regressions as well as the normal main push gates; scoped mobile checks do not replace them.
- Verify affected native behavior separately on iPhone, iPad and Android. Browser checks are not native acceptance. Record task-specific owner delegation of manual QA honestly; it does not waive automated gates. A locked Mac leaves affected checks pending while independent work continues.
- QA is confined to owned disposable vaults/simulators; existing user apps, containers and vault data stay untouched.
- CircleCI publishes mobile-related main pushes to **Alpha** after its required gates; desktop-only changes are excluded from mobile publication. Confirm the actual publication receipt, source SHA, runtime and update ID before claiming delivery. Native/configuration/dependency changes that alter the runtime require a compatible signed binary, not an incompatible OTA.
- Use one external **Tolaria Beta** TestFlight group. Settings defaults to **Stable**, with Alpha opt-in; selected channel and running update identity are distinct. Legacy Alpha-native binaries can launch embedded Alpha before preferences load. Retain runtime matching, safe editor flush/restart and Sentry artifact verification.
- **Stable promotion remains manual**, authorized explicitly by the owner and using the existing exact-tested-Alpha-artifact republish/approval workflow. Never rebuild from moving main or redirect Stable to moving Alpha. Do not submit Apple compliance declarations or grant new credential permissions without explicit owner authorization.

### Hourly mobile queue routine

Keep the scheduled prompt limited to queue orchestration; this file owns coding and release policy.

1. Reuse the routine's attached worktree and inspect current work. Resume its own identified unfinished claim before taking another issue; keep execution serial under the claim protocol above.
2. Otherwise paginate **Tolaria Mobile** To Rework, then Open; order by priority (unspecified last), then oldest creation time. Skip work assigned or delegated to others (including cards assigned to Luca for owner action), unmet dependencies, and cards whose Status line records a failed attempt less than 1 h ago (after a 2nd consecutive failure wait 2 h, after a 3rd 4 h, then 8 h). Do not pull Backlog or In Review into implementation. Follow the claim protocol above.
3. Implement the selected issue under this file's rules, including Linear comments, proof before push and the done gate. On a blocker, failure or session exit, edit the Status line with the plain reason (keep evidence and the checkpoint location in `release-record.md` or the worktree, not in comments; post "Needs you" only for a decision), then move the card back to Open (or to In Review if verified work landed on main) before claiming the next one; never leave a blocked card In Progress. Continue independent eligible work without mixing partial changes or extending exceptions.
4. Put verified implementation In Review with one Ready for QA comment (proof inline, iPhone/iPad/Android screenshots or clips for UI) and `release-record.md` attached, not self-approved Done. Report meaningful milestones or actionable blockers; stay quiet when the queue or status is unchanged. Resume remaining work on the next hourly run. Keep only one active mobile queue routine.

### TDD (mandatory)

Red → Green → Refactor → Commit. One cycle per commit. For bugs: write failing regression test first, then fix. Exception: pure CSS/layout changes.

**Test quality (Kent Beck's Desiderata):** Isolated · Deterministic · Fast · Behavioral · Structure-insensitive · Specific · Predictive. Fix flaky tests first. Prefer E2E over unit tests for user flows.

### Localization (mandatory for UI copy)

All user-facing UI labels/copy must live in `src/lib/locales/en.json` and be translated into every target listed in `lara.yaml`. Exception: when the localization service remains unavailable after one retry, use the mandatory-rule exception protocol above and do not release untranslated copy without repository-owner approval. When adding or changing interface copy:

```bash
pnpm l10n:translate
```

Use `pnpm l10n:translate:force` only when intentionally regenerating existing translations. Commit `src/lib/locales/*.json`, `lara.yaml`/`lara.lock` changes if produced, and verify placeholders/product names stayed intact.

### Product analytics (mandatory for meaningful features)

New features should emit a PostHog event so we can see whether users actually discover and use them. Skip instrumentation when the change has no meaningful user action or when a dedicated event would create noise; record that reason in the release record. If the correct instrumentation remains unclear, obtain repository-owner direction before release. Use clear, stable event names, avoid PII or note content, and include only safe metadata that helps evaluate adoption and failures.

When adding or changing a meaningful user-facing feature, include the event name(s) in the release record alongside QA, docs, and code health. If intentionally not instrumenting a feature, explain why there.

### Code health (mandatory)

Pre-push compares **Hotspot Code Health** and **Average Code Health** with the exact numeric floors in `.codescene-thresholds` and fails when either score is lower. Pre-commit is lint-only; CodeScene remains mandatory through the file-level review rules below and the pre-push ratchet gate. Thresholds are a **ratchet** — only go up. When pre-push sees improved remote scores, it updates `.codescene-thresholds`, stages it, and stops so you can commit the new floor with normal verified hooks before pushing again. Exception: adding `// eslint-disable`, `#[allow(...)]`, `as any`, or another bypass requires the mandatory-rule exception protocol and repository-owner approval before the edit.

**Release rule:** CodeScene is a before/after gate, not just a final score. Record the starting CodeScene state before edits and the final state after edits. If touched code gets worse, refactor before committing; if the comparison cannot be produced, stop and obtain explicit repository-owner direction.

Do not edit `.codescene-thresholds` to lower the values. If the gate blocks you, improve the code; any proposed exception requires explicit repository-owner approval recorded before the edit.

**CodeScene access order:** use CodeScene MCP tools if available. If MCP is unavailable, use the installed `cs` CLI for file-level review/delta work, and use the CodeScene API (`CODESCENE_PAT` + `CODESCENE_PROJECT_ID`) for project-wide Hotspot/Average threshold checks from `.codescene-thresholds`.

**Before editing any existing code file:** capture its current file-level CodeScene score. After your edits, re-run the same file-level review and verify the score is higher. If the file already starts at `10.0`, it must remain `10.0`. Exception: if the score cannot be obtained after one retry, use the mandatory-rule exception protocol and obtain repository-owner approval before editing.

**New files:** every new **scorable code file** must reach CodeScene score `10.0` before commit. If CodeScene reports `null` / "no scorable code" for a new file, it must still have zero CodeScene findings/warnings. If either requirement cannot be met, stop and obtain explicit repository-owner direction.

**Before every commit:** run CodeScene file-level review on every touched or newly created code file and verify the rule above. Then run `mcp__codescene__pre_commit_code_health_safeguard` for the repository and do not commit unless its quality gates pass. **Boy Scout Rule:** every file you touch must leave with a higher score, unless it was already `10.0`, in which case it must stay `10.0`. If an analyzer or gate is unavailable, stop and obtain explicit repository-owner approval for a documented exception.

**Before the final direct-to-main push:** run `mcp__codescene__analyze_change_set` with `base_ref=origin/main`. This is Tolaria's PR-preflight equivalent: every affected file must be improved or stable, and the overall quality gate must pass. Refactor and repeat if any file is degraded. Exception: if the analysis cannot complete after one retry, use the mandatory-rule exception protocol and obtain repository-owner approval before pushing.

**If CodeScene gate blocks your push:** use `mcp__codescene__code_health_score` to find the worst file, refactor it, commit, push again. Do not wait for laputa-refactor because it is a background loop rather than a substitute for fixing your own regressions; if no in-scope refactor can restore the gate, stop and obtain explicit repository-owner direction.

### Security scan with Codacy (mandatory)

Use Codacy as a security and static-analysis gate before a task is considered releasable.

- **Two required checks:** Codacy's local CLI/MCP analyzes the uncommitted working tree, while the Codacy dashboard also runs server-side tools after a commit is pushed. These are complementary gates. Report each count with its source; if either check is unavailable, stop and obtain explicit repository-owner approval instead of substituting one for the other.
- **What counts as new code:** both a newly created code, test, script, or executable configuration file and any added code in an existing file. Scan the entire containing file, not only the added lines, because Codacy tools can report findings on unchanged lines or at file level after a change.
- **Build the scan manifest:** before each Codacy check, enumerate added and modified tracked paths with `git diff --name-only --diff-filter=ACMR "$(git merge-base HEAD origin/main)" --` and untracked paths with `git ls-files --others --exclude-standard`. Classify every code, test, script, and executable configuration path as new or existing, record the manifest in the task evidence, and scan every path individually. Rebuild the manifest immediately before commit so no late-created file is omitted.
- **Before editing existing code:** run a local file scan and record every finding for each code file you intend to touch. Also record that file's findings on Codacy's currently analyzed `main` commit using `codacy_list_files` to resolve the file and `codacy_get_file_issues` to enumerate all paginated results.
- **Local file scan:** use `mcp__codacy__codacy_cli_analyze` with the repository's absolute `rootPath` and an explicit `file`, one touched/new file at a time. If the MCP is unavailable or fails, run `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 .codacy/cli.sh analyze <path> --format sarif --output /tmp/codacy-<slug>.sarif`. Omit `--tool` so every locally configured analyzer runs. Explicitly inspect every `runs[].results[]` entry in the SARIF output.
- **Analyzer-parity gate:** before creating or modifying code, call `codacy_list_repository_tools` and record the enabled dashboard analyzer name, UUID/generation, configuration mode, and language coverage. Compare that roster with the `runs[].tool.driver` entries produced locally for every language in the scan manifest. Tool names alone are not sufficient: deprecated ESLint/ESLint8 and current ESLint9 are different analyzers, and a local run of Lizard, Opengrep, and Trivy does not prove that dashboard ESLint will be clean. For TypeScript/JavaScript, the passing roster must include the current analyzer that honors `eslint.config.js`, plus every other enabled relevant dashboard tool. If the intended analyzer is disabled, a deprecated analyzer is enabled, or any enabled dashboard analyzer has no equivalent successful local run, analyzer parity fails: stop, correct the Codacy tool configuration, trigger a full reanalysis, and verify parity before code work. A repository-owner-approved exception is required if configuration access is unavailable.
- **Approved analyzer-parity exception (Biome):** Biome is enabled on the Codacy dashboard but missing from the local Codacy CLI. Biome: covered locally by the repo's own Biome (`npx biome check <changed files>`, or the repo's existing Biome run in `pnpm codacy:gate`); approved by Luca 2026-10-10. This is a standing exception recorded here, so it needs no per-task re-approval: record that `npx biome check` run as the local Biome row in the parity and per-file evidence. It covers only the missing local Biome run; any Biome diagnostic on changed files still fails the gate, and every other analyzer must still match.
- **Per-file analyzer evidence:** for every new code file, record one result row per expected analyzer with the exact file path, analyzer identity, completion status, and finding counts split into Critical/High/Medium/Minor/Info/unclassified. Missing rows, a skipped/untracked target, an analyzer crash, or an analyzer that silently omits the language is a failed scan, never a zero. If the CLI requires Git discovery, add the file to the index normally before the final scan; do not rely on a directory scan to discover an untracked file.
- **Fail closed on partial scans:** a zero process exit code is not enough. Confirm the expected relevant tools produced SARIF runs and inspect scan logs for crashes, encoding failures, skipped target files, partial analysis, or missing tool output. If any relevant analyzer did not complete, the scan did not pass.
- **Approved analyzer-coverage exception (unsupported or excluded files):** if Codacy or CodeScene does not support a file type, or excludes the path from analysis (for example test paths, `.husky/*` hook scripts), an agent does not need a pre-edit baseline or a post-edit score from that tool to edit the file. Record "not analyzed by <tool>: <unsupported|excluded>" as that tool's row in the parity/per-file evidence. Likewise, when an enabled dashboard analyzer has no local equivalent for a file type (for example Jackson Linter for `src/lib/locales/*.json`), cover it locally with the repo's own check (`node scripts/validate-locales.mjs` plus a JSON parse for locale catalogs) and record that run. Approved by Luca 2026-10-13; standing, no per-task re-approval. Every other gate still applies: the other tool's baseline and Boy Scout rule where it does analyze the file, zero new findings, tests, coverage, pre-push hooks and post-push verification.
- **Zero-new-findings rule:** added or modified code must introduce no Codacy finding at any severity, including Info/Minor, Warning/Medium, High/Error/Critical, unclassified findings, and findings reported on unchanged lines or at file level because of the change. If this cannot be achieved, stop and obtain explicit repository-owner approval for a documented exception.
- **New code — absolute zero rule:** every new code file and every file containing newly added code must be scanned explicitly after creation or modification and must have exactly zero findings attributable to the new code at every severity. A newly created file must have exactly zero findings in the whole file. For added code in an existing file, any finding on an added line, caused by an added symbol or dependency, or newly appearing at file level fails the gate. `0 Critical + 0 High + 0 Medium + 0 Minor + 0 Info + 0 unclassified` is the only passing result. If a scanner cannot prove this, stop and obtain explicit repository-owner approval before proceeding.