@knowledge-bus/opencode 0.5.0 → 0.8.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@knowledge-bus/opencode",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "private": false,
-  "description": "Knowledge Bus workflows for OpenCode",
+  "description": "Define, inspect, and check Knowledge Bus expectations in OpenCode",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",

package/references/agent-runtime.md

@@ -18,11 +18,15 @@ Requires [uv](https://docs.astral.sh/uv/) and Python matching `requires_python`
 ```sh
 python3 /absolute/runtime/kbp.py --validate /absolute/target/.knowledge-bus/
 python3 /absolute/runtime/kbp.py --mint element 1 /absolute/target/.knowledge-bus/
+python3 /absolute/runtime/kbp.py --inspect /absolute/target/.knowledge-bus/
+python3 /absolute/runtime/kbp.py --explore --output /absolute/output /absolute/target/.knowledge-bus/
 ```
 
-The bundled wheel supplies the checker and protocol. Its pinned dependency can be downloaded on first use. The launcher keeps its cache outside the installation and preserves the caller's working directory and failure exit code. If a prerequisite is missing, report it; do not install tools without permission.
+The bundled wheel supplies the checker, protocol, and required Python code. The launcher uses bundled files without registry access, keeps its cache outside the installation, and preserves the caller's working directory and failure exit code. If a prerequisite is missing, report it; do not install tools without permission.
 
-Supply an absolute target when the shell is not in the user's folder. Checking never initializes a folder. `KNOWLEDGE_BUS_CACHE_DIR` optionally selects another external cache location.
+Supply an absolute universe file, knowledge-base folder, or its `.knowledge-bus/` folder when the shell is elsewhere. Checking never initializes a folder. `.knowledge-bus/` is the reserved Knowledge Bus configuration directory, not the knowledge base itself. `KNOWLEDGE_BUS_CACHE_DIR` optionally selects another cache location.
+
+`--inspect` prints an Explorer model and writes nothing. When the scope contains several universes, select one with `--universe`. `--explore` requires an output directory and refuses existing output unless `--replace` is supplied. It builds an offline Explorer from the bundled viewer.
 
 ## References
 
@@ -32,4 +36,4 @@ The references directory containing this guide includes `knowledge-bus-protocol.
 
 The checker first checks that its protocol is sound. It checks definitions and guidance for required fields, code collisions, references, version compatibility, and permitted structures. Include the universe when checking its guidance.
 
-Each failure names the offending declaration or reference. Explain the change it calls for. A passing result does not establish that a question is useful or that an answer is true. Answers and ingestion logs still require human review.
+Each failure names the offending declaration or reference. Explain how to correct the reported problem. Report conformance and Explorer renderability separately. A passing result does not establish that a question is useful or that an answer is true. Answers and ingestion logs still require human review.

package/references/knowledge-bus-directory.md

@@ -10,8 +10,14 @@ my-folder/
 └── .knowledge-bus/
     ├── universe.kbp.yaml
     ├── type-guidance.kbp.yaml   # optional
+    ├── marks.explorer.yaml      # optional presentation declarations
     ├── answers.yaml            # when recording answers
-    └── ingest-log.md           # when ingesting existing material
+    ├── ingest-log.md           # when ingesting existing material
+    └── explorer/               # optional generated read-only projection
+        └── <universe-id>/
+            ├── index.html
+            ├── model.json
+            └── receipt.json
 ```
 
 Any folder can contain a `.knowledge-bus/` directory. Git is not required. Define the structure before creating documents, or derive it from existing material through ingestion. Answers and an ingest log are not prerequisites for authoring a universe.
@@ -28,7 +34,26 @@ kbp --validate path/to/universe.kbp.yaml path/to/type-guidance.kbp.yaml
 
 Without an explicit target, the checker searches the current folder and then its parents for `.knowledge-bus/`. It uses the first one found and does not combine definitions from different directories. Calls from inside `.knowledge-bus/` use that directory. An empty or incomplete nearer directory does not fall back to a parent's `.knowledge-bus/`.
 
-The selected Knowledge Bus directory supplies its directly contained `*.kbp.yaml` files together, so guidance can resolve its universe. Answers and logs are not checker inputs. Explicit file targets select exactly those files; include the universe when checking guidance.
+The checker reads the `*.kbp.yaml` files directly inside the selected `.knowledge-bus/` directory together, so it can check guidance against its universe. Duplicate universe ids fail. Answers, logs, presentation marks, and Explorer outputs are not checker inputs. Explicit file targets select exactly those files; include the universe when checking guidance.
+
+## Several Universes in One Scope
+
+Several universes may be direct siblings in one `.knowledge-bus/`. Prefix filenames for people, but rely on semantic headers for identity and association:
+
+```text
+.knowledge-bus/
+├── product-development.universe.kbp.yaml
+├── product-development.type-guidance.kbp.yaml
+├── product-development.marks.explorer.yaml
+├── team-operations.universe.kbp.yaml
+├── team-operations.type-guidance.kbp.yaml
+├── team-operations.marks.explorer.yaml
+└── explorer/
+    ├── product-development/{index.html,model.json,receipt.json}
+    └── team-operations/{index.html,model.json,receipt.json}
+```
+
+`universe.id` identifies a universe. `guidance.guides` and `marks.marks_for` associate its companion files. When the directory contains several universes, inspection requires an id or universe file. Duplicate ids and ambiguous companion files fail. Generated Explorers stay under their universe ids. Nested `.knowledge-bus/` directories remain separate.
 
 A generic directory target without its own `.knowledge-bus/` still scans for `*.kbp.yaml` files, for example a reference collection or test corpus. It skips metadata directories and nested folders that contain their own `.knowledge-bus/`. Directory scans do not follow nested directory symlinks.
 

package/references/knowledge-bus-protocol.yaml

@@ -1,7 +1,7 @@
 protocol:
   id: kbp
   name: Knowledge Bus Protocol
-  version: 0.5
+  version: 0.7
   status: draft
   purpose: >
     The structured exchange of contextual knowledge rather than data. Defines what a
@@ -95,6 +95,24 @@ declarations:
     scope: >
       A predicate in a universe names frames only. A factor id is legal in a guidance
       entry's `when` and nowhere else.
+    evaluation:
+      result: true | false | unknown
+      rules:
+        - Named dimensions and named facets are combined with AND.
+        - Values in each predicate list are alternatives combined with OR.
+        - An empty predicate is true; an empty alternatives list is false.
+        - >
+          Missing context is unknown, not false. AND is false if any operand is
+          false, true if all are true, and unknown otherwise.
+        - >
+          Context supplies one resolved value per dimension or facet at the scope
+          being evaluated. Consumers MUST NOT guess a missing value, merge distinct
+          outcome-components, or substitute an artifact's placement for an element's
+          ordering value. Evaluate each applicable scope separately.
+        - >
+          Invalid locally enumerated values and undeclared facets are errors, not
+          unknown. Source-backed values require resolution against their registry;
+          lack of that resolution leaves the affected context unknown.
 
   universe:
     document:
@@ -200,7 +218,27 @@ declarations:
   relation_kind:
     id: "<kind-id>"
     ordered: true | false
+    phrasing:
+      forward: "<plain-text phrase>"
+      reverse: "<plain-text phrase>"
     required: [id, ordered]
+    rules:
+      - ordered MUST be a boolean.
+      - >
+        phrasing is optional. When present it MUST be a mapping with exactly
+        forward for an unordered kind, or exactly forward and reverse for an
+        ordered kind. Each value MUST be a nonblank string.
+      - >
+        For an edge from A to B, forward reads A / phrase / B and reverse reads
+        B / phrase / A. An unordered kind uses forward from either endpoint.
+        Consumers choose the phrase by the displayed subject, not by selection
+        state. Phrases are plain text, without template interpretation or inferred
+        grammatical changes; endpoint names remain separate display components.
+      - >
+        Phrasing does not change the relation's meaning, direction or restrictions.
+        Shared kind contracts still apply. Without phrasing, consumers retain
+        shared explanations where defined and MUST NOT invent inverse wording for
+        custom kinds.
 
   guidance:
     document:
@@ -284,13 +322,41 @@ composition:
 
   rules:
     - An element appears at most once per artifact.
+    - An explicit entry strength MUST agree with its containing composition list.
     - Exactly one artifact owns a given element instance; others link to the owner.
     - Strength MAY be conditional on a frame predicate.
+    - >
+      On a core entry, when controls requiredness: true means core, false means
+      situationally available, and unknown means unresolved requiredness. A false
+      strength predicate does not exclude the element or require a second entry.
+    - >
+      On a situational entry, when controls situational availability: true means
+      available, false means excluded, and unknown means unresolved availability.
+      With no when, the entry has its containing list's strength and is available,
+      subject to the independent applicability rules below.
     - A universe MAY disable an artifact type entirely under a frame predicate.
     - >
       A universe MUST be able to return the empty composition. Where no frame value
       warrants structure, the conforming answer is no artifact.
 
+  evaluation:
+    precedence:
+      - >
+        Evaluate artifact disabled_when and universe empty_composition.when first.
+        A true disabled_when returns disabled; otherwise a true empty predicate
+        returns empty. Either definite outcome suppresses all members, even when
+        the other predicate is unknown. If neither is true and either is unknown,
+        the artifact result is unresolved, not an asserted usable composition.
+      - >
+        For an applicable artifact, evaluate each element gate at its applicable
+        scope. A false gate excludes the member regardless of strength; an unknown
+        gate leaves applicability unresolved. An absent gate allows the member.
+      - >
+        Apply the entry's strength/availability rule only to applicable members.
+        Preserve unresolved members as unresolved rather than silently discarding
+        or promoting them. These results describe requirements and availability;
+        they do not assert that instances exist or that the action is ready.
+
   ordering:
     declared_by: universe
     attaches_to: element
@@ -301,6 +367,29 @@ composition:
 
 relations:
 
+  kind_contracts:
+    scope: >
+      Universes still declare their kinds. The following ids have shared meanings
+      in this protocol version and MUST use the stated ordered value. Other ids
+      remain universe-defined; consumers MUST NOT infer a shared meaning from
+      their names. These contracts do not generate extra edges.
+    distinct-from:
+      ordered: false
+      meaning: >
+        The definitions answer different questions or enable different actions and
+        must not be substituted for one another. The distinction is symmetric.
+      limits: >
+        Not transitive. Does not imply opposites, disjoint contents or disjoint
+        instances. Different ids alone do not warrant emitting an edge.
+    feeds:
+      ordered: true
+      meaning: Knowledge from the source can inform the target.
+      limits: >
+        Source to recipient. Does not imply mandatory sequence, causation, proof,
+        ownership, copying or actual instance provenance. A feeds B and B feeds C
+        do not entail A feeds C. Gate, legality and freeze restrictions remain
+        attached and MUST NOT be lost when displaying or aggregating connections.
+
   edge:
     from: "<element-id | artifact-id>"
     to: "<element-id | artifact-id>"

package/references/product-development/type-guidance.kbp.yaml

@@ -1,8 +1,8 @@
 guidance:
   id: product-development-guidance
   label: Product development — type guidance
-  version: 0.5
-  conforms_to: kbp/0.5
+  version: 0.7
+  conforms_to: kbp/0.7
   guides: product-development
 
 guidance_kinds:
@@ -143,8 +143,8 @@ sources:
     url: "https://github.com/google-labs-code/design.md/blob/main/docs/spec.md"
     checked: 2026-08-18
   dtcg:
-    cite: "Design Tokens Community Group — Design Tokens Format Module 2025.10, a draft marked 'Do not implement this version'"
-    url: "https://www.designtokens.org/TR/drafts/format/"
+    cite: "Design Tokens Community Group — Design Tokens Format Module 2025.10, published version"
+    url: "https://www.designtokens.org/TR/2025.10/format/"
     checked: 2026-08-18
   hig:
     cite: "Apple — Human Interface Guidelines, the Foundations topic list. Client-rendered; read through a headless browser"
@@ -178,7 +178,7 @@ sources:
     cite: "GitLab Pajamas — a standing public brand guideline set"
     url: "https://design.gitlab.com/"
   scenario-walkthrough:
-    cite: "Alan Cooper et al. — About Face, on the key path scenario"
+    cite: "Gardenia Durian — How to write a useful scenario walkthrough (Pivotal Labs, 2016)"
     url: "https://medium.com/product-labs/how-to-write-a-useful-scenario-walkthrough-f48bf40b1b69"
   adr:
     cite: "Michael Nygard — Documenting Architecture Decisions (2011); templates at adr.github.io"
@@ -336,7 +336,7 @@ elements:
     - { kind: convention, source: outcome,
         claim: "The name stays singular: an effort steers by a scope-named product outcome — a behavioural measure within its own influence that drives the star — and sets its success criteria on that." }
     - { kind: convention, source: omtm,
-        claim: "The stage-scoped One Metric That Matters is the same move under another name — team- and period-scoped, complementing a durable star rather than competing with it." }
+        claim: "A North Star tracks customer value within its framework. The One Metric That Matters identifies the current metric to focus on and may change with the business stage or bottleneck; the names are not interchangeable." }
     - { kind: convention, source: ns-checklist,
         claim: "Represents vision and strategy without being either — a strong metric statement lets a reader recover both at a high level." }
     - { kind: pitfall, source: asserted,
@@ -369,8 +369,8 @@ elements:
         claim: "'Improve X' invites post-hoc rationalisation. Set a threshold and a measurement date." }
     - { kind: heuristic, source: asserted,
         claim: "What a PRD loosely calls a launch's success metrics is this element. A key result is this element wearing OKR vocabulary — a time-boxed threshold, typically on an input metric." }
