@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/docs/rules/code-quality-redlines.md

@@ -1,321 +1,35 @@
 # 代码质量红线
 
-> 代码生成绝对禁止项清单与 Enforcement 策略
+> 目标：用最少的文字描述“什么会被挡住、怎么检查、失败后怎么修”。
 
-## 1. 红线总则
+## 红线表
 
-以下代码模式在 CodeMap 仓库中被视为**硬性阻断项**。AI 生成代码时必须主动避免，否则必须在可信度自评中标记风险。
+| 红线 | 命令 | 阈值/级别 | 失败后果 | 恢复方式 |
+|---|---|---|---|---|
+| 敏感信息硬编码 | `grep -rn "password.*=.*['\"]" src/ --include="*.ts"` | 生产代码出现明文凭证 | 阻断提交/审查 | 改为 `process.env` + 类型检查 |
+| 非边界文件使用 `any` | `npm run typecheck` / `npx eslint src --rule '@typescript-eslint/no-explicit-any: error'` | 非测试/边界文件禁止 | 阻断 | 改为具体类型或 `unknown` + 守卫 |
+| 函数超过 50 行 | `npx eslint src --rule 'max-lines-per-function: [error, { max: 50, skipBlankLines: true, skipComments: true }]'` | 单函数 > 50 行 | 阻断 | 拆成小函数，保持单一职责 |
+| 未处理 Promise | `npx eslint src --rule '@typescript-eslint/no-floating-promises: error'` | 无 `await` / `.catch()` | 阻断 | 显式 `await` 或补错误处理 |
+| 遗留 `console.log` | `npx eslint src --rule 'no-console: [error, { allow: [\"error\"] }]'` | `src/cli/runtime-logger.ts` 外禁止 | 阻断 | 换成 `runtime-logger` |
+| 未使用 import / 变量 | `tsc --noUnusedLocals --noEmit` / `npm run lint` | 任意未使用符号 | 阻断 | 删除无用 import / 变量 |
+| TS 源文件缺少 `[META]` / `[WHY]` | `.githooks/pre-commit` | 非测试 `.ts` 源文件必须有文件头 | 阻断 | 补文件头注释 |
 
-**红线判定标准**：
-- 可能导致安全漏洞
-- 严重降低代码可维护性
-- 破坏类型安全保证
-- 违反架构分层原则
+## 默认执行顺序
 
-## 2. 红线清单
+1. `npm run typecheck`
+2. `npm run lint`
+3. 变更涉及行为时再补 `npm test`
 
-### 2.1 敏感信息硬编码
+## 技术债例外
 
-**禁止模式**：
-```typescript
-// ❌ 绝对禁止
-const API_KEY = "sk-abc123xyz";
-const password = "admin123";
-const secret = "my-jwt-secret";
-```
+- 只允许在边界场景临时记录 `TODO-DEBT`。
+- 例外必须写清：原因、风险、偿还计划。
 
-**合规模式**：
-```typescript
-// ✅ 使用环境变量
-const API_KEY = process.env.OPENAI_API_KEY;
-if (!API_KEY) {
-  throw new Error('OPENAI_API_KEY is required');
-}
-```
+## 最小提交前清单
 
