chore: warm up CI checks

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.env.example

@@ -1,7 +1,7 @@
 # file: .env.example
 # owner: duksan
 # created: 2025-09-22 11:15 UTC / 2025-09-22 20:15 KST
-# updated: 2025-09-22 11:15 UTC / 2025-09-22 20:15 KST
+# updated: 2025-09-23 06:33 UTC / 2025-09-23 15:33 KST
 # description: 샘플 환경 변수 파일(민감값은 비워두고 문서화 목적)
 # doc_refs: ["SECURITY.md", "THREAT_MODEL.md", "admin/plan/improvement-rounds.md"]
 
@@ -25,3 +25,24 @@ STORAGE_BUCKET=gg-real
 STORAGE_ACCESS_KEY=your-access-key
 STORAGE_SECRET_KEY=your-secret-key
 
+# Observability / Monitoring
+ENABLE_SENTRY=false
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=development
+SENTRY_TRACES_SAMPLE_RATE=0.1
+SENTRY_PROFILES_SAMPLE_RATE=0.1
+ENABLE_OTEL=false
+OTEL_SERVICE_NAME=gg-real-api
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer YOUR_TOKEN
+
+# Frontend Sentry
+NEXT_PUBLIC_ENABLE_SENTRY=false
+NEXT_PUBLIC_SENTRY_DSN=
+NEXT_PUBLIC_SENTRY_ENVIRONMENT=development
+NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0.1
+NEXT_PUBLIC_SENTRY_PROFILES_SAMPLE_RATE=0.1
+
+# Optional Sentry project metadata
+SENTRY_ORG=
+SENTRY_PROJECT=

.githooks/pre-commit

@@ -1,10 +1,48 @@
 #!/usr/bin/env bash
-# Git pre-commit hook: 문서 변경 포함 시 자동 체크포인트 생성 후 스테이징
+# Git pre-commit hook: 민감 파일 가드 + 문서 updated 자동 스탬프 + 문서 변경 시 체크포인트
 set -euo pipefail
 
 # 현재 스테이징된 파일 목록
 staged=$(git diff --cached --name-only --diff-filter=ACMR || true)
 
+# [Guard] 비밀/민감 파일 스테이징 차단(.env/키/자격증명 등)
+if [[ -n "$staged" ]]; then
+  # 차단 패턴 목록(확장 가능)
+  deny_patterns=(
+    '^\.env(\..*)?$'            # .env, .env.*
+    '(^|/)\.env(\..*)?$'        # any path/.env*
+    '\.pem$'                     # private keys
+    '\b(id_rsa|id_ecdsa|id_ed25519)(\.pub)?$'
+    '\.p8$'                      # Apple keys
+    '\bservice-account.*\.json$'
+  )
+  for f in $staged; do
+    for pat in "${deny_patterns[@]}"; do
+      if [[ $f =~ $pat ]]; then
+        echo "[pre-commit][BLOCK] 민감 파일 스테이징 감지: $f" >&2
+        echo "[pre-commit] 해당 파일은 .gitignore에 추가하고 커밋에서 제외하세요." >&2
+        exit 1
+      fi
+    done
+  done
+fi
+
+# 문서 updated: 자동 스탬프(UTC/KST)
+if [ -n "$staged" ]; then
+  if [ -x scripts/update_frontmatter_time.sh ]; then
+    bash scripts/update_frontmatter_time.sh >/dev/null 2>&1 || true
+  fi
+fi
+
+# 핵심 검사: 문서/참조/마이그/코드헤더/사이드카
+if [ -n "$staged" ]; then
+  bash scripts/validate_docs.sh
+  bash scripts/validate_refs.sh
+  bash scripts/validate_migrations.sh
+  bash scripts/validate_code_headers.sh
+  bash scripts/validate_sidecar_meta.sh
+fi
+
 # 문서 변경이 있는지 검사(.md 또는 admin/docs 디렉토리 등)
 if echo "$staged" | grep -Eq '\.(md)$|^AGENTS\.md$|^admin/|^docs/'; then
   # 체크포인트 생성하고 파일을 커밋에 포함

.github/workflows/auto-enable-automerge.yml

@@ -0,0 +1,31 @@
+name: Auto Enable PR Auto-Merge
+
+on:
+  pull_request:
+    types: [opened, ready_for_review]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  enable-automerge:
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge (squash)
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request
+            try {
+              const query = `mutation($pr:ID!, $method: PullRequestMergeMethod!) {
+                enablePullRequestAutoMerge(input:{pullRequestId:$pr, mergeMethod:$method}) {
+                  clientMutationId
+                }
+              }`
+              await github.graphql(query, { pr: pr.node_id, method: 'SQUASH' })
+              core.info('Auto-merge enabled (SQUASH)')
+            } catch (e) {
+              core.warning('Auto-merge enable failed: ' + e.message)
+            }

