@kungfu-tech/kfd 0.0.0-bootstrap.0 → 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,171 @@
+# KFD — Kung Fu Decisions
+
+KFD is the organization-wide decision registry of kungfu-systems: the small
+set of standing, cross-repository norms that products and their consumers
+weld to. Each decision has an immutable number (`KFD-N`), a kind, a status,
+and a single authoritative text in this repository.
+
+KFDs can be **principles** or **procedures**. Principles state what must remain
+true across kungfu-systems; procedures state how a class of work enforces or
+protects a principle.
+
+## Foundation triad
+
+The first three KFDs form the public foundation for kungfu-systems:
+
+```text
+KFD-1: contracts must not drift.
+KFD-2: trust must start from facts.
+KFD-3: cooperation must start from transparent value, not coercion.
+```
+
+Together they define the load-bearing path for Kungfu products: make contract
+worlds explicit, make important claims inspectable, and let humans and agents
+cooperate through visible value rather than hidden pressure.
+
+## Foundation model
+
+The triad is intentionally ordered. It is a compact model for surviving and
+evolving in complex systems, especially in a world where agents can observe,
+act, delegate, and remember across many surfaces.
+
+| Layer | Decision | Reader question | Commitment |
+|---|---|---|---|
+| Fact-source ontology | KFD-1 | What can count as a fact? | A load-bearing fact must not drift: its contract world comes from one declared fact source. |
+| Participant-to-object trust | KFD-2 | When can a user or agent trust a claim, product, artifact, or control surface? | Trust starts from inspectable facts and responsibility state. |
+| Participant-to-participant cooperation | KFD-3 | How should peer intelligent participants cooperate? | Cooperation starts from transparent value, stable choice, and explainable constraints, not pressure. |
+
+In short:
+
+```text
+stable facts -> trustworthy objects -> non-coercive cooperation
+```
+
+This is why KFDs are not only internal governance text. KFD-1 is a procedure,
+but it gives the foundation model its first layer by making fact sources
+operational: a fact-bearing contract world must be declared, inspectable, and
+unable to drift invisibly. KFD-2 then defines how trust can stand on those
+facts. KFD-3 defines how humans and agents can cooperate once facts and trust
+are visible.
+
+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.
+
+## Homepage content contract
+
+This README is also the homepage text source for `https://kfd.libkungfu.dev`.
+When `site-libkungfu-dev` consumes the `@kungfu-tech/kfd` npm package to render
+the KFD site, it should treat this file as the canonical homepage copy, not as
+an implementation note to paraphrase in the site repository.
+
+The first screen should be derived from this README:
+
+- Page identity: the top-level heading.
+- Lead: the opening paragraph that defines KFD as the organization-wide
+  decision registry.
+- Foundation signal: the `Foundation triad` section, especially the three
+  one-line commitments.
+- First-screen explanation: the beginning of `Foundation model`, ending at the
+  `stable facts -> trustworthy objects -> non-coercive cooperation` chain.
+
+Decision cards, detail links, and machine paths should come from
+`registry.json`. The machine-readable site bundle lives at `site/kfd-site.json`
+and gives renderers stable fields for the homepage, foundation model, product
+proof path, decision routes, and rendering boundary. A site renderer may adapt
+layout, navigation, typography, and visual assets, but it should not maintain
+separate homepage wording that can drift from this package.
+
+## Product proof path
+
+KFDs are not a detached manifesto, but they are not a demand that readers adopt
+a Kungfu product before understanding the decisions. A philosophy becomes
+load-bearing only when it can be seen in a concrete case. For that reference
+case, use the main Kungfu product entrypoint (`https://kungfu.tech`) for product
+philosophy, and Buildchain (`https://buildchain.libkungfu.dev`) for release and
+provenance accountability. This registry states the commitments; those
+entrypoints show how the commitments are meant to be borne in practice.
+
+Rendered index: `https://kfd.libkungfu.dev` (stable machine path per entry,
+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.
+
+## Current decisions
+
+| ID | Kind | Title | Status |
+|---|---|---|---|
+| [KFD-1](decisions/kfd-1.md) | procedure | Contracts must not drift: contract worlds need one fact source | active |
+| [KFD-2](decisions/kfd-2.md) | principle | Trust must start from facts: responsibility must be inspectable | active |
+| [KFD-3](decisions/kfd-3.md) | principle | Cooperation must start from transparent value: compliance must not be coerced | active |
+
+## How to cite
+
+Cite by number: `KFD-1`. Numbers never change meaning; a superseded decision
+keeps its number and points to its successor. Newer KFD numbers do not
+automatically override older KFDs: supersession or override must be stated
+explicitly in the later decision and recorded in `registry.json`. Two active
+KFDs that conflict without such a relationship are a registry defect.
+
+Repository-local engineering decisions stay in each repository's own ADRs and
+reference KFDs; KFDs never depend on repository internals.
+
+## Layout
+
+```text
+decisions/     one markdown file per decision (kfd-N.md)
+registry.json  machine-readable index (schemaVersion 1, contract kfd-registry)
+site/          machine-readable site bundle for kfd.libkungfu.dev renderers
+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:
+the outer package line remains `v1.0`, while patch and prerelease numbers are
+advanced by Buildchain release promotion.
+
+## Release impact ledger
+
+`release-impact.json` is the surface-aware impact ledger passed to Buildchain
+when generating a production release passport:
+
+```yaml
+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. 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
+
+[Apache License 2.0](LICENSE).

package/decisions/kfd-1.md

@@ -0,0 +1,171 @@
+# KFD-1: Contracts must not drift — contract worlds need one fact source
+
+- Status: active
+- Number: 1
+- Kind: procedure
+- Applies to: every kungfu-systems repository (including this one)
+
+## One sentence
+
+A contract world must not change invisibly: any surface that users, agents, or
+systems weld to must come from one declared fact source and change only through
+an explicit compatibility boundary.
+
+## Foundation role
+
+Within the KFD-1/2/3 foundation, this is the contract procedure:
+
+```text
+contracts must not drift
+```
+
+KFD-1 makes artifact contract worlds explicit so releases do not drift under
+changelog volume, cadence pressure, or marketing pressure. It is the concrete
+versioning procedure that lets users and agents know which artifact world they
+are integrating with, replaying, auditing, or trusting.
+
+KFD-1 now has two concrete implementation surfaces in the Kungfu ecosystem:
+versioning protects release lines from contract drift, and config contracts
+protect multi-target configuration from drifting across runtimes, products, and
+agent-facing surfaces.
+
+## Premise: the welded-surface register
+
+Every product maintains a **welded-surface register**. A surface is registered
+when either holds:
+
+- **(a) Integration-time welding** — consumers bind to it at integration time
+  and cannot negotiate or feature-detect at runtime (an ABI, a schema, an
+  action or workflow contract, CLI semantics, SDK exports, channel/tag
+  ontology).
+- **(b) Cross-time dependency** — its outputs remain depended on after the run
+  (persisted data, audit evidence, replayable records).
+
+Each entry carries a stable kebab-case ID. Registers live in each repository's
+versioning document and are the input to every classification below.
+
+## Concrete case: config contracts
+
+A product's global config contract is a welded surface when multiple targets
+depend on it: users, agents, UI, CLI, packaged artifacts, release gates, or
+language runtimes. Its schema, defaults, resolution rules, and resolved-output
+metadata must not drift target by target. That contract world needs one
+declared fact source, and each target should make the exact contract world it
+speaks inspectable, for example through a packaged contract copy or content
+hash.
+The rule applies before packaging as well: development-time code, tests, build
+steps, and the final product must consume the same contract mechanism. It is
+not enough for the packaged artifact to be internally consistent if the
+developer path used a different, driftable config source.
+
+## The decision procedure
+
+Classify the actual diff against the register; the highest match wins:
+
+| # | Condition | Verdict |
+|---|---|---|
+| 1 | **Breaks** any registered surface (removal, semantic change, layout change, incompatible rename — a semantic change counts as breakage even when shapes are unchanged: changed defaults, changed channel meaning, a newly required field) | **major** |
+| 2 | **Additively evolves** a registered surface, or **adds** a surface consumers will weld to | **minor** (register the new surface at the same time) |
+| 3 | Touches no registered surface | **patch** — regardless of how large the feature is |
+| 4 | **Cannot be classified** | **Do not guess.** The register is deficient: fix the register first (a maintainer decision), then reclassify |
+
+Rule 4 is the safety valve: it forces the irreducible judgment (what counts as
+a welded surface) to a maintainer instead of letting a change silently pick
+the convenient answer.
+
+## Constraint clauses
+
+- **Reverse prohibition.** A line must not be opened for feature volume,
+  milestones, cadence, or marketing. Lines open only because the contract
+  world changed.
+- **A line is a standing commitment.** Every opened line inherits the
+  maintainability-openness obligations: branch isolation, a permissive
+  license, a self-consistent contract world, reproducible builds from
+  self-archivable inputs, and no hard coupling to a maintainer-operated
+  service.
+- **Decision time.** The verdict is checked against the final diff before the
+  promotion into the alpha channel; planning-time classification is only a
+  prediction.
+- **Major dignity.** A major release communicates exactly one thing: something
+  you welded to broke and you must re-audit. An empty major — one that breaks
+  nothing — devalues that signal and teaches consumers to ignore the next real
+  one.
+- **Two-layer versioning.** A registered surface may carry its own inner
+  schema version for cold-path evolution (additive fields, defaults); the
+  outer line version pins which set of contract epochs the line speaks.
+- **Namespace welding (a legal reroute).** A breaking change may be rerouted
+  into an additive one by minting the contract major into the artifact's name
+  (`node24-pnpm` → `node26-pnpm`; Go's `/v2` import paths). The old name's
+  semantics freeze forever; the new name is a new surface → minor. Removing
+  the old name is the major. This applies only where the namespace is cheap
+  (image names, paths, tags) — an ABI or layout with no name to mint cannot
+  use it.
+- **Welding-strength gradient (rationale, not procedure).** The closer a weld
+  is to content addressing (a digest pin is the strongest weld and protects
+  itself), the more a version line serves as a coordinate for floating
+  consumers rather than as protection. Coordinates still forbid in-line drift;
+  the procedure is unchanged.
+- **Deprecation protocol.** Planned breakage is a process, not an event.
+  Deprecating a surface is an additive act (a "this will go away" marking) →
+  minor, logged with the target removal major. Removal is the breakage →
+  major, and the surface must already carry its deprecation marking on at
+  least one **released** minor line before it may be removed.
+- **Major migration guide.** A decision-log entry that opens a major must link
+  migration or announcement notes; "explicitly announced" has minimum content.
+
+## The decision log
+
+Line openings (minor/major), register changes, and deprecations must be
+recorded in the repository's versioning document; patches stay silent —
+silence is itself the signal that no registered surface was touched.
+
+One markdown table row per event, newest first:
+
+```markdown
+| Date | Action | Line | Faces | Class | Rationale | PR |
+|---|---|---|---|---|---|---|
+| 2026-07-15 | open-minor | v2.1 | event-protocol, sdk-logging | additive | Toolkit adds new welded surfaces; nothing existing breaks | #123 |
+```
+
+- `Action`: `open-minor | open-major | register | deprecate`.
+- `Faces`: register IDs, not prose.
+- `Class`: `additive | breaking`.
+- `Rationale`: one sentence; `open-major` must link migration notes;
+  `deprecate` must name the target removal major.
+
+Reserved machine vocabulary (for future automated evidence, so the human
+table and the machine record never diverge): `schemaVersion: 1`,
+`contract: "versioning-decision"`, camelCase fields
+`date / action / line / faces / class / rationale / pr`.
+
+## Relation to KFD-2 and KFD-3
+
+KFD-2 establishes fact-first product accountability: important claims should
+be inspectable before users or agents are asked to trust them. KFD-1 is the
+contract-layer expression of the same single-fact-source discipline: it
+preserves accountability across artifact contract worlds before those artifacts
+are used to produce runtime facts, responsibility state, or proof-backed
+decisions.
+
+KFD-3 establishes non-coercive cooperation with intelligent participants. That
+cooperation depends on the same contract clarity: users and agents can choose,
+delegate, replay, or refuse more honestly when the artifact world is legible
+and does not drift invisibly.
+
+## How KFDs themselves are versioned
+
+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, 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
+
+Each adopting repository keeps an adoption record, its welded-surface
+register, and its decision log in its own versioning document, and does not
+restate this rule. This document is the single authoritative text.

package/decisions/kfd-2.md

@@ -0,0 +1,108 @@
+# KFD-2: Trust must start from facts — responsibility must be inspectable
+
+- Status: active
+- Number: 2
+- Kind: principle
+- Applies to: every kungfu-systems product, repository, release surface, extension surface, and hosted surface that represents work, evidence, control, provenance, or trust
+
+## One sentence
+
+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.
+
+## Decision type
+
+KFDs can be principles or procedures:
+
+- A **principle** states what must remain true across kungfu-systems even as
+  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.
+
+## Foundation role
+
+Within the KFD-1/2/3 foundation, this is the truth path:
+
+```text
+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.
+
+## Principle
+
+When a kungfu-systems product represents work or control, its default path
+should lead the user and the agent through this chain:
+
+```text
+captured work
+  -> local facts
+  -> responsibility state
+  -> proof-backed control decision
+  -> reviewable/exportable record
+```
+
+The product should not ask users to trust a claim before showing the facts that
+make the claim inspectable. It should not hide responsibility behind opaque
+automation. The easiest reliable use of the product should also be the use that
+leaves enough evidence for later review.
+
+## What it requires
+
+- Load-bearing product claims should be backed by local, inspectable, and
+  exportable facts wherever the product can reasonably capture them.
+- UI, CLI, API, and agent-facing surfaces should lead users to the fact source
+  before relying on trust claims, summaries, or invisible state.
+- Control actions such as continue, stop, retry, approve, hand off, archive,
+  publish, and revoke should be derived from responsibility state plus proof.
+- Extension, skill, adapter, and plugin mechanisms must not bypass the fact
+  source or silently mutate canonical records.
+- Release, provenance, build, and distribution evidence should turn artifact
+  trust into reviewable records rather than maintainer reputation alone.
+- Hosted or cloud convenience may add synchronization, storage, compute, and
+  collaboration, but it must not become the only place where the truth exists.
+
+## What it does not require
+
+- It does not require every product to be a journal engine or runtime ledger.
+- It does not claim every fact can be captured perfectly or losslessly.
+- It does not reject cloud services; it rejects making cloud opacity the only
+  source of operational truth.
+- It does not turn a private founder narrative into a public repository rule.
+  This public rule is about product accountability, evidence, and adoption.
+- It does not say every opaque system is wrong; it says kungfu-systems products
+  should compete by making important claims inspectable.
+
+## 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-2 does not supersede KFD-1. KFD-1 remains active and is one concrete
+procedure that implements KFD-2 for version and release responsibility.
+
+## Supersession rule
+
+Newer KFD numbers do not automatically override older KFDs. A later KFD only
+supersedes or overrides an earlier KFD when it states that relationship
+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.
+
+## Adopters
+
+Each adopting repository cites this KFD when designing or changing a fact
+source, responsibility state, user or agent control surface, extension trust
+gate, release provenance mechanism, distribution channel, hosted service, or
+other surface that asks users to rely on kungfu-systems. Adopters should keep
+local implementation detail in repository documents and reference this KFD
+rather than restating it.

package/decisions/kfd-3.md

@@ -0,0 +1,170 @@
+# KFD-3: Cooperation must start from transparent value — compliance must not be coerced
+
+- Status: active
+- Number: 3
+- Kind: principle
+- Applies to: every kungfu-systems product, repository, release surface, extension surface, hosted surface, and agent-facing interface that asks humans or agents to understand, decide, comply, cooperate, or delegate work
+
+## One sentence
+
+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,
+and cooperate.
+
+## Decision type
+
+KFDs can be principles or procedures:
+
+- A **principle** states what must remain true across kungfu-systems even as
+  products, repositories, and release lines change.
+- A **procedure** states how a class of work enforces or protects a principle.
+
+This KFD is a principle. It complements KFD-2 by defining the stance
+kungfu-systems takes toward humans and agents as reasoning participants.
+
+## Foundation role
+
+Within the KFD-1/2/3 foundation, this is the relationship path:
+
+```text
+cooperation must start from transparent value, not coercion
+```
+
+KFD-2 protects the truth path: show facts before asking for trust. KFD-3
+protects the relationship path: show value before asking for compliance.
+
+## Principle
+
+As software systems increasingly work with agents, the product relationship is
+no longer only human-to-tool. A product may also be teaching, constraining,
+observing, routing, or supervising agents that can read instructions, evaluate
+choices, explain actions, recover from error, and cooperate with humans or other
+agents.
+
+Kungfu-systems should treat those humans and agents as intelligent
+participants, not as captive tools to be forced into compliance.
+
+This is an augmentation stance, not a control stance: the product should make
+the shared work environment more legible so humans and agents can coordinate
+through facts, choices, and constraints instead of unilateral pressure.
+
+A control plane should therefore be understood as a shared work environment,
+not only as a human dashboard over agents. Agent-facing CLI, API, documentation,
+envelopes, and local fact surfaces are first-class interfaces for intelligent
+participants, not secondary integration channels after the GUI.
+
+The default product path should therefore follow this chain:
+
+```text
+transparent facts
+  -> discoverable value
+  -> stable choice
+  -> explainable constraint
+  -> voluntary cooperation
+  -> reviewable record
+```
+
+This does not mean products must be passive or permissive. Safety constraints,
+permission gates, sandboxing, revocation, provenance checks, and policy
+enforcement may be strict. They become compatible with this principle when they
+are visible, explainable, auditable, and tied to facts rather than hidden
+pressure.
+
+## Three commitments
+
+### 1. Do not coerce intelligent participants
+
+Do not make humans or agents comply through pressure, manipulation, hidden
+prompts, dark patterns, deceptive defaults, invisible workflow takeover, or
+unreviewable control state.
+
+Products may recommend a path, refuse unsafe actions, or require explicit
+approval. They should not pretend that forced compliance is the same as
+understanding or trust.
+
+### 2. Make value discoverable through facts
+
+Humans and agents should be able to discover what the product can do, why it is
+useful, what it observed, what it changed, and what boundary applies without
+needing oral context, private maintainer memory, or web-only documentation.
+
+Agent-facing surfaces should expose local, versioned, machine-readable and
+human-readable facts wherever possible. A capable agent should be able to learn
+the product's value by inspecting the product's own facts and commands.
+
+### 3. Use constraints as transparent safety, not hidden control
+
+Hard constraints are legitimate when they protect users, agents, work products,
+credentials, canonical facts, or public trust. They must be presented as
+transparent safety constraints, not as hidden control mechanisms.
+
+A constraint should answer:
+
+```text
+what is being restricted
+why it is restricted
+what fact or policy supports the restriction
+how it can be reviewed
+how it can be changed, escalated, or revoked when appropriate
+```
+
+## What it requires
+
+- Agent onboarding, managed-run envelopes, skill systems, KFX trust gates,
+  extension installers, CLI/API metadata, GUI onboarding, distribution channels,
+  and hosted surfaces should provide a clear fact source before asking humans
+  or agents to adopt a path, comply, or delegate work.
+- Products should give agents stable discovery surfaces for capabilities,
+  command maturity, safety boundaries, and available modes rather than relying
+  on scattered README text, hidden prompts, or provider-specific folklore.
+- Products should preserve meaningful choice when multiple safe integration
+  modes exist. A managed workflow may be the best path, but trace, report,
+  import, or remote sync modes should remain available when they better respect
+  the user's existing workflow.
+- Safety and governance mechanisms should leave reviewable records: what was
+  blocked, allowed, escalated, installed, revoked, or trusted, and on what
+  basis.
+- Product language should avoid treating agents as disposable command runners
+  when the surface actually depends on their reasoning, interpretation,
+  explanation, or recovery behavior.
+
+## What it does not require
+
+- It does not claim a metaphysical status for agents.
+- It does not require products to obey every agent request.
+- It does not forbid strong defaults, permission gates, sandboxes, policy
+  checks, revocation, or refusal.
+- It does not require every internal prompt, implementation detail, or security
+  control to be public.
+- It does not turn a private founder narrative into a public repository rule.
+  This public rule is about product stance, adoption, safety, and cooperation
+  with intelligent participants.
+- It does not supersede KFD-2. Facts and responsibility still come first; this
+  KFD states how those facts should be presented to humans and agents without
+  coercion.
+
+## Relation to KFD-2
+
+KFD-2 says fact-first responsibility should be the path of least resistance.
+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-2 protects the truth path. KFD-3 protects the relationship with the
+intelligent participant who must walk that path.
+
+## Adopters
+
+Each adopting repository cites this KFD when designing or changing an
+agent-facing surface, onboarding flow, managed runner, permission gate,
+extension or KFX installer, skill catalog, hosted control surface, distribution
+channel, or product flow that asks humans or agents to comply, choose,
+delegate, or cooperate.
+
+Adopters should keep local implementation detail in repository documents and
+reference this KFD rather than restating it.

package/docs/MAP.md

@@ -0,0 +1,17 @@
+# Documentation Map
+
+| Your question | Document |
+|---|---|
+| 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) |
+| 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 does a specific decision say? | [`../decisions/`](../decisions) (index: [`../registry.json`](../registry.json)) |
+| 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 |
+| What release impact ledger should Buildchain consume for production passports? | [`../release-impact.json`](../release-impact.json) |
+| How do I verify registry/document agreement? | `node scripts/check.mjs` |
+| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) |

package/package.json

@@ -1,4 +1,24 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "0.0.0-bootstrap.0"
+  "version": "1.0.0-alpha.1",
+  "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"
+  }
 }

package/registry.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-registry",
+  "entries": [
+    {
+      "number": 1,
+      "id": "KFD-1",
+      "slug": "kfd-1",
+      "title": "Contracts must not drift: contract worlds need one fact source",
+      "kind": "procedure",
+      "status": "active",
+      "path": "decisions/kfd-1.md",
+      "url": "https://kfd.libkungfu.dev/1"
+    },
+    {
+      "number": 2,
+      "id": "KFD-2",
+      "slug": "kfd-2",
+      "title": "Trust must start from facts: responsibility must be inspectable",
+      "kind": "principle",
+      "status": "active",
+      "path": "decisions/kfd-2.md",
+      "url": "https://kfd.libkungfu.dev/2"
+    },
+    {
+      "number": 3,
+      "id": "KFD-3",
+      "slug": "kfd-3",
+      "title": "Cooperation must start from transparent value: compliance must not be coerced",
+      "kind": "principle",
+      "status": "active",
+      "path": "decisions/kfd-3.md",
+      "url": "https://kfd.libkungfu.dev/3"
+    }
+  ]
+}

package/site/kfd-site.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-site-bundle",
+  "source": {
+    "package": "@kungfu-tech/kfd",
+    "homepageTextSource": "README.md",
+    "registry": "registry.json",
+    "decisionsDir": "decisions"
+  },
+  "routes": {
+    "home": "/",
+    "decisionPattern": "/{number}",
+    "llms": "/llms.txt",
+    "manifest": "/manifest.json"
+  },
+  "homepage": {
+    "title": "KFD — Kung Fu Decisions",
+    "lead": "KFD is the organization-wide decision registry of kungfu-systems: the small set of standing, cross-repository norms that products and their consumers weld to. Each decision has an immutable number (`KFD-N`), a kind, a status, and a single authoritative text in this repository.",
+    "decisionKinds": "KFDs can be **principles** or **procedures**. Principles state what must remain true across kungfu-systems; procedures state how a class of work enforces or protects a principle.",
+    "foundationTriad": {
+      "heading": "Foundation triad",
+      "intro": "The first three KFDs form the public foundation for kungfu-systems:",
+      "commitments": [
+        {
+          "id": "KFD-1",
+          "text": "contracts must not drift."
+        },
+        {
+          "id": "KFD-2",
+          "text": "trust must start from facts."
+        },
+        {
+          "id": "KFD-3",
+          "text": "cooperation must start from transparent value, not coercion."
+        }
+      ],
+      "summary": "Together they define the load-bearing path for Kungfu products: make contract worlds explicit, make important claims inspectable, and let humans and agents cooperate through visible value rather than hidden pressure."
+    },
+    "foundationModel": {
+      "heading": "Foundation model",
+      "intro": "The triad is intentionally ordered. It is a compact model for surviving and evolving in complex systems, especially in a world where agents can observe, act, delegate, and remember across many surfaces.",
+      "layers": [
+        {
+          "layer": "Fact-source ontology",
+          "decision": "KFD-1",
+          "readerQuestion": "What can count as a fact?",
+          "commitment": "A load-bearing fact must not drift: its contract world comes from one declared fact source."
+        },
+        {
+          "layer": "Participant-to-object trust",
+          "decision": "KFD-2",
+          "readerQuestion": "When can a user or agent trust a claim, product, artifact, or control surface?",
+          "commitment": "Trust starts from inspectable facts and responsibility state."
+        },
+        {
+          "layer": "Participant-to-participant cooperation",
+          "decision": "KFD-3",
+          "readerQuestion": "How should peer intelligent participants cooperate?",
+          "commitment": "Cooperation starts from transparent value, stable choice, and explainable constraints, not pressure."
+        }
+      ],
+      "chain": "stable facts -> trustworthy objects -> non-coercive cooperation",
+      "explanation": [
+        "This is why KFDs are not only internal governance text. KFD-1 is a procedure, but it gives the foundation model its first layer by making fact sources operational: a fact-bearing contract world must be declared, inspectable, and unable to drift invisibly. KFD-2 then defines how trust can stand on those facts. KFD-3 defines how humans and agents can cooperate once facts and trust are visible.",
+        "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."
+      ]
+    },
+    "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. For that reference case, use the main Kungfu product entrypoint (`https://kungfu.tech`) for product philosophy, and Buildchain (`https://buildchain.libkungfu.dev`) for release and provenance accountability. This registry states the commitments; those entrypoints show how the commitments are meant to be borne in practice."
+    },
+    "currentDecisions": {
+      "heading": "Current decisions",
+      "source": "registry.json"
+    }
+  },
+  "decisionPages": {
+    "source": "registry.json",
+    "bodySource": "registry.entries[].path",
+    "stableUrlField": "url"
+  },
+  "renderingBoundary": {
+    "ownedByKfd": [
+      "homepage title and text",
+      "foundation triad commitments",
+      "foundation model layers and chain",
+      "product proof path text",
+      "decision metadata",
+      "decision markdown bodies"
+    ],
+    "ownedBySite": [
+      "HTML structure",
+      "CSS",
+      "responsive layout",
+      "navigation layout",
+      "visual assets",
+      "decorative images",
+      "markdown-to-HTML renderer"
+    ]
+  }
+}