@codetreker/daynight 0.25.4 → 0.27.2

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

@@ -1,182 +1,85 @@
 # Task content standard
 
-Read this reference when creating, breaking down, handing off, or executing a
-task. The description and its readable references must explain the task without
-the originating chat, memory, private worktree, or temporary files. Use the
-target repository's document and language rules.
+Applies to creation, breakdown, handoff, and execution.
+Descriptions and their actual references should let an independent reader understand the task without the original chat, private worktrees, or temporary files.
+Follow the target repository's documentation and language rules.
 
 ## Task and session boundary
 
-Tasks describe what must be achieved and delivered. Sessions hold how the task
-is executed or discussed. Keep task definitions, required inputs, deliverables,
-acceptance criteria, and resulting artifacts in task content. Keep execution and
-discussion plans, steps, tool choices, collaboration, operational authorization,
-progress, blockers, and recovery context in the session. Apply this boundary to
-descriptions, attachments, and referenced task material.
-
-A design supplied as a required input or produced as the task's deliverable is
-task content; the session's plan for producing that deliverable is session
-context. Classify information by its purpose, not its filename or words such as
-"plan", "method", or "steps". A requested migration design, test strategy, or
-runbook can be a task deliverable. Do not invent such a deliverable to upload a
-session checkpoint or execution log.
-
-| Information | Location |
-|---|---|
-| Required sorting behavior; an upstream API contract; a design task's current architecture | Task definition, input, or result |
-| "Register only; do not execute or enable agents in this session"; chosen commands, agent assignments, review rounds | Session context; current operations still obey its restrictions |
-| Required deliverable platform or compatibility threshold; a human-confirmation completion condition | Task scope or acceptance criteria |
-| Authorization to push or merge; CI/review progress, waiting items, claim/worktree/head and next action | Session context or the corresponding platform |
-| A final deliverable's immutable revision; an acceptance conclusion and the key observations needed to support it | Task result, without the execution history |
-
-Operational authorization does not become task content because another session
-might need it. Preserve it in the host's session state or existing local
-checkpoint. Missing authorization or assignment cannot be reconstructed from a
-task's description, attachments, acceptance state, or status.
-
-## Task definition and results
-
-Provide the following substantive information in the description, clearly
-referenced documents, or a mixture of both. These are not mandatory headings.
-Complete inline content needs no primary attachment; do not duplicate complete
-documents or keep empty template sections.
-
-| Definition | Required information |
-|---|---|
-| Objective and requirements | The concrete problem, intended outcome, and required behavior. Use requirement IDs when they help acceptance. |
-| Scope and constraints | This task's responsibility and delivery boundaries, including constraints on the product or deliverable and applicable parts of shared documents. |
-| Inputs and sources | Actual required requirements, designs, prototypes, protocols, or deliveries, with accurate source identities, applicable sections, and purpose. |
-| Deliverables and contracts | Expected outputs, delivery and reading locations, and the structure and semantics needed by actual producers or consumers. Explicitly say when there is no task-to-task exchange. |
-| Acceptance criteria | Observable completion conditions, applicable success/failure/boundary behavior, required thresholds, and any human-confirmation gate. |
-
-Save results as they are produced: current reviewable requirements or designs,
-actual deliverables, acceptance conclusions, defects, and material limitations.
-An immutable revision or verified resource location may identify a result.
-Keep the accepted content and its effective state, not successive discussion or
-confirmation records. Acceptance results may include the assessed source and
-key observations needed to understand the conclusion; commands, debugging
-history, CI logs, and review handling remain execution context.
-
-A task does not universally require a separate solution, implementation plan,
-verification procedure, confirmation record, or evidence location. Its starting
-content depends on the stage and actual inputs. Do not require unfinished
-results or prefilled result sections at registration.
-
-The description must identify the concrete current work and responsibility and
-make its content sources discoverable. Judge completeness from the description
-and the contents actually read, not heading presence or whether the description
-repeats the documents. A bare generic problem plus unexplained links, "see the
-previous discussion", unreadable resources, and missing required decisions are
-insufficient. Absence of a session execution plan is not a task-content gap.
-
-## Content ownership
-
-Each detailed explanation has one owner: the description, a referenced task
-attachment, or its actual shared source. Keep shared requirements, architecture,
-and protocols at their owning task. Save this task's results at their actual
-owner and make them discoverable from its description. Rewrite the owning
-material coherently when its facts change; do not accumulate an execution log.
-
-For example, an upload retry task may define its required behavior and
-acceptance inline and reference the architecture task's `design/upload.md` for
-shared interfaces. A design task may own that architecture in its description
-or an actual attachment. Neither needs an attachment containing the session's
-implementation steps. Those source identities and paths must be real and
-verified.
-
-## Resolve and read sources
-
-Description-relative links and images start at the current task's attachment
-root; references inside a Markdown attachment start at its containing directory.
-Keep paths inside the task root and preserve case and resource identity. Confirm
-uploaded contents before adding their links. Shared task sources identify the
-owning task ID and content location: its description and applicable sections for
-inline content, or the complete attachment path for an actual attachment. Name
-the whole description when all of it applies; sections only delimit a larger
-source and do not require invented headings. Read source task descriptions with
-`task show --json`; list and read attachment contents separately with the
-installed attachment commands. Repository documents need accurate paths and the
-required verified immutable source revision. State the sections, requirements,
-or interfaces applicable to this task when a source covers more. Do not invent
-an attachment path for inline content, relocate or copy it merely to satisfy a
-reference format, or invent a URL scheme, cross-task relative link, or fixed
-service host.
-
-Read the required source contents, including further references needed for the
-current stage. Track already-read resource identities to avoid circular reading.
-A reference cycle that supplies no actual required content cannot pass. Limit
-traversal to this task's requirements; it does not authorize redesigning a Goal
-or executing related tasks. Resolve material conflicts between the description
-and sources or between sources before declaring the content sufficient.
-
-Every Goal delivery task's description must directly list the architecture task
-ID and all required architecture source locations, including indirect successors.
-For inline architecture, name the source task's description and applicable
-sections. For each actual required attachment document, include its full path;
-for repository architecture, retain the owning task ID and a verified immutable
-reference. An entry only in another task or inside an attachment is insufficient.
-[The Goal protocol](goal.md) owns this additional source-index requirement and
-its registration checks.
-
-## Input and output contracts
-
-Describe actual exchanges rather than inventing an interface to fill a template.
-As applicable, include fields, types, requiredness, format or version, examples,
-and the units, states, errors, and null semantics needed by consumers. APIs, CLI
-output, files, database records, attachments, and design conclusions can all be
-exchanged outputs. Check the relevant producer and consumer explanations for
-consistency and distinguish their responsibilities.
-
-For example, an upload protocol may define a required multipart `file`, a
-10 MiB limit, a `201` response containing a UUID `id`, `name`, and byte-count
-`size`, a nonretryable `413 file_too_large`, and a `503 temporarily_unavailable`
-that permits user-initiated retry. Provider and consumer tasks reference the same
-protocol and state their own delivery locations and availability.
-
-Necessary direct prerequisites remain in the complete `dependsOn` set and its
-`externalDependsOn` subset, following
-[the handbook's dependency reduction rule](handbook.md#dependency-reduction).
-Contract source identities do not form a second complete dependency list, and a
-source reference does not create an execution dependency. Use
-[the handbook](handbook.md) for relationship semantics. Existing status, PR,
-permission, platform, and worker fields keep their own service semantics; do not
-copy them into prose as a second operational record.
-
-## Apply the current stage
-
-| Stage | Sufficient starting content | Stage results |
-|---|---|---|
-| Requirements discussion | Known problem, outcome, scope, constraints, open requirements questions, and completion conditions | Current and confirmed requirements and applicable prototype |
-| Solution or architecture discussion | Confirmed requirements, applicable prototype, design questions, intended deliverables, and completion conditions | Current architecture, key decisions, and delivery breakdown |
-| Implementation or document delivery | Defined requirements and scope, required design and applicable prototype, contracts, deliverables, and acceptance criteria | The scoped deliverable and its actual location or version |
-| Independent final acceptance | Whole agreed requirements and confirmed changes, actual deliveries, and acceptance criteria | Requirement-based conclusions, defects, and unverified items |
-
-A stage's unfinished outputs are not prerequisites for starting that stage.
-Preserve human confirmation as an actual completion condition where required;
-the execution protocol handles the confirmation action and advancement.
-Explicit prerequisite-produced implementation outputs may still be pending when
-preparing a blocked task, provided the necessary design and agreed interfaces
-already define the successor's work. Do not label future output as an existing
-readable input. Execution still waits for real prerequisites and required inputs.
-
-## Check sufficiency
-
-Before reporting creation, breakdown, or handoff ready, check the task
-definition, source readability and applicability, existing result ownership, and
-the stage's additional conditions. Check both directions: session context stays
-out, and actual requirements, required design inputs, and task results remain
-complete. Unknown requirements, design choices, acceptance thresholds, and
-interface decisions are concrete blockers, not details to invent. Only organize
-confirmed information within existing authorization. A material scope or
-behavior change requires user confirmation.
-
-Apply the boundary when reading existing material and when authoring or
-rewriting authorized task content. It does not authorize bulk edits of historical
-tasks or automatic changes to fields, permissions, or recorded history.
-
-Task versions protect task metadata, not independently mutable attachments or
-cross-task references. Verify mutable contents before enabling permission and
-read the required contents again before execution. Reassess affected content
-when it changes. A content check is not an atomic freeze or permanent
-certification of future sources. [Handoff](handoff.md) owns permission-update
-and read-only re-audit behavior.
+Tasks store what must be implemented and delivered; sessions store how to execute or discuss it.
+Apply the same boundary to descriptions, attachments, and referenced material.
+
+| Store in the task | Store in the session or relevant platform |
+| --- | --- |
+| Objectives, requirements, scope, delivery constraints, required inputs, acceptance criteria | Execution steps, tool choices, agent assignments, operational authorization |
+| Current requirements or architecture, accepted conclusions and essential rationale, substantive open questions | Discussion rounds, confirmation process, debugging history, CI and review progress |
+| Deliverables, immutable revisions, acceptance conclusions, key observations and limitations | Worktree, HEAD, claim, blocker, waiting, and recovery context |
+
+Classify by purpose, not by filenames or words such as "plan" or "method".
+User-requested migration designs, test strategies, and operating manuals can be deliverables; the session steps that produce them do not belong in tasks.
+Do not invent delivery requirements to justify uploading execution logs.
+Operational authorization still constrains current behavior, but does not become task content merely because a later session needs it.
+
+## Definitions and results
+
+The description and readable references together provide the following information, without mandatory headings or empty templates:
+
+| Information | Content |
+| --- | --- |
+| Objectives and requirements | Specific problem, expected outcome, required behavior, and requirement IDs when needed. |
+| Scope and constraints | This task's responsibilities, delivery boundaries, and applicable shared constraints. |
+| Inputs and sources | Source identifiers, locations, applicable sections, and purposes of genuinely required material. |
+| Deliverables and contracts | Outputs, read locations, and semantics needed by producers and consumers; state when there is no exchange between tasks. |
+| Acceptance criteria | Observable completion conditions, success and failure behavior, thresholds, and human confirmation points. |
+
+The description must identify this task's specific work and where to find its sources.
+When attachment delivery is not specified, complete inline content needs no primary attachment; references or a mix of inline content and references are also valid.
+Do not duplicate complete documents.
+The [complete delivery standard](autopilot-managed-task.md#complete-delivery-standard) governs managed tasks' attachment and separate review-file requirements; the general inline-content rule cannot waive them.
+Generic questions, unexplained links, unreadable sources, or "see the previous discussion" are insufficient.
+
+Save stage results promptly: current reviewable artifacts, accepted content and its effective status, actual deliverables, acceptance conclusions, and important limitations.
+Each detailed explanation has one owner; rewrite it coherently when it changes rather than accumulating logs.
+The requirements stage does not require completed requirements in advance, nor does the design stage require a completed design.
+Do not present future prerequisite outputs as existing inputs. See the [Goal protocol](goal.md) for stage requirements.
+
+## Attachments and references
+
+Task details contain neither an attachment listing nor attachment bytes; use `task attachment list/read` separately.
+Uploading to the same path replaces the file.
+See [write safety](write-safety.md#attachments-and-multi-step-operations) for content concurrency limits.
+
+Relative links and images in a description resolve from this task's attachment root; references inside a Markdown attachment resolve from the file's directory.
+Preserve case and actual resource paths, and do not escape the task root.
+Upload and read back resources before adding links.
+Preserve valid relative locations for prototype HTML, CSS, JavaScript, images, and other resources, and follow the [prototype requirements](create-task.md#prepare-content).
+
+Keep shared inputs in their owning tasks and cite the owning task ID and source location: identify the description and applicable sections for inline content, the full path for actual attachments, and the exact path and required, verified immutable revision reference for repository sources.
+Read source descriptions with `task show --json` and read attachments separately.
+The whole description may be referenced when no section restriction is needed.
+Do not invent attachments, cross-task relative links, URL schemes, or fixed service hosts, or copy or move content merely to satisfy formatting requirements.
+
+Read further references genuinely needed by the current task, tracking resources already read to avoid cycles.
+Reference cycles without substantive content cannot pass checks; resolve substantive conflicts between sources before declaring inputs sufficient.
+See the [Goal protocol](goal.md#register-the-delivery-breakdown) for the additional architecture-index requirements for every Goal delivery task.
+
+## Markdown and exchange contracts
+
+Descriptions use Markdown; the Web renders CommonMark/GFM and displays raw HTML as text.
+The CLI/API preserves the original string and has no format field.
+Preserve newlines, code, syntax, and valid references when replacing the full content.
+
+Describe only exchanges that actually exist, specifying fields, types, requiredness, formats or versions, examples, units, statuses, errors, and null semantics as needed.
+APIs, CLI output, files, databases, attachments, and design conclusions can all form contracts.
+Verify consistent producer and consumer responsibilities; do not invent interfaces to fill a template.
+Citing sources does not create execution dependencies; see [task management](task-management.md#dependency-classification) for relationship rules.
+
+## Content sufficiency
+
+Before creation, handoff, or execution, check definitions, source readability and applicability, result ownership, and stage requirements.
+Unknown requirements, interface decisions, design choices, and acceptance thresholds are specific gaps, not details to invent.
+If completing a task requires an architecture or execution plan, it is a required input and cannot be omitted on the grounds that "session plans do not belong in tasks"; actual session steps still follow the content boundary.
+Handle input gaps in managed tasks through the [user interaction workflow](autopilot-managed-task.md#request-user-interaction).
+
+Organize confirmed information only within the authorized scope; substantive scope or behavior changes require user confirmation.
+This standard does not authorize bulk rewrites of historical tasks or automatic changes to permissions, statuses, or records.

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

@@ -1,142 +1,50 @@
 # Shared task execution
 
-Read this reference after the selected execution mode establishes the task's
-identity. It owns required inputs, authorized work, delivery, results, and
-acceptance readiness. The execution mode owns starting or resuming the task,
-its final status operation, and returning to its caller.
+Read this file after identifying the task in both ordinary and managed execution.
+It governs shared inputs, work, results, and completion conditions; the mode-specific files govern startup, final status operations, interaction, and return.
+Managed execution must also meet its [complete delivery standard](autopilot-managed-task.md#complete-delivery-standard).
 
-## Read the task and stage inputs
+## Inputs and readiness
 
-Read the complete task and its actual required references under
-[the task content standard](task-content.md), including the task definition,
-actual required design inputs, acceptance criteria, and existing results. Its
-Markdown description must identify the concrete current work, responsibility,
-and content sources. Complete inline content needs no primary attachment;
-document-owned and mixed organization are valid when their combined contents
-provide the stage-appropriate task definition. A missing session execution plan
-is not a missing task input.
+Read the complete task, actually required references, and existing results under the [task content standard](task-content.md).
+For Goal tasks, also apply the [stage protocol](goal.md) and check responsibilities, stage inputs, and the architecture index.
+Inspect required prototypes with their assets and actually interact with them.
 
-Resolve description-relative links and images from the current task's attachment
-root; links inside a Markdown attachment use its own directory. Resolve real
-shared input references using the owning task ID and description/sections,
-complete paths for actual attachments, or a verified immutable repository
-reference. Read source descriptions through `task show --json` and actual
-attachment contents through the attachment commands; a task read does not load
-attachment inventory or bytes.
+Verify status and all direct prerequisites under [task management](task-management.md), and apply [authorization and scope](authorization.md).
+Execution is not ready when required content or authorization is missing, sources are unreadable, or dependencies are incomplete; report the specific blocker without executing predecessor tasks to bypass it.
 
-For a Goal stage or delivery task, read [the Goal protocol](goal.md) and identify
-its role from the actual task content and context. Apply that stage's input and
-output requirements. Requirements and solution discussions start from their
-stage briefs; the completed requirements, applicable UI prototype, and
-architecture are outputs of the stages that produce them. Delivery tasks
-require the delivered design and applicable prototype. Before implementation,
-read every required architecture source listed in the delivery task's
-description: the owning architecture task's inline description and applicable
-sections, full paths for actual attachment documents, or verified immutable
-repository references. This also applies when the architecture task is only an
-indirect prerequisite. Confirm that the description's references satisfy the
-Goal protocol. When a prototype is a required input, view and exercise it with
-its resources. An unfinished output of the current stage is not a missing input.
+## Work and results
 
-## Verify prerequisites and scope
+Work within the confirmed scope, design, and acceptance criteria, following the target repository's rules for worktrees, implementation, research, review, verification, and delivery.
+For independent final acceptance, apply the [acceptance standard](final-acceptance.md), not inapplicable development workflows.
 
-Check state, every direct prerequisite, authorized scope, and required stage
-inputs. Read `dependsOn` and its `externalDependsOn` subset: ordinary edges
-express same-chain prerequisites, and external marks distinguish verified
-cross-chain ownership. Both kinds must be done before starting or completing
-work. Classification never grants permission to execute a prerequisite, enable
-automatic execution, or remove a blocker.
+When authorized changes occur, coherently rewrite the actual owning material and affected references, preserving the strength of requirements and acceptance criteria; reconfirm material revisions at the corresponding confirmation points.
+Follow [task management](task-management.md) and [write safety](write-safety.md) when updating fields and editing dependencies.
 
-Missing required content, an unreadable required source, or a missing required
-architecture reference or input leaves execution unready. Resolve it within
-existing authorization or return the concrete issue. Do not infer requirements
-from a title or silently invent acceptance criteria. Do not execute prerequisites
-as an implicit expansion of the requested task.
+When creating a PR, its description must clearly explain the problem being solved and how the change addresses it.
+If the PR is associated with a Daynight task, include the task's ID and title.
 
-Before analysis, questions, or proposals, establish this task's confirmed scope
-and acceptance criteria and apply the [shared scope constraint](../SKILL.md#shared-constraints)
-to execution and discussion.
+Save the URLs and titles of all required delivery PRs in the complete `properties.pullRequests` list, preserving existing entries. Save actual deliverables, current conclusions, and acceptance results in the owning task's material; keep implementation steps, CI, reviews, merge handling, and operational authorization in the session or corresponding platform under the content standard.
 
-## Execute and maintain continuity
+## Completion conditions
 
-Identify [final acceptance](../SKILL.md#final-acceptance) from the task's confirmed
-outcome before applying a development or PR delivery lifecycle. Read the complete
-requirements and actual deliveries for the task or Goal being assessed, and
-apply the shared rule to verification methods, temporary helpers, and result
-ownership.
+| Task type | Completion conditions |
+| --- | --- |
+| Goal discussion | The user confirms the current material, and the corresponding Goal stage requirements are met; generic PR rules cannot replace or add confirmation requirements. |
+| PR delivery | The hosting platform confirms that all required delivery PRs are merged, and stage acceptance criteria are met; finished code, passing CI, approval, an open PR, or entry into a merge queue is not enough. |
+| No PR delivery | Meet stage acceptance criteria and the selected mode's delivery requirements, without inventing PRs or unrelated approvals. |
+| Final acceptance | Also meet the [acceptance requirements](final-acceptance.md) for the complete task or Goal. |
 
-Follow the target repository's instructions for worktrees, implementation,
-review, validation, and delivery. Use the task's required design inputs and
-acceptance criteria, including applicable final-style prototype interactions.
-Keep the implementation or discussion plan in the session.
-Requirements discussion defines the problem without architecture decisions or
-production implementation. Solution discussion keeps its draft architecture and
-breakdown in its owning task. Preserve the Goal's user-confirmation gates:
-completed text, a review result, or successful checks cannot replace the user's
-confirmation or authorize delivery. Keep an unconfirmed discussion in progress;
-a material revision after confirmation needs renewed user confirmation.
+Verify actual merges through the hosting platform's native client or API, without assuming a specific platform.
+When the user requires PRs to remain open for review or prohibits merging, deliver reviewable results and keep the task in progress, without enabling auto-merge.
+Completion remains pending when permission is missing, verification is impossible, or merge conditions are unmet.
 
-Resolve material changes to the agreed solution or acceptance within the current
-authorization. Rewrite the owning artifact and affected task summaries and input
-references coherently. Preserve requirements; do not silently weaken acceptance.
-Descriptions remain self-contained Markdown task summaries. Preserve valid
-syntax, required task content, and actual resource references during full-field
-updates; confirm new or replaced resources before linking them. Apply the content
-boundary to authorized rewrites without modifying unrelated historical tasks.
-Dependency edits
-must follow the handbook's CLI replacement contract: read full D/E, retain needed
-ordinary D−E and external E declarations, submit their intended complete sets
-with the observed version, and read back both. Omit all dependency options for
-unrelated metadata updates. Keep detailed task content and produced results at
-their identified owners; shared inputs remain at their verified source.
+Before returning to the mode-specific file for completion operations, confirm that required deliverables and acceptance conclusions are readable.
+Completing a stage establishes only that stage's results, not completion of the whole Goal.
 
-Advance only this task. Subagents collaborate on it, and waiting for CI, review,
-approval, or merge remains part of it. Keep all required delivery PR URLs and
-titles in the complete `properties.pullRequests` list, preserving existing
-entries. Save actual task results and acceptance conclusions at their owners.
-Use verified artifact locations or immutable revisions when needed to identify
-the final deliverable. Rewrite current results coherently rather than
-accumulating an execution log. Keep operational authorization, implementation
-steps, CI/review/merge handling, progress, blockers, waiting items, and next
-action in the conversation or existing execution checkpoint, retaining the task
-ID and needed PR and workspace references. Recover authorization and assignment
-from that session context, not task material or status.
+## Waiting context
 
-## Confirm acceptance readiness
-
-Goal requirements and solution discussion tasks use the user-confirmed material
-and stage acceptance in the Goal protocol. A generic repository PR rule does not
-add a PR-merge prerequisite to these Daynight discussions. If particular
-repository artifacts or PR delivery are explicitly part of that discussion
-task's acceptance, honor that requirement under its delivery rules.
-Unconfirmed discussion material keeps its discussion task in progress.
-
-Development tasks and design or documentation delivery tasks with PRs remain
-in progress until the hosting platform confirms **every necessary delivery PR
-is merged** and all stage acceptance criteria are satisfied. Code completion,
-passing CI, approved review, and an open PR do not satisfy this condition. Verify
-actual merge state through the host's native client or API; do not assume a
-particular host.
-
-Completion rules grant no merge, deployment, external communication, or mainline
-push permission. Follow existing authorization without asking again for actions
-it covers. If the user requests an open PR for review or forbids merging, deliver
-the reviewable PR and preserve the waiting checkpoint. Do not enable auto-merge.
-Missing permission, unavailable merge visibility, or an unmet merge check keeps
-completion pending and successors blocked.
-
-For tasks without a development or PR delivery path, use their stated stage
-acceptance. For [final acceptance](../SKILL.md#final-acceptance), also apply the
-shared whole-task or whole-Goal completion rule. In every case, confirm the
-required deliverables and acceptance conclusions are readable before returning
-to the execution mode's completion operation; retain operational verification
-in the session. Discussion completion establishes that stage's accepted
-output; it does not establish whole-Goal completion.
-
-## Preserve waiting context
-
-Continue CI and review waits as this task. When progress requires external
-intervention, preserve the target, actual state, concrete blocker, existing work,
-and next action in the checkpoint, then return the waiting result through the
-selected execution mode. Do not declare completion or select other work to
-bypass a wait. Preserve the task ID through recovery and waiting.
+CI, review, and merge waits belong to the current task; the execution mode defines continued waiting, signaling, and return behavior.
+When intervention is needed, preserve the task ID, actual status, existing work, specific blocker, PR and workspace references, existing authorization, and next step in the session checkpoint, not a task execution log.
+Recover the assignment and authorization from this context, not by inferring them from task status.
+Waiting neither completes the task nor permits selecting other work.

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

@@ -0,0 +1,135 @@
+# Task management
+
+Covers query scope, metadata, lifecycle, and dependency semantics.
+See [authorization and scope](authorization.md) for operational permissions.
+Follow [write safety](write-safety.md) for all writes.
+Consult the relevant `--help` for arguments and field-clearing syntax.
+
+## Task queries
+
+| Read operation | Scope and limits |
+| --- | --- |
+| `task ready` | One capped page of candidate `todo` tasks whose direct prerequisites are all complete, ordered by creation, not relevance. An empty page does not rule out in-progress or blocked work. |
+| `task list` | Traverse all matching pages. Excludes `done` by default; explicitly include completed tasks when checking for duplicates or inspecting history. |
+| `task show` | A single task's full description, metadata, and exact version. Read it before operating on the selected task. |
+| `task graph <task-id>` | The target's full bidirectionally connected component of ordinary dependencies, plus one layer of external prerequisites for those tasks. Includes all statuses without recursively expanding external tasks. |
+
+Human-readable lists are summaries; JSON lists omit only `description`.
+Ready results, task details, and write results that return tasks contain complete tasks.
+Dependency graphs provide compact relationship context without full descriptions, PR properties, or versions and cannot replace task details. `--depends-only --json` returns only `id`, the full `dependsOn` set, and its `externalDependsOn` subset.
+Graph nodes retain complete dependency references, which may point outside the graph; read the relevant tasks or their dependency graphs when those paths need assessment.
+Reaching the graph limit fails the command rather than returning a truncated graph.
+A candidate page or a single task cannot replace complete relationship verification.
+
+Lists group tasks into in-progress, ready todo, blocked todo, and, when explicitly included, done.
+These groups are not relevance rankings. See command help for filter syntax.
+
+## Metadata
+
+`task update` cannot change status.
+A supplied description or PR reference list fully replaces that field; retain content that must remain and omit unrelated fields.
+PR URLs are paired with titles; see help for syntax.
+See the [task content standard](task-content.md) for organizing descriptions and attachments.
+
+| Field | Semantics and limits |
+| --- | --- |
+| `allowAgents` | Permission for automatic selection. False for new tasks and cannot be enabled during creation. Enable only after an explicit [handoff](handoff.md) review. Omitting it from an update preserves its value. |
+| `requiredPlatform` | `null`, `windows`, `linux`, or `macos`; null means unrestricted. Can be specified during creation or updates and cleared during updates. |
+
+Actual changes to either field are prohibited while `in_progress`.
+Same-value requests preserve the version and timestamps, but stale versions still conflict.
+Status operations and other metadata operations preserve these fields.
+
+List and ready support filtering by automatic-execution permission and platform compatibility.
+The service combines filters before pagination or candidate limits.
+Platform compatibility includes unrestricted and exact-match tasks without changing dependency readiness.
+Preserve filters across pages; do not locally filter a capped, unfiltered ready page.
+
+Ordinary execution explicitly targeted by the user is not restricted by automatic-selection permission or platform compatibility, but must still satisfy dependency, input, and authorization requirements.
+Automatic execution must use the actual runtime platform and recheck full task eligibility before starting.
+Query arguments do not prove the actual environment; a Linux runtime in WSL is Linux.
+
+## Status and timing
+
+New tasks are `todo`, have no approval status, and do not execute automatically.
+Use `task set-status` to set `todo`, `in_progress`, or `done`.
+Ordinary operations carry no claim; completion of a worker assignment must use [original-claim completion](autopilot-managed-task.md#complete-the-original-claim).
+If either path is rejected, do not fall back to the other.
+
+All direct prerequisites must be done before entering `in_progress` or `done`.
+A completed prerequisite cannot be reopened while a direct successor is `in_progress` or `done`; successors are not modified automatically.
+
+| Transition | Timing result |
+| --- | --- |
+| Enter `in_progress` | Start a new execution interval and clear the completion time. |
+| Return to `todo` | Clear the start and completion times. |
+| `in_progress` -> `done` | Preserve the nullable start time and record the completion time. |
+| `todo` -> `done` | Record only the completion time; elapsed time is unknown. |
+
+An actual status change increments the version once; a same-status operation with the current version changes no fields.
+Metadata updates and same-status operations preserve timing.
+Ordinary status changes have no process ownership, release, withdrawal, stop, or lease semantics.
+
+## Dependency classification
+
+`dependsOn` is the set D of all direct prerequisites, and `externalDependsOn` is its external subset E; ordinary dependencies are D minus E.
+These are normalized UUID sets without duplicates or ordering semantics.
+
+Ordinary dependencies belong to the same task chain; external dependencies are verified cross-chain prerequisites within the same project, not cross-project references.
+Both kinds block starting and completion and participate in cycle and access checks.
+Verify actual content and ownership; do not infer classification from done status, similar titles, graph roots, or connected components.
+
+### CLI relationship replacement
+
+`--depends-on` supplies the ordinary set, and `--external-depends-on` supplies the external set.
+Supplying either option replaces all relationships and their classification: supplying only the ordinary option clears the external subset; supplying only the external option retains only those external relationships.
+This is not an append operation.
+
+Before editing, read the full D/E sets, compute D minus E, and declare every relationship that must remain with its intended classification.
+Duplicate UUIDs, including equivalent UUIDs repeated across options, fail.
+Omitting both options preserves relationships; the dependency-clearing option empties both sets and cannot be combined with dependency declarations.
+After writing, [verify dependency changes](#verify-dependency-changes) across the complete relationships.
+
+Partial updates through direct API patches differ from CLI semantics; do not infer that the CLI preserves undeclared relationships.
+Omit all dependency options when updating only other metadata.
+
+### Dependency reduction
+
+Before creating tasks, registering a Goal breakdown, or changing dependencies, read the relevant dependency paths and retain only necessary direct prerequisites.
+In `A -> B -> C`, arrows point from prerequisites to successors; C declares only B, not A again.
+
+An ordinary edge is redundant only when another path consisting entirely of ordinary edges supplies the same prerequisite; an external edge may be supplied by an alternative path containing either kind of edge.
+Preserve classification and check that all necessary paths still exist after reduction.
+Source references do not require extra execution dependencies; this rule does not authorize cleaning up unrelated existing relationships.
+
+### Verify dependency changes
+
+After creating, replacing, or clearing dependencies, you must call `task graph` to read back the actual dependency graphs of the tasks involved, for example:
+
+```bash
+daynight task graph <task-id> --depends-only --json
+```
+
+Compare the D/E sets and classification with expectations, check that required prerequisite paths are complete, and check for direct edges removable under the reduction rules.
+Disconnecting relationships may split the graph into multiple components; read each component starting from the tasks involved, not just the portion still connected to one starting task after the change.
+Also read any paths outside the graph that require verification; an absent node does not prove that a dependency is missing or that no redundancy exists.
+
+Do not report dependency checks as passed if graph reads fail or required paths remain unverified.
+If missing or redundant relationships are found, reread task details, decide on changes, and verify again only within the authorized scope.
+Consult `daynight task graph --help` for command arguments.
+
+## Task deletion
+
+`task delete` soft-deletes a task, removing it from ordinary lists, dependency graphs, ready results, and detail access while retaining stored data, its own prerequisite references, and attachments.
+Deletion is independent of status and is not completion.
+
+Deletion is strict by default: it is rejected if any undeleted task has a dependency pointing to the target.
+When `--remove-depends` is explicitly authorized, the same transaction deletes the target and removes other tasks' ordinary and external dependencies on it, including references added before the transaction; this may make successors ready.
+Tasks whose relationships change increment their versions while preserving status, timing, worker ownership, and other fields.
+
+Deletion is always prohibited while the target has an active worker claim.
+Reconsider deletion only after the stopped worker is released through an authorized management workflow; status changes cannot replace release.
+
+Successful deletion returns neither a task resource nor a count of removed references.
+If the response is uncertain, read the task: `410 task_deleted` confirms deletion; if the task still exists, decide again; permission or transport failures leave the outcome unconfirmed.
+Do not equate inaccessibility or absence with deletion, and do not automatically replay deletion.