@codetreker/daynight 0.13.0 → 0.16.0

package/dist/commands/skill/skills/using-daynight/references/goal.md

@@ -1,186 +1,190 @@
 # Goal protocol
 
-Read this reference when creating a multi-stage Goal, running one of its tasks,
-or advancing its authorized scope. Use [create-task](create-task.md) for content
-and registration rules, [run-task](run-task.md) for one task's lifecycle, and
+Read this reference when starting or registering a Goal, discussing one of its
+stages, or advancing its authorized scope. Use [create-task](create-task.md) for
+content and registration, [run-task](run-task.md) for task execution, and
 [the handbook](handbook.md) for CLI semantics. A Goal uses existing tasks,
 attachments, complete `dependsOn` relationships, their `externalDependsOn`
-classification and PR properties; it adds no Goal-specific command, task type,
-status, or execution authority.
-
-## Identify and register a Goal
-
-Use a Goal when completing the request requires multiple independently tracked
-delivery stages. One independently tracked outcome remains a normal task;
-commands, tests, and temporary execution steps do not each need persistent tasks.
-The user need not use the word Goal.
-
-Explicit permission to create a Goal covers its two starting tasks and the later
-breakdown within that Goal. It covers no unrelated tasks and grants no execution,
-publication, deployment, external communication, merge, or mainline push
-permission. Existing explicit authorization continues to apply within its scope.
-Implementation or autopilot permission alone does not grant creation permission.
-Goal-creation permission does not authorize approval. Approve only tasks or a
-Goal-task scope explicitly approved by the user, using each reviewed task's exact
-version; CLI and Web approval are available. Goal creation, requirements/prototype
-completion, design completion and autopilot never imply that instruction. Approval
-itself grants no execution or delivery permission.
-
-During registration, create or reuse both starting tasks:
-
-| Task | Title | Initial content |
-|---|---|---|
-| Goal description | `[Goal]<outcome>` | The known overall problem, intended results, scope, constraints, UI applicability, exclusions, and observable acceptance summary; a stage brief for resolving open requirements and producing the complete Goal. |
-| Architecture design and task breakdown | `Architecture design and task breakdown: <outcome>` | Its concrete work: consume the completed Goal, design the architecture, register the complete delivery breakdown, verify its artifacts and dependencies, and deliver any required design PR. Its own stage brief defines the approach and acceptance. |
-
-The `[Goal]` marker is followed directly by the outcome. Goal description names
-the stage; it is not the title prefix. Titles communicate purpose but do not
-establish stable identity. Preserve confirmed IDs and inspect full content when
-reusing an existing chain.
-
-Set the design task's ordinary `--depends-on` to the Goal description task.
-Confirmed within-Goal stages and delivery prerequisites stay ordinary. Verified
-prerequisites owned by other same-project chains use `--external-depends-on`; even a Goal's
-top-level task may have such external predecessors. They remain real blockers.
-Preserve both kinds through the handbook's complete CLI replacement semantics,
-not by inferring classification from done status or the current rendered graph.
-Each task starts
-in `proposed` with its own self-contained Markdown description and primary Markdown
-containing Solution and Acceptance criteria. State unanswered questions honestly.
-Complete requirements, prototypes, architecture, and breakdown are produced by their
-respective stages; they are not prerequisites for registering the chain or
-starting the stage that produces them. Confirm both tasks, stage briefs,
-references, and dependency through real reads, then return from `create-task`.
-Registration completeness leaves approval pending unless the user separately
-authorized approval for those tasks. Metadata and attachment writes do not approve.
+classification, and PR properties. It adds no resource, command, or status.
+
+## Identify the current discussion
+
+Use a Goal when a concrete outcome needs requirements discussion, solution or
+architecture discussion, and actual delivery work. Independently understandable
+features, bug fixes, architecture/design assignments, and real breakdown items
+are tasks. Agent-generated commands, file reads, and routine checks stay in the
+owning task's execution plan.
+
+Permission to create a Goal covers its requirements discussion, the later solution
+discussion, and the confirmed in-scope delivery breakdown. Create each only at
+its stage below. Reuse suitable existing tasks after reading their full problem,
+scope, materials, acceptance, and actual context; a title alone is not identity.
+An explicit user or applicable repository tracking/review instruction supplies
+standing creation permission within the confirmed scope. It grants no unrelated
+work, implementation, external communication, deployment, merge, or mainline push
+permission.
+
+A request to start a Goal discussion authorizes creating and starting
+that discussion task so it becomes `in_progress`. A registration-only request
+creates only the current discussion task in `todo` and returns without execution. A generic run request, Goal registration, or autopilot
+activation does not supply discussion-start or delivery execution authorization.
+
+## Start requirements discussion
+
+Create or reuse only the requirements discussion task, titled `[Goal]<outcome>`.
+The marker is followed directly by the outcome. Do not create an architecture
+placeholder or delivery tasks at this point. Give the task a self-contained Markdown description
+for the known problem, intended outcome, scope, constraints, open
+questions, and observable completion conditions. Its primary Markdown's Solution
+and Acceptance criteria describe this discussion and its user-confirmation gate;
+finished requirements and prototypes are outputs, not prerequisites to starting.
+
+Each task starts in `todo`. For an explicit discussion-start request, read its
+current materials and exact version, use `task set-status <task-id> in_progress`
+with the version observed for that decision and confirm `in_progress`.
+All direct prerequisites must be done. Preserve real external blockers rather
+than removing dependencies to make a discussion ready. An already in-progress
+task is resumed after checking its actual work and context.
+
+Discuss requirements with the user: the whole problem, desired behavior, scope,
+constraints, exclusions, and whole-Goal acceptance. Keep current material and open
+questions in this task's description or attachments. The description remains a
+self-contained brief; its primary Markdown owns detailed requirements, validation,
+and evidence. Before requesting user review, save the complete current material,
+read it back, and provide the task and resource reference.
+
+For a UI Goal, produce a final-style interactive frontend-only prototype with
+working relative resources and relevant populated, empty, loading, failure,
+disabled, long-content, and narrow-screen states. View and exercise it. Prototype
+code is a requirements artifact; this discussion does not implement production
+code or decide the architecture.
+
+## Confirm requirements and start solution discussion
+
+Keep the requirements task `in_progress` until the user explicitly confirms the
+current requirements and directs the next discussion, for example, "Requirements
+are settled; move to architecture discussion." Agent confidence, completed text,
+a review result, or elapsed time does not satisfy this gate.
+
+Record the user's confirmation with the accepted material in the owning task and
+verify it is readable. A material revision after confirmation requires renewed
+user confirmation before advancement. When the discussion's acceptance is met,
+reread the task, use `task set-status <task-id> done` with its observed version, and confirm done.
+Do not create the solution discussion until that completion is confirmed; reconcile
+an uncertain completion before another mutation.
+
+Then create or reuse the solution discussion task, with a purpose-specific title
+such as `Architecture discussion: <outcome>`, and an ordinary prerequisite on the
+completed requirements task. The user's direction to start this discussion
+provides its scoped execution authorization. Prepare its stage brief,
+read its current version, set in_progress through the same lifecycle, and
+confirm `in_progress`. This user-directed transition does not require autopilot
+and does not authorize selection of another unrelated task.
 
 ## Execute the appropriate stage
 
