docs: add CLI command contract and architecture

docs/GitGuard-CLI-Architecture.en.md

@@ -0,0 +1,23 @@
+# GitGuard CLI Architecture
+
+## 1. Positioning
+
+GitGuard（分支规范防护）是独立 CLI，不依赖统一 guard 调度器。插件只负责宿主集成、Hook 和技能路由。
+
+## 2. Command layers
+
+生命周期：install/uninstall/upgrade/version/doctor/status/completion。
+项目事实：discover/init/check/report。
+专业命令：install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report。
+
+## 3. State and evidence
+
+项目状态写入 .guard/evidence/gitguard/；配置由各工具管理。FlowGuard 只读证据，不替其他工具执行。
+
+## 4. Security
+
+install 不写项目，init 不写宿主，hooks install 不静默执行。所有写操作支持 --dry-run/--yes。
+
+## 5. Maturity
+
+已实现 discover/init/audit/check/doctor/context/hooks/branch/sync/release/version

docs/GitGuard-CLI-Architecture.zh_CN.md

@@ -0,0 +1,23 @@
+# GitGuard CLI 架构设计
+
+## 1. 定位
+
+GitGuard（分支规范防护）是独立 CLI，不依赖统一 guard 调度器。插件只负责宿主集成、Hook 和技能路由。
+
+## 2. 命令分层
+
+生命周期：install/uninstall/upgrade/version/doctor/status/completion。
+项目事实：discover/init/check/report。
+专业命令：install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report。
+
+## 3. 状态与证据
+
+项目状态写入 .guard/evidence/gitguard/；配置由各工具管理。FlowGuard 只读证据，不替其他工具执行。
+
+## 4. 安全
+
+install 不写项目，init 不写宿主，hooks install 不静默执行。所有写操作支持 --dry-run/--yes。
+
+## 5. 当前成熟度
+
+已实现 discover/init/audit/check/doctor/context/hooks/branch/sync/release/version

docs/commands.en.md

@@ -0,0 +1,11 @@
+# GitGuard Command Reference
+
+Status: 已实现 discover/init/audit/check/doctor/context/hooks/branch/sync/release/version
+
+## Commands
+
+install, uninstall, upgrade, version, doctor, status, discover, init, check, report, plus domain commands: install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report.
+
+Exit codes: 0 PASS, 1 BLOCK, 2 usage/config, 3 UNVERIFIED/DESIGN_ONLY, 4 internal/runtime error.
+
+No PASS without real execution evidence. CodeReview uses Alibaba OCR commands directly.

docs/commands.md

@@ -0,0 +1,28 @@
+# GitGuard 命令参考
+
+版本：0.1.0 文档 · 状态：已实现 discover/init/audit/check/doctor/context/hooks/branch/sync/release/version
+
+## 命令表
+
+| 命令 | 作用 | 状态 |
+|---|---|---|
+| gitguard install | 接入宿主，不写项目 | 规划 |
+| gitguard uninstall | 移除宿主接入 | 规划 |
+| gitguard upgrade | 升级自身 | 规划 |
+| gitguard version | 版本与协议 | 规划 |
+| gitguard doctor | 环境与依赖诊断 | 规划 |
+| gitguard status | 当前项目状态 | 规划 |
+| gitguard discover | 只读识别项目 | 规划 |
+| gitguard init | 建项目配置/基线 | 规划 |
+| gitguard check | 只读门禁 | 已有/规划 |
+| gitguard report | 读取证据 | 规划 |
+
+完整领域命令：install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report
+
+## 退出码
+
+0 PASS；1 BLOCK；2 用法/配置错误；3 UNVERIFIED/DESIGN_ONLY；4 内部错误。
+
+## 边界
+
+没有真实执行证据时不得输出 PASS。CodeReview 使用阿里云 OCR 的真实命令，不新增自有 CLI。

openspec/changes/add-cli-command-contract/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-24

openspec/changes/add-cli-command-contract/design.md

@@ -0,0 +1,36 @@
+# GitGuard CLI 命令契约设计
+
+## 1. 目标
+
+让用户只记住少量稳定动词，同时保持 GitGuard 独立安装、独立版本、独立 Hook。
+
+## 2. 分层
+
+生命周期：install、uninstall、upgrade、version、doctor、status、completion。
+项目事实：discover、init、check、report。
+专业命令：install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report。
+
+## 3. 语义
+
+- install 只接宿主，不写项目。
+- init 只写项目配置/基线，幂等，支持 --dry-run。
+- hooks install 只写当前仓库 Git Hook。
+- discover 只读识别。
+- check 只读门禁，不自动修复。
+- apply/fix 必须显式批准。
+- doctor 诊断环境，不检查代码。
+- status 读取状态，不重新执行。
+- report 读取已有证据，不重新执行。
+
+## 4. 输出与退出码
+
+统一 JSON：schemaVersion、tool、command、decision、exitCode、findings、evidence、nextActions。
+退出码：0 PASS，1 BLOCK，2 用法/配置错误，3 UNVERIFIED/DESIGN_ONLY，4 内部错误或运行时缺失。
+
+## 5. Hook
+
+GitGuard 只调用自身命令。事件所有权：GitGuard 管 git commit/push；CodeGuard 管 Write/Edit 后的增量检查；FlowGuard 管阶段上下文；其他工具只做自身诊断和摘要。
+
+## 6. 边界
+
+没有真实执行证据时不得输出 PASS。CodeReview 使用 ocr 的真实命令，不伪造自有 CLI。

