@kungfu-tech/kfd 1.0.0-alpha.2 → 1.0.0-alpha.21

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 trusted 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 trusted 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. |
+| Participant-to-participant cooperation | KFD-3 | How should peer intelligent participants cooperate? | Cooperation starts from trusted value: value becomes trustable through transparent facts, stable choice, and explainable constraints. |
 
 In short:
 
 ```text
-stable facts -> trustworthy objects -> non-coercive cooperation
+non-drifting facts -> inspectable trust -> trusted value -> voluntary 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,
@@ -72,7 +73,37 @@ systems. KFD is part of that bootstrap: the worldview is forged through the same
 transparent and inspectable mechanisms it asks products to provide.
 
 This README states the architecture; KFD-1, KFD-2, and KFD-3 provide the
-detailed rules.
+foundation rules.
+
+## Practice guidelines
+
+KFDs after the foundation triad may define practice guidelines: procedures
+that apply the foundation to a specific class of real-world product behavior.
+They do not expand the foundation triad; they show how the foundation behaves
+when a product must make a concrete kind of reality legible.
+
+| Layer | Decision | Reader question | Commitment |
+|---|---|---|---|
+| Perspective-bearing views | KFD-4 | How should a product show time, history, replay, sync, or mixed-source work state? | Timelines must declare their observer: a useful view states who is observing, which facts were accepted, and how concurrent facts were projected. |
+
+KFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of
+perspective and timeline order. In a multi-machine or multi-agent world, a
+product should not pretend to own a universal global clock. It should preserve
+non-drifting facts, make trust start from those facts, and let participants
+cooperate by exposing the observer, accepted ranges, causal constraints, and
+projection policy behind the view. KFD-4 gates perspective-bearing views; it
+does not claim that importing the KFD-4 schema proves an adopter's concrete
+timeline implementation is complete or correct.
+
+## Adoption boundary
+
+KFD is an engineering discipline, not a belief test.
+KFD governs systems before it judges people.
+No one should be pressured to adopt KFD in the name of KFD.
+Disagreement is a valid cooperation state.
+
+A constraint can be strict and still KFD-compatible when it is fact-bound,
+explainable, auditable, and proportionate.
 
 ## Homepage content contract
 
@@ -89,7 +120,10 @@ 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 -> trusted value -> voluntary
+  cooperation` chain.
+- Practice signal: the `Practice guidelines` section, starting with KFD-4 as
+  the declared-observer rule for perspective-bearing timeline views.
 
 Decision cards, detail links, and machine paths should come from
 `registry.json`. The machine-readable site bundle lives at `site/kfd-site.json`
@@ -98,14 +132,26 @@ proof path, decision routes, and rendering boundary. A site renderer may adapt
 layout, navigation, typography, and visual assets, but it should not maintain
 separate homepage wording that can drift from this package.
 
+`site/kfd-site.json` is generated from this README by
+`scripts/update-site-bundle.mjs`. The generated bundle exposes both compatible
+top-level homepage fields and ordered `homepage.sections` entries. The
+`homepage.displayPlan` tells renderers which sections belong in the first
+screen, primary narrative, and support area. Site repositories should consume
+that bundle instead of parsing this README themselves. The renderer contract is
+exposed as machine/implementation metadata, not as ordinary homepage content.
+
 ## Product proof path
 
 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, KFD-3,
+and KFD-4 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,
@@ -115,20 +161,91 @@ e.g. `https://kfd.libkungfu.dev/1`). This repository publishes
 
 Machine consumers that need KFD-owned standard identity should read
 `standards.json`. It is the versioned metadata surface for stable standard
-keys, document routes, schema IDs, and KFD-owned concept names. In Node or
-TypeScript projects, import it as:
+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-2/trust-claims.schema.json` and
+   `schemas/kfd-2/trust-assessment.schema.json` when a claim needs generic
+   KFD-2 assessment instead of a release-specific passport.
+6. Use `schemas/kfd-3/collaboration-interface.schema.json` and
+   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.
+7. 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, trust-claims, trust-assessment,
+release-claims, and release-trust-passport schemas under `schemas/kfd-2/`.
+The generic schemas let humans, agents, Buildchain, and other systems assess
+whether claims about KFD-1, KFD-3, KFD-4, future KFDs, or product surfaces are
+bound to source facts, evidence, hashes, audit boundaries, residual risk, and
+responsibility state. The release schemas are a release-specific projection of
+that model. See [`docs/KFD-2-usage.md`](docs/KFD-2-usage.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-usage.md`](docs/KFD-3-usage.md).
+
+KFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives
+humans and agents a standard vocabulary for observer, accepted facts,
+projection policy, causal constraints, degraded evidence, and verification
+state when a product shows a perspective-bearing timeline. The package-level
+claim proves the KFD-owned interface surface; adopter runtime correctness
+requires adopter-owned KFD-2 evidence.
+
 ## 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 trusted value. | active |
