markitect-main/Makefile

# MarkiTect - Advanced Markdown Engine
# Makefile for common development tasks

.PHONY: help setup install-dev install-home install-home-venv install-deps install-deps-force install-deps-venv install-system list-deps setup-dev test build clean update status lint format check-deps venv-status update-digest add-diary-entry test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly test-clean test-tdd test-changed test-module test-cache-clean test-efficient cli-help release-status release-validate release-prepare release-build release-publish release-dry-run chaos-validate chaos-matrix chaos-inject chaos-report cost-help

# Default target
help:
	@echo "MarkiTect Development Commands"
	@echo "=============================="
	@echo ""
	@echo "Environment Status:"
	@$(MAKE) --no-print-directory venv-status
	@echo ""
	@echo "Setup & Installation:"
	@echo "  setup       - Initial project setup (venv + install-dev)"
	@echo "  install-dev - Install package in development mode"
	@echo "  install-home - Install markitect binary to ~/bin/"
	@echo "  install-deps - Install dependencies (tries user-local first)"
	@echo "  install-deps-force - Force install with --break-system-packages"
	@echo "  install-deps-venv - Install to user virtual environment"
	@echo "  install-home-venv - Install binary using user virtual environment"
	@echo "  install-system - Install system dependencies via apt (requires sudo)"
	@echo "  list-deps   - List required dependencies for markitect"
	@echo "  setup-dev   - Install with development dependencies"
	@echo "  venv-status - Check if venv is active"
	@echo ""
	@echo "Development:"
	@echo "  test        - Run core tests (excluding capability-specific tests)"
	@echo "  test-capabilities   - Run all capability-specific tests"
	@echo "  test-capability-*   - Run specific capability tests (content, utils, finance, etc.)"
	@echo "  test-status - Show test status summary without re-running"
	@echo "  test-new    - Create new test file template"
	@echo "  test-coverage       - Analyze test coverage"
	@echo "  build       - Build the package"
	@echo "  lint        - Run code linting"
	@echo "  format      - Format code"
	@echo ""
	@echo "Release Management:"
	@echo "  release-status       - Show current release status"
	@echo "  release-validate     - Validate repository for release"
	@echo "  release-prepare VERSION=x.y.z - Prepare new release"
	@echo "  release-build        - Build release packages"
	@echo "  release-publish VERSION=x.y.z - Publish complete release"
	@echo "  release-dry-run VERSION=x.y.z - Test release preparation"
	@echo ""
	@echo "Chaos Engineering:"
	@echo "  chaos-validate       - Run architectural independence validation"
	@echo "  chaos-matrix         - Show dependency matrix"
	@echo "  chaos-inject LAYER=X TYPE=Y - Inject chaos into specific layer"
	@echo "  chaos-report         - Generate chaos engineering report"
	@echo ""
	@echo "Cost Tracking:"
	@echo "  cost-help            - Show cost tracking commands and usage"
	@echo ""
	@echo "Architectural Testing:"
	@echo "  test-arch           - Run all tests in architectural order"
	@echo "  test-foundation     - Run foundation layer tests only"
	@echo "  test-infrastructure - Run infrastructure layer tests only"
	@echo "  test-integration    - Run integration layer tests only"
	@echo "  test-domain         - Run domain layer tests only"
	@echo "  test-service        - Run service layer tests only"
	@echo "  test-application    - Run application layer tests only"
	@echo "  test-presentation   - Run presentation layer tests only"
	@echo "  test-quick          - Run foundation + infrastructure only (fast)"
	@echo "  test-layers         - List all architectural layers"
	@echo ""
	@echo "Randomized Testing:"
	@echo "  test-random         - Run tests in random order (dependency detection)"
	@echo "  test-random-seed SEED=X - Run with specific seed for reproducibility"
	@echo "  test-random-repeat NUM=X - Run multiple random iterations"
	@echo "  test-install-randomly    - Install pytest-randomly plugin"
	@echo ""
	@echo "Test Efficiency (Issue #57):"
	@echo "  test-clean      - Clean test run (exclude workspaces, fresh cache)"
	@echo "  test-tdd        - Quick TDD tests for fast feedback (<30s)"
	@echo "  test-changed    - Run tests for changed files only"
	@echo "  test-module MODULE=name - Run tests for specific module"
	@echo "  test-cache-clean - Clean pytest cache"
	@echo "  test-efficient  - Enhanced test suite (exclude workspaces)"
	@echo ""
	@echo "Maintenance:"
	@echo "  update      - Update from upstream (git + submodules)"
	@echo "  status      - Show git status for repo and submodules"
	@echo "  clean       - Clean build artifacts"
	@echo "  check-deps  - Check dependency status"
	@echo "  validate-js - Validate JavaScript syntax in templates"
	@echo ""
	@echo "Documentation:"
	@echo "  update-digest   - Update ProjectStatusDigest.md (requires Claude Code)"
	@echo "  add-diary-entry - Add new entry to ProjectDiary.md (requires Claude Code)"
	@echo ""
	@echo "Capability Management:"
	@echo "  capability-report   - Generate capability discovery report"
	@echo "  capability-search TERM=xyz - Search for functionality across capabilities"
	@echo "  capability-validate FILE=path - Validate proper capability usage in file"
	@echo ""
	@echo ""
	@echo "Requirements Engineering:"
	@echo "  validate-requirements - Analyze foundations before development"
	@echo "  check-interface-compatibility INTERFACE=Name - Check interface compatibility"
	@echo "  generate-dev-checklist FEATURE='Name' - Generate development checklist"
	@echo "  validate-mocks        - Validate mock object compatibility"
	@echo "  pre-commit-validate   - Complete pre-commit validation"
	@echo "  view-requirements-examples - Show usage examples"
	@echo ""
	@echo "MarkiTect CLI Usage:"
	@echo "  cli-help              - Show detailed CLI usage targets and examples"
	@echo "  cli-ingest [FILE=doc.md] - Process and store markdown files"
	@echo "  cli-workflow-basic    - Run complete basic workflow demo"
	@echo "  cli-workflow-schema FILE=doc.md - Run schema generation workflow"

# Python and virtual environment setup
PYTHON := python3
VENV := .venv
VENV_PYTHON := $(VENV)/bin/python
VENV_PIP := $(VENV)/bin/pip

# Check virtual environment status (read-only)
venv-status:
	@if [ -f $(VENV)/bin/activate ] && [ -f $(VENV)/bin/python ]; then \
		if [ -n "$$VIRTUAL_ENV" ] && [ "$$VIRTUAL_ENV" = "$$(realpath $(VENV))" ]; then \
			echo "  ✅ Virtual environment: Active in current shell"; \
		elif [ -n "$$VIRTUAL_ENV" ]; then \
			echo "  ⚠️  Virtual environment: Different venv active ($$VIRTUAL_ENV)"; \
			echo "     Run 'deactivate' then 'source $(VENV)/bin/activate'"; \
		else \
			echo "  📁 Virtual environment: Ready but not activated"; \
			echo "     Run 'source $(VENV)/bin/activate' to activate"; \
		fi; \
	else \
		echo "  ❌ Virtual environment: Not found"; \
		echo "     Run 'make setup' to create and configure"; \
	fi

# Setup virtual environment and install package
setup: $(VENV)/bin/activate install-dev
	@echo "✅ Project setup complete!"

$(VENV)/bin/activate:
	@echo "🔧 Creating virtual environment..."
	$(PYTHON) -m venv $(VENV)
	$(VENV_PIP) install --upgrade pip setuptools wheel

# Install package in development mode
install-dev: $(VENV)/bin/activate
	@echo "📦 Installing MarkiTect in development mode..."
	$(VENV_PIP) install -e .

