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

guarantee_based_coding-0.4.0/MANIFEST.in

@@ -0,0 +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.2.3 → guarantee_based_coding-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guarantee-based-coding
-Version: 0.2.3
+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
@@ -61,6 +61,17 @@ gbc setup        # 打印本地化接线指南：怎么把 MCP / skills 接入
 
 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.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)。
+
 ---
 
 ## 核心想法
@@ -87,9 +98,9 @@ GBC 目前是一个可用的 Python 分发包（`pipx install guarantee-based-co
 
 - ✅ 核心保证机制（具名 id、多对一、出生即绿、退休保护、反查）
 - ✅ 多语言 executor 配置
-- ✅ CLI + MCP 双接口（含意图文档 `gbc doc` 全进 MCP）
-- ✅ 意图文档子系统（`gbc doc` / web 编辑器）
-- ✅ 随包分发的接线指南（`gbc setup`）与 CLI-only agent 的 skill 包
+- ✅ CLI + MCP 双接口（含意图文档 `gbc intent` 全进 MCP）
+- ✅ 意图文档子系统（`gbc intent` / web 编辑器）
+- ✅ 随包接线指南（`gbc setup`）、通用于 MCP / CLI 的工作流 skill 与 CLI 命令适配 skill
 - ✅ 原子文件写入 + 备份
 
 

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

@@ -1,87 +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/)。
 
----
-
-## 核心想法
-
-代码之间的依赖本质上是一组**保证**。模块 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 doc` 全进 MCP）
-- ✅ 意图文档子系统（`gbc doc` / web 编辑器）
-- ✅ 随包分发的接线指南（`gbc setup`）与 CLI-only agent 的 skill 包
-- ✅ 原子文件写入 + 备份
-
-
-**诚实的局限**：保护能力上限 = 测试质量（测试只走 happy path 就是虚假安全感）；依赖需主动登记，
-覆盖率随项目增长需持续投入；每次验证真实跑测试，有一定延迟。详见
-[核心概念 · 局限性](./docs/zh/concepts.md#局限性诚实地说)。
-
----
-
-## 许可
-
-本项目采用 [Apache-2.0](./LICENSE) 许可证。
-
-## 联系
-
-如果你对这个方向感兴趣，欢迎 star、issue 或者直接联系我。
+安装后也能离线查询同版本手册：`gbc doc list --lang zh`、`gbc doc read quick-start --lang zh`、
+`gbc doc search "保证" --lang zh`。`--help` 仍用于查简短命令语法。
+
+**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)。
+
+---
+
+## 核心想法
+
+代码之间的依赖本质上是一组**保证**。模块 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/build_support.py

@@ -0,0 +1,29 @@
+"""Copy the canonical offline manual into built packages, never the source tree."""
+from pathlib import Path
+
+from setuptools.command.build_py import build_py
+
+
+MANUAL_LANGUAGES = ("en", "zh")
+MANUAL_TOPICS = ("quick-start", "concepts", "workflow", "reference", "onboarding-agent")
+
+
+class BuildPy(build_py):
+    """Include the fixed manual topics when building directly or from an sdist."""
+
+    def _manual_files(self):
+        root = Path(__file__).resolve().parent
+        for language in MANUAL_LANGUAGES:
+            for topic in MANUAL_TOPICS:
+                relative = Path(language) / f"{topic}.md"
+                yield root / "docs" / relative, Path(self.build_lib) / "gbc/assets/docs" / relative
+
+    def run(self):
+        super().run()
+        for source, destination in self._manual_files():
+            self.mkpath(str(destination.parent))
+            self.copy_file(str(source), str(destination))
+
+    def get_outputs(self, include_bytecode=True):
+        outputs = super().get_outputs(include_bytecode=include_bytecode)
+        return outputs + [str(destination) for _, destination in self._manual_files()]

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.

guarantee_based_coding-0.4.0/docs/en/concepts.md

