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

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,15 @@
 | 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) |
@@ -17,5 +22,6 @@
 | 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 |
 | What release impact ledger should Buildchain consume for production passports? | [`../release-impact.json`](../release-impact.json) |
+| What release provenance path must alpha promotion use? | [`release-governance.md`](release-governance.md) |
 | How do I verify registry/document agreement? | `node scripts/check.mjs` |
 | How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) |

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

@@ -7,6 +7,9 @@ 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
@@ -24,6 +27,35 @@ 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

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

@@ -26,6 +26,8 @@ A product collaboration interface should identify:
 
 - participant profiles, such as `human`, `agent`, `operator`,
   `extension-author`, or `api-consumer`;
+- public fact sources that identify where load-bearing facts live and which
+  surfaces are only projections;
 - minimal entrypoints that let each participant discover the rest of the
   interface;
 - participant-visible surfaces, such as CLI commands, JSON APIs, manuals,
@@ -33,6 +35,8 @@ A product collaboration interface should identify:
 - visible constraints, including what is restricted, why, and where review or
   escalation happens;
 - choice paths that let participants choose or decline safe cooperation modes;
+- extension requests that tell participants how to ask for a new value,
+  capability, or interface when the declared interface is insufficient;
 - a closure policy for reachable participant-facing entrypoints.
 
 The KFD-3 witness schema is intentionally stricter about closure: a passing
@@ -57,3 +61,17 @@ Examples:
   requested.
 
 This keeps KFD-3 general while making real product interfaces testable.
+
+## Extension Requests
+
+KFD-3 treats extension requests as part of the collaboration interface. A
+human or agent should not have to infer how to cooperate when a declared
+interface is missing a value or capability. The interface should expose a
+visible request path, the participants it is for, the trigger, and the expected
+outcome.
+
+For KFD itself, the standard request path for missing KFD-2 trust-taxonomy
+values is a GitHub issue in `kungfu-systems/kfd`. This is both a KFD-2 trust
+rule and a KFD-3 collaboration rule: the taxonomy defines what values are valid,
+while the collaboration interface tells agents how to request an extension
+without inventing private values or relying on pressure.

package/docs/release-governance.md

@@ -0,0 +1,28 @@
+# Release Governance Notes
+
+KFD releases are governed by Buildchain channel promotion. The package version
+line stays fixed at `v1.0`; alpha and production releases move through
+protected channel branches.
+
+For alpha promotion, Buildchain treats the provenance path as part of the
+release contract:
+
+```text
+dev/v1/v1.0 -> alpha/v1/v1.0
+```
+
+The alpha branch must be updated by a merged same-repository pull request whose
+head is `dev/v1/v1.0` and whose base is `alpha/v1/v1.0`. A temporary promotion
+branch may satisfy GitHub freshness rules, but it is not a valid Buildchain
+release source for KFD alpha publishing.
+
+The protected branch required status check must also name the status emitted by
+the current Verify workflow. As of the alpha.14 line, that required check is:
+
+```text
+check / check
+```
+
+Keeping the branch protection rule and the workflow-emitted status name aligned
+is part of KFD-1's "facts must not drift" requirement: the release gate cannot
+depend on a stale status context that no current workflow can produce.

package/kfd.release.json

@@ -4,7 +4,7 @@
   "line": "v1.0",
   "channel": "alpha",
   "npmPackage": "@kungfu-tech/kfd",
-  "npmVersion": "1.0.0-alpha.12",
+  "npmVersion": "1.0.0-alpha.14",
   "source": {
     "repository": "kungfu-systems/kfd",
     "branch": "alpha/v1/v1.0"

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
   "files": [
     "README.md",
+    "TRADEMARKS.md",
     "decisions",
     "registry.json",
     "standards.json",
@@ -21,6 +22,7 @@
   "exports": {
     "./package.json": "./package.json",
     "./README.md": "./README.md",
+    "./TRADEMARKS.md": "./TRADEMARKS.md",
     "./registry.json": "./registry.json",
     "./standards.json": "./standards.json",
     "./kfd.release.json": "./kfd.release.json",

package/registry.json

@@ -6,7 +6,7 @@
       "number": 1,
       "id": "KFD-1",
       "slug": "kfd-1",
-      "title": "Contracts must not drift: contract worlds need one fact source",
+      "title": "Facts must not drift: contract worlds need one fact source",
       "kind": "procedure",
       "status": "active",
       "path": "decisions/kfd-1.md",

package/release-impact.json

@@ -9,14 +9,14 @@
   "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."
+    "rationale": "This change additively registers KFD-owned standards metadata, the KFD-2 trust taxonomy, 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."
+      "rationale": "KFD documents are append-only content coordinates; current documentation changes clarify the KFD public fact-source, license, trademark, official-status, and derivative-authority boundaries without altering the decision numbers or registry shape."
     },
     {
       "id": "kfd-registry-schema",
@@ -28,13 +28,13 @@
       "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."
+      "rationale": "standards.json and schemas/ add the KFD-2 trust-taxonomy schema ID, release-claims and release-trust-passport schema IDs, explicit KFD-1/2/3 interface versions, KFD document SHA-256 bindings, KFD-owned concept names, KFD-3 fact-source interface metadata, and official-status interface metadata 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."
+      "rationale": "The npm package now publishes the KFD-2 trust taxonomy, KFD-2 schemas, KFD-2 documentation, KFD-3 self collaboration-interface witnesses, TRADEMARKS.md, public fact-source metadata, and agent quickstart/self-proof documentation through existing schemas/, docs/, standards.json, site/, .buildchain/, and subpath exports while preserving existing README.md, decisions/, registry.json, and site/ paths."
     },
     {
       "id": "kfd-3-self-collaboration",
@@ -61,5 +61,5 @@
       "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."
+  "summary": "KFD v1.0 production promotion is minor-impact because it additively exposes KFD-2 trust taxonomy and 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-2/release-claims.schema.json

@@ -140,8 +140,7 @@
         "residualRisk": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "$ref": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk"
           }
         },
         "responsibility": {

package/schemas/kfd-2/release-trust-passport.schema.json

@@ -74,8 +74,7 @@
     "downgradeReasons": {
       "type": "array",
       "items": {
-        "type": "string",
-        "minLength": 1
+        "$ref": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/downgradeReason"
       }
     },
     "responsibility": {
@@ -171,8 +170,7 @@
         "residualRisk": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "$ref": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk"
           }
         }
       },