-New Goal stages and delivery tasks start with `allowAgents=false`. Creation and
-approval do not enable automatic execution. Automated workflows must not enable
-the flag themselves; explicit user-selected execution may use manual claim
-regardless of it while retaining all authorization and prerequisite checks.
-
-Every stage uses the same explicit task lifecycle. Proposed work waits for the
-user's scoped approval; an authorized `task approve` moves it to todo even with
-unfinished prerequisites. Begin only from approved ready todo with complete
-stage inputs and execution authorization: use `task claim` with the exact version
-observed for that decision and confirm in_progress. Resume existing in-progress
-work after checking its actual checkpoint. After the stage acceptance and every
-required authorized PR merge, reread and use `task complete` with the observed
-version. Completion satisfies dependencies but never approves the next stage.
-Unstarted todo work can return to proposed through explicitly authorized
-unapprove; it then waits for a new approval before claim.
-
-| Stage | Required inputs to start | Outputs and completion |
-|---|---|---|
-| Goal description | Its stage brief, current problem and scope, and available background. | Complete overall requirements, applicable final-style interactive UI prototype, verified stage acceptance, and repository-required delivery. Finishing this task completes problem definition. |
-| Architecture design and task breakdown | Completed Goal description, its full requirements and applicable prototype, and the design stage brief. | Complete architecture and the actual registered delivery tasks, verified task-specific artifacts and dependencies, satisfied stage acceptance, and platform-confirmed merge of every required design PR. |
-| Delivery task | Completed design prerequisite, delivered architecture, its own solution and acceptance criteria, and applicable prototype and resources. | This task's deliverable, verification, required review and PR merges, and readable acceptance evidence under the normal run-task rules. |
-
-### Goal description
-
-Explain the whole problem and why it matters, the final observable results,
-required behavior and constraints, scope, explicit exclusions, and how the whole
-Goal will be accepted. The task description itself must communicate this complete
-overall brief and a concise acceptance summary. Its primary Markdown owns the
-full requirements, verification methods, and stage evidence. Resolve blocking
-ambiguities without making architecture decisions or changing production
-implementation code.
-
-For a UI Goal, specify final layout, visual styling, interactions, representative
-data, and relevant states. Produce an interactive prototype that runs with
-frontend code alone, with final styling and all necessary resources. Cover
-applicable populated, empty, loading, failure, disabled, long-content, and
-narrow-screen states; explain exclusions when a relevant-looking state does not
-apply. Prototype code is an allowed problem-definition artifact. View and
-exercise the result when verifying this stage.
-
-Confirm the full requirements are clear, the applicable prototype is usable,
-and this stage's acceptance and repository delivery rules are satisfied. If
-repository rules require a PR for these artifacts, use the existing PR completion
-rules. Otherwise use the stated stage acceptance. Complete only this in-progress
-task through `task complete` with its observed version after verification. This
-satisfies design's dependency; design still needs its own approval and claim, and
-whole-Goal delivery remains unverified.
-
-### Architecture design and actual task breakdown
-
-Consume the completed Goal and prototype. Design the responsibilities, boundaries,
-data and control flow, contracts, error behavior, key decisions, and validation
-approach required by the target repository and Goal.
-
-During this task, register the complete set of persistent delivery tasks needed
-to satisfy the Goal. Each represents a concrete outcome with its own actions,
-scope, deliverables, constraints, solution, acceptance criteria, verification
-methods, and real input references. Their combined scope must cover the complete
-Goal. A future registration list or a vague implementation placeholder does not
-satisfy task breakdown.
-
-Use ordinary edges for actual within-Goal prerequisites. Every delivery root
-with no other ordinary implementation prerequisite depends directly on the
-design task, so every within-Goal delivery path passes through design completion.
-External prerequisites keep their verified source ownership and do not replace
-that ordinary design gate; they also must be done before execution. Keep delivery tasks blocked
-while design is unfinished. This stage registers and verifies them; it does not
-execute them. New successors are proposed; approval requires a separate explicit
-user instruction covering them, even when Goal creation already permits their
-registration. Approved successors still wait for completed design prerequisites.
-
-Upload each successor's own primary Markdown and needed resources, referencing
-shared Goal and design inputs at their verified source. The design task owns its
-architecture and breakdown outputs. Read back every registered task, required
-attachment, source reference, and dependency. Verify the full breakdown before
-handing over the design PR. When review changes the design, update its owning
-artifacts and affected task summaries, plans, and references coherently, then
-reread them before completion.
-
-Follow repository document and independent review requirements. When a design
-PR is required, create it and maintain the full `properties.pullRequests` list.
-Keep this task `in_progress` until every necessary PR is platform-confirmed merged
-and stage acceptance is satisfied. An open PR, successful CI, or approval does
-not complete design. A user-review or no-merge instruction preserves this task
-and its blocking dependency while waiting; it grants no merge authority.
+During solution discussion, consume the confirmed requirements and applicable
+prototype. Discuss how to achieve the outcome: responsibilities, data and control
+flow, interfaces, error behavior, key decisions, verification, and the proposed
+breakdown. The solution task owns the current architecture, proposal, and draft
+breakdown. Keep discussion material accessible in its description or attachments,
+verify it before user review, and synchronize revisions and review decisions.
+Do not register delivery subtasks before the user confirms the current solution.
+
+A discussion task completes from user-confirmed Daynight material and its stated
+stage acceptance. Repository document/code delivery still follows normal PR and
+merge rules, but a generic repository PR rule does not add a merge prerequisite
+to a Daynight discussion. If the user explicitly makes particular repository
+artifacts or PR delivery part of that discussion's acceptance, honor that
+requirement and its delivery permissions. An unresolved user review keeps the
+current discussion `in_progress`. Successful CI or a design review cannot replace
+the user's confirmation.
+
+After explicit user confirmation of the current solution, record that confirmation
+with the accepted material and register the delivery breakdown below. Complete
+the solution discussion only after the accepted solution and actual registered delivery tasks,
+their required materials, and their dependencies are read back
+and verified. Use `task set-status <task-id> done` with the observed version and confirm done.
+Completion satisfies dependencies and grants no delivery execution permission. Completing
+either discussion does not establish whole-Goal completion.
+
+## Register the confirmed delivery breakdown
+
+Only after user solution confirmation, create or reuse the concrete delivery tasks
+needed for the agreed outcome. Each needs its own problem, objective, scope,
+deliverables, constraints, solution, observable acceptance, verification methods,
+and real input references. Include independently scoped acceptance work when it
+has its own outcome; do not turn agent-generated execution steps into tasks.
+The combined scope must cover the confirmed Goal, rather than a vague placeholder.
+
+Create new delivery tasks in `todo`. Solution confirmation authorizes the
+confirmed breakdown's registration, not implementation, autopilot,
+automatic-execution permission, publishing, deployment, or merge. Apply any
+separate explicit authorization only within its stated scope. New tasks have
+`allowAgents=false`; automated workflows must not enable it themselves.
+
+Use ordinary dependencies for real within-Goal prerequisites. Every delivery root
+without another ordinary implementation prerequisite depends directly on the
+solution discussion, so each delivery path includes confirmed design completion.
+Mark verified prerequisites owned by another same-project chain as external;
+external prerequisites remain real blockers and do not replace that ordinary
+design gate. Preserve the complete relationship sets under the handbook's CLI
+replacement semantics. Do not create dependencies merely to group cards.
+
+Upload each task's own primary Markdown and needed resources. Keep shared
+requirements with the requirements task and the solution and breakdown with the
+solution task. Consumers reference the verified source task ID and attachment
+path, or an immutable repository source. Read back every task, required attachment,
+shared input, and dependency before reporting the breakdown registered. Keep the
+solution discussion `in_progress` when registration is incomplete. If the accepted
+solution materially changes, obtain renewed user confirmation before registering
+or advancing the changed work.
 
 ## Preserve ownership and recover partial registration
 
