feat(spec): SPEC-STATUS-AUTO-001 — SPEC status auto-update system (#735)

* docs(spec): SPEC-STATUS-AUTO-001 — SPEC 상태 자동 업데이트 시스템 기획

L1(커밋 기반) + L2(sync 워크플로우) 조합으로 SPEC lifecycle status를
자동 관리하는 시스템. 6가지 SPEC 메타데이터 형식을 모두 지원하는
updater library + CLI 명령어 + PostToolUse hook.

🤖 MoAI <email@mo.ai.kr>

* feat(spec): SPEC-STATUS-AUTO-001 — SPEC status auto-update system (REQ-1/2/3)

Implement automatic SPEC status updates when implementation completes:
- REQ-1: status library with 6 format variants (YAML/list/table/prepend)
- REQ-2: `moai spec status` CLI command with --dry-run and --list flags
- REQ-3: PostToolUse hook detecting git commits with SPEC-ID patterns

New files:
- internal/spec/status.go: Format detection, ParseStatus, UpdateStatus
- internal/hook/spec_status.go: PostToolUse handler for auto-update
- internal/cli/spec.go: Parent `moai spec` command
- internal/cli/spec_status.go: `moai spec status` subcommand
- .claude/hooks/moai/handle-spec-status.sh: Hook wrapper script
- Tests: 16 new tests, 89.1% coverage on internal/spec/

🗿 MoAI <email@mo.ai.kr>

* feat(spec): SPEC-STATUS-AUTO-001 — REQ-4 sync integration + REQ-5 batch sync-git

Add remaining requirements:
- REQ-4: sync.md Step 2.4 now invokes `moai spec status <SPEC-ID> completed`
- REQ-5: `moai spec status --sync-git` batch command scans git log on main,
  extracts SPEC-IDs, and updates statuses with --yes for non-interactive mode

🤖 MoAI <email@mo.ai.kr>

Author: GoosLab

.claude/hooks/moai/handle-spec-status.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# Hook wrapper for SPEC status auto-update
+# Triggered by PostToolUse event after git commit
+
+INPUT=$(cat)
+moai hook spec-status <<< "$INPUT"

.claude/skills/moai/workflows/sync.md

@@ -706,6 +706,12 @@ Update SPEC status based on lifecycle level and implementation completeness:
 - Level 2 (spec-anchored): Set status to "completed" if all requirements met, or "in-progress" if partial. Schedule next review based on quarterly maintenance policy.
 - Level 3 (spec-as-source): Set status based on implementation-SPEC alignment. Flag discrepancies for resolution.
 
+**Implementation** (SPEC-STATUS-AUTO-001 REQ-4):
+```bash
+moai spec status <SPEC-ID> completed
+```
+Failure to update status does not block the sync workflow (warning only).
+
 Record version changes, status transitions, and divergence summary. Include in sync report.
 
 #### Step 2.4.1: GitHub Issue Status Sync

.moai/specs/SPEC-STATUS-AUTO-001/progress.md

@@ -0,0 +1,13 @@
+## SPEC-STATUS-AUTO-001 Progress
+
+- Started: 2026-04-27T10:00:00Z
+- Harness: standard (auto-detected: file_count > 3, spec_type=feature)
+- Development Mode: tdd (quality.yaml)
+- Phase 0.9: Language=Go (moai-lang-go)
+- Phase 0.95: Standard Mode (6 files, 1 domain)
+- plan_artifact_hash: 6d96a8fabe28a193c0bc8631912158a2b58351320f72eecab639a6ce7aab7d09
+- Phase 0.5 complete: audit_verdict=FAIL_WARNED (grace window D-5)
+- audit_report: .moai/reports/plan-audit/SPEC-STATUS-AUTO-001-review-1.md
+- audit_at: 2026-04-27T10:02:00Z
+- auditor_version: plan-auditor
+- defects: 8 critical, 3 major, 4 minor (must-pass: REQ numbering, EARS ACs, frontmatter fields)

.moai/specs/SPEC-STATUS-AUTO-001/spec.md

@@ -0,0 +1,161 @@
+---
+id: SPEC-STATUS-AUTO-001
+version: "1.0.0"
+status: implemented
+created: "2026-04-27"
+updated: "2026-04-27"
+author: GOOS
+priority: P1
+labels: [spec-status, automation, hooks, cli, sync-workflow]
+---
+
+# SPEC-STATUS-AUTO-001: SPEC Status Auto-Update System
+
+## Problem Statement
+
+SPEC documents in `.moai/specs/` track lifecycle status (`draft` → `planned` → `implemented` → `completed`), but status updates are purely manual. When a SPEC's implementation is merged to main, the SPEC frontmatter is often left at `draft` or `planned` indefinitely. 15 SPECs were found in this exact state during audit on 2026-04-27.
+
+Root causes:
+1. No code exists to modify SPEC frontmatter status
+2. `/moai sync` Step 2.4 documents status updates but has no implementation
+3. SPEC metadata formats are fragmented (6 variants: YAML, Markdown list, table, Korean fields)
+4. No trigger mechanism to detect when a SPEC should transition
+
+## Requirements (EARS Format)
+
+### REQ-1: SPEC Status Updater Library (Priority: P0)
+
+**WHEN** `spec.UpdateStatus(specID, newStatus)` is called, **THE SYSTEM SHALL** locate `.moai/specs/<specID>/spec.md`, detect its metadata format (YAML frontmatter, Markdown list, or table), update the status field to `newStatus`, and preserve all other content unchanged.
+
+**Acceptance Criteria:**
+- AC-1.1: Supports all 6 format variants:
+  - YAML `status:` (Format A, B)
+  - Markdown `- **Status**: X` (Format D)
+  - Markdown table `| 상태 | X |` or `| Status | X |` (Format E)
+  - Adds YAML frontmatter block if none exists (Format F)
+- AC-1.2: Validated status values: `draft`, `planned`, `in-progress`, `implemented`, `completed`, `superseded`
+- AC-1.3: Returns error if spec.md file not found or status value invalid
+- AC-1.4: Does not modify any content outside the status field
+- AC-1.5: Unit test coverage >= 90% for all format parsers
+
+### REQ-2: CLI Command (Priority: P0)
+
+**WHEN** `moai spec status <SPEC-ID> <status>` is invoked, **THE SYSTEM SHALL** call the updater library and report success or failure.
+
+**Acceptance Criteria:**
+- AC-2.1: Command registered under `moai spec` parent command
+- AC-2.2: Validates SPEC-ID exists in `.moai/specs/` before attempting update
+- AC-2.3: Prints human-readable confirmation: `SPEC-XXX status updated: draft → completed`
+- AC-2.4: Supports `--dry-run` flag to preview change without writing
+- AC-2.5: Supports `--list` flag to show all SPECs and their current status
+
+### REQ-3: Commit-Based Auto-Detection (L1) (Priority: P1)
+
+**WHEN** a git commit message contains a pattern matching `SPEC-[A-Z0-9]+-[0-9]+`, **THE SYSTEM SHALL** extract the SPEC-ID(s) and automatically update their status to `implemented`.
+
+**Acceptance Criteria:**
+- AC-3.1: Implemented as `internal/hook/spec_status.go` hook handler
+- AC-3.2: Triggered by `PostToolUse` event when tool is `Bash` and command matches `git commit`
+- AC-3.3: Parses commit message from `git log -1 --format=%s`
+- AC-3.4: Extracts all unique SPEC-XXX patterns from the message
+- AC-3.5: For each SPEC-ID found, calls `spec.UpdateStatus(specID, "implemented")`
+- AC-3.6: Logs updated SPECs to stderr (non-blocking — hook exit code always 0)
+- AC-3.7: Gracefully skips if `.moai/specs/` directory does not exist
+
+### REQ-4: Sync Workflow Integration (L2) (Priority: P1)
+
+**WHEN** `/moai sync` completes documentation synchronization, **THE SYSTEM SHALL** update the synced SPEC status to `completed`.
+
+**Acceptance Criteria:**
+- AC-4.1: sync.md Phase 2.4 invokes `moai spec status <SPEC-ID> completed`
+- AC-4.2: Status update occurs after documentation sync succeeds
+- AC-4.3: Failure to update status does not block the sync workflow (warning only)
+- AC-4.4: Logs the status transition in sync output
+
+### REQ-5: Batch Status Command (Priority: P2)
+
+**WHEN** `moai spec status --sync-git` is invoked, **THE SYSTEM SHALL** cross-reference all SPECs in `.moai/specs/` against git log on main and update statuses where implementation commits exist.
+
+**Acceptance Criteria:**
+- AC-5.1: Scans `git log main --oneline --no-merges` for SPEC-XXX patterns
+- AC-5.2: For each SPEC found in commits but not marked `completed`/`implemented`, updates status
+- AC-5.3: Reports a summary: `Updated N SPECs, skipped M (already completed), K not found`
+- AC-5.4: Requires `--confirm` flag (or `--yes` for non-interactive) before writing changes
+
+## Technical Approach
+
+### Package Structure
+
+```
+internal/spec/
+  status.go         # UpdateStatus(), ParseStatus(), Format detection
+  status_test.go    # Unit tests for all 6 format parsers
+
+internal/hook/
+  spec_status.go    # L1 hook handler (PostToolUse)
+
+internal/cli/
+  spec.go           # `moai spec` parent command
+  spec_status.go    # `moai spec status` subcommand
+```
+
+### Format Detection Algorithm
+
+```
+1. Read first 30 lines of spec.md
+2. If contains "---" delimiter → YAML frontmatter
+   a. Parse YAML, look for "status:" key
+   b. If no "status:" key → add it
+3. Else if contains "| 상태 |" or "| Status |" → Table format
+   a. Replace status value in table row
+4. Else if contains "- **Status**:" → Markdown list format
+   a. Replace status value in list item
+5. Else → Prepend YAML frontmatter block with status field
+```
+
+### Hook Registration
+
+In `settings.json` hooks:
+```json
+{
+  "PostToolUse": [{
+    "matcher": "Bash",
+    "hooks": [{
+      "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-spec-status.sh\"",
+      "timeout": 5
+    }]
+  }]
+}
+```
+
+Hook wrapper script reads stdin JSON, checks if bash command was `git commit`, then calls `moai spec status --auto-commit`.
+
+## Scope
+
+### In Scope
+- SPEC status updater library with multi-format support
+- CLI command `moai spec status`
+- L1 PostToolUse hook for commit-based detection
+- L2 sync workflow integration
+- Batch sync-git command
+
+### Out of Scope
+- L3 PR merge detection via GitHub Actions (future SPEC)
+- SPEC lifecycle state machine enforcement (validation only)
+- Web UI for SPEC status management
+- Automatic archiving of completed SPECs
+
+## Dependencies
+
+- Existing `internal/cli/` command structure (cobra)
+- Existing `internal/hook/` hook handler pattern
+- `.moai/specs/` directory structure (convention)
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| YAML frontmatter parsing fragile | Use simple line-based regex, not full YAML parser |
+| Hook timeout on large commit messages | 5s timeout, process only first line |
+| Race condition on concurrent edits | SPEC files are single-writer (one session at a time) |
+| False positive SPEC pattern in commit body | Only match conventional commit title (first line) |

.moai/specs/SPEC-STATUS-AUTO-001/tasks.md

@@ -0,0 +1,14 @@
+## Task Decomposition
+SPEC: SPEC-STATUS-AUTO-001
+
+| Task ID | Description | Requirement | Dependencies | Planned Files | Status |
+|---------|-------------|-------------|--------------|---------------|--------|
+| T-001 | YAML frontmatter status update (Format A/B) | REQ-1 | - | internal/spec/status.go, internal/spec/status_test.go | pending |
+| T-002 | Markdown list status update (Format D) | REQ-1 | T-001 | internal/spec/status.go | pending |
+| T-003 | Table status update (Format E, KR/EN) | REQ-1 | T-001 | internal/spec/status.go | pending |
+| T-004 | YAML frontmatter prepend (Format F) | REQ-1 | T-001 | internal/spec/status.go | pending |
+| T-005 | ParseStatus + validation | REQ-1 | T-001 | internal/spec/status.go | pending |
+| T-006 | CLI: moai spec status + --dry-run + --list | REQ-2 | T-005 | internal/cli/spec.go, internal/cli/spec_status.go, internal/cli/root.go | pending |
+| T-007 | PostToolUse hook handler + wrapper script | REQ-3 | T-005 | internal/hook/spec_status.go, .claude/hooks/moai/handle-spec-status.sh | pending |
+| T-008 | Sync workflow integration | REQ-4 | T-006 | .claude/skills/moai/workflows/sync.md | pending |
+| T-009 | Batch --sync-git command | REQ-5 | T-005 | internal/cli/spec_status.go | pending |

internal/cli/hook.go

@@ -106,6 +106,15 @@ func init() {
 	}
 	dbSchemaSyncCmd.Flags().String("file", "", "File path from PostToolUse hook stdin")
 	hookCmd.AddCommand(dbSchemaSyncCmd)
+
+	// Add "spec-status" subcommand (SPEC-STATUS-AUTO-001)
+	specStatusCmd := &cobra.Command{
+		Use:   "spec-status",
+		Short: "Auto-update SPEC status on git commit",
+		Long:  "Extract SPEC-IDs from git commit messages and update their status to 'implemented'. Called from handle-spec-status.sh.",
+		RunE:  runSpecStatus,
+	}
+	hookCmd.AddCommand(specStatusCmd)
 }
 
 // @MX:ANCHOR: [AUTO] runHookEvent is the central dispatcher for all Claude Code hook events
