@kungfu-tech/kfd 1.0.0-alpha.1 → 1.0.0-alpha.13

package/README.md

@@ -5,6 +5,8 @@ set of standing, cross-repository norms that products and their consumers
 weld to. Each decision has an immutable number (`KFD-N`), a kind, a status,
 and a single authoritative text in this repository.
 
+Stable rendered site: `https://kfd.libkungfu.dev`.
+
 KFDs can be **principles** or **procedures**. Principles state what must remain
 true across kungfu-systems; procedures state how a class of work enforces or
 protects a principle.
@@ -14,14 +16,14 @@ protects a principle.
 The first three KFDs form the public foundation for kungfu-systems:
 
 ```text
-KFD-1: contracts must not drift.
+KFD-1: facts must not drift.
 KFD-2: trust must start from facts.
-KFD-3: cooperation must start from transparent value, not coercion.
+KFD-3: cooperation must start from transparent value.
 ```
 
-Together they define the load-bearing path for Kungfu products: make contract
-worlds explicit, make important claims inspectable, and let humans and agents
-cooperate through visible value rather than hidden pressure.
+Together they define the load-bearing path for Kungfu products: make facts
+non-drifting, make trust inspectable from those facts, and let humans and
+agents cooperate through visible value rather than hidden pressure.
 
 ## Foundation model
 
@@ -31,22 +33,21 @@ act, delegate, and remember across many surfaces.
 
 | Layer | Decision | Reader question | Commitment |
 |---|---|---|---|
-| Fact-source ontology | KFD-1 | What can count as a fact? | A load-bearing fact must not drift: its contract world comes from one declared fact source. |
+| Fact-source ontology | KFD-1 | What can count as a fact? | Facts must not drift: a load-bearing contract world comes from one declared fact source. |
 | Participant-to-object trust | KFD-2 | When can a user or agent trust a claim, product, artifact, or control surface? | Trust starts from inspectable facts and responsibility state. |
 | Participant-to-participant cooperation | KFD-3 | How should peer intelligent participants cooperate? | Cooperation starts from transparent value, stable choice, and explainable constraints, not pressure. |
 
 In short:
 
 ```text
-stable facts -> trustworthy objects -> non-coercive cooperation
+non-drifting facts -> inspectable trust -> transparent cooperation
 ```
 
-This is why KFDs are not only internal governance text. KFD-1 is a procedure,
-but it gives the foundation model its first layer by making fact sources
-operational: a fact-bearing contract world must be declared, inspectable, and
-unable to drift invisibly. KFD-2 then defines how trust can stand on those
-facts. KFD-3 defines how humans and agents can cooperate once facts and trust
-are visible.
+This is why KFDs are not only internal governance text. KFD-1 gives the
+foundation model its first layer by making fact sources operational: a
+fact-bearing contract world must be declared, inspectable, and unable to drift
+invisibly. KFD-2 then defines how trust can stand on those facts. KFD-3
+defines how humans and agents can cooperate once facts and trust are visible.
 
 Real-world agent work turns ordinary work into a dense system of products,
 files, repositories, traces, policies, humans, and agents. In that world,
@@ -89,7 +90,7 @@ The first screen should be derived from this README:
 - Foundation signal: the `Foundation triad` section, especially the three
   one-line commitments.
 - First-screen explanation: the beginning of `Foundation model`, ending at the
-  `stable facts -> trustworthy objects -> non-coercive cooperation` chain.
+  `non-drifting facts -> inspectable trust -> transparent cooperation` chain.
 
 Decision cards, detail links, and machine paths should come from
 `registry.json`. The machine-readable site bundle lives at `site/kfd-site.json`
@@ -102,10 +103,14 @@ separate homepage wording that can drift from this package.
 
 KFDs are not a detached manifesto, but they are not a demand that readers adopt
 a Kungfu product before understanding the decisions. A philosophy becomes
