tama task scope

Declares, shows or clears which registered work one session is serving — a defect in Oko's register or a task in its task register — and which repositories that work touches. The block-off-task-work gate checks every write against this declaration: a call that changes a repository outside it is refused with the declaration to make.

#Invocation

tama task scope show --session <ID> [--json]
tama task scope set --session <ID> [--repository <NAME>]... [--defect <ID>] [--task <ID>] [--json]
tama task scope clear --session <ID>

#Inputs and options

#What set writes

The declaration is bound to the latest captured operator turn: its digest is stored beside the defect, task and repositories under ~/.tama/task-scope/<session>.json, so a future prompt cannot silently inherit it. show reports whether the scope still serves the current instruction:

working  task task-d6c1ffa06b19682f
task     <the operator's words>
touches  oko, oko-landing
current  yes — this scope was declared for the instruction being served

After the operator speaks again, current reads no — the operator has spoken since; declare the scope of the new instruction, and the gate refuses writes until set runs again. set prints task scope for session <ID>: <repositories> for task <ID> and the instruction it was bound to; clear prints task scope cleared for session <ID>, or session <ID> had no task scope when there was nothing to remove.

#Output document

{"session":String,"turn_digest":String,"task":String,"repositories":[String],"defect":String,"task_id":String,"serves_current_instruction":Boolean}

#Refusal boundary

A wrong invocation exits two with the usage line or the sentence that names what is missing: a verb other than show, set or clear, an unknown option, a missing --session, a --repository outside the workspace, or a set that names no entry or no repository:

task scope requires --session ID: a scope belongs to one session's instruction, and no other session's instruction stands in for it
--repository <value> is not inside the workspace, so no change could ever match it; name the repository, for example `--repository oko`
task scope set requires --defect <ID> or --task <ID>: every change belongs to a defect in Oko's register or a task in its task register, and a change that belongs to neither is the drift this gate exists to stop
task scope set requires at least one --repository, or a --task whose Oko contract lists its scope (`oko tasks state <task> --scope <repo>`): work that touches nothing changes nothing

A well-formed set that names nothing the registers hold open exits one:

Oko's register holds no defect <ID>: <Oko's answer>
defect <ID> is already closed, so no work belongs to it; record what is wrong now with `oko defects record`
Oko's task register holds no task <ID>: <Oko's answer>
task <ID> is not open, so there is no work to resume
no operator instruction is recorded for session <ID>, so there is nothing to declare a scope for; the capture hook records it when the operator writes

Another session declaring the same defect is not a refusal. The command prints who else declared it and directs the sessions to read the shared notes and work together using anchored edits; it still records the scope.

A session that recorded a defect with no fix and no repair plan is told that this is its first work, and how to plan it and take it up. show on a session with no scope exits one and names the set to run. A scope file that cannot be created, written or removed is reported with the path and the cause.

#Tama Desktop

The Session screen shows, declares and clears the selected session's scope beside its last turn ending, through tama request task-scope/show, task-scope/set and task-scope/clear. Each takes {"session": "<ID>"}; set also takes "repositories" (a list of names), "defect" and "task". They run the same declaration as the verbs: show answers {"session", "scope"} with the output document above or null when none is declared, set answers {"session", "scope", "notice"} with another session's declaration of the same defect as the notice, and clear answers {"session", "cleared"}. A request that exits two on the terminal is a bad request carrying the same sentence, and one that exits one is a failure carrying it. The real test is tests/task-scope/request.rs (cargo test -p tama-cli --test task_scope_request).

Return to assignment show or the complete CLI tree.