# Extract file organization section
awk '/## File Organization/,/^## [A-Z]/' CLAUDE.md

# Or from PROJECT.md
awk '/## File Organization Standards/,/^## [A-Z]/' PROJECT.md

{
  "root_policy": {
    "max_md_files": 8,
    "essential_files": ["README.md", "CHANGELOG.md", ...]
  },
  "scripts": {
    "allowed_locations": ["scripts/debug/", "scripts/test/", "scripts/build/"]
  },
  "documentation": {
    "allowed_locations": ["docs/guides/", "docs/debugging/", "docs/development/", "docs/architecture/", "docs/reference/"],
    "root_allowed": false
  },
  "source_code": {
    "allowed_locations": ["src/"]
  }
}

file_organization:
  exceptions:
    - "build*.sh" # Allow build scripts in root
    - "Dockerfile*" # Allow Dockerfiles anywhere

FILE_PATH="$1"
FILE_EXT="${FILE_PATH##*.}"
FILE_NAME=$(basename "$FILE_PATH")
FILE_DIR=$(dirname "$FILE_PATH")

if [[ "$FILE_EXT" == "sh" ]]; then
  if [[ ! "$FILE_PATH" =~ ^scripts/ ]]; then
    echo "❌ Shell scripts must be in scripts/ subdirectories"
    # Determine correct location
    if [[ "$FILE_NAME" =~ ^test- ]]; then
      CORRECT_PATH="scripts/test/$FILE_NAME"
    elif [[ "$FILE_NAME" =~ ^debug- ]]; then
      CORRECT_PATH="scripts/debug/$FILE_NAME"
    else
      CORRECT_PATH="scripts/$FILE_NAME"
    fi
  fi
fi

if [[ "$FILE_EXT" == "md" ]]; then
  # Check if essential file
  ESSENTIAL="README|CHANGELOG|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|CLAUDE|PROJECT"

  if [[ ! "$FILE_NAME" =~ ^($ESSENTIAL)\.md$ ]]; then
    # Not essential - must be in docs/
    if [[ ! "$FILE_PATH" =~ ^docs/ ]]; then
      echo "❌ Non-essential .md files must be in docs/ subdirectories"

      # Infer category from name
      if [[ "$FILE_NAME" =~ -guide|tutorial|getting-started ]]; then
        CORRECT_PATH="docs/guides/$FILE_NAME"
      elif [[ "$FILE_NAME" =~ debug|troubleshoot|error ]]; then
        CORRECT_PATH="docs/debugging/$FILE_NAME"
      elif [[ "$FILE_NAME" =~ arch|design|adr ]]; then
        CORRECT_PATH="docs/architecture/$FILE_NAME"
      elif [[ "$FILE_NAME" =~ api|reference ]]; then
        CORRECT_PATH="docs/reference/$FILE_NAME"
      else
        CORRECT_PATH="docs/$FILE_NAME"
      fi
    fi
  fi
fi

if [[ "$FILE_EXT" =~ ^(ts|js|py|go|rs)$ ]]; then
  # Exclude test files
  if [[ ! "$FILE_NAME" =~ \.test\.|_test\.|\.spec\. ]]; then
    # Should be in src/
    if [[ ! "$FILE_PATH" =~ ^src/ ]]; then
      echo "❌ Source code must be in src/"
      CORRECT_PATH="src/$FILE_NAME"
    fi
  else
    # Test file - should be in tests/
    if [[ ! "$FILE_PATH" =~ ^tests/ ]]; then
      echo "❌ Test files must be in tests/"
      # Determine test type
      if [[ "$FILE_NAME" =~ \.unit\. ]]; then
        CORRECT_PATH="tests/unit/$FILE_NAME"
      elif [[ "$FILE_NAME" =~ \.integration\. ]]; then
        CORRECT_PATH="tests/integration/$FILE_NAME"
      else
        CORRECT_PATH="tests/unit/$FILE_NAME"
      fi
    fi
  fi
fi

file_organization:
  enforcement: "auto-fix" # or "block" or "warn"

🤖 file-organization skill activated

Proposed: ./test-auth.sh
Rule Check: Shell scripts → scripts/debug/ or scripts/test/
File Purpose: Testing script (detected from name prefix "test-")
Correct Location: scripts/test/

✅ Auto-corrected to: scripts/test/test-auth.sh
   Reason: Testing scripts belong in scripts/test/ (CLAUDE.md:45)

File created at correct location.

# Instead of creating at wrong location
# Claude creates at correct location directly
PROPOSED="./test-auth.sh"
CORRECT="./scripts/test/test-auth.sh"

# Create parent directory if needed
mkdir -p $(dirname "$CORRECT")

# Create file at correct location
# (Claude's Write/Edit tool uses $CORRECT instead of $PROPOSED)

