@knowledge-bus/opencode 0.5.0 → 0.8.0

package/runtime/explorer-viewer.json

@@ -0,0 +1,6 @@
+{
+  "id": "@knowledge-bus/explorer",
+  "version": "0.1.0",
+  "digest": "sha256:9c18839590e8974c94c87a51d15914619745a82a62e36266c3c0ce1662e669f8",
+  "bytes": 263859
+}

package/runtime/kbp.py

@@ -49,6 +49,8 @@ def command(arguments, runtime=None, environ=None):
         raise ValueError("The runtime cache must be outside the installed plugin.")
     env["UV_CACHE_DIR"] = str(cache)
     env["UV_PYTHON_DOWNLOADS"] = "never"
+    env["UV_OFFLINE"] = "1"
+    env["UV_NO_INDEX"] = "1"
     env["PYTHONDONTWRITEBYTECODE"] = "1"
     for key in (
         "UV_PROJECT_ENVIRONMENT",
@@ -60,11 +62,29 @@ def command(arguments, runtime=None, environ=None):
         "VIRTUAL_ENV",
         "PYTHONPATH",
         "PYTHONHOME",
+        "KNOWLEDGE_BUS_EXPLORER_BUNDLE",
+        "KNOWLEDGE_BUS_EXPLORER_BUNDLE_MANIFEST",
     ):
         env.pop(key, None)
+    viewer = runtime / "explorer-viewer.js"
+    viewer_manifest = runtime / "explorer-viewer.json"
+    if viewer.is_file() or viewer_manifest.is_file():
+        if not viewer.is_file() or not viewer_manifest.is_file():
+            raise ValueError("Bundled Explorer viewer is incomplete.")
+        declared = json.loads(viewer_manifest.read_text())
+        actual = "sha256:" + hashlib.sha256(viewer.read_bytes()).hexdigest()
+        if (
+            declared.get("digest") != actual
+            or declared.get("bytes") != viewer.stat().st_size
+        ):
+            raise ValueError("Bundled Explorer viewer does not match its manifest.")
+        env["KNOWLEDGE_BUS_EXPLORER_BUNDLE"] = str(viewer)
+        env["KNOWLEDGE_BUS_EXPLORER_BUNDLE_MANIFEST"] = str(viewer_manifest)
     args = [
         uv,
         "run",
+        "--offline",
+        "--no-index",
         "--no-project",
         "--no-config",
         "--isolated",

package/runtime/requirements.json

@@ -1,9 +1,7 @@
 {
-  "version": "0.5.0",
-  "wheel": "knowledge_bus-0.5.0-py3-none-any.whl",
+  "version": "0.8.0",
+  "wheel": "knowledge_bus-0.8.0-py3-none-any.whl",
   "requires_python": ">=3.14",
-  "sha256": "9334bb61f23ba979e1a8466cce06a37388d71d38578870f9a8c8dff00c13cfc8",
-  "dependencies": [
-    "PyYAML==6.0.3"
-  ]
+  "sha256": "93563734c693aff63a44edda8bd941d45ce7a3388e6055045de3f8cd792727b9",
+  "dependencies": []
 }

package/skills/kb-check/SKILL.md

@@ -15,7 +15,7 @@ description: Validate Knowledge Bus definitions and guidance after edits, and ex
 
 - **3. Interpret.** Every refusal names its clause. Translate each into the edit it calls for; see [Checker for Agent Workflows](../../references/agent-runtime.md) for the clause families.
 
-- **4. Report.** Per-file pass/fail, then refusals grouped by fix, not by file.
+- **4. Report.** Per-file pass/fail, then refusals grouped by fix, not by file. If Explorer inspection was also requested, report renderability separately.
 
 ## Common failures
 

package/skills/kb-evolve/SKILL.md

@@ -7,10 +7,11 @@ description: Add or re-examine document types in a Knowledge Bus universe, groun
 
 **Purpose — add a type the spec does not carry, or deepen one it already declares, so that every declaration is earned by evidence, every refusal is recorded with its reason, and the framework stays cohesive rather than locally patched.**
 
-Two entry points share one spine. Run the spine; take the branch that applies.
+Run the shared spine through the path that applies.
 
 - **Path A — new type.** A form exists in the world and the spec does not carry it. Governing question: *does it enable something no declared type enables?*
 - **Path B — re-evaluation.** A declared type is about to become load-bearing and its basis is unexamined. Governing question: *what in this type is inherited rather than earned?*
+- **Path C — greenfield or adaptation.** Start from what the user needs to understand, decide, or do. External references are optional.
 
 ## Knowledge Bus Directory
 
@@ -30,10 +31,11 @@ Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). U
 - **1. State the suspicion before searching.** Write down what you expect to find wrong, then go looking. This is what stops a first-hit lineage from being confirmed rather than tested.
   - **A:** name the form and the gap it claims to fill.
   - **B:** name what looks inherited — a word in the id, a single-tradition guidance base, a question doing more than one job, an enablement promising something no element delivers.