-    - { kind: convention, source: cascade,
-        claim: "The initiative inherits its space's star and guardrails by reference and authors its own commitments. The reference cascades; the goals do not." }
+    - { kind: heuristic, source: asserted,
+        claim: "KB recommendation: inherit shared metrics by reference and state local commitments explicitly." }
 
   market-sizing:
     - { kind: heuristic, source: asserted,
@@ -434,7 +434,7 @@ elements:
 
   risks-and-assumptions:
     - { kind: heuristic, source: asserted,
-        claim: "An assumption is believed true but unvalidated; a risk could go wrong. Each gets impact times likelihood and a response — mitigate, accept, watch." }
+        claim: "For an assumption, state what is being relied on and how it will be checked. For a risk, state what could happen, its significance, and the response." }
     - { kind: convention, source: premortem,
         claim: "Pre-mortem sorting — real tigers versus paper tigers — resists both alarmism and optimism." }
     - { kind: convention, source: rust-rfc,
@@ -498,9 +498,9 @@ elements:
 
   alternatives-considered:
     - { kind: convention, source: rust-rfc,
-        claim: "Standard in RFCs, decision documents and decision records. This element holds the roads not taken." }
-    - { kind: boundary, source: adr,
-        claim: "The winner lives in Decision. Folding the chosen option in here structurally breaks that element." }
+        claim: "Standard in RFCs, decision documents and decision records. Describe the options considered, including the chosen option." }
+    - { kind: boundary, source: madr,
+        claim: "Describe and compare the options here, including the chosen option. Decision records the commitment and why it was chosen." }
     - { kind: convention, source: y-statement,
         claim: "Naming the rejected options is grammatically obligatory in the Y-statement form — 'and neglected …' — not an optional courtesy to the reader." }
     - { kind: convention, source: spade,
@@ -540,19 +540,19 @@ elements:
     - { kind: boundary, source: asserted,
         claim: "Distinct from Risks & Assumptions: a consequence is accepted and expected, a risk is uncertain. Filing a known cost as a risk hides that someone chose it." }
     - { kind: empty, source: asserted,
-        claim: "Honestly empty means the option genuinely dominated on every criterion — rare enough that it is worth saying so explicitly." }
+        claim: "An option can outperform every alternative and still have consequences. Distinguish none identified from not assessed; neither follows from the option dominating the comparison." }
 
   reversal-condition:
     - { kind: heuristic, source: asserted,
         claim: "An observable condition, not a review date: what would have to be seen for this to stop holding. 'Revisit in six months' is a calendar entry; 'if median latency exceeds the budget for two consecutive quarters' is a condition." }
