shelve

Shelve

Move a completed feature out of the active workspace into the archive directory. This skill is user-invocable only (disable-model-invocation: true) — Claude will not auto-trigger shelving even if the workflow seems "done".

When to use

• The user explicitly invokes /mumei:shelve <feature>.
• A feature has phase: done and the user is ready to clean up the active workspace.

Pre-flight checks

Refuse with a clear error if any of these fail:

1. <feature> slug must exist as a directory under either .mumei/specs/ (spec vehicle) or .mumei/plans/ (plan vehicle). Try specs/ first, then plans/. Refuse if neither has the slug.
2. state.json must have phase: "done" (or phase: "review" with the latest review verdict PASS, with explicit confirmation).
3. Working tree must be clean for files within the feature's _Files:_ scope (spec vehicle only — plan vehicle has no _Files:_ meta and skips this check).
4. .mumei/current is exclusively owned by this skill. No other skill or hook may clear it. If <feature> is the active feature in .mumei/current, this skill auto-clears the file as part of the shelve operation (see Method below). The "owned exclusively" rule prevents session-handoff inconsistency where a prior turn cleared .mumei/current while leaving the spec / plan dir behind, causing the next session to lose track of in-progress work.

Method

source "${CLAUDE_PLUGIN_ROOT}/hooks/_lib/state.sh"

feature="$1"

# auto-detect vehicle by directory existence. spec vehicle
# (.mumei/specs/) takes precedence when both happen to exist; the slug
# collision picker in /mumei:compose is supposed to prevent that situation
# in the first place.
source_dir=""
state_path=""
if [[ -d ".mumei/specs/${feature}" ]]; then
  source_dir=".mumei/specs/${feature}"
  state_path=".mumei/specs/${feature}/state.json"
elif [[ -d ".mumei/plans/${feature}" ]]; then
  source_dir=".mumei/plans/${feature}"
  state_path=".mumei/plans/${feature}/state.json"
else
  echo "Feature not found: ${feature} (looked in .mumei/specs/ and .mumei/plans/)" >&2
  exit 1
fi

# Both vehicles store phase in the same field; mumei_state_read_any
# returns the value from whichever state.json exists.
phase="$(mumei_state_read_any "$feature" '.phase' 2>/dev/null || true)"
if [[ "$phase" != "done" ]]; then
  echo "Feature ${feature} is not done (phase=${phase}). Refuse." >&2
  exit 1
fi

# Phase D — cross-feature dependency guard.
# Refuse to shelve when an active feature declares a Wave-level
# `**Depends-Feature**:` directive pointing at this feature. The user
# can override by either shelving the dependency (remove the
# directive in the dependent's tasks.md) or by archiving in the
# correct order (dependents first).
source "${CLAUDE_PLUGIN_ROOT}/hooks/_lib/dependencies.sh"
dependents="$(mumei_dependencies_active_dependents_of "$feature" 2>/dev/null || true)"
if [[ -n "$dependents" ]]; then
  echo "Cannot shelve ${feature}: active dependent feature(s) still declare it via Wave **Depends-Feature**:" >&2
  printf '  %s\n' $dependents >&2
  echo "Either shelve the dependents first, or remove the Depends-Feature line." >&2
  exit 1
fi

# Calculate archive subdir based on creation month (or current month if missing).
# Both schemas have created_at as ISO 8601.
created_at="$(mumei_state_read_any "$feature" '.created_at' 2>/dev/null || true)"
yyyymm="$(date -u -d "${created_at}" +%Y-%m 2>/dev/null || date -u +%Y-%m)"

target_dir=".mumei/archive/${yyyymm}"
mkdir -p "$target_dir"

# Refuse if target already exists (collision)
if [[ -e "${target_dir}/${feature}" ]]; then
  echo "Archive target already exists: ${target_dir}/${feature}" >&2
  exit 1
fi

# Capture the glean scratch path BEFORE moving the source dir
# (mumei_state_read_any no-ops once the dir is moved). Prefer the recorded
# scratch_source — it survives a feature slug that diverged from the scratch
# basename (collision -N suffix, rename), so the originating scratch is
# co-moved instead of orphaned. Fall back to the legacy slug-match for
# features predating the field. When neither resolves to an existing file,
# the co-move below silently skips.
slug="$(mumei_state_read_any "$feature" '.slug' 2>/dev/null || true)"
[[ -z "$slug" ]] && slug="$feature"
scratch_src="$(mumei_state_scratch_source "$feature" 2>/dev/null || true)"
[[ -z "$scratch_src" ]] && scratch_src=".mumei/scratch/${slug}.md"

# Move the source directory. The move + git history serves as
# the audit trail. Refuse to continue if both git mv and the bare mv
# fallback fail — without an explicit guard the scratch block would
# still run on a half-shelved feature.
git mv "$source_dir" "${target_dir}/${feature}" 2>/dev/null \
  || mv "$source_dir" "${target_dir}/${feature}" \
  || { echo "source dir move failed: ${source_dir}" >&2; exit 1; }

# Move the glean scratch file alongside the spec / plan, if
# present. Vehicle-independent: plan vehicle uses the same scratch
# co-move behaviour as spec vehicle.
if [[ -n "$scratch_src" && -f "$scratch_src" ]]; then
  scratch_dst="${target_dir}/${feature}/scratch.md"
  git mv "$scratch_src" "$scratch_dst" 2>/dev/null \
    || mv "$scratch_src" "$scratch_dst" \
    || mumei_log_warn "shelve: scratch co-move failed for ${scratch_src} (left in place); move it manually or it will linger in .mumei/scratch/"
fi

# Auto-clear .mumei/current if it points at the feature being shelved.
if [[ -f .mumei/current ]]; then
  current="$(tr -d '[:space:]' <.mumei/current)"
  if [[ "$current" == "$feature" ]]; then
    : >.mumei/current
  fi
fi