.github/workflows/build.yml

@@ -0,0 +1,54 @@
+name: Build Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: ${{ matrix.task }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        task:
+          - lint:root
+          - lint:web
+          - lint:api
+          - typecheck
+          - build:web
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.12.0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build documents (verbose)
+        if: ${{ matrix.task == 'build:web' }}
+        run: pnpm --filter @gg-real/documents run build
+
+      - name: Build web (verbose)
+        if: ${{ matrix.task == 'build:web' }}
+        run: pnpm --filter web run build
+
+      - name: Run task (default)
+        if: ${{ matrix.task != 'build:web' }}
+        run: pnpm run ${{ matrix.task }}

.github/workflows/ci.yml

@@ -13,6 +13,9 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install ripgrep (rg)
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
       - name: Run secrets scan (strict)
         run: |
           chmod +x scripts/secrets_scan.sh || true
@@ -23,12 +26,15 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # gitleaks가 PR 범위를 계산할 수 있게 전체 히스토리 필요
 
       - name: Run gitleaks
         uses: zricethezav/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          config-path: .gitleaks.toml
-          fail: true
+          args: "--source . --no-banner"
 
   summary:
     runs-on: ubuntu-latest

.github/workflows/docs-validate.yml

@@ -2,43 +2,65 @@ name: Docs Validate
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   docs-validate:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.12.0
+          run_install: false
 
-      - name: Setup Node
+      - name: Setup Node 20
         uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run precommit:meta (docs + refs)
+        run: pnpm -s precommit:meta
+
+      - name: Run docs validator (full suite)
+        run: pnpm run validate:docs
 
-      - name: Install markdownlint-cli
-        run: npm i -g markdownlint-cli@0.38.0
+      - name: Run cross-ref validator (R9)
+        run: pnpm run validate:refs
 
-      - name: Install ajv-cli and js-yaml
-        run: npm i -g ajv-cli@5.0.0 js-yaml@4.1.0
+      - name: Run migration governance validator (R10)
+        run: pnpm exec bash scripts/validate_migrations.sh
 
-      - name: Run markdownlint (MD029 ordered)
-        run: markdownlint -q -c .markdownlint.json "**/*.md"
+      - name: Run code header validator (P1)
+        run: pnpm exec bash scripts/validate_code_headers.sh
 
-      - name: Run local docs validator
-        run: bash scripts/validate_docs.sh
+      - name: Run sidecar meta validator (P3)
+        env:
+          ALLOW_SIDECAR_MISSING: 'true'
+        run: pnpm exec bash scripts/validate_sidecar_meta.sh
 
       - name: Validate hub manifests against schema
         if: ${{ always() }}
         run: |
           set -e
           shopt -s nullglob
           for f in admin/manifests/*.yaml; do
+            # Skip sidecar files like *.meta.yaml — they are validated separately
+            case "$f" in *.meta.yaml) continue ;; esac
             echo "Validating $f"
-            tmp=$(mktemp)
-            js-yaml "$f" > "$tmp"
-            ajv validate -s admin/schemas/hub.schema.json -d "$tmp"
+            tmp="$(mktemp).json"
+            pnpm exec js-yaml "$f" > "$tmp"
+            pnpm exec ajv validate -s admin/schemas/hub.schema.json -d "$tmp"
             rm -f "$tmp"
           done

.gitignore

@@ -0,0 +1,25 @@
+# Environment
+.env
+
+# Node.js
+node_modules/
+.pnpm-store/
+.pnp.*
+
+# Build outputs
+.next/
+dist/
+build/
+out/
+coverage/
+.turbo/
+
+# Logs and caches
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+*.log
+.DS_Store
+.idea/
+.vscode/

.husky/pre-commit

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -e
+
+pnpm -s precommit:meta
+pnpm exec lint-staged

.nvmrc

@@ -0,0 +1 @@
+v20.16.0

.prettierignore

@@ -0,0 +1,8 @@
+# Auto-generated checkpoint snapshots
+admin/checkpoints/**
+
+# pnpm lockfile formatting은 pnpm이 담당
+pnpm-lock.yaml
+
+# Git hooks 템플릿 등 바이너리성 스크립트
+.githooks/**