@kungfu-tech/kfd 1.0.0-alpha.18 → 1.0.0-alpha.19

package/scripts/check.mjs

@@ -76,7 +76,7 @@ if (!Array.isArray(siteBundle.homepage?.sections) || siteBundle.homepage.section
 if (!siteBundle.homepage?.displayPlan?.firstScreen?.include?.includes("foundation-triad")) {
   fail("site bundle homepage displayPlan firstScreen must include foundation-triad");
 }
-for (const requiredSection of ["foundation-triad", "foundation-model", "adoption-boundary", "product-proof-path", "agent-quickstart", "decision-metadata"]) {
+for (const requiredSection of ["foundation-triad", "foundation-model", "adoption-boundary", "practice-guidelines", "product-proof-path", "agent-quickstart", "decision-metadata"]) {
   if (!siteBundle.homepage.sections.some((entry) => entry.id === requiredSection && entry.sourcePath === "README.md" && entry.markdown)) {
     fail(`site bundle homepage.sections must include README projection ${requiredSection}`);
   }
@@ -366,18 +366,43 @@ for (const concept of ["participant", "collaborationInterface", "minimalEntrypoi
 for (const iface of ["collaborationInterface", "witness"]) {
   if (!kfd3?.interfaces?.[iface]) fail(`KFD-3 standards metadata missing interface ${iface}`);
 }
+const kfd4 = standardsMetadata.standards?.["kfd-4"];
+if (kfd4?.schemaIds?.observerPerspective !== "https://kfd.libkungfu.dev/schemas/kfd-4/observer-perspective.schema.json") {
+  fail("KFD-4 standards metadata must expose the canonical observerPerspective schema URI");
+}
+if (kfd4?.schemaPaths?.observerPerspective !== "schemas/kfd-4/observer-perspective.schema.json") {
+  fail("KFD-4 standards metadata must expose the observerPerspective schema path");
+}
+const kfd4ObserverPerspectiveSchema = JSON.parse(readFileSync("schemas/kfd-4/observer-perspective.schema.json", "utf8"));
+if (kfd4ObserverPerspectiveSchema.properties?.contract?.const !== "kfd-4-observer-perspective") {
+  fail("KFD-4 observerPerspective schema must describe the kfd-4-observer-perspective contract");
+}
+for (const concept of ["observer", "declaredPerspective", "observerPerspective", "acceptedFacts", "projectionPolicy", "causalDominance", "degradedEvidence", "timeline"]) {
+  if (!kfd4?.concepts?.[concept]) fail(`KFD-4 standards metadata missing concept ${concept}`);
+}
+if (!kfd4?.interfaces?.observerPerspective) fail("KFD-4 standards metadata missing interface observerPerspective");
 for (const [id, successors] of superseded) {
   for (const successor of successors) {
     if (!registry.entries.some((e) => e.id === successor)) fail(`${id} cites missing successor ${successor}`);
   }
 }
 const siteCommitments = new Map((siteBundle.homepage?.foundationTriad?.commitments ?? []).map((item) => [item.id, item]));
-for (const e of registry.entries) {
-  if (!siteCommitments.has(e.id)) fail(`site bundle foundationTriad missing ${e.id}`);
+for (const id of ["KFD-1", "KFD-2", "KFD-3"]) {
+  if (!siteCommitments.has(id)) fail(`site bundle foundationTriad missing ${id}`);
+}
+for (const id of siteCommitments.keys()) {
+  if (!["KFD-1", "KFD-2", "KFD-3"].includes(id)) fail(`site bundle foundationTriad must not include practice guideline ${id}`);
 }
 const siteLayers = new Map((siteBundle.homepage?.foundationModel?.layers ?? []).map((item) => [item.decision, item]));
-for (const e of registry.entries) {
-  if (!siteLayers.has(e.id)) fail(`site bundle foundationModel missing ${e.id}`);
+for (const id of ["KFD-1", "KFD-2", "KFD-3"]) {
+  if (!siteLayers.has(id)) fail(`site bundle foundationModel missing ${id}`);
+}
+for (const id of siteLayers.keys()) {
+  if (!["KFD-1", "KFD-2", "KFD-3"].includes(id)) fail(`site bundle foundationModel must not include practice guideline ${id}`);
+}
+const practiceGuidelines = new Map((siteBundle.homepage?.practiceGuidelines?.guidelines ?? []).map((item) => [item.decision, item]));
+for (const e of registry.entries.filter((entry) => !["KFD-1", "KFD-2", "KFD-3"].includes(entry.id))) {
+  if (!practiceGuidelines.has(e.id)) fail(`site bundle practiceGuidelines missing ${e.id}`);
 }
 const boundary = siteBundle.renderingBoundary ?? {};
 if (!Array.isArray(boundary.ownedByKfd) || !boundary.ownedByKfd.includes("homepage title and text")) {

package/scripts/update-kfd-3-witness.mjs

@@ -41,6 +41,7 @@ const schemaSurfaces = [
   "schemas/kfd-2/release-trust-passport.schema.json",
   "schemas/kfd-3/collaboration-interface.schema.json",
   "schemas/kfd-3/witness.schema.json",
+  "schemas/kfd-4/observer-perspective.schema.json",
 ].map((filePath) => ({
   id: `schema:${filePath.replace(/^schemas\//, "").replace(/\.schema\.json$/, "").replace(/\//g, ":")}`,
   sourcePath: filePath,

package/scripts/update-site-bundle.mjs

@@ -93,6 +93,13 @@ const parseFoundationModel = (markdown) => {
   };
 };
 
+const parsePracticeGuidelines = (markdown) => ({
+  heading: "Practice guidelines",
+  intro: paragraphBlocks(markdown)[0] || "",
+  guidelines: parseMarkdownTable(markdown),
+  explanation: paragraphBlocks(markdown).slice(1),
+});
+
 const parseProductProofPath = (markdown) => ({
   heading: "Product proof path",
   body: paragraphBlocks(markdown)[0] || "",
@@ -115,6 +122,7 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
   const { lead, decisionKinds } = introLead(readme.intro);
   const foundationTriad = parseFoundationTriad(readme.sections["Foundation triad"] || "");
   const foundationModel = parseFoundationModel(readme.sections["Foundation model"] || "");
+  const practiceGuidelines = parsePracticeGuidelines(readme.sections["Practice guidelines"] || "");
   const productProofPath = parseProductProofPath(readme.sections["Product proof path"] || "");
   const entries = registry.entries || [];
 
@@ -148,6 +156,15 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
       priority: 25,
       presentation: "boundary-note",
     }),
+    section({
+      id: "practice-guidelines",
+      sourceHeading: "Practice guidelines",
+      title: "Practice guidelines",
+      markdown: readme.sections["Practice guidelines"],
+      role: "primary",
+      priority: 27,
+      presentation: "practice-table",
+    }),
     section({
       id: "product-proof-path",
       sourceHeading: "Product proof path",
@@ -198,6 +215,7 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
       decisionKinds,
       foundationTriad,
       foundationModel,
+      practiceGuidelines,
       productProofPath,
       currentDecisions: {
         heading: "Current decisions",
@@ -210,7 +228,7 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
           maxPrimarySections: 2,
           note: "The first viewport should establish KFD identity and the three-decision worldview without showing renderer or developer contract text.",
         },
-        primary: ["foundation-triad", "foundation-model", "adoption-boundary", "product-proof-path"],
+        primary: ["foundation-triad", "foundation-model", "adoption-boundary", "practice-guidelines", "product-proof-path"],
         support: ["agent-quickstart", "decision-metadata"],
         currentDecisions: {
           source: REGISTRY_PATH,

package/site/kfd-site.json

@@ -65,12 +65,28 @@
         "Real-world agent work turns ordinary work into a dense system of products, files, repositories, traces, policies, humans, and agents. In that world, complexity cannot be made safe by hidden state or forced compliance. It has to be compressed through non-drifting facts, inspectable trust, and voluntary cooperation. The goal is not to force increasingly capable participants into compliance through stronger pressure. It is to give humans and agents a shared worldview for adapting to a more complex world.",
         "This also changes what a product interface means. Agent-facing CLI, API, documentation, envelopes, and local fact surfaces are not secondary integration channels after the human GUI. They are first-class interfaces for intelligent participants that may use the system more frequently than humans do. A control plane in this model is a shared work environment for humans and agents, not only a human dashboard over agent activity.",
         "This model used to be expensive to practice. Stable facts require engineering, iteration, and disciplined evidence paths, so older systems often survived by leaning on cheaper substitutes such as authority, habit, reputation, or intuition. Agents change both sides of that equation: they make the world more complex, and they also provide more intelligence for building fact-bearing 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."
+        "This README states the architecture; KFD-1, KFD-2, and KFD-3 provide the foundation rules."
+      ]
+    },
+    "practiceGuidelines": {
+      "heading": "Practice guidelines",
+      "intro": "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.",
+      "guidelines": [
+        {
+          "layer": "Perspective-bearing views",
+          "decision": "KFD-4",
+          "readerQuestion": "How should a product show time, history, replay, sync, or mixed-source work state?",
+          "commitment": "Timelines must declare their observer: a useful view states who is observing, which facts were accepted, and how concurrent facts were projected."
+        }
+      ],
+      "explanation": [
+        "| 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."
       ]
     },
     "productProofPath": {
       "heading": "Product proof path",
-      "body": "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. The first concrete case is this package itself: `standards.json`, `schemas/`, `docs/`, `site/kfd-site.json`, and `scripts/check.mjs` show how KFD-1, KFD-2, and KFD-3 are expressed as consumable interfaces for both humans and agents. For the broader product case, use the main Kungfu product entrypoint (`https://kungfu.tech`) for product philosophy, and Buildchain (`https://buildchain.libkungfu.dev`) for release and provenance accountability. This registry states the commitments; this package and those entrypoints show how the commitments are meant to be borne in practice."
+      "body": "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. 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."
     },
     "currentDecisions": {
       "heading": "Current decisions",
@@ -97,7 +113,7 @@
         "homepagePriority": 20,
         "defaultPresentation": "layered-model",
         "includeInFirstScreen": true,
-        "markdown": "The triad is intentionally ordered. It is a compact model for surviving and\nevolving in complex systems, especially in a world where agents can observe,\nact, delegate, and remember across many surfaces.\n\n| Layer | Decision | Reader question | Commitment |\n|---|---|---|---|\n| 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. |\n| 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. |\n| 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. |\n\nIn short:\n\n```text\nnon-drifting facts -> inspectable trust -> trusted value -> voluntary cooperation\n```\n\nThis is why KFDs are not only internal governance text. KFD-1 gives the\nfoundation model its first layer by making fact sources operational: a\nfact-bearing contract world must be declared, inspectable, and unable to drift\ninvisibly. KFD-2 then defines how trust can stand on those facts. KFD-3\ndefines how humans and agents can cooperate once facts and trust are visible.\n\nReal-world agent work turns ordinary work into a dense system of products,\nfiles, repositories, traces, policies, humans, and agents. In that world,\ncomplexity cannot be made safe by hidden state or forced compliance. It has to\nbe compressed through non-drifting facts, inspectable trust, and voluntary\ncooperation. The goal is not to force increasingly capable participants into\ncompliance through stronger pressure. It is to give humans and agents a shared\nworldview for adapting to a more complex world.\n\nThis also changes what a product interface means. Agent-facing CLI, API,\ndocumentation, envelopes, and local fact surfaces are not secondary integration\nchannels after the human GUI. They are first-class interfaces for intelligent\nparticipants that may use the system more frequently than humans do. A control\nplane in this model is a shared work environment for humans and agents, not\nonly a human dashboard over agent activity.\n\nThis model used to be expensive to practice. Stable facts require engineering,\niteration, and disciplined evidence paths, so older systems often survived by\nleaning on cheaper substitutes such as authority, habit, reputation, or\nintuition. Agents change both sides of that equation: they make the world more\ncomplex, and they also provide more intelligence for building fact-bearing\nsystems. KFD is part of that bootstrap: the worldview is forged through the same\ntransparent and inspectable mechanisms it asks products to provide.\n\nThis README states the architecture; KFD-1, KFD-2, and KFD-3 provide the\ndetailed rules."
+        "markdown": "The triad is intentionally ordered. It is a compact model for surviving and\nevolving in complex systems, especially in a world where agents can observe,\nact, delegate, and remember across many surfaces.\n\n| Layer | Decision | Reader question | Commitment |\n|---|---|---|---|\n| 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. |\n| 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. |\n| 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. |\n\nIn short:\n\n```text\nnon-drifting facts -> inspectable trust -> trusted value -> voluntary cooperation\n```\n\nThis is why KFDs are not only internal governance text. KFD-1 gives the\nfoundation model its first layer by making fact sources operational: a\nfact-bearing contract world must be declared, inspectable, and unable to drift\ninvisibly. KFD-2 then defines how trust can stand on those facts. KFD-3\ndefines how humans and agents can cooperate once facts and trust are visible.\n\nReal-world agent work turns ordinary work into a dense system of products,\nfiles, repositories, traces, policies, humans, and agents. In that world,\ncomplexity cannot be made safe by hidden state or forced compliance. It has to\nbe compressed through non-drifting facts, inspectable trust, and voluntary\ncooperation. The goal is not to force increasingly capable participants into\ncompliance through stronger pressure. It is to give humans and agents a shared\nworldview for adapting to a more complex world.\n\nThis also changes what a product interface means. Agent-facing CLI, API,\ndocumentation, envelopes, and local fact surfaces are not secondary integration\nchannels after the human GUI. They are first-class interfaces for intelligent\nparticipants that may use the system more frequently than humans do. A control\nplane in this model is a shared work environment for humans and agents, not\nonly a human dashboard over agent activity.\n\nThis model used to be expensive to practice. Stable facts require engineering,\niteration, and disciplined evidence paths, so older systems often survived by\nleaning on cheaper substitutes such as authority, habit, reputation, or\nintuition. Agents change both sides of that equation: they make the world more\ncomplex, and they also provide more intelligence for building fact-bearing\nsystems. KFD is part of that bootstrap: the worldview is forged through the same\ntransparent and inspectable mechanisms it asks products to provide.\n\nThis README states the architecture; KFD-1, KFD-2, and KFD-3 provide the\nfoundation rules."
       },
       {
         "id": "adoption-boundary",
@@ -110,6 +126,17 @@
         "includeInFirstScreen": false,
         "markdown": "KFD is an engineering discipline, not a belief test.\nKFD governs systems before it judges people.\nNo one should be pressured to adopt KFD in the name of KFD.\nDisagreement is a valid cooperation state.\n\nA constraint can be strict and still KFD-compatible when it is fact-bound,\nexplainable, auditable, and proportionate."
       },
+      {
+        "id": "practice-guidelines",
+        "sourcePath": "README.md",
+        "sourceHeading": "Practice guidelines",
+        "title": "Practice guidelines",
+        "renderRole": "primary",
+        "homepagePriority": 27,
+        "defaultPresentation": "practice-table",
+        "includeInFirstScreen": false,
+        "markdown": "KFDs after the foundation triad may define practice guidelines: procedures\nthat apply the foundation to a specific class of real-world product behavior.\nThey do not expand the foundation triad; they show how the foundation behaves\nwhen a product must make a concrete kind of reality legible.\n\n| Layer | Decision | Reader question | Commitment |\n|---|---|---|---|\n| 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. |\n\nKFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of\nperspective and timeline order. In a multi-machine or multi-agent world, a\nproduct should not pretend to own a universal global clock. It should preserve\nnon-drifting facts, make trust start from those facts, and let participants\ncooperate by exposing the observer, accepted ranges, causal constraints, and\nprojection policy behind the view."
+      },
       {
         "id": "product-proof-path",
         "sourcePath": "README.md",
@@ -119,7 +146,7 @@
         "homepagePriority": 30,
         "defaultPresentation": "proof-path",
         "includeInFirstScreen": false,
-        "markdown": "KFDs are not a detached manifesto, but they are not a demand that readers adopt\na Kungfu product before understanding the decisions. A philosophy becomes\nload-bearing only when it can be seen in a concrete case. The first concrete\ncase is this package itself: `standards.json`, `schemas/`, `docs/`,\n`site/kfd-site.json`, and `scripts/check.mjs` show how KFD-1, KFD-2, and KFD-3\nare expressed as consumable interfaces for both humans and agents. For the\nbroader product case, use the main Kungfu product entrypoint\n(`https://kungfu.tech`) for product philosophy, and Buildchain\n(`https://buildchain.libkungfu.dev`) for release and provenance\naccountability. This registry states the commitments; this package and those\nentrypoints show how the commitments are meant to be borne in practice.\n\nRendered index: `https://kfd.libkungfu.dev` (stable machine path per entry,\ne.g. `https://kfd.libkungfu.dev/1`). This repository publishes\n`@kungfu-tech/kfd` — the decision texts plus a machine-readable\n`registry.json` — which the site consumes as its single fact source.\n\nMachine consumers that need KFD-owned standard identity should read\n`standards.json`. It is the versioned metadata surface for stable standard\nkeys, document routes and SHA-256 digests, schema IDs, KFD-owned concept names,\nand machine-interface contract versions. In Node or TypeScript projects, import\nit as:\n\n```js\nimport standards from \"@kungfu-tech/kfd/standards.json\" with { type: \"json\" };\n```"
+        "markdown": "KFDs are not a detached manifesto, but they are not a demand that readers adopt\na Kungfu product before understanding the decisions. A philosophy becomes\nload-bearing only when it can be seen in a concrete case. The first concrete\ncase is this package itself: `standards.json`, `schemas/`, `docs/`,\n`site/kfd-site.json`, and `scripts/check.mjs` show how KFD-1, KFD-2, KFD-3,\nand KFD-4 are expressed as consumable interfaces for both humans and agents.\nFor the broader product case, use the main Kungfu product entrypoint\n(`https://kungfu.tech`) for product philosophy, and Buildchain\n(`https://buildchain.libkungfu.dev`) for release and provenance\naccountability. This registry states the commitments; this package and those\nentrypoints show how the commitments are meant to be borne in practice.\n\nRendered index: `https://kfd.libkungfu.dev` (stable machine path per entry,\ne.g. `https://kfd.libkungfu.dev/1`). This repository publishes\n`@kungfu-tech/kfd` — the decision texts plus a machine-readable\n`registry.json` — which the site consumes as its single fact source.\n\nMachine consumers that need KFD-owned standard identity should read\n`standards.json`. It is the versioned metadata surface for stable standard\nkeys, document routes and SHA-256 digests, schema IDs, KFD-owned concept names,\nand machine-interface contract versions. In Node or TypeScript projects, import\nit as:\n\n```js\nimport standards from \"@kungfu-tech/kfd/standards.json\" with { type: \"json\" };\n```"
       },
       {
         "id": "agent-quickstart",
@@ -130,7 +157,7 @@
         "homepagePriority": 40,
         "defaultPresentation": "ordered-steps",
         "includeInFirstScreen": false,
-        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n6. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, release-claims, and release-trust-passport\nschemas under `schemas/kfd-2/`. These schemas let Buildchain and other release\nsystems audit whether public release claims are bound to source facts,\nevidence, hashes, audit boundaries, residual risk, and responsibility state. See\n[`docs/kfd-2-release-trust.md`](docs/kfd-2-release-trust.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/kfd-3-collaboration-interface.md`](docs/kfd-3-collaboration-interface.md)."
+        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n6. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, release-claims, and release-trust-passport\nschemas under `schemas/kfd-2/`. These schemas let Buildchain and other release\nsystems audit whether public release claims are bound to source facts,\nevidence, hashes, audit boundaries, residual risk, and responsibility state. See\n[`docs/kfd-2-release-trust.md`](docs/kfd-2-release-trust.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/kfd-3-collaboration-interface.md`](docs/kfd-3-collaboration-interface.md).\n\nKFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives\nhumans and agents a standard vocabulary for observer, accepted facts,\nprojection policy, causal constraints, degraded evidence, and verification\nstate when a product shows a perspective-bearing timeline."
       },
       {
         "id": "decision-metadata",
@@ -159,6 +186,7 @@
         "foundation-triad",
         "foundation-model",
         "adoption-boundary",
+        "practice-guidelines",
         "product-proof-path"
       ],
       "support": [
@@ -171,7 +199,8 @@
         "ids": [
           "KFD-1",
           "KFD-2",
-          "KFD-3"
+          "KFD-3",
+          "KFD-4"
         ]
       }
     },
@@ -184,7 +213,7 @@
       "homepagePriority": 90,
       "defaultPresentation": "developer-note",
       "includeInFirstScreen": false,
-      "markdown": "This README is also the homepage text source for `https://kfd.libkungfu.dev`.\nWhen `site-libkungfu-dev` consumes the `@kungfu-tech/kfd` npm package to render\nthe KFD site, it should treat this file as the canonical homepage copy, not as\nan implementation note to paraphrase in the site repository.\n\nThe first screen should be derived from this README:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines KFD as the organization-wide\n  decision registry.\n- Foundation signal: the `Foundation triad` section, especially the three\n  one-line commitments.\n- First-screen explanation: the beginning of `Foundation model`, ending at the\n  `non-drifting facts -> inspectable trust -> trusted value -> voluntary\n  cooperation` chain.\n\nDecision cards, detail links, and machine paths should come from\n`registry.json`. The machine-readable site bundle lives at `site/kfd-site.json`\nand gives renderers stable fields for the homepage, foundation model, product\nproof path, decision routes, and rendering boundary. A site renderer may adapt\nlayout, navigation, typography, and visual assets, but it should not maintain\nseparate homepage wording that can drift from this package.\n\n`site/kfd-site.json` is generated from this README by\n`scripts/update-site-bundle.mjs`. The generated bundle exposes both compatible\ntop-level homepage fields and ordered `homepage.sections` entries. The\n`homepage.displayPlan` tells renderers which sections belong in the first\nscreen, primary narrative, and support area. Site repositories should consume\nthat bundle instead of parsing this README themselves. The renderer contract is\nexposed as machine/implementation metadata, not as ordinary homepage content.",
+      "markdown": "This README is also the homepage text source for `https://kfd.libkungfu.dev`.\nWhen `site-libkungfu-dev` consumes the `@kungfu-tech/kfd` npm package to render\nthe KFD site, it should treat this file as the canonical homepage copy, not as\nan implementation note to paraphrase in the site repository.\n\nThe first screen should be derived from this README:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines KFD as the organization-wide\n  decision registry.\n- Foundation signal: the `Foundation triad` section, especially the three\n  one-line commitments.\n- First-screen explanation: the beginning of `Foundation model`, ending at the\n  `non-drifting facts -> inspectable trust -> trusted value -> voluntary\n  cooperation` chain.\n- Practice signal: the `Practice guidelines` section, starting with KFD-4 as\n  the declared-observer rule for perspective-bearing timeline views.\n\nDecision cards, detail links, and machine paths should come from\n`registry.json`. The machine-readable site bundle lives at `site/kfd-site.json`\nand gives renderers stable fields for the homepage, foundation model, product\nproof path, decision routes, and rendering boundary. A site renderer may adapt\nlayout, navigation, typography, and visual assets, but it should not maintain\nseparate homepage wording that can drift from this package.\n\n`site/kfd-site.json` is generated from this README by\n`scripts/update-site-bundle.mjs`. The generated bundle exposes both compatible\ntop-level homepage fields and ordered `homepage.sections` entries. The\n`homepage.displayPlan` tells renderers which sections belong in the first\nscreen, primary narrative, and support area. Site repositories should consume\nthat bundle instead of parsing this README themselves. The renderer contract is\nexposed as machine/implementation metadata, not as ordinary homepage content.",
       "renderAsHomepageContent": false,
       "note": "This is a machine/renderer contract for site implementers. It should not be rendered as ordinary homepage content."
     }

package/standards.json

@@ -201,6 +201,55 @@
         "extensionRequest": "extension request",
         "extensionPath": "extension path"
       }
+    },
+    "kfd-4": {
+      "key": "kfd-4",
+      "id": "KFD-4",
+      "number": 4,
+      "label": "KFD-4",
+      "title": "Timelines must declare their observer: useful views need a stated perspective",
+      "kind": "procedure",
+      "status": "active",
+      "revision": 1,
+      "metadataSchemaVersion": "1",
+      "document": {
+        "path": "decisions/kfd-4.md",
+        "url": "https://kfd.libkungfu.dev/4",
+        "sha256": "7077a6446c8baa60d85426780cb7b2bee488133196b6f53d74f0eb151f6e26e4"
+      },
+      "compatibility": {
+        "packageLine": "v1.0",
+        "registrySchemaVersion": 1,
+        "metadataSchemaVersion": "1",
+        "rule": "Substantive semantic changes mint a new KFD; compatible metadata additions keep schemaVersion 1."
+      },
+      "schemaIds": {
+        "metadata": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json",
+        "observerPerspective": "https://kfd.libkungfu.dev/schemas/kfd-4/observer-perspective.schema.json"
+      },
+      "schemaPaths": {
+        "metadata": "schemas/kfd-standards.schema.json",
+        "observerPerspective": "schemas/kfd-4/observer-perspective.schema.json"
+      },
+      "interfaces": {
+        "observerPerspective": {
+          "contract": "kfd-4-observer-perspective",
+          "schemaVersion": 1,
+          "schemaId": "https://kfd.libkungfu.dev/schemas/kfd-4/observer-perspective.schema.json",
+          "schemaPath": "schemas/kfd-4/observer-perspective.schema.json",
+          "compatibilityRule": "Compatible additions may keep schemaVersion 1; semantic or required-field changes require a new interface version or contract."
+        }
+      },
+      "concepts": {
+        "observer": "observer",
+        "declaredPerspective": "declared perspective",
+        "observerPerspective": "observer perspective",
+        "acceptedFacts": "accepted facts",
+        "projectionPolicy": "projection policy",
+        "causalDominance": "causal dominance",
+        "degradedEvidence": "degraded evidence",
+        "timeline": "perspective-bearing timeline"
+      }
     }
   }
 }