-Every stage and delivery task needs its own self-contained Markdown description
-and detailed primary Markdown. Follow create-task's Markdown and verified-resource
-rules without claiming unfinished stage outputs are already available. Keep shared
-requirements on the Goal description task and shared architecture and breakdown on the design task. Later tasks reference
-verified source task IDs and attachment paths, read through the installed CLI,
-or verified immutable repository references. Do not distribute a duplicate whole
-packet to all tasks. Only copy a snapshot when the consuming task needs it,
-recording the purpose, original source, and source revision or content identity.
-
-Registration comprises independent writes, not a transaction. Reuse confirmed
-IDs if creating the second starting task, uploading an artifact, updating a
-reference, or registering part of the breakdown fails. Before retrying an
-uncertain write, read the complete actual resource and operation context as the
-handbook requires. A similar title does not prove success, and a lost response
-does not prove failure. If identity cannot be established uniquely, preserve the
-specific error and request the information needed to reconcile it; do not create
-another chain.
-
-Apply the handbook's exact-version rules to metadata updates, approval,
-withdrawal, claim and completion, and preserve complete-field replacement semantics for updates. Attachments are independent of task versions, status, and timestamps;
-verify actual file contents and metadata separately. Do not unlock delivery by
-marking incomplete registration or unfinished design complete. Readiness and
-`in_progress` provide no ownership lock; claim is a versioned transition, not an
-assignee lease. Generic updates cannot write status or bypass stages.
+Stage briefs describe the work to produce the stage's outputs; they do not claim
+unfinished results exist. Every stage and delivery task has its own self-contained
+Markdown brief and detailed primary Markdown. Keep shared inputs at their actual
+owner. Do not distribute a duplicate whole packet to every task. An independently
+needed snapshot records its purpose, original source, and source revision or
+content identity. Existing attachment reads support these references; do not
+invent a URL scheme, cross-task relative links, or fixed service host.
+
+Creation, uploads, metadata changes, and lifecycle actions are independent writes.
+Retain confirmed IDs and resume missing operations after partial success. Read
+actual task fields and attachment contents before retrying an uncertain write;
+a matching title or lost response does not establish success or failure. If the
+identity cannot be established uniquely, preserve the failure and information
+needed to reconcile it rather than creating a duplicate chain.
+
+Bind metadata updates and status changes to the exact version
+observed for that decision. Attachment bytes have independent concurrency and
+must be verified separately; task versions cannot prove the reviewed content is
+unchanged. Generic updates cannot write status. A version conflict requires a
+new decision. Readiness and `in_progress` provide no ownership lock or lease.
 
 ## Advance and accept the whole Goal
 