-load-bearing only when it can be seen in a concrete case. For that reference
-case, use the main Kungfu product entrypoint (`https://kungfu.tech`) for product
-philosophy, and Buildchain (`https://buildchain.libkungfu.dev`) for release and
-provenance accountability. This registry states the commitments; those
+load-bearing only when it can be seen in a concrete case. The first concrete
+case is this package itself: `standards.json`, `schemas/`, `docs/`,
+`site/kfd-site.json`, and `scripts/check.mjs` show how KFD-1, KFD-2, and KFD-3
+are expressed as consumable interfaces for both humans and agents. For the
+broader product case, use the main Kungfu product entrypoint
+(`https://kungfu.tech`) for product philosophy, and Buildchain
+(`https://buildchain.libkungfu.dev`) for release and provenance
+accountability. This registry states the commitments; this package and those
 entrypoints show how the commitments are meant to be borne in practice.
 
 Rendered index: `https://kfd.libkungfu.dev` (stable machine path per entry,
@@ -113,13 +118,80 @@ e.g. `https://kfd.libkungfu.dev/1`). This repository publishes
 `@kungfu-tech/kfd` — the decision texts plus a machine-readable
 `registry.json` — which the site consumes as its single fact source.
 
+Machine consumers that need KFD-owned standard identity should read
+`standards.json`. It is the versioned metadata surface for stable standard
+keys, document routes and SHA-256 digests, schema IDs, KFD-owned concept names,
+and machine-interface contract versions. In Node or TypeScript projects, import
+it as:
+
+```js
+import standards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
+```
+
+## Agent Quickstart
+
+Agents consuming this package should start from the same sources as humans:
+
+1. Read this README for the foundation model and package map.
+2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,
+   and interface contracts.
+3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration
+   interface fact-source metadata to identify the public KFD fact source.
+4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and
+   trust-downgrade values. Unknown taxonomy values are invalid.
+5. Use `schemas/kfd-3/collaboration-interface.schema.json` and
+   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.
+6. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather
+   than inventing a local value:
+   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.
+
+KFD package semver is only the distribution version. KFD-owned machine
+interfaces carry their own `schemaVersion` and `contract` fields. Compatible
+additions may keep the same interface version; semantic changes, required-field
+changes, verification meaning changes, or responsibility-boundary changes must
+use a new interface version or contract.
+
+KFD-2 publishes trust-taxonomy, release-claims, and release-trust-passport
+schemas under `schemas/kfd-2/`. These schemas let Buildchain and other release
+systems audit whether public release claims are bound to source facts,
+evidence, hashes, audit boundaries, residual risk, and responsibility state. See
+[`docs/kfd-2-release-trust.md`](docs/kfd-2-release-trust.md).
+
+KFD-3 also publishes a general collaboration-interface schema and witness
+schema under `schemas/kfd-3/`. These schemas are for participant-facing product
+interfaces, not only agent APIs. A product such as Kungfu may implement an
+agent-first profile, but that profile remains a product-specific realization of
+KFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and
+closed-world evidence shape. See
+[`docs/kfd-3-collaboration-interface.md`](docs/kfd-3-collaboration-interface.md).
+
 ## Current decisions
 
-| ID | Kind | Title | Status |
+| ID | Kind | Axiom | Status |
 |---|---|---|---|
-| [KFD-1](decisions/kfd-1.md) | procedure | Contracts must not drift: contract worlds need one fact source | active |
-| [KFD-2](decisions/kfd-2.md) | principle | Trust must start from facts: responsibility must be inspectable | active |
-| [KFD-3](decisions/kfd-3.md) | principle | Cooperation must start from transparent value: compliance must not be coerced | active |
+| [KFD-1](decisions/kfd-1.md) | procedure | Facts must not drift. | active |
+| [KFD-2](decisions/kfd-2.md) | principle | Trust must start from facts. | active |
+| [KFD-3](decisions/kfd-3.md) | principle | Cooperation must start from transparent value. | active |
+
+## Decision metadata
+
+Every rendered decision page should make the KFD fact source explicit. The
+public KFD fact source is the GitHub-hosted `kungfu-systems/kfd` git
+repository. GitHub is the current canonical coordination and hosting surface;
+the load-bearing facts are the commit-addressed repository contents.
+
+Decision metadata should expose:
+
+- Public fact source: `https://github.com/kungfu-systems/kfd`
+- Load-bearing coordinate: commit-addressed repository contents.
+- Canonical paths: `decisions/kfd-N.md`, `registry.json`, `standards.json`.
+- Stable rendered index: `https://kfd.libkungfu.dev`.
+- Rendered URL: `https://kfd.libkungfu.dev/N`.
+
+Rendered pages, npm package contents, Buildchain release passports, and
+`kfd.libkungfu.dev` are projections or evidence surfaces. A GitHub issue is an
+extension request path, not a KFD fact by itself; it becomes part of the KFD
+fact source only after the resulting change is committed to the repository.
 
 ## How to cite
 