+  - **C:** name the intended decision, action, or understanding and the smallest suspected set of questions.
 
 - **2. Group candidate sources by enablement, not by discipline.** Families are "what does this let someone *do*" — decide, know-what-stands, calibrate, follow-an-argument. Discipline groupings smuggle in the lineage you are trying to test.
 
-- **3. Fetch primary sources. Record every failed or degraded fetch.** Paywalled, rescinded, image-only, redirected — say so, and carry the caveat into the citation itself rather than leaving it for a reader to discover.
+- **3. Gather proportionate evidence.** Prefer primary sources for reference-led work and record access limitations. For greenfield work, use the user's intent and reviewed local examples without inventing a lineage.
 
 - **4. Run the artifact test per family.** Identity is `(action, actor)`; add timing to break ties.
   - **A:** if the enablement duplicates a declared type's, fold the form in as an alias — do not add a row.

package/skills/kb-explore/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: kb-explore
+description: Inspect a Knowledge Bus universe and optionally create or open its offline Explorer.
+---
+
+# Explore a Universe
+
+Use this procedure to understand or present declared Knowledge Bus definitions. Explorer is an optional read-only consumer; it does not author definitions or decide whether their contents are true, useful, approved, or applicable to a situation.
+
+## Select and inspect
+
+Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). An explicit universe file, knowledge-base folder, or its `.knowledge-bus/` folder takes precedence; otherwise use the nearest `.knowledge-bus/` and never fall through an empty nearer scope. Run the bundled command described in [Checker for Agent Workflows](../../references/agent-runtime.md):
+
+```sh
+python3 /absolute/runtime/kbp.py --inspect /absolute/target/.knowledge-bus/
+```
+
+Inspection writes nothing. A sole universe may be selected automatically. If the scope contains several, list the candidates and ask the user to select an id or universe file; never choose by filename or sort order. Explain the universe through its questions, artifact purposes, relationships, guidance, and presentation marks. Report conformance and renderability separately.
+
+## Optional static artifact
+
+Before writing, tell the user the proposed destination. The conventional local path is `.knowledge-bus/explorer/<universe-id>/`, but generation always receives an explicit destination:
+
+```sh
+python3 /absolute/runtime/kbp.py --explore --universe <id> --output /absolute/destination /absolute/target/.knowledge-bus/
+```
+
+Do not replace an existing destination unless the user asks; then add `--replace`. Before recommending replacement, compare the receipt with the current inspection and viewer. Refresh when the definitions, guidance, marks, viewer, or requested presentation changed. A package release alone is not a reason to refresh.
+
+Generation uses bundled files and works offline. Open `index.html` only when requested or useful. Users can export SVG from the viewer; automated export remains contributor and release tooling.
+
+If visualization is unavailable, provide the inspected model or a concise text explanation. Never change definitions, evaluate context, reconstruct an institution, promote descriptive material into an authorized state, or silently ignore invalid or mismatched inputs.