-`run-task` returns after its specified task completes or requires external
-intervention. Completing registration, Goal description, or design never activates
-autopilot. Only explicitly active `autopilot` may select the next related task
-after confirming the current task `done`, within the user's authorized scope.
-CI, review, and merge waits remain with the current task.
-
-To report the whole Goal complete, inspect the full registered delivery scope,
-confirm every delivery task completed and every necessary PR actually merged,
-and verify the original Goal's overall acceptance criteria with recorded
-evidence. Description completion, design completion, one delivery PR, or an empty
-ready page is insufficient. Distinguish verified partial results and remaining
-blockers from whole-Goal completion. This check does not create a new Goal status
-or reopen the completed problem-definition task.
+Automatic delivery discovery requires actual-runtime platform compatibility.
+Use autopilot's platform-filtered queries and preserve automatic-selection context
+for run-task's full-task recheck before setting in_progress. A user-specified fixed
+Goal queue keeps its manual path and existing execution scope across ready successors;
+it does not enable automatic discovery permission or bypass stage confirmation.
+
+A user-directed requirements-to-solution transition follows the confirmation
+protocol above. Ordinary `run-task` otherwise returns after its specified task
+completes or needs external intervention. Neither discussion completion nor
+breakdown registration activates autopilot or starts delivery. Only explicitly
+active autopilot selects later delivery work, and only with the existing readiness, input, and execution requirements. Automatic discovery
+requires `allowAgents=true`; an explicitly selected task or fixed Goal queue
+uses the manual execution path regardless of that flag. CI, review, and merge
+waits stay with the current delivery task.
+
+Delivery tasks follow normal run-task completion: accepted outcomes, required
+review, all necessary authorized PR merges, and readable evidence. To report the
+whole Goal complete, inspect the full confirmed delivery scope, every delivery
+task's completion, all required PR merges, and the original whole-Goal acceptance.
+The requirements task being done means only that requirements discussion is
+complete. The solution task being done means the confirmed solution and verified
+breakdown are delivered. An empty ready page or a single delivery result proves
+neither the whole outcome nor completion of all its work.

