mindsystem-cc 3.17.1 → 3.18.1

package/scripts/archive-milestone-files.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+#
+# archive-milestone-files.sh
+# Moves optional milestone files (audit, context, research) to the
+# milestone archive directory. Skips silently if files don't exist.
+#
+# Usage: ./scripts/archive-milestone-files.sh <version>
+# Example: ./scripts/archive-milestone-files.sh v1.0
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ]; then
+  echo "Error: Version argument required"
+  echo "Usage: $0 <version>"
+  exit 1
+fi
+
+VERSION="$1"
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+PLANNING_DIR="$GIT_ROOT/.planning"
+MILESTONE_DIR="$PLANNING_DIR/milestones/$VERSION"
+
+if [ ! -d "$MILESTONE_DIR" ]; then
+  echo "Error: Milestone directory not found at $MILESTONE_DIR"
+  echo "Run archive_milestone step first to create it"
+  exit 1
+fi
+
+# --- Move files ---
+ARCHIVED=0
+
+# Milestone audit
+if [ -f "$PLANNING_DIR/${VERSION}-MILESTONE-AUDIT.md" ]; then
+  mv "$PLANNING_DIR/${VERSION}-MILESTONE-AUDIT.md" "$MILESTONE_DIR/MILESTONE-AUDIT.md"
+  echo "Archived: ${VERSION}-MILESTONE-AUDIT.md → MILESTONE-AUDIT.md"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+# Milestone context
+if [ -f "$PLANNING_DIR/MILESTONE-CONTEXT.md" ]; then
+  mv "$PLANNING_DIR/MILESTONE-CONTEXT.md" "$MILESTONE_DIR/CONTEXT.md"
+  echo "Archived: MILESTONE-CONTEXT.md → CONTEXT.md"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+# Research directory
+if [ -d "$PLANNING_DIR/research" ]; then
+  mv "$PLANNING_DIR/research" "$MILESTONE_DIR/research"
+  echo "Archived: research/ → research/"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+if [ "$ARCHIVED" -eq 0 ]; then
+  echo "No optional files to archive (audit, context, research all absent)"
+else
+  echo ""
+  echo "Archived $ARCHIVED item(s) to milestones/$VERSION/"
+fi
+
+exit 0