+| [KFD-4](decisions/KFD-4.md) | procedure | Timelines must declare their observer. | 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
 
@@ -150,6 +267,8 @@ 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
@@ -157,7 +276,8 @@ scripts/       conformance check: registry and documents must agree
 
 `node scripts/check.mjs` (also `pnpm run check`) verifies numbering
 uniqueness, registry/document agreement, standards metadata/schema agreement,
-status validity, and the release impact ledger required by Buildchain
+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
@@ -179,6 +299,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.contract-lock.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-contract-lock",
+  "buildchain": {
+    "ref": "v2",
+    "resolvedSha": "7073acd84765df11260f825abdcfdd7e57379fd8",
+    "contract": "kungfu-buildchain-runtime-contract-world",
+    "contractDigest": "sha256:657034ebc39315b3450cd4c4356af2529b6a2ad03d0df680ec6010f3396df52d",
+    "compatibilityDigest": "sha256:967df7e854fdf582294ddfb6403eff25c00db9518a24051e7d47cbd75527c785",
+    "majorLine": "v2",
+    "compatibilityPolicy": "major-compatible",
+    "acceptedAt": "2026-07-08T13:48:44.565Z",
+    "surfaces": [
+      {
+        "id": "reusable-build",
+        "kind": "workflow",
+        "breakingDigest": "sha256:6303aa2c2cb8c2cef4301ceea95cc3c426c2aa81d98714aa9bdf2471d63faee1"
+      },
+      {
+        "id": "release-candidate-promote",
+        "kind": "workflow",
+        "breakingDigest": "sha256:403d2fcdb0c5eabe749e89102defad69745f70a1556707bec7831fcc2e9fa8f8"
+      },
+      {
+        "id": "web-surface",
+        "kind": "workflow",
+        "breakingDigest": "sha256:82ee63cb336e40d832dfff4a1c5e6cbfa221a4fc8b2359990033bc931bffc43a"
+      },
+      {
+        "id": "promote-buildchain-ref-action",
+        "kind": "action",
+        "breakingDigest": "sha256:0c5896590c8c9a44dfecbe060bcef1b43d3a9556737309dbe7e5f2bf83bfee6c"
+      },
+      {
+        "id": "report-buildchain-issue-action",
+        "kind": "action",
+        "breakingDigest": "sha256:575a2cb02cdb2e61bb2e84d5bbaaf64b430aa5d7936645660b592de4549d81b0"
+      },
+      {
+        "id": "release-passport-schema",
+        "kind": "schema",
+        "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad"
+      },
+      {
+        "id": "kfd-1-release-gate",
+        "kind": "schema",
+        "breakingDigest": "sha256:f46c1f67b94957ad956cf70db59a73fd5690bd67c91edf9c2d0eb8f3d1e3cf8d"
+      },
+      {
+        "id": "kfd-2-release-trust-passport-audit",
+        "kind": "schema",
+        "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16"
+      },
+      {
+        "id": "kfd-3-collaboration-interface-release-gate",
+        "kind": "schema",
+        "breakingDigest": "sha256:33654f3444c893754aacc42dde3051f0a371bd17c6ef7c657c579a07159cd7c1"
+      },
+      {
+        "id": "buildchain-cli",
+        "kind": "cli",
+        "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc"
+      },
+      {
+        "id": "homebrew-distribution-index",
+        "kind": "node-api",
+        "breakingDigest": "sha256:148c0387ff4cea76433bbde80cd9d77c5aa67e1a29856ced33e4d819366f2213"
+      },
+      {
+        "id": "readme-badge-facts",
+        "kind": "node-api",
+        "breakingDigest": "sha256:bcd72ad6dfba8013c96f8b2f7b0a307d2e7713972a1219348f0d5ecc493939a0"
+      },
+      {
+        "id": "agent-manual-registry",
+        "kind": "site-contract",
+        "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2"
+      },
+      {
+        "id": "node-api-registry",
+        "kind": "site-contract",
+        "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945"
+      }
+    ]
+  }
+}

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 → 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
 