❌ CLAUDE.md Rule Violation:
   Shell scripts must be in scripts/debug/ or scripts/test/

   Proposed: ./test-auth.sh
   Suggested: scripts/test/test-auth.sh
   Reason: Keeps root directory clean (CLAUDE.md policy)

Please create file at correct location:
  Write: scripts/test/test-auth.sh

⚠️ File organization warning:
   Created: ./test-auth.sh
   Recommended: scripts/test/test-auth.sh
   Reason: Shell scripts should be in scripts/ subdirectories

File created at requested location.
Note: Run /align-project to organize files.

OLD_PATH="./test-auth.sh"
NEW_PATH="./scripts/test/test-auth.sh"

# Search for references in docs
REFS=$(grep -r "$OLD_PATH" --include="*.md" .)

if [ -n "$REFS" ]; then
  echo "📝 Updating documentation references..."

  # Auto-update (since file hasn't been created yet, unlikely to have refs)
  # But check for template references
fi

{
  "auto_fixes": [
    {
      "timestamp": "2024-10-26T15:30:00Z",
      "proposed": "./test-auth.sh",
      "corrected": "./scripts/test/test-auth.sh",
      "reason": "Shell scripts must be in scripts/ subdirectories",
      "rule": "CLAUDE.md:45"
    }
  ]
}

🤖 file-organization skill activated

Proposed: ./scripts/deploy/deploy.sh
Rule Check: scripts/deploy/ not in documented categories

New category detected: scripts/deploy/
This isn't documented in CLAUDE.md.

Options:
1. Allow (one-off script) → use scripts/deploy.sh
2. Create new category → Add to CLAUDE.md:

   ## File Organization
   - scripts/deploy/ - Deployment scripts

Create new category? [y/N]

Proposed: ./tsconfig.json
Rule Check: Configuration file
Enforcement: SKIP (config files allowed in root)

✅ Config file - root location is standard

Proposed: ./.github/workflows/ci.yml
Rule Check: Hidden directory
Enforcement: SKIP (hidden dirs have different conventions)

✅ GitHub workflows - standard location

#!/bin/bash
# .claude/hooks/pre-commit.sh

# Check for files in wrong locations
echo "🔍 Validating file organization..."

# Check for non-essential .md in root
ROOT_MD_COUNT=$(git diff --cached --name-only --diff-filter=A | \
  grep '^[^/]*\.md$' | \
  grep -v -E '(README|CHANGELOG|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|CLAUDE|PROJECT)\.md' | \
  wc -l)

if [ "$ROOT_MD_COUNT" -gt 0 ]; then
  echo "❌ Attempting to commit non-essential .md files in root:"
  git diff --cached --name-only --diff-filter=A | \
    grep '^[^/]*\.md$' | \
    grep -v -E '(README|CHANGELOG|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|CLAUDE|PROJECT)\.md'
  echo ""
  echo "Move to docs/ subdirectories per CLAUDE.md"
  exit 1
fi

# Check for shell scripts in root
ROOT_SH=$(git diff --cached --name-only --diff-filter=A | grep '^[^/]*\.sh$' | wc -l)

if [ "$ROOT_SH" -gt 0 ]; then
  echo "❌ Attempting to commit shell scripts in root:"
  git diff --cached --name-only --diff-filter=A | grep '^[^/]*\.sh$'
  echo ""
  echo "Move to scripts/ subdirectories per CLAUDE.md"
  exit 1
fi

echo "✅ File organization validated"

file_organization:
  # Enforcement level
  enforcement: "auto-fix" # Options: "auto-fix", "block", "warn"

  # Root directory policy
  root_directory:
    max_md_files: 8
    essential_files:
      - "README.md"
      - "CHANGELOG.md"
      - "LICENSE"
      - "CONTRIBUTING.md"
      - "CODE_OF_CONDUCT.md"
      - "SECURITY.md"
      - "CLAUDE.md"
      - "PROJECT.md"

  # Directory structure rules
  rules:
    shell_scripts:
      allowed_locations:
        - "scripts/debug/"
        - "scripts/test/"
        - "scripts/build/"
      exceptions: []

    markdown_docs:
      allowed_locations:
        - "docs/guides/"
        - "docs/debugging/"
        - "docs/development/"
        - "docs/architecture/"
        - "docs/reference/"
      root_allowed: false # Only essential files

    source_code:
      allowed_locations:
        - "src/"
      exceptions:
        - "tests/"

  # Exceptions (files/patterns exempt from rules)
  exceptions:
    - "build*.sh" # Allow build.sh in root
    - "Dockerfile*" # Dockerfiles anywhere

  # Auto-create directories
  auto_create_dirs: true # Create target directory if missing