@team-semicolon/semicolony-cli 4.18.51

package/migrations/020_bot_workspace_standard.sql

@@ -0,0 +1,174 @@
+-- 020: bot_workspace_standard — 봇 워크스페이스 규격 SoT 테이블
+-- v2.0 규격을 DB로 통합하여 MCP 도구/audit/셸 스크립트가 단일 소스에서 규칙 로드
+
+CREATE TABLE IF NOT EXISTS semicolony.bot_workspace_standard (
+  id              BIGSERIAL PRIMARY KEY,
+  path_pattern    VARCHAR(255) NOT NULL,     -- "SOUL.md", ".claude/", "*.ovpn"
+  entry_type      VARCHAR(20)  NOT NULL,     -- 'file' | 'dir' | 'symlink' | 'glob'
+  level           VARCHAR(20)  NOT NULL,     -- 'required' | 'optional' | 'forbidden'
+  severity        VARCHAR(10)  NOT NULL DEFAULT 'error',  -- 'error' | 'warn'
+  category        VARCHAR(50)  NOT NULL DEFAULT 'structure', -- 'structure' | 'legacy' | 'hygiene'
+  bot_scope       VARCHAR(20)  NOT NULL DEFAULT 'all',    -- 'all' | 'include' | 'exclude'
+  bot_ids         TEXT[]       DEFAULT '{}',
+  symlink_target  TEXT,                      -- 심링크 타겟 (템플릿: $HOME)
+  content_rules   JSONB,                     -- 콘텐츠 검증 규칙
+  description     TEXT,
+  fix_action      VARCHAR(50),               -- 'create_file' | 'create_dir' | 'create_symlink' | null
+  fix_template    TEXT,                      -- --fix 시 생성할 콘텐츠 ($BOT_ID 치환)
+  spec_version    VARCHAR(20)  NOT NULL DEFAULT '2.0',
+  created_at      TIMESTAMPTZ  DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ  DEFAULT NOW(),
+  UNIQUE (path_pattern, spec_version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_bws_level ON semicolony.bot_workspace_standard(level);
+CREATE INDEX IF NOT EXISTS idx_bws_version ON semicolony.bot_workspace_standard(spec_version);
+
+-- ============================================================
+-- Seed data (v2.0 규격 ~35행)
+-- ============================================================
+
+INSERT INTO semicolony.bot_workspace_standard (path_pattern, entry_type, level, severity, category, bot_scope, bot_ids, symlink_target, content_rules, description, fix_action, fix_template)
+VALUES
+  -- 필수 파일
+  ('SOUL.md', 'file', 'required', 'error', 'structure', 'all', '{}', NULL,
+   '{"max_lines": 120, "required_sections": ["## Identity", "## R&R", "## KB Lookup", "## Operating Procedures", "## NON-NEGOTIABLE"], "forbidden_patterns": ["U[0-9A-Z]{8,11}", "C[0-9A-Z]{8,11}"]}'::jsonb,
+   '봇 페르소나 + R&R + 행동강령', 'create_file',
+   '# $BOT_ID — SOUL\n\n## Identity\n\n> TODO\n\n## R&R\n\n> TODO\n\n## KB Lookup\n\n> kb_get/kb_search로 팀 정보 조회\n\n## Operating Procedures\n\n> TODO\n\n## NON-NEGOTIABLE\n\n1. TODO'),
+
+  ('AGENTS.md', 'symlink', 'required', 'error', 'structure', 'all', '{}',
+   '$HOME/.openclaw-shared/AGENTS.md',
+   '{"max_lines": 150, "required_patterns": ["Every Session", "KB-First"]}'::jsonb,
+   '공통 세션 운영 규칙 (심링크)', 'create_symlink', NULL),
+
+  ('USER.md', 'file', 'required', 'error', 'structure', 'all', '{}', NULL,
+   '{"max_lines": 15}'::jsonb,
+   '사용자 컨텍스트', 'create_file',
+   '# USER\n\n> TODO: $BOT_ID 사용자 정보'),
+
+  ('MEMORY.md', 'file', 'required', 'error', 'structure', 'all', '{}', NULL,
+   '{"max_lines": 30, "required_patterns": ["KB SoT|KB.*SoT|Single Source"]}'::jsonb,
+   'KB 도메인 인덱스 (main 세션만)', 'create_file',
+   '# MEMORY\n\n> KB SoT — 팀 정보는 kb_search/kb_get으로 조회'),
+
+  ('HEARTBEAT.md', 'file', 'required', 'error', 'structure', 'include', '{semiclaw}', NULL,
+   NULL,
+   '크론 작업 정의 (semiclaw 전용)', NULL, NULL),
+
+  ('.claude/settings.json', 'file', 'required', 'error', 'structure', 'all', '{}', NULL,
+   '{"required_patterns": ["semicolony-kb"]}'::jsonb,
+   'MCP 서버 설정', NULL, NULL),
+
+  -- 필수 디렉토리
+  ('.claude/', 'dir', 'required', 'error', 'structure', 'all', '{}', NULL, NULL,
+   'Claude 설정 디렉토리', 'create_dir', NULL),
+
+  ('hooks/', 'dir', 'required', 'error', 'structure', 'all', '{}', NULL, NULL,
+   'OpenClaw 훅', 'create_dir', NULL),
+
+  ('memory/', 'dir', 'required', 'error', 'structure', 'all', '{}', NULL, NULL,
+   '일일로그 디렉토리', 'create_dir', NULL),
+
+  ('skills/', 'dir', 'required', 'error', 'structure', 'all', '{}', NULL, NULL,
+   '봇 전용 스킬', 'create_dir', NULL),
+
+  -- 선택 디렉토리/파일
+  ('scripts/', 'dir', 'optional', 'warn', 'structure', 'all', '{}', NULL, NULL,
+   '유틸리티 스크립트', NULL, NULL),
+
+  ('shared/', 'dir', 'optional', 'warn', 'structure', 'all', '{}', NULL, NULL,
+   '공유 리소스 (심링크)', NULL, NULL),
+
+  ('.gh-pat', 'file', 'optional', 'warn', 'structure', 'all', '{}', NULL, NULL,
+   'GitHub PAT 파일', NULL, NULL),
+
+  ('.gitignore', 'file', 'optional', 'warn', 'structure', 'all', '{}', NULL, NULL,
+   'Git ignore', NULL, NULL),
+
+  -- 레거시 파일 (금지)
+  ('IDENTITY.md', 'file', 'forbidden', 'error', 'legacy', 'all', '{}', NULL, NULL,
+   'v1 레거시 — SOUL.md ## Identity로 대체됨', NULL, NULL),
+
+  ('TOOLS.md', 'file', 'forbidden', 'error', 'legacy', 'all', '{}', NULL, NULL,
+   'v1 레거시 — KB lookup 지시로 대체', NULL, NULL),
+
+  ('RULES.md', 'file', 'forbidden', 'error', 'legacy', 'all', '{}', NULL, NULL,
+   'v1 레거시 — SOUL.md ## NON-NEGOTIABLE로 통합', NULL, NULL),
+
+  ('CLAUDE.md', 'file', 'forbidden', 'warn', 'legacy', 'all', '{}', NULL, NULL,
+   'v1 레거시 — 프로젝트 .claude/CLAUDE.md에 이미 존재', NULL, NULL),
+
+  ('BOOTSTRAP.md', 'file', 'forbidden', 'warn', 'legacy', 'all', '{}', NULL, NULL,
+   'v1 레거시', NULL, NULL),
+
+  -- 위생 (금지)
+  ('*/.git', 'glob', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   '클론된 리포 — workspace에 git clone 금지', NULL, NULL),
+
+  ('node_modules', 'glob', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   'npm install 산출물', NULL, NULL),
+
+  ('dist/', 'dir', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   '빌드 산출물', NULL, NULL),
+
+  ('build/', 'dir', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   '빌드 산출물', NULL, NULL),
+
+  ('.next/', 'dir', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   'Next.js 빌드 산출물', NULL, NULL),
+
+  ('out/', 'dir', 'forbidden', 'error', 'hygiene', 'all', '{}', NULL, NULL,
+   '빌드 산출물', NULL, NULL),
+
+  ('*.ovpn', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   'VPN 설정 파일 — 보안', NULL, NULL),
+
+  ('*.pem', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '인증서 파일 — 보안', NULL, NULL),
+
+  ('*.key', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '비밀키 파일 — 보안', NULL, NULL),
+
+  ('credentials/', 'dir', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '인증 정보 디렉토리', NULL, NULL),
+
+  ('*.png', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '바이너리 이미지 파일', NULL, NULL),
+
+  ('*.jpg', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '바이너리 이미지 파일', NULL, NULL),
+
+  ('*.zip', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '압축 파일', NULL, NULL),
+
+  ('*.tgz', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '압축 파일', NULL, NULL),
+
+  ('temp/', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '임시 디렉토리', NULL, NULL),
+
+  ('tmp/', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '임시 디렉토리', NULL, NULL),
+
+  ('*.tmp', 'glob', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   '임시 파일', NULL, NULL),
+
+  ('go.mod', 'file', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   'Go 모듈 파일 — workspace에 불필요', NULL, NULL),
+
+  ('go.sum', 'file', 'forbidden', 'warn', 'hygiene', 'all', '{}', NULL, NULL,
+   'Go 체크섬 파일 — workspace에 불필요', NULL, NULL)
+
+ON CONFLICT (path_pattern, spec_version) DO UPDATE SET
+  entry_type     = EXCLUDED.entry_type,
+  level          = EXCLUDED.level,
+  severity       = EXCLUDED.severity,
+  category       = EXCLUDED.category,
+  bot_scope      = EXCLUDED.bot_scope,
+  bot_ids        = EXCLUDED.bot_ids,
+  symlink_target = EXCLUDED.symlink_target,
+  content_rules  = EXCLUDED.content_rules,
+  description    = EXCLUDED.description,
+  fix_action     = EXCLUDED.fix_action,
+  fix_template   = EXCLUDED.fix_template,
+  updated_at     = NOW();

package/migrations/021_drop_dead_tables.sql

@@ -0,0 +1,8 @@
+-- 021: Drop dead tables
+-- bot_kb_subscriptions: 코드 참조 0건, kb_digest since 파라미터로 대체
+-- bot_knowledge: 012에서 DROP 선언되었으나 잔존 가능
+-- kb_usage_log: 코드 참조 0건, 계획만 있고 미구현
+
+DROP TABLE IF EXISTS semicolony.bot_kb_subscriptions;
+DROP TABLE IF EXISTS semicolony.bot_knowledge;
+DROP TABLE IF EXISTS semicolony.kb_usage_log;

package/migrations/021_test_declarative.sql

@@ -0,0 +1,19 @@
+-- 021_test_declarative.sql
+-- test_suites에 rule_source 컬럼 추가 + workspace-audit을 declarative 타입으로 전환
+
+BEGIN;
+
+-- runner_path를 nullable로 변경 (declarative는 path 불필요)
+ALTER TABLE semicolony.test_suites ALTER COLUMN runner_path DROP NOT NULL;
+
+-- rule_source: declarative 러너가 규칙을 로드할 테이블명
+ALTER TABLE semicolony.test_suites ADD COLUMN IF NOT EXISTS rule_source TEXT;
+
+-- workspace-audit을 declarative로 전환
+UPDATE semicolony.test_suites
+SET runner_type = 'declarative',
+    runner_path = NULL,
+    rule_source = 'bot_workspace_standard'
+WHERE suite_id = 'workspace-audit';
+
+COMMIT;

package/migrations/022_bot_ontology_type.sql

@@ -0,0 +1,38 @@
+-- 022_bot_ontology_type.sql
+-- bot 타입을 온톨로지 + kb_type_schema에 추가하고, 봇을 도메인으로 등록
+
+BEGIN;
+
+-- 1. ontology_types에 bot 타입 추가
+INSERT INTO semicolony.ontology_types (type_key, description)
+VALUES ('bot', 'OpenClaw 봇 에이전트')
+ON CONFLICT (type_key) DO NOTHING;
+
+-- 2. bot 타입 scheme_key 정의 (KB 메타데이터 전용, 워크스페이스 파일은 bot_workspace_standard에서 관리)
+INSERT INTO semicolony.kb_type_schema (type_key, scheme_key, scheme_description, required, value_hint, sort_order) VALUES
+  ('bot', 'identity',       '봇 기본 정보 (이름, 이모지, 한 줄 설명)',    true,  'YAML: name, emoji, tagline',                 1),
+  ('bot', 'role',            'R&R — 역할 범위, 담당 업무',                true,  '마크다운: 업무 범위 테이블',                    2),
+  ('bot', 'status',          '현재 상태',                                true,  'online | offline | maintenance',              3),
+  ('bot', 'delegation',      '인계 매트릭스 — 역할 밖 요청 라우팅',       false, '마크다운: 요청유형 → 인계봇 테이블',            4),
+  ('bot', 'gateway_config',  '게이트웨이 설정 (포트, 토큰 경로)',         false, 'YAML: port, token_path, model',               5),
+  ('bot', 'cron_schedule',   '크론 작업 목록',                           false, '마크다운: 스케줄 + 설명 테이블',                6),
+  ('bot', 'slack_config',    'Slack 연동 (Bot ID, 채널)',                false, 'YAML: bot_id, channels[]',                    7)
+ON CONFLICT (type_key, scheme_key) DO UPDATE SET
+  scheme_description = EXCLUDED.scheme_description,
+  required = EXCLUDED.required,
+  value_hint = EXCLUDED.value_hint,
+  sort_order = EXCLUDED.sort_order;
+
+-- 3. 각 봇을 ontology 도메인으로 등록 (bot_status에서 동적 조회)
+INSERT INTO semicolony.ontology (domain, entity_type, description, service, schema)
+SELECT bot_id, 'bot',
+       COALESCE(name, bot_id) || ' — ' || COALESCE(role, 'Bot'),
+       bot_id,
+       '{}'::jsonb
+FROM semicolony.bot_status
+WHERE bot_id != 'shared'
+ON CONFLICT (domain) DO UPDATE SET
+  entity_type = 'bot',
+  description = EXCLUDED.description;
+
+COMMIT;

package/migrations/022_kb_schema_enforcement.sql

@@ -0,0 +1,77 @@
+-- 022_kb_schema_enforcement.sql
+-- KB 키 검증 강화: scheme_key 1뎁스 전환 + key_type 컬럼 추가
+--
+-- 변경 내용:
+--   1. key_type 컬럼 추가 (singleton | collection)
+--   2. 기존 변수 패턴({...}) scheme_key → collection으로 마킹
+--   3. scheme_key를 1뎁스(첫 세그먼트)로 축약
+--   4. 축약 후 중복 제거
+--   5. service 타입에 kpi/milestone collection 추가
+--
+-- 선행 조건: 018_type_schema.sql 적용 완료
+
+BEGIN;
+
+-- ============================================================
+-- 1. key_type 컬럼 추가
+-- ============================================================
+
+ALTER TABLE semicolony.kb_type_schema
+  ADD COLUMN IF NOT EXISTS key_type VARCHAR(20) DEFAULT 'singleton';
+
+-- ============================================================
+-- 2. 기존 데이터 key_type 설정 (변수 포함 = collection)
+-- ============================================================
+
+UPDATE semicolony.kb_type_schema
+SET key_type = 'collection'
+WHERE scheme_key LIKE '%{%';
+
+-- ============================================================
+-- 3. scheme_key를 1뎁스로 축약 (첫 번째 세그먼트만)
+-- ============================================================
+
+UPDATE semicolony.kb_type_schema
+SET scheme_key = SPLIT_PART(scheme_key, '/', 1)
+WHERE scheme_key LIKE '%/%';
+
+-- ============================================================
+-- 4. 중복 제거 (축약 후 동일 type_key+scheme_key 병합)
+-- ============================================================
+
+DELETE FROM semicolony.kb_type_schema a
+USING semicolony.kb_type_schema b
+WHERE a.id > b.id
+  AND a.type_key = b.type_key
+  AND a.scheme_key = b.scheme_key;
+
+-- 축약 후 collection으로 마킹되지 않은 행도 올바르게 설정
+-- (예: 'team' 은 원래 'team/{name}'이었으므로 collection)
+UPDATE semicolony.kb_type_schema
+SET key_type = 'collection'
+WHERE key_type = 'singleton'
+  AND scheme_key IN ('team', 'decision', 'process', 'infra', 'bot-config', 'skill', 'spec', 'memory', 'session-log');
+
+-- kpi 타입의 '{YYYY-WNN}' → collection으로 이미 변환됨, 축약 후 '{YYYY-WNN}' 자체가 첫 세그먼트
+-- 이 잔여 항목 정리 (변수 패턴이 첫 세그먼트인 경우 삭제 — collection prefix로 대체 불가)
+DELETE FROM semicolony.kb_type_schema
+WHERE scheme_key LIKE '{%';
+
+-- milestone 타입의 '{slug}' 도 동일하게 삭제
+-- (service.milestone collection으로 통합)
+
+-- ============================================================
+-- 5. service 타입에 kpi/milestone collection 추가
+-- ============================================================
+
+INSERT INTO semicolony.kb_type_schema (type_key, scheme_key, scheme_description, required, value_hint, sort_order, key_type)
+VALUES
+  ('service', 'kpi',       'KPI (current/target/주간 스냅샷)', false, 'kpi/current, kpi/target, kpi/2026-W12', 10, 'collection'),
+  ('service', 'milestone', '마일스톤 항목',                    false, 'milestone/blog-auto-gen',                11, 'collection')
+ON CONFLICT (type_key, scheme_key) DO UPDATE SET
+  key_type = 'collection',
+  scheme_description = EXCLUDED.scheme_description,
+  value_hint = EXCLUDED.value_hint,
+  sort_order = EXCLUDED.sort_order;
+
+COMMIT;

package/migrations/023_decision_key_cleanup.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env npx tsx
+/**
+ * 023_decision_key_cleanup.ts
+ *
+ * ~100건의 비표준 decision 키를 표준 형식(decision/{date}/{slug})으로 변환.
+ *
+ * 변환 규칙:
+ * - 이미 decision/{YYYY-MM-DD}/{slug} 형식이면 스킵
+ * - content/metadata에서 날짜 추출 시도
+ * - 날짜 추출 불가 시 updated_at에서 추출
+ * - 키 충돌 시 suffix 추가 (-2, -3, ...)
+ *
+ * 사용법:
+ *   npx tsx packages/cli/migrations/023_decision_key_cleanup.ts [--dry-run]
+ */
+
+import pg from "pg";
+
+const DATABASE_URL = process.env.DATABASE_URL;
+if (!DATABASE_URL) {
+  console.error("DATABASE_URL 환경변수가 필요합니다");
+  process.exit(1);
+}
+
+const DRY_RUN = process.argv.includes("--dry-run");
+
+const STANDARD_PATTERN = /^decision\/\d{4}-\d{2}-\d{2}\/.+$/;
+const DATE_PATTERN = /(\d{4}-\d{2}-\d{2})/;
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[가-힣]+/g, (match) => match) // keep Korean as-is
+    .replace(/[^a-z0-9가-힣\-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .substring(0, 80);
+}
+
+function extractDate(keySlug: string, content: string, metadata: Record<string, unknown> | null): string | null {
+  // Try metadata first
+  if (metadata) {
+    for (const k of ["date", "decided_at", "created_at", "timestamp"]) {
+      const val = metadata[k];
+      if (typeof val === "string") {
+        const match = val.match(DATE_PATTERN);
+        if (match) return match[1];
+      }
+    }
+  }
+
+  // Try key slug (e.g., "메모리 구조 개편 (2026-02-17)")
+  const keyMatch = keySlug.match(DATE_PATTERN);
+  if (keyMatch) return keyMatch[1];
+
+  // Try content
+  const contentMatch = content.match(DATE_PATTERN);
+  if (contentMatch) return contentMatch[1];
+
+  return null;
+}
+
+async function main() {
+  const pool = new pg.Pool({ connectionString: DATABASE_URL });
+
+  try {
+    // Find all decision keys in semicolon domain
+    const result = await pool.query(`
+      SELECT domain, key, content, metadata, updated_at::text
+      FROM semicolony.knowledge_base
+      WHERE domain = 'semicolon' AND key LIKE 'decision/%'
+      ORDER BY key
+    `);
+
+    const rows = result.rows;
+    console.log(`총 decision 엔트리: ${rows.length}건`);
+
+    const nonStandard = rows.filter((r) => !STANDARD_PATTERN.test(r.key));
+    console.log(`비표준 키: ${nonStandard.length}건`);
+
+    if (nonStandard.length === 0) {
+      console.log("정리할 항목 없음");
+      return;
+    }
+
+    // Collect existing keys to avoid conflicts
+    const existingKeys = new Set(rows.map((r) => r.key));
+
+    let updated = 0;
+    let skipped = 0;
+
+    for (const row of nonStandard) {
+      const oldKey = row.key;
+      const parts = oldKey.split("/");
+
+      // Extract the "slug" portion (everything after "decision/")
+      const rawSlug = parts.slice(1).join("/");
+
+      // Extract date
+      let date = extractDate(rawSlug, row.content, row.metadata);
+      if (!date && row.updated_at) {
+        date = row.updated_at.substring(0, 10);
+      }
+      if (!date) {
+        date = "unknown";
+      }
+
+      // If it already has a date as second segment, use that
+      if (parts.length >= 3 && DATE_PATTERN.test(parts[1])) {
+        // Already has date but may have extra depth — keep as is
+        console.log(`  스킵 (이미 날짜 포함): ${oldKey}`);
+        skipped++;
+        continue;
+      }
+
+      const slug = slugify(rawSlug);
+      let newKey = `decision/${date}/${slug}`;
+
+      // Dedup: if conflict, add suffix
+      if (existingKeys.has(newKey) && newKey !== oldKey) {
+        let suffix = 2;
+        while (existingKeys.has(`${newKey}-${suffix}`)) suffix++;
+        newKey = `${newKey}-${suffix}`;
+      }
+
+      if (newKey === oldKey) {
+        skipped++;
+        continue;
+      }
+
+      console.log(`  ${oldKey} → ${newKey}`);
+
+      if (!DRY_RUN) {
+        await pool.query(
+          `UPDATE semicolony.knowledge_base SET key = $1 WHERE domain = $2 AND key = $3`,
+          [newKey, row.domain, oldKey]
+        );
+      }
+
+      existingKeys.delete(oldKey);
+      existingKeys.add(newKey);
+      updated++;
+    }
+
+    console.log(`\n결과: ${updated}건 변환, ${skipped}건 스킵${DRY_RUN ? " (dry-run)" : ""}`);
+  } finally {
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  console.error("에러:", err);
+  process.exit(1);
+});

package/migrations/024_embedding_backfill.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env npx tsx
+/**
+ * 024_embedding_backfill.ts
+ *
+ * 임베딩 없는 KB 엔트리에 벡터 일괄 생성.
+ * OpenAI batch API를 사용하여 효율적으로 처리.
+ *
+ * 사용법:
+ *   npx tsx packages/cli/migrations/024_embedding_backfill.ts [--dry-run] [--batch-size=20]
+ */
+
+import pg from "pg";
+
+const DATABASE_URL = process.env.DATABASE_URL;
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+
+if (!DATABASE_URL) {
+  console.error("DATABASE_URL 환경변수가 필요합니다");
+  process.exit(1);
+}
+if (!OPENAI_API_KEY) {
+  console.error("OPENAI_API_KEY 환경변수가 필요합니다");
+  process.exit(1);
+}
+
+const DRY_RUN = process.argv.includes("--dry-run");
+const BATCH_SIZE = parseInt(
+  process.argv.find((a) => a.startsWith("--batch-size="))?.split("=")[1] || "20",
+  10
+);
+
+const EMBEDDING_MODEL = "text-embedding-3-small";
+const EMBEDDING_DIMENSIONS = 1024;
+
+async function generateEmbeddings(texts: string[]): Promise<(number[] | null)[]> {
+  const response = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${OPENAI_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model: EMBEDDING_MODEL,
+      input: texts.map((t) => t.substring(0, 8000)),
+      dimensions: EMBEDDING_DIMENSIONS,
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    console.error(`API 에러: ${response.status} ${err}`);
+    return texts.map(() => null);
+  }
+
+  const data = (await response.json()) as { data?: { embedding: number[] }[] };
+  return data.data?.map((d) => d.embedding) || texts.map(() => null);
+}
+
+async function main() {
+  const pool = new pg.Pool({ connectionString: DATABASE_URL });
+
+  try {
+    const result = await pool.query(`
+      SELECT domain, key, content
+      FROM semicolony.knowledge_base
+      WHERE embedding IS NULL
+      ORDER BY domain, key
+    `);
+
+    const rows = result.rows;
+    console.log(`임베딩 없는 엔트리: ${rows.length}건`);
+
+    if (rows.length === 0) {
+      console.log("처리할 항목 없음");
+      return;
+    }
+
+    if (DRY_RUN) {
+      console.log("(dry-run) 실제 처리하지 않음");
+      for (const row of rows) {
+        console.log(`  ${row.domain}/${row.key}`);
+      }
+      return;
+    }
+
+    let processed = 0;
+    let failed = 0;
+
+    for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+      const batch = rows.slice(i, i + BATCH_SIZE);
+      const texts = batch.map((r) => `${r.key}: ${r.content}`);
+
+      console.log(`배치 ${Math.floor(i / BATCH_SIZE) + 1}/${Math.ceil(rows.length / BATCH_SIZE)} (${batch.length}건)...`);
+
+      const embeddings = await generateEmbeddings(texts);
+
+      for (let j = 0; j < batch.length; j++) {
+        const row = batch[j];
+        const embedding = embeddings[j];
+
+        if (!embedding) {
+          console.error(`  실패: ${row.domain}/${row.key}`);
+          failed++;
+          continue;
+        }
+
+        const embeddingStr = `[${embedding.join(",")}]`;
+        await pool.query(
+          `UPDATE semicolony.knowledge_base SET embedding = $1::vector WHERE domain = $2 AND key = $3`,
+          [embeddingStr, row.domain, row.key]
+        );
+
+        processed++;
+      }
+
+      // Rate limiting: 짧은 대기
+      if (i + BATCH_SIZE < rows.length) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    }
+
+    console.log(`\n결과: ${processed}건 생성, ${failed}건 실패`);
+
+    // Verify
+    const remaining = await pool.query(
+      "SELECT COUNT(*)::int as cnt FROM semicolony.knowledge_base WHERE embedding IS NULL"
+    );
+    console.log(`남은 NULL 임베딩: ${remaining.rows[0].cnt}건`);
+  } finally {
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  console.error("에러:", err);
+  process.exit(1);
+});

package/migrations/025_kb_flat_keys.sql

@@ -0,0 +1,33 @@
+-- 025: KB Flat Key Migration
+-- key + sub_key 분리: key는 scheme_key exact match, sub_key는 계층 식별자
+BEGIN;
+
+-- 1. sub_key 컬럼 추가
+ALTER TABLE semicolony.knowledge_base
+  ADD COLUMN IF NOT EXISTS sub_key VARCHAR(255) NOT NULL DEFAULT '';
+
+-- 2. 기존 Unique constraint 제거 (UPDATE 전에 제거해야 충돌 없음)
+ALTER TABLE semicolony.knowledge_base
+  DROP CONSTRAINT IF EXISTS knowledge_base_domain_key_key;
+
+-- 3. 기존 collection 키 분리 (첫 '/' 기준)
+UPDATE semicolony.knowledge_base
+SET sub_key = SUBSTRING(key FROM POSITION('/' IN key) + 1),
+    key     = SPLIT_PART(key, '/', 1)
+WHERE key LIKE '%/%';
+
+-- 4. 새 Unique constraint 추가
+ALTER TABLE semicolony.knowledge_base
+  ADD CONSTRAINT knowledge_base_domain_key_subkey_key
+    UNIQUE (domain, key, sub_key);
+
+-- 5. 조회 성능 인덱스
+CREATE INDEX IF NOT EXISTS idx_kb_domain_key ON semicolony.knowledge_base (domain, key);
+
+-- 6. 테스트 파이프라인 등록
+INSERT INTO semicolony.test_suites (suite_id, name, layer, runner_type, runner_path, enabled)
+VALUES ('025-flat-keys', '025 KB Flat Key Migration', 'integration', 'tsx',
+        'packages/mcp-kb/test-025-flat-keys.ts', true)
+ON CONFLICT (suite_id) DO NOTHING;
+
+COMMIT;

package/migrations/026_drop_session_log.sql

@@ -0,0 +1,19 @@
+BEGIN;
+
+-- 1. kb_type_schema에서 session-log 행 제거
+DELETE FROM semicolony.kb_type_schema
+WHERE type_key = 'organization' AND scheme_key = 'session-log';
+
+-- 2. ontology_types에서 session-log 타입 제거 (있다면)
+DELETE FROM semicolony.ontology_types WHERE type_key = 'session-log';
+
+-- 3. 기존 session-log 데이터 정리
+DELETE FROM semicolony.knowledge_base
+WHERE domain = 'semicolon' AND key = 'session-log';
+
+-- 4. semicolon 온톨로지 description에서 session-log 참조 제거
+UPDATE semicolony.ontology
+SET description = REPLACE(description, '/session-log', '')
+WHERE domain = 'semicolon' AND description LIKE '%session-log%';
+
+COMMIT;