@@ -295,6 +304,39 @@ func runDBSchemaSync(cmd *cobra.Command, _ []string) error {
 	return nil
 }
 
+// runSpecStatus handles the spec-status hook subcommand.
+// It reads hook input from stdin and dispatches to the spec status handler.
+func runSpecStatus(cmd *cobra.Command, _ []string) error {
+	if deps == nil || deps.HookProtocol == nil || deps.HookRegistry == nil {
+		return fmt.Errorf("hook system not initialized")
+	}
+
+	// Read hook input from stdin
+	input, err := deps.HookProtocol.ReadInput(os.Stdin)
+	if err != nil {
+		return fmt.Errorf("read hook input: %w", err)
+	}
+
+	ctx, cancel := context.WithTimeout(cmd.Context(), 5*time.Second)
+	defer cancel()
+
+	// Create spec status handler and execute
+	handler := hook.NewSpecStatusHandler()
+	output, err := handler.Handle(ctx, input)
+	if err != nil {
+		// Log but don't fail - hook is non-blocking
+		_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "spec-status: error:", err)
+		return nil
+	}
+
+	if writeErr := deps.HookProtocol.WriteOutput(cmd.OutOrStdout(), output); writeErr != nil {
+		_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "spec-status: write output:", writeErr)
+	}
+
+	// Always exit 0 (non-blocking)
+	return nil
+}
+
 // defaultMigrationPatterns are the built-in migration patterns from SPEC-DB-SYNC-001.
 var defaultMigrationPatterns = []string{
 	"prisma/schema.prisma",

internal/cli/hook_e2e_test.go

@@ -344,6 +344,7 @@ func TestHookValidEventTypes_AllHaveSubcommands(t *testing.T) {
 		"pre-push":         true,
 		"db-schema-sync":   true, // SPEC-DB-SYNC-001: domain hook, not a Claude Code event
 		"harness-observe":  true, // SPEC-V3R3-HARNESS-LEARNING-001: domain hook, not a Claude Code event
+			"spec-status":      true, // SPEC-STATUS-AUTO-001: domain hook, not a Claude Code event
 	}
 
 	for _, cmd := range hookCmd.Commands() {

internal/cli/hook_pre_push_test.go

@@ -73,8 +73,8 @@ func TestReadStdinLines_Empty(t *testing.T) {
 func TestHookCmd_PrePushSubcommandCount(t *testing.T) {
 	// The hook command should now have 31 subcommands (30 previous + 1 new: db-schema-sync, SPEC-DB-SYNC-001).
 	count := len(hookCmd.Commands())
-	// 31 previous + 1 new: harness-observe (SPEC-V3R3-HARNESS-LEARNING-001)
-	if count != 32 {
+	// 32 previous + 1 new: spec-status (SPEC-STATUS-AUTO-001)
+	if count != 33 {
 		names := make([]string, 0, count)
 		for _, cmd := range hookCmd.Commands() {
 			names = append(names, cmd.Name())

internal/cli/hook_test.go

@@ -60,9 +60,9 @@ func TestHookCmd_HasSubcommands(t *testing.T) {
 
 func TestHookCmd_SubcommandCount(t *testing.T) {
 	count := len(hookCmd.Commands())
-	// 31 previous + 1 new: harness-observe (SPEC-V3R3-HARNESS-LEARNING-001 T-P1-03)
-	if count != 32 {
-		t.Errorf("hook should have 32 subcommands, got %d", count)
+	// 32 previous + 1 new: spec-status (SPEC-STATUS-AUTO-001)
+	if count != 33 {
+		t.Errorf("hook should have 33 subcommands, got %d", count)
 	}
 }
 

internal/cli/spec.go

@@ -0,0 +1,27 @@
+package cli
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// newSpecCmd creates the 'moai spec' parent command
+func newSpecCmd() *cobra.Command {
+	specCmd := &cobra.Command{
+		Use:   "spec",
+		Short: "Manage SPEC documents",
+		Long:  `Manage SPEC documents in .moai/specs/ directory.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+		GroupID: "tools",
+	}
+
+	// Add subcommands
+	specCmd.AddCommand(newSpecStatusCmd())
+
+	return specCmd
+}
+
+func init() {
+	rootCmd.AddCommand(newSpecCmd())
+}