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

guarantee_based_coding-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+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

{guarantee_based_coding-0.2.2 → guarantee_based_coding-0.3.0}/PKG-INFO

@@ -1,108 +1,115 @@
-Metadata-Version: 2.4
-Name: guarantee-based-coding
-Version: 0.2.2
-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
-Project-URL: Homepage, https://github.com/Jesse-x86/guarantee-based-coding
-Project-URL: Repository, https://github.com/Jesse-x86/guarantee-based-coding
-Keywords: guarantee,testing,ai-coding,mcp,code-safety
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: typer[all]
-Requires-Dist: pydantic
-Requires-Dist: mcp<2.0,>=1.0
-Dynamic: license-file
-
-# 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 或者直接联系我。
+Metadata-Version: 2.4
+Name: guarantee-based-coding
+Version: 0.3.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
+Project-URL: Homepage, https://github.com/Jesse-x86/guarantee-based-coding
+Project-URL: Repository, https://github.com/Jesse-x86/guarantee-based-coding
+Keywords: guarantee,testing,ai-coding,mcp,code-safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]
+Requires-Dist: pydantic
+Requires-Dist: mcp<2.0,>=1.0
+Dynamic: license-file
+
+# 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.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 或者直接联系我。

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

@@ -40,6 +40,13 @@ 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.3.0 开发中的改动，尚未发布**；0.2.3 已发布。
+0.3.0 中项目架构意图入口由 `gbc doc` 改为 `gbc intent`，MCP 的八个意图工具由 `doc_*`
+改为 `intent_*`，不保留旧别名。此后的 `gbc doc` 专门查询 GBC 手册。
+
 ---
 
 ## 核心想法
