@kungfu-tech/kfd 1.0.0-alpha.0 → 1.0.0-alpha.12

package/README.md

@@ -113,6 +113,36 @@ 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" };
+```
+
+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 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 |
@@ -137,16 +167,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.
+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
 
@@ -160,7 +199,9 @@ release-passport-impact-json: release-impact.json
 For ordinary KFD content changes, keep `kfd-content` at `patch`. Move
 `kfd-registry-schema` or `kfd-package-structure` to `minor` or `major` only
 when those machine-consumed surfaces add or break fields, meanings, package
-paths, or published structure under KFD-1.
+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
 

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

@@ -157,10 +157,12 @@ and does not drift invisibly.
 KFD documents are append-only. A KFD's number is immutable and is the
 content-layer coordinate; substantive semantic change is made by minting a new
 KFD that supersedes the old number (namespace welding applied to decisions).
-Consequently, in the `@kungfu-tech/kfd` package, content operations — new
-KFDs, status flips, editorial clarifications — are patches; only the machine
-surfaces of the package itself (the registry schema, the package structure)
-can move minor or major.
+Consequently, in the `@kungfu-tech/kfd` package, the outer package line stays
+fixed at `v1.0`. Content operations — new KFDs, status flips, editorial
+clarifications — are patches. Machine surfaces of the package itself (the
+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.
 
 ## Adopters
 

package/docs/MAP.md

@@ -8,7 +8,11 @@
 | 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 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,46 @@
+# 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/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.
+
+## 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.

package/docs/kfd-3-collaboration-interface.md

@@ -0,0 +1,59 @@
+# KFD-3 Collaboration Interface
+
+KFD-3 is a cooperation standard for intelligent participants. It is not an
+agent-only standard. Products can use it for humans, agents, operators,
+extension authors, API consumers, hosted-service users, service integrators,
+maintainers, and other participants who need to understand value, choices, and
+constraints before cooperating.
+
+The KFD-owned schema surface is intentionally general:
+
+- `schemas/kfd-3/collaboration-interface.schema.json` declares a product's
+  participant-facing collaboration interface.
+- `schemas/kfd-3/witness.schema.json` declares release or build evidence that
+  the interface is discoverable, classified, constraint-transparent, and closed
+  over reachable participant-facing entrypoints.
+
+KFD owns the standard identity, schema IDs, concept names, and compatibility
+rules. Product repositories own their concrete profiles. For example, Kungfu
+may expose an agent-first profile because agents are a first-class participant
+in the current product, but that profile remains a Kungfu implementation of
+KFD-3 rather than the definition of KFD-3 itself.
+
+## Required shape
+
+A product collaboration interface should identify:
+
+- participant profiles, such as `human`, `agent`, `operator`,
+  `extension-author`, or `api-consumer`;
+- minimal entrypoints that let each participant discover the rest of the
+  interface;
+- participant-visible surfaces, such as CLI commands, JSON APIs, manuals,
+  skills, GUI routes, envelopes, packages, or protocols;
+- visible constraints, including what is restricted, why, and where review or
+  escalation happens;
+- choice paths that let participants choose or decline safe cooperation modes;
+- a closure policy for reachable participant-facing entrypoints.
+
+The KFD-3 witness schema is intentionally stricter about closure: a passing
+closed-world proof reports reachable entrypoints, classified entrypoints, and
+an empty `unclassifiedEntrypoints` list. This prevents a product from exposing
+a participant-facing or callable backdoor API outside the declared interface.
+
+## Product profile boundary
+
+Concrete product profiles may add their own contracts, registry fields, command
+metadata, generated manuals, or audit output. Those fields should reference the
+KFD-3 schema IDs from `standards.json` instead of copying KFD-owned terms.
+
+Examples:
+
+- A Kungfu agent-first bridge can map local commands, provider skills, command
+  metadata, and operating manuals into a KFD-3 collaboration interface.
+- A Buildchain release passport can carry a KFD-3 witness once a downstream
+  product can freeze and verify the concrete interface artifact.
+- A hosted surface can use the same standard to show where policy constraints,
+  permission gates, and user choices are visible before cooperation is
+  requested.
+
+This keeps KFD-3 general while making real product interfaces testable.

package/kfd.release.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-release-anchor",
+  "line": "v1.0",
+  "channel": "alpha",
+  "npmPackage": "@kungfu-tech/kfd",
+  "npmVersion": "1.0.0-alpha.12",
+  "source": {
+    "repository": "kungfu-systems/kfd",
+    "branch": "alpha/v1/v1.0"
+  },
+  "rationale": "KFD uses an anchored/manual Buildchain mode: the public package version is an explicit release fact, while the outer KFD line remains v1.0."
+}

package/package.json

@@ -1,10 +1,54 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.12",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
-  "files": ["README.md", "decisions", "registry.json", "site", "docs"],
-  "scripts": {"check": "node scripts/check.mjs"},
-  "publishConfig": {"registry": "https://registry.npmjs.org/", "access": "public"},
-  "repository": {"type": "git", "url": "git+https://github.com/kungfu-systems/kfd.git"}
+  "files": [
+    "README.md",
+    "decisions",
+    "registry.json",
+    "standards.json",
+    "kfd.release.json",
+    "schemas",
+    "site",
+    "buildchain.release-propagation.json",
+    "release-impact.json",
+    ".buildchain/kfd-1/contract-world.witness.json",
+    ".buildchain/kfd-2",
+    ".buildchain/kfd-3",
+    "docs"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./README.md": "./README.md",
+    "./registry.json": "./registry.json",
+    "./standards.json": "./standards.json",
+    "./kfd.release.json": "./kfd.release.json",
+    "./site/kfd-site.json": "./site/kfd-site.json",
+    "./buildchain.release-propagation.json": "./buildchain.release-propagation.json",
+    "./release-impact.json": "./release-impact.json",
+    "./buildchain/kfd-1/contract-world.witness.json": "./.buildchain/kfd-1/contract-world.witness.json",
+    "./buildchain/kfd-2/public-release-trust.claim.json": "./.buildchain/kfd-2/public-release-trust.claim.json",
+    "./buildchain/kfd-3/collaboration-interface.json": "./.buildchain/kfd-3/collaboration-interface.json",
+    "./buildchain/kfd-3/collaboration-interface.prebuild.json": "./.buildchain/kfd-3/collaboration-interface.prebuild.json",
+    "./buildchain/kfd-3/collaboration-interface.artifact.json": "./.buildchain/kfd-3/collaboration-interface.artifact.json",
+    "./schemas/*.json": "./schemas/*.json",
+    "./schemas/*/*.json": "./schemas/*/*.json",
+    "./decisions/*.md": "./decisions/*.md",
+    "./docs/*": "./docs/*"
+  },
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "update:kfd-1-witness": "node scripts/update-kfd-1-witness.mjs",
+    "update:kfd-2-claim": "node scripts/update-kfd-2-claim.mjs",
+    "update:kfd-3-witness": "node scripts/update-kfd-3-witness.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kungfu-systems/kfd.git"
+  }
 }

package/release-impact.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-impact",
+  "release": {
+    "line": "v1.0",
+    "channel": "release",
+    "targetRef": "release/v1/v1.0"
+  },
+  "versionImpact": {
+    "final": "minor",
+    "source": "kfd-surface-register",
+    "rationale": "This change additively registers KFD-owned standards metadata, KFD-2 release trust schemas, KFD-3 collaboration-interface schemas, KFD-3 self-verification witnesses, and KFD-1 document/interface integrity bindings while keeping existing registry and decision surfaces compatible."
+  },
+  "surfaceImpacts": [
+    {
+      "id": "kfd-content",
+      "impact": "patch",
+      "class": "content",
+      "rationale": "KFD documents are append-only content coordinates; current decision text changes do not alter a machine-consumed surface."
+    },
+    {
+      "id": "kfd-registry-schema",
+      "impact": "patch",
+      "class": "compatible",
+      "rationale": "registry.json keeps schemaVersion 1 and the existing entry shape, including number, id, slug, title, kind, status, path, and url; slug and path values are stable number coordinates."
+    },
+    {
+      "id": "kfd-standards-metadata",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "standards.json and schemas/ add KFD-2 release-claims and release-trust-passport schema IDs, explicit KFD-1/2/3 interface versions, KFD document SHA-256 bindings, and KFD-owned concept names for downstream consumers."
+    },
+    {
+      "id": "kfd-package-structure",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "The npm package now also publishes KFD-2 schemas, KFD-2 documentation, and KFD-3 self collaboration-interface witnesses through existing schemas/, docs/, standards.json, .buildchain/, and subpath exports while preserving existing README.md, decisions/, registry.json, and site/ paths."
+    },
+    {
+      "id": "kfd-3-self-collaboration",
+      "impact": "minor",
+      "class": "release-passport",
+      "rationale": "KFD now declares its own participant-facing collaboration interface and ships pre-build plus artifact-side KFD-3 witnesses so Buildchain can audit interface closure in the release passport."
+    },
+    {
+      "id": "kfd-2-public-release-trust-claim",
+      "impact": "minor",
+      "class": "release-passport",
+      "rationale": "KFD now ships an explicit machine-bound public KFD-2 release trust claim and passes it into Buildchain release passport generation."
+    },
+    {
+      "id": "kfd-release-anchor",
+      "impact": "minor",
+      "class": "release-governance",
+      "rationale": "KFD now declares its package version through an anchored/manual release manifest so package version state is an explicit release fact rather than an auto-derived Buildchain side effect."
+    },
+    {
+      "id": "kfd-release-propagation",
+      "impact": "patch",
+      "class": "compatible",
+      "rationale": "The KFD to site-libkungfu-dev propagation graph now targets the downstream site's actual main branch and documents the exact KFD package surfaces consumed by kfd.libkungfu.dev, without changing the release propagation graph contract."
+    }
+  ],
+  "summary": "KFD v1.0 production promotion is minor-impact because it additively exposes KFD-2 release trust metadata, KFD-1/2/3 interface version metadata, KFD-3 self-verification witnesses, document integrity bindings, and a corrected site release-propagation target for Buildchain and other consumers; existing registry, decision text, site bundle, and propagation graph contracts remain compatible."
+}

package/schemas/kfd-1/contract-world.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json",
+  "title": "KFD-1 contract world",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "factSource",
+    "surfaces"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-1-contract-world"
+    },
+    "standard": {
+      "const": "kfd-1"
+    },
+    "factSource": {
+      "type": "string",
+      "minLength": 1
+    },
+    "surfaces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "class",
+          "description"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "class": {
+            "enum": [
+              "integration-time",
+              "cross-time"
+            ]
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/kfd-1/witness.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json",
+  "title": "KFD-1 witness",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "contractWorld",
+    "evidence"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-1-witness"
+    },
+    "standard": {
+      "const": "kfd-1"
+    },
+    "contractWorld": {
+      "type": "object",
+      "required": [
+        "schemaId",
+        "digest"
+      ],
+      "properties": {
+        "schemaId": {
+          "const": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json"
+        },
+        "digest": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "path"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "minLength": 1
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}