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 |