-    - { kind: convention, source: madr,
-        claim: "Where the decision can be checked mechanically, name the check — a fitness function, a test, a review step — so that compliance is observable rather than assumed." }
+    - { kind: boundary, source: asserted,
+        claim: "Checking that a decision was implemented and deciding whether it should change are different activities. Implementation compliance is not itself a condition for reconsideration." }
     - { kind: convention, source: azure-waf,
-        claim: "A decision taken at low confidence should say so, because recorded low confidence is what makes later reconsideration legitimate rather than second-guessing." }
+        claim: "Record uncertainty that may warrant revisiting the decision. New evidence or changed circumstances can justify reconsideration regardless of its original confidence." }
     - { kind: boundary, source: asserted,
         claim: "Distinct from Risks & Assumptions: a failing assumption is one trigger among several. A better alternative appearing, a constraint lifting, or an authority changing reopen the decision without any assumption having failed." }
     - { kind: empty, source: asserted,
-        claim: "Honestly empty means nothing observable would reopen it — which is a strong claim about an irreversible commitment, and should read as one." }
+        claim: "State what would warrant reconsideration. If no trigger has been identified, say so; this does not establish that the commitment is irreversible." }
 
   prior-art:
     - { kind: convention, source: rust-rfc,
@@ -606,7 +606,7 @@ elements:
     - { kind: heuristic, source: asserted,
         claim: "The element holds the model, not the instances. Bulk enumeration beyond what makes the model legible is product content, not documentation." }
     - { kind: heuristic, source: asserted,
-        claim: "Takes its host's phase — behaviour-defining sets in a design document, schema-bound catalogues in an architecture overview. Promoted to a standalone document it would fail the one-phase rule." }
+        claim: "Canonical Model is assigned to Architecture in this universe. Referencing it from another artifact does not change its phase." }
 
 artifacts:
 