@@ -137,18 +209,25 @@ reference KFDs; KFDs never depend on repository internals.
 ```text
 decisions/     one markdown file per decision (kfd-N.md)
 registry.json  machine-readable index (schemaVersion 1, contract kfd-registry)
+standards.json machine-readable KFD standard metadata (schemaVersion 1,
+               contract kfd-standards-metadata)
+schemas/       JSON schemas for package metadata and KFD-owned schema IDs
 site/          machine-readable site bundle for kfd.libkungfu.dev renderers
+buildchain.release-propagation.json
+               Buildchain release propagation graph for KFD -> site consumers
 release-impact.json
                Buildchain surface-aware impact ledger for production release passports
 scripts/       conformance check: registry and documents must agree
 ```
 
 `node scripts/check.mjs` (also `pnpm run check`) verifies numbering
-uniqueness, registry/document agreement, status validity, and the release
-impact ledger required by Buildchain production release passports. Releases are
-governed by Buildchain; this package versions itself under KFD-1's own rules:
-the outer package line remains `v1.0`, while patch and prerelease numbers are
-advanced by Buildchain release promotion.
+uniqueness, registry/document agreement, standards metadata/schema agreement,
+status validity, decision document SHA-256 bindings, interface contract
+version bindings, and the release impact ledger required by Buildchain
+production release passports. Releases are governed by Buildchain; this package
+versions itself under KFD-1's own rules: the outer package line remains `v1.0`,
+while patch and prerelease numbers are advanced by Buildchain release
+promotion.
 
 ## Release impact ledger
 
@@ -166,6 +245,10 @@ paths, or published structure under KFD-1. These values are Buildchain release
 passport impact classifications; they do not by themselves open a new
 `@kungfu-tech/kfd` package major or minor line.
 
-## License
+## License and official status
 
-[Apache License 2.0](LICENSE).
+Repository contents are licensed under the [Apache License 2.0](LICENSE).
+Apache-2.0 grants broad reuse rights for the licensed contents, but it does
+not grant KFD/Kungfu trademarks, official status, certification status, or
+endorsement. The official source, name-use, fork, derivative, and agent-facing
+authority boundaries are defined in [`TRADEMARKS.md`](TRADEMARKS.md).

package/TRADEMARKS.md

@@ -0,0 +1,60 @@
+# Trademarks and Official Status
+
+The contents of this repository are licensed under the Apache License 2.0.
+That license covers use, reproduction, modification, and distribution of the
+licensed repository contents under the terms of `LICENSE`.
+
+Apache-2.0 does not grant trademark rights, official project status,
+certification status, or endorsement by kungfu-systems.
+
+## Names and marks
+
+The names `Kungfu`, `Kung Fu Decisions`, `KFD`, `kungfu-systems`,
+`@kungfu-tech`, and related project names, logos, domains, and package names
+identify kungfu-systems projects and release surfaces. They may be used for
+accurate, non-misleading reference to the origin of the work, but not to imply
+official status, certification, endorsement, or project ownership.
+
+## Official sources
+
+The current public KFD fact source is:
+
+```text
+https://github.com/kungfu-systems/kfd
+```
+
+The stable rendered KFD site is:
+
+```text
+https://kfd.libkungfu.dev
+```
+
+The public npm package is:
+
+```text
+npm:@kungfu-tech/kfd
+```
+
+Those surfaces are official only when published or controlled by
+kungfu-systems. Forks, mirrors, local copies, downstream packages, generated
+sites, and derivative works are not official KFD sources unless kungfu-systems
+explicitly says so.
+
+## Forks and derivatives
+
+Forks and derivative works may say that they are based on KFD or implement
+specific KFD decisions when that statement is accurate. They must not describe
+themselves as the official KFD registry, canonical KFD release, certified KFD
+implementation, or kungfu-systems-approved project unless that status has been
+explicitly granted by kungfu-systems.
+
+If a derivative changes KFD content, metadata, schemas, or package surfaces, it
+should make those changes clear to readers and agents so that official KFD
+facts do not drift into derivative facts.
+
+## Agent-facing rule
+
+An agent consuming KFD should treat Apache-2.0 as permission to reuse the
+licensed repository contents, not as permission to claim official KFD authority.
+When official status matters, the agent should resolve facts through the
+public KFD fact source and the metadata surfaces declared in this repository.

