sw-status

name	sw-status
description	Shows current Specwright state for this worktree, the attached work, repo-wide active works, gate results, and lock status. Supports --reset, --cleanup, and --repair {unitId}.
argument-hint	[--reset | --cleanup | --repair {unitId}]
allowed-tools	["Read","Write","Bash","Glob","AskUserQuestion"]

Specwright Status

Goal

Tell the user what this worktree is attached to, what that work is doing, what other works are active in the repository, which runtime layout is active, and what the next action should be.

Inputs

• {projectArtifactsRoot}/config.json
• {worktreeStateRoot}/session.json
• {repoStateRoot}/work/*/workflow.json
• {workArtifactsRoot}/{selectedWork.id}/approvals.md when a work is attached
• {workDir}/review-packet.md when the selected unit has reached verify or ship artifacts

Outputs

• Formatted status display for the current session and selected work
• Repo-wide summary of active works and their owner worktrees
• In --repair mode: remediation outcome for the targeted shipped unit

Constraints

Display (HIGH freedom):

• Print the resolved projectArtifactsRoot, repoStateRoot, worktreeStateRoot, and workArtifactsRoot before the session summary so tracked project artifacts and the active runtime layout are inspectable.
• Name the runtime layout explicitly: project-visible runtime roots under .specwright-local/ are the recommended interactive default, while git-admin roots under .git/specwright/ are compatibility mode.
• Show the current session first: worktreeId, mode, branch, and attachedWorkId.
• If the session is attached, show that work's status, unit/task progress, the selected work's target branch and latest freshness state, configured work-artifact publication mode when present, approval freshness reason, latest closeout or review-packet availability, review-packet presence, gates, and per-work lock freshness.
• Keep the operator vocabulary aligned with the primary adapter surfaces: attached work, branch validity, approval or closeout posture, live ownership, and next action.
• If the attached work is already owned by another live top-level worktree, surface that conflict explicitly and point the operator to /sw-adopt instead of implying that status can mutate ownership.
• Enumerate other active works discovered under repoStateRoot/work/*, along with their recorded owner worktrees and whether the owner still has a live top-level session.
• If no work is attached in this worktree, say so and suggest /sw-design.
• Keep the output concise.

Non-interactive context (LOW freedom):

• Follow protocols/headless.md when AskUserQuestion is unavailable.
• --reset: abort without confirmation and report that reset requires a human.
• --cleanup: report-only. List eligible work directories but do not delete them.
• --repair: report-only. Inspect the selected or uniquely matched work/unit, print what interactive repair would do, and never mutate workflow state in headless mode.

Reset mode (LOW freedom):

• --reset applies to the work attached to this worktree session.
• Confirm with the user before mutating anything.
• If confirmed: set the selected work's status to abandoned, clear that work's lock, clear its gates, and detach this session if it points at that work.
• Follow protocols/state.md for all mutations.

Cleanup mode (MEDIUM freedom):

• Scan {repoStateRoot}/work/ for work directories.
• Exclude any work currently claimed by a live session from deletion choices.
• Present only non-attached work directories for deletion.
• Canonicalize {repoStateRoot}/work/ and each selected candidate with realpath before removing anything.
• Verify each canonical candidate is a direct child of the canonical {repoStateRoot}/work/ directory.
• If canonicalization fails, or a candidate escapes the allowed direct-child scope, skip it with a warning.
• Delete only the user-selected, verified paths.

Repair mode (MEDIUM freedom):

• --repair {unitId} first looks in the selected work, if one is attached.
• If no selected work is attached, or the unit is absent there, search repo-wide workflows for a unique matching unitId.
• If the match is ambiguous across works, stop and tell the user which work IDs conflict.
• Repair applies only to shipped units with prNumber=null.
• If gh confirms a merged PR, populate the owning work's prNumber and prMergedAt and report repaired.
• If no PR can be proven, offer the same three outcomes as before: revert-to-building, mark-abandoned, force-shipped-with-note.
• force-shipped-with-note appends the user's assertion to the owning decisions.md.
• If repo-wide inspection finds stale attachments without live top-level sessions, report them as stale attachments and never treat them as active owners.

Protocol References

• protocols/context.md -- logical roots and session/work resolution
• protocols/state.md -- per-work workflow schema and mutation rules

Failure Modes

Condition	Action
no shared/session state can be resolved	tell the user to run /sw-init
selected workflow parse error	show the raw error and stop
stale per-work lock detected	offer to clear it with a warning
--repair target ambiguous across works	stop and list matching work IDs