skill-family-contracts 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+<!-- release-skill:changelog:start version=0.3.0 locale=en baseline=sha256:32a8df58662f9dbb64e142cb8a2b329556b4bd59872e48fcbc317cc971cbdd7c -->
+## [0.3.0] - 2026-08-12
+
+This source candidate replaces the Quickstart Profile candidate with v2 while preserving the stable Contracts registry and kernel protocol.
+
+### Added
+
+- Adds the v2 protocol definition with the business-neutral execute-method operation and a real $id-indexed Resource, Task, and Result schema collection.
+- Enforces JSON-safe Task and Result boundaries, one path-backed observation, terminal output shapes, and exact evidence bindings.
+
+### Changed
+
+- Replaces the incompatible 0.2.1 candidate surface; consumers that still require v1 must remain pinned to exactly 0.2.1.
+- Keeps method identifiers, parameter schemas, and domain result semantics under consumer ownership.
+
+### Upgrade Notes
+
+Version 0.3.0 is a local, unpublished source candidate. Pin all candidate imports to an exact package version and migrate v1 integrations before selecting this version.
+<!-- release-skill:changelog:end version=0.3.0 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.2.1 locale=en baseline=sha256:b759650e4d52969bd907bccea937c64622b00b0ff97851da9c6c4aee8adb4888 -->
+## [0.2.1] - 2026-08-10
+
+This release adds a candidate Quickstart Profile contract surface and makes the package release documentation available in English and Simplified Chinese.
+
+### Added
+
+- Adds candidate Resource, Task, and Result schemas with strict validation helpers. The candidate schemas remain outside the stable Contracts registry.
+- Adds complete English and Simplified Chinese package documentation, including an agent quick-reference section.
+
+### Changed
+
+- Manages the current README and CHANGELOG release sections from one bilingual, versioned notes source.
+- Distributes the project NOTICE separately from the Apache-2.0 LICENSE.
+
+### Upgrade Notes
+
+Stable registry consumers do not need to change. Import the Quickstart Profile only through its candidate subpath and do not treat it as a frozen Contracts object.
+<!-- release-skill:changelog:end version=0.2.1 locale=en -->

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,42 @@
+# 变更日志
+
+<!-- release-skill:changelog:start version=0.3.0 locale=zh-CN baseline=sha256:5f1c4cf56cc336279cbc6f11bc6cf8ce0a7524f454ff6589e067e828707a7cc7 -->
+## [0.3.0] - 2026-08-12
+
+本源码候选版以 Quickstart Profile v2 替换原 candidate，同时保持稳定 Contracts 登记表和内核协议不变。
+
+### 新增
+
+- 新增 v2 协议定义，以业务中立的 execute-method 作为唯一操作，并按真实 $id 登记 Resource、Task、Result Schema 集合。
+- 收紧 Task 与 Result 的 JSON-safe 边界、单一 path-backed observation、终态输出形状及 evidence 精确回指。
+
+### 变更
+
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法标识、参数 Schema 与领域结果语义继续归消费者所有。
+
+### 升级说明
+
+0.3.0 当前只是本地、未发布的源码候选。candidate 导入必须精确锁定包版本，v1 接入完成迁移后才能选用本版本。
+<!-- release-skill:changelog:end version=0.3.0 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.2.1 locale=zh-CN baseline=sha256:1f9b53564843c024415fda87d41abf96bc22db2ec5b90d12d7a8cd7c897a24fc -->
+## [0.2.1] - 2026-08-10
+
+本版新增 Quickstart Profile 候选契约面，并为包发布文档提供完整英文版与简体中文版。
+
+### 新增
+
+- 新增候选 Resource、Task、Result Schema 及其严格校验辅助函数。这组候选 Schema 不进入稳定 Contracts 登记表。
+- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+
+### 变更
+
+- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+- 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+
+### 升级说明
+
+稳定登记表的消费者无需修改。Quickstart Profile 只能通过 candidate 子路径导入，不得把它当作已冻结的 Contracts 对象。
+<!-- release-skill:changelog:end version=0.2.1 locale=zh-CN -->

package/NOTICE