@@ -650,7 +650,7 @@ artifacts:
     - { kind: boundary, source: asserted,
         claim: "The brand book's strategy half — values, personality, purpose — belongs to Product Vision and Positioning Statement by the split rule. This type takes only the rules for expressing it, visual and verbal alike." }
     - { kind: convention, source: design-md,
-        claim: "A machine-readable form of this type now exists, written for whoever renders the identity — a person or a coding agent alike. It carries the visual rules and no writing rules." }
+        claim: "DESIGN.md represents visual design-system rules. It can supply the visual portion of a brand guide; it does not represent its verbal rules." }
     - { kind: pitfall, source: asserted,
         claim: "Instructions for revising the document are not part of the document. That is a process, and it belongs wherever the process is owned." }
     - { kind: refresh, source: asserted,
@@ -658,7 +658,7 @@ artifacts:
 
   scenario-walkthrough:
     - { kind: convention, source: scenario-walkthrough,
-        claim: "The key path scenario walks the primary pathways as user actions with product responses, deliberately concrete where a context scenario stays high-level." }
+        claim: "A useful scenario walkthrough follows a person pursuing a goal. It can help a team determine what the product should do early, without prescribing detailed interface design." }
     - { kind: pitfall, source: asserted,
         claim: "Distinct from three unrelated walkthroughs: the live usability exercise, ATAM's quality-attribute review, and the inspection meeting." }
 
