feat(spec-kit): constitution - new principles and governance clarifications

.specify/memory/constitution.md

@@ -1,14 +1,16 @@
 <!--
 Sync Impact Report:
-- Version change: none → 1.0.0
-- Modified principles: N/A (initial constitution)
-- Added sections: Core Principles (8), Technology Stack & Standards, Development Workflow & Review, Governance
-- Removed sections: N/A
+- Version change: 1.0.0 → 1.1.0 (MINOR: added new principle, governance clarifications)
+- Modified principles: VIII. Simplicity Over Cleverness (clarified ordering rationale wording); Compliance section now references new principle explicitly
+- Added sections: Principle IX (Incremental Adoption & Backward Compatibility); Quarterly Review note in Governance
+- Removed sections: None
 - Templates requiring updates:
-  ✅ .specify/templates/plan-template.md (Constitution Check section aligns)
-  ✅ .specify/templates/spec-template.md (User scenarios align with Collaboration-Centric principle)
-  ✅ .specify/templates/tasks-template.md (Testing discipline reflected in task structure)
-- Follow-up TODOs: None
+  ✅ .specify/templates/plan-template.md (Constitution Check remains generic, no change required)
+  ✅ .specify/templates/spec-template.md (Incremental adoption supported via independent user stories pattern)
+  ✅ .specify/templates/tasks-template.md (Incremental delivery language already present; aligns with new principle)
+  ⚠ .specify/templates/commands/* (Directory absent in repository; reference in prompt instructions only—TODO if future command templates are added)
+- Follow-up TODOs:
+  TODO(COMMAND_TEMPLATES): Create `.specify/templates/commands/` directory if command workflows are adopted to enable constitution alignment checks.
 -->
 
 # Radius Design Notes Constitution
@@ -74,6 +76,12 @@ Start simple and add complexity only when proven necessary through actual requir
 
 **Rationale**: Premature complexity is the enemy of maintainability. Simple, direct solutions are easier to understand, test, debug, and evolve. Complexity should be justified by concrete needs, not hypothetical future scenarios.
 
+### IX. Incremental Adoption & Backward Compatibility
+
+Features, abstractions, and workflow changes MUST support gradual opt-in rather than forcing a disruptive migration. Breaking changes MUST provide a documented migration path and a deprecation period (minimum two release cycles) before removal. New abstractions MUST start behind feature flags or clearly labeled "experimental" status until validated by real usage. Backward compatibility MUST be maintained within a major version; removal or hard behavioral shifts REQUIRE either a guarded rollout or a MAJOR version bump with explicit migration guidance. Documentation MUST call out required user actions for any change that affects existing workflows.
+
+**Rationale**: Radius integrates with diverse existing toolchains (Bicep, Terraform, Kubernetes). Enforcing big-bang changes erodes trust and slows adoption. Iterative, reversible evolution encourages early feedback, reduces risk, and preserves stability for production users.
+
 ## Technology Stack & Standards
 
 ### Supported Languages and Tools
@@ -143,6 +151,7 @@ Reviewers MUST verify:
 - **Commit Hygiene**: Conventional commit messages; Signed-off-by present; no merge commits
 - **Error Handling**: Errors are not suppressed without justification; specific error types are handled appropriately
 - **Complexity**: Any violations of simplicity principles (e.g., new abstraction layers) are justified with concrete requirements
+- **Incremental Adoption**: Changes altering existing workflows include migration guidance, optionality (flags or config), and do not silently break existing deploy paths
 
 ## Governance
 
@@ -163,12 +172,16 @@ Amendments to this constitution require:
 
 ### Compliance and Enforcement
 
-All design specifications, plans, and implementation PRs MUST demonstrate compliance with this constitution. Maintainers MAY request changes to bring work into compliance with stated principles. Complexity that violates principles (especially Multi-Cloud Neutrality, Simplicity Over Cleverness, or Incremental Adoption) MUST be justified with explicit trade-off analysis documented in the PR or design note.
+All design specifications, plans, and implementation PRs MUST demonstrate compliance with this constitution. Maintainers MAY request changes to bring work into compliance with stated principles. Complexity that violates principles (especially Multi-Cloud Neutrality, Simplicity Over Cleverness, or Incremental Adoption & Backward Compatibility) MUST be justified with explicit trade-off analysis documented in the PR or design note.
+
+### Periodic Review
+
+This constitution MUST undergo a scheduled review at least quarterly (January, April, July, October) to assess relevance of principles, identify emerging gaps (e.g., security, observability evolution), and plan any prospective MINOR or MAJOR amendments transparently.
 
 For day-to-day development guidance beyond this constitution, refer to:
 
 - [CONTRIBUTING.md](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md) for contribution workflow
 - [Developer guides](https://github.com/radius-project/radius/tree/main/docs/contributing) for detailed technical instructions
 - [Code organization guide](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-organization/README.md) for repository structure
 
-**Version**: 1.0.0 | **Ratified**: 2025-11-06 | **Last Amended**: 2025-11-06
+**Version**: 1.1.0 | **Ratified**: 2025-11-06 | **Last Amended**: 2025-11-06

.specify/scripts/bash/check-prerequisites.sh

@@ -28,21 +28,21 @@ INCLUDE_TASKS=false
 PATHS_ONLY=false
 
 for arg in "$@"; do
-    case "$arg" in
-        --json)
-            JSON_MODE=true
-            ;;
-        --require-tasks)
-            REQUIRE_TASKS=true
-            ;;
-        --include-tasks)
-            INCLUDE_TASKS=true
-            ;;
-        --paths-only)
-            PATHS_ONLY=true
-            ;;
-        --help|-h)
-            cat << 'EOF'
+  case "$arg" in
+  --json)
+    JSON_MODE=true
+    ;;
+  --require-tasks)
+    REQUIRE_TASKS=true
+    ;;
+  --include-tasks)
+    INCLUDE_TASKS=true
+    ;;
+  --paths-only)
+    PATHS_ONLY=true
+    ;;
+  --help | -h)
+    cat <<'EOF'
 Usage: check-prerequisites.sh [OPTIONS]
 
 Consolidated prerequisite checking for Spec-Driven Development workflow.
@@ -57,21 +57,21 @@ OPTIONS:
 EXAMPLES:
   # Check task prerequisites (plan.md required)
   ./check-prerequisites.sh --json
-  
+
   # Check implementation prerequisites (plan.md + tasks.md required)
   ./check-prerequisites.sh --json --require-tasks --include-tasks
-  
+
   # Get feature paths only (no validation)
   ./check-prerequisites.sh --paths-only
-  
+
 EOF
-            exit 0
-            ;;
-        *)
-            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
-            exit 1
-            ;;
-    esac
+    exit 0
+    ;;
+  *)
+    echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+    exit 1
+    ;;
+  esac
 done
 
 # Source common functions
@@ -84,39 +84,39 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
 
 # If paths-only mode, output paths and exit (support JSON + paths-only combined)
 if $PATHS_ONLY; then
-    if $JSON_MODE; then
-        # Minimal JSON paths payload (no validation performed)
-        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
-            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
-    else
-        echo "REPO_ROOT: $REPO_ROOT"
-        echo "BRANCH: $CURRENT_BRANCH"
-        echo "FEATURE_DIR: $FEATURE_DIR"
-        echo "FEATURE_SPEC: $FEATURE_SPEC"
-        echo "IMPL_PLAN: $IMPL_PLAN"
-        echo "TASKS: $TASKS"
-    fi
-    exit 0
+  if $JSON_MODE; then
+    # Minimal JSON paths payload (no validation performed)
+    printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+      "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+  else
+    echo "REPO_ROOT: $REPO_ROOT"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "FEATURE_DIR: $FEATURE_DIR"
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN"
+    echo "TASKS: $TASKS"
+  fi
+  exit 0
 fi
 
 # Validate required directories and files
 if [[ ! -d "$FEATURE_DIR" ]]; then
-    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run /speckit.specify first to create the feature structure." >&2
-    exit 1
+  echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+  echo "Run /speckit.specify first to create the feature structure." >&2
+  exit 1
 fi
 
 if [[ ! -f "$IMPL_PLAN" ]]; then
-    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.plan first to create the implementation plan." >&2
-    exit 1
+  echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+  echo "Run /speckit.plan first to create the implementation plan." >&2
+  exit 1
 fi
 
 # Check for tasks.md if required
 if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
-    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.tasks first to create the task list." >&2
-    exit 1
+  echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+  echo "Run /speckit.tasks first to create the task list." >&2
+  exit 1
 fi
 
 # Build list of available documents
@@ -128,39 +128,39 @@ docs=()
 
 # Check contracts directory (only if it exists and has files)
 if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
-    docs+=("contracts/")
+  docs+=("contracts/")
 fi
 
 [[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
 
 # Include tasks.md if requested and it exists
 if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
-    docs+=("tasks.md")
+  docs+=("tasks.md")
 fi
 
 # Output results
 if $JSON_MODE; then
-    # Build JSON array of documents
-    if [[ ${#docs[@]} -eq 0 ]]; then
-        json_docs="[]"
-    else
-        json_docs=$(printf '"%s",' "${docs[@]}")
-        json_docs="[${json_docs%,}]"
-    fi
-    
-    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+  # Build JSON array of documents
+  if [[ ${#docs[@]} -eq 0 ]]; then
+    json_docs="[]"
+  else
+    json_docs=$(printf '"%s",' "${docs[@]}")
+    json_docs="[${json_docs%,}]"
+  fi
+
+  printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
 else
-    # Text output
-    echo "FEATURE_DIR:$FEATURE_DIR"
-    echo "AVAILABLE_DOCS:"
-    
-    # Show status of each potential document
-    check_file "$RESEARCH" "research.md"
-    check_file "$DATA_MODEL" "data-model.md"
-    check_dir "$CONTRACTS_DIR" "contracts/"
-    check_file "$QUICKSTART" "quickstart.md"
-    
-    if $INCLUDE_TASKS; then
-        check_file "$TASKS" "tasks.md"
-    fi
+  # Text output
+  echo "FEATURE_DIR:$FEATURE_DIR"
+  echo "AVAILABLE_DOCS:"
+
+  # Show status of each potential document
+  check_file "$RESEARCH" "research.md"
+  check_file "$DATA_MODEL" "data-model.md"
+  check_dir "$CONTRACTS_DIR" "contracts/"
+  check_file "$QUICKSTART" "quickstart.md"
+
+  if $INCLUDE_TASKS; then
+    check_file "$TASKS" "tasks.md"
+  fi
 fi