package/buildchain.release-propagation.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-release-propagation-graph",
+  "nodes": [
+    {
+      "id": "kfd",
+      "repository": "kungfu-systems/kfd",
+      "package": "@kungfu-tech/kfd"
+    },
+    {
+      "id": "site-libkungfu-dev",
+      "repository": "kungfu-systems/site-libkungfu-dev",
+      "lockPath": "buildchain.upstreams/kfd.release.json",
+      "baseRef": "main"
+    }
+  ],
+  "edges": [
+    {
+      "id": "kfd-to-site-libkungfu-dev",
+      "from": "kfd",
+      "to": "site-libkungfu-dev",
+      "channelPolicy": "preserve",
+      "consumes": [
+        "@kungfu-tech/kfd",
+        "site/kfd-site.json",
+        "registry.json",
+        "standards.json",
+        "decisions/*.md"
+      ]
+    }
+  ]
+}

package/decisions/kfd-1.md

@@ -1,4 +1,4 @@
-# KFD-1: Contracts must not drift — contract worlds need one fact source
+# KFD-1: Facts must not drift — contract worlds need one fact source
 
 - Status: active
 - Number: 1
@@ -7,27 +7,30 @@
 
 ## One sentence
 
-A contract world must not change invisibly: any surface that users, agents, or
-systems weld to must come from one declared fact source and change only through
-an explicit compatibility boundary.
+Facts must not drift.
+
+Any contract world that users, agents, or systems weld to must come from one
+declared fact source and change only through an explicit compatibility
+boundary.
 
 ## Foundation role
 
-Within the KFD-1/2/3 foundation, this is the contract procedure:
+Within the KFD-1/2/3 foundation, this is the fact-source procedure:
 
 ```text
-contracts must not drift
+facts must not drift
 ```
 
-KFD-1 makes artifact contract worlds explicit so releases do not drift under
-changelog volume, cadence pressure, or marketing pressure. It is the concrete
-versioning procedure that lets users and agents know which artifact world they
-are integrating with, replaying, auditing, or trusting.
+KFD-1 makes fact-bearing contract worlds explicit so they do not drift under
+changelog volume, cadence pressure, implementation pressure, or marketing
+pressure. It is the procedure that lets users and agents know which fact world
+they are integrating with, replaying, auditing, or trusting.
 
-KFD-1 now has two concrete implementation surfaces in the Kungfu ecosystem:
-versioning protects release lines from contract drift, and config contracts
-protect multi-target configuration from drifting across runtimes, products, and
-agent-facing surfaces.
+KFD-1 has concrete implementation surfaces across the Kungfu ecosystem:
+versioning protects release lines from contract drift, config contracts protect
+multi-target configuration from drifting across runtimes, products, and
+agent-facing surfaces, and KFD metadata protects the decision package's own
+standard surfaces from drifting away from their declared source.
 
 ## Premise: the welded-surface register
 
@@ -140,17 +143,16 @@ table and the machine record never diverge): `schemaVersion: 1`,
 
 ## Relation to KFD-2 and KFD-3
 
-KFD-2 establishes fact-first product accountability: important claims should
-be inspectable before users or agents are asked to trust them. KFD-1 is the
-contract-layer expression of the same single-fact-source discipline: it
-preserves accountability across artifact contract worlds before those artifacts
-are used to produce runtime facts, responsibility state, or proof-backed
-decisions.
+KFD-2 establishes fact-first product accountability: trust must start from
+facts. KFD-1 defines the lower layer that makes such facts load-bearing:
+important facts must not drift from the contract world that declares them.
+Without KFD-1, KFD-2 would have facts that cannot reliably be re-read,
+replayed, audited, or trusted over time.
 
 KFD-3 establishes non-coercive cooperation with intelligent participants. That