@@ -0,0 +1,10 @@
+Skill Family Foundation
+=======================
+
+Copyright 2026 广州市风荷科技有限公司
+
+Licensed under the Apache License, Version 2.0.
+
+This NOTICE contains project attribution for Skill Family Foundation. Third-party
+attribution and license texts distributed with skill-family-engineering-kit are
+recorded separately in THIRD_PARTY_NOTICES and the corresponding license files.

package/README.md

@@ -1,21 +1,100 @@
 <!-- release-skill:safe-first-command -->
 <!-- release-skill:external-write-boundary -->
+> 简体中文版：[README.zh-CN.md](./README.zh-CN.md)
 
 # skill-family-contracts
 
-机器可执行工程结构和机制协议的唯一权威包（Contracts 1.4.0，冻结）。
+<!-- release-skill:release-version: 0.3.0 -->
 
-本包拥有：十八类顶层对象的 JSON Schema、Kernel Protocol（内核协议）、稳定错误码、
-协议名/`$id` 登记表，以及九种有限机械检查类型与受限强制规则集。
-本包不执行骨架生成、文件写入、审计或发布；机制实现由 Harness 承担，
-工程命令由 Kit 承担，二者单向消费本包。
+The single authoritative package of machine-executable engineering structure and mechanism protocols (Contracts 1.4.0, frozen).
 