@@ -0,0 +1,229 @@
+# Core Concepts
+
+> Language: [简体中文](../zh/concepts.md) | **English**
+
+This page explains GBC's core concepts — what it actually protects, and how. To get hands-on first
+see [quick-start.md](./quick-start.md); for the workflow see [workflow.md](./workflow.md).
+
+---
+
+## The problem: when changing code, how do you know what must not break?
+
+A coding agent's core failure mode isn't writing wrong code — that can be retried. The real problem
+is **silently breaking the implicit assumptions of existing code**. When an agent changes a
+function's return format, other modules that depend on that format can quietly break — with no
+mechanism telling the agent those dependencies exist, and none stopping it when the break happens.
+
+## The core idea: turn implicit dependencies into explicit guarantees
+
+Dependencies between code are essentially a set of **guarantees**. Module A depends on module B not
+on B's implementation details, but on some of B's behavioral promises — the type, format, semantics
+of return values.
+
+Make those guarantees **explicit, executable, and verifiable** and you get:
+
+- Every change mechanically verifies whether all guarantees still hold;
+- When a guarantee breaks, you know exactly which one and who depends on it;
+- **Correctness shifts from "the AI thinks it got it right" to "every depended-on guarantee still
+  passes"** — a mechanically verifiable boolean.
+
+![Without GBC vs with GBC](../assets/workflow-comparison_en.svg)
+
+---
+
+## Architecture
+
+![GBC architecture](../assets/architecture_en.svg)
+
+### Three design principles
+
+1. **Zero source intrusion**: all metadata lives under the target project's `.gbc/` directory —
+   no source edits, no decorators/annotations.
+2. **Tests are user-owned**: GBC does not generate, store, or manage the test files themselves.
+   You organize tests your own way in your own project; GBC only **records which test backs which
+   guarantee, runs them, and aggregates results**.
+3. **Language-agnostic**: any language and test framework, via executor config.
+
+---
+
+## Two layers of contract
+
+GBC pins down the impact of a change with two layers:
+
+1. **Intent layer**: in `.gbc/**/gbc.md`. Natural language (Markdown) defining a folder's role,
+   internal constraints, and architectural intent. It is the source of truth — it tells an agent
+   "what you should and shouldn't do here." **Human-held**; the agent only drafts.
+2. **Guarantee layer**: in `.gbc/**/*.json`. Executable, test-backed concrete behavioral promises.
+
+When changing code, the agent must honor both the intent layer (don't violate the original purpose)
+and the guarantee layer (don't break concrete behavior).
+
+How to write intent docs (the three sections: intent / internal constraints / files) is in
+[workflow.md](./workflow.md#writing-intent-docs).
+
+---
+
+## The intent document system (gbc.md)
+
+The behavior layer guards "behavior doesn't break"; the intent layer guards "direction doesn't
+drift" — both are pre-change defenses, but of different natures: guarantees are mechanically
+verifiable (born-green / verify), while intent relies on **human sign-off + tool consistency**.
+
+### What it is
+
+Each folder's intent lives in `.gbc/<path>/gbc.md`, made of three sections that are really
+**visibility scopes**:
+
+| Section | Answers | Who needs to know |
+|---|---|---|
+| **Intent** | What this is and why it exists | Outside (public contract) |
+| **Internal constraints** | What it must / must never do | Internal coordination (package-private) |
+| **Files** | Subfolders + file list, one role line each | Only the file itself (private) |
+
+When unsure whether something is "intent vs constraint", ask per sentence: "who needs to know
+this?". It only records the **current state** (what it is now, what it must do now), not diffs
+against the past — phase words, roadmaps, and migration narratives are drift bait.
+
+### How it is maintained
+
+- **Hierarchy**: a subfolder's intent auto-projects into its parent's entry; parent/child
+  consistency is a **deterministic constraint** maintained by the `gbc intent` tools (`intent check`
+  reports DRIFT / ORPHAN, `intent sync` repairs).
+- **The only compliant entry**: `gbc intent` (CLI / MCP intent tools). Never hand-edit — hand-editing
+  drifts the deterministic constraint, downgrading "verifiable truth" to "best-effort habit".
+- **Spec-first**: investigate the relevant evidence first. If existing intent covers the task,
+  use it; if it must change, draft the delta, obtain the approval required by the project's rules,
+  and land it before implementation. See [workflow.md](./workflow.md) and the **gbc-workflow** skill
+  for consequential questions, vocabulary reuse, and preserving decision reasons with MCP or CLI.
+
+### How it relates to the guarantee layer
+
+The intent layer answers "why, and what are the boundary obligations" — **not mechanically
+verifiable**; it relies on human sign-off + intent check. The guarantee layer answers "does the
+behavior still hold" — **mechanically verifiable**. The former prevents directional drift, the
+latter prevents behavioral breakage; they complement each other.
+
+### How to treat it
+
+It is a **snapshot of the current state, not a sacred text**: born to prevent drift, not to
+freeze the architecture. Found it wrong, or it starts blocking reasonable evolution? Draft the
+delta → human sign-off → commit through the tools — legitimate evolution, not a violation.
+Piling responsibilities into one file instead of changing the intent (a god file) is exactly the
+drift-guard mechanism turned upside down. For an agent: **read it (map before acting), obey it
+(stay in scope), propose changes to it (through the official channel) — but don't own it.**
+
+---
+
+## Core terms
+
+- **Provider**: the source file that offers a guarantee (e.g. `src/llm_client/client.py`).
+- **Consumer / Dependent**: a file depending on a guarantee (e.g. `src/conversation/manager.py`).
+- **Guarantee**: a **named** behavioral promise (id shaped `<symbol>.<behavior>`, path-free),
+  backed by a test + a description. **Multiple consumers may share one guarantee.**
+- **Executor**: config defining how to run tests (command template, working dir, env vars, ...).
+
+### Two tiers of dependency edge
+
+- **Symbol dependency (free)**: depends only on a signature or a symbol existing; no test, no
+  reverse edge.
+- **Named guarantee dependency**: depends on concrete behavior. Registered **both ways** via the
+  reverse-edge mechanism — the provider's `provides[id].dependents` ⇄ the consumer's
+  `depends_on[].guarantees`, kept in sync by the tooling.
+
+> Default to free symbol dependencies; upgrade to a named guarantee **only** when you depend on
+> concrete behavior (not just a signature), and upgrade lazily.
+
+---
+
+## The unbreakable core invariants
+
+Whichever surface you swap in — CLI / MCP / a future GUI — these engine-level invariants hold:
+
+- **Guarantees are first-class; identity is a named id** (e.g. `get_config.never_none`, ≠ a test
+  path).
+- **Many-to-one**: one guarantee can be shared by many consumers; hitting an existing one appends
+  a dependent and reuses it, rather than writing a second test.
+- **Two-section self-contained meta**: one `.gbc` json per code file, `provides` (as provider) +
+  `depends_on` (as consumer).
+- **Born-green**: on create / test change the test runs on the spot, and registration is refused
+  if it fails — the one integrity invariant, with no backdoor.
+  Passing this gate does not establish defect sensitivity; the test must protect the consumer's
+  actual behavior, including exact values when contractual (see [workflow.md](./workflow.md#narrow-test-rule)).
+- **Retirement protection**: a guarantee with dependents refuses deletion.
+- **Binary gate**: a test that ran is pass or fail; one that was skipped (heavy) is reported loudly
+  but never turns the gate red. Green = no failures.
+- **heavy** is a cost rank (int) + an auto-run authorization: batch runs only heavy ≤ threshold;
+  a named verify ignores it.
+
+### What a meta file looks like
+
+`client.py` (provider), at `.gbc/src/llm_client/gbc.client.py.json`:
+
+```json
+{
+  "provides": {
+    "chat.content_is_str": {
+      "desc": "chat()'s result['content'] is a str; manager concatenates it into history directly",
+      "test": "tests/test_client_content_is_str.py::test_content_is_str",
+      "executor": "pytest-myproject",
+      "heavy": 0,
+      "dependents": ["src/conversation/manager.py"]
+    }
+  }
+}
+```
+
+`manager.py` (consumer), at `.gbc/src/conversation/gbc.manager.py.json`, records the reverse edge:
+
+```json
+{
+  "depends_on": [
+    {
+      "symbol": "src/llm_client/client.py:chat",
+      "guarantees": ["chat.content_is_str"]
+    }
+  ]
+}
+```
+
+Both directions are written by the tools (CLI / MCP); you don't hand-edit them.
+
+---
+
+## What it is not
+
+GBC is **not** another AI coding assistant challenging Cursor or Aider. It fills the piece they lack
+in large, complex projects: a **machine-verifiable boundary for change**.
+
+- **Works with Cursor / Aider**: they're good at finding and editing code, but lack explicit
+  awareness of cross-module dependencies and thus break things silently. GBC gives them a
+  "constraint guardrail" — check the dependency tree before, and pass all relevant guarantees
+  after.
+- **Different from CI**: CI is after-the-fact — it catches errors after commit. GBC is
+  admission-based — a gate inside the agent's workflow, catching errors before they land, inside
+  the agent's context.
+
+### How it differs from existing ideas
+
+**"Isn't this just Design by Contract?"** Traditional contract programming has a module declare its
+**own** contract. GBC's key differences: a guarantee is **registered by the dependent** ("what
+behavior of yours I rely on" comes from the user), it **carries attribution** (who registered it
+and why, so breaking it pinpoints impact), and it **targets AI agents** (a boundary for change,
+not a runtime check).
+
+**"Isn't this just testing?"** Technically a guarantee is a test file. Conceptually: it **carries
+attribution** (records who registered it, which cross-module dependency it protects), it's a
+**live gate** (not run after-the-fact in CI, but an admission condition when the agent changes
+code), and it's **user-managed** (GBC manages the metadata and running, not the test files
+themselves).
+
+---
+
+## Limitations (stated honestly)
+
+- **Protection ceiling = test quality**: GBC only catches what a test can catch. Tests that only
+  walk the happy path make guarantees a false sense of safety. (Happy-path-only tests are the
+  textbook example.)
+- **Manual registration cost**: dependencies must be registered by an agent or human. The per-edge
+  cost is small, but coverage takes ongoing investment as the project grows.
+- **Run performance**: every verification really runs tests, so there's some latency cost.