package/schemas/kfd-2/trust-taxonomy.schema.json

@@ -0,0 +1,219 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json",
+  "title": "KFD-2 trust taxonomy",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-2-trust-taxonomy"
+    },
+    "standard": {
+      "const": "kfd-2"
+    }
+  },
+  "additionalProperties": true,
+  "x-kfd": {
+    "contract": "kfd-2-trust-taxonomy",
+    "schemaVersion": 1,
+    "allowedValues": {
+      "riskType": [
+        "natural-language-semantic-risk",
+        "external-fact-risk",
+        "partial-machine-coverage-risk",
+        "time-sensitive-state-risk",
+        "manual-review-risk"
+      ],
+      "trustImpact": [
+        "none",
+        "downgrade-warning",
+        "fail",
+        "unverifiable"
+      ],
+      "machineProvability": [
+        "machine-verifiable",
+        "partially-machine-verifiable",
+        "not-machine-verifiable",
+        "not-exhaustively-enumerable"
+      ],
+      "agentAction": [
+        "accept-with-warning",
+        "semantic-review-required",
+        "verify-external-facts",
+        "request-maintainer-review",
+        "open-kfd-extension-issue",
+        "fail-release"
+      ]
+    },
+    "extensionPolicy": {
+      "unknownValuePolicy": "schema-validation-fail",
+      "standardAction": "open-kfd-extension-issue",
+      "requestPath": {
+        "kind": "github-issue",
+        "repository": "https://github.com/kungfu-systems/kfd",
+        "issueUrl": "https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request",
+        "appliesTo": [
+          "riskType",
+          "trustImpact",
+          "machineProvability",
+          "agentAction"
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "riskType": {
+      "enum": [
+        "natural-language-semantic-risk",
+        "external-fact-risk",
+        "partial-machine-coverage-risk",
+        "time-sensitive-state-risk",
+        "manual-review-risk"
+      ]
+    },
+    "trustImpact": {
+      "enum": [
+        "none",
+        "downgrade-warning",
+        "fail",
+        "unverifiable"
+      ]
+    },
+    "machineProvability": {
+      "enum": [
+        "machine-verifiable",
+        "partially-machine-verifiable",
+        "not-machine-verifiable",
+        "not-exhaustively-enumerable"
+      ]
+    },
+    "agentAction": {
+      "enum": [
+        "accept-with-warning",
+        "semantic-review-required",
+        "verify-external-facts",
+        "request-maintainer-review",
+        "open-kfd-extension-issue",
+        "fail-release"
+      ]
+    },
+    "extensionRequest": {
+      "type": "object",
+      "required": [
+        "kind",
+        "repository",
+        "issueUrl"
+      ],
+      "properties": {
+        "kind": {
+          "const": "github-issue"
+        },
+        "repository": {
+          "const": "https://github.com/kungfu-systems/kfd"
+        },
+        "issueUrl": {
+          "type": "string",
+          "format": "uri"
+        },
+        "appliesTo": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "riskType",
+              "trustImpact",
+              "machineProvability",
+              "agentAction"
+            ]
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "residualRisk": {
+      "type": "object",
+      "required": [
+        "id",
+        "definedBy",
+        "riskType",
+        "trustImpact",
+        "machineProvability",
+        "agentAction",
+        "reason",
+        "owner"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "definedBy": {
+          "const": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk"
+        },
+        "riskType": {
+          "$ref": "#/$defs/riskType"
+        },
+        "trustImpact": {
+          "$ref": "#/$defs/trustImpact"
+        },
+        "machineProvability": {
+          "$ref": "#/$defs/machineProvability"
+        },
+        "agentAction": {
+          "$ref": "#/$defs/agentAction"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "extensionRequest": {
+          "$ref": "#/$defs/extensionRequest"
+        }
+      },
+      "additionalProperties": false
+    },
+    "downgradeReason": {
+      "type": "object",
+      "required": [
+        "id",
+        "riskType",
+        "trustImpact",
+        "reason"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "riskType": {
+          "$ref": "#/$defs/riskType"
+        },
+        "trustImpact": {
+          "$ref": "#/$defs/trustImpact"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agentAction": {
+          "$ref": "#/$defs/agentAction"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}