@anchorlock/cli 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.2.0
+
+- Kernel is now `@anchorlock/core` >= 0.6.0 (was `@keelforge/spec-forge`). A sibling `anchorlock-core` checkout is used first when present.
+- `npm test` works on Windows and on Node 22+.
+
+## 0.1.9
+
+- Docs: several coding agents is not a third path. Share one pin and one check; field scope still moves only when the backend releases.
+- Product page: `#start` is a long section; the 16% intersection reveal left it invisible and left a blank footer. Content is visible by default; multi-agent is its own section.
+
+## 0.1.8
+
+- `anchor repin --from <new openapi.json> --tag vX.Y.Z`: swap the whole pin when the backend ships a release. Keeps the existing `url` (tag substituted) and `change`, recomputes the hash, no `--force` needed, warns when the artifact is byte-identical.
+- `anchor pin --change <id>` records which requirement moved the contract; `check` prints `pin   v1.5.0 · change PROJ-123` so nobody has to open the file.
+- Docs answer the second round: field scope moves when the backend releases, never by hand-editing the pin. Agents must not repin to turn a red gate green.
+- Path B drafts state what to keep (names crossing a process boundary) and what to delete (functions, locals, types, single-file names).
+
+## 0.1.7
+
+- FAIL output tells humans to fix code (not the pin) and paste the log to the coding agent.
+- Product page LIVE CHECK matches FAIL/PASS plus the next hint; Path A check commands include `--strict --require-hash`.
+- `--strict` ignores identifiers used only as function calls or declarations (`lookupMine()`, `encodeURIComponent()`), so FAIL lists field names an agent can actually fix.
+- Path A (pinned OpenAPI in the consumer repo) is the product. `anchor init` installs the skill only and does not write a field list.
+- Agents must not author `constraints.json` from a PRD. Path B is draft-from-code plus a human confirm.
+- Consumer CI snippets use `--strict --require-hash`.
+
+## 0.1.6
+
+- Check always prints `scan` (path + file count). Humans use `--changed` (git edits); do not pick a single source file.
+- `--src` is for CI / Agent only.
+
+## 0.1.5
+
+- `anchor check --src` no longer switches to undeclared mode. `--src` is scan root only; `--strict` is the full gate.
+
+## 0.1.4
+
+- `anchor init` writes empty `units: []`. Demo field names stay in `anchor demo`, not in a real repo.
+
+## 0.1.3
+
+- `anchor check` maps `units[].aliases` to the unit `id` (`orderId` / `order_sn` / quoted `单号` → `order_no`).
+- `anchor demo` (and `npm run demo`) is that story: red then green.
+- `pin.json` includes `path` so check can run offline when the artifact is still on disk.
+- CI snippets: `ci/check-contract.github.yml` / `ci/check-contract.gitlab.yml`.
+- `anchor pin --from openapi.json --url … --tag vX.Y.Z` writes `pin.json` (sha256).
+- Kernel: `@keelforge/spec-forge` >= 0.5.19.
+
+## 0.1.2
+
+- Two onboarding paths: have OpenAPI (pin + `check`) or scan code (`anchor init --from-code` → `constraints.json`).
+- `anchor constraints --from <openapi|url|pin.json>` projects OpenAPI → `constraints.json` for SemanticAnchor.
+- `anchor init --from-code` drafts `constraints.json` from source (aliases included). Blank template is `constraints --init` only.
+- Kernel: `@keelforge/spec-forge` >= 0.5.17.
+
+## 0.1.1
+
+- `anchor check --contract` accepts a tagged OpenAPI URL or `pin.json` (`url` + `hash` + `version`).
+- `--hash sha256:…` / `--require-hash`. Frontend pins the release artifact; does not clone the backend repo.
+
+## 0.1.0
+
+- First wedge: `anchor check` and `anchor init --from-code` (draft).
+- Kernel: `@keelforge/spec-forge` >= 0.5.15 (`checkNames` / `draftIds`).
+- No compile / pack / demand-repo commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anchorlock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# Anchorlock
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Consumer repos check field names against a pinned OpenAPI — not a list the coding agent wrote.**
+
+Think: ESLint for API field names at merge. The spec comes from the **backend tagged artifact**. Same-repo Java/TS that the compiler already checks is not the point.
+
+| | When | Command |
+|---|---|---|
+| **Haul** | Before merge in the **frontend / client / test** repo | `anchor check --contract pin.json --src src --strict --require-hash` |
+| **Cast** | Agent about to write a file | SemanticAnchor MCP: `bind` / `verify_usage` on a `constraints.json` **projected from that same OpenAPI** |
+| Project | Prepare the file for cast | `anchor constraints --from pin.json` — this is **not** the cast |
+
+Do not invent `constraints.json` from a PRD. The agent that writes the list is the agent that writes the code; that is not a lock.
+
+- Product page (Chinese): [`public/index.html`](./public/index.html)
+- CLI guide (Chinese): [`docs/usage.md`](./docs/usage.md)
+
+## Path A (default) — you already have OpenAPI
+
+Backend **build-exports** `openapi.json` (Springdoc / Nest / FastAPI). Tag a release. Do not hand-write the spec. Do not point at a live `/v3/api-docs`.
+
+In the **consumer** repo, once:
+
+```bash
+npm i -D @anchorlock/cli
+npx anchor init    # agent skill only — no field list
+```
+
+Pin the tagged download URL (not a git clone of the backend):
+
+```bash
+npx anchor pin --from dist/openapi.json \
+  --url https://…/releases/v1.4.0/openapi.json --tag v1.4.0 \
+  -o contracts/order.pin.json
+npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+`orderId` / `order_sn` vs spec `order_no` → **red**. Same name as the spec → **green**. Fix the code, not the pin.
+
+| `--contract` | What it is |
+|---|---|
+| `openapi.json` | Local copy of the spec |
+| `https://…/openapi.json` | Tagged release artifact (pass `--hash`) |
+| `order.pin.json` | `{ url, hash, version, path }` — `check` uses `path` if that file is still on disk; otherwise it downloads `url` |
+
+Copy [`ci/check-contract.github.yml`](./ci/check-contract.github.yml) into the consumer repo.
+
+### Second round — the backend shipped a new tag
+
+Field scope moves when the **backend releases**, not when you and the agent talk about a ticket. Never hand-add a field to the pin; swap the whole thing:
+
+```bash
+npx anchor repin --from ../order-api/dist/openapi.json --tag v1.5.0 --change PROJ-123
+git diff contracts/order.pin.json    # version + hash changed
+npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+`repin` keeps the existing `url` (swapping the tag inside it) and `change`, recomputes the hash, and overwrites without `--force`. Every `check` prints what you are locked to:
+
+```
+  pin   v1.5.0 · change PROJ-123
+```
+
+History is `git log contracts/order.pin.json`. A coding agent must never `repin` to turn a red gate green — that is the human's call, driven by a release.
+
+### Several agents (not a third path)
+
+Same pin, same check. More agents does not mean more contracts. Backend ships a tagged OpenAPI; a human `repin`s; frontend / client / test agents only change source. Paste FAIL to the agent that drifted. Do not let each agent draft its own list.
+
+Need SemanticAnchor? Project, then point SA at the file:
+
+```bash
+npx anchor constraints --from contracts/order.pin.json -o constraints.json
+```
+
+## Path B — no OpenAPI yet
+
+Draft **once** from a **narrow** tree. A human confirms ids. Other repos only `check` that file.
+
+```bash
+npx anchor init --from-code path/to/one-module -o constraints.json
+# human deletes junk, confirms id / aliases
+npx anchor check --contract constraints.json --src src
+```
+
+Keep names that cross a process boundary (HTTP JSON keys, SQL columns, MQ payloads, stored fields). Delete function names, locals, type names, framework words, and anything seen in a single file. When unsure, delete: a missing lock costs you nothing, a wrong lock makes CI demand changes to correct code.
+
+Do not `init --from-code` in every repo. Two drafts (`orderStatus` vs `order_status`) both go green and still disagree at runtime.
+
+## What this is not
+
+| Not this | Use instead |
+|---|---|
+| Shape / enum values at write time | SemanticAnchor `verify_usage` |
+| Demand-repo authoring / compile / pack | `@anchorlock/core` |
+| A field list the coding agent wrote from the ticket | Path A pin, or Path B + **human** confirm |
+| Company defaults, design tokens | your org's spec CLI (e.g. `@your-org/spec-cli`) |
+
+## Install
+
+Node.js 18+. Kernel: `@anchorlock/core` ≥ 0.6.0, installed with the CLI.
+
+```bash
+npm install -D @anchorlock/cli
+npx anchor --help
+```
+
+```bash
+npm run preview   # product page → http://localhost:4174
+```
+
+## License
+
+MIT
+
+## Publish (maintainers)
+
+1. Publish the kernel: in `anchorlock-core`, `npm test && npm publish --access public`.
+2. Here, `npm install` so the dependency resolves from the registry, then `npm test && npm publish --access public`.

package/bin/anchor.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runCli } = require('../lib/cli');
+
+runCli(process.argv)
+  .then(function (code) {
+    if (typeof code === 'number' && code !== 0) process.exit(code);
+  })
+  .catch(function (err) {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write('\nanchor  ' + msg + '\n');
+    process.stderr.write('hint: anchor --help\n');
+    process.exit(1);
+  });

package/ci/check-contract.github.yml

@@ -0,0 +1,25 @@
+# 消费仓：对照钉死的契约扫源码
+#
+# 提交 contracts/order.pin.json（url + hash + version，可选 path）。
+# 不要对生产 /v3/api-docs 扫。私有制品把只读 token 放进 ANCHOR_CONTRACT_TOKEN 或 SPEC_CONTRACT_TOKEN。
+
+name: check-contract
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  field-names:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Field-name gate
+        env:
+          ANCHOR_CONTRACT_TOKEN: ${{ secrets.ANCHOR_CONTRACT_TOKEN }}
+          SPEC_CONTRACT_TOKEN: ${{ secrets.SPEC_CONTRACT_TOKEN }}
+        run: npx --yes @anchorlock/cli check --contract contracts/order.pin.json --src src --strict --require-hash

package/ci/check-contract.gitlab.yml

@@ -0,0 +1,12 @@
+# 消费仓：对照钉死的契约扫源码（GitLab）
+#
+# 提交 contracts/order.pin.json。私有 Release 把只读 token 放进 CI 变量 ANCHOR_CONTRACT_TOKEN。
+
+check-contract:
+  stage: test
+  image: node:20
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+  script:
+    - npx --yes @anchorlock/cli check --contract contracts/order.pin.json --src src --strict --require-hash

package/docs/usage.md

@@ -0,0 +1,320 @@
+# Anchorlock CLI 使用说明
+
+包：`@anchorlock/cli` · 命令：`anchor`  
+本包装的是**收紧**：消费仓合并前，对照一份**仓外权威**的契约扫字段名。权威来自后端发版的 OpenAPI（钉 hash），不是本仓 Agent 根据需求编的名单。
+
+**抛锚**是写盘前的 SemanticAnchor MCP（`bind` / `verify_usage`）。有 OpenAPI 时，先 `anchor constraints --from` 投影出它要吃的 `constraints.json`；投影本身不是抛锚。
+
+需要 **Node.js 18+**。内核 `@anchorlock/core` ≥ **0.6.0**，随 cli 自动安装。本机若与 `anchorlock-core` 同级，会优先用 `../anchorlock-core`。
+
+---
+
+## 0. 先问一句：有没有 OpenAPI？
+
+有 → **路 A（默认）**。没有 → 路 B，且必须人确认一次起草稿。不要两条一起走。不要从 PRD 手写/让 Agent 写字段名单。
+
+---
+
+## 0.5 两份文件长什么样
+
+`check` 只读字段名。下面是**对公转账**里最容易漂的五个名字，是切片，不是整份支付说明书。
+
+**openapi.json**（路 A，后端发版，不要手写）：
+
+```json
+{
+  "openapi": "3.0.3",
+  "info": { "title": "payment-api", "version": "1.4.0" },
+  "paths": {
+    "/payments/transfers": {
+      "post": {
+        "operationId": "createTransfer",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/TransferReq" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "TransferReq": {
+        "type": "object",
+        "required": ["payer_account", "payee_account", "payment_amount", "payment_currency"],
+        "properties": {
+          "payer_account": { "type": "string", "description": "付款账号" },
+          "payee_account": { "type": "string", "description": "收款账号" },
+          "payment_amount": { "type": "string", "description": "转账金额，十进制字符串" },
+          "payment_currency": { "type": "string", "description": "币种，ISO 4217" }
+        }
+      },
+      "TransferRes": {
+        "type": "object",
+        "properties": {
+          "payment_id": { "type": "string", "description": "支付流水号" },
+          "payment_status": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+规范名在 `properties` 上。消费仓不提交这份文件，只提交 pin：`{ "url", "hash", "version" }`。
+
+**constraints.json**（路 B 人确认后的名单；路 A 用 `anchor constraints --from` 投影，不要手写）：
+
+```json
+{
+  "schemaVersion": "1",
+  "units": [
+    {
+      "id": "payment_id",
+      "type": "string",
+      "aliases": ["paymentId", "payId", "bank_serial_no", "支付流水号"]
+    },
+    {
+      "id": "payer_account",
+      "type": "string",
+      "aliases": ["fromAccount", "payerAcct", "payer_acct", "付款账号"]
+    },
+    {
+      "id": "payee_account",
+      "type": "string",
+      "aliases": ["toAccount", "payeeAcct", "payee_acct", "收款账号"]
+    },
+    {
+      "id": "payment_amount",
+      "type": "string",
+      "aliases": ["amount", "txnAmt", "pay_amt", "转账金额"]
+    },
+    {
+      "id": "payment_currency",
+      "type": "string",
+      "aliases": ["currency", "ccy", "币种"]
+    }
+  ]
+}
+```
+
+`id` 是规范名。前端的 `fromAccount` / `amount`，或测试里的 `"付款账号"`，应对齐 `payer_account` / `payment_amount`。
+
+---
+
+## 1. 路 A：钉死的 OpenAPI（推荐）
+
+后端构建导出说明书（Springdoc / Nest / FastAPI），打 tag，把 `openapi.json` 挂到 Release。前端**不 clone 后端仓**，不对着线上 `/v3/api-docs` 扫。
+
+消费仓只提交 pin：
+
+```bash
+npm i -D @anchorlock/cli
+npx anchor init    # 只装 Agent skill，不写名单
+
+npx anchor pin --from dist/openapi.json \
+  --url "https://git.example.com/group/order-api/-/releases/v1.4.0/downloads/openapi.json" \
+  --tag v1.4.0 -o contracts/order.pin.json
+
+npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+`check` 做的事：
+
+1. 读 pin：优先用本地 `path`，否则下 `url`，用 `hash` 核对没下错文件。
+2. 从说明书 schema 属性名抽出契约认的字段（如 `order_no`）。
+3. 扫 `--src`（一般是 `src/`，跳过 `node_modules`）。近义词或说明书上没有的字段名 → 退出码非 0。
+
+红了改**代码**对齐说明书，不要改 pin。CI 复制 [`ci/check-contract.github.yml`](../ci/check-contract.github.yml)，挂在 merge 保护上。
+
+```json
+{
+  "url": "https://git.example.com/group/order-api/-/releases/v1.4.0/downloads/openapi.json",
+  "hash": "sha256:后端发版时算出的64位指纹",
+  "version": "v1.4.0",
+  "path": "../dist/openapi.json"
+}
+```
+
+本地还能读到 `path` 时不联网。私有制品把只读 token 放进 `ANCHOR_CONTRACT_TOKEN`。
+
+合主干用 `--strict`：契约来自完整 OpenAPI，名单外的字段名也应失败。这在 TypeScript / JS 消费仓可用。不要拿 `--strict` 去扫同一个 Java 后端仓里的方法名和 SQL 列名——那是编译器和 MyBatis 的范围。
+
+### 抛锚
+
+```bash
+anchor constraints --from contracts/order.pin.json -o constraints.json
+# 然后 SA_CONSTRAINTS 指向这份文件，SemanticAnchor 跑 bind / verify_usage
+```
+
+收紧继续：`anchor check --contract contracts/order.pin.json --src src --strict --require-hash`。
+
+---
+
+## 1.5 第二回合：这次需求要加字段
+
+**字段范围由后端发版推进，不由你和 Agent 的对话推进。** 需求说要加「优惠券抵扣」，不等于你可以往契约里加一个 `couponAmount`——先让后端发版，说明书上有了，前端才认。
+
+pin 是**整份换**，不是往里面加字段：
+
+```bash
+# 1. 后端：改完接口，重新导出、打新 tag、挂到 Release
+# 2. 前端：换到新那一版（url 里的 tag 会跟着换）
+npx anchor repin --from ../order-api/dist/openapi.json --tag v1.5.0 --change PROJ-123
+
+# 3. 看清楚换了什么，再提交
+git diff contracts/order.pin.json
+git add contracts/order.pin.json
+
+# 4. 改业务代码用新字段，跑同一条 check
+npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+`repin` 就是「换版专用的 pin」：沿用原来的 `url` 和 `change`，把 tag 换掉、hash 重算、直接覆盖（不用记 `--force`）。制品和上一版一字不差时会警告，多半是后端还没重新导出。
+
+版本管理靠两样东西，不需要另建目录：
+
+| 东西 | 谁记的 |
+|---|---|
+| 锁在哪一版 | `pin.json` 里的 `version` + `hash` |
+| 为什么换 | `pin.json` 里的 `change`（需求号）+ 这次 commit |
+| 换过几次 | `git log contracts/order.pin.json` |
+
+`check` 每次都会把这两样打出来，人不用去翻文件：
+
+```
+  pin   v1.5.0 · change PROJ-123
+```
+
+**编码 Agent 不许自己 repin。** 换版是「后端发了新版本」触发的，不是「check 红了想换绿」。红了只能改代码。
+
+---
+
+## 1.6 多 Agent 协作（不是第三条路）
+
+Cursor、Claude、Copilot 同时写，或前端 / 后端 / 测试各开一个 Agent，**仍走路 A（没有说明书则路 B）**。协作增加的是写代码的人，不是契约的份数。
+
+共享这一份：
+
+```text
+contracts/order.pin.json
+```
+
+所有编码 Agent 吃同一份 `anchor init` 装进去的 skill。CI 只认这一条：
+
+```bash
+npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+| 谁 | 做什么 | 不许做什么 |
+|---|---|---|
+| 人 | 第一次 `pin`；后端发新 tag 后 `repin --change <需求号>` | 让 Agent 按对话补字段 |
+| 后端 Agent | 实现接口、导出 OpenAPI、打 tag | 在消费仓 `check` 自己的 Java；手写名单当权威 |
+| 前端 / 客户端 / 测试 Agent | 用说明书上的名字写代码；红了把 FAIL 贴回去改源码 | `repin`、改 pin、从 PRD 编名单 |
+| CI | 合主干前跑上面那条 | 没有 |
+
+同一仓里几个 Agent 并行：开工先看 `check` 打出来的 `pin   v1.5.0 · change …` 是不是同一版；各改各的源码；红了把整段 FAIL 贴给**写飘了的那个** Agent。冲突在 git，不在契约。
+
+跨仓时顺序不能倒：后端发版 → 人 `repin` → 前端 / 测试 Agent 才用新字段。前端 Agent 不能先发明 `couponAmount` 再让后端追。测试仓和前端仓 pin **同一个** url/tag。
+
+写盘前可选：投影一次，各 Agent 的 SemanticAnchor 都指向**这一份** `constraints.json`。投影不能代替 `check`，也不能手改当权威。
+
+路 B：只允许**一处**起草并由人确认。其它 Agent 只 `check`。各扫各的（`orderStatus` vs `order_status`）两边都绿，联调照样炸。
+
+---
+
+## 2. 路 B：没有 OpenAPI
+
+只在**一处、已经圈定的模块**起草。人确认 `id`，其它仓只 `check` 这一份。
+
+```bash
+anchor init --from-code path/to/one-module -o constraints.json
+# 人确认之后：
+anchor check --contract constraints.json --src src
+```
+
+起草稿里留什么、删什么，按这条判：
+
+| 留 | 删 |
+|---|---|
+| 会跨进程传的名字：HTTP JSON key、SQL 列名、MQ payload、存储字段 | 函数名、方法名、局部变量、类型名、框架词 |
+| 两个以上模块都在用的业务名 | 只在一个文件里出现过的名字 |
+
+拿不准就删。漏锁只是这个字段没保护；错锁会让 CI 逼别人改本来正确的代码，工具很快就被关掉。
+
+路 B 没有 tag 和 hash，`constraints.json` 的版本就是 git 历史。加字段的规矩和路 A 一样：**先改这一份、人确认，再写代码**，不要写完代码回头补名单。
+
+不要每个仓都起草：前端扫出 `orderStatus`、后端扫出 `order_status`，两份都绿，联调照样炸。
+
+不要让 Agent 按「实现订单查询」往 `units` 里加字段。那是自己给自己发证。
+
+连代码都没有、要从零发明字段时，才用 `anchor constraints --init`。那是例外。
+
+---
+
+## 3. `check` 在查什么
+
+词法扫描 `.js` / `.ts` / `.vue` / `.java` 等（**不扫 `.xml`**），对照契约的 `id` / `aliases`，以及驼峰↔蛇形折合。不读 PRD，不追踪调用链。
+
+| 情况 | 结果 |
+|------|------|
+| 与某个 `id` 完全一致 | 通过 |
+| 出现在某单元 `aliases`（含 `"单号"`） | **漂移 · 红** |
+| `orderNo` 能折成契约里的 `order_no` | **漂移 · 红** |
+| 长得像字段但不在契约里 | 默认忽略；`--strict` 时 **未声明 · 红** |
+| 只作为函数出现：`lookupMine()`、`encodeURIComponent()`、`const fetchOrder = async () =>` | `--strict` 下忽略 |
+| `id` / `name` / `status`、PascalCase 类型、`useXxx` | 忽略 |
+
+`--src` 只定扫描根。人不要靠它指定某一个源文件。看未提交改动用 `--changed`。
+
+---
+
+## 4. 接到 CI（消费仓）
+
+```yaml
+- run: npx anchor check --contract contracts/order.pin.json --src src --strict --require-hash
+```
+
+门禁挂在 **merge / 主分支保护** 上。Prompt「请统一命名」挡不住下一次生成。
+
+---
+
+## 5. 抛锚和收紧
+
+| | 何时 | 命令 | 吃什么 |
+|---|---|---|---|
+| **抛锚** | Agent 正在写文件 | SemanticAnchor MCP：`bind` / `verify_usage` | 从 OpenAPI **投影**出的 `constraints.json` |
+| **收紧** | 合进主干之前 | `anchor check --contract pin.json --src src --strict` | 钉死的 OpenAPI / pin |
+| 投影（不是抛锚） | 给抛锚准备文件 | `anchor constraints --from pin.json` | 钉住的说明书 |
+
+`compile` / `pipeline` / `new-change` 会直接拒绝。
+
+---
+
+## 6. 常见问题
+
+**每个仓都生成一份名单？**  
+不要。路 A 钉同一份发版 OpenAPI。路 B 只扫一次，各仓共用这一份已确认文件。
+
+**这次需求新增的字段放哪？**  
+不往 pin 里加。后端发新 tag → `anchor repin --tag <新 tag> --change <需求号>` 整份换 → 再改代码。见上面「第二回合」。
+
+**我怎么知道自己锁在哪一版？**  
+`check` 会打 `pin   v1.5.0 · change PROJ-123`。历史看 `git log contracts/order.pin.json`。
+
+**有 OpenAPI 还要让 Agent 写 constraints 吗？**  
+不要。
+
+**在 Java 后端仓跑 check 扫到 SQL 列名 / getter？**  
+别这么用。本工具锁的是消费仓对接口字段；同一仓的 Java 交给编译器。合主干的 `--strict` 给 TS/JS 消费仓。
+
+**红了改清单还是改代码？**  
+改代码对齐契约。FAIL 末尾会写：不要改 pin，把这段贴给编码 Agent，改完再跑同一条 check。
+
+**多个 Agent 同时写，要走第三条路吗？**  
+不要。仍是路 A（或路 B）。共享同一份 pin，各自改代码，CI 收紧。见上面「多 Agent 协作」。
+
+**想先看闸、不碰仓库：** `npx @anchorlock/cli demo` 或本仓 `npm run demo`。