Fix Task Builder workflows

Use this page when a Task Builder Session is missing, cannot be edited, or is not ready to publish. Building draft type, title, Markdown, Mass or Weight, same-session Plan membership, labels, and same-session dependencies can be edited in the browser. Draft creation, proposed Plan definitions, order, metric exclusion, and scheduling changes use the local AI conversation and CLI. Publication remains your action in the application.

Ask your local AI tool to inspect the Task Builder Sessions available to the initialized project.

Ask your local AI tool to include archived sessions when needed, select an available Building session, or clear an outdated local selection before choosing the right one.

The expected result is a current Building session selected for later draft changes. If the session is unavailable, confirm the selected repository project and your access without attempting to infer another project's sessions.

Published sessions are immutable history. Return to the planning conversation and create or select a Building session for new draft work. Do not try to alter a Published session or its published records through Task Builder.

The expected result is a Building session where draft changes are available. Published tasks and Plans use their normal product workflows after publication.

A draft may change through another browser or the CLI after you open its editor. The rejected save preserves your unsaved type, title, Markdown, size, Plan, labels, and dependencies. Review the current saved draft and merge your intended changes before retrying. Reload saved draft replaces the editor with saved values; unsaved changes require confirmation before they are discarded. Canceling that confirmation keeps your fields.

If someone published the session while your editor was open, the save is rejected and your text remains available to copy. Published snapshots cannot be edited. Do not try to republish that session.

Run alterac-ai task-builder show <SESSION-NUMBER> and review the draft’s current type, title, Markdown, size, Plan membership, labels, and dependencies. Copy its --expected-updated-at timestamp into the replacement command. It is the draft’s updatedAt, not the session timestamp. Content updates and task set-plan, set-labels, and set-dependencies replacements accept this optional version, including when clearing a relationship.

After a stale-version rejection, run show again, review current type, content, and relationships, merge the changes, and retry with the latest reviewed draft token. Do not automatically refresh the token and overwrite fields you have not reviewed. Older CLIs and commands without --expected-updated-at remain supported with their previous last-write-wins behavior; they can overwrite changes saved after your read. Browser saves always check the reviewed version. Check the command’s help before using the option; install an available release to gain version-checked CLI updates if needed. Refreshing repository guidance does not update the executable.

Read every readiness message before publishing. Errors prevent publication. Correct draft type, content, size, same-session Plan membership, labels, or same-session dependencies through Edit on the draft detail page; use the planning conversation and CLI for proposed Plan definitions, order, metric exclusion, and scheduling. Common causes include missing required content, out-of-range Mass or Weight, unavailable or conflicting labels, invalid draft membership, and dependency references that cannot be published safely. Both Coding agent and Person drafts can publish when the session meets these readiness rules.

Missing Mass or Weight does not block saving or publication. Changing draft type clears the previous size for optional re-estimation. The publication confirmation reminds you to review missing estimates, and publishing preserves an empty estimate. Readiness warnings are also nonblocking: an archived Building session can be ready, but its published history remains hidden from normal discovery until it is restored.

The expected result is no readiness errors and an intentional decision about any warning before you use the visible Publish action.

Open the reported draft's Edit page or use the stable draft IDs shown by session output with the CLI. Remove the circular dependency so no draft eventually depends on itself; dependencies can reference only other draft tasks in the same session. For labels, choose only labels currently available to the selected project and avoid conflicting labels in the same scoped group.

The expected result is a readiness result without that error. Do not replace a label or dependency blindly: confirm that the revised draft still represents the intended work.

If the CLI reports an unknown set-sprint or set-milestone command, first check scheduling command availability. Refreshing repository guidance or enabling a project feature cannot add commands to an older executable.

A draft can publish only into a future Planned Sprint in this project while Sprints are enabled. If its target became Current or Complete, is unavailable, or belongs to another project, ask your local AI tool to replace or clear Sprint membership through the CLI. The review website keeps this choice read-only and shows blockers in the session readiness area.

If Sprints are disabled, Sprint metadata and row references are hidden but the session readiness blocker remains. Ask a Team Lead to re-enable Sprints in Project Settings, or clear membership through the CLI. If the blocker reports missing Sprint access, ask an ordinary project member or organization Owner/Admin to publish or update the draft.

Expected result: the affected draft has an eligible future target or no Sprint membership, readiness has no Sprint blocker, and the complete session can be published when its other checks pass. Failed publication preserves the Building session and its draft metadata. See Review and publish a session.

The review website shows accessible Milestone links, lifecycle, and saved Current intent, with blockers in the session readiness area. There is no Milestone editor in review. Use the affected draft number and title to ask your local AI tool to find its stable ID and recover the saved intent through task-builder task set-milestone. Select an enabled same-project Planned or Current target, save explicit --milestone-change correction or --milestone-change scope-change for a Current target, or omit both options to clear target and intent. Planned assignment and clearing reject Current intent. Complete targets are ineligible. Current is Started in API and JSON output.

If the target became Current after a Planned assignment, save a Scope change choice for newly added work. Correction needs Team Lead authority and counts the published task in the opening plan, while retaining its actual creation and completion times. Choose this intent when correcting the baseline; use Scope change when the work should enter scope at publication time.

Clearing remains available to any authorized session editor when Milestones are disabled, the target is unavailable, or scheduling access is missing. This includes an editor with standing platform-support access alone. Assigning or replacing a target and publishing scheduled work require ordinary project membership or organization Owner/Admin access. A Team Lead can re-enable Milestones in Project Settings if you want to keep the target. A failed replacement preserves the previous target and intent.

Disabled Milestone metadata and links are hidden while readiness still explains saved-target blockers. Unavailable, deleted, cross-project, or inaccessible targets have no link or protected target details. Clearing draft metadata needs no feature re-enablement and does not change live membership. If publication rejects a previously ready session, review the refreshed server errors, correct the saved intent through Task Builder, and retry only after readiness clears.

Expected result: the affected draft has an eligible target with valid intent, or no saved Milestone assignment. Readiness has no Milestone blocker. A failed publication leaves all drafts intact and creates no partial tasks, memberships, or Milestone history. See Resolve saved Milestone intent.

Ask your local AI tool to refresh the session and use the stable draftPlanId or draftId from the current result. Do not substitute a Plan or task position. Both IDs must belong to the same Building session when assigning a task to a proposed Plan.

If a grouping should be cleared, choose Standalone in the draft editor's Plan field or ask the local AI tool to clear membership; it does not change published Plans or tasks. If a Plan was removed, its former member tasks already became Standalone and keep their stable task IDs.

The expected result is an assignment to one current same-session proposed Plan or an explicit Standalone task, without changing published Plans or tasks.

Publication is all-or-nothing. If it fails, no partial set of Plans or tasks was created and the session remains Building; resolve the reported readiness problem and publish again when ready. If a session or its published history is hidden, use the archived view and restore it through the application when that visibility is wanted.

The expected result is a Published session with its complete set of published records, or a still-Building session with an actionable error.

For the product language used by Task Builder, see alterac.ai terminology. For repository or sign-in problems before session commands run, see Fix repository setup.