fix: proactive documentation and sprint planning automation

- doc-guardian: Hook now tracks documentation dependencies and outputs
  specific files needing updates (e.g., commands → COMMANDS-CHEATSHEET.md)
- projman: SessionStart hook now suggests /sprint-plan when open issues
  exist without milestone, and warns about unreleased CHANGELOG entries
- projman: Add /suggest-version command for semantic version recommendations
- docs: Update COMMANDS-CHEATSHEET.md with data-platform plugin (was missing)
- docs: Update CLAUDE.md with data-platform and version 4.0.0

Fixes documentation drift and lack of proactive workflow suggestions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

plugins/doc-guardian/hooks/notify.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # doc-guardian notification hook
-# Outputs a single notification for config file changes, nothing otherwise
+# Tracks documentation dependencies and queues updates
 # This is a command hook - guaranteed not to block workflow
 
 # Read tool input from stdin (JSON with file_path)
@@ -14,10 +14,45 @@ if [ -z "$FILE_PATH" ]; then
     exit 0
 fi
 
-# Check if file is in a config directory (commands/, agents/, skills/, hooks/)
-if echo "$FILE_PATH" | grep -qE '/(commands|agents|skills|hooks)/'; then
-    echo "[doc-guardian] Config file modified. Run /doc-sync when ready."
+# Define documentation dependency mappings
+# When these directories change, these docs need updating
+declare -A DOC_DEPS
+DOC_DEPS["commands"]="docs/COMMANDS-CHEATSHEET.md README.md"
+DOC_DEPS["agents"]="README.md CLAUDE.md"
+DOC_DEPS["hooks"]="docs/COMMANDS-CHEATSHEET.md README.md"
+DOC_DEPS["skills"]="README.md"
+DOC_DEPS[".claude-plugin"]="CLAUDE.md .claude-plugin/marketplace.json"
+DOC_DEPS["mcp-servers"]="docs/COMMANDS-CHEATSHEET.md CLAUDE.md"
+
+# Check which config directory was modified
+MODIFIED_TYPE=""
+for dir in commands agents hooks skills .claude-plugin mcp-servers; do
+    if echo "$FILE_PATH" | grep -qE "/${dir}/|^${dir}/"; then
+        MODIFIED_TYPE="$dir"
+        break
+    fi
+done
+
+# Exit silently if not a tracked config directory
+if [ -z "$MODIFIED_TYPE" ]; then
+    exit 0
 fi
 
-# Exit silently for all other files (no output = no blocking)
+# Get the dependent docs
+DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
+
+# Queue file for tracking pending updates
+QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
+
+# Add to queue (create if doesn't exist, append if does)
+{
+    echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
+} >> "$QUEUE_FILE" 2>/dev/null || true
+
+# Count pending updates
+PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
+
+# Output notification with specific docs that need updating
+echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
+
 exit 0

plugins/projman/commands/suggest-version.md

