# Repository Guidelines

## User-requested scope

Always work only within the scope the user actually requested or explicitly authorized. Do not independently expand the task with additional fixes, cleanup, refactors, or improvements, even when they are related to the requested work.
Perform the verification, review, and delivery needed for that authorized scope. Report newly discovered issues separately; discovering an issue does not authorize fixing it, reopening a completed track, or starting follow-up work.
Once the requested outcome is delivered, stop. Additional work requires an explicit user request. Clearly distinguish completed delivery from any separately authorized follow-up work in status reports.
Report additional work to the user separately: describe the work, why it is needed or optional, whether it blocks the original request, and whether it has been started. Reporting does not authorize execution. Leave work outside the authorized scope unstarted until explicitly requested; do not hide it inside the original task or silently register new tasks. If unrequested work has already been performed, disclose what changed and its current state.
Own the stopping decision: the user must not repeatedly tell you to stop. Before continuing, identify the specific unmet requirement or concrete correctness issue that the next action resolves. If the requested result and required evidence are sufficient, finish without adding checks, improvements, or a permission question. Resolve ordinary ambiguity by choosing the narrower scope; ask only when missing information materially affects correctness, authorization, or an irreversible action. Do not introduce runtime mechanisms or process changes merely to compensate for this judgment. When the user asks to persist a working rule, edit the applicable instructions in that turn and report the actual file changes; a conversational promise is not completion.
For authorized track runs and landings, never disable automatic cleanup in configuration, command flags, temporary drivers, or recovery scripts unless the user explicitly requests retaining those resources. Convenience, debugging, or an intention to clean up later is not authorization. Keep any requested exception scoped and report it. Code landing does not prove resource cleanup: report actual removal or the concrete reason for deferral using cleanup receipts and the relevant Git/Orca inventory, while preserving ownership and user-data protections.
A trackrun is incomplete while any resource created for that run remains pending cleanup or the delivered changes have not been synchronized to the primary local checkout. Code landing or a `done` track record is not run completion. Resolve recoverable cleanup deferrals within the authorized run, including unused creation shells and interrupted retirement receipts, then verify absence in both Git and Orca inventories. Do not stop at reporting a deferral or ask the user to request cleanup again. Preserve user changes and reused sessions; if they genuinely block removal, report the run as incomplete with the exact blocker rather than complete. This obligation is cleanup of the selected run, not permission for an unrelated cleanup campaign.
After confirmed landing, synchronize the configured base branch in the primary local checkout with the landing remote using `git pull --ff-only`, before reporting the trackrun complete. This is part of the authorized run and requires no separate user request. Verify that the landed commit is included in local HEAD and the local base branch is not behind its remote; report local synchronization separately from remote landing and resource cleanup. Preserve user changes and branch choice: do not force a checkout, reset, rebase or stash to make synchronization succeed. If safe fast-forward synchronization is blocked, report the exact blocker and keep the run incomplete. If the user has already synchronized the checkout, verify that state without repeating the pull.
Source: the user's 2026-10-04 clarification explicitly makes pulling landed changes into the local checkout part of trackrun's responsibility. Public-safe counterexample: remote landing and cleanup are complete, but local `main` is eight commits behind `origin/main`; reporting the run complete is premature. Check the landed commit with `git merge-base --is-ancestor` and compare the local base branch with the fetched remote base using `git rev-list --left-right --count` and `git status`.

### Reusing confirmed feedback

Keep feedback beside the applicable instruction or regression test, with its source, scope, a public-safe counterexample and a way to check it. This section explains the scope rules above; it is not a separate rule ledger. A confirmed instruction and an implementer's proposal have different authority. Record an explicit user instruction or decision as the source; a commit, implementation summary or repeated suggestion alone does not establish user approval.

Concrete source: the user-supplied worker request for `confirmed-feedback-rules`, revision 3, task `work-16fc2dbe79e04da5`, explicitly instructs: “Tie every proposed change to a selected condition or an existing invariant affected by this change.” It also says: “A useful optional feature, unrelated observed defect or hypothetical risk does not expand this track.” These current instructions reaffirm the existing user-requested scope boundary above. They apply to selecting changes and mandatory follow-up work for the authorized outcome; they do not waive its verification, review, delivery or cleanup obligations. This is a source for the current reaffirmation, not a claim about the original private conversation. `git show 7b48077 -- AGENTS.md` shows the earlier scope guidance and `git show 52de599 -- AGENTS.md` shows its cleanup clarification; those commits establish change history, not user approval. The track's historical `assets/evidence.json` has classification `source-review-and-proposal` and empty `observations`; it establishes neither measured benefits nor user confirmation.

