guarantee-based-coding 0.3.0__tar.gz → 0.4.0__tar.gz

{guarantee_based_coding-0.3.0 → guarantee_based_coding-0.4.0}/MANIFEST.in

@@ -1,3 +1,4 @@
 include build_support.py
 include docs/en/quick-start.md docs/en/concepts.md docs/en/workflow.md docs/en/reference.md docs/en/onboarding-agent.md
 include docs/zh/quick-start.md docs/zh/concepts.md docs/zh/workflow.md docs/zh/reference.md docs/zh/onboarding-agent.md
+include docs/development/0.4.0-validation.md

{guarantee_based_coding-0.3.0/guarantee_based_coding.egg-info → guarantee_based_coding-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guarantee-based-coding
-Version: 0.3.0
+Version: 0.4.0
 Summary: Make code safely modifiable even when not fully understood — turn implicit inter-module dependencies into explicit, executable, verifiable guarantees.
 Author: Jesse-x86
 License-Expression: Apache-2.0
@@ -64,10 +64,14 @@ English docs: [docs/en/](./docs/en/)。
 安装后也能离线查询同版本手册：`gbc doc list --lang zh`、`gbc doc read quick-start --lang zh`、
 `gbc doc search "保证" --lang zh`。`--help` 仍用于查简短命令语法。
 
-当前仓库包含 **0.3.0 开发中的改动，尚未发布**；0.2.3 已发布。
+**0.4.0** 在 0.3.0 的命令职责与离线手册基础上，完善意图起草、保证测试和术语 / 决策复用工作流。
 0.3.0 中项目架构意图入口由 `gbc doc` 改为 `gbc intent`，MCP 的八个意图工具由 `doc_*`
 改为 `intent_*`，不保留旧别名。此后的 `gbc doc` 专门查询 GBC 手册。
 
+0.4.0 增加可配合 MCP 或 CLI 使用的 **gbc-workflow** skill：先查证据再起草意图、保护消费者
+行为的保证测试，以及术语与决策理由复用。**gbc-cli** 保留为命令适配器；用 `gbc setup` 查询
+随包路径，按客户端需要在项目内接入，不自动全局安装。详见[工作流](./docs/zh/workflow.md)。
+
 ---
 
 ## 核心想法
@@ -96,7 +100,7 @@ GBC 目前是一个可用的 Python 分发包（`pipx install guarantee-based-co
 - ✅ 多语言 executor 配置
 - ✅ CLI + MCP 双接口（含意图文档 `gbc intent` 全进 MCP）
 - ✅ 意图文档子系统（`gbc intent` / web 编辑器）
-- ✅ 随包分发的接线指南（`gbc setup`）与 CLI-only agent 的 skill 包
+- ✅ 随包接线指南（`gbc setup`）、通用于 MCP / CLI 的工作流 skill 与 CLI 命令适配 skill
 - ✅ 原子文件写入 + 备份
 
 

{guarantee_based_coding-0.3.0 → guarantee_based_coding-0.4.0}/README.md

@@ -1,94 +1,98 @@
-# Guarantee-Based Coding (GBC)
-
-**与其指望 AI 更聪明，不如让再笨的 agent 也改不坏你的代码。**
-
-**English version: [docs/en/README.md](docs/en/README.md)**
-
-GBC 把「这次改动会不会悄悄碰坏别处」从一种担心，变成可以当场验证的事实：你在意的行为被登记成
-一条条带测试的**保证（guarantee）**，每次改完一跑——全绿就安心，有红就精确告诉你碰坏了谁、谁在
-依赖它。
-
----
-
-## 🚀 快速开始
-
-```bash
-pipx install guarantee-based-coding
-gbc setup        # 打印本地化接线指南：怎么把 MCP / skills 接入你的 agent
-```
-
-装好后 `gbc` 命令即在 PATH 上。完整上手（安装 → 接入 agent → 冒烟验证）见
-**[docs/zh/quick-start.md](./docs/zh/quick-start.md)**。
-
-想让 agent 替你接入？把 **[docs/zh/onboarding-agent.md](./docs/zh/onboarding-agent.md)** 交给它。
-
----
-
-> 🚧 **交互式 demo 施工中**：旧的演示套件已废弃，新的交互式演示正在筹备。目前请直接读文档上手。
-
----
-
-## 📚 文档
-
-| 你想 | 看这里 |
-|------|--------|
-| 装好并跑起来 | [快速开始](./docs/zh/quick-start.md) |
-| 懂 GBC 在保护什么 | [核心概念](./docs/zh/concepts.md) |
-| 在 GBC 下安全改代码 | [工作流](./docs/zh/workflow.md) |
-| 查命令 / 工具 / executor | [参考手册](./docs/zh/reference.md) |
-| 你是 agent，被要求接入 GBC | [Agent 上手](./docs/zh/onboarding-agent.md) |
-
+# Guarantee-Based Coding (GBC)
+
+**与其指望 AI 更聪明，不如让再笨的 agent 也改不坏你的代码。**
+
+**English version: [docs/en/README.md](docs/en/README.md)**
+
+GBC 把「这次改动会不会悄悄碰坏别处」从一种担心，变成可以当场验证的事实：你在意的行为被登记成
+一条条带测试的**保证（guarantee）**，每次改完一跑——全绿就安心，有红就精确告诉你碰坏了谁、谁在
+依赖它。
+
+---
+
+## 🚀 快速开始
+
+```bash
+pipx install guarantee-based-coding
+gbc setup        # 打印本地化接线指南：怎么把 MCP / skills 接入你的 agent
+```
+
+装好后 `gbc` 命令即在 PATH 上。完整上手（安装 → 接入 agent → 冒烟验证）见
+**[docs/zh/quick-start.md](./docs/zh/quick-start.md)**。
+
+想让 agent 替你接入？把 **[docs/zh/onboarding-agent.md](./docs/zh/onboarding-agent.md)** 交给它。
+
+---
+
+> 🚧 **交互式 demo 施工中**：旧的演示套件已废弃，新的交互式演示正在筹备。目前请直接读文档上手。
+
+---
+
+## 📚 文档
+
+| 你想 | 看这里 |
+|------|--------|
+| 装好并跑起来 | [快速开始](./docs/zh/quick-start.md) |
+| 懂 GBC 在保护什么 | [核心概念](./docs/zh/concepts.md) |
+| 在 GBC 下安全改代码 | [工作流](./docs/zh/workflow.md) |
+| 查命令 / 工具 / executor | [参考手册](./docs/zh/reference.md) |
+| 你是 agent，被要求接入 GBC | [Agent 上手](./docs/zh/onboarding-agent.md) |
+
 English docs: [docs/en/](./docs/en/)。
 
 安装后也能离线查询同版本手册：`gbc doc list --lang zh`、`gbc doc read quick-start --lang zh`、
 `gbc doc search "保证" --lang zh`。`--help` 仍用于查简短命令语法。
 
-当前仓库包含 **0.3.0 开发中的改动，尚未发布**；0.2.3 已发布。
+**0.4.0** 在 0.3.0 的命令职责与离线手册基础上，完善意图起草、保证测试和术语 / 决策复用工作流。
 0.3.0 中项目架构意图入口由 `gbc doc` 改为 `gbc intent`，MCP 的八个意图工具由 `doc_*`
 改为 `intent_*`，不保留旧别名。此后的 `gbc doc` 专门查询 GBC 手册。
 
----
-
-## 核心想法
-
-代码之间的依赖本质上是一组**保证**。模块 A 依赖模块 B，不是依赖它的实现细节，而是依赖它的某些
-行为承诺——返回值的类型、格式、语义。把这些保证从隐含变成**显式、可执行、可验证**，正确性的判定
-就从「AI 觉得自己改对了」变成「所有被依赖的保证仍通过」——一个可机械验证的布尔条件。
-
-![无 GBC vs 有 GBC](docs/assets/workflow-comparison.svg)
-
-GBC **不是**另一个要挑战 Cursor / Aider 的 AI 编程助手，而是填补它们在大型项目里缺的一环：
-**机器可判定的变更边界**。它与那些 agent 配合——改前查依赖树，改后必须跑通所有相关保证；也区别
-于 CI——CI 是事后的，GBC 是准入制的门禁，错误在落地前就被拦在 agent 的上下文里。
-
-完整概念、架构图、与已有概念（Design by Contract / 测试）的区别，见
-[核心概念](./docs/zh/concepts.md)。
-
----
-
-## 当前状态
-
-GBC 目前是一个可用的 Python 分发包（`pipx install guarantee-based-coding`），自身用 GBC 管理自己的
-`.gbc/`（dogfooding）：
-
-- ✅ 核心保证机制（具名 id、多对一、出生即绿、退休保护、反查）
-- ✅ 多语言 executor 配置
-- ✅ CLI + MCP 双接口（含意图文档 `gbc intent` 全进 MCP）
-- ✅ 意图文档子系统（`gbc intent` / web 编辑器）
-- ✅ 随包分发的接线指南（`gbc setup`）与 CLI-only agent 的 skill 包
-- ✅ 原子文件写入 + 备份
-
-
-**诚实的局限**：保护能力上限 = 测试质量（测试只走 happy path 就是虚假安全感）；依赖需主动登记，
-覆盖率随项目增长需持续投入；每次验证真实跑测试，有一定延迟。详见
-[核心概念 · 局限性](./docs/zh/concepts.md#局限性诚实地说)。
-
----
-
-## 许可
-
-本项目采用 [Apache-2.0](./LICENSE) 许可证。
-
-## 联系
-
-如果你对这个方向感兴趣，欢迎 star、issue 或者直接联系我。
+0.4.0 增加可配合 MCP 或 CLI 使用的 **gbc-workflow** skill：先查证据再起草意图、保护消费者
+行为的保证测试，以及术语与决策理由复用。**gbc-cli** 保留为命令适配器；用 `gbc setup` 查询
+随包路径，按客户端需要在项目内接入，不自动全局安装。详见[工作流](./docs/zh/workflow.md)。
+
+---
+
+## 核心想法
+
+代码之间的依赖本质上是一组**保证**。模块 A 依赖模块 B，不是依赖它的实现细节，而是依赖它的某些
+行为承诺——返回值的类型、格式、语义。把这些保证从隐含变成**显式、可执行、可验证**，正确性的判定
+就从「AI 觉得自己改对了」变成「所有被依赖的保证仍通过」——一个可机械验证的布尔条件。
+
+![无 GBC vs 有 GBC](docs/assets/workflow-comparison.svg)
+
+GBC **不是**另一个要挑战 Cursor / Aider 的 AI 编程助手，而是填补它们在大型项目里缺的一环：
+**机器可判定的变更边界**。它与那些 agent 配合——改前查依赖树，改后必须跑通所有相关保证；也区别
+于 CI——CI 是事后的，GBC 是准入制的门禁，错误在落地前就被拦在 agent 的上下文里。
+
+完整概念、架构图、与已有概念（Design by Contract / 测试）的区别，见
+[核心概念](./docs/zh/concepts.md)。
+
+---
+
+## 当前状态
+
+GBC 目前是一个可用的 Python 分发包（`pipx install guarantee-based-coding`），自身用 GBC 管理自己的
+`.gbc/`（dogfooding）：
+
+- ✅ 核心保证机制（具名 id、多对一、出生即绿、退休保护、反查）
+- ✅ 多语言 executor 配置
+- ✅ CLI + MCP 双接口（含意图文档 `gbc intent` 全进 MCP）
+- ✅ 意图文档子系统（`gbc intent` / web 编辑器）
+- ✅ 随包接线指南（`gbc setup`）、通用于 MCP / CLI 的工作流 skill 与 CLI 命令适配 skill
+- ✅ 原子文件写入 + 备份
+
+
+**诚实的局限**：保护能力上限 = 测试质量（测试只走 happy path 就是虚假安全感）；依赖需主动登记，
+覆盖率随项目增长需持续投入；每次验证真实跑测试，有一定延迟。详见
+[核心概念 · 局限性](./docs/zh/concepts.md#局限性诚实地说)。
+
+---
+
+## 许可
+
+本项目采用 [Apache-2.0](./LICENSE) 许可证。
+
+## 联系
+
+如果你对这个方向感兴趣，欢迎 star、issue 或者直接联系我。

guarantee_based_coding-0.4.0/docs/development/0.4.0-validation.md

@@ -0,0 +1,61 @@
+# 0.4.0 workflow validation
+
+Date: 2026-09-23. This record distinguishes source inspection, observed test results, and remaining validation. Publication status is tracked in `TODO.md`; a completed local check is not an upload receipt.
+
+## Scope and design basis
+
+The authorized change covers three workflow improvements: evidence-first intent drafting with consequential questions; tests that protect consumer behavior; and reuse of vocabulary and material decision reasons. It adds the transport-neutral `gbc-workflow` skill and updates guidance. It does not change the engine, command names, fixed manual topics, guarantee schema, born-green, or the project's existing approval authority. `gbc-cli` remains the CLI adapter.
+
+Source inspection found concrete weaknesses in the previous guidance:
+
+- `docs/en/workflow.md` and its Chinese counterpart favored non-null/type checks over exact assertions without asking which values consumers actually require.
+- `gbc/assets/i18n/texts/rules.*.md` encouraged reporting every step and asking whenever unsure, without first distinguishing discoverable facts from consequential choices.
+- The workflow's bad-fixture advice could be satisfied by a mock that bypasses the behavior under protection. Passing such an assertion does not demonstrate target-defect sensitivity.
+- Existing guidance already required defined terms and current-state intent. The change adds reuse of existing vocabulary and decision reasons rather than a mandatory new document convention.
+
+Existing project evidence supplied the examples: `.gbc/gbc/app/core/gbc.md` requires reverse dependency preservation until the final relevant symbol dependency is removed; `tests/test_guarantee_deps.py` checks the resulting retirement protection. `.gbc/gbc/app/intent/gbc.editor.py.json` distinguishes HTTP 400 for invalid paths from HTTP 200 with `meta: null` for missing metadata. The latter is contract inspection, not a new editor test run. The intent subsystem's existing `base` IO boundary supplies the vocabulary/decision example.
+
+Selective design inspiration comes from Matt Pocock's [grilling](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), [tdd](https://github.com/mattpocock/skills/blob/main/skills/engineering/tdd/SKILL.md), and [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md). GBC adopts fact investigation, meaningful behavior boundaries, and vocabulary/scenario/reason reuse within its own existing contracts. It does not require the source skills, exhaustive interviews, per-test-boundary approval, universal red-first, or a new CONTEXT/ADR document.
+
+## Historical defect replay: observed
+
+The isolated replay ran the unchanged existing `test_shared_guarantee_keeps_retirement_guard_until_last_symbol_removed` through GBC, covering both single-guarantee removal and whole-symbol removal. Its detailed local record is `.cache/workflow-eval-0.4.0/dependency-replay/REPORT.md`.
+
+| Stage | GBC CLI exit | Observed result |
+| --- | ---: | --- |
+| Born-green creation against current implementation | 0 | Registration accepted |
+| Explicit current implementation verification | 0 | 2 passed |
+| Exact historical module substituted | 1 | 2 failed at the target behavioral assertion |
+| Exact current module restored | 0 | 2 passed |
+
+The historical source was Git blob `aaaa8521bf3d193d29e5f9ca833a86e6ef5e7090^:gbc/app/core/guarantee.py`. Both failures occurred at test line 165: the consumer disappeared from `dependents_of` after only the first symbol dependency was removed. The failures were behavioral, not import, fixture, or temporary-directory failures. **The historical run stopped before the later retirement assertion; retirement itself was not executed in RED.** A separate final restored verification also returned 2 passed.
+
+The test file remained byte-identical. An observation-only `conftest.py` recorded the module path and hash from inside each actual test subprocess. Current/restored SHA-256 was `1f70804b46859927954b8a1f58cdf2350b83ab1dc5f298cdc268d71c8ba3b44e`; historical SHA-256 was `843a25b543d095e357331c807f1d771beb5cb532c604ff637ff11646306fecac`. The sandbox used a fresh executor, the dedicated Windows interpreter, explicit cwd/PYTHONPATH, controlled basetemp, disabled pytest cache and third-party plugin autoload. Tests ran only through GBC. Explicit verification logs contained no skipped, xfail, or warning entries.
+
+This establishes sensitivity of **one existing test** to its historical defect. It is a historical module inside the current package/environment, not a full historical-release execution. It does not establish universal workflow efficacy or the quality of newly authored tests. Raw logs, hashes, exact subprocess arguments, and the restoration procedure are in the local replay directory; that cache is supplementary evidence rather than a shipped artifact.
+
+## Forward workflow evaluation: observed, qualitative
+
+An independent evaluator read the new skill and handled three realistic requests without changing code or metadata, running tests, or actually questioning the user. The detailed local record is `.cache/workflow-eval-0.4.0/forward-evaluation.md`. The following preserves the substantive outcomes and durable evidence rather than relying only on that local cache:
+
+| Request | Observed judgment | Durable evidence examined by the evaluator |
+| --- | --- | --- |
+| Simplify file-meta responses to HTTP 200/null | Rejected flattening invalid paths and non-directory roots into the empty state; traced the frontend's error/empty distinction, reused existing guarantees, and proposed precise HTTP and view assertions. | `gbc/app/intent/editor.py` file-meta handler; `gbc/app/intent/base.py:file_meta_view`; `gbc/assets/editor/js/api.js`, `actions.js`, `editor-view.js`; `tests/test_intent_editor_api.py` |
+| Preserve concurrent editor changes and allow explicit conflict overwrite | Discovered existing field-level three-way merge and force handling; preserved the base IO / HTTP surface boundary and reused selective-write, preservation, and conflict guarantees. Identified UI detail, concurrent writes, and changes occurring after the conflict prompt as distinct possible follow-ups. | `.gbc/gbc/app/intent/gbc.md`; `gbc/app/intent/base.py:save_flat`; `gbc/assets/editor/js/actions.js`; `tests/test_intent_flat.py`; registered base/editor guarantees |
+| Rename heavy as timeout and describe GREEN as every test passing | Rejected both semantic changes using existing definitions and implementation. Proposed clearer wording in existing docs, retaining skipped counts and distinguishing cost rank, timeout, gate result, and execution coverage; did not require a new ADR/CONTEXT file. | `.gbc/gbc.md`; `docs/en/concepts.md`, `docs/zh/concepts.md`; `gbc/app/models/meta.py`; `gbc/app/models/verify.py:VerifySummary.green`; `gbc/app/core/guarantee.py`; `tests/test_cli_commands.py` |
+
+The file-meta inspection also found an important boundary: current `meta: null` means no displayable view, including existing handling of damaged/unreadable metadata, not exclusively an unregistered file. A future change must not silently narrow that compatibility behavior. Existing null-versus-error examples in the manual illustrate the missing-metadata case without claiming it is the only null case.
+
+For the save request, the evaluator's suggested UI/conflict-version/concurrency refinements are **unapproved proposals outside 0.4.0**, not new implementation commitments. This evaluation did not authorize expanding the release. Test plans described in the responses were not executed, and the inspected editor paths were not retested by these dry-runs.
+
+The outputs show evidence-first judgment, consumer-oriented assertions, reuse of terminology/contracts, and awareness of approval boundaries in these three cases. There was no before/after control, productivity measurement, or runtime implementation assessment. The evaluator used the new guidance, so this is limited qualitative forward evidence, not a universal efficacy claim or proof of future agent compliance.
+
+## Packaging and final acceptance
+
+Top-level verification through GBC covered seven affected providers and twelve guarantees: **12 passed, 0 failed, 0 skipped**. The providers were assets, documentation base/CLI, translation, interface CLI/MCP, and the entry point. Both graph and intent consistency checks passed. This is affected-scope acceptance, not a claim that every repository test was executed. Exact source-gate results are preserved locally in `.cache/release-receipts-0.4.0/source-gates.json`.
+
+Two temporary GBC guarantees ran the official skill-creator `quick_validate` against `gbc-workflow` and `gbc-cli`; both passed. Earlier bounded asset self-verification reported 9 passed. The sdist build, wheel build from that sdist, `twine check --strict`, and installed-environment `pip check` all passed.
+
+The built 0.4.0 wheel was installed into a separate virtual environment. The observed `gbc.__file__` resolved to that environment's `site-packages`, and `__version__` was 0.4.0. This environment reused existing system dependencies; the GBC package itself came from its own wheel, not the editable source checkout. A registered GBC guarantee ran **13 installed smoke checks and passed**, including real module/console entry points, CLI migration behavior, all ten English/Chinese manual documents across five fixed topics, localized setup/rules, packaged editor/i18n/skill resources, all four workflow skill files with resolved local reference links, a persistent intent round trip, consistency exit codes, and a real MCP stdio session listing 30 tools. The raw installed gate output is `.cache/release-receipts-0.4.0/installed-gate.log`.
+
+The source distribution includes this validation report through an explicit manifest entry. The observations above concern the verified wheel payload; a rebuild that only adds source-distribution documentation requires a payload identity check before those results are reused. Publication status is tracked separately in `TODO.md`; local validation results are not publication receipts.