gdd-progress

name	gdd-progress
description	Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit. Activates for requests involving showing current project state, routing to the next action, or a status check.
argument-hint	[--forensic]
tools	Read, Bash, Grep, Glob, mcp__gdd_state__get, mcp__gdd_status, mcp__gdd_phase_current

@reference/retrieval-contract.md

/gdd:progress

Role: Show current position in the pipeline and recommend the next action. With --forensic, run a 6-check integrity audit.

Step 1 - Read state

Two paths - MCP preferred when available, file-read fallback otherwise.

MCP path (preferred)

When the harness exposes mcp__gdd_status (Phase 27.7+, registered via npx @hegemonart/get-design-done --register-mcp):

1. Call mcp__gdd_status (no args). Returns {phase, branch, last_decisions, last_completed_plans, blocker_count} in one call.
2. If you need stage / task_progress for the output line, call mcp__gdd_phase_current (no args). Returns {phase, stage, task_progress, status}.
3. Skip to Step 2.

This path loads the full priming context in 1–2 MCP calls (~3s, ~32k tokens - Storybloq benchmark).

File-read path (fallback)

When MCP tools are not available, fall back to the legacy flow:

1. Call mcp__gdd_state__get if exposed (Phase 20 STATE.md mutator MCP) → parsed state object. Otherwise, Read .design/STATE.md and parse the frontmatter + <position>, <decisions>, <plans> sections.
2. Extract: stage, cycle, last_checkpoint, task_progress, status, decisions.length, open todos from .design/TODO.md (count unchecked - [ ] - outside the MCP catalog, so Read is still used).
3. If STATE.md is missing, print: "No pipeline state. Run /gdd:brief first." and stop.

This path loads the same context in 5–10 file reads (~100s, ~46.5k tokens - file-reading baseline).

Step 2 - Default output

━━━ Pipeline state ━━━
Stage: <stage>   Cycle: <cycle or "default">   Wave: <wave>
Last checkpoint: <timestamp>
Decisions: <N>   Open todos: <N>
Next: /gdd:<next-stage>
━━━━━━━━━━━━━━━━━━━━━━

Recommend next stage via the same logic as /gdd:next (route by which artifacts exist).

First-run connection nudge

After the pipeline state block, if every <connections> entry from the snapshot is not_configured AND .design/config.json > connections_onboarding is absent, append once per session (transient marker .design/.connections-nudge-shown): Tip: run /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).

Step 3 - Forensic audit (only if --forensic)

Run these six checks and print PASS/WARN/FAIL per check:

1. Stale artifacts - compare mtime of .design/DESIGN.md against most recent file under src/ via ls -lt. WARN if DESIGN.md is older by >7 days.
2. Missing transitions - stage from the mcp__gdd_state__get snapshot vs artifacts present. e.g. stage=plan requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
3. Token drift - wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md; tokens ≈ bytes/4. WARN if combined >50000 tokens.
4. Aged DESIGN-DEBT - read .design/DESIGN-DEBT.md; any item whose line predates HEAD by >14 days (check git blame or file mtime fallback) → WARN.
5. Cycle alignment - if cycle from the snapshot is set but .design/CYCLES.md has no matching heading → FAIL.
6. Connection status - re-probe figma/refero via ToolSearch; compare to the <connections> field in the snapshot. WARN on mismatch.

Also scan .design/SEEDS.md (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content; list them as "Seed ready to germinate: ".

Print:

━━━ Forensic audit ━━━
[PASS] Stale artifacts
[WARN] Token drift — 53,400 tokens combined
[PASS] Missing transitions
[PASS] Aged DESIGN-DEBT
[PASS] Cycle alignment
[WARN] Connection status — figma now unavailable
Seeds ready: 0
━━━━━━━━━━━━━━━━━━━━━━

Step 3.5 - Composition-graph readiness

After the pipeline state (and forensic audit if run), surface a one-line composition-graph hint from scripts/lib/manifest/skills.json. Count skill records declaring composes_with or next_skills, then probe for structural problems (cycles in the directed graph, or edges pointing at a skill name that has no record). Print one line:

• Composition graph: <edges> edges, <skills-with-edges> skills wired | cycles: <n> | dangling: <n>

Run scripts/validate-composition-graph.cjs for the authoritative cycle and dangling-edge counts when that validator is present; until then report 0 and note the graph is not yet wired. This is a readiness hint, not a gate.

Step 3.6 - DesignContext graph coverage

When .design/context-graph.json exists, surface one line for the typed DesignContext graph using the coverage helper in scripts/lib/design-context-query.cjs (node scripts/lib/design-context-query.cjs coverage), then point at the Atomic-Design map: DesignContext graph: <pct>% node-type coverage | map: .design/INTEGRATION-MAP.md. Skip this line entirely when the graph is absent (a pre-Phase-52 project); offer /gdd:migrate-context as the next step instead. Readiness hint, not a gate.

Step 4 - Update notice (safe-window surface)

After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by hooks/update-check.sh subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.

[ -f .design/update-available.md ] && cat .design/update-available.md

No-op when: no new release exists, state-machine guard is active (stage in plan|design|verify), or the latest tag has been dismissed via /gdd:check-update --dismiss.

Do Not

• Do not mutate STATE.md - this skill is read-only. Only mcp__gdd_state__get is permitted.

PROGRESS COMPLETE