-cooperation depends on the same contract clarity: users and agents can choose,
-delegate, replay, or refuse more honestly when the artifact world is legible
-and does not drift invisibly.
+cooperation depends on non-drifting facts: users and agents can choose,
+delegate, replay, or refuse more honestly when the fact world is legible and
+does not drift invisibly.
 
 ## How KFDs themselves are versioned
 
@@ -164,6 +166,18 @@ registry schema, the package structure) can still require `minor` or `major`
 surface-impact review in the Buildchain release passport, but that review
 classification is not a silent package-line upgrade.
 
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package is a self-proof case for this procedure.
+Its decision texts, `registry.json`, `standards.json`, schemas, site bundle,
+and release propagation graph are published as stable surfaces. Their contract
+world is not inferred from README prose or package version alone: it is exposed
+through `standards.json`, checked by `scripts/check.mjs`, and bound into the
+KFD-1 witness under `.buildchain/kfd-1/contract-world.witness.json`.
+
+This lets humans and agents inspect how the KFD package prevents its own
+contract surfaces from drifting while it evolves.
+
 ## Adopters
 
 Each adopting repository keeps an adoption record, its welded-surface

package/decisions/kfd-2.md

@@ -7,6 +7,8 @@
 
 ## One sentence
 
+Trust must start from facts.
+
 A product must not ask users or agents to trust important claims before the
 relevant facts are inspectable, local where possible, and connected to
 responsibility state.
@@ -19,8 +21,9 @@ KFDs can be principles or procedures:
   products, repositories, and release lines change.
 - A **procedure** states how a class of work enforces or protects a principle.
 
-This KFD is a principle. KFD-1 is a procedure that protects release and
-version responsibility under this principle.
+This KFD is a principle. KFD-1 is the procedure that keeps the fact sources
+under this principle from drifting. KFD-3 is the principle that governs how
+humans and agents cooperate once facts and trust are visible.
 
 ## Foundation role
 
@@ -31,9 +34,9 @@ trust must start from facts
 ```
 
 KFD-2 says Kungfu products should not ask users or agents to trust a claim
-before the product has made the relevant facts inspectable. KFD-1 protects
-contract truth across artifact lines. KFD-3 protects the relationship with the
-human or agent who must understand and act on those facts.
+before the product has made the relevant facts inspectable. KFD-1 protects the
+non-drifting fact source those claims stand on. KFD-3 protects the relationship
+with the human or agent who must understand and act on those facts.
 
 ## Principle
 
@@ -81,14 +84,15 @@ leaves enough evidence for later review.
 
 ## Relation to KFD-1
 
-KFD-1 is a procedure. It makes release and version responsibility legible when
-contract worlds change. KFD-2 is the higher-level principle: versioning,
-release evidence, fact ledgers, agent control panes, extension gates, and
-hosted services should all preserve the path from fact source to responsibility
-state to proof-backed decision.
+KFD-1 is a procedure. It defines what can count as a load-bearing fact source:
+facts must not drift from the contract world that declares them. KFD-2 is the
+next layer: once facts are non-drifting and inspectable, trust claims must be
+bound to those facts and to responsibility state.
 
 KFD-2 does not supersede KFD-1. KFD-1 remains active and is one concrete
-procedure that implements KFD-2 for version and release responsibility.
+procedure that implements KFD-2 wherever trust depends on contract worlds,
+release evidence, fact ledgers, agent control panes, extension gates, hosted
+surfaces, schemas, configs, or package metadata.
 
 ## Supersession rule
 
@@ -98,6 +102,21 @@ explicitly and the registry records the affected decision. Two active KFDs that
 conflict without an explicit supersession relationship are a registry defect,
 not an invitation to pick the newer text silently.
 
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package is a self-proof case for this principle.
+It does not ask humans or agents to trust the KFD registry only because the
+README says so. It publishes inspectable facts: decision documents,
+`registry.json`, `standards.json`, JSON schemas, document hashes, release-impact
+metadata, and conformance checks.
+
+KFD-2 also owns the trust taxonomy used by release claims, release trust
+passports, and KFD-3 witnesses. Unknown residual-risk or trust-downgrade values
+fail validation until KFD records them in
+`schemas/kfd-2/trust-taxonomy.schema.json`. When an agent needs a new value,
+the declared extension path is to open an issue in
+`https://github.com/kungfu-systems/kfd` rather than inventing a private value.
+
 ## Adopters
 
 Each adopting repository cites this KFD when designing or changing a fact