openspec/changes/add-cli-command-contract/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+GitGuard 需要一套可预测、可诊断、可自动化的命令契约，避免安装、初始化、检查、修复和 Hook 语义互相混淆。当前状态：已实现 discover/init/audit/check/doctor/context/hooks/branch/sync/release/version。
+
+## What Changes
+
+- 统一生命周期命令：install、uninstall、upgrade、version、doctor、status、completion。
+- 统一项目事实命令：discover、init、check、report。
+- 按能力增加 impact、explain、hooks、plan/apply 等领域命令。
+- 统一 JSON 信封、退出码、--dry-run/--yes、Hook 事件责任。
+- CodeReview 只使用阿里云 OCR 的真实命令，不新增自有 CLI。
+
+## Capabilities
+
+### New Capabilities
+- cli-command-contract: 命令语义、输出、退出码和 Hook 边界。
+
+### Modified Capabilities
+无。
+
+## Impact
+
+涉及 CLI 入口、插件 Hook、技能路由和文档；不改变 GitGuard 的专业判定边界。未实现能力必须报告 DESIGN_ONLY 或 UNVERIFIED。

openspec/changes/add-cli-command-contract/specs/cli-command-contract/spec.md

@@ -0,0 +1,47 @@
+# CLI 命令契约规格
+
+## Purpose
+
+定义命令语义、输出、退出码和 Hook 边界，供各 Guard 独立实现。
+
+## ADDED Requirements
+
+### Requirement: CLI-001 Install and project initialization
+命令 SHALL 区分 install、init 和 hooks install；install 不写项目文件，init 不写宿主配置。
+
+#### Scenario: install on clean host
+- **WHEN** 用户运行 install
+- **THEN** 只写宿主集成，不修改项目，不执行代码检查
+
+### Requirement: CLI-002 Discovery
+discover SHALL 只读输出项目、语言、构建系统和可用工具。
+
+### Requirement: CLI-003 Idempotent init
+init SHALL 幂等，不覆盖已有配置；--dry-run 不写文件。
+
+### Requirement: CLI-004 Diagnosis
+doctor SHALL 检查运行时、依赖、配置和 Hook，不执行代码检查；status SHALL 读取状态，不重新执行。
+
+### Requirement: CLI-005 Read-only check
+check SHALL 只读，不修改文件；输出 allow、deny、unverified 或 error。
+
+### Requirement: CLI-006 Evidence report
+report SHALL 读取已有证据，不重新执行命令。
+
+### Requirement: CLI-007 Domain commands
+领域命令 SHALL 使用固定动词和明确边界，不得用同一命令混合检查与修复。
+
+### Requirement: CLI-008 Honest capability
+未实现或未执行的能力 SHALL 输出 DESIGN_ONLY 或 UNVERIFIED，不得输出 PASS。
+
+### Requirement: CLI-009 Repository hooks
+hooks install SHALL 只写当前仓库 Git Hook，并在 status 中报告真实路径和状态。
+
+### Requirement: CLI-010 Hook ownership
+每个 Hook 事件 SHALL 有唯一所有者，禁止多个 Guard 在同一事件上重复阻断。
+
+### Requirement: CLI-011 Compatibility
+旧命令 SHALL 保留别名，并输出弃用提示；不得静默改变语义。
+
+### Requirement: CLI-012 Output contract
+所有支持 --json 的命令 SHALL 输出统一信封，并保留 rawExitCode。

openspec/changes/add-cli-command-contract/tasks.md

@@ -0,0 +1,30 @@
+# GitGuard CLI 命令契约任务
+
+状态：规划完成，按实现证据勾选。
+
+## 1. P0 生命周期
+
+- [ ] 1.1 实现 install/uninstall，区分宿主接入与项目文件；支持 --dry-run。规格：CLI-001。
+- [ ] 1.2 实现 version/doctor/status，输出 JSON；doctor 不执行代码检查。规格：CLI-004。
+- [ ] 1.3 实现 discover，只读识别项目、语言、构建系统和可用工具。规格：CLI-002。
+
+## 2. P0 项目事实
+
+- [ ] 2.1 实现/补齐 init，幂等，不覆盖已有配置，支持 --dry-run。规格：CLI-003。
+- [ ] 2.2 实现/补齐 check，只读门禁，输出统一 decision。规格：CLI-005。
+- [ ] 2.3 实现 report，读取已有证据，不重新执行。规格：CLI-006。
+
+## 3. P1 专业能力
+
+- [ ] 3.1 按命令表补齐领域命令：install,uninstall,upgrade,version,doctor,status,discover,init,check,audit,policy,branch,sync,release,hooks,report。规格：CLI-007。
+- [ ] 3.2 未实现能力必须输出 DESIGN_ONLY/UNVERIFIED；不得伪造 PASS。规格：CLI-008。
+
+## 4. P1 Hook
+
+- [ ] 4.1 实现 hooks install/status，只写当前仓库 Hook。规格：CLI-009。
+- [ ] 4.2 确认 Hook 事件所有权，不与其他 Guard 抢占同一事件。规格：CLI-010。
+
+## 5. P2 兼容
+
+- [ ] 5.1 保留旧命令别名并输出弃用提示。规格：CLI-011。
+- [ ] 5.2 增加 golden JSON 与退出码矩阵测试。规格：CLI-012。