# Install markitect binary to user's home bin directory
install-home: $(VENV)/bin/activate
	@echo "🏠 Installing MarkiTect to ~/bin/..."
	@mkdir -p $$HOME/bin
	@PYTHON_PATH=$$(which python3); \
	echo "#!/usr/bin/env python3" > $$HOME/bin/markitect; \
	echo "import sys" >> $$HOME/bin/markitect; \
	echo "import os" >> $$HOME/bin/markitect; \
	echo "# Add project directory to Python path" >> $$HOME/bin/markitect; \
	echo "sys.path.insert(0, '$(shell pwd)')" >> $$HOME/bin/markitect; \
	echo "try:" >> $$HOME/bin/markitect; \
	echo "    from markitect.cli import main" >> $$HOME/bin/markitect; \
	echo "except ImportError as e:" >> $$HOME/bin/markitect; \
	echo "    print('Error: MarkiTect dependencies not found.')" >> $$HOME/bin/markitect; \
	echo "    print('Please run: make install-deps')" >> $$HOME/bin/markitect; \
	echo "    print(f'ImportError: {e}')" >> $$HOME/bin/markitect; \
	echo "    sys.exit(1)" >> $$HOME/bin/markitect; \
	echo "if __name__ == '__main__':" >> $$HOME/bin/markitect; \
	echo "    main()" >> $$HOME/bin/markitect
	@chmod +x $$HOME/bin/markitect
	@echo "✅ MarkiTect installed to $$HOME/bin/markitect"
	@echo "💡 Make sure $$HOME/bin is in your PATH to use 'markitect' command globally"
	@echo "   Add this to your shell config: export PATH=\"\$$HOME/bin:\$$PATH\""
	@echo "⚠️  Dependencies needed: Run 'make install-deps' or 'make list-deps' for details"

# Install markitect binary using user virtual environment
install-home-venv: $(VENV)/bin/activate
	@echo "🏠 Installing MarkiTect to ~/bin/ (using user virtual environment)..."
	@if [ ! -d "$$HOME/.local/markitect-venv" ]; then \
		echo "❌ User virtual environment not found"; \
		echo "   Run 'make install-deps-venv' first"; \
		exit 1; \
	fi
	@mkdir -p $$HOME/bin
	@echo "#!$$HOME/.local/markitect-venv/bin/python" > $$HOME/bin/markitect
	@echo "import sys" >> $$HOME/bin/markitect
	@echo "import os" >> $$HOME/bin/markitect
	@echo "# Add project directory to Python path" >> $$HOME/bin/markitect
	@echo "sys.path.insert(0, '$(shell pwd)')" >> $$HOME/bin/markitect
	@echo "try:" >> $$HOME/bin/markitect
	@echo "    from markitect.cli import main" >> $$HOME/bin/markitect
	@echo "except ImportError as e:" >> $$HOME/bin/markitect
	@echo "    print('Error: MarkiTect dependencies not found.')" >> $$HOME/bin/markitect
	@echo "    print('Please run: make install-deps-venv')" >> $$HOME/bin/markitect
	@echo "    print(f'ImportError: {e}')" >> $$HOME/bin/markitect
	@echo "    sys.exit(1)" >> $$HOME/bin/markitect
	@echo "if __name__ == '__main__':" >> $$HOME/bin/markitect
	@echo "    main()" >> $$HOME/bin/markitect
	@chmod +x $$HOME/bin/markitect
	@echo "✅ MarkiTect installed to $$HOME/bin/markitect (using user venv)"
	@echo "💡 Make sure $$HOME/bin is in your PATH to use 'markitect' command globally"
	@echo "   Add this to your shell config: export PATH=\"\$$HOME/bin:\$$PATH\""
	@echo "✅ Dependencies are isolated in: $$HOME/.local/markitect-venv"

# List required dependencies for markitect
list-deps:
	@echo "📋 MarkiTect Dependencies"
	@echo "========================"
	@echo ""
	@echo "Required dependencies:"
	@echo "  markdown-it-py    - Markdown parsing"
	@echo "  PyYAML           - YAML front matter parsing"
	@echo "  click>=8.0.0     - CLI framework"
	@echo "  tabulate>=0.9.0  - Table formatting"
	@echo "  jsonpath-ng>=1.5.0 - JSON path queries"
	@echo "  aiohttp>=3.8.0   - Async HTTP client"
	@echo "  toml             - TOML configuration parsing"
	@echo ""
	@echo "🔧 Installation options:"
	@echo "  make install-deps                    - Install user-local (recommended)"
	@echo "  make install-system                 - Install via apt + pip --user (requires sudo)"
	@echo "  pip3 install --user [packages]      - Manual user-local installation"
	@echo "  pip install -e .                    - Install from project directory (dev mode)"

# Install user-local dependencies for markitect (no sudo needed)
install-deps:
	@echo "📦 Installing MarkiTect dependencies (user-local)..."
	@echo "🐍 Target Python: $$(which python3) (version: $$(python3 --version))"
	@echo "📍 pip3 location: $$(which pip3)"
	@echo ""
	@echo "🔧 Attempting user-local installation..."
	@if pip3 install --user markdown-it-py PyYAML "click>=8.0.0" "tabulate>=0.9.0" "jsonpath-ng>=1.5.0" "aiohttp>=3.8.0" toml 2>/dev/null; then \
		echo "✅ Dependencies installed successfully!"; \
	else \
		echo "❌ User-local installation failed (externally-managed-environment)"; \
		echo ""; \
		echo "🔧 Alternative solutions:"; \
		echo "  1. Use system packages: make install-system"; \
		echo "  2. Override restriction: make install-deps-force"; \
		echo "  3. Create user venv: make install-deps-venv"; \
		echo "  4. Use development setup: make setup"; \
		echo ""; \
		echo "💡 Recommended: Try 'make install-system' first"; \
		exit 1; \
	fi
	@echo "🧪 Testing import..."
	@python3 -c "import sys; sys.path.insert(0, '$(shell pwd)'); import markitect.cli; print('✅ MarkiTect imports successfully')" 2>/dev/null || echo "⚠️  Import test failed - check if project path is correct"
	@echo "💡 You can now use 'markitect' command if it's in your PATH"

# Force install user-local dependencies (overrides externally-managed restriction)
install-deps-force:
	@echo "📦 Force installing MarkiTect dependencies (overriding restrictions)..."
	@echo "⚠️  This uses --break-system-packages flag"
	@echo "   Only use if you understand the implications"
	@echo ""
	@read -p "Continue with forced installation? [y/N]: " confirm; \
	if [ "$$confirm" = "y" ] || [ "$$confirm" = "Y" ]; then \
		echo "📦 Installing dependencies with --break-system-packages..."; \
		pip3 install --user --break-system-packages markdown-it-py PyYAML "click>=8.0.0" "tabulate>=0.9.0" "jsonpath-ng>=1.5.0" "aiohttp>=3.8.0" toml; \
		echo "✅ Dependencies installed successfully!"; \
		echo "🧪 Testing import..."; \
		python3 -c "import sys; sys.path.insert(0, '$(shell pwd)'); import markitect.cli; print('✅ MarkiTect imports successfully')" 2>/dev/null || echo "⚠️  Import test failed"; \
		echo "💡 You can now use 'markitect' command if it's in your PATH"; \
	else \
		echo "❌ Installation cancelled"; \
		echo "💡 Alternative: Use 'make install-system' or 'make install-deps-venv'"; \
	fi

