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

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

@@ -0,0 +1,77 @@
+# 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`;
+- 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,
+  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;
+- 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
+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.
+
+## 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/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.13",
+  "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,17 +1,49 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.13",
   "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",
+    "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",
+    "./TRADEMARKS.md": "./TRADEMARKS.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"
+    "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/",

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

@@ -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, 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 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",
+      "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 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 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",
+      "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 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-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
+}

package/schemas/kfd-2/release-claims.schema.json

@@ -0,0 +1,331 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-2/release-claims.schema.json",
+  "title": "KFD-2 release claims",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "product",
+    "release",
+    "claims"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-2-release-claims"
+    },
+    "standard": {
+      "const": "kfd-2"
+    },
+    "product": {
+      "$ref": "#/$defs/product"
+    },
+    "release": {
+      "$ref": "#/$defs/release"
+    },
+    "claims": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/claim"
+      }
+    },
+    "schemaEvolution": {
+      "$ref": "#/$defs/schemaEvolution"
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "product": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "version",
+        "channel"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "channel": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceSha": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "claim": {
+      "type": "object",
+      "required": [
+        "id",
+        "statement",
+        "source",
+        "evidence",
+        "auditBoundary",
+        "responsibility",
+        "status"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "category": {
+          "enum": [
+            "metadata",
+            "schema",
+            "package-export",
+            "artifact",
+            "site",
+            "release",
+            "kfd-1",
+            "kfd-2",
+            "kfd-3",
+            "other"
+          ]
+        },
+        "source": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/evidenceBinding"
+          }
+        },
+        "verification": {
+          "$ref": "#/$defs/verification"
+        },
+        "auditBoundary": {
+          "$ref": "#/$defs/auditBoundary"
+        },
+        "residualRisk": {
+          "type": "array",
+          "items": {
+            "$ref": "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk"
+          }
+        },
+        "responsibility": {
+          "$ref": "#/$defs/responsibilityState"
+        },
+        "status": {
+          "enum": [
+            "declared",
+            "audited",
+            "enforced",
+            "not-applicable"
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "artifactPointer": {
+      "type": "object",
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "file",
+            "schema",
+            "package-export",
+            "artifact",
+            "command",
+            "witness",
+            "passport",
+            "url",
+            "other"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "specifier": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "schemaId": {
+          "type": "string",
+          "format": "uri"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "digest": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "evidenceBinding": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "file",
+            "schema",
+            "package-export",
+            "artifact",
+            "hash",
+            "command-result",
+            "witness",
+            "passport-section",
+            "url",
+            "other"
+          ]
+        },
+        "pointer": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "verification": {
+      "type": "object",
+      "properties": {
+        "resultRef": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expectedResult": {
+          "enum": [
+            "pass",
+            "fail",
+            "warning",
+            "unverifiable"
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "auditBoundary": {
+      "type": "object",
+      "required": [
+        "scope",
+        "enumerability"
+      ],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "minLength": 1
+        },
+        "enumerability": {
+          "enum": [
+            "closed-world",
+            "declared-open",
+            "sampled",
+            "manual"
+          ]
+        },
+        "exclusions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "responsibilityState": {
+      "type": "object",
+      "required": [
+        "sourceOwner",
+        "verificationOwner",
+        "releaseDecisionOwner"
+      ],
+      "properties": {
+        "sourceOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "verificationOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "releaseDecisionOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "escalation": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "schemaEvolution": {
+      "type": "object",
+      "required": [
+        "interfaceVersion",
+        "compatibilityRule"
+      ],
+      "properties": {
+        "interfaceVersion": {
+          "const": 1
+        },
+        "compatibilityRule": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}