Public counterexample (illustrative, not an observed incident): a user requests a README correction; the implementer writes “also refactor the dispatcher while here.” That note is an unconfirmed proposal, not permission. Deliver the correction and required checks; report the optional refactor separately without starting it. By contrast, the explicit instruction quoted above is an applicable requirement. Review each proposed change against the selected condition or affected invariant and the recorded decisions. Merely labeling a note “confirmed” cannot supply missing authority; retain it as a proposal when the source is absent.

Maintain the existing entry rather than copying it into another registry. For example, clarify an ambiguous “stop after delivery” statement in place to include the selected run's required cleanup, preserving its scope; the cleanup clarification in `52de599` illustrates such an amendment. If a later explicit user decision replaces a rule, revise or remove the superseded wording at that same location, cite the decision and update affected references. Track the change with `git log -p -- AGENTS.md` or the existing track document revisions. A proposed retirement is not effective merely because an implementer suggests it.

Recording a rule does not satisfy an unmet condition or dispose of a finding. For example, documenting “original obligations cannot escape” while an original defect remains still requires correction and the applicable review/triage gates. Existing checks in `tests/test_triage.py` cover this boundary: `test_disposition_batch_is_atomic_and_original_scope_cannot_escape` rejects an in-scope obligation moved to a new track without partial registration, and `test_new_finding_invalidates_clear_receipt_and_old_completion_cannot_skip` shows that a new finding invalidates clearance and blocks completion. These checks protect runtime obligations; they do not prove the authority of a feedback source. For instruction-only changes, inspect the source, scope, counterexample and references through document review. For changed runtime behavior, apply the necessity decision in Changes and tests before adding or running a regression. Preserve independent-review gates and report verification evidence honestly; do not add tests that merely assert this prose exists.

## Layout

- `src/todo_flow/`: Python CLI, canonical HTML/Markdown documents and JSON files, disposable query cache, dispatcher, agent/GitHub adapters, loopback dashboard.
- `skills/`: agent-facing skills; packaged into the Python wheel.
- `templates/`: agent-authored track document schema/example.
- `tests/`: unittest store, real local Git integration, HTTP, adapter and large-list projection tests.
- `scripts/`: reproducible public GitHub acceptance tests and labeled local dashboard fixtures.
- `assets/metrics/`: anonymous aggregate measurements, methodology, and generated public charts. Keep raw source histories and identifying metadata outside this repository.
- `docs/`: local-only design specifications, prototypes, and experiment records; ignored by Git and excluded from distributions. Preserve local files and do not force-add them.
- `README.md`, `README.ko.md`, `AGENT_INSTALL.md`, `OPERATIONS.md`, `UPDATES.md`, `DEMO.md`, `CHANGELOG.md`, `CONTRIBUTING.md`: tracked usage, change history, and contributor guidance. Shared instructions must work without `docs/`.

## Commands

`uv sync --frozen` installs the editable package and pinned development tools.
`uv run python -m unittest discover -s tests -v` runs tests.
`uv run ruff check src tests scripts` and `uv run ruff format --check src tests scripts` validate Python.
`uv build` produces the distributable package. See README for runtime setup.

## Invariants

Use descriptive Python identifiers and Ruff formatting. Core runtime uses the standard library; Markdown rendering uses pinned markdown-it-py.
Track authoring belongs to the todo skill/CLI; selection is dashboard/track-picks; execution is trackrun IDs.
Do not add dashboard authoring or execution requests. Track documents are human review artifacts: preserve HTML, SVG, images, JS simulations and revisioned assets; Markdown must render to HTML. Files are authoritative; SQLite is a rebuildable query cache.
A model proposes work; only the fenced host writes files and external effects.
Pass workspace and evidence paths to workers; do not inject repository file bodies into their prompts. Keep built-in exploration read-only. For every current and future agent provider, the first-choice execution path is a visible Orca agent session in the task's own managed worktree. Headless execution is fallback only when that route is demonstrably unavailable or cannot preserve the required execution contract, unless the user explicitly requests headless. A headless command such as `claude -p` inside an Orca terminal is still headless; a visible wrapper or `backend=orca` does not establish an interactive agent session. Do not select headless solely because of the provider name or silently treat missing provider integration as the intended default. Record and explain the concrete fallback reason. Preserve read-only exploration, host-owned writes, complete proposal collection, session ownership and actual PID/exit evidence; never duplicate an uncertain launch through a fallback.
Source: the user's 2026-10-04 instruction states that headless must be fallback for Claude and any agents added later, and Orca terminals must always take priority. Public-safe counterexample: `auto` opens a terminal in the primary checkout and runs a new provider with a print-mode flag, then reports it as a worktree agent session. Check the actual provider argv, session receipt and Orca terminal/worktree identity, not just the launcher label. This is the required routing policy; documenting it does not establish that an existing provider adapter implements it.
Do not weaken exact-head evidence, independent review, durable handoff, or ownership checks.
Confirmed landing must be triaged before completion; original obligations cannot escape to follow-up TODOs or Watch.
Dispositions, registration and follow-ups commit atomically. New tracks await user selection.
Dashboard lists use bounded server queries; completed tracks have a separate archive.
Queries never mutate execution. UI connection loss never means completion.
Keep credentials, state databases, agent transcripts and local virtualenvs out of Git.