# Install dependencies using a user virtual environment
install-deps-venv:
	@echo "📦 Installing MarkiTect dependencies using user virtual environment..."
	@echo "💡 Creating virtual environment in ~/.local/markitect-venv"
	@mkdir -p $$HOME/.local
	@python3 -m venv $$HOME/.local/markitect-venv
	@$$HOME/.local/markitect-venv/bin/pip install --upgrade pip
	@echo "📦 Installing main dependencies..."
	@$$HOME/.local/markitect-venv/bin/pip install markdown-it-py PyYAML "click>=8.0.0" "tabulate>=0.9.0" "jsonpath-ng>=1.5.0" "aiohttp>=3.8.0" toml
	@echo "📦 Installing local markitect-content package..."
	@if [ -d "capabilities/markitect-content" ]; then \
		$$HOME/.local/markitect-venv/bin/pip install -e capabilities/markitect-content; \
		echo "✅ markitect-content installed"; \
	else \
		echo "⚠️  markitect-content directory not found, skipping"; \
	fi
	@echo "✅ Dependencies installed successfully!"
	@echo "🧪 Testing import..."
	@$$HOME/.local/markitect-venv/bin/python -c "import sys; sys.path.insert(0, '$(shell pwd)'); import markitect.cli; print('✅ MarkiTect imports successfully')" 2>/dev/null || echo "⚠️  Import test failed"
	@echo "💡 Virtual environment created at: $$HOME/.local/markitect-venv"
	@echo "💡 To use this, run 'make install-home-venv' instead of 'make install-home'"

# Install system dependencies via apt (requires sudo)
install-system:
	@echo "📦 Installing MarkiTect dependencies via apt..."
	@echo "⚠️  This requires sudo and installs system packages"
	@echo ""
	@echo "Available system packages:"
	@echo "  python3-yaml       - PyYAML"
	@echo "  python3-click      - Click CLI framework"
	@echo "  python3-tabulate   - Tabulate"
	@echo "  python3-aiohttp    - Async HTTP client"
	@echo ""
	@echo "⚠️  Note: Some packages (markdown-it-py, jsonpath-ng) may not be available via apt"
	@echo "   You may need to combine this with 'make install-deps' for missing packages"
	@echo ""
	@read -p "Continue with apt installation? [y/N]: " confirm; \
	if [ "$$confirm" = "y" ] || [ "$$confirm" = "Y" ]; then \
		echo "📦 Installing available system packages..."; \
		sudo apt update; \
		sudo apt install -y python3-yaml python3-click python3-tabulate python3-aiohttp python3-toml; \
		echo "📦 Installing remaining packages with pip --user..."; \
		pip3 install --user markdown-it-py "jsonpath-ng>=1.5.0"; \
		echo "✅ Dependencies installed successfully!"; \
		echo "🧪 Testing import..."; \
		python3 -c "import sys; sys.path.insert(0, '$(shell pwd)'); import markitect.cli; print('✅ MarkiTect imports successfully')" 2>/dev/null || echo "⚠️  Import test failed"; \
		echo "💡 You can now use 'markitect' command if it's in your PATH"; \
	else \
		echo "❌ Installation cancelled"; \
		echo "💡 Alternative: Use 'make install-deps' for user-local installation"; \
	fi

# Install with development dependencies
setup-dev: install-dev
	@echo "🛠️  Installing development dependencies..."
	$(VENV_PIP) install pytest pytest-cov black flake8 mypy

# Run tests
test: $(VENV)/bin/activate
	@echo "🧪 Running core tests (excluding capability-specific tests)..."
	@if [ -f $(VENV)/bin/pytest ]; then \
		PYTHONPATH=. $(VENV)/bin/pytest tests/ -v \
			--ignore=capabilities/markitect-content/tests/ \
			--ignore=capabilities/markitect-utils/tests/ \
			--ignore=markitect/finance/tests/ \
			--ignore=markitect/query_paradigms/tests/ \
			--ignore=markitect/graphql/tests/ \
			--ignore=markitect/plugins/tests/; \
	else \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v \
			--ignore=capabilities/markitect-content/tests/ \
			--ignore=capabilities/markitect-utils/tests/ \
			--ignore=markitect/finance/tests/ \
			--ignore=markitect/query_paradigms/tests/ \
			--ignore=markitect/graphql/tests/ \
			--ignore=markitect/plugins/tests/ 2>/dev/null || \
		PYTHONPATH=. $(VENV_PYTHON) -m unittest discover tests/ -v; \
	fi

# Capability-Specific Test Targets
test-capabilities: test-capability-content test-capability-utils test-capability-finance test-capability-query test-capability-graphql test-capability-plugins
	@echo "✅ All capability tests completed"

test-capability-content: $(VENV)/bin/activate
	@echo "🧪 Running markitect-content capability tests..."
	@cd capabilities/markitect-content && python -m pytest tests/ -v

test-capability-utils: $(VENV)/bin/activate
	@echo "🧪 Running markitect-utils capability tests..."
	@cd capabilities/markitect-utils && python -m pytest tests/ -v

test-capability-finance: $(VENV)/bin/activate
	@echo "🧪 Running finance capability tests..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/finance/tests/ -v

test-capability-query: $(VENV)/bin/activate
	@echo "🧪 Running query paradigms capability tests..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/query_paradigms/tests/ -v

test-capability-graphql: $(VENV)/bin/activate
	@echo "🧪 Running GraphQL capability tests..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/graphql/tests/ -v

test-capability-plugins: $(VENV)/bin/activate
	@echo "🧪 Running plugins capability tests..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/plugins/tests/ -v

# TDD8 Workflow Optimized Test Targets (Issue #57)

# Fast test execution for TDD red phase
test-red: $(VENV)/bin/activate
	@echo "🔴 TDD Red Phase - Fast test execution..."
	PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -x --maxfail=1 --tb=short -q \
		--ignore=capabilities/markitect-content/tests/ \
		--ignore=capabilities/markitect-utils/tests/ \
		--ignore=markitect/finance/tests/ \
		--ignore=markitect/query_paradigms/tests/ \
		--ignore=markitect/graphql/tests/ \
		--ignore=markitect/plugins/tests/

# Comprehensive test execution for TDD green phase
test-green: $(VENV)/bin/activate
	@echo "🟢 TDD Green Phase - Comprehensive validation..."
	PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --tb=short \
		--ignore=capabilities/markitect-content/tests/ \
		--ignore=capabilities/markitect-utils/tests/ \
		--ignore=markitect/finance/tests/ \
		--ignore=markitect/query_paradigms/tests/ \
		--ignore=markitect/graphql/tests/ \
		--ignore=markitect/plugins/tests/

# Smart test selection - changed files only
test-smart: $(VENV)/bin/activate
	@echo "🧠 Smart test selection - changed files only..."
	@changed_tests=$$(git diff --name-only HEAD~1 | grep test_ | tr '\n' ' '); \
	if [ -n "$$changed_tests" ]; then \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest $$changed_tests -v; \
	else \
		echo "No test files changed, running fast subset"; \
		$(MAKE) test-fast; \
	fi

# Ultra-fast test execution
test-ultra-fast: $(VENV)/bin/activate
	@echo "⚡ Ultra-fast test execution..."
	PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -m "not slow" --maxfail=1 -x -q \
		--ignore=capabilities/markitect-content/tests/ \
		--ignore=capabilities/markitect-utils/tests/ \
		--ignore=markitect/finance/tests/ \
		--ignore=markitect/query_paradigms/tests/ \
		--ignore=markitect/graphql/tests/ \
		--ignore=markitect/plugins/tests/

# Test with performance monitoring
test-perf: $(VENV)/bin/activate
	@echo "📊 Test execution with performance monitoring..."
	PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --durations=10 --tb=short \
		--ignore=capabilities/markitect-content/tests/ \
		--ignore=capabilities/markitect-utils/tests/ \
		--ignore=markitect/finance/tests/ \
		--ignore=markitect/query_paradigms/tests/ \
		--ignore=markitect/graphql/tests/ \
		--ignore=markitect/plugins/tests/

