From 3a5edce6ac45e5d8a0313da062310870bcfa09c7 Mon Sep 17 00:00:00 2001 From: PartMe AI Date: Sat, 24 Oct 2026 17:53:45 +0800 Subject: [PATCH] docs: add CLI command contract and architecture --- docs/GitGuard-CLI-Architecture.en.md | 23 +++++++++ docs/GitGuard-CLI-Architecture.zh_CN.md | 23 +++++++++ docs/commands.en.md | 11 +++++ docs/commands.md | 28 +++++++++++ .../add-cli-command-contract/.openspec.yaml | 2 + .../add-cli-command-contract/design.md | 36 ++++++++++++++ .../add-cli-command-contract/proposal.md | 23 +++++++++ .../specs/cli-command-contract/spec.md | 47 +++++++++++++++++++ .../changes/add-cli-command-contract/tasks.md | 30 ++++++++++++ 9 files changed, 223 insertions(+) create mode 100644 docs/GitGuard-CLI-Architecture.en.md create mode 100644 docs/GitGuard-CLI-Architecture.zh_CN.md create mode 100644 docs/commands.en.md create mode 100644 docs/commands.md create mode 100644 openspec/changes/add-cli-command-contract/.openspec.yaml create mode 100644 openspec/changes/add-cli-command-contract/design.md create mode 100644 openspec/changes/add-cli-command-contract/proposal.md create mode 100644 openspec/changes/add-cli-command-contract/specs/cli-command-contract/spec.md create mode 100644 openspec/changes/add-cli-command-contract/tasks.md diff --git a/docs/GitGuard-CLI-Architecture.en.md b/docs/GitGuard-CLI-Architecture.en.md new file mode 100644 index 0000000..c58c08c --- /dev/null +++ b/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 diff --git a/docs/GitGuard-CLI-Architecture.zh_CN.md b/docs/GitGuard-CLI-Architecture.zh_CN.md new file mode 100644 index 0000000..bad2e1b --- /dev/null +++ b/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 diff --git a/docs/commands.en.md b/docs/commands.en.md new file mode 100644 index 0000000..c3feaa3 --- /dev/null +++ b/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. diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..60811e6 --- /dev/null +++ b/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。 diff --git a/openspec/changes/add-cli-command-contract/.openspec.yaml b/openspec/changes/add-cli-command-contract/.openspec.yaml new file mode 100644 index 0000000..1f5d280 --- /dev/null +++ b/openspec/changes/add-cli-command-contract/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-24 diff --git a/openspec/changes/add-cli-command-contract/design.md b/openspec/changes/add-cli-command-contract/design.md new file mode 100644 index 0000000..f3cec6c --- /dev/null +++ b/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。 diff --git a/openspec/changes/add-cli-command-contract/proposal.md b/openspec/changes/add-cli-command-contract/proposal.md new file mode 100644 index 0000000..5701ea5 --- /dev/null +++ b/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。 diff --git a/openspec/changes/add-cli-command-contract/specs/cli-command-contract/spec.md b/openspec/changes/add-cli-command-contract/specs/cli-command-contract/spec.md new file mode 100644 index 0000000..7466b7a --- /dev/null +++ b/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。 diff --git a/openspec/changes/add-cli-command-contract/tasks.md b/openspec/changes/add-cli-command-contract/tasks.md new file mode 100644 index 0000000..c21b11e --- /dev/null +++ b/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。