-**检测方式**：
-```bash
-# 正则检测敏感信息字面量
-grep -rn "password.*=.*['\"]" src/ --include="*.ts"
-grep -rn "secret.*=.*['\"]" src/ --include="*.ts"
-grep -rn "api_key.*=.*['\"]" src/ --include="*.ts"
-```
-
-**阻断阈值**：生产代码中出现任何明文凭证
-
-### 2.2 `any` 类型使用
-
-**禁止模式**：
-```typescript
-// ❌ 非边界文件禁止使用 any
-function processData(data: any): any {
-  return data.value;
-}
-```
-
-**合规模式**：
-```typescript
-// ✅ 使用具体类型或 unknown + 类型守卫
-interface DataPayload {
-  value: string;
-}
-
-function processData(data: unknown): string {
-  if (typeof data === 'object' && data !== null && 'value' in data) {
-    return (data as DataPayload).value;
-  }
-  throw new Error('Invalid data format');
-}
-```
-
-**例外情况**（需标记 TODO-DEBT）：
-- 第三方库无类型定义时的临时处理
-- 与遗留系统集成的边界
-
-**检测方式**：
-```bash
-# TypeScript 编译器检查
-npx tsc --noImplicitAny --noEmit
-
-# ESLint 检查
-npx eslint src --rule '@typescript-eslint/no-explicit-any: error'
-```
-
-**阻断阈值**：非边界文件出现 `any` 类型
-
-### 2.3 函数超过 50 行
-
-**计算方式**：函数体实际代码行数（不含空行、注释、类型定义）
-
-**禁止模式**：
-```typescript
-// ❌ 超过 50 行的函数
-function complexFunction(data: Data) {
-  // 行 1
-  // 行 2
-  // ... 50+ 行
-  // 行 51
-  // 行 52
-}
-```
-
-**合规模式**：
-```typescript
-// ✅ 拆分为子函数
-function complexFunction(data: Data) {
-  const validated = validateData(data);
-  const transformed = transformData(validated);
-  return persistData(transformed);
-}
-
-function validateData(data: Data): ValidatedData { ... }
-function transformData(data: ValidatedData): TransformedData { ... }
-function persistData(data: TransformedData): Result { ... }
-```
-
-**检测方式**：
-```bash
-# 使用 ESLint 的 max-lines-per-function 规则
-npx eslint src --rule 'max-lines-per-function: [error, { max: 50, skipBlankLines: true, skipComments: true }]'
-```
-
-**阻断阈值**：单函数超过 50 行代码
-
-### 2.4 未处理 Promise
-
-**禁止模式**：
-```typescript
-// ❌ 未处理的异步操作
-fetchUserData(userId); // 没有 await 或 .catch()
-database.query(sql);   // 没有错误处理
-```
-
-**合规模式**：
-```typescript
-// ✅ 正确处理异步操作
-try {
-  const user = await fetchUserData(userId);
-} catch (error) {
-  logger.error('Failed to fetch user', error);
-  throw new UserFetchError(userId);
-}
-
-// 或显式忽略
-void fetchUserData(userId).catch(() => {}); // 有意的显式忽略
-```
-
-**检测方式**：
-```bash
-# ESLint 检查
-npx eslint src --rule '@typescript-eslint/no-floating-promises: error'
-```
-
-**阻断阈值**：未使用 `await` 或未附加错误处理的 Promise
-
-### 2.5 `console.log` 遗留代码
-
-**禁止模式**：
-```typescript
-// ❌ 生产代码中的调试语句
-console.log('Debug:', data);
-console.warn('Warning');
-```
-
-**合规模式**：
-```typescript
-// ✅ 使用 runtime-logger
-import { runtimeLogger } from '../cli/runtime-logger';
-runtimeLogger.debug('Debug:', data);
-runtimeLogger.warn('Warning');
-```
-
-**例外情况**：
-- `src/cli/runtime-logger.ts` 本身
-- 临时调试代码（提交前必须删除）
-
-**检测方式**：
-```bash
-# ESLint 检查
-npx eslint src --rule 'no-console: [error, { allow: ["error"] }]'
-```
-
-**阻断阈值**：非 logger 模块出现 `console.log`
-
-### 2.6 未使用 Import
-
-**禁止模式**：
-```typescript
-// ❌ 导入但未使用
-import { unusedFunction } from './utils';
-import type { UnusedType } from './types';
-
-export function doSomething() {
-  // 未使用上面的导入
-}
-```
-
-**合规模式**：
-```typescript
-// ✅ 删除未使用的导入
-export function doSomething() {
-  // 干净的代码
-}
-```
-
-**检测方式**：
-```bash
-# TypeScript 检查
-npx tsc --noUnusedLocals --noEmit
-
-# ESLint 检查
-npx eslint src --rule '@typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: "^_" }]'
-```
-
-**阻断阈值**：存在未使用的 import 或变量
-
-### 2.7 缺少文件头注释
-
-**禁止模式**：
-```typescript
-// ❌ 缺少 META 和 WHY 注释
-export function analyze() { ... }
-```
-
-**合规模式**：
-```typescript
-// [META] since:2026-03 | owner:team | stable:false
-// [WHY] 分析器主入口，负责协调解析和生成流程
-export function analyze() { ... }
-```
-
-**检测方式**：
-```bash
-# pre-commit hook 自动检查
-# 或手动检查
-grep -L "\[META\]" src/**/*.ts | grep -v ".test.ts" | grep -v ".d.ts"
-```
-
-**阻断阈值**：TS 源文件缺少 `[META]` 或 `[WHY]` 注释
-
-## 3. 检测自动化
-
-### 3.1 集成到 CI
-
-```yaml
-# .github/workflows/ci-gateway.yml
-- name: Check code quality redlines
-  run: |
-    npx eslint src \
-      --rule '@typescript-eslint/no-explicit-any: error' \
-      --rule '@typescript-eslint/no-floating-promises: error' \
-      --rule 'no-console: [error, { allow: ["error"] }]'
-```
-
-### 3.2 本地检查脚本
-
-```json
-// package.json
-{
-  "scripts": {
-    "check:redlines": "npm run check:types && npm run check:lint",
-    "check:types": "tsc --noImplicitAny --noUnusedLocals --noEmit",
-    "check:lint": "eslint src --ext .ts"
-  }
-}
-```
-
-## 4. 自动修复策略
-
-| 红线 | 自动修复 | 修复命令 |
-|------|---------|---------|
-| `any` 类型 | 部分可行 | 使用类型推导工具（如 TS 语言服务） |
-| 未使用 import | 完全可行 | `eslint --fix` |
-| `console.log` | 部分可行 | 替换为 logger 引用（需人工确认） |
-| 函数长度 | 不可行 | 需人工重构 |
-| 未处理 Promise | 部分可行 | 添加 `await` 或 `.catch()`（需人工确认逻辑） |
-| 敏感信息 | 不可行 | 需人工替换为环境变量 |
-| 缺少文件头 | 部分可行 | 使用代码片段模板 |
-
-## 5. 例外处理
-
-### 5.1 技术债务标记
-
-若因特殊原因必须违反红线，必须标记为技术债务：
-
-```typescript
-// TODO-DEBT [L1] [日期:2026-03-17] [作者:AI] [原因:第三方库无类型定义]
-// 问题：被迫使用 any 类型处理无类型的第三方库
-// 风险：丢失类型安全
-// 偿还计划：提交 PR 给第三方库添加类型定义，或使用 @types 包
-function handleLegacyAPI(response: any): any {
-  return response.data;
-}
-```
-
-### 5.2 边界文件例外
-
-以下文件类型允许适当的灵活性：
-- 测试文件（`.test.ts`）
-- 类型声明文件（`.d.ts`）
-- 配置文件（如 `vitest.config.ts`）
-- 脚本文件（`scripts/` 目录）
-
-## 6. 验收检查清单
-
-提交代码前检查：
-
-- [ ] 无敏感信息硬编码
-- [ ] 无 `any` 类型（或已标记 TODO-DEBT）
-- [ ] 函数长度 <= 50 行（或已拆分为子函数）
-- [ ] 所有 Promise 都有错误处理
-- [ ] 无 `console.log` 遗留
-- [ ] 无未使用的 import
-- [ ] TS 源文件有 `[META]` 和 `[WHY]` 注释
-- [ ] `npm run check:redlines` 通过
-
-## 7. 相关文档
-
-- `AGENTS.md` - 任务分级与可信度自评
-- `CLAUDE.md` - 执行清单与验收标准
-- `docs/rules/engineering-with-codex-openai.md` - 工程规则
-- `docs/rules/architecture-guardrails.md` - 架构护栏
+- [ ] 无明文凭证
+- [ ] 无多余 `any`
+- [ ] 无漂浮 Promise
+- [ ] 无遗留 `console.log`
+- [ ] 无未使用 import
+- [ ] `.ts` 文件头完整