# Test health check
test-health: $(VENV)/bin/activate
	@echo "🏥 Test infrastructure health check..."
	@PYTHONPATH=. $(VENV_PYTHON) tools/testing_efficiency_optimizer.py diagnose

# Clean all test caches (Enhanced for Issue #57)
test-cache-clean-enhanced: $(VENV)/bin/activate
	@echo "🧹 Enhanced cache cleaning..."
	find . -name '.pytest_cache' -type d -exec rm -rf {} + 2>/dev/null || true
	find . -name '__pycache__' -type d -exec rm -rf {} + 2>/dev/null || true
	find . -name '*.pyc' -delete 2>/dev/null || true

# Build the package
build: $(VENV)/bin/activate
	@echo "🏗️  Building package..."
	$(VENV_PYTHON) -m build 2>/dev/null || \
	$(VENV_PIP) install build && $(VENV_PYTHON) -m build

# Release management
release-status:
	@echo "🔍 Checking release status..."
	$(VENV_PYTHON) release.py status

release-validate:
	@echo "✅ Validating release readiness..."
	$(VENV_PYTHON) release.py validate

release-prepare:
	@echo "🚀 Preparing release..."
	@if [ -z "$(VERSION)" ]; then \
		echo "❌ Usage: make release-prepare VERSION=1.0.0"; \
		exit 1; \
	fi
	$(VENV_PYTHON) release.py prepare --version $(VERSION)

release-build:
	@echo "📦 Building release packages..."
	$(VENV_PYTHON) release.py build $(if $(VERSION),--version $(VERSION))

release-publish:
	@echo "📢 Publishing release..."
	@if [ -z "$(VERSION)" ]; then \
		echo "❌ Usage: make release-publish VERSION=1.0.0"; \
		exit 1; \
	fi
	$(VENV_PYTHON) release.py publish --version $(VERSION)

release-dry-run:
	@echo "🧪 Dry run release preparation..."
	@if [ -z "$(VERSION)" ]; then \
		echo "❌ Usage: make release-dry-run VERSION=1.0.0"; \
		exit 1; \
	fi
	$(VENV_PYTHON) release.py prepare --version $(VERSION) --dry-run

# Chaos Engineering targets
chaos-validate:
	@echo "🔥 Running architectural independence validation..."
	$(VENV_PYTHON) tools/chaos_test_runner.py validate-independence

chaos-matrix:
	@echo "🏗️  Showing architectural dependency matrix..."
	$(VENV_PYTHON) tools/chaos_test_runner.py dependency-matrix

chaos-inject:
	@echo "💥 Injecting chaos into layer..."
	@if [ -z "$(LAYER)" ]; then \
		echo "❌ Usage: make chaos-inject LAYER=L1_Presentation TYPE=import_failure"; \
		exit 1; \
	fi
	$(VENV_PYTHON) tools/chaos_test_runner.py inject-layer-failure --layer $(LAYER) $(if $(TYPE),--injection-type $(TYPE))

chaos-report:
	@echo "📄 Generating chaos engineering report..."
	$(VENV_PYTHON) tools/chaos_test_runner.py chaos-report

# Code linting
lint: $(VENV)/bin/activate
	@echo "🔍 Running linting..."
	@if [ -f $(VENV)/bin/flake8 ]; then \
		$(VENV)/bin/flake8 markitect/ tests/; \
	else \
		echo "⚠️  flake8 not installed. Run 'make setup-dev' first."; \
	fi

# Code formatting
format: $(VENV)/bin/activate
	@echo "✨ Formatting code..."
	@if [ -f $(VENV)/bin/black ]; then \
		$(VENV)/bin/black markitect/ tests/; \
	else \
		echo "⚠️  black not installed. Run 'make setup-dev' first."; \
	fi

# Update from upstream
update:
	@echo "🔄 Updating from upstream..."
	@git status --porcelain | grep -q . && echo "⚠️  Working directory not clean. Commit or stash changes first." && exit 1 || true
	git pull origin main
	git submodule update --remote
	@if git status --porcelain | grep -q "wiki"; then \
		echo "📝 Committing wiki submodule update..."; \
		git add wiki; \
		git commit -m "Update wiki submodule to latest"; \
	fi
	@echo "✅ Update complete!"

# Show git status
status:
	@echo "📊 Repository Status"
	@echo "==================="
	@echo ""
	@echo "Main Repository:"
	git status --short
	@echo ""
	@echo "Wiki Submodule:"
	@cd wiki && git status --short
	@echo ""
	@echo "Recent Commits:"
	git log --oneline -5

# Clean build artifacts
clean:
	@echo "🧹 Cleaning build artifacts..."
	rm -rf build/
	rm -rf dist/
	rm -rf *.egg-info/
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
	find . -name "*.pyc" -delete 2>/dev/null || true
	@echo "✅ Clean complete!"

# Check dependency status
check-deps: $(VENV)/bin/activate
	@echo "📋 Dependency Status"
	@echo "==================="
	@echo ""
	@echo "Python version:"
	$(VENV_PYTHON) --version
	@echo ""
	@echo "Installed packages:"
	$(VENV_PIP) list
	@echo ""
	@echo "Project dependencies:"
	$(VENV_PIP) check

# Update project status digest (requires Claude Code)
update-digest:
	@echo "🔍 Checking for Claude Code availability..."
	@if ! command -v claude >/dev/null 2>&1; then \
		echo "❌ Claude Code not found in PATH"; \
		echo "   This target requires Claude Code CLI to be installed"; \
		echo "   Visit: https://claude.ai/code for installation instructions"; \
		exit 1; \
	fi
	@echo "✅ Claude Code found"
	@echo "📝 Updating ProjectStatusDigest.md..."
	@echo "   Please ask Claude Code to update the project digest based on current state"
	@echo "   Command: 'Please update ProjectStatusDigest.md with the current project state'"
	@echo ""
	@echo "💡 Tip: You can also manually edit ProjectStatusDigest.md if needed"

# Add new entry to project diary (requires Claude Code)
add-diary-entry:
	@echo "🔍 Checking for Claude Code availability..."
	@if ! command -v claude >/dev/null 2>&1; then \
		echo "❌ Claude Code not found in PATH"; \
		echo "   This target requires Claude Code CLI to be installed"; \
		echo "   Visit: https://claude.ai/code for installation instructions"; \
		exit 1; \
	fi
	@echo "✅ Claude Code found"
	@if [ ! -f ProjectDiary.md ]; then \
		echo "❌ ProjectDiary.md not found"; \
		echo "   Create the diary file first or run this from the project root"; \
		exit 1; \
	fi
	@echo "📖 Adding new entry to ProjectDiary.md..."
	@echo "   Please ask Claude Code to add a new diary entry for recent work"
	@echo "   Command: 'Please add a new entry to ProjectDiary.md summarizing recent progress'"
	@echo ""
	@echo "📋 Entry should include:"
	@echo "   - Date ($(shell date +%Y-%m-%d))"
	@echo "   - One-line progress characterization"
	@echo "   - Contributors since last entry"
	@echo "   - Time estimate and AI token usage"
	@echo "   - One paragraph work summary"
	@echo ""
	@echo "💡 Tip: New entries are added to the top for reverse chronological order"

# Capability discovery and management targets
capability-report: $(VENV)/bin/activate
	@echo "📋 Generating capability discovery report..."
	@$(VENV_PYTHON) tools/capability_discovery.py report

capability-search: $(VENV)/bin/activate
	@if [ -z "$(TERM)" ]; then \
		echo "❌ Please specify search term: make capability-search TERM=issue_management"; \
		exit 1; \
	fi
	@echo "🔍 Searching for '$(TERM)' across capabilities..."
	@$(VENV_PYTHON) tools/capability_discovery.py search "$(TERM)"