@@ -672,7 +672,7 @@ artifacts:
 
   system-context-diagram:
     - { kind: convention, source: c4,
-        claim: "C4 level 1 exactly. Component detail inside it is the split signal toward the Architecture Overview." }
+        claim: "Show people and external systems at C4 level 1. Use the Architecture Overview for internal containers and their interactions at level 2. C4 component-level detail is a further level." }
 
   decision-brief:
     - { kind: convention, source: daci,
@@ -708,4 +708,4 @@ artifacts:
     - { kind: boundary, source: adr-boundary,
         claim: "A decision record that grows into a design guide has stopped being a decision record." }
     - { kind: refresh, source: asserted,
-        claim: "It goes stale when its reversal condition is met, not on a schedule — and a record whose reversal condition can no longer be evaluated is already stale." }
+        claim: "Reassess the decision when a reconsideration trigger occurs or its supporting circumstances change. If a trigger cannot be evaluated, establish what evidence is missing. If the decision changes, create a superseding record and retain the original." }

package/references/product-development/universe.kbp.yaml

@@ -1,8 +1,8 @@
 universe:
   id: product-development
   label: Product development
-  version: 0.5
-  conforms_to: kbp/0.5
+  version: 0.8
+  conforms_to: kbp/0.7
   ordering_frame: phase
   overview:
     covers: >