package/skills/kb-ingest/SKILL.md

@@ -24,16 +24,12 @@ description: Map existing notes or documents into Knowledge Bus definitions and
   convention. Inspect that directory if it already exists; the domain phrase is proposed after the survey and confirmed, never requested cold.
 
 - **2. Survey before reading.** Inventory files, dates, and formats; report counts to the user before any deep read.
-  Three staleness marks: **contradicted** (a newer source disputes it — mechanical), **unconfirmed**
+  Three staleness marks: **contradicted** (sources disagree), **unconfirmed**
   (older than the corpus's age threshold, nothing disputes it), **confirmed** (cleared during the interview).
   Confirmation questions come batched and informed — reason through the whole survey first so the user rules
   on genuine uncertainty, not on what the corpus already settles.
 
-- **3. Position the domain, then choose the spec.** Locate the starter using [Checker for Agent Workflows](../../references/agent-runtime.md). Reason over the folder
-  and whatever the user supplied, clarifying unclear questions by probing what answering each would enable and checking for overlap,
-  then interview to place the domain against the product-agnostic built-in: how regulated or commercial
-  versus DIY, and where the abstraction layer sits — industry, company, product, or feature. Adopt, trim,
-  or derive follows from that placement; structural changes require the user's review. If `kb-evolve` is installed, offer it; otherwise explain the proposed change and stop before changing the structure.
+- **3. Choose the definitions.** Use supplied definitions when they fit. Treat the bundled starter as an optional reference, not a universal lens. If no set fits, propose an adaptation for review. Structural changes require the user's approval. Use `kb-evolve` when available; otherwise explain the proposed change and stop.
 
 - **4. Extract answers.** Map each document section to a declared question; one answer per question per party and time.
   A collision — two docs answering the same question — is never resolved by recency. The older doc may be the

package/skills/kb-uncover-decision/SKILL.md

@@ -15,7 +15,7 @@ Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). U
 
 - **Past tense throughout.** What was live, not what is sensible now.
 - **Reconstruction is flagged as reconstruction.** Memory is not evidence.
-- **A decision with no reversal condition is not fully recovered.**
+- **Do not fill missing history.**
 
 ## The flow
 
@@ -27,6 +27,6 @@ Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). U
 
 - **4. Recover the binding constraints.** What ruled options out, in force at the time.
 
-- **5. Name the reversal condition.** What changing would reopen this.
+- **5. Seek the reversal condition.** Record it when supported; otherwise mark it unknown.
 
-- **6. File as answers** against declared questions; flag what stayed ambiguous.
+- **6. File as answers** against declared questions; label fact, recollection, reconstruction, and missing evidence. Flag what stayed ambiguous.

package/skills/kb-uncover-question/SKILL.md

@@ -22,7 +22,7 @@ Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). U
 
 ## The loop
 
-Every round runs the same shape. Loop until a round changes nothing.
+Repeat only while a follow-up can resolve stated uncertainty. Stop when the tests settle the candidate or when resolution requires missing evidence or another person.
 
 - **1. Reason first.** Re-read everything held — the material, prior answers, every declared question. Draft what the next batch must uncover; discard whatever the record already settles.
 
@@ -30,6 +30,6 @@ Every round runs the same shape. Loop until a round changes nothing.
 
 - **3. Reflect and test.** Against the answers, run the tests: an enablement a declared question already covers is a collision — rule *sharpen existing / new / refused*; two jobs is a split; a candidate with no honest empty answer is not load-bearing.
 
-- **4. Follow up or converge.** Where a test left ambiguity, ask a follow-up batch in the same sitting. A round that changes nothing ends the loop.
+- **4. Follow up or stop.** Ask another batch only when it can resolve stated ambiguity. A round that changes nothing ends the loop; unresolved uncertainty stays unresolved.
 
 - **5. Declare.** Freeze the wording last. Mint a code using [Checker for Agent Workflows](../../references/agent-runtime.md); record every refusal with its reason.