package/docs/rules/engineering-with-codex-openai.md

@@ -45,18 +45,28 @@
 - 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
 - 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
 - 修改 `design`、`analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+  - `node dist/cli/index.js generate --symbol-level` 只在显式开启时新增 symbol-level `call` 依赖；默认 `generate` 路径不得被悄悄改变；
   - `node dist/cli/index.js design validate mycodemap.design.md --json` 的成功/失败路径符合文档；
   - `node dist/cli/index.js design map mycodemap.design.md --json` 的 success/blocker 路径、`candidates` / `unknowns` / `diagnostics` 与文档一致；
   - `node dist/cli/index.js design handoff mycodemap.design.md --json` 的 `readyForExecution` / `approvals` / `assumptions` / `openQuestions` 与文档一致；
   - `node dist/cli/index.js design verify mycodemap.design.md --json` 的 `checklist` / `drift` / `diagnostics` / `readyForExecution` 与文档一致，并保持 review-needed / blocker 分离语义；
+  - `node dist/cli/index.js check --contract mycodemap.design.md --against src` 的 JSON / `--human` / exit code 语义与文档一致；
+  - `node dist/cli/index.js mcp install` 必须显式标记 experimental，且只更新当前仓库 `.mcp.json`；
+  - `node dist/cli/index.js mcp start` 必须保持 `stdout` 协议纯净，不能混入欢迎信息、迁移提示或 runtime log；
+  - `codemap_query` / `codemap_impact` 必须返回显式 `graph_status` / `error.code`，并覆盖 `GRAPH_NOT_FOUND`、`SYMBOL_NOT_FOUND`、`AMBIGUOUS_EDGE`；
   - `node dist/cli/index.js analyze --help` 与文档示例一致；
   - `find` / `read` / `link` / `show` 中受影响的 public intent 可以在当前仓库运行；
+  - `analyze -i find -k <keyword> --json --structured` 的 stdout JSON 必须包含 `diagnostics.status`，可区分 true zero-hit、`partialFailure` 与 `failure`；
+  - `complexity -f <file> --json` 必须只返回目标 `file`，不得返回全项目 `modules`；
+  - `ci assess-risk --json` 必须输出 `status: passed | failed | skipped`，且 failed path 保持 stdout JSON 可解析；
+  - `workflow start "<task>" --json` 必须输出纯 JSON，但 workflow 边界仍限于 `find → read → link → show` analysis-only 阶段；
   - 若文档保留 legacy alias 说明，真实输出仍会返回 `warnings[]`；
   - 若涉及机器输出，`--json` 与 `--structured --json` 仍保持纯 JSON 契约。
 - 修改 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/OUTPUT.md`、`ARCHITECTURE.md` 这类入口文档时，必须明确区分“目标产品基线”和“当前 CLI 现实”，尤其是 `Server Layer` / `mycodemap server` 的命名边界。
 - 修改 `docs/product-specs/*` 现行规格时，必须同步 `docs/product-specs/README.md` 与 `scripts/validate-docs.js` 的高信号断言，避免规格正文和目录索引分叉；`docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md` 也属于这一约束。
 - 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
 - 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`；该命令会同时执行 docs guardrail 与 `sync-analyze-docs.js --check`。
+- 若改动涉及 repo-root contract 或 CI gate，确认 `.github/workflows/ci-gateway.yml` 中的 `node dist/cli/index.js check --contract mycodemap.design.md --against src` 仍保持 PR 显式 base / push full scan 语义。
 - `ci check-branch --allow` 支持 `*` 通配；在 CI / PR 环境中，分支识别会回退到 `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`。
 - `generate`、`analyze` 与 `ci check-headers -d` 共享 `.gitignore` 感知文件发现模块；没有 `.gitignore` 时回退到统一默认 `exclude`。
 - 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
@@ -65,12 +75,15 @@
 
 - 本地护栏：
   - `.githooks/pre-commit` 会执行变更相关测试、文件头检查，并尝试生成 AI feed。
+  - `.githooks/pre-commit` 还会读取 `.claude/rule-system.config.json` 的 `hard_gate.mode`：`report-only` 时执行 `python3 scripts/validate-rules.py code --report-only` 并继续；`enforce` 时执行 `python3 scripts/validate-rules.py code`，其中 `1/4` 阻断、`2/3` 只告警。
   - 当变更涉及 README、`docs/`、CLI 入口、测试配置或 CI 配置时，`.githooks/pre-commit` 还会执行 `npm run docs:check`。
-  - `.githooks/commit-msg` 会校验 `[TAG] scope: message` 格式与单次 commit 文件数量。
+  - `.githooks/commit-msg` 只校验 `[TAG] scope: message` 格式；单次 commit 文件数量限制只保留在 `.githooks/pre-commit`。
 - 服务端护栏：
+  - `.github/workflows/ci-gateway.yml` 包含固定命名的 `Rule validation backstop` step；即使本地使用 `git commit --no-verify` 绕过 hooks，CI 仍会运行 `python3 scripts/validate-rules.py code`，并仅在退出码 `1` 或 `4` 时 fail，`2/3` 只输出 warn-only / notice-only。
   - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，并通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`（含 docs guardrail + analyze generated block）、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
   - `check-working-tree`、`check-branch`、`check-scripts` 作为共享发布前 gate checks，由本地 `ci` 命令提供，`ship` 的 CHECK 阶段直接复用它们。
   - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