package/decisions/kfd-3.md

@@ -7,6 +7,8 @@
 
 ## One sentence
 
+Cooperation must start from transparent value.
+
 A product must not obtain cooperation through pressure, manipulation, hidden
 control, or forced workflow capture. It must make value, choices, and
 constraints visible enough for intelligent participants to understand, decide,
@@ -28,11 +30,11 @@ kungfu-systems takes toward humans and agents as reasoning participants.
 Within the KFD-1/2/3 foundation, this is the relationship path:
 
 ```text
-cooperation must start from transparent value, not coercion
+cooperation must start from transparent value
 ```
 
 KFD-2 protects the truth path: show facts before asking for trust. KFD-3
-protects the relationship path: show value before asking for compliance.
+protects the relationship path: show value before asking for cooperation.
 
 ## Principle
 
@@ -151,12 +153,29 @@ KFD-3 says the path of least resistance should not be built from pressure or
 hidden control. Together:
 
 ```text
-KFD-2: show the facts before asking for trust.
-KFD-3: show the value before asking for compliance.
+KFD-1: facts must not drift.
+KFD-2: trust must start from facts.
+KFD-3: cooperation must start from transparent value.
 ```
 
-KFD-2 protects the truth path. KFD-3 protects the relationship with the
-intelligent participant who must walk that path.
+KFD-1 protects the fact-source layer. KFD-2 protects the trust layer. KFD-3
+protects the relationship with the intelligent participant who must walk that
+path.
+
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package is a self-proof case for this principle.
+Its README gives humans and agents the same quickstart path. `standards.json`
+gives stable standard identity, schema IDs, and concept names. The KFD-3
+schemas define collaboration interfaces, witnesses, and extension requests, so
+an agent can discover both the valid interface and the standard path for asking
+to extend it.
+
+For example, if an agent needs a KFD-2 trust-taxonomy value that does not
+exist, the KFD-3 collaboration path is not hidden maintainer pressure or local
+invention. The declared path is a visible GitHub issue in the KFD repository,
+where the new value can be reviewed and, if accepted, added to the KFD-owned
+taxonomy for everyone.
 
 ## Adopters
 

package/docs/MAP.md

