Fix lint errors and publish workflow

.github/workflows/ci.yml

@@ -44,3 +44,7 @@ jobs:
         run: test -f dist/packages/cli/index.js
       - name: Smoke test
         run: node dist/packages/cli/index.js --help
+      - name: CLI check (hello-world)
+        run: node dist/packages/cli/index.js check -r examples/hello-world
+      - name: CLI check (order-service)
+        run: node dist/packages/cli/index.js check -r examples/order-service

.github/workflows/publish.yml

@@ -7,7 +7,6 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    environment: npm
     permissions:
       contents: read
       id-token: write

.gitignore

@@ -6,6 +6,8 @@
 !.prettierrc
 !.node-version
 !README.md
+!CONTRIBUTING.md
+!CODE_OF_CONDUCT.md
 !LICENSE
 !tsconfig.json
 !package.json

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at <https://github.com/SemanticVoxelProtocol/forge/issues>. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Contributing to SVP Forge
+
+感谢你对 SVP Forge 的关注！以下指南帮助你高效参与贡献。
+
+## Code of Conduct
+
+请阅读并遵守我们的 [Code of Conduct](./CODE_OF_CONDUCT.md)。
+
+## 如何贡献
+
+### 报告 Bug
+
+1. 先搜索 [已有 Issues](https://github.com/SemanticVoxelProtocol/forge/issues) 确认没有重复
+2. 使用 Bug Report 模板创建 Issue
+3. 提供：复现步骤、期望行为、实际行为、环境信息（Node 版本、OS）
+
+### 提议新功能
+
+1. 创建 Feature Request Issue 描述需求
+2. 说明：要解决的问题、建议的方案、可能的替代方案
+3. 非平凡的 API 变更建议先在 Issue 中讨论，达成共识后再开发
+
+### 提交代码
+
+欢迎通过 Pull Request 贡献代码，包括 bug 修复、新功能、文档改进和测试补充。
+
+## 开发环境
+
+### 前置要求
+
+- Node.js >= 22（见 `.node-version`）
+- npm
+
+### 安装与构建
+
+```bash
+# 克隆仓库
+git clone https://github.com/SemanticVoxelProtocol/forge.git
+cd forge
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 运行测试
+npm test
+
+# 完整检查（TypeScript + ESLint + Prettier）
+npm run check
+```
+
+## 项目结构
+
+```
+packages/
+  cli/        CLI 命令（forge check, init, prompt, ...）
+  core/       核心逻辑（check, hash, store, view, i18n）
+  skills/     AI 工具适配器和 prompt 生成
+examples/     示例项目（hello-world, order-service, ...）
+tests/e2e/    端到端测试
+docs/         文档
+```
+
+## Pull Request 流程
+
+### 分支策略
+
+- `main` — 稳定分支，所有发布从此分支打 tag
+- `dev` — 开发分支，日常开发合入此分支
+- 功能分支从 `dev` 创建，命名：`feat/描述`、`fix/描述`、`docs/描述`
+
+### PR 步骤
+
+1. Fork 仓库，从 `dev` 创建功能分支
+2. 每个 PR 只解决一个问题（不要混合多个无关改动）
+3. 为新功能和 bug 修复添加测试
+4. 本地运行完整检查：
+   ```bash
+   npm run check   # tsc --noEmit + eslint + prettier --check
+   npm test         # vitest
+   ```
+5. PR 标题遵循 Conventional Commits 格式（见下方）
+6. 关联 Issue：`Fixes #123` 或 `Closes #123`
+7. 开启 "Allow edits from maintainers"
+
+### PR 检查清单
+
+- [ ] 代码通过 `npm run check`
+- [ ] 测试通过 `npm test`
+- [ ] 新功能/bug 修复包含测试
+- [ ] 文档已更新（如涉及用户可见变更）
+- [ ] PR 标题符合 Conventional Commits
+
+## Commit 规范
+
+遵循 [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)。
+
+### 格式
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### 类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `feat` | 新功能 | `feat(cli): add view command` |
+| `fix` | Bug 修复 | `fix(core): handle empty hash input` |
+| `docs` | 仅文档 | `docs: update tutorial` |
+| `style` | 格式调整，无逻辑变化 | `style: fix indentation` |
+| `refactor` | 重构，非 feat/fix | `refactor(store): simplify read logic` |
+| `perf` | 性能优化 | `perf(hash): cache computed values` |
+| `test` | 测试相关 | `test(check): add edge case coverage` |
+| `build` | 构建系统 | `build: update tsconfig target` |
+| `ci` | CI 配置 | `ci: add Node 24 to matrix` |
+| `chore` | 杂项维护 | `chore: update dependencies` |
+
+### 规则
+
+- 使用祈使句现在时：`add feature` 而非 `added` 或 `adds`
+- 首字母小写，末尾不加句号
+- 标题行不超过 72 字符
+- 破坏性变更在类型后加 `!`：`feat!: remove deprecated API`
+
+## 编码规范
+
+- **TypeScript** — 所有源码必须有类型标注
+- **ESLint** — `npm run lint`（配置见 `eslint.config.ts`）
+- **Prettier** — `npm run format`（提交前自动格式化）
+- **测试** — 使用 Vitest，bug 修复和新功能必须附带测试
+- 提交前运行 `npm run check` 确保一切正常
+
+## 发布流程
+
+> 此部分仅面向维护者。
+
+发布通过 CI 自动完成：
+
+1. 确保 `main` 分支 CI 全绿
+2. 更新版本号：`npm version patch|minor|major`
+3. 推送 tag：`git push --follow-tags`
+4. CI 自动通过 npm Trusted Publishing 发布到 npm
+
+## 需要帮助？
+
+- 浏览标记为 [`good first issue`](https://github.com/SemanticVoxelProtocol/forge/labels/good%20first%20issue) 的 Issue
+- 在 Issue 或 Discussion 中提问
+
+再次感谢你的贡献！

README.md

@@ -22,7 +22,7 @@ L1  Code         最终实现
 
 SVP 不自己调 AI API，不造编译器。SVP 是 AI 编码工具（Claude Code、Cursor、Windsurf、Kimi Code、Codex、GitHub Copilot）的**增强层**：
 
-- **工具链**：`svp check`（校验）、store（读写）、hash（变更追踪）
+- **工具链**：`forge check`（校验）、store（读写）、hash（变更追踪）
 - **Skills**：基于五层数据模型生成结构化 context，喂给用户已有的 AI 工具
 
 类似 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 的定位——不造 AI，给 AI 喂更好的上下文。SVP 的能力随 base model 进化自动提升。
@@ -73,15 +73,15 @@ npm run check    # tsc + eslint + prettier
 - [设计理由](docs/design-rationale.md) — 为什么这么设计，每个决策的推理过程
 - [代码风格](docs/code-style.md) — 开发规范（命名、测试、git、依赖、版本）
 - [交互架构](docs/interaction.md) — 逐层渗透模型、虚拟文件树、聚焦视图、编译计划
-- [check 错误码](docs/check-reference.md) — svp check 的所有错误/警告及修复建议
+- [check 错误码](docs/check-reference.md) — forge check 的所有错误/警告及修复建议
 
 ## 目录
 
 ```
 packages/
 ├── core/        五层数据模型的 TypeScript 类型定义 + 核心函数
 ├── skills/      Prompt 生成器（design-l3、compile、recompile 等）
-└── cli/         CLI 入口（svp 命令）
+└── cli/         CLI 入口（forge 命令）
 
 docs/            设计文档 + 开发规范
 examples/        示例项目（hello-world、order-service）

docs/architecture.md

@@ -89,7 +89,7 @@ interface L2CodeBlock {
 
 分界原则：**层间连接关系结构化，block 内部是黑盒。**
 
-结构化（`svp check` 校验）：
+结构化（`forge check` 校验）：
 - pins 的类型、wire 的引用、层间 block/flow 引用
 
 自然语言（展示给人看就行）：
@@ -125,7 +125,7 @@ L5 改了 intent
 
 自下而上（仅检测，用户决策）：
 L1 被手改
-  → L2 的 contentHash 和 L1 实际哈希不匹配 → svp check 报 CONTENT_DRIFT
+  → L2 的 contentHash 和 L1 实际哈希不匹配 → forge check 报 CONTENT_DRIFT
     → 用户决定：接受改动 / 回退 / 更新上层契约
 ```
 
@@ -141,7 +141,7 @@ L4/L3 的可视化编辑器。用节点图（nodes + wires）来编辑 L4 flow 
 
 svp-blueprint 不是一个"层"——它是数据模型的一种人看面（编辑视图）。未来可以有其他编辑器（CLI、Web IDE、VS Code 插件），底下操作的是同一份数据。
 
-### svp check
+### forge check
 
 校验层间连接关系：
 - pin 类型匹配
@@ -162,9 +162,9 @@ SVP 不自己调 AI API，而是生成结构化的 context（skills）喂给用
 
 SVP 不锁定任何 AI 提供商。今天用 Claude Code，明天用别的，SVP 数据模型不变。
 
-这个定位类似 [OpenSpec](https://github.com/Fission-AI/OpenSpec)——不造 AI，给 AI 喂更好的上下文。SVP 的差异在于：五层结构化的契约框架 + `svp check` 的形式化校验。
+这个定位类似 [OpenSpec](https://github.com/Fission-AI/OpenSpec)——不造 AI，给 AI 喂更好的上下文。SVP 的差异在于：五层结构化的契约框架 + `forge check` 的形式化校验。
 
-Skills 的具体实现形式是 SVP CLI 的虚拟文件树（`svp view`）和编译计划（`svp compile-plan`），详见 [交互架构](interaction.md)。
+Skills 的具体实现形式是 SVP CLI 的虚拟文件树（`forge view`）和编译计划（`forge compile-plan`），详见 [交互架构](interaction.md)。
 
 ### SVP 交互架构
 

docs/check-reference.md

@@ -1,6 +1,6 @@
-# svp check 错误码参考
+# forge check 错误码参考
 
-`svp check` 校验 `.svp/` 目录下所有层的数据一致性。以下是所有可能的错误和警告。
+`forge check` 校验 `.svp/` 目录下所有层的数据一致性。以下是所有可能的错误和警告。
 
 ## 错误（Error）
 

docs/compilation.md

@@ -19,7 +19,7 @@ L3Block ──→ AI 编码工具 + SVP skills ──→ L2CodeBlock + L1 源文
 
 SVP 不自己调 AI API。契约盒（validate + constraints + description）作为结构化 context 喂给 AI 工具，AI 工具负责生成代码。
 
-> **注意区分两种"编译"**：本文档描述的是**格式转换编译**（YAML 节点图 → L3/L4 JSON），是确定性的、不需要 AI 的。变更驱动的**重编译计划**（某层改了 → 计算哪些下层需要重新生成）见 [交互架构](interaction.md) 的 `svp compile-plan` 章节。
+> **注意区分两种"编译"**：本文档描述的是**格式转换编译**（YAML 节点图 → L3/L4 JSON），是确定性的、不需要 AI 的。变更驱动的**重编译计划**（某层改了 → 计算哪些下层需要重新生成）见 [交互架构](interaction.md) 的 `forge compile-plan` 章节。
 
 ## 映射规则
 
@@ -195,7 +195,7 @@ interface OrderRequest {
 { name: "request", type: "OrderRequest" }
 ```
 
-类型本身不被编译成独立的数据结构——它们就是 TypeScript，被 `svp check` 用来做连线类型匹配。
+类型本身不被编译成独立的数据结构——它们就是 TypeScript，被 `forge check` 用来做连线类型匹配。
 
 ## 编译缓存
 

docs/design-rationale.md

@@ -172,11 +172,11 @@ TypeScript interface 在这里的角色不是"实现语言"，而是**对 AI 最
 
 ### 结构化的边界：拓扑骨架 vs 黑盒内部
 
-"AI 不需要结构化"不意味着什么都不结构化。SVP 的工具链（`svp check`、渲染器）需要程序化处理一部分数据。
+"AI 不需要结构化"不意味着什么都不结构化。SVP 的工具链（`forge check`、渲染器）需要程序化处理一部分数据。
 
 区分标准很简单：**层间的连接关系必须结构化，block 内部可以是黑盒。**
 
-需要结构化（`svp check` 要校验）：
+需要结构化（`forge check` 要校验）：
 - **pins 的类型** — 连线两端类型是否兼容
 - **wire 的引用** — from/to 指向的 pin 是否存在
 - **层间引用** — L4 step 引用的 L3 block 是否存在、签名是否匹配
@@ -201,7 +201,7 @@ SVP 协议（语言无关）
   └── 变更传播的机制
 
 SVP 工具链（某种语言实现）
-  ├── 校验器（svp check）
+  ├── 校验器（forge check）
   ├── 编辑器（svp-blueprint 等）
   ├── Skills（给 AI 编码工具的结构化 context）
   └── Store（.svp/ 数据读写）

docs/design.md

@@ -193,7 +193,7 @@ wires:
 
 ## 蓝图查看器
 
-`svp blueprint` 命令是 svp-blueprint 的只读可视化入口——读取 `.svp/` 下已编译的 L3/L4 JSON，生成自包含 HTML 节点图在浏览器中查看。
+`forge blueprint` 命令是 svp-blueprint 的只读可视化入口——读取 `.svp/` 下已编译的 L3/L4 JSON，生成自包含 HTML 节点图在浏览器中查看。
 
 设计要点：
 
@@ -204,7 +204,7 @@ wires:
 - **三种 L4 变体**：Flow（主要，节点图）、EventGraph（事件处理器列表）、StateMachine（状态节点 + 转换边）
 - **零依赖自包含**：单个 HTML 文件内联所有 CSS/JS/数据，无需服务器，离线可用
 
-查看器不做编辑——编辑仍然通过 YAML 文件 + `svp compile-blueprint` 完成。查看器是数据的一种只读渲染视图。
+查看器不做编辑——编辑仍然通过 YAML 文件 + `forge compile-blueprint` 完成。查看器是数据的一种只读渲染视图。
 
 ## 不做什么