package/dist/commands/skill/skills/using-daynight/references/handbook.md

@@ -13,15 +13,12 @@ needed to use them correctly.
 | `project create` | Register a repository as a project or find its existing project. |
 | `project list` | Find projects on the configured service. |
 | `project show` | Inspect a project's details. |
-| `task create` | Register a proposed task with its metadata and dependencies. |
-| `task ready` | Read a bounded candidate page of approved todo tasks with completed prerequisites. |
+| `task create` | Register a todo task with its metadata and dependencies. |
+| `task ready` | Read a bounded candidate page of todo tasks with completed prerequisites. |
 | `task list` | Read every matching page; defaults to unfinished tasks. |
 | `task show` | Read one task's complete details and exact version. |
-| `task update` | Change metadata, automatic-execution permission, dependencies, or PR references; status is not writable. |
-| `task approve` | Change proposed to todo using an observed version and explicit approval authorization. |
-| `task unapprove` | Withdraw approval of todo work, returning it to proposed using an observed version. |
-| `task claim` | Change ready todo to in_progress using an observed version. |
-| `task complete` | Change in_progress to done after acceptance and required authorized delivery. |
+| `task update` | Change metadata, automatic-execution permission, platform requirements, dependencies, or PR references; status is not writable. |
+| `task set-status` | Set todo, in_progress, or done using an observed exact version. |
 | `task graph` | Inspect the project's dependency graph and summary. |
 | `task attachment put` | Upload or replace one attachment file. |
 | `task attachment list` | Read a task's attachment inventory and metadata. |