@@ -66,8 +73,8 @@ GBC 目前是一个可用的 Python 分发包（`pipx install guarantee-based-co
 
 - ✅ 核心保证机制（具名 id、多对一、出生即绿、退休保护、反查）
 - ✅ 多语言 executor 配置
-- ✅ CLI + MCP 双接口（含意图文档 `gbc doc` 全进 MCP）
-- ✅ 意图文档子系统（`gbc doc` / web 编辑器）
+- ✅ CLI + MCP 双接口（含意图文档 `gbc intent` 全进 MCP）
+- ✅ 意图文档子系统（`gbc intent` / web 编辑器）
 - ✅ 随包分发的接线指南（`gbc setup`）与 CLI-only agent 的 skill 包
 - ✅ 原子文件写入 + 备份
 

guarantee_based_coding-0.3.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.3.0/docs/en/concepts.md

@@ -0,0 +1,225 @@
+# 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**: draft the intent, get human sign-off, commit it, then implement against the
+  written gbc.md.
+
+### 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.
+- **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.

guarantee_based_coding-0.3.0/docs/en/onboarding-agent.md

@@ -0,0 +1,114 @@
+# Onboarding Instructions for Agents
+
+> Language: [简体中文](../zh/onboarding-agent.md) | **English**
+
+Hi. If you're reading this, you're working inside a project and your human wants to use GBC — glad
+you're here to wire it up. It's not much: confirm the tool is ready, wire it into the current
+project, then work by the recommended workflow.
+
+Two roles throughout:
+
+- **The working project** — the project you're in right now; GBC gets wired in here.
+- **The GBC tool** — a standalone tool already installed as the `gbc` command. You call it and
+  point it at the working project.
+
+---
+
+## ① Confirm the tool is ready
+
+GBC ships as a standalone command-line tool. Confirm it's installed:
+
+```bash
+gbc --help
+```
+
+If not, have your human install it (or install it yourself when authorized):
+`pipx install guarantee-based-coding`. Once installed, the `gbc` command is on PATH and the same
+install is reused across projects.
+
+> For a localized wiring guide (where the endpoints / skill files are), run `gbc setup` any time.
+
+---
+
+## ② Wire GBC into the current project
+
+GBC's abilities reach you through two paths — use whichever you support (or both):
+
+### Path A — MCP (recommended)
+
+Register GBC's MCP server for yourself, pointed at the working project. Start command:
+
+```
+gbc mcp up <absolute path to the working project root>
+```
+
+Register it however your framework adds MCP servers (for Claude Code, a `.mcp.json` in the project
+root). Reconnect / restart afterward and the tools appear. MCP exposes the
+guarantee engine + intent documents (`intent_*` tools), plus the offline manual
+(`doc_list` / `doc_read` / `doc_search`). Read `gbc doc read onboarding-agent --lang en` when
+you need this guide from an installed package; use `gbc intent` to manage project architecture.
+
+### Path B — Skills
+
+Run `gbc setup`; it prints the absolute path to the bundled skill files. Copy them into wherever
+your framework discovers skills (GBC materializes the files, you place them). The `gbc-cli` skill
+teaches you to use every `gbc` command.
+
+### Once per project
+
+GBC points at the working project, and the test executor follows that project's environment and
+language — switch projects and it naturally needs reconfiguring. So re-run this wiring once per new
+project (a few minutes).
+
+---
+
+## ③ Register an executor + smoke test
+
+- Register a test executor (how to run tests): see [reference.md](./reference.md#executor-config).
+  Give it a **project-scoped name** (`pytest-<project>`), since executors are shared across
+  projects by name.
+- Smoke test: run `gbc tree show` or `gbc doctor check` (over MCP, call `tree` / `check_consistency`).
+  If it returns, you're wired.
+
+---
+
+## ④ Before you touch code: don't let guarantees rot into fake safety
+
+Wiring only connects the tools — it can't stop you from making them lie. A guarantee only protects
+what it can actually catch, and a handful of moves quietly turn it into theater. These three are
+worth carrying from day one, because they fail **silently** (full trap list in
+[workflow.md](./workflow.md#a-few-traps-that-fail-silently)):
+
+- **A guarantee test must be able to go red**: a fixture that only walks the happy path stays green
+  even after the behavior breaks = guarding nothing.
+- **Promote the behavior you actually depend on**: non-null / non-empty / raises-on-X / ordering /
+  idempotence are behavior, not signature, and a free symbol dependency has no test guarding them.
+- **When a guarantee goes red, restore it or announce it — never loosen the test**: relaxing /
+  retiring a test to turn green silently downgrades a real guarantee into fake safety.
+
+Every time you register a dependency or a guarantee, ask: **"If the behavior I care about broke
+right now, would a test actually go red?"** If no, fix that first.
+
+---
+
+## ⑤ Hierarchy and authority: stay within your scope
+
+- **Top-level agent (architect / lead)**: you lead the intent. Draft `gbc.md` changes through
+  `gbc intent` (MCP intent tools / CLI) — never hand-edit — bound each subtask, review the local
+  contracts it registers, and do the final integration check after subtasks return.
+- **Subagent (task worker)**: a focused implementer. It reads `gbc.md` without changing intent,
+  maintains any interface artifact required by that language/project (a Python project may use
+  `.pyi`) with the code, and owns the local GBC contracts introduced by its implementation:
+  query/reuse guarantees, register actual dependencies, and when a needed
+  guarantee is missing, write a narrow test that can genuinely go red and create it. Then self-prove with `verify_provider` /
+  `verify_guarantee`. An unregistered behavioral dependency means the task is not done.
+- **Guardrails**: if your framework supports hooks (e.g. Claude Code's `pre-tool-use`), block every
+  agent from hand-editing GBC-managed files, and block subagents from changing intent or performing
+  unauthorized cross-scope operations such as retiring/disabling guarantees or refactoring other
+  files. **Do not blanket-block dependency registration, guarantee creation, or verification for
+  subagents.** Enforcement comes from the framework, independent of MCP vs CLI.
+
+---
+
+The full "working safely under GBC" is in [workflow.md](./workflow.md); a command / tool cheat sheet
+is in [reference.md](./reference.md); core concepts are in [concepts.md](./concepts.md).