capability-validate: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "❌ Please specify file path: make capability-validate FILE=path/to/file.py"; \
		exit 1; \
	fi
	@echo "✅ Validating capability usage in $(FILE)..."
	@$(VENV_PYTHON) tools/capability_discovery.py validate "$(FILE)"

# Git repository and API configuration
GITEA_URL := http://92.205.130.254:32166


# Show test status summary without re-running tests
test-status: $(VENV)/bin/activate
	@echo "📊 MarkiTect Test Status Summary"
	@echo "==============================="
	@echo ""
	@echo "📄 Test Files:"
	@find tests/ -name "test_*.py" -exec basename {} \; | sort | sed 's/^/   📝 /'
	@echo ""
	@echo "📊 Quick Stats:"
	@echo -n "   Total test files: "
	@find tests/ -name "test_*.py" | wc -l
	@echo ""
	@if [ -f ".pytest_cache/CACHEDIR.TAG" ]; then \
		echo "💾 Last Test Results (cached):"; \
		if [ -f ".pytest_cache/v/cache/lastfailed" ]; then \
			echo "   ❌ Recent failures detected"; \
			echo -n "   Failed tests: "; \
			cat .pytest_cache/v/cache/lastfailed | jq -r 'keys[]' 2>/dev/null | wc -l || echo "Unknown"; \
		else \
			echo "   ✅ No recent failures in cache"; \
		fi; \
		echo "   📁 Cache: .pytest_cache/ ($$(du -sh .pytest_cache/ 2>/dev/null | cut -f1 || echo 'Unknown size'))"; \
		if [ -f ".pytest_cache/README.md" ]; then \
			echo "   📅 Last run: $$(stat -c %y .pytest_cache/README.md 2>/dev/null | cut -d. -f1 || echo 'Unknown')"; \
		fi; \
	else \
		echo "❓ No test cache found - run 'make test' to generate results"; \
	fi
	@echo ""
	@echo "🔍 For detailed status:"
	@echo "   make test           # Run all tests with full output"
	@echo "   make test 2>&1 | grep -E 'PASSED|FAILED'  # Show only results"
	@echo ""
	@if [ -f "test_status_report.md" ]; then \
		echo "📋 Full Status Report: test_status_report.md"; \
		echo "   Last updated: $$(stat -c %y test_status_report.md 2>/dev/null || echo 'Unknown')"; \
	else \
		echo "💡 Generate detailed report with test run data"; \
	fi