@@ -48,12 +45,11 @@ service. An explicit project overrides discovery for that invocation. Resolve
 missing or ambiguous matches rather than guessing an ID or creating a project
 to make a query succeed.
 
-**Read scope.** Ready is a candidate page of approved todo tasks, ordered by
-creation rather than relevance. An empty page does not rule out proposed,
-in-progress or dependency-blocked work. List traverses every matching page but
+**Read scope.** Ready is a candidate page of todo tasks, ordered by
+creation rather than relevance. An empty page does not rule out in-progress or dependency-blocked work. List traverses every matching page but
 excludes `done` by default; include completed tasks explicitly when checking the
 full backlog or prior registrations. Its grouping is in-progress, ready todo,
-blocked todo, proposed, then done when included; this does not rank relevance.
+blocked todo, then done when included; this does not rank relevance.
 Human lists are summaries; JSON lists omit only `description` and preserve every
 other task field. Use show when a description is needed; ready, details and write
 results retain full tasks. Graph provides compact dependency context without
@@ -61,46 +57,68 @@ full descriptions, PR properties, or versions. Read the selected task's details
 before acting. A graph-limit error still permits bounded candidate and
 individual task reads.
 
-**Lifecycle and approval.** Creation starts in `proposed`. Explicit approval
-moves proposed to todo; unapprove returns only unstarted todo work to proposed;
-claim moves ready todo to in_progress; complete moves in_progress to done.
-Approval and withdrawal allow unfinished prerequisites. Claim and completion
-require every direct prerequisite to be done. Proposed is never ready, even
-with no prerequisites. Withdrawal preserves task materials, dependencies,
-execution timestamps and attachments; it does not change successor states.
-Repeated actions and wrong predecessor states fail. There is no reopening of
-in-progress or done work, execution release, or direct todo-to-done transition.
-Metadata, attachments and PR references cannot approve, withdraw approval or
-claim work. Approve or unapprove only when the user explicitly authorizes that
-action for the task or stated scope; creation, execution requests, `run-task`
-and autopilot grant none. In the Web, the title-row entry opens a confirmation;
-only deliberate confirmation is the user's approval or withdrawal instruction.
-Cancel and Escape submit no action. Task approval itself grants no implementation,
-publication, deployment or merge permission.
+**Task status.** Creation starts in `todo` with no task approval stage and does
+not start execution. `task set-status <task-id> <status> --if-version <version>`
+sets any of `todo`, `in_progress`, or `done`. The service checks the exact version
+before a same-status no-op; it preserves all fields for a current-version no-op
+and refuses stale versions. A real change increments the version once. Generic
+metadata updates cannot write status. Status, materials, and readiness grant no
+implementation, publication, deployment, or merge permission.
+
+Entering in_progress or done requires every direct prerequisite done. Reopening
+done to todo or in_progress is refused when a direct successor is in_progress or
+done; successors are never changed automatically. Entering in_progress starts a
+new execution interval and clears completion; returning to todo clears both
+endpoints. In_progress to done retains the nullable start and records completion.
+Todo to done records only completion, with unknown duration. Same-status and
+metadata updates preserve timing. State changes provide no process ownership,
+release, transfer, stop, or lease semantics. The Web confirms every status choice,
+including the current status; cancel and Escape submit no request.
 
 **Automatic execution permission.** Tasks expose the required boolean
-`allowAgents`, independent of status approval and dependency readiness. New tasks
+`allowAgents`, independent of status and dependency readiness. New tasks
 start false; public creation cannot set it. Existing tasks receive true through
 the database migration. Use `task update <task-id> --allow-agents true|false --if-version <version>` only
 for an explicitly authorized permission change.
 Omission preserves the current value, including explicit false. Actual changes
 are locked during in_progress; exact-version same-value requests keep the