+- 禁止依赖 `git commit --no-verify` 作为解决方案；它只能跳过本地 hooks，不能绕过 CI 中的 `Rule validation backstop`。
 - 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
 
 ## 6. 代码生成红线详细规范（Harness 规范）

package/docs/rules/pre-release-checklist.md

@@ -78,6 +78,7 @@
 - 所有文件版本号必须完全一致
 - 必须符合语义化版本规范 (`x.x.x`)
 - 预发布版本可包含后缀 (`0.2.0-beta.1`)
+- 预发布版本发布到 npm 时必须显式传 dist-tag（例如 `0.2.0-beta.1 -> --tag beta`）
 
 **版本同步清单**:
 
@@ -202,8 +203,8 @@ git push origin main --tags
      - Workflow Name: `publish.yml`
 
 2. **GitHub Secrets 检查**:
-   - [ ] **不应设置** `NPM_TOKEN` secret
-   - [ ] 如果需要 Token 方式，使用 `NPM_TOKEN` 并确保是 **Automation** 类型
+   - [ ] 默认可不设置 `NPM_TOKEN`，优先走 OIDC Trusted Publishing
+   - [ ] 如果需要 token fallback，使用 `NPM_TOKEN` 并确保是 **Automation** 类型
 
 3. **Workflow 权限配置**:
    ```yaml
@@ -214,9 +215,13 @@ git push origin main --tags
 
 4. **发布命令**:
    ```yaml