# Create new test file template
test-new: $(VENV)/bin/activate
	@echo "🧪 Creating new test file"
	@echo "========================"
	@echo ""
	@read -p "Test name (e.g., feature_name): " test_name; \
	if [ -z "$$test_name" ]; then \
		echo "❌ Test name cannot be empty"; \
		exit 1; \
	fi; \
	test_file="tests/test_$$test_name.py"; \
	if [ -f "$$test_file" ]; then \
		echo "❌ Test file already exists: $$test_file"; \
		exit 1; \
	fi; \
	echo "📝 Creating: $$test_file"; \
	echo '"""' > "$$test_file"; \
	echo "Test for $$test_name functionality." >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "This test module validates [describe what you're testing]." >> "$$test_file"; \
	echo '"""' >> "$$test_file"; \
	echo "import pytest" >> "$$test_file"; \
	echo "from markitect import [import what you need]" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	class_name=$$(echo $$test_name | sed 's/_/ /g' | sed 's/\b\w/\U&/g' | sed 's/ //g'); \
	echo "class Test$$class_name:" >> "$$test_file"; \
	echo '    """Test suite for '$$test_name' functionality."""' >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def setup_method(self):" >> "$$test_file"; \
	echo '        """Set up test environment."""' >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def teardown_method(self):" >> "$$test_file"; \
	echo '        """Clean up after tests."""' >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_basic_functionality(self):" >> "$$test_file"; \
	echo '        """Test basic '$$test_name' functionality."""' >> "$$test_file"; \
	echo "        # Arrange" >> "$$test_file"; \
	echo "        # TODO: Set up test data" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "        # Act" >> "$$test_file"; \
	echo "        # TODO: Execute the functionality" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "        # Assert" >> "$$test_file"; \
	echo "        # TODO: Verify expected results" >> "$$test_file"; \
	echo "        assert True  # Replace with actual assertions" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_edge_cases(self):" >> "$$test_file"; \
	echo '        """Test edge cases for '$$test_name'."""' >> "$$test_file"; \
	echo "        # TODO: Test boundary conditions, empty inputs, etc." >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_error_handling(self):" >> "$$test_file"; \
	echo '        """Test error handling for '$$test_name'."""' >> "$$test_file"; \
	echo "        # TODO: Test invalid inputs, exception cases" >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "if __name__ == '__main__':" >> "$$test_file"; \
	echo "    pytest.main([__file__, '-v'])" >> "$$test_file"; \
	echo "✅ Test file created: $$test_file"; \
	echo ""; \
	echo "🎯 Next steps:"; \
	echo "   1. Edit the test file to add your specific tests"; \
	echo "   2. Run: make test to check if it works"; \
	echo "   3. Implement the actual functionality"; \
	echo "   4. Run tests again to verify (TDD cycle)"

# Analyze test coverage
test-coverage: $(VENV)/bin/activate
	@echo "📊 Analyzing test coverage..."
	@pytest --cov=markitect --cov-report=html --cov-report=term-missing tests/
	@echo "✅ Coverage report generated in htmlcov/"

# ============================================================================
# Architectural Testing Targets
# ============================================================================

# Run all tests in architectural order (reverse dependency)
test-arch: $(VENV)/bin/activate
	@echo "🏗️  Running architectural test suite in reverse dependency order..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py

# Run foundation layer tests only (Layer 7 - fastest feedback)
test-foundation: $(VENV)/bin/activate
	@echo "🏢 Running Foundation Layer tests (Layer 7)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer foundation

# Run infrastructure layer tests only (Layer 5 - technical capabilities)
test-infrastructure: $(VENV)/bin/activate
	@echo "🔧 Running Infrastructure Layer tests (Layer 5)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer infrastructure

# Run integration layer tests only (Layer 6 - external systems)
test-integration: $(VENV)/bin/activate
	@echo "🌐 Running Integration Layer tests (Layer 6)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer integration

# Run domain layer tests only (Layer 3 - business logic)
test-domain: $(VENV)/bin/activate
	@echo "🏛️  Running Domain Layer tests (Layer 3)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer domain

# Run service layer tests only (Layer 4 - application services)
test-service: $(VENV)/bin/activate
	@echo "⚙️  Running Service Layer tests (Layer 4)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer service

# Run application layer tests only (Layer 2 - use cases & workflows)
test-application: $(VENV)/bin/activate
	@echo "🚀 Running Application Layer tests (Layer 2)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer application

# Run presentation layer tests only (Layer 1 - user interface)
test-presentation: $(VENV)/bin/activate
	@echo "🎯 Running Presentation Layer tests (Layer 1)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --layer presentation

# Run foundation + infrastructure only (quick feedback)
test-quick: $(VENV)/bin/activate
	@echo "⚡ Running quick test suite (Foundation + Infrastructure)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --quick

# List all architectural layers and their test files
test-layers: $(VENV)/bin/activate
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --list-layers

# Advanced architectural testing options
test-arch-verbose: $(VENV)/bin/activate
	@echo "🏗️  Running architectural test suite with verbose output..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --verbose

test-arch-continue: $(VENV)/bin/activate
	@echo "🏗️  Running architectural test suite (continue on failures)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_architectural_tests.py --continue-on-failure

# Update .PHONY for advanced targets
.PHONY: test-arch-verbose test-arch-continue

# ============================================================================
# Randomized Testing Targets
# ============================================================================

# Run tests in random order to detect hidden dependencies
test-random: $(VENV)/bin/activate
	@echo "🎲 Running tests in randomized order..."
	@PYTHONPATH=src $(VENV_PYTHON) run_randomized_tests.py

# Run tests with specific seed for reproducibility
test-random-seed: $(VENV)/bin/activate
	@if [ -z "$(SEED)" ]; then \
		echo "❌ Please specify seed: make test-random-seed SEED=12345"; \
		exit 1; \
	fi
	@echo "🎲 Running tests with seed $(SEED)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_randomized_tests.py --seed $(SEED)

# Run multiple random iterations to find flaky tests
test-random-repeat: $(VENV)/bin/activate
	@if [ -z "$(NUM)" ]; then \
		echo "❌ Please specify number of iterations: make test-random-repeat NUM=5"; \
		exit 1; \
	fi
	@echo "🔄 Running $(NUM) randomized test iterations..."
	@PYTHONPATH=src $(VENV_PYTHON) run_randomized_tests.py --repeat $(NUM)

# Install pytest-randomly plugin for enhanced randomization
test-install-randomly: $(VENV)/bin/activate
	@echo "📦 Installing pytest-randomly plugin..."
	@$(VENV_PIP) install pytest-randomly
	@echo "✅ pytest-randomly installed - now supports within-file randomization"
	@echo "💡 Use --shuffle-within-file flag for enhanced randomization"

# Advanced randomized testing options
test-random-verbose: $(VENV)/bin/activate
	@echo "🎲 Running randomized tests with verbose output..."
	@PYTHONPATH=src $(VENV_PYTHON) run_randomized_tests.py --verbose

test-random-enhanced: $(VENV)/bin/activate
	@echo "🎲 Running enhanced randomized tests (within-file shuffling)..."
	@PYTHONPATH=src $(VENV_PYTHON) run_randomized_tests.py --shuffle-within-file --verbose

# Update .PHONY for randomized targets
.PHONY: test-random-verbose test-random-enhanced

# ============================================================================
# Test Efficiency Targets (Issue #57)
# ============================================================================

# Clean test runner that excludes workspace directories and cleans cache
test-clean: $(VENV)/bin/activate
	@echo "🧹 Running clean test suite (excluding workspaces, fresh cache)..."
	@echo "   Cleaning pytest cache..."
	@rm -rf .pytest_cache/
	@echo "   Running tests with workspace exclusion..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v \
		--ignore=.markitect_workspace/ \
		--cache-clear \
		--tb=short

# Quick test suite for TDD workflows (fast feedback)
test-tdd: $(VENV)/bin/activate
	@echo "⚡ Running TDD test suite for fast feedback..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ \
		--ignore=.markitect_workspace/ \
		-x \
		--tb=line \
		-q \
		-m "not slow and not integration and not e2e"

# Run tests for changed files only (intelligent selection)
test-changed: $(VENV)/bin/activate
	@echo "🎯 Running tests for changed files..."
	@if git diff --name-only HEAD~1 | grep -E "\.(py)$$" >/dev/null 2>&1; then \
		echo "   Detected Python file changes"; \
		changed_files=$$(git diff --name-only HEAD~1 | grep -E "\.(py)$$" | tr '\n' ' '); \
		echo "   Changed files: $$changed_files"; \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest \
			--ignore=.markitect_workspace/ \
			-v \
			--tb=short; \
	else \
		echo "   No Python file changes detected"; \
		echo "   Running smoke tests instead..."; \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ \
			--ignore=.markitect_workspace/ \
			-m "smoke" \
			-q; \
	fi

# Run tests for a specific module
test-module: $(VENV)/bin/activate
	@if [ -z "$(MODULE)" ]; then \
		echo "❌ Please specify module: make test-module MODULE=markitect.cli"; \
		exit 1; \
	fi
	@echo "🎯 Running tests for module: $(MODULE)..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ \
		--ignore=.markitect_workspace/ \
		-k "$(MODULE)" \
		-v \
		--tb=short

# Clean up stale cache entries
test-cache-clean: $(VENV)/bin/activate
	@echo "🧹 Cleaning test cache..."
	@if [ -d ".pytest_cache" ]; then \
		echo "   Removing pytest cache directory..."; \
		rm -rf .pytest_cache/; \
		echo "   ✅ Cache cleaned"; \
	else \
		echo "   ✅ No cache to clean"; \
	fi

# Enhanced test command with workspace exclusion (replace default test)
test-efficient: $(VENV)/bin/activate
	@echo "🧪 Running efficient test suite (excluding workspaces)..."
	@PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ \
		--ignore=.markitect_workspace/ \
		-v \
		--tb=short \
		--maxfail=5

.PHONY: test-clean test-tdd test-changed test-module test-cache-clean test-efficient

# ============================================================================
# MarkiTect CLI Usage Targets
# ============================================================================

# Variables for CLI targets
MARKITECT := PYTHONPATH=. $(VENV_PYTHON) -c "from markitect.cli import cli; import sys; cli(sys.argv[1:])"
SAMPLE_DOC := test_frontmatter.md
OUTPUT_FORMAT := table

# Basic document operations
cli-ingest: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "📄 Processing sample document..."; \
		$(MARKITECT) ingest $(SAMPLE_DOC); \
	else \
		echo "📄 Processing document: $(FILE)"; \
		$(MARKITECT) ingest $(FILE); \
	fi

cli-status: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "📊 Checking status of sample document..."; \
		$(MARKITECT) status $(SAMPLE_DOC); \
	else \
		echo "📊 Checking status of document: $(FILE)"; \
		$(MARKITECT) status $(FILE); \
	fi

cli-list: $(VENV)/bin/activate
	@echo "📋 Listing all processed documents..."
	@$(MARKITECT) list --format $(OUTPUT_FORMAT)

cli-get: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "📖 Retrieving sample document..."; \
		$(MARKITECT) get $(SAMPLE_DOC); \
	else \
		echo "📖 Retrieving document: $(FILE)"; \
		$(MARKITECT) get $(FILE); \
	fi

# Schema operations
cli-schema-generate: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "🔧 Generating schema from sample document..."; \
		$(MARKITECT) schema-generate $(SAMPLE_DOC) --format json; \
	else \
		echo "🔧 Generating schema from document: $(FILE)"; \
		$(MARKITECT) schema-generate $(FILE) --format json; \
	fi

cli-schema-ingest: $(VENV)/bin/activate
	@if [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-schema-ingest SCHEMA=schema.json"; \
		echo "   Example: make cli-schema-ingest SCHEMA=my_schema.json"; \
		exit 1; \
	fi
	@echo "📥 Ingesting schema: $(SCHEMA)"
	@$(MARKITECT) schema-ingest $(SCHEMA)

cli-schema-list: $(VENV)/bin/activate
	@echo "📋 Listing stored schemas..."
	@$(MARKITECT) schema-list --format $(OUTPUT_FORMAT)

cli-schema-get: $(VENV)/bin/activate
	@if [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-schema-get SCHEMA=schema_name"; \
		echo "   Example: make cli-schema-get SCHEMA=my_schema.json"; \
		exit 1; \
	fi
	@echo "📖 Retrieving schema: $(SCHEMA)"
	@$(MARKITECT) schema-get $(SCHEMA)

cli-validate: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ] || [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-validate FILE=document.md SCHEMA=schema.json"; \
		echo "   Example: make cli-validate FILE=test_frontmatter.md SCHEMA=generated_schema.json"; \
		exit 1; \
	fi
	@echo "✅ Validating $(FILE) against $(SCHEMA)..."
	@$(MARKITECT) validate $(FILE) $(SCHEMA)

cli-validate-detailed: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ] || [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-validate-detailed FILE=document.md SCHEMA=schema.json"; \
		echo "   Example: make cli-validate-detailed FILE=test_frontmatter.md SCHEMA=generated_schema.json"; \
		exit 1; \
	fi
	@echo "🔍 Validating $(FILE) with detailed errors..."
	@$(MARKITECT) validate $(FILE) $(SCHEMA) --detailed-errors --error-format text

# AST operations
cli-ast-show: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "🌳 Showing AST for sample document..."; \
		$(MARKITECT) ast-show $(SAMPLE_DOC); \
	else \
		echo "🌳 Showing AST for document: $(FILE)"; \
		$(MARKITECT) ast-show $(FILE); \
	fi

cli-ast-stats: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "📈 Showing AST statistics for sample document..."; \
		$(MARKITECT) ast-stats $(SAMPLE_DOC); \
	else \
		echo "📈 Showing AST statistics for document: $(FILE)"; \
		$(MARKITECT) ast-stats $(FILE); \
	fi

cli-ast-query: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ] || [ -z "$(QUERY)" ]; then \
		echo "❌ Usage: make cli-ast-query FILE=document.md QUERY='JSONPath expression'"; \
		echo "   Example: make cli-ast-query FILE=test_frontmatter.md QUERY='$.headings[*].text'"; \
		exit 1; \
	fi
	@echo "🔍 Querying AST: $(QUERY)"
	@$(MARKITECT) ast-query $(FILE) '$(QUERY)'

# Metadata operations
cli-metadata: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "🏷️  Showing metadata for sample document..."; \
		$(MARKITECT) metadata $(SAMPLE_DOC) --format $(OUTPUT_FORMAT); \
	else \
		echo "🏷️  Showing metadata for document: $(FILE)"; \
		$(MARKITECT) metadata $(FILE) --format $(OUTPUT_FORMAT); \
	fi

# Database operations
cli-query: $(VENV)/bin/activate
	@if [ -z "$(SQL)" ]; then \
		echo "❌ Usage: make cli-query SQL='SELECT statement'"; \
		echo "   Example: make cli-query SQL='SELECT * FROM files LIMIT 5'"; \
		exit 1; \
	fi
	@echo "🗄️  Executing SQL query..."
	@$(MARKITECT) query '$(SQL)' --format $(OUTPUT_FORMAT)

cli-schema-db: $(VENV)/bin/activate
	@echo "🗄️  Showing database schema..."
	@$(MARKITECT) schema

# Cache management
cli-cache-info: $(VENV)/bin/activate
	@echo "💾 Cache information..."
	@$(MARKITECT) cache-info

cli-cache-clean: $(VENV)/bin/activate
	@echo "🧹 Cleaning cache..."
	@$(MARKITECT) cache-clean

cli-cache-invalidate: $(VENV)/bin/activate
	@if [ -z "$(FILE)" ]; then \
		echo "❌ Usage: make cli-cache-invalidate FILE=document.md"; \
		exit 1; \
	fi
	@echo "🔄 Invalidating cache for $(FILE)..."
	@$(MARKITECT) cache-invalidate $(FILE)

# Schema visualization
cli-visualize-schema: $(VENV)/bin/activate
	@if [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-visualize-schema SCHEMA=schema.json"; \
		echo "   Example: make cli-visualize-schema SCHEMA=generated_schema.json"; \
		exit 1; \
	fi
	@echo "🎨 Visualizing schema: $(SCHEMA)"
	@$(VENV_PYTHON) visualize_schema.py $(SCHEMA)

cli-visualize-schema-ascii: $(VENV)/bin/activate
	@if [ -z "$(SCHEMA)" ]; then \
		echo "❌ Usage: make cli-visualize-schema-ascii SCHEMA=schema.json"; \
		echo "   Example: make cli-visualize-schema-ascii SCHEMA=generated_schema.json"; \
		exit 1; \
	fi
	@echo "🎨 Visualizing schema (ASCII mode): $(SCHEMA)"
	@$(VENV_PYTHON) visualize_schema.py $(SCHEMA) --ascii

# Complete workflow examples
cli-workflow-basic: $(VENV)/bin/activate
	@echo "🔄 Running basic MarkiTect workflow..."
	@echo "  Step 1: Ingest document"
	@$(MARKITECT) ingest $(SAMPLE_DOC)
	@echo ""
	@echo "  Step 2: Show status"
	@$(MARKITECT) status $(SAMPLE_DOC)
	@echo ""
	@echo "  Step 3: Show AST statistics"
	@$(MARKITECT) ast-stats $(SAMPLE_DOC)
	@echo ""
	@echo "✅ Basic workflow complete!"

cli-workflow-schema: $(VENV)/bin/activate
	@echo "🔄 Running schema generation and validation workflow..."
	@if [ -z "$(FILE)" ]; then \
		echo "❌ Usage: make cli-workflow-schema FILE=document.md"; \
		echo "   Example: make cli-workflow-schema FILE=test_frontmatter.md"; \
		exit 1; \
	fi
	@echo "  Step 1: Ingest document"
	@$(MARKITECT) ingest $(FILE)
	@echo ""
	@echo "  Step 2: Generate schema"
	@$(MARKITECT) schema-generate $(FILE) --format json > temp_schema.json
	@echo "  Schema saved to temp_schema.json"
	@echo ""
	@echo "  Step 3: Validate document against generated schema"
	@$(MARKITECT) validate $(FILE) temp_schema.json
	@echo ""
	@echo "  Step 4: Visualize schema"
	@$(VENV_PYTHON) visualize_schema.py temp_schema.json --ascii
	@echo ""
	@echo "✅ Schema workflow complete!"
	@echo "💡 Schema file: temp_schema.json"

# Help for CLI targets
cli-help:
	@echo "🚀 MarkiTect CLI Usage Targets"
	@echo "============================="
	@echo ""
	@echo "Document Operations:"
	@echo "  cli-ingest [FILE=doc.md]     - Process and store markdown file"
	@echo "  cli-status [FILE=doc.md]     - Show processing status"
	@echo "  cli-list [OUTPUT_FORMAT=table] - List all processed documents"
	@echo "  cli-get [FILE=doc.md]        - Retrieve processed document"
	@echo "  cli-metadata [FILE=doc.md]   - Show document metadata"
	@echo ""
	@echo "Schema Operations:"
	@echo "  cli-schema-generate [FILE=doc.md]        - Generate JSON schema"
	@echo "  cli-schema-ingest SCHEMA=schema.json     - Store schema in database"
	@echo "  cli-schema-list [OUTPUT_FORMAT=table]   - List stored schemas"
	@echo "  cli-schema-get SCHEMA=name               - Retrieve stored schema"
	@echo "  cli-validate FILE=doc.md SCHEMA=schema.json - Validate document"
	@echo "  cli-validate-detailed FILE=doc.md SCHEMA=schema.json - Detailed validation"
	@echo "  cli-visualize-schema SCHEMA=schema.json  - Visualize schema (colorful)"
	@echo "  cli-visualize-schema-ascii SCHEMA=schema.json - Visualize schema (ASCII)"
	@echo ""
	@echo "AST Operations:"
	@echo "  cli-ast-show [FILE=doc.md]   - Display AST structure"
	@echo "  cli-ast-stats [FILE=doc.md]  - Show AST statistics"
	@echo "  cli-ast-query FILE=doc.md QUERY='JSONPath' - Query AST"
	@echo ""
	@echo "Database Operations:"
	@echo "  cli-query SQL='SELECT...'    - Execute SQL query"
	@echo "  cli-schema-db               - Show database schema"
	@echo ""
	@echo "Cache Management:"
	@echo "  cli-cache-info              - Show cache statistics"
	@echo "  cli-cache-clean             - Clear all caches"
	@echo "  cli-cache-invalidate FILE=doc.md - Invalidate specific file cache"
	@echo ""
	@echo "Complete Workflows:"
	@echo "  cli-workflow-basic          - Basic ingest → status → stats workflow"
	@echo "  cli-workflow-schema FILE=doc.md - Complete schema workflow"
	@echo ""
	@echo "📋 Variables:"
	@echo "  FILE         - Target markdown file (default: $(SAMPLE_DOC))"
	@echo "  OUTPUT_FORMAT - Output format: table, json, yaml, simple (default: $(OUTPUT_FORMAT))"
	@echo "  SCHEMA       - JSON schema file"
	@echo "  SQL          - SQL query string"
	@echo "  QUERY        - JSONPath query expression"
	@echo ""
	@echo "💡 Examples:"
	@echo "  make cli-ingest FILE=my_document.md"
	@echo "  make cli-list OUTPUT_FORMAT=table"
	@echo "  make cli-schema-list OUTPUT_FORMAT=simple"
	@echo "  make cli-validate FILE=doc.md SCHEMA=doc_schema.json"
	@echo "  make cli-ast-query FILE=doc.md QUERY='$.headings[*].text'"
	@echo "  make cli-query SQL='SELECT title FROM metadata WHERE status=\"draft\"'"

# Update .PHONY for CLI targets
.PHONY: cli-ingest cli-status cli-list cli-get cli-schema-generate cli-schema-ingest cli-schema-list cli-schema-get cli-validate cli-validate-detailed cli-ast-show cli-ast-stats cli-ast-query cli-metadata cli-query cli-schema-db cli-cache-info cli-cache-clean cli-cache-invalidate cli-visualize-schema cli-visualize-schema-ascii cli-workflow-basic cli-workflow-schema cli-help

# ============================================================================
# Requirements Engineering Integration
# ============================================================================

# Validate project requirements and foundations before development
validate-requirements: $(VENV)/bin/activate
	@echo "🔍 Validating project requirements and foundations..."
	@PYTHONPATH=. $(VENV_PYTHON) tools/requirements_engineering_toolkit.py analyze

# Check interface compatibility for specific interface
check-interface-compatibility: $(VENV)/bin/activate
	@if [ -z "$(INTERFACE)" ]; then \
		echo "❌ Please specify interface: make check-interface-compatibility INTERFACE=IssueBackend"; \
		exit 1; \
	fi
	@echo "🔌 Checking interface compatibility for $(INTERFACE)..."
	@PYTHONPATH=. $(VENV_PYTHON) tools/requirements_engineering_toolkit.py plan-interface --interface $(INTERFACE)

# Generate development checklist for specific feature
generate-dev-checklist: $(VENV)/bin/activate
	@if [ -z "$(FEATURE)" ]; then \
		echo "❌ Please specify feature: make generate-dev-checklist FEATURE='Your Feature Name'"; \
		exit 1; \
	fi
	@echo "📋 Generating development checklist for $(FEATURE)..."
	@PYTHONPATH=. $(VENV_PYTHON) tools/requirements_engineering_toolkit.py checklist --feature "$(FEATURE)"

# Validate mock object compatibility
validate-mocks: $(VENV)/bin/activate
	@echo "🧪 Validating mock object compatibility..."
	@if [ -f "tests/test_mock_compatibility.py" ]; then \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/test_mock_compatibility.py -xvs; \
	else \
		echo "⚠️  Mock compatibility tests not found"; \
		echo "   Run 'make setup-mock-validation' to create them"; \
	fi

# Pre-commit validation including requirements
pre-commit-validate: validate-requirements validate-mocks
	@echo "✅ Pre-commit validation complete"

# Setup mock validation test file
setup-mock-validation: $(VENV)/bin/activate
	@echo "🔧 Setting up mock validation tests..."
	@if [ ! -f "tests/test_mock_compatibility.py" ]; then \
		cp docs/integration/requirements_engineering_integration.md tests/temp_integration_guide.md; \
		echo "💡 Mock compatibility test template available in integration guide"; \
		echo "   Create tests/test_mock_compatibility.py based on the guide"; \
		echo "   See docs/integration/requirements_engineering_integration.md"; \
	else \
		echo "✅ Mock validation tests already exist"; \
	fi

# View requirements engineering usage examples
view-requirements-examples: $(VENV)/bin/activate
	@echo "📖 Requirements Engineering Usage Examples"
	@echo "========================================="
	@echo ""
	@echo "Foundation Analysis:"
	@echo "  make validate-requirements"
	@echo ""
	@echo "Interface Planning:"
	@echo "  make check-interface-compatibility INTERFACE=IssueBackend"
	@echo "  make check-interface-compatibility INTERFACE=PluginManager"
	@echo ""
	@echo "Feature Development:"
	@echo "  make generate-dev-checklist FEATURE='New Plugin System'"
	@echo "  make generate-dev-checklist FEATURE='CLI Enhancement'"
	@echo ""
	@echo "Mock Validation:"
	@echo "  make validate-mocks"
	@echo "  make setup-mock-validation"
	@echo ""
	@echo "Complete Workflow:"
	@echo "  make pre-commit-validate"
	@echo ""
	@echo "📋 Prevention Demo:"
	@echo "  PYTHONPATH=. $(VENV_PYTHON) examples/issue_59_prevention_demo.py"

# Update .PHONY for requirements engineering targets
.PHONY: validate-requirements check-interface-compatibility generate-dev-checklist validate-mocks pre-commit-validate setup-mock-validation view-requirements-examples

# ==============================================================================
# Cost Tracking Commands
# ==============================================================================

# Show cost tracking help and examples
cost-help:
	@echo "MarkiTect Cost Tracking System"
	@echo "==============================="
	@echo ""
	@echo "The cost tracking system captures Claude token usage and generates"
	@echo "cost notes for issues. Currently tracks Claude API costs only."
	@echo ""
	@echo "🔧 Commands:"
	@echo "  cost-help                                    - Show this help"
	@echo "  cost-note-issue ISSUE=X INPUT_TOKENS=N OUTPUT_TOKENS=M"
	@echo "                                               - Generate cost note for issue"
	@echo ""
	@echo "💰 Manual Cost Note Generation:"
	@echo "  markitect cost session track ISSUE_ID 'ISSUE_TITLE' \\"
	@echo "    --input-tokens N --output-tokens M \\"
	@echo "    --summary 'Implementation description'"
	@echo ""
	@echo "📊 Token Estimation Guidelines:"
	@echo "  - Small changes (1-2 functions):     15k input,  8k output"
	@echo "  - Medium features (multiple files):  30k input, 18k output"
	@echo "  - Large features (TDD8 full cycle): 45k input, 28k output"
	@echo "  - Complex systems (refactoring):    60k input, 35k output"
	@echo ""
	@echo "💡 Examples:"
	@echo "  make cost-note-issue ISSUE=136 INPUT_TOKENS=45000 OUTPUT_TOKENS=28000"
	@echo "  markitect cost session track 136 'Index generation' --input-tokens 45000 --output-tokens 28000"
	@echo ""
	@echo "📁 Output: Cost notes saved to cost_notes/ directory"
	@echo "💰 Currency: Costs calculated in USD and EUR"
	@echo "🤖 Model: Default claude-sonnet-4 pricing"

# JavaScript validation for edit mode templates
validate-js: $(VENV)/bin/activate
	@echo "🔍 Validating JavaScript syntax in templates..."
	@if command -v node >/dev/null 2>&1; then \
		$(PYTHON) tools/validate_js_syntax.py; \
	else \
		echo "⚠️  Node.js not available - skipping JavaScript validation"; \
		echo "   Install Node.js to enable JavaScript syntax checking"; \
	fi