@@ -93,14 +93,44 @@ empty_composition:
   when: { time-separation: [none], reversibility: [reversible] }
 
 relation_kinds:
-  - { id: presupposes,      ordered: true }
-  - { id: distinct-from,    ordered: false }
-  - { id: counterweight-to, ordered: false }
-  - { id: feeds,            ordered: true }
-  - { id: split-signal,     ordered: true }
-  - { id: descendant-of,    ordered: true }
-  - { id: requires,         ordered: true }
-  - { id: nests-under,      ordered: true }
+  - id: presupposes
+    ordered: true
+    phrasing:
+      forward: Context from
+      reverse: Context for
+  - id: distinct-from
+    ordered: false
+    phrasing:
+      forward: Not interchangeable with
+  - id: counterweight-to
+    ordered: false
+    phrasing:
+      forward: Balances
+  - id: feeds
+    ordered: true
+    phrasing:
+      forward: Can inform
+      reverse: Can be informed by
+  - id: split-signal
+    ordered: true
+    phrasing:
+      forward: May need detail moved to
+      reverse: May receive detail moved from
+  - id: descendant-of
+    ordered: true
+    phrasing:
+      forward: Adapted from
+      reverse: Adapted into
+  - id: requires
+    ordered: true
+    phrasing:
+      forward: Needs
+      reverse: Needed by
+  - id: nests-under
+    ordered: true
+    phrasing:
+      forward: Within the scope of
+      reverse: Broader scope for
 
 elements:
 
@@ -172,7 +202,7 @@ artifacts:
     disabled_when: { uptake: [given] }
     composition:
       core: [product-vision, customer-segments, value-proposition, cost-structure, trade-offs,
-             north-star-metric, growth-mechanism, capabilities, unfair-advantage]
+             { element: north-star-metric, mode: links }, growth-mechanism, capabilities, unfair-advantage]
       situational: [positioning-statement, input-metrics, revenue-streams, case-for-change]
 
   - id: business-model-canvas
@@ -202,7 +232,7 @@ artifacts:
     disabled_when: { uptake: [given, chosen] }
     composition:
       core: [product-vision, customer-segments, value-proposition, cost-structure, trade-offs,
-             north-star-metric, growth-mechanism, capabilities, unfair-advantage, revenue-streams]
+             { element: north-star-metric, mode: links }, growth-mechanism, capabilities, unfair-advantage, revenue-streams]
       situational: [positioning-statement, input-metrics]
 
   - id: swot-analysis
@@ -353,15 +383,6 @@ artifacts:
         - { element: decision-criteria, mode: links, when: { authority: [approve, statutory] } }
       situational: [constraints, prior-art, open-questions]
 
-  - id: working-note
-    code: axh9h
-    enablement: { action: "resume your own work after a gap without re-deriving it", actor: the author at a later time, timing: across sessions }
-    alias: { kind: none, reason: no-aligned-form }
-    disabled_when: { time-separation: [none] }
-    composition:
-      core: [constraints, scope-in-out, open-questions]
-      situational: [trade-offs, as-built-survey, success-criteria]
-
 relations:
 
   - { from: value-proposition, to: case-for-change, kind: distinct-from }
@@ -392,8 +413,8 @@ relations:
   - { from: north-star-metric, to: input-metrics, kind: requires }
   - { from: guardrail-health-metrics, to: input-metrics, kind: counterweight-to }
   - { from: measurement-protocol, to: hypothesis, kind: presupposes }
-  - { from: external-opportunities-threats, to: macro-environment-factors, kind: feeds }
-  - { from: external-opportunities-threats, to: competitor-profile, kind: feeds }
+  - { from: macro-environment-factors, to: external-opportunities-threats, kind: feeds }
+  - { from: competitor-profile, to: external-opportunities-threats, kind: feeds }
   - { from: as-built-survey, to: sequence-and-foreclosure, kind: feeds }
   - { from: stepwise-trace, to: data-flows-and-integrations, kind: split-signal }
   - { from: product-vision, to: product-vision, kind: nests-under, legality: permitted }