package/scripts/archive-milestone-phases.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+#
+# archive-milestone-phases.sh
+# Consolidates phase summaries, deletes raw artifacts, and moves phase
+# directories to the milestone archive.
+#
+# Usage: ./scripts/archive-milestone-phases.sh <start_phase> <end_phase> <version>
+# Example: ./scripts/archive-milestone-phases.sh 1 6 v1.0
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]; then
+  echo "Error: Three arguments required"
+  echo "Usage: $0 <start_phase> <end_phase> <version>"
+  exit 1
+fi
+
+START="$1"
+END="$2"
+VERSION="$3"
+
+if ! [[ "$START" =~ ^[0-9]+$ ]] || ! [[ "$END" =~ ^[0-9]+$ ]]; then
+  echo "Error: start_phase and end_phase must be numeric"
+  echo "Usage: $0 <start_phase> <end_phase> <version>"
+  exit 1
+fi
+
+if [ "$START" -gt "$END" ]; then
+  echo "Error: Start phase ($START) cannot exceed end phase ($END)"
+  exit 1
+fi
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+PHASES_DIR="$GIT_ROOT/.planning/phases"
+if [ ! -d "$PHASES_DIR" ]; then
+  echo "Error: Phases directory not found at $PHASES_DIR"
+  exit 1
+fi
+
+MILESTONE_DIR="$GIT_ROOT/.planning/milestones/$VERSION"
+if [ ! -d "$MILESTONE_DIR" ]; then
+  echo "Error: Milestone directory not found at $MILESTONE_DIR"
+  echo "Run archive_milestone step first to create it"
+  exit 1
+fi
+
+# --- Helper: check if phase number is in range (supports decimals like 02.1) ---
+in_range() {
+  local phase_num="$1"
+  echo "$phase_num" | awk -v s="$START" -v e="$END" '{
+    # Strip leading zeros for comparison
+    val = $1 + 0
+    if (val >= s && val <= e + 0.999) exit 0
+    else exit 1
+  }'
+}
+
+# --- Stage 1: Consolidate summaries ---
+SUMMARIES_FILE="$MILESTONE_DIR/PHASE-SUMMARIES.md"
+SUMMARY_COUNT=0
+
+echo "# Phase Summaries: $VERSION" > "$SUMMARIES_FILE"
+echo "" >> "$SUMMARIES_FILE"
+
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+  phase_name="${dirname#*-}"
+
+  if in_range "$phase_num"; then
+    has_summaries=false
+    for f in "$dir"/*-SUMMARY.md; do
+      [ -f "$f" ] || continue
+      if [ "$has_summaries" = false ]; then
+        echo "## Phase $phase_num: $phase_name" >> "$SUMMARIES_FILE"
+        echo "" >> "$SUMMARIES_FILE"
+        has_summaries=true
+      fi
+      plan_file=$(basename "$f")
+      plan_id="${plan_file%-SUMMARY.md}"
+      echo "### $plan_id" >> "$SUMMARIES_FILE"
+      echo "" >> "$SUMMARIES_FILE"
+      cat "$f" >> "$SUMMARIES_FILE"
+      echo "" >> "$SUMMARIES_FILE"
+      SUMMARY_COUNT=$((SUMMARY_COUNT + 1))
+    done
+  fi
+done
+
+echo "Stage 1: Consolidated $SUMMARY_COUNT summaries to PHASE-SUMMARIES.md"
+
+# --- Stage 2: Delete artifacts ---
+DELETED=0
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+
+  if in_range "$phase_num"; then
+    for f in "$dir"/*-CONTEXT.md "$dir"/*-DESIGN.md "$dir"/*-RESEARCH.md \
+             "$dir"/*-SUMMARY.md "$dir"/*-UAT.md "$dir"/*-VERIFICATION.md \
+             "$dir"/*-EXECUTION-ORDER.md; do
+      if [ -f "$f" ]; then
+        rm -f "$f"
+        DELETED=$((DELETED + 1))
+      fi
+    done
+  fi
+done
+
+echo "Stage 2: Deleted $DELETED artifact files"
+
+# --- Stage 3: Move phase directories ---
+mkdir -p "$MILESTONE_DIR/phases"
+MOVED=0
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+
+  if in_range "$phase_num"; then
+    mv "$dir" "$MILESTONE_DIR/phases/$dirname"
+    MOVED=$((MOVED + 1))
+  fi
+done
+
+echo "Stage 3: Moved $MOVED phase directories to milestones/$VERSION/phases/"
+echo ""
+echo "Archive complete: $SUMMARY_COUNT summaries, $DELETED artifacts deleted, $MOVED dirs moved"
+exit 0

package/scripts/gather-milestone-stats.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+#
+# gather-milestone-stats.sh
+# Gathers milestone readiness status and statistics from the filesystem
+# and git history. Outputs structured text for the LLM to present.
+#
+# Usage: ./scripts/gather-milestone-stats.sh <start_phase> <end_phase>
+# Example: ./scripts/gather-milestone-stats.sh 1 6
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Error: Two arguments required"
+  echo "Usage: $0 <start_phase> <end_phase>"
+  exit 1
+fi
+
+START="$1"
+END="$2"
+
+if ! [[ "$START" =~ ^[0-9]+$ ]] || ! [[ "$END" =~ ^[0-9]+$ ]]; then
+  echo "Error: Both arguments must be numeric"
+  echo "Usage: $0 <start_phase> <end_phase>"
+  exit 1
+fi
+
+if [ "$START" -gt "$END" ]; then
+  echo "Error: Start phase ($START) cannot exceed end phase ($END)"
+  exit 1
+fi
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+PHASES_DIR="$GIT_ROOT/.planning/phases"
+if [ ! -d "$PHASES_DIR" ]; then
+  echo "Error: Phases directory not found at $PHASES_DIR"
+  exit 1
+fi
+
+# --- Helper: check if phase number is in range (supports decimals like 02.1) ---
+in_range() {
+  local phase_num="$1"
+  echo "$phase_num" | awk -v s="$START" -v e="$END" '{
+    val = $1 + 0
+    if (val >= s && val <= e + 0.999) exit 0
+    else exit 1
+  }'
+}
+
+# ============================================================
+# READINESS
+# ============================================================
+echo "=== Readiness ==="
+echo ""
+
+PHASE_COUNT=0
+PLAN_COUNT=0
+COMPLETE=0
+INCOMPLETE_LIST=""
+PHASE_DETAILS=""
+
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+  phase_name="${dirname#*-}"
+
+  if in_range "$phase_num"; then
+    PHASE_COUNT=$((PHASE_COUNT + 1))
+    phase_plans=0
+    phase_complete=0
+
+    for plan in "$dir"/*-PLAN.md; do
+      [ -f "$plan" ] || continue
+      PLAN_COUNT=$((PLAN_COUNT + 1))
+      phase_plans=$((phase_plans + 1))
+      plan_base=$(basename "$plan" -PLAN.md)
+      summary="$dir/${plan_base}-SUMMARY.md"
+      if [ -f "$summary" ]; then
+        COMPLETE=$((COMPLETE + 1))
+        phase_complete=$((phase_complete + 1))
+      else
+        INCOMPLETE_LIST+="  $(basename "$dir")/$(basename "$plan")"$'\n'
+      fi
+    done
+
+    PHASE_DETAILS+="- Phase $phase_num: $phase_name ($phase_complete/$phase_plans plans)"$'\n'
+  fi
+done
+
+echo "Phases: $PHASE_COUNT (range $START-$END)"
+echo "Plans: $PLAN_COUNT total, $COMPLETE complete"
+echo ""
+echo "$PHASE_DETAILS"
+
+if [ "$COMPLETE" -eq "$PLAN_COUNT" ] && [ "$PLAN_COUNT" -gt 0 ]; then
+  echo "Status: READY"
+else
+  INCOMPLETE=$((PLAN_COUNT - COMPLETE))
+  echo "Incomplete ($INCOMPLETE):"
+  echo "$INCOMPLETE_LIST"
+  echo "Status: NOT READY"
+fi
+
+# ============================================================
+# GIT STATS
+# ============================================================
+echo ""
+echo "=== Git Stats ==="
+echo ""
+
+# Collect commits matching Mindsystem phase convention: feat(XX-YY), fix(XX-YY), etc.
+ALL_COMMITS=""
+for i in $(seq "$START" "$END"); do
+  phase=$(printf "%02d" "$i")
+  commits=$(git log --all --format="%H %ai %s" --grep="($phase-" 2>/dev/null || true)
+  if [ -n "$commits" ]; then
+    ALL_COMMITS+="$commits"$'\n'
+  fi
+done
+
+# Also capture decimal phase commits (e.g., 02.1 inserted phases)
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+  case "$phase_num" in
+    *.*) # Decimal phase — not captured by seq
+      if in_range "$phase_num"; then
+        commits=$(git log --all --format="%H %ai %s" --grep="($phase_num-" 2>/dev/null || true)
+        if [ -n "$commits" ]; then
+          ALL_COMMITS+="$commits"$'\n'
+        fi
+      fi
+      ;;
+  esac
+done
+
+# Remove empty lines, deduplicate, sort by date
+ALL_COMMITS=$(echo "$ALL_COMMITS" | grep -v '^$' | sort -u -k2,3)
+
+if [ -n "$ALL_COMMITS" ]; then
+  COMMIT_COUNT=$(echo "$ALL_COMMITS" | wc -l | tr -d ' ')
+  FIRST_LINE=$(echo "$ALL_COMMITS" | head -1)
+  LAST_LINE=$(echo "$ALL_COMMITS" | tail -1)
+  FIRST_HASH=$(echo "$FIRST_LINE" | awk '{print $1}')
+  LAST_HASH=$(echo "$LAST_LINE" | awk '{print $1}')
+  FIRST_DATE=$(echo "$FIRST_LINE" | awk '{print $2}')
+  LAST_DATE=$(echo "$LAST_LINE" | awk '{print $2}')
+  FIRST_MSG=$(echo "$FIRST_LINE" | cut -d' ' -f4-)
+  LAST_MSG=$(echo "$LAST_LINE" | cut -d' ' -f4-)
+
+  # Calculate days
+  DAYS=$(python3 -c "from datetime import date; print((date.fromisoformat('$LAST_DATE') - date.fromisoformat('$FIRST_DATE')).days)" 2>/dev/null || echo "?")
+
+  echo "Commits: $COMMIT_COUNT"
+  echo "Git range: ${FIRST_HASH:0:7}..${LAST_HASH:0:7}"
+  echo "First: $FIRST_DATE — $FIRST_MSG"
+  echo "Last:  $LAST_DATE — $LAST_MSG"
+  echo "Timeline: $DAYS days ($FIRST_DATE → $LAST_DATE)"
+
+  # Diff stats for the range
+  DIFFSTAT=$(git diff --shortstat "${FIRST_HASH}^..${LAST_HASH}" 2>/dev/null || true)
+  if [ -n "$DIFFSTAT" ]; then
+    echo "Changes:$DIFFSTAT"
+  fi
+else
+  echo "No commits found matching phase patterns (expected 'feat(XX-YY): ...')"
+  echo "Determine git range manually from git log"
+fi
+
+echo ""
+exit 0

package/scripts/ms-lookup/ms_lookup/backends/context7.py

@@ -25,6 +25,16 @@ class Context7Client:
                 ],
             )
 
+    @staticmethod
+    def _extract_error_body(response: httpx.Response) -> str:
+        """Extract human-readable error message from response."""
+        try:
+            data = response.json()
+            # Context7 style: {"error": "code", "message": "..."}
+            return data.get("message", data.get("error", response.text[:200]))
+        except Exception:
+            return response.text[:200]
+
     def resolve_library(self, library_name: str, query: str) -> dict:
         """Resolve library name to Context7 library ID.
 
@@ -50,21 +60,22 @@ class Context7Client:
                 response.raise_for_status()
                 data = response.json()
         except httpx.HTTPStatusError as e:
+            body = self._extract_error_body(e.response)
             if e.response.status_code == 401:
                 raise MsLookupError(
                     ErrorCode.MISSING_API_KEY,
-                    "Invalid CONTEXT7_API_KEY",
+                    f"Invalid CONTEXT7_API_KEY — {body}",
                     suggestions=["Check your API key at https://context7.com/dashboard"],
                 )
             elif e.response.status_code == 429:
                 raise MsLookupError(
                     ErrorCode.RATE_LIMITED,
-                    "Context7 API rate limit exceeded",
+                    f"Context7 API rate limited — {body}",
                     suggestions=["Wait a moment and try again", "Use --no-cache sparingly"],
                 )
             raise MsLookupError(
                 ErrorCode.API_ERROR,
-                f"Context7 API error: {e.response.status_code}",
+                f"Context7 API error ({e.response.status_code}): {body}",
             )
         except httpx.RequestError as e:
             raise MsLookupError(
@@ -122,6 +133,7 @@ class Context7Client:
                     # Plain text/markdown response - wrap in a structure
                     data = {"content": response.text, "format": "markdown"}
         except httpx.HTTPStatusError as e:
+            body = self._extract_error_body(e.response)
             if e.response.status_code == 404:
                 raise MsLookupError(
                     ErrorCode.LIBRARY_NOT_FOUND,
@@ -130,11 +142,11 @@ class Context7Client:
             elif e.response.status_code == 429:
                 raise MsLookupError(
                     ErrorCode.RATE_LIMITED,
-                    "Context7 API rate limit exceeded",
+                    f"Context7 API rate limited — {body}",
                 )
             raise MsLookupError(
                 ErrorCode.API_ERROR,
-                f"Context7 API error: {e.response.status_code}",
+                f"Context7 API error ({e.response.status_code}): {body}",
             )
         except httpx.RequestError as e:
             raise MsLookupError(

package/scripts/ms-lookup/ms_lookup/backends/perplexity.py

@@ -81,21 +81,22 @@ class PerplexityClient:
                 response.raise_for_status()
                 data = response.json()
         except httpx.HTTPStatusError as e:
+            body = self._extract_error_body(e.response)
             if e.response.status_code == 401:
                 raise MsLookupError(
                     ErrorCode.MISSING_API_KEY,
-                    "Invalid PERPLEXITY_API_KEY",
+                    f"Invalid PERPLEXITY_API_KEY — {body}",
                     suggestions=["Check your API key at https://docs.perplexity.ai/"],
                 )
             elif e.response.status_code == 429:
                 raise MsLookupError(
                     ErrorCode.RATE_LIMITED,
-                    "Perplexity API rate limit exceeded",
+                    f"Perplexity API rate limited — {body}",
                     suggestions=["Wait a moment and try again"],
                 )
             raise MsLookupError(
                 ErrorCode.API_ERROR,
-                f"Perplexity API error: {e.response.status_code}",
+                f"Perplexity API error ({e.response.status_code}): {body}",
             )
         except httpx.RequestError as e:
             raise MsLookupError(
@@ -105,6 +106,19 @@ class PerplexityClient:
 
         return data
 
+    @staticmethod
+    def _extract_error_body(response: httpx.Response) -> str:
+        """Extract human-readable error message from response."""
+        try:
+            data = response.json()
+            # OpenAI-style: {"error": {"message": "..."}}
+            if isinstance(data.get("error"), dict):
+                return data["error"].get("message", str(data["error"]))
+            # Simple: {"error": "...", "message": "..."}
+            return data.get("message", data.get("error", response.text[:200]))
+        except Exception:
+            return response.text[:200]
+
     def _strip_think_tags(self, content: str) -> str:
         """Remove <think>...</think> blocks from response."""
         # Remove think tags and their content (including multiline)

package/scripts/ms-lookup-wrapper.sh

@@ -10,7 +10,7 @@ fi
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$SCRIPT_DIR/ms-lookup"
 
-if command -v uv &> /dev/null; then
+if command -v uv > /dev/null 2>&1; then
   # Prefer uv if available (faster)
   uv sync --quiet 2>/dev/null
   uv run python -m ms_lookup "$@"