track-work git:20261019.d8757acA

Immutable. This exact content never changes and is served at /api/v1/blob/c53ae0e6b33d44c3.

---
name: track-work
description: Perform one bounded TODO Flow work request from durable state and return a proposal, evidence, or a concrete decision wait.
---

# track-work

Read installed `project.json` for STATE and primary language, then STATE's `config/1.json`. Use the project language for user-facing reports and new documents unless explicitly overridden; default to English. Preserve protocol keys, identifiers, commands and source quotations.

Read task purpose and the supplied `workspace` and `paths`. Open the goal/condition document and relevant evidence, decisions and recent results by path. Search the actual workspace with file reads and rg/Glob/Grep; `context_patterns` are starting hints, not preloaded files or read-access controls. Choose the useful work now; no global phase order. Built-in workers have read-only exploration tools and return proposals; the runtime applies changes and runs verification. Never assume that a path in the handoff means its contents have already been read.

Return the worker JSON contract: summary, optional changes, verify, publish, next[{kind,purpose}], question, watches, findings[{observation,evidence}]. Use either changes[{path,content}] with complete UTF-8 contents, or changes[{path,format:"replace-v1",base_head,sha256,edits:[{old,new}]}] for existing UTF-8 files when the supplied schema supports it. Keep paths within configured writable patterns. Never change tests just to conceal a failure. Next kinds: assess, work, verify, review, land, triage, complete, watch. A question has no mutations or next requests. Store follow-up intent before the session ends; never rely on a parent receiving a chat reply. Current scope failures are work, not watch.

For replace-v1, copy the input head into base_head and compute lowercase SHA-256 over the original raw file bytes. Each nonempty old must occur exactly once in that original, including overlapping occurrences; all edit ranges refer to the same original and must not overlap. new may be empty. Preserve exact Unicode and line endings, and never search a previous replacement's output for a later edit. Use normalized relative paths without aliases or symlinks. Do not mix content with edit fields or invent versions. New files use full content. Existing files may also use `{path,content}` with complete UTF-8 contents. If permitted read-only tools cannot obtain the original SHA-256, use this full-content form without a hash; never guess a digest or broaden tool permissions to compute it. The host still checks allowed paths, the pre-execution HEAD and existing changes before applying the proposal. The host validates the complete batch before writing and supplies assembled full contents to merge-resolution checks. Existing claim, checkout and process barriers still apply. See the repository's examples/replace-v1.md and examples/replace_worker.py for the contract and command-worker example.

Keep each proposed change tied to a selected condition or an existing invariant affected by this change. Complete the smallest working path, including its required callers. A useful improvement, unrelated observed defect or hypothetical risk does not expand this track: record it as an optional finding when useful, rather than including it in changes or mandatory follow-up work. Fix demonstrated failures of the selected outcome and its existing invariants.

Honor recorded user decisions and accepted tradeoffs. Before claiming an extra capability or repository change is required, show the concrete failure of the existing supported path. Reconcile a genuinely necessary scope change through the document revision process; do not invent a dependency or ask again for authority already given.

With configured `verify_related`, intermediate change proposals run those explicit checks after any preflight. `verify:true` requests final full verification; publication and review/land/complete follow-ups also require full verification. Partial success is feedback only and cannot authorize those boundaries. When the candidate is ready, request final verification and independent review; do not split finished work merely to use intermediate checks. Without related checks, existing full verification remains the default.

For changed behavior, tie concrete inputs and expected results to a condition ID and its selected requirement or behavior to preserve. Justify expectations independently of the implementation; do not compute them by repeating its algorithm. For a bug fix, use the same focused check to distinguish the wrong behavior from the corrected behavior where practical. If changing an existing expectation, report its old/new result and the requirement or preservation evidence authorizing that change for independent review; matching the current implementation alone is insufficient. Existing `method`, test comments or visible analysis suffice; no new metadata or tests for every task are required.

Use the smallest meaningful checks for the changed behavior. Resolve formatting, lint and focused failures before the host's expensive final verification; keep test execution with the authorized host when the worker is read-only. Do not request full application tests for instruction-only edits, duplicate a successful unchanged check, or add review rounds without a concrete failure or evidence gap. Existing configured verification and independent-review gates still apply.

Before proposing another task, name the specific unmet user requirement or concrete correctness issue it resolves. If the requested result already has sufficient evidence, return completion through the required endpoint and stop. Choose the narrower scope for ordinary ambiguity instead of asking the user to manage optional work. Do not invent runtime or workflow changes to avoid making this stopping decision.

Report discovered additional work separately in the user-facing summary: what it is, why it is needed or optional, whether it blocks the original request, and whether it has started. Do not treat that report as authorization or include unrequested work in changes or executable follow-ups. Disclose any unrequested work already performed.

Persist concrete findings for post-landing triage. Fix known original-scope defects now or request work; do not conceal them as unrelated follow-ups. A post-landing repair uses a fresh branch/PR and must obtain new exact-head verification and independent review.