skill-family-contracts 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+<!-- 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,21 @@
+# 变更日志
+
+<!-- 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,98 @@
 <!-- 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.2.1 -->
 
-本包拥有：十八类顶层对象的 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.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.
 
-| 对象 | `$id` | Schema 文件 |
+**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: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.2.1
+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.2.1
+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";
+```
+
+The subpath is public but **not stable**. Its schemas are deliberately absent from `src/registry.json`, do not expand the eighteen stable object classes, and may change or be removed in a later minor release. Consumers should pin the exact package version and keep candidate imports outside their stable public API. Use the root package export for production contracts that require frozen registry and compatibility guarantees.
+
+## 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 +111,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 +184,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 -->

package/README.zh-CN.md

@@ -0,0 +1,265 @@
+<!-- release-skill:safe-first-command -->
+<!-- release-skill:external-write-boundary -->
+
+> English version: [README.md](./README.md)
+
+# skill-family-contracts
+
+<!-- release-skill:release-version: 0.2.1 -->
+
+机器可执行工程结构和机制协议的唯一权威包（Contracts 1.4.0，冻结）。
+
+<!-- release-skill:managed:start id=latest-release -->
+**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:managed:end id=latest-release -->
+
+## 解决的问题
+
+技能族项目各自写一套结构契约，会出现 Schema 漂移、错误码不一致、协议名冲突。Contracts 把结构、协议、错误码与协议名登记收敛成一份冻结的机器可读权威，让 Harness 与 Kit 单向消费，不再各自解释。
+
+## 核心心智模型
+
+Contracts 是「定义与登记」层，不是「执行」层。它拥有十八类顶层对象的 JSON Schema、Kernel Protocol（内核协议）、稳定错误码、协议名与 `$id` 登记表，以及九种有限机械检查类型与受限强制规则集。本包不执行骨架生成、文件写入、审计或发布；机制实现由 Harness 承担，工程命令由 Kit 承担。
+
+Schema 验证完全基于 [Ajv](https://ajv.js.org/)（精确版本见 `package.json`），按方言路由到对应 Ajv 类；不实现任何手写 Schema 子集解释器。
+
+## 安装和最小示例
+
+```sh
+npm install skill-family-contracts@0.2.1
+npm info skill-family-contracts --help
+```
+
+最小示例从空目录开始，演示如何校验一份已登记契约对象：
+
+```js
+// 从空目录运行：npm install skill-family-contracts@0.2.1
+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);
+```
+
+以上代码展示了 `validateDocument` 的基本调用：传入文档与目标 Schema 的 `$id`，返回 `{ valid, errorCode, errors, data }`，其中 `data` 是规范化后的副本，原输入不被修改。
+
+## Candidate Quickstart Profile
+
+需要在进入冻结登记表前评估早期 Resource → Task → Result 交换时，使用 candidate Quickstart Profile：
+
+```js
+import {
+  QUICKSTART_PROTOCOL,
+  quickstartProfileSchemas,
+  validateQuickstartProfileDocument,
+} from "skill-family-contracts/candidate/quickstart-profile";
+```
+
+以上子路径公开但**不稳定**。这些 Schema 刻意不进入 `src/registry.json`，不扩张十八类稳定对象，后续小版本可以修改或移除。调用方需要锁定精确包版本，并避免把 candidate 导入转成自身稳定公共 API。生产合同若需要冻结登记与兼容性保证，继续使用包根导出。
+
+## 典型使用场景
+
+- 需要校验某份契约文档是否符合已登记 Schema：用 `validateDocument`。
+- 需要按对象名或 `$id` 查找 Schema、按协议名查找 Kernel 协议：用 `loadRegistry` / `findSchemaByObject` / `findProtocol`。
+- 需要运行强制机械规则、收集未解析引用：用 `runChecks` / `collectUnresolvedRefs`。
+- 需要枚举并校验公开 fixture：用 `verifyAllFixtures`。
+
+## 十八类顶层对象
+
+| 对象 | `$id` | Schema 文件 |
+| --- | --- | --- |
+| `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` |
+| `managed-file-lock` | `https://contracts.skill-family.example/v1/managed-file-lock.json` | `src/schemas/managed-file-lock.schema.json` |
+| `operation-request` | `https://contracts.skill-family.example/v1/operation-request.json` | `src/schemas/operation-request.schema.json` |
+| `operation-result` | `https://contracts.skill-family.example/v1/operation-result.json` | `src/schemas/operation-result.schema.json` |
+| `migration-manifest` | `https://contracts.skill-family.example/v1/migration-manifest.json` | `src/schemas/migration-manifest.schema.json` |
+| `report-model` | `https://contracts.skill-family.example/v1/report-model.json` | `src/schemas/report-model.schema.json` |
+| `report-binding` | `https://contracts.skill-family.example/v1/report-binding.json` | `src/schemas/report-binding.schema.json` |
+| `host-descriptor` | `https://contracts.skill-family.example/v1/host-descriptor.json` | `src/schemas/host-descriptor.schema.json` |
+| `host-capability-fact` | `https://contracts.skill-family.example/v1/host-capability-fact.json` | `src/schemas/host-capability-fact.schema.json` |
+| `adapter-build-manifest` | `https://contracts.skill-family.example/v1/adapter-build-manifest.json` | `src/schemas/adapter-build-manifest.schema.json` |
+| `host-operation-plan` | `https://contracts.skill-family.example/v1/host-operation-plan.json` | `src/schemas/host-operation-plan.schema.json` |
+| `host-operation-receipt` | `https://contracts.skill-family.example/v1/host-operation-receipt.json` | `src/schemas/host-operation-receipt.schema.json` |
+| `adapter-source` | `https://contracts.skill-family.example/v1/adapter-source.json` | `src/schemas/adapter-source.schema.json` |
+| `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.json` |
+
+所有 v1 Schema 使用 draft 2020-12 方言；实例信封统一为 `schemaVersion: 1` + 唯一 `kind` 常量 + 各层 `additionalProperties: false`。`$id` 命名空间 `contracts.skill-family.example` 使用保留示例域，永不解析到真实站点。
+
+## Kernel Protocol（内核协议）
+
+登记表：`src/registry.json`；冻结定义：`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` 必填）。新增操作名属于合同变更，需新版本登记。
+
+重名协议与重复 `$id` 被机械拒绝：`registerProtocol` 抛出 `SFC1004`，`registerSchema` 抛出 `SFC1003`；检查类型 `protocol.unique-name` 与 `schema.unique-id` 对登记表做同样判定。
+
+## 稳定错误码
+
+冻结登记表：`src/error-codes.json`。`SFC1xxx` 为合同权威层错误，`SFC2xxx` 为内核操作错误，`SFC3xxx` 为报告绑定错误。码只增不改、不复用。v1 冻结：
+
+| 码 | 名称 | 含义摘要 |
+| --- | --- | --- |
+| 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）样例。每个 fixture 声明目标 Schema、方言、策略与期望；反例期望携带稳定失败码。`verifyAllFixtures()` 机械重放全部期望，行为不符报 `SFC1010`。fixture 是完全虚构数据，不是审计 oracle。
+
+## API 概览
+
+```js
+import {
+  CONTRACT_OBJECTS, CONTRACTS_VERSION,
+  validateDocument, SUPPORTED_DIALECTS, VALIDATION_POLICIES, detectDialect,
+  loadRegistry, registerSchema, registerProtocol,
+  loadKernelProtocol, checkOperation,
+  runChecks, CHECK_TYPES, MANDATORY_RULES, RULE_BUDGET,
+  listFixtures, verifyAllFixtures,
+  ERROR_CODES, ContractsError, stableError,
+} from "skill-family-contracts";
+```
+
+以上导入列出了本包稳定公共面；`validateDocument` 与 `runChecks` 是最常用入口。`validateDocument(document, { schemaId | schema, dialect, policy })` 返回 `{ valid, errorCode, errors, data }`；`runChecks({ rules?, registry?, fixtures?, loadSchema? })` 返回 `{ ok, mandatoryCount, budget, results }`；`registerSchema` / `registerProtocol` 返回新登记表副本，重复项分别以 `SFC1003` / `SFC1004` 抛出 `ContractsError`。
+
+## 安全边界与非目标
+
+不拥有生成、语义审计、发布状态与远端写入；不定义清理计划、发布快照、消费者冒烟结果、领域审计报告或自由文本规则语言；不建通用 DSL。冻结内容的变更只能作为新的合同版本任务进行。
+
+## 故障诊断
+
+验证失败时 `errorCode` 为 `SFC1001`（SCHEMA_VALIDATION_FAILED，文档未通过目标 Schema 验证）；`$id` 未注册时报 `SFC1002`（UNKNOWN_SCHEMA_ID）。如失败，检查文档是否满足目标 Schema 的必填字段与类型约束。
+
+## 深入文档入口
+
+- 架构边界与路由：[架构说明](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/)、[智能体架构路由](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- 能力目录：[capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- 当前产品状态：[公开状态](https://ifoohoo.github.io/skill-family-engineering-kit/public/status/)
+
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
+
+### Use when
+
+- 需要校验已登记契约对象、查找 Schema/协议、运行强制机械规则。
+- 需要枚举并校验公开 fixture，或确定性序列化契约表面。
+- 需要在锁定精确包版本后评估非稳定的 Quickstart Resource/Task/Result Profile。
+
+### Do not use when
+
+- 需要校验消费者自有业务 Schema（消费者应自行持有，Foundation 不取代）。
+- 需要把领域语义校验混入通用契约。
+- 需要兼容性已冻结的 Quickstart Profile；candidate 子路径尚未登记为 stable。
+
+### Capability selection
+
+- `foundation.contracts.object-validation`：Ajv 双方言校验 18 类对象。
+- `foundation.contracts.registry-protocol`：Schema `$id` 与协议名登记查询。
+- `foundation.contracts.kernel-protocol`：operation-request/result 协议。
+- `foundation.contracts.mandatory-checks`：九类强制规则与未解析引用。
+- `foundation.contracts.fixture-verification`：fixture 全量回放。
+- `foundation.contracts.error-codes`：稳定错误码体系。
+- `foundation.contracts.audit-surface`：canonical JSON + sha256 摘要。
+- `foundation.contracts.quickstart-profile-candidate`：通过精确版本子路径使用 candidate-only Resource/Task/Result Schema 与校验。
+
+### Required inputs
+
+- 待校验文档（带已登记 `$id`）或目标契约对象名。
+- 校验策略 `strict`（默认）或 `tolerant`。
+
+### Outputs and evidence
+
+- `validateDocument` 返回 `{ valid, errorCode, errors, data }`。
+- 证据：`packages/skill-family-contracts/test/validator.test.mjs`、`registry.test.mjs`、`checker.test.mjs`、`fixtures.test.mjs`。
+
+### Side effects
+
+- 纯函数，无文件系统、Git、网络或进程副作用（编译缓存仅驻留内存）。
+
+### Failure semantics
+
+- `SFC1001/1002/1006` 等稳定错误码，错误对象含 `stableError` 与 `details.kind`。
+- 冻结错误码只增不改，不漂移。
+
+### Architectural invariants
+
+- 18 类顶层对象集合固定，新增需 ADR；错误码冻结不漂移。
+- 校验器仅 Ajv 8.20.0（精确 pin），不接受其他实现。
+
+### Route elsewhere when
+
+- 消费者业务 Schema 校验：留在调用方。
+- 发布远端写入：转 release-skill。
+- 领域审计语义：转独立审计消费者。
+
+### Machine-readable sources
+
+- 公开能力目录：[`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)（`foundation.contracts.*` 条目）。
+- 包内结构合同：`src/registry.json`、`src/schemas/*`。
+- 包内 Candidate 源：`candidate/quickstart-profile/*`；公共导入：`skill-family-contracts/candidate/quickstart-profile`。
+<!-- agent-quick-reference:end -->

package/candidate/quickstart-profile/fixtures/resource-negative-bad-digest.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.resource",
+  "id": "observation-main",
+  "location": {
+    "path": "inputs/observation.json"
+  },
+  "role": "observation",
+  "digest": {
+    "algorithm": "sha256",
+    "value": "not-a-digest"
+  }
+}

package/candidate/quickstart-profile/fixtures/resource-positive.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.resource",
+  "id": "observation-main",
+  "location": {
+    "path": "inputs/observation.json"
+  },
+  "role": "observation",
+  "digest": {
+    "algorithm": "sha256",
+    "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}

package/candidate/quickstart-profile/index.mjs

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { detectDialect, validateDocument } from "../../src/validator.mjs";
+
+const documents = Object.freeze({
+  resource: load("resource.schema.json"),
+  task: load("task.schema.json"),
+  result: load("result.schema.json"),
+});
+
+function load(name) {
+  return Object.freeze(
+    JSON.parse(readFileSync(new URL(name, import.meta.url), "utf8")),
+  );
+}
+
+export const QUICKSTART_PROFILE_ID = "quickstart-profile";
+export const QUICKSTART_PROFILE_VERSION = 1;
+export const QUICKSTART_PROTOCOL = Object.freeze({
+  name: "skill-family.quickstart-profile",
+  version: 1,
+});
+
+/** Candidate-only schemas. They are deliberately absent from registry.json. */
+export function quickstartProfileSchemas() {
+  return structuredClone(documents);
+}
+
+function linkResourceSchema(schema) {
+  const linked = structuredClone(schema);
+  const resourceId = documents.resource.$id;
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (value.$ref === resourceId) value.$ref = "#/$defs/quickstartResource";
+    for (const child of Object.values(value)) visit(child);
+  };
+  visit(linked);
+  linked.$defs = {
+    ...(linked.$defs ?? {}),
+    quickstartResource: structuredClone(documents.resource),
+  };
+  return linked;
+}
+
+/** Validate one candidate profile document through the shared Ajv validator. */
+export function validateQuickstartProfileDocument(kind, document) {
+  if (!Object.hasOwn(documents, kind)) {
+    throw new TypeError(`unknown quickstart profile document kind: ${String(kind)}`);
+  }
+  const schema = kind === "resource" ? documents.resource : linkResourceSchema(documents[kind]);
+  return validateDocument(document, {
+    schema,
+    dialect: detectDialect(schema),
+    policy: "strict",
+  });
+}

package/candidate/quickstart-profile/resource.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json",
+  "title": "QuickstartResource",
+  "description": "Candidate Resource profile for one content-addressed observation, output, or evidence item.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "id", "location", "role", "digest"],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "kind": {
+      "const": "skill-family.resource"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "location": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
+        },
+        "uri": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:.+$"
+        }
+      },
+      "oneOf": [
+        {
+          "required": ["path"],
+          "properties": {
+            "path": {}
+          }
+        },
+        {
+          "required": ["uri"],
+          "properties": {
+            "uri": {}
+          }
+        }
+      ]
+    },
+    "role": {
+      "enum": ["observation", "output", "evidence"]
+    },
+    "digest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": {
+          "const": "sha256"
+        },
+        "value": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    }
+  }
+}