## Changes and tests

Decide whether a check is necessary before starting it. Identify the concrete defect or affected behavior it can detect in the authorized change, and why existing evidence or direct inspection is insufficient. Execute only checks with that justification. If a check is unnecessary, or its necessity cannot be determined, do not run it. Uncertainty is not a reason to run a test just in case. Apply this decision to individual tests, lint, formatting, builds, whole suites, and commands or workflows that launch checks indirectly; do not start a blanket verifier before assessing the checks it invokes. Speed or parallel execution does not make an unnecessary check necessary.
For instruction-only edits, review the changed text and references; do not run application tests. For runtime changes, use the least costly check that addresses the identified defect. Use real Git repositories, subprocesses, interruption scenarios, or external services only when their actual behavior is needed to establish the changed product behavior and a simpler check is insufficient. Do not test Git or another dependency merely to reconfirm its established behavior.
Reuse successful evidence for the same candidate and unchanged verification inputs. A changed input, failure, existing test, or configured project gate is a reason to reassess necessity, not automatic justification to execute or broaden checks. Independent review should consume existing evidence. Preserve exact-head evidence, independent-review and ownership requirements; never label an omitted check as passed or fabricate satisfaction of a gate. If a skipped check leaves an actual delivery requirement unmet, report that specific limitation rather than silently running it or claiming completion.
Source: the user's 2026-10-19 instruction explicitly requires deciding whether a test is necessary before execution, running only necessary tests, and not running a test when that judgment cannot be made. This replaces the earlier default of proceeding with configured full verification. Public-safe counterexample: a wording correction triggers a full Git recovery suite because the verifier includes it, or uncertainty about relevance prompts a “just in case” run. Both should be omitted. Check compliance by comparing each executed command with the affected behavior and the stated reason existing evidence was insufficient; no executable test of this prose is needed.
For this repository's local trackrun, `.todo-flow/verify.py` calls `scripts/verify_selected.py` with the primary checkout's `.todo-flow/verification-plans.json`. Before requesting verification, the coordinator records its necessity assessment for the candidate Git tree there, following the README format. This is an agent judgment, not automatic file-based test selection. No assessment means no checks execute; do not replace that result with a full-suite fallback. Review the selected checks and omissions with the change. The selection file and runner are declared verification identity inputs, so changing the decision invalidates previous evidence. Do not revise them during an active verification.
Test observable behavior and recovery boundaries, not implementation-shaped snapshots.
External live tests require explicit authorization and use disposable, public-safe fixtures.
Do not alter private/production repositories to exercise test workflows.
Use imperative commit subjects and report validation and real limitations accurately.

## Language and public presentation

English is primary for shared docs, templates and skill instructions. Keep the Korean README current.
Use project `language` for new human-facing worker output and documents, with stable protocol keys.
Dashboard labels use `tr()` / `data-i18n`; never translate authored content or rewrite records on a UI switch.
Keep language preferences isolated by project and preserve selection, drafts and navigation on switching.
Jev is an optional recommendation in todo/watchlist, never an execution or installation prerequisite.
Public demos must disclose synthetic data. The project is MIT licensed.
Run `node --test tests/dashboard_i18n.test.cjs` for localization behavior.

## Update boundaries

Package version and state/config/worker/skill protocol versions are independent. Check compatibility before recovery writes; do not silently downgrade unknown formats. CLI/driver/dashboard lifetimes participate in maintenance locks. Keep engine recovery independent of the environment being replaced. Skill updates compare managed-file baselines, preserve project context and local edits, and reject conflicts before mutation. Preserve durable receipts and test interrupted updates. The isolated update smoke uses synthetic future versions only; never publish its wheels.