-Schema 验证完全基于 [Ajv](https://ajv.js.org/)（精确版本见 `package.json`），
-按方言路由到对应 Ajv 类；不实现任何手写 Schema 子集解释器。
+<!-- release-skill:managed:start id=latest-release -->
+**0.3.0** (2026-08-12)
 
-## 十八类顶层对象
+This source candidate replaces the Quickstart Profile candidate with v2 while preserving the stable Contracts registry and kernel protocol.
 
-| 对象 | `$id` | Schema 文件 |
+**Added**
+
+- Adds the v2 protocol definition with the business-neutral execute-method operation and a real $id-indexed Resource, Task, and Result schema collection.
+- Enforces JSON-safe Task and Result boundaries, one path-backed observation, terminal output shapes, and exact evidence bindings.
+
+**Changed**
+
+- Replaces the incompatible 0.2.1 candidate surface; consumers that still require v1 must remain pinned to exactly 0.2.1.
+- Keeps method identifiers, parameter schemas, and domain result semantics under consumer ownership.
+
+**Upgrade Notes**
+
+Version 0.3.0 is a local, unpublished source candidate. Pin all candidate imports to an exact package version and migrate v1 integrations before selecting this version.
+<!-- release-skill:managed:end id=latest-release -->
+
+## Problem It Solves
+
+When every skill-family project writes its own set of structural contracts, you get schema drift, inconsistent error codes, and protocol-name collisions. Contracts consolidates the structure, protocols, error codes, and protocol-name registry into one frozen machine-readable authority, so that the Harness and Kit consume it unidirectionally instead of each interpreting it independently.
+
+## Core Mental Model
+
+Contracts is the "definition and registry" layer, not the "execution" layer. It owns the JSON Schemas for the eighteen top-level object classes, the Kernel Protocol, the stable error codes, the protocol-name and `$id` registry, and the nine finite mechanical check types together with a restricted set of mandatory rules. This package does not perform skeleton generation, file writing, auditing, or publishing; mechanism implementation is owned by the Harness, and engineering commands are owned by the Kit.
+
+Schema validation is based entirely on [Ajv](https://ajv.js.org/) (exact version in `package.json`), routing by dialect to the corresponding Ajv class; no hand-written schema-subset interpreter is implemented.
+
+## Installation and Minimal Example
+
+```sh
+npm install skill-family-contracts@0.3.0
+npm info skill-family-contracts --help
+```
+
+The minimal example starts from an empty directory and demonstrates how to validate a registered contract object:
+
+```js
+// Run from an empty directory: npm install skill-family-contracts@0.3.0
+import { validateDocument } from "skill-family-contracts";
+
+const document = {
+  schemaVersion: 1,
+  kind: "skill-family.project-manifest",
+  project: { id: "my-project", name: "My Project", description: "Example" },
+  contracts: { version: "1.0.0", profile: "generic" },
+  managedFiles: ["package.json"],
+  updatedAt: "2026-01-01T00:00:00Z",
+};
+
+const result = validateDocument(document, {
+  schemaId: "https://contracts.skill-family.example/v1/project-manifest.json",
+  dialect: "2020-12",
+});
+if (!result.valid) console.error(result.errorCode);
+```
+
+The code above shows the basic `validateDocument` call: pass the document and the target Schema's `$id`, and it returns `{ valid, errorCode, errors, data }`, where `data` is a normalized copy and the original input is not modified.
+
+## Candidate Quickstart Profile
+
+Use the candidate Quickstart Profile to evaluate an early Resource → Task → Result exchange before proposing it for the frozen registry:
+
+```js
+import {
+  QUICKSTART_PROTOCOL,
+  quickstartProfileSchemas,
+  validateQuickstartProfileDocument,
+} from "skill-family-contracts/candidate/quickstart-profile";
+```
+
+Version 0.3.0 carries Quickstart Profile v2. Its protocol fixes the business-neutral operation to `execute-method`; Resource, Task, and Result schemas resolve one another through their real v2 `$id` values. Foundation validates the JSON-safe exchange shape, while the consumer owns method identifiers, parameter schemas, and domain results.
+
+The subpath is public but **not stable**. Its schemas remain absent from `src/registry.json`, do not expand the eighteen stable object classes, and may change or be removed in a later minor release. Pin exactly `0.3.0` when evaluating v2. Integrations that still require candidate v1 must stay pinned to exactly `0.2.1`.
+
+## Typical Use Cases
+
+- Need to validate whether a contract document conforms to a registered Schema: use `validateDocument`.
+- Need to look up a Schema by object name or `$id`, or look up a Kernel Protocol by protocol name: use `loadRegistry` / `findSchemaByObject` / `findProtocol`.
+- Need to run mandatory mechanical rules and collect unresolved references: use `runChecks` / `collectUnresolvedRefs`.
+- Need to enumerate and validate the public fixtures: use `verifyAllFixtures`.
+
+## Eighteen Top-Level Object Classes
+
+| Object | `$id` | Schema File |
 | --- | --- | --- |
 | `project-manifest` | `https://contracts.skill-family.example/v1/project-manifest.json` | `src/schemas/project-manifest.schema.json` |
 | `profile-descriptor` | `https://contracts.skill-family.example/v1/profile-descriptor.json` | `src/schemas/profile-descriptor.schema.json` |
@@ -34,84 +113,66 @@ Schema 验证完全基于 [Ajv](https://ajv.js.org/)（精确版本见 `package.
 | `host-registry` | `https://contracts.skill-family.example/v1/host-registry.json` | `src/schemas/host-registry.schema.json` |
 | `host-probe-result` | `https://contracts.skill-family.example/v1/host-probe-result.json` | `src/schemas/host-probe-result.schema.json` |
 | `state-event-envelope` | `https://contracts.skill-family.example/v1/state-event-envelope.json` | `src/schemas/state-event-envelope.schema.json` |
-| `state-snapshot-metadata` | `https://contracts.skill-family.example/v1/state-snapshot-metadata.json` | `src/schemas/state-snapshot-metadata.schema.json` |
+| `state-snapshot-metadata` | `https://contracts.skill-family.example/v1/state-snapshot-metadata.json` | `src/schemas/state-snapshot-metadata.json` |
 
-所有 v1 Schema 使用 draft 2020-12 方言；实例信封统一为
-`schemaVersion: 1` + 唯一 `kind` 常量 + 各层 `additionalProperties: false`。
-`$id` 命名空间 `contracts.skill-family.example` 使用保留示例域，永不解析到真实站点。
+All v1 Schemas use the draft 2020-12 dialect; instance envelopes are uniformly `schemaVersion: 1` + a unique `kind` constant + `additionalProperties: false` at each layer. The `$id` namespace `contracts.skill-family.example` uses a reserved example domain and never resolves to a real site.
 
-## Kernel Protocol（内核协议）
+## Kernel Protocol
 
-登记表：`src/registry.json`；冻结定义：`src/kernel-protocol.json`。
+Registry: `src/registry.json`; frozen definition: `src/kernel-protocol.json`.
 
-- 协议名：`skill-family.kernel.operation`，版本 `1`，状态 `stable`。
-- 状态集：`accepted`、`running`、`succeeded`、`failed`、`rejected`；
-  终态为 `succeeded`、`failed`、`rejected`；`operation-result` 只携带终态。
-- 转移：`accepted → running → succeeded|failed`，另允许 `accepted → failed`；
-  入口可直接 `rejected`。
-- v1 操作词汇表只冻结 `validate`，其 params 合同在
-  `kernel-protocol.json` 内定义（`schemaId` + `document` 必填）。
-  新增操作名属于合同变更，需新版本登记。
+- Protocol name: `skill-family.kernel.operation`, version `1`, status `stable`.
+- State set: `accepted`, `running`, `succeeded`, `failed`, `rejected`; terminal states are `succeeded`, `failed`, `rejected`; `operation-result` carries only terminal states.
+- Transitions: `accepted → running → succeeded|failed`, with `accepted → failed` also allowed; the entry may directly `rejected`.
+- The v1 operation vocabulary freezes only `validate`, whose params contract is defined inside `kernel-protocol.json` (`schemaId` + `document` required). Adding a new operation name is a contract change and requires a new version registration.
 
-重名协议与重复 `$id` 被机械拒绝：`registerProtocol` 抛出 `SFC1004`，
-`registerSchema` 抛出 `SFC1003`；检查类型 `protocol.unique-name` 与
-`schema.unique-id` 对登记表做同样判定。
+Duplicate-name protocols and duplicate `$id`s are machine-rejected: `registerProtocol` throws `SFC1004`, `registerSchema` throws `SFC1003`; the check types `protocol.unique-name` and `schema.unique-id` make the same determination against the registry.
 
-## 稳定错误码
+## Stable Error Codes
 
-冻结登记表：`src/error-codes.json`。`SFC1xxx` 为合同权威层错误，
-`SFC2xxx` 为内核操作错误，`SFC3xxx` 为报告绑定错误。码只增不改、不复用。v1 冻结：
+Frozen registry: `src/error-codes.json`. `SFC1xxx` are contract-authority-layer errors, `SFC2xxx` are kernel-operation errors, `SFC3xxx` are report-binding errors. Codes are only added, never modified or reused. Frozen in v1:
 
-| 码 | 名称 | 含义摘要 |
+| Code | Name | Summary |
 | --- | --- | --- |
-| SFC1001 | SCHEMA_VALIDATION_FAILED | 文档未通过目标 Schema 验证 |
-| SFC1002 | UNKNOWN_SCHEMA_ID | `$id` 未在登记表注册 |
-| SFC1003 | DUPLICATE_SCHEMA_ID | 重复 `$id` 注册被拒绝 |
-| SFC1004 | DUPLICATE_PROTOCOL_NAME | 重复协议名/版本注册被拒绝 |
-| SFC1005 | UNRESOLVED_REF | `$ref` 目标无法解析 |
-| SFC1006 | UNSUPPORTED_DIALECT | 方言不在冻结支持集 |
-| SFC1007 | UNKNOWN_CHECK_TYPE | 规则使用九类之外的检查类型 |
-| SFC1008 | RULE_BUDGET_EXCEEDED | 强制规则数超出预算/上限 |
-| SFC1009 | UNKNOWN_ERROR_CODE | 引用了未登记的错误码 |
-| SFC1010 | FIXTURE_EXPECTATION_MISMATCH | fixture 行为与声明期望不符 |
-| SFC1011 | UNKNOWN_PROTOCOL | 请求引用未登记的协议名/版本 |
-| SFC1012 | SCHEMA_COMPILE_FAILED | Schema 本身无法编译 |
-| SFC2002 | UNKNOWN_OPERATION | 操作名不在冻结词汇表 |
-| SFC2003 | INVALID_PARAMS | 参数不满足操作的冻结 params 合同 |
-| SFC2004 | EXECUTION_FAILED | 机制运行时执行失败（仅运行时可演示） |
-| SFC3001 | REPORT_DIGEST_MISMATCH | 报告或结果摘要与绑定不一致 |
-| SFC3002 | REPORT_ELEMENT_MISSING | 报告缺少强制元素 |
-| SFC3003 | REPORT_FACT_DRIFT | 报告字节偏离确定性重渲染结果 |
-
-## 方言与验证策略（Ajv）
-
-- 支持方言：`draft-07`、`2020-12`。draft 识别通过 `$schema` URI 映射
-  （`detectDialect`），验证按方言路由到对应 Ajv 类。
-- 验证策略（`VALIDATION_POLICIES`）：
-  - `strict`（默认）：不做类型强制、不注入默认值，Ajv 严格模式全开；
-  - `tolerant`：开启 Ajv `coerceTypes: "array"` 与 `useDefaults`，用于采纳场景。
-- 格式：`date-time`（RFC 3339，含日历合法性检查）经 Ajv `addFormat` 登记。
-- `validateDocument` 永不修改调用者输入；规范化后的副本在结果的 `data` 字段返回。
-
-## 九类机械检查与规则预算
-
-登记表：`src/rules.json`。检查类型集合封闭，共九种：
-`schema.compile`、`schema.unique-id`、`protocol.unique-name`、
-`schema.ref-resolves`、`schema.dialect-declared`、`fixture.positive-passes`、
-`fixture.negative-coded`、`error-code.registered`、`rules.budget`。
-
-当前强制规则 **9 条**（CR-001、CR-006…CR-013）。其中 CR-001 对登记表内全部 Schema 做统一编译，
-不再为每个对象重复占用一条规则；预算上限 20 条、绝对上限 30 条；
-`rules.budget` 是机械门禁，超限即 `runChecks` 失败并报 `SFC1008`。
-
-## Fixture
-
-`src/fixtures/<contract>/` 为每类合同提供正例（positive）、反例（negative）
-与方言边界（dialect-boundary）样例，共 76 个。每个 fixture 声明目标 Schema、
-方言、策略与期望；反例期望携带稳定失败码。`verifyAllFixtures()` 机械重放全部期望，
-行为不符报 `SFC1010`。fixture 是完全虚构数据，不是审计 oracle。
-
-## API 概览
+| SFC1001 | SCHEMA_VALIDATION_FAILED | Document failed target Schema validation |
+| SFC1002 | UNKNOWN_SCHEMA_ID | `$id` not registered in the registry |
+| SFC1003 | DUPLICATE_SCHEMA_ID | Duplicate `$id` registration rejected |
+| SFC1004 | DUPLICATE_PROTOCOL_NAME | Duplicate protocol name/version registration rejected |
+| SFC1005 | UNRESOLVED_REF | `$ref` target cannot be resolved |
+| SFC1006 | UNSUPPORTED_DIALECT | Dialect not in the frozen support set |
+| SFC1007 | UNKNOWN_CHECK_TYPE | Rule uses a check type outside the nine categories |
+| SFC1008 | RULE_BUDGET_EXCEEDED | Mandatory rule count exceeds budget/limit |
+| SFC1009 | UNKNOWN_ERROR_CODE | References an unregistered error code |
+| SFC1010 | FIXTURE_EXPECTATION_MISMATCH | Fixture behavior does not match declared expectation |
+| SFC1011 | UNKNOWN_PROTOCOL | Request references an unregistered protocol name/version |
+| SFC1012 | SCHEMA_COMPILE_FAILED | Schema itself cannot be compiled |
+| SFC2002 | UNKNOWN_OPERATION | Operation name not in the frozen vocabulary |
+| SFC2003 | INVALID_PARAMS | Parameters do not satisfy the operation's frozen params contract |
+| SFC2004 | EXECUTION_FAILED | Mechanism runtime execution failed (only demonstrable at runtime) |
+| SFC3001 | REPORT_DIGEST_MISMATCH | Report or result digest inconsistent with binding |
+| SFC3002 | REPORT_ELEMENT_MISSING | Report missing a mandatory element |
+| SFC3003 | REPORT_FACT_DRIFT | Report bytes deviate from deterministic re-render result |
+
+## Dialects and Validation Strategy (Ajv)
+
+- Supported dialects: `draft-07`, `2020-12`. Draft detection uses `$schema` URI mapping (`detectDialect`), and validation routes by dialect to the corresponding Ajv class.
+- Validation strategy (`VALIDATION_POLICIES`):
+  - `strict` (default): no type coercion, no injected defaults; Ajv strict mode fully enabled;
+  - `tolerant`: enables Ajv `coerceTypes: "array"` and `useDefaults`, for adoption scenarios.
+- Format: `date-time` (RFC 3339, including calendar-validity checks) registered via Ajv `addFormat`.
+- `validateDocument` never modifies the caller's input; the normalized copy is returned in the result's `data` field.
+
+## Nine Mechanical Check Types and the Rule Budget
+
+Registry: `src/rules.json`. The check-type set is closed, with nine types total: `schema.compile`, `schema.unique-id`, `protocol.unique-name`, `schema.ref-resolves`, `schema.dialect-declared`, `fixture.positive-passes`, `fixture.negative-coded`, `error-code.registered`, `rules.budget`.
+
+There are currently **9** mandatory rules (CR-001, CR-006…CR-013). Among them, CR-001 performs uniform compilation of all Schemas in the registry, instead of occupying one rule per object; the budget cap is 20 rules, absolute cap 30 rules; `rules.budget` is a mechanical gate, and exceeding it fails `runChecks` with `SFC1008`.
+
+## Fixtures
+
+`src/fixtures/<contract>/` provides positive, negative, and dialect-boundary samples for each contract class. Each fixture declares the target Schema, dialect, policy, and expectation; negative expectations carry a stable failure code. `verifyAllFixtures()` mechanically replays all expectations, and reports `SFC1010` on mismatch. Fixtures are entirely fictional data, not an audit oracle.
+
+## API Overview
 
 ```js
 import {
@@ -125,48 +186,81 @@ import {
 } from "skill-family-contracts";
 ```
 
-- `validateDocument(document, { schemaId | schema, dialect, policy })` →
-  `{ valid, errorCode, errors, data }`；
-- `runChecks({ rules?, registry?, fixtures?, loadSchema? })` →
-  `{ ok, mandatoryCount, budget, results }`；
-- `registerSchema` / `registerProtocol` 返回新登记表副本，重复项分别以
-  `SFC1003` / `SFC1004` 抛出 `ContractsError`。
+The imports above list the stable public surface of this package; `validateDocument` and `runChecks` are the most commonly used entry points. `validateDocument(document, { schemaId | schema, dialect, policy })` returns `{ valid, errorCode, errors, data }`; `runChecks({ rules?, registry?, fixtures?, loadSchema? })` returns `{ ok, mandatoryCount, budget, results }`; `registerSchema` / `registerProtocol` return a new registry copy, throwing `ContractsError` with `SFC1003` / `SFC1004` respectively on duplicates.
 
-## 边界与非目标
+## Security Boundaries and Non-Goals
 
-不拥有生成、语义审计、发布状态与远端写入；不定义清理计划、发布快照、
-消费者冒烟结果、领域审计报告或自由文本规则语言；不建通用 DSL。
-冻结内容的变更只能作为新的合同版本任务进行。
+It does not own generation, semantic auditing, publishing state, or remote writing; it does not define cleanup plans, publish snapshots, consumer smoke results, domain audit reports, or a free-text rule language; it does not build a general DSL. Changes to frozen content can only be carried out as a new contract-version task.
 
-## 安装
+## Troubleshooting
 
-```sh
-npm install skill-family-contracts@0.2.0
-npm info skill-family-contracts --help
-```
+On validation failure `errorCode` is `SFC1001` (SCHEMA_VALIDATION_FAILED, document failed target Schema validation); when `$id` is unregistered it reports `SFC1002` (UNKNOWN_SCHEMA_ID). If it fails, check whether the document satisfies the target Schema's required fields and type constraints.
 
-## 最小示例
+## Further Documentation
 
-```js
-// 从空目录运行：npm install skill-family-contracts@0.2.0
-import { validateDocument } from "skill-family-contracts";
+- Architecture boundaries and routing: [Architecture](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/), [Agent architecture routing](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- Capability catalog: [capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- Current product status: [Public status](https://ifoohoo.github.io/skill-family-engineering-kit/public/status/)
 
-const document = {
-  schemaVersion: 1,
-  kind: "skill-family.project-manifest",
-  project: { id: "my-project", name: "My Project", description: "Example" },
-  contracts: { version: "1.0.0", profile: "generic" },
-  managedFiles: ["package.json"],
-  updatedAt: "2026-01-01T00:00:00Z",
-};
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
 
-const result = validateDocument(document, {
-  schemaId: "https://contracts.skill-family.example/v1/project-manifest.json",
-  dialect: "2020-12",
-});
-if (!result.valid) console.error(result.errorCode);
-```
+### Use when
+
+- You need to validate a registered contract object, look up a Schema/protocol, or run mandatory mechanical rules.
+- You need to enumerate and validate public fixtures, or deterministically serialize the contract surface.
+- You need to evaluate the non-stable Quickstart Resource/Task/Result profile with an exact package-version pin.
+
+### Do not use when
+
+- You need to validate a consumer's own business Schema (the consumer should own it; Foundation does not replace it).
+- You need to mix domain semantic validation into the general contract.
+- You need a compatibility-frozen Quickstart profile; the candidate subpath is not registered as stable.
+
+### Capability selection
+
+- `foundation.contracts.object-validation`: Ajv dual-dialect validation of the 18 object classes.
+- `foundation.contracts.registry-protocol`: Schema `$id` and protocol-name registry query.
+- `foundation.contracts.kernel-protocol`: operation-request/result protocol.
+- `foundation.contracts.mandatory-checks`: nine mandatory rules and unresolved references.
+- `foundation.contracts.fixture-verification`: full fixture replay.
+- `foundation.contracts.error-codes`: stable error-code system.
+- `foundation.contracts.audit-surface`: canonical JSON + sha256 digest.
+- `foundation.contracts.quickstart-profile-candidate`: candidate-only Resource/Task/Result schemas and validation through the exact-version subpath.
+
+### Required inputs
+
+- The document to validate (carrying a registered `$id`), or the target contract object name.
+- The validation policy `strict` (default) or `tolerant`.
+
+### Outputs and evidence
+
+- `validateDocument` returns `{ valid, errorCode, errors, data }`.
+- Evidence: `packages/skill-family-contracts/test/validator.test.mjs`, `registry.test.mjs`, `checker.test.mjs`, `fixtures.test.mjs`.
+
+### Side effects
+
+- Pure functions; no filesystem, Git, network, or process side effects (the compile cache lives only in memory).
+
+### Failure semantics
+
+- Stable error codes such as `SFC1001/1002/1006`; the error object carries `stableError` and `details.kind`.
+- Frozen error codes are only added, never modified; no drift.
+
+### Architectural invariants
+
+- The set of 18 top-level object classes is fixed; additions require an ADR; the error-code freeze does not drift.
+- The validator is exclusively Ajv 8.20.0 (exact pin); no other implementation is accepted.
+
+### Route elsewhere when
+
+- Consumer business Schema validation: stays with the caller.
+- Remote publish writing: route to release-skill.
+- Domain audit semantics: route to a standalone audit consumer.
 
-## 故障诊断
+### Machine-readable sources
 
-验证失败时 `errorCode` 为 `SFC1001`（SCHEMA_VALIDATION_FAILED，文档未通过目标 Schema 验证）；`$id` 未注册时报 `SFC1002`（UNKNOWN_SCHEMA_ID）。如失败，检查文档是否满足目标 Schema 的必填字段与类型约束。
+- Public capability catalog: [`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json) (`foundation.contracts.*` entries).
+- Package-local structural contract: `src/registry.json`, `src/schemas/*`.
+- Package-local candidate source: `candidate/quickstart-profile/*`; public import: `skill-family-contracts/candidate/quickstart-profile`.
+<!-- agent-quick-reference:end -->