-version and timestamps, while stale versions still conflict. Approve, unapprove,
-claim, complete and other metadata updates preserve the flag.
+version and timestamps, while stale versions still conflict. Status changes and other metadata updates preserve the flag.
 
 `task list` and `task ready` accept `--allow-agents true|false`. The server
 combines that condition with other filters before pagination and the ready limit;
 an unfiltered ready page may contain tasks without automatic-execution permission.
 Automatic selection requires true and automated workflows must not enable it
-themselves. An explicitly user-selected task may still use manual claim regardless
+themselves. An explicitly user-selected task may still use manual execution regardless
 of the flag. Permission does not grant execution, publication or merge authority.
 A lost permission PATCH response is an unconfirmed write: read actual task state
 before reconsidering the operation, without resubmitting automatically.
 
-**Task concurrency.** Bind each metadata update, approve, unapprove, claim and complete to
+**Execution platform.** Complete tasks, inventory items and graph nodes expose
+`requiredPlatform` as `null`, `windows`, `linux` or `macos`; null means unrestricted.
+Set a requirement with `task create --required-platform <platform>` or
+`task update <task-id> --required-platform <platform> --if-version <version>`.
+Clear it with `task update <task-id> --clear-required-platform --if-version <version>`;
+setting and clearing in one command is invalid. Omitting both update options
+preserves the requirement. Existing and new tasks without a requirement are
+unrestricted. Actual changes are locked during in_progress; an exact-version
+same-value request keeps version and timestamps, while stale versions conflict.
+Explicitly user-selected tasks and fixed queues retain their manual execution
+path independently of platform compatibility. Automatic selections keep their
+actual-platform context and recheck full-task eligibility before set-status.
+
+`task list` and `task ready` accept `--compatible-platform <platform>`. The
+server includes unrestricted tasks and exact matches, combining this condition
+with status, readiness and `--allow-agents` before pagination or the ready limit.
+Platform compatibility does not change readiness or enable automatic execution.
+Preserve the filter when requesting additional candidate inventory; do not filter
+a bounded unfiltered ready page locally. A query option selects a candidate
+platform and does not establish the actual execution environment. Worker runtime
+must identify its own platform; a Linux runtime in WSL is Linux.
+
+**Task concurrency.** Bind each metadata update and status change to
 the exact version read for that decision using `--if-version`; the CLI's default
 pre-submit read cannot protect an earlier decision. Preserve full int64 decimal
-digits without numeric rounding. A claim is a versioned transition, not an
+digits without numeric rounding. Entering in_progress is a versioned transition, not an
 assignee lock, renewable lease or proof that existing work belongs to this
 session. On a conflict, reread and reconsider; a new action needs a fresh
 decision, not merely a newer version. Never retry a mutation automatically.
@@ -108,7 +126,7 @@ decision, not merely a newer version. Never retry a mutation automatically.
 **Dependency classification.** `dependsOn` contains every direct prerequisite;
 `externalDependsOn` is its explicit external subset. Ordinary prerequisites are
 `dependsOn` minus that subset. Both are canonical, duplicate-free UUID sets,
-not insertion order. Every prerequisite must be done before claim or completion,
+not insertion order. Every prerequisite must be done before entering in_progress or done,
 including external ones; cycle checks and project access rules use all edges.
 External means cross-chain within the same project, not a cross-project
 reference. It separates chain ownership, not blocking or authorization. Use
@@ -171,5 +189,7 @@ resource IDs rather than reporting success or blindly resending a write.
 Task registration, execution, and selection follow [create-task](create-task.md),
 [run-task](run-task.md), and [autopilot](autopilot.md), respectively. For a chain
 of independently tracked delivery stages, use [the Goal protocol](goal.md).
-Goal scope grants no implicit approval: every stage and delivery task follows the
-same proposed/approve/unapprove/claim/complete lifecycle.
+Every stage and delivery task follows the same todo/in_progress/done contract.
+A fixed Goal queue may use existing scoped execution authorization for its ready
+successors; registration and discussion confirmation grant no delivery execution
+permission.