git:20261101.e21cd74 to git:20261101.03d46ca

# Repository Working Agreement

## Required development context

Before planning or changing this repository, read this file, the

[development skill](.agents/skills/tmt-dev/SKILL.md),

[architecture](ARCHITECTURE.md), [coding conventions](CONVENTIONS.md), and

[development/verification guide](DEVELOPMENT.md). Inspect the relevant source

and issue as well. Use the linked E2E or release skill when applicable. If a

required reference is missing or contradicts the code, report and resolve that

discrepancy within scope before relying on it; do not invent a convention.

## Context and evidence budget

- Read required instructions completely once per task, in bounded chunks. Reread

them only when they may have changed or you are unsure.

- Locate the relevant source and guide sections before reading broadly. Keep bulk

inventories and logs in files or artifacts, and verify published text with an

equality check or a focused diff against its source.

- Hand off decisions, unresolved risks and evidence locations, not transcripts.

While waiting on a gate, prepare only the next step.

These limits reduce repeated input; they never replace required review or verification.

## Architecture ownership and primary review

The owner splits the work into squads; the pinned team issue (#606) records each

squad's lead, owned paths and contracts, and how squads communicate and merge.

The core lead owns the architecture: core paths and contracts, the seams between

squads, and the product's guiding principles. Within its owned paths and

contracts, a squad lead decides on its own, including architecture and design

choices, staffing within the recorded limits, and alpha releases of its

components. Stable releases, breaking changes and any other publishing

authorization stay with the owner.

Bring only decisions that change core paths, core contracts or a seam between

squads to the core lead.

A squad lead is the primary reviewer for pull requests confined to its squad's

paths. Members implement; the reviewing lead keeps the design and stays

accountable. Before accepting any work, including its own, the primary reviewer

personally reads every changed file's diff and surrounding implementation,

relevant callers, contracts, and tests. Assess dependency direction, module

responsibility, reuse, compatibility, state/failure behavior, readability, and

test validity—not only whether the ticket or CI is green. An independent

reviewer is supplementary, not a replacement.

A change to shared paths needs review from the lead of every squad it affects:

contracts, `.github/`, `AGENTS.md`, guide index sections, workspace

configuration and lockfiles, and any change to another squad's paths. A squad

does not edit another squad's paths directly; it files an issue for that squad,

unless the owner gave it a cross-cutting mandate recorded in #606, such as the

refactor squad fixing what it finds. Such a change still needs the owning

squad lead's review.

Record the reviewed commit, affected boundaries, findings and their disposition,

and verification evidence in the PR and GitHub issue. If there are no findings,

state what was inspected rather than merely saying "LGTM". Review later changes

and rerun affected checks before accepting a newer head.

For every PR, follow the [architecture maintenance contract](ARCHITECTURE.md#maintenance-contract):

update affected architecture and developer guidance in the same PR, or explain

why the change does not affect them. The implementer proposes documentation

updates; the primary reviewer verifies them against code before merge. A linked

follow-up is not permission to ship inaccurate descriptions of current behavior.

## Pattern audit before changes

Before editing code or guidance, inspect relevant architecture, helpers, fixtures

and conventions for reusable patterns, duplicate responsibility and conflicts.

Keep inspection proportional; record material findings and resolve them within scope.

Give each member one bounded topic with an explicit owner, done condition and

is a staffing decision recorded with the team, not a repository rule.

Delegation never expands authorization.

## Repository content language

All repository content must be written in English, including code, tests,

comments, documentation, configuration, workflows, repository skills, commit

messages, and pull request metadata. Non-language symbols and technically

required fixture data are allowed when necessary; explain any such exception

in English.

Exceptions: translated handbook prose and UI strings may use the language of

`site/src/i18n/<lang>/`. Approved blog article prose and metadata title/summary

may use the language of `site/src/posts/<slug>/<lang>/` (`ja`, `zh-hant`, `zh-hans`).

Each directory requires its matching `languageExceptions` entry in

[the layout map](.github/repository-layout.json), added with its first tracked

translation. Blog translations require independent approval; English stays at

the slug root. Keys, code, comments, tests and all other content remain English.

## Durable documentation

Keep living documents focused on current results, definitions, contracts and

clearly labeled proposals. User and developer guides may include actionable

instructions and the constraints needed to use them safely. Keep implementation

chronology, rejected alternatives, per-run logs and review evidence in issues/PRs

or pinned history, not repeated in manuals. Preserve non-obvious invariants and

fixture provenance. Each definition has one document owner; other guides link

to it rather than copying it. Removing narrative must not remove a safety gate

or present planned behavior as shipped.

When revising guidance, replace or consolidate overlapping rules before adding

new ones. Resolve contradictions against the owning contract and verified behavior;

ask when resolution would require an undecided product or authorization choice.

## Delivery lifecycle

- GitHub Issues is the active tracker for TMT. Historical Linear links are

references, not a second workflow or a requirement to duplicate tickets.

- Keep decisions, progress, blockers, deferred work, branch/PR links and evidence

synchronized in GitHub. Do not mark work done before its delivery state supports it.

- Keep the issue's Project fields, tracker parentage and Status current as defined in

[Project tracking](DEVELOPMENT.md#project-tracking).

- Every agent-created commit ends with its provider's co-author trailer, such as

`Co-authored-by: Codex <codex@openai.com>` or

`Co-Authored-By: Claude <noreply@anthropic.com>`, plus any session trailer its

harness requires. Preserve the user's authorship and signing configuration.

- Every PR body names its contributors with visible `Agent:` lines; see the [attribution grammar](.agents/skills/tmt-release/references/native-release.md#pr-agent-attribution).

- Authors finish and verify their own work before asking for review: rebased,

every check green on the exact head, PR body complete (Fixes and Agent lines).

The review request names that head. Authors own CI end to end (watch,

rerun, fix); nobody asks a lead to watch CI. Leads gate (review, design, seams,

merge decision) and do not babysit: no CI watching, no chasing members for status.

- After starting a CI, merge-queue or long-build wait, end the turn and let one

message wake you: start `scripts/ci-wake.sh` (see

[DEVELOPMENT](DEVELOPMENT.md#waiting-on-ci-and-the-merge-queue)) or a provider-native

background task whose completion the harness delivers (Claude `run_in_background`).

Never `wait`, `sleep`, `wait_agent` or poll it from the main session; where

neither can run, use one long-interval monitor or the seat's cheapest subagent

that reports only the final state.

- Merge only when authorized and all required CI has passed on the reviewed head.

Never bypass protection or lower checks to deliver. Publishing, releases and

destructive operations require their own applicable authorization.

- Before removing a completed worktree, verify it is clean, committed and safely

pushed or handed off, with branch/PR recorded in GitHub. Do not discard user

changes or unpushed work. Remove the safe worktree and prune stale metadata.

- Follow the [release skill](.agents/skills/tmt-release/SKILL.md) for branch-line

policy; do not duplicate or improvise long-lived branch rules here.

## Code organization

Follow the [layout procedure](.agents/skills/tmt-layout/SKILL.md) when adding or moving repository files.

- Prefer fixes that simplify ownership and data flow over accumulating defensive patches. Before adding flags, counters, branches or abstractions, check whether moving responsibility to its natural owner or removing redundant state eliminates the defect. Judge simplicity across the affected flow, not by the smallest diff. Keep necessary trust-boundary validation and behavior tests; this is not permission for unrelated rewrites.

- Before launch, breaking refactors are allowed within the agreed scope. Do not retain obsolete APIs, commands or compatibility layers solely to preserve an unreleased design. Update callers, tests and guidance together; this does not authorize discarding user data or uncommitted work.

- Keep production behavior, test infrastructure, fixtures, and scenario assertions in clearly separated modules.

- Prefer small, purpose-specific interfaces and existing dependency-injection boundaries over new global state or parallel abstractions.

- Put shared behavior in one named helper only after more than one caller needs it; keep scenario-specific behavior close to the scenario.

- Use names that describe observable behavior and stable domain concepts rather than implementation accidents.

- Keep completion criteria bounded to the agreed outcome. Classify adjacent findings

as blocking correctness/security defects or deferred improvements; explain the

dependency before expanding scope. Do not silently turn optional hardening into

a milestone gate or declare unresolved blockers complete.

## Host tmux safety

The tmux server an agent runs in hosts the whole team; losing it stops every agent

(#4189). This is a hard rule, not a test-quality preference:

- Any test, fixture, script or experiment that starts or drives tmux runs with

`env -u TMUX -u TMUX_PANE`, uses its own `-S` socket in a private temp directory,

and asserts that socket is not the host default (`tmux-$UID/default` under

`$TMUX_TMPDIR`, else `/tmp`; `/private/tmp` on macOS) before any server command.

- A test runs `kill-*` only on a server it created. On the host server, never run

`kill-server` or `kill-session`, and never change server options or hooks. There,

use `tmt` commands, and read or type into an explicit pane or window you are

responsible for (`list-*`, `capture-pane`, `send-keys -t <target>`). A lead may

also open a member window in its own squad session (`new-window -t '=<session>:'`)

and retire one by exact name (`kill-window -t '=<session>:=<name>'`; the `=`

turns off tmux prefix and pattern matching); no other `kill-window` or

`kill-pane` runs on the host.

A bare `tmux` in an agent shell reaches the host through the inherited `TMUX`, so

never use one for a scratch server.

- If a command reaches the host server by mistake, stop at once, tell your lead,

and do not retry. Change the approach, and get it reviewed, before continuing.

## Verification quality

- Verify observable behavior and durable state, not only exit codes, log echoes, snapshots, or test counts.

- Include representative success, failure, cleanup, and lifecycle cases for the changed behavior.

- Prefer deterministic readiness signals and bounded polling over fixed sleeps.

- Treat false positives, leaked processes, leaked tmux servers, non-isolated state, and any test that opens the host browser or touches host stores as test failures; host tmux is covered by [Host tmux safety](#host-tmux-safety).

- Run the repository checks relevant to every changed layer and report the exact commands and results.