@@ -41,8 +44,10 @@ when either holds:
 - **(b) Cross-time dependency** — its outputs remain depended on after the run
   (persisted data, audit evidence, replayable records).
 
-Each entry carries a stable kebab-case ID. Registers live in each repository's
-versioning document and are the input to every classification below.
+Each entry carries a stable kebab-case ID. A surface may be
+`integration-time`, `cross-time`, or both. Registers live in each repository's
+contract-world metadata or versioning document and are the input to every
+classification below.
 
 ## Concrete case: config contracts
 
@@ -58,21 +63,44 @@ steps, and the final product must consume the same contract mechanism. It is
 not enough for the packaged artifact to be internally consistent if the
 developer path used a different, driftable config source.
 
-## The decision procedure
+## The compatibility impact core
 
-Classify the actual diff against the register; the highest match wins:
+Classify the actual diff against the register; the strongest match wins:
 
 | # | Condition | Verdict |
 |---|---|---|
-| 1 | **Breaks** any registered surface (removal, semantic change, layout change, incompatible rename — a semantic change counts as breakage even when shapes are unchanged: changed defaults, changed channel meaning, a newly required field) | **major** |
-| 2 | **Additively evolves** a registered surface, or **adds** a surface consumers will weld to | **minor** (register the new surface at the same time) |
-| 3 | Touches no registered surface | **patch** — regardless of how large the feature is |
-| 4 | **Cannot be classified** | **Do not guess.** The register is deficient: fix the register first (a maintainer decision), then reclassify |
+| 1 | **Breaks** any registered surface (removal, semantic change, layout change, incompatible rename — a semantic change counts as breakage even when shapes are unchanged: changed defaults, changed channel meaning, a newly required field) | **breaking impact** |
+| 2 | **Additively evolves** a registered surface, or **adds** a surface consumers will weld to | **additive impact** (register the new surface at the same time) |
+| 3 | Touches no registered surface | **no registered-surface impact** — regardless of how large the implementation change is |
+| 4 | **Cannot be classified** | **unclassifiable impact. Do not guess.** The register is deficient: fix the register first (a maintainer decision), then reclassify |
 
 Rule 4 is the safety valve: it forces the irreducible judgment (what counts as
 a welded surface) to a maintainer instead of letting a change silently pick
 the convenient answer.
 
+These four impact classes are the KFD-1 core. They are not inherently release
+version numbers. A product must project them into the control action that
+matches its domain: version line movement, config migration, ABI epoch, API
+namespace, release gate, runtime compatibility bridge, or user workflow gate.
+
+## Release versioning projection
+
+For release versioning, the compatibility impact core projects to semver:
+
+| Compatibility impact | Release verdict |
+|---|---|
+| breaking impact | **major** |
+| additive impact | **minor** |
+| no registered-surface impact | **patch** |
+| unclassifiable impact | **block release; fix the register first** |
+
+This projection is the first implementation case, not the whole principle.
+Other domains must keep the same impact core while choosing their own action:
+config contracts may require a migration bridge or rejected old config, ABIs
+may require a new soname or ABI epoch, APIs may require a namespace or endpoint
+compatibility boundary, and agent/UI surfaces may require explicit workflow or
+command migration.
+
 ## Constraint clauses
 
 - **Reverse prohibition.** A line must not be opened for feature volume,
@@ -84,7 +112,8 @@ the convenient answer.
   self-archivable inputs, and no hard coupling to a maintainer-operated
   service.
 - **Decision time.** The verdict is checked against the final diff before the
-  promotion into the alpha channel; planning-time classification is only a
+  action gate that depends on it; for releases this is checked before
+  promotion into the alpha channel. Planning-time classification is only a
   prediction.
 - **Major dignity.** A major release communicates exactly one thing: something
   you welded to broke and you must re-audit. An empty major — one that breaks
@@ -115,9 +144,11 @@ the convenient answer.
 
 ## The decision log
 
-Line openings (minor/major), register changes, and deprecations must be
-recorded in the repository's versioning document; patches stay silent —
-silence is itself the signal that no registered surface was touched.
+Line openings (minor/major), register changes, deprecations, and other
+compatibility-impact decisions must be recorded in the repository's
+contract-world or versioning document. Release patches stay silent — silence
+is itself the signal that no registered surface was touched in the release
+projection.
 
 One markdown table row per event, newest first:
 
@@ -140,17 +171,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 +194,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