full-stack-plugins · loong10k · Sep 23, 2026 · Sep 23, 2026
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -9,20 +9,20 @@
       "source": {
         "source": "url",
         "url": "https://github.com/full-stack-plugins/flowguard-plugin.git",
-        "ref": "v0.2.0"
+        "ref": "v0.3.0"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_USE"
       },
       "category": "Developer Tools",
-      "version": "0.2.0",
-      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/flowguard-plugin@v0.2.0/assets/official-logo.png",
+      "version": "0.3.0",
+      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/flowguard-plugin@v0.3.0/assets/official-logo.png",
       "description": "Agent-driven SDD governance for Codex, ZCode, Kimi and Claude: native Spec Kit/OpenSpec/Superpowers discovery, session-worktree task binding, evidence freshness and deterministic code/commit/release gates.",
       "interface": {
         "displayName": "研发流程门禁",
         "shortDescription": "智能体 SDD 治理：原生规格、证据与提交门禁",
-        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/flowguard-plugin@v0.2.0/assets/official-logo.png"
+        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/flowguard-plugin@v0.3.0/assets/official-logo.png"
       }
     }
   ]

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "flowguard",
-  "version": "0.2.0+codex.20260923",
+  "version": "0.3.0+codex.20260923",
   "author": {
     "name": "Full Stack Skills / PartMe.AI",
     "url": "https://github.com/full-stack-plugins/flowguard-plugin"

diff --git a/.zcode-plugin/plugin.json b/.zcode-plugin/plugin.json
@@ -5,7 +5,7 @@
     "en": "研发流程门禁",
     "zh-CN": "研发流程门禁"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent-driven SDD governance for Codex, ZCode, Kimi and Claude: native Spec Kit/OpenSpec/Superpowers discovery, session-worktree task binding, evidence freshness and deterministic code/commit/release gates.",
   "description_i18n": {
     "en": "Agent-driven SDD governance with native specification discovery, task-context binding, evidence freshness, and deterministic commit/release gates.",

diff --git a/AGENTS.md b/AGENTS.md
@@ -4,11 +4,11 @@
 
 ## 全局约束（照 spec 决策表）
 
-- 命名：仓库 `flowguard-plugin`、name `flowguard`、displayName「研发流程门禁」、i18n en "FlowGuard: R&D Process Gate"、命令前缀 `/flowguard-*`、产物目录 `.flowguard/`。
+- 命名：仓库 `flowguard-plugin`、name `flowguard`、displayName「研发流程门禁」、i18n en "FlowGuard: R&D Process Gate"、命令前缀 `/flowguard-*`。十阶段产物只写 `docs/project/` 与 `docs/features/<task-id>/`；新项目不得创建 `.flowguard/`。
 - Python 仅标准库；测试用 `python3 -m unittest discover -s tests`（不是 pytest）。
 - SKILL.md ≤ 500 行；frontmatter 必含 `name`（kebab，与目录同名）/ `license: Apache-2.0` / `description`（含触发词与负面边界）/ `compatibility`。
 - 跨技能引用只用「技能名 + `npx skills add <org>/<pkg> --skill <name>`」，禁止 `../` 相对路径指向其它技能。
-- 新治理模型的门禁无 strict_mode 软化开关；用户批准与验收不得由 agent 伪造。旧十阶段的 override/accepted 规则继续兼容。
+- 十阶段由智能体推进，Hook 只校验与拦截；门禁无 strict_mode 软化开关。用户批准与验收不得由 agent 伪造；旧状态仅供迁移和兼容读取。
 - REQ-ID 全局唯一，格式 `<feature-id>/REQ-<n>`；feature-id/模块名 kebab `^[a-z0-9]+(?:-[a-z0-9]+)*$`。
 - 门禁/校验输出统一诊断信封基础字段 `{severity, code, message, fix}`；新治理拒绝可追加 `missing/allowed_actions`。
 - 四宿主 manifest 版本字段必须一致（`.codex-plugin/plugin.json` 例外：`<v>+codex.<YYYYMMDD>`）；`.zcode-plugin/plugin.json` 不得含 `hooks` 键；不得含占位 `mcpServers`。
@@ -31,11 +31,11 @@
 
 - **治理核单一判定源**：发现/上下文/证据/门禁只存在于 flowguard_lib，hooks 与命令只是呈现面（JSON 与文本永不漂移）。
 - **SKILL.md 是生成物**：改内容改 `scripts/templates/workflows.py` 模板源，再跑 `scripts/generate_skills.py`；parity 测试强制一致。
-- **accepted 只能由用户写入**：`advance` 是唯一入口；agent 永远不能代替用户验收；override 必须用户发起 + 理由留痕。
+- **accepted 只能依据真实用户批准写入**：`stage advance` 是新流程入口；agent 永远不能代替用户验收。宿主若无不可伪造回执，不得宣称已建立对抗性强制门禁。
 
 ## 实现规格参照
 
-- 当前规格（单一权威）：`docs/superpowers/specs/2026-09-23-flowguard-agent-driven-sdd-governance.md`
+- 当前规格（单一权威）：`docs/superpowers/specs/2026-09-23-flowguard-docs-ten-stage-governance.md`
 - 当前实施计划：`docs/superpowers/plans/2026-09-23-flowguard-agent-driven-sdd-governance.md`
-- 旧十阶段规格仅作兼容历史，不得作为新任务默认流程。
+- v0.2 的“十阶段仅兼容”决策已被当前规格取代；旧 `.flowguard/` 仅是迁移输入，不得作为新任务默认产物。
 - 钩子协议：`hooks/__protocol__.md`（改协议必须同 commit 更新契约与测试）
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![skills-check](https://github.com/full-stack-plugins/flowguard-plugin/actions/workflows/skills-check.yml/badge.svg)](https://github.com/full-stack-plugins/flowguard-plugin/actions/workflows/skills-check.yml)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-FlowGuard is an agent governance plugin for Codex, ZCode, Kimi, and Claude. **The agent decides how to advance the task; native SDD tools own specifications and engineering methods; FlowGuard prevents required context, approvals, dependencies, and evidence from being skipped.**
+FlowGuard is an agent governance plugin for Codex, ZCode, Kimi, and Claude. **Its ten-stage process remains mandatory and agent-driven; native SDD tools own specifications and engineering methods; FlowGuard validates stage documents in `docs/`, approvals, dependencies, and evidence.**
 
 ## Responsibilities
 
@@ -21,20 +21,20 @@ FlowGuard does not copy specifications, silently initialize tools, or turn a mac
 flowchart LR
     D[Discover Git / SDD] --> C[Agent classifies and selects]
     C --> B[Bind context]
-    B --> N[Advance native specs and implementation]
+    B --> N[Agent advances ten stages, docs, and native specs]
     N --> E[Tests / CodeGuard / CodeReview]
     E --> G[FlowGuard action decision]
     G -->|Missing| C
     G -->|Satisfied| A[Allow code / commit / release]
 ```
 
-The required rule is “follow the applicable process,” not “run every task through a fixed pipeline.”
+The ten stages are a verifiable process skeleton, not a Hook-driven script. Read-only tasks only need discovery and classification; writing tasks must satisfy applicable stage gates.
 
 | Task type | Default governance |
 |:---|:---|
 | Read-only analysis | Discover and classify; no initialization required |
-| Simple change | Lightweight context plus current-fingerprint verification |
-| Important change | Bind a native specification, capture required approval, execute with TDD |
+| Simple change | Bind context; reuse or justify skipped stages; retain verification evidence |
+| Important change | Bind a native specification, complete ten-stage documents and approval, execute with TDD |
 | Production incident | Restore stability first; backfill behavior-changing specifications |
 
 ## Quick start
@@ -46,6 +46,8 @@ The required rule is “follow the applicable process,” not “run every task
 /flowguard-governance  # check code-write, commit, or release readiness
 ```
 
+Kimi registers the same command prompts as namespaced Markdown commands, for example `/flowguard:flowguard-discover`. The Markdown files in `kimi-commands/` are generated from `commands/*.json`; regenerate with `python3 scripts/generate_kimi_commands.py --write` after changing a source command. Kimi Shell may not expose `KIMI_PLUGIN_ROOT`; in that case, use `/plugins info flowguard` to locate the enabled plugin before running its bundled CLI. The plugin remains centrally cataloged in `full-stack-plugins`; this source repository is maintained separately.
+
 CLI example:
 
 ```bash
@@ -54,6 +56,7 @@ python3 scripts/flowguard_state.py context bind \
   --session session-1 --task-id refund-idempotency \
   --task-type important_change --spec-system openspec \
   --spec-ref openspec/changes/refund-idempotency --json
+python3 scripts/flowguard_state.py stage status --task-id refund-idempotency --json
 python3 scripts/flowguard_state.py governance \
   --session session-1 --action code_write --json
 ```
@@ -64,9 +67,9 @@ python3 scripts/flowguard_state.py governance \
 |:---|:---|
 | Read / specification remediation | Always open so a block can be resolved |
 | Test write | Active governance context |
-| Business-code write | Writable task; important changes also need a valid spec and scope approval |
-| `git commit` | Current-fingerprint tests, static analysis, and semantic review |
-| Release | Commit conditions plus release readiness, user acceptance, and completed dependencies/children |
+| Business-code write | Stages 01–07 satisfied; important changes also need a valid spec and scope approval |
+| `git commit` | Stages 01–09 plus valid current-fingerprint tests, static analysis, and semantic review |
+| Release | All ten stages, valid stage-09 documents for every feature listed in the stage-10 release scope, release readiness, user acceptance, and completed dependencies/children |
 
 Denials use exit code 2 and return `code / message / fix / missing / allowed_actions`. Hook failures fail open; known governance gaps fail closed.
 
@@ -75,19 +78,20 @@ Denials use exit code 2 and return `code / message / fix / missing / allowed_act
 - `SessionStart`: discover SDD state and restore context.
 - `UserPromptSubmit`: remind the agent to reassess task, scope, and source of truth.
 - `PreToolUse`: gate code writes, Git commits, and releases; protect governance state.
-- `PostToolUse`: expire stale evidence and observe explicit test/check exit codes.
+- `PostToolUse`: expire stale evidence and observe explicit test exit codes; CodeGuard/CodeReview PASS requires a structured, verifiable result rather than a zero exit code alone.
+- Kimi `PostToolUseFailure` for Shell: mark a recognized failed test run as FAIL so an earlier PASS cannot remain current.
 - `Stop`: summarize missing evidence and the next action without treating the turn as task completion.
 
 See [hooks/__protocol__.md](hooks/__protocol__.md).
 
-## Legacy compatibility
+## Document locations and legacy migration
 
-The v0.1 ten-stage `.flowguard` artifacts and commands remain available for existing projects. They are compatibility-only: new tasks no longer create ten specification copies or rely on one global `current_feature`.
+Project stages 02/07/10 live in `docs/project/`; feature stages 01/03/04/05/06/08/09 live in `docs/features/<task-id>/`. New projects do not create `.flowguard/`; session cache lives outside the repository. For existing projects, run `migrate --dry-run`, resolve conflicts, then `migrate --apply`; retain the original data until verified. If migration stops midway, newly created documents are listed and kept for inspection rather than deleting files another process may have edited. `legacy-init` is only for old-command compatibility.
 
 ## Documentation
 
 - [Current architecture](docs/FlowGuard-Architecture.zh_CN.md)
-- [Agent-driven SDD governance specification](docs/superpowers/specs/2026-09-23-flowguard-agent-driven-sdd-governance.md)
+- [Ten-stage docs governance specification](docs/superpowers/specs/2026-09-23-flowguard-docs-ten-stage-governance.md)
 - [Implementation plan](docs/superpowers/plans/2026-09-23-flowguard-agent-driven-sdd-governance.md)
 - [Legacy artifact contract](docs/FLOWGUARD_ARTIFACT_SPEC.md)
 - [Roadmap](docs/roadmap.md)
@@ -98,6 +102,7 @@ The v0.1 ten-stage `.flowguard` artifacts and commands remain available for exis
 python3 -m unittest discover -s tests -v
 python3 scripts/vendor/skill_vendor.py check --offline
 python3 scripts/generate_skills.py
+python3 scripts/generate_kimi_commands.py
 git diff --check
 ```
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -3,7 +3,7 @@
 [![skills-check](https://github.com/full-stack-plugins/flowguard-plugin/actions/workflows/skills-check.yml/badge.svg)](https://github.com/full-stack-plugins/flowguard-plugin/actions/workflows/skills-check.yml)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-FlowGuard 是面向 Codex、ZCode、Kimi 与 Claude 的智能体研发治理插件：**智能体决定怎样推进任务，原生 SDD 工具提供规格与方法，FlowGuard 用可核验的上下文、批准、依赖和证据防止跳过必要步骤。**
+FlowGuard 是面向 Codex、ZCode、Kimi 与 Claude 的智能体研发治理插件：**强制十阶段由智能体推进；原生 SDD 工具提供规格与方法；FlowGuard 用 `docs/` 文档、批准、依赖和证据防止跳过必要步骤。**
 
 ## 核心定位
 
@@ -21,20 +21,20 @@ FlowGuard 不复制规格、不自动初始化工具，也不把机器 PASS 变
 flowchart LR
     D[发现 Git / SDD] --> C[智能体分类与选择]
     C --> B[绑定上下文]
-    B --> N[推进原生规格与实现]
+    B --> N[智能体推进十阶段 docs 文档与原生规格]
     N --> E[测试 / CodeGuard / CodeReview]
     E --> G[FlowGuard 动作裁决]
     G -->|缺失| C
     G -->|满足| A[允许写码 / commit / release]
 ```
 
-强制的是“遵循适用流程”，不是让所有任务走固定阶段：
+十阶段是可验证的流程骨架，不由 Hook 自动推进。只读任务只做发现和分类；需要写码的任务按适用范围完成十阶段门禁：
 
 | 任务 | 默认治理 |
 |:---|:---|
 | 只读分析 | 完成发现和分类，不要求初始化 |
-| 简单修改 | 轻量上下文 + 当前代码指纹的验证证据 |
-| 重要变更 | 绑定原生规格、取得必要批准、按 TDD 推进 |
+| 简单修改 | 绑定上下文，复用或有依据地跳过不适用阶段，保留验证证据 |
+| 重要变更 | 绑定原生规格、完成十阶段产物与必要批准，按 TDD 推进 |
 | 生产故障 | 允许先恢复稳定，行为变化随后补规格 |
 
 ## 快速开始
@@ -53,6 +53,8 @@ flowchart LR
 /flowguard-governance
 ```
 
+Kimi 将同源命令注册为带命名空间的 Markdown 命令，例如 `/flowguard:flowguard-discover`。`kimi-commands/` 由 `commands/*.json` 机械生成；修改 JSON 后运行 `python3 scripts/generate_kimi_commands.py --write`。若 Kimi Shell 未提供 `KIMI_PLUGIN_ROOT`，先通过 `/plugins info flowguard` 确认已启用插件的安装目录，再运行其自带 CLI。插件仍由 `full-stack-plugins` 统一登记与发布管理，源码仓库独立维护。
+
 对应 CLI：
 
 ```bash
@@ -61,6 +63,7 @@ python3 scripts/flowguard_state.py context bind \
   --session session-1 --task-id refund-idempotency \
   --task-type important_change --spec-system openspec \
   --spec-ref openspec/changes/refund-idempotency --json
+python3 scripts/flowguard_state.py stage status --task-id refund-idempotency --json
 python3 scripts/flowguard_state.py governance \
   --session session-1 --action code_write --json
 ```
@@ -71,9 +74,9 @@ python3 scripts/flowguard_state.py governance \
 |:---|:---|
 | 读取 / 补规格 | 保持开放，确保能解除阻断 |
 | 补测试 | 已绑定治理上下文 |
-| 写业务代码 | 可写任务；重要变更另需有效规格与范围批准 |
-| `git commit` | 当前指纹的测试、静态分析、语义审查证据 |
-| 发布 | 提交条件 + 发布就绪 + 用户验收 + 依赖/子任务收敛 |
+| 写业务代码 | 01—07 阶段满足；重要变更另需有效规格与范围批准 |
+| `git commit` | 01—09 阶段满足，且当前指纹的测试、静态分析、语义审查证据有效 |
+| 发布 | 十阶段满足；10 发布清单所列功能的 09 文档仍有效，且发布就绪、用户验收、依赖/子任务收敛 |
 
 拒绝使用 exit 2，并返回 `code / message / fix / missing / allowed_actions`。Hook 故障本身 fail-open；确定性治理缺口 fail-closed。
 
@@ -82,19 +85,20 @@ python3 scripts/flowguard_state.py governance \
 - `SessionStart`：只读发现项目和 SDD 状态，恢复上下文。
 - `UserPromptSubmit`：提醒智能体重新判断任务、范围与事实源。
 - `PreToolUse`：校验写码、Git commit、发布，并保护治理状态。
-- `PostToolUse`：使旧证据过期；仅在明确 exit code 时观察测试/检查结果。
+- `PostToolUse`：使旧证据过期；仅对明确执行测试的命令观察 exit code。CodeGuard/CodeReview 的 PASS 不能只凭退出码，仍需结构化、可核验的结果。
+- Kimi 的 Shell `PostToolUseFailure`：明确的测试工具失败记 FAIL，避免旧 PASS 继续作为最新证据。
 - `Stop`：汇总缺失证据和下一步，不把本轮结束当成任务完成。
 
 协议见 [hooks/__protocol__.md](hooks/__protocol__.md)。
 
-## 兼容旧十阶段
+## 文档位置与旧项目迁移
 
-v0.1 的 `.flowguard/project.json`、十阶段产物和 `init/feature/next/advance/override` 命令暂时保留。它们只用于已有项目兼容；新任务不再默认生成十份 `.flowguard` 规格，也不再使用全局 `current_feature` 作为唯一上下文。
+项目级 02/07/10 放在 `docs/project/`，功能级 01/03/04/05/06/08/09 放在 `docs/features/<task-id>/`。新项目不创建 `.flowguard/`；会话缓存保存在宿主状态目录。旧项目先运行 `migrate --dry-run`，确认无冲突后再 `migrate --apply`，核对完成前保留旧数据。迁移中途失败时，已创建文档保留并在错误中列出，需人工核对；不会为了回滚而删除可能已被他人修改的文件。`legacy-init` 仅供旧命令兼容。
 
 ## 文档
 
 - [FlowGuard-Architecture.zh_CN.md](docs/FlowGuard-Architecture.zh_CN.md) — 当前架构、运行流、可信边界和风险
-- [智能体驱动 SDD 治理规格](docs/superpowers/specs/2026-09-23-flowguard-agent-driven-sdd-governance.md)
+- [十阶段 docs 治理规格](docs/superpowers/specs/2026-09-23-flowguard-docs-ten-stage-governance.md)
 - [实施计划](docs/superpowers/plans/2026-09-23-flowguard-agent-driven-sdd-governance.md)
 - [旧产物兼容契约](docs/FLOWGUARD_ARTIFACT_SPEC.md)
 - [路线图](docs/roadmap.md)
@@ -105,6 +109,7 @@ v0.1 的 `.flowguard/project.json`、十阶段产物和 `init/feature/next/advan
 python3 -m unittest discover -s tests -v
 python3 scripts/vendor/skill_vendor.py check --offline
 python3 scripts/generate_skills.py
+python3 scripts/generate_kimi_commands.py
 git diff --check
 ```