-   # 正确：使用 OIDC
+   # 正确：stable 版本发布到 latest
    - name: Publish to NPM
-     run: npm publish --access public --provenance
+     run: npm publish --access public --tag latest
+
+   # 正确：prerelease 版本显式发布到 preid 对应 tag
+   - name: Publish to NPM
+     run: npm publish --access public --tag beta
    
    # 错误：设置 NODE_AUTH_TOKEN 会干扰 OIDC
    # env:

package/docs/rules/validation.md

@@ -1,64 +1,115 @@
 # 验证规则
 
+> 原则：先跑最相关检查，再扩大范围；没有验证，不得声称“已解决”。
+
 ## 最小验证顺序
 
-1. 先验证与你改动最相关的命令、测试或模块。
-2. 若改动影响 agent 路由、CLI 示例、规则文档或测试事实，先执行 `npm run docs:check`。
-3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`；该命令会串联 docs guardrail 与 analyze generated block 校验。
-4. 若改动涉及 `design validate` / `design map` / `design handoff` / `design verify` 链路，确认 README、AI 文档、`docs/rules/*` 与 `scripts/validate-docs.js` 同步到同一条链：`design validate → design map → design handoff → design verify`，并显式区分 review-needed 与 blocker 退出语义。
-5. 若改动涉及 `analyze` canonical 示例、选项表或 `AI_GUIDE.md` 速查模板，优先用 `node scripts/sync-analyze-docs.js --check` 直接定位 generated block 漂移。
-6. 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
-7. 若改动涉及 `docs/product-specs/*` 的现行规格，确认 `docs/product-specs/README.md`、相关规格文档与 `scripts/validate-docs.js` 同步；当前 docs guardrail 会显式校验 MVP3 三份架构规格的 shipped baseline 表述。
-8. 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
-9. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
-10. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
+| 场景 | 先跑什么 | 为什么 |
+|---|---|---|
+| 改 rules / CLAUDE / README / AI 文档 / 测试事实 | `npm run docs:check` | 先挡住文档漂移 |
+| 改 repo-local 规则控制脚本或 hook 路由 | `python3 scripts/validate-rules.py code --report-only` | 先看 contract，不先硬阻断 |
+| 改 CLI 文档入口或统一 guardrail | `node dist/cli/index.js ci check-docs-sync` | 同时验证 docs guardrail 与 analyze generated block |
+| 改实现代码 | `npm run typecheck` → `npm run lint` → `npm test` | 从最小相关验证扩到基础回归 |
+| 改发布/打包边界 | `npm run docs:check:pre-release` → `npm run build` → `npm run validate-pack` | 先锁版本/发布契约，再确认 shipped artifact 仍成立 |
 
-## CI Gateway 验证流程
+## Repo-local rule validator
 
-CI Gateway 已集成以下自动检查（按执行顺序）：
+### `validate-rules.py` exit-code 表
 
-1. `npm run docs:check` - 文档护栏检查
-2. `npm run typecheck` - TypeScript 类型检查
-3. `npm run lint` - ESLint 代码质量检查（渐进式规则，0 error 通过）
-4. `npm test` - 单元测试
-5. `npm run build` - 构建验证
-6. CLI 相关检查（当前 CI Gateway 直接执行 `check-docs-sync`、commit 格式、文件头、risk、output contract；`ship` 的本地 CHECK 阶段复用 `check-working-tree`、`check-branch`、`check-scripts`）
+| 命令 | 退出码 | 含义 | 默认动作 |
+|---|---:|---|---|
+| `python3 scripts/validate-rules.py code --report-only` | `0` | pass / report-only | 只报告，不阻断 |
+| `python3 scripts/validate-rules.py code` | `1` | `P0` | blocker |
+| `python3 scripts/validate-rules.py code` | `2` | `P1` | warn-only |
+| `python3 scripts/validate-rules.py code` | `3` | `P2` | notice-only |
+| `python3 scripts/validate-rules.py code` | `4` | `unavailable` | 依赖缺失，必须显式处理 |
 
-> 当前 `check-docs-sync` 会串联 docs guardrail 与 analyze generated block 校验。
+### 当前默认值
 
-## 强约束
+- `.claude/rule-system.config.json` 默认开启 `enabled: true` 与 `route_by_edit_path: true`。
+- `soft_gate.change_analyzer` 默认开启；`hard_gate.mode` 默认是 `report-only`。
+- 本阶段默认 contract 是“先报告、再决定是否强阻断”，不要把 report-only 误写成 enforce。
 
-- 没有验证，不得声称“已解决”。
-- 失败时优先修根因，不绕过护栏。
-- 涉及 CI / hooks / 输出契约时，必须给出失败场景与修复验证证据。
-- 严禁使用 `--no-verify`、禁用 hooks、删除检查项规避失败。
+## CI Gateway 真实顺序
+
+当前 CI Gateway 直接执行 `check-docs-sync`、commit 格式、文件头、risk、output contract；`ship` 的本地 CHECK 阶段复用 `check-working-tree`、`check-branch`、`check-scripts`。
+
+| 顺序 | 命令 | 说明 |
+|---|---|---|
+| 1 | `npm run docs:check` | 文档护栏 |
+| 2 | `npm run typecheck` | 类型检查 |
+| 3 | `npm run lint` | lint |
+| 4 | `npm test` | 单元测试 |
+| 5 | `npm run build` | 构建验证 |
+| 6 | `node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10` | 设计 contract 校准；`changed files <= 10` 才可能进入 hard gate |
+| 7 | `node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github` | PR 注解与 contract gate |
+| 8 | `node dist/cli/index.js ci check-docs-sync` | 统一 docs/AI guardrail |
+| 9 | `node dist/cli/index.js ci assess-risk --threshold=0.7` | 风险评估 |
+
+> PR 超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时，workflow 必须明确标为 `warn-only / fallback`。
+
+## 需要特别补跑的场景
+
+- 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
+- 若改动涉及 `check` / `ci assess-risk` / `history` / `analyze --include-git-history` 的统一 risk truth，至少补跑 `node dist/cli/index.js history --symbol createCheckCommand`、`node scripts/report-high-risk-files.mjs --top 3`、`npm run build`。
+- 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
+
+## Design / Contract gate 速记
+
+- 当前 canonical 设计链保持为 `design validate` / `design map` / `design handoff` / `design verify`，不要把 `workflow`、CI 或 ship 步骤混写进这条产品契约链。
+- 需要验证完整链路时，直接运行 `design validate → design map → design handoff → design verify`。
+- 常用命令：
+  - `node dist/cli/index.js design validate mycodemap.design.md --json`
+  - `node dist/cli/index.js design map mycodemap.design.md --json`
+  - `node dist/cli/index.js design handoff mycodemap.design.md --json`
+  - `node dist/cli/index.js design verify mycodemap.design.md --json`
+  - `node dist/cli/index.js check --contract mycodemap.design.md --against src`
+  - 裸 contract gate 片段必须保持为 `check --contract mycodemap.design.md --against src`
+  - PR 路径必须显式使用 `github.event.pull_request.base.sha`
+- `review-needed 与 blocker 退出语义` 必须分开写；`review-needed` 不是 blocker。
 
 ## 典型失败模式
 
-- 入口文档改成 AI-first，但 `scripts/validate-docs.js` 仍检查旧措辞 → `npm run docs:check` 失败。
-- 把 `Server Layer` 和公共 `mycodemap server` 命令混写成同一件事 → 架构文档与命令文档发生边界漂移。
-- 手改 `README.md`、`docs/ai-guide/COMMANDS.md` 或 `AI_GUIDE.md` 的 `analyze` canonical 代码块 / 选项表 / 速查模板，却没同步 generated block → `node scripts/sync-analyze-docs.js --check` 失败。
-- 文档声称扫描类命令会尊重 `.gitignore`，但实现仍保留手写跳过规则 → `analyze` 与 `check-headers -d` 的文件集合漂移。
-- 把 `workflow` 重新扩回非分析阶段，却没同步 README / AI 命令文档 / guardrail 脚本 → `npm run docs:check` 失败。
-- 文档把 `design verify` 写成新的 workflow phase，或把 review-needed 路径写成 blocker failure → design docs 与命令退出语义漂移。
-- `docs/product-specs/README.md` 仍写“当前活跃产品规格暂为空”，但目录里已经有现行规格 → 目录索引与规格正文自相矛盾。
-- MVP3 规格文档继续把历史设计愿景写成当前现实（例如把 `neo4j`、14 种语言或公共 `server` 产品面写回去）→ `npm run docs:check` 失败。
-- `config-loader` 已支持 `storage`，但 schema / README / AI 文档没同步 → 用户能写配置，编辑器和 guardrail 却仍把它当非法字段。
-- 旧的 `neo4j` 配置已经不受支持，但文档还把它写成正式 backend，或缺少 `kuzu` 时却被文档写成会自动 fallback → 现场排障方向错误，误判为实现 bug。
+| 失败模式 | 先看哪里 | 恢复方式 |
+|---|---|---|
+| `schema / README / AI 文档没同步` | `npm run docs:check` | 先修文档真相，再重跑 |
+| prerelease 发布卡在 npm publish | `.github/workflows/publish.yml` / `package.json version` | 确认 prerelease 版本显式传了 `--tag <preid>`；例如 `0.5.2-beta.1` 必须走 `--tag beta` |
+| 文档继续把历史设计写成当前现实 | `npm run docs:check` | 把 shipped baseline 与 future intent 分开 |
+| 旧的 `neo4j` / `kuzudb` 配置已经不受支持，但文档还把它写成正式 backend | `README.md` / `AI_GUIDE.md` / schema | 改回 `filesystem` / `sqlite` / `memory` / `auto` 真实 contract |
+| `storage.type="sqlite"` 运行时不满足要求 | Node.js `>=20`、`better-sqlite3`、`STORAGE_BACKEND_MIGRATED`、`SQLITE_NOT_AVAILABLE` | 修运行时或改配置，不要静默 fallback |
+| 风险 truth 漂移 | `check` / `ci assess-risk` / `history` / `analyze --include-git-history` | 统一命令输出与文档措辞 |
+| 把 `workflow` 写回非 analysis-only | `docs/rules/engineering-with-codex-openai.md` / README | 收敛回 `find → read → link → show` |
+| 文档声称扫描类命令会尊重 `.gitignore`，但实现仍保留手写跳过规则 | `node dist/cli/index.js ci check-docs-sync` | 改回共享文件发现 contract，再重跑 docs guardrail |
+| 把 `workflow` 重新扩回非分析阶段，却没同步 README / AI 命令文档 / guardrail 脚本 | `npm run docs:check` | 收敛回 analysis-only 边界，再同步文档 |
 
 ## 常用命令
 
 ```bash
+python3 scripts/validate-rules.py code --report-only
 npm run docs:check
-node scripts/sync-analyze-docs.js --check
 node dist/cli/index.js ci check-docs-sync
-node dist/cli/index.js design verify mycodemap.design.md --json
-node dist/cli/index.js ci check-working-tree
-node dist/cli/index.js ci check-branch
-SHIP_IN_CI=1 node dist/cli/index.js ci check-scripts
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+node dist/cli/index.js check --contract mycodemap.design.md --against src
+node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+node dist/cli/index.js history --symbol createCheckCommand
+node scripts/report-high-risk-files.mjs --top 3
 npm run typecheck
-npm test
 npm run lint
+npm test
 npm run build
 npm run validate-pack
 ```
+
+## Rule Control QA
+
+| 命令 | 目的 |
+|---|---|
+| `bash scripts/qa-rule-control.sh --scenario all` | 一键覆盖 capability、P0/P1/unavailable、disabled soft gate、rule-context、CI backstop 七个场景 |
+| `python3 -m unittest scripts/tests/test_rule_control_workflow.py` | 锁住 helper scope、workflow `<rule_context>` 注入和 CI backstop 文本契约 |
+
+## 强约束
+
+- 没有验证，不得声称“已解决”。
+- 失败时优先修根因，不绕过护栏。
+- 涉及 CI / hooks / 输出契约时，必须给出失败场景与修复验证证据。
+- 不得把 `warn-only / fallback` 伪装成 hard gate success。

package/mycodemap.config.schema.json

@@ -47,9 +47,9 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["filesystem", "kuzudb", "memory", "auto"],
+          "enum": ["filesystem", "sqlite", "memory", "auto"],
           "default": "filesystem",
-          "description": "Storage backend type (Neo4j is no longer supported)"
+          "description": "Storage backend type (Neo4j and KùzuDB are no longer supported)"
         },
         "outputPath": {
           "type": "string",
@@ -58,7 +58,7 @@
         },
         "databasePath": {
           "type": "string",
-          "description": "KùzuDB database directory relative to project root"
+          "description": "SQLite database file path relative to project root"
         },
         "autoThresholds": {
           "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.5.0",
+  "version": "0.5.2-beta.1",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",
@@ -60,6 +60,8 @@
   "license": "MIT",
   "dependencies": {
     "@hono/node-server": "^1.19.11",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.9.0",
     "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
     "commander": "^11.1.0",
@@ -69,14 +71,17 @@
     "tree-sitter": "^0.21.1",
     "tree-sitter-typescript": "^0.23.2",
     "typescript": "^5.3.3",
-    "typhonjs-escomplex": "^0.1.0"
+    "typhonjs-escomplex": "^0.1.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/glob": "^8.1.0",
     "@types/node": "^20.10.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "@vitest/coverage-v8": "^1.6.1",
+    "dependency-cruiser": "^17.3.10",
     "eslint": "^8.57.1",
     "vitest": "^1.1.0"
   },