@@ -0,0 +1,78 @@
+# /suggest-version
+
+Analyze CHANGELOG.md and suggest appropriate semantic version bump.
+
+## Behavior
+
+1. **Read current state**:
+   - Read `CHANGELOG.md` to find current version and [Unreleased] content
+   - Read `.claude-plugin/marketplace.json` for current marketplace version
+   - Check individual plugin versions in `plugins/*/. claude-plugin/plugin.json`
+
+2. **Analyze [Unreleased] section**:
+   - Extract all entries under `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`
+   - Categorize changes by impact
+
+3. **Apply SemVer rules**:
+
+   | Change Type | Version Bump | Indicators |
+   |-------------|--------------|------------|
+   | **MAJOR** (X.0.0) | Breaking changes | `### Removed`, `### Changed` with "BREAKING:", renamed/removed APIs |
+   | **MINOR** (x.Y.0) | New features, backwards compatible | `### Added` with new commands/plugins/features |
+   | **PATCH** (x.y.Z) | Bug fixes only | `### Fixed` only, `### Changed` for non-breaking tweaks |
+
+4. **Output recommendation**:
+   ```
+   ## Version Analysis
+
+   **Current version:** X.Y.Z
+   **[Unreleased] summary:**
+   - Added: N entries (new features/plugins)
+   - Changed: N entries (M breaking)
+   - Fixed: N entries
+   - Removed: N entries
+
+   **Recommendation:** MINOR bump → X.(Y+1).0
+   **Reason:** New features added without breaking changes
+
+   **To release:** ./scripts/release.sh X.Y.Z
+   ```
+
+5. **Check version sync**:
+   - Compare marketplace version with individual plugin versions
+   - Warn if plugins are out of sync (e.g., marketplace 4.0.0 but projman 3.1.0)
+
+## Examples
+
+**Output when MINOR bump needed:**
+```
+## Version Analysis
+
+**Current version:** 4.0.0
+**[Unreleased] summary:**
+- Added: 3 entries (new command, hook improvement, workflow example)
+- Changed: 1 entry (0 breaking)
+- Fixed: 2 entries
+
+**Recommendation:** MINOR bump → 4.1.0
+**Reason:** New features (Added section) without breaking changes
+
+**To release:** ./scripts/release.sh 4.1.0
+```
+
+**Output when nothing to release:**
+```
+## Version Analysis
+
+**Current version:** 4.0.0
+**[Unreleased] summary:** Empty - no pending changes
+
+**Recommendation:** No release needed
+```
+
+## Integration
+
+This command helps maintain proper versioning workflow:
+- Run after completing a sprint to determine version bump
+- Run before `/sprint-close` to ensure version is updated
+- Integrates with `./scripts/release.sh` for actual release execution

plugins/projman/hooks/startup-check.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # projman startup check hook
-# Checks for common issues at session start
+# Checks for common issues AND suggests sprint planning proactively
 # All output MUST have [projman] prefix
 
 PREFIX="[projman]"
@@ -26,5 +26,41 @@ if [[ -f ".env" ]]; then
     fi
 fi
 
-# All checks passed - say nothing
+# Check for open issues (suggests sprint planning)
+# Only if .env exists with valid GITEA config
+if [[ -f ".env" ]]; then
+    GITEA_API_URL=$(grep -E "^GITEA_API_URL=" ~/.config/claude/gitea.env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true)
+    GITEA_API_TOKEN=$(grep -E "^GITEA_API_TOKEN=" ~/.config/claude/gitea.env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true)
+    GITEA_REPO=$(grep -E "^GITEA_REPO=" .env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true)
+
+    if [[ -n "$GITEA_API_URL" && -n "$GITEA_API_TOKEN" && -n "$GITEA_REPO" ]]; then
+        # Quick check for open issues without milestone (unplanned work)
+        OPEN_ISSUES=$(curl -s -m 5 \
+            -H "Authorization: token $GITEA_API_TOKEN" \
+            "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none&limit=1" 2>/dev/null | \
+            grep -c '"number"' || echo "0")
+
+        if [[ "$OPEN_ISSUES" -gt 0 ]]; then
+            # Count total unplanned issues
+            TOTAL_UNPLANNED=$(curl -s -m 5 \
+                -H "Authorization: token $GITEA_API_TOKEN" \
+                "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none" 2>/dev/null | \
+                grep -c '"number"' || echo "?")
+            echo "$PREFIX ${TOTAL_UNPLANNED} open issues without milestone - consider /sprint-plan"
+        fi
+    fi
+fi
+
+# Check for CHANGELOG.md [Unreleased] content (version management)
+if [[ -f "CHANGELOG.md" ]]; then
+    # Check if there's content under [Unreleased] that hasn't been released
+    UNRELEASED_CONTENT=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md 2>/dev/null | grep -E '^### (Added|Changed|Fixed|Removed|Deprecated)' | head -1 || true)
+    if [[ -n "$UNRELEASED_CONTENT" ]]; then
+        UNRELEASED_LINES=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md 2>/dev/null | grep -E '^- ' | wc -l | tr -d ' ')
+        if [[ "$UNRELEASED_LINES" -gt 0 ]]; then
+            echo "$PREFIX ${UNRELEASED_LINES} unreleased changes in CHANGELOG - consider version bump"
+        fi
+    fi
+fi
+
 exit 0