@@ -5,10 +5,19 @@
 | What is KFD, and what decisions exist? | [`../README.md`](../README.md) |
 | What is the KFD-1/2/3 foundation triad? | [`../README.md`](../README.md#foundation-triad) |
 | What worldview structure does the foundation triad express? | [`../README.md`](../README.md#foundation-model) |
+| How should an agent quickly understand this package? | [`../README.md`](../README.md#agent-quickstart) |
+| What is the concrete self-proof case for KFD-1/2/3? | [`../README.md`](../README.md#product-proof-path) and the implementation case in each KFD |
+| Where is the public KFD fact source? | [`../README.md`](../README.md#decision-metadata) and [`../site/kfd-site.json`](../site/kfd-site.json) decision metadata |
+| What does Apache-2.0 cover, and what remains official/trademark-bound? | [`../TRADEMARKS.md`](../TRADEMARKS.md) |
 | What should a site renderer consume to render `kfd.libkungfu.dev`? | [`../site/kfd-site.json`](../site/kfd-site.json) |
 | What is the top-level product accountability principle? | [KFD-2](../decisions/kfd-2.md) |
 | What stance should products take toward humans and agents as reasoning participants? | [KFD-3](../decisions/kfd-3.md) |
+| What schema should products use for KFD-3 participant-facing collaboration interfaces? | [`kfd-3-collaboration-interface.md`](kfd-3-collaboration-interface.md) |
+| What should an agent do when a needed KFD-2 trust taxonomy value is missing? | [`kfd-2-release-trust.md`](kfd-2-release-trust.md#trust-taxonomy) — open a KFD GitHub issue |
 | What does a specific decision say? | [`../decisions/`](../decisions) (index: [`../registry.json`](../registry.json)) |
+| What machine metadata should Buildchain or another consumer import for KFD standard identity and schema IDs? | [`../standards.json`](../standards.json) |
+| What schema validates the standards metadata surface? | [`../schemas/kfd-standards.schema.json`](../schemas/kfd-standards.schema.json) |
+| What schema should release systems use for KFD-2 release claims and trust passports? | [`kfd-2-release-trust.md`](kfd-2-release-trust.md) |
 | How do I cite a decision? | [`../README.md`](../README.md) — cite by number, e.g. `KFD-1` |
 | How do decisions change over time? | [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — append-only; explicit supersession mints a new number |
 | How is this package versioned and released? | [KFD-1](../decisions/kfd-1.md) applied to itself; Buildchain governs releases |

package/docs/kfd-2-release-trust.md

@@ -0,0 +1,78 @@
+# KFD-2 Release Trust Metadata
+
+KFD-2 says that trust must start from inspectable facts and responsibility
+state. For releases, that means a product must not ask users or agents to trust
+release claims only because they appear in prose, changelogs, or repository
+history.
+
+This package defines two KFD-owned machine interfaces:
+
+- `schemas/kfd-2/trust-taxonomy.schema.json`: the KFD-owned taxonomy for
+  residual-risk types, trust impact, machine provability, agent actions, and
+  downgrade reasons.
+- `schemas/kfd-2/release-claims.schema.json`: the product's declared public
+  release claims.
+- `schemas/kfd-2/release-trust-passport.schema.json`: the verifier's result
+  after auditing those claims against evidence.
+
+The intended Buildchain flow is:
+
+```text
+release claims -> evidence audit -> release trust passport -> release passport
+```
+
+Each claim should declare the statement being made, the source of the claim,
+machine-readable evidence, the audit boundary, residual risk, and responsibility
+state. The trust passport should then record whether each claim is bound to
+evidence, which evidence was checked, what the result was, and who owns the
+release decision.
+
+## Trust Taxonomy
+
+KFD-2 owns the vocabulary for residual risks and trust downgrades. A product,
+release tool, or agent must not invent new residual-risk values locally and
+still claim KFD-2 conformance. Unknown values fail schema validation.
+
+The current taxonomy is published in
+`schemas/kfd-2/trust-taxonomy.schema.json`. It defines:
+
+- `riskType`: what kind of trust gap remains;
+- `trustImpact`: whether the gap is informational, downgraded, failing, or
+  unverifiable;
+- `machineProvability`: whether the gap can be fully proved by machine;
+- `agentAction`: what an agent should do next;
+- `downgradeReason`: how a verifier maps residual risk into a release trust
+  result.
+
+If an agent needs a KFD-2 value that is not present, the standard extension
+path is to open an issue in the KFD repository:
+
+```text
+https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request
+```
+
+The issue should state the missing value, the field it belongs to, the product
+or release scenario that needs it, and why existing values cannot express the
+case. Until KFD accepts the new value into the taxonomy schema, consumers
+should treat the value as invalid rather than as a soft warning.
+
+## Interface Versioning
+
+KFD package semver is only the distribution version. It is not the version of a
+KFD-owned machine interface.
+
+Every KFD-owned machine interface uses:
+
+- `schemaVersion`: the interface version consumed by tools.
+- `contract`: the stable contract name, such as `kfd-2-release-claims`.
+- `$id`: the canonical schema URL for the current stable interface.
+
+Compatible additions may keep `schemaVersion: 1`. A change that alters required
+fields, field semantics, verification meaning, audit boundary semantics, or
+responsibility semantics must not silently reuse the same interface contract.
+It must introduce a new interface version or, when the standard itself changes,
+a new KFD decision or amendment path.
+
+The same rule applies to KFD-1 and KFD-3 schemas. Their current schemas already
+carry `schemaVersion: 1` and a `contract` value; this document makes the
+evolution rule explicit across the KFD package.