package/candidate/quickstart-profile/result.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/result.json",
+  "title": "QuickstartResult",
+  "description": "Candidate narrow profile over the stable terminal operation-result envelope.",
+  "allOf": [
+    {
+      "$ref": "https://contracts.skill-family.example/v1/operation-result.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": {
+            "name": "skill-family.quickstart-profile",
+            "version": 1
+          }
+        },
+        "operation": {
+          "const": "audit"
+        },
+        "outputs": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/outputs"
+            }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "state": {
+                "const": "succeeded"
+              }
+            },
+            "required": ["state"]
+          },
+          "then": {
+            "type": "object",
+            "required": ["outputs"],
+            "properties": {
+              "outputs": {
+                "$ref": "#/$defs/outputs"
+              }
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "$defs": {
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run", "stage", "attempt"],
+      "properties": {
+        "run": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "stage": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "taskBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operationId", "taskDigest", "observationId", "observationDigest", "correlation"],
+      "properties": {
+        "operationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "taskDigest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "observationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "observationDigest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "correlation": {
+          "$ref": "#/$defs/correlation"
+        }
+      }
+    },
+    "outputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "outputs", "evidence", "domainResult", "taskBinding"],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "outputs": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              {
+                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "role": {
+                    "const": "output"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              {
+                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "role": {
+                    "const": "evidence"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "domainResult": {},
+        "taskBinding": {
+          "$ref": "#/$defs/taskBinding"
+        }
+      }
+    }
+  }
+}

package/candidate/quickstart-profile/task.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/task.json",
+  "title": "QuickstartTask",
+  "description": "Candidate narrow profile over the stable operation-request envelope.",
+  "allOf": [
+    {
+      "$ref": "https://contracts.skill-family.example/v1/operation-request.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": {
+            "name": "skill-family.quickstart-profile",
+            "version": 1
+          }
+        },
+        "operation": {
+          "const": "audit"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["method", "parameters", "inputs", "correlation"],
+          "properties": {
+            "method": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+            },
+            "parameters": {
+              "type": "object"
+            },
+            "inputs": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 1,
+              "items": {
+                "allOf": [
+                  {
+                    "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "location": {
+                        "type": "object",
+                        "required": ["path"],
+                        "properties": {
+                          "path": {}
+                        }
+                      },
+                      "role": {
+                        "const": "observation"
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            "correlation": {
+              "$ref": "#/$defs/correlation"
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run", "stage", "attempt"],
+      "properties": {
+        "run": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "stage": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -11,9 +11,19 @@
   "engines": {
     "node": ">=22.22.2 <23"
   },
-  "exports": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./candidate/quickstart-profile": "./candidate/quickstart-profile/index.mjs"
+  },
   "files": [
     "src",
+    "candidate",
+    "release-notes",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh-CN.md",
+    "NOTICE",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md"
@@ -27,7 +37,7 @@
     "url": "https://github.com/ifoohoo/skill-family-contracts.git"
   },
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.2.1.yaml

@@ -0,0 +1,23 @@
+version: 0.2.1
+date: 2026-08-10
+locales:
+  en:
+    summary: This release adds a candidate Quickstart Profile contract surface and makes the package release documentation available in English and Simplified Chinese.
+    changes:
+      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.
+    upgradeNotes: 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.
+  zh-CN:
+    summary: 本版新增 Quickstart Profile 候选契约面，并为包发布文档提供完整英文版与简体中文版。
+    changes:
+      added:
+        - 新增候选 Resource、Task、Result Schema 及其严格校验辅助函数。这组候选 Schema 不进入稳定 Contracts 登记表。
+        - 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+      changed:
+        - 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+        - 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+    upgradeNotes: 稳定登记表的消费者无需修改。Quickstart Profile 只能通过 candidate 子路径导入，不得把它当作已冻结的 Contracts 对象。