v3.7 Pass 3a: fixes from Pass 4 critical roast

styk-tv · styk-tv · commit f261b587e72e · 2026-04-24T20:45:02.000+01:00
Roaster (read-only subagent) flagged contradictions against established
v3.7 truths. Corrections:

- ontology-model.md class tree: remove stale ckp:EdgeKernel and
  ckp:WssHubKernel entries (classes removed in Pass 1); add
  ckp:AgentKernel for completeness.
- compliance.md Identity check-category no longer mentions
  "version/serving" -- replaced with "version pinned in .ckproject"
  to match the retired-serving.json narrative.
- conformance.md: added CRD tip naming both custom resources explicitly
  (ConceptKernel = conceptkernel.org/v1, CKProject = ck.tech.games/v1)
  instead of referring to an unnamed "Kubernetes CRD".
- crd.md spec.type enum description expanded to explain what an `agent`
  kernel type implies (streaming, persona templates).
- evolution.md "all LLM calls through CLI" MUST tightened to also allow
  claude_agent_sdk -- matches extends.md architecture that uses the SDK
  directly, not CLI re-routing.
- project.md: clarified that "frozen deployment" applies to CK and TOOL
  organs; DATA drifts at runtime by design -- links to Pin Semantics.
- graph.md + changelog.md: corrected the .ttl.template mechanism claim.
  RDF loaders don't skip by extension semantics; actual mechanism is
  the *.ttl glob pattern not matching the .ttl.template suffix.

Build clean.

Still deferred from roast (need design decisions):
- extends.md circular-EXTENDS gap (spec-acknowledged)
- consensus.md ontology_update semantic validation gap
- Several MUST requirements could cite enforcement mechanism explicitly
- Marketing/fluff passages (opinionated tone changes)
diff --git a/docs/v3.7/changelog.md b/docs/v3.7/changelog.md
@@ -124,7 +124,7 @@ All notable changes in the development increments that compose v3.7. Each versio
 - Loaded 10 CKP v3.5-alpha6 Turtle modules into `/ckp` dataset on Jena Fuseki
 - 2,797 triples across core, proof, base-instances, kernel-metadata, processes, rbac, relations, self-improvement, shapes, workflow modules
 - SPARQL endpoint live at `jena-fuseki.jena.svc:3030/ckp/sparql`
-- `kernel-entity-template.ttl` renamed to `kernel-entity-template.ttl.template` — it's a scaffolding template with placeholder tokens, not valid Turtle; the new extension signals RDF loaders to skip it (previously caused HTTP 400 from Fuseki)
+- `kernel-entity-template.ttl` renamed to `kernel-entity-template.ttl.template` — it's a scaffolding template with placeholder tokens, not valid Turtle. The new suffix keeps it out of the `*.ttl` glob used by the ontology loader, so Jena Fuseki no longer attempts to parse it (previously returned HTTP 400).
 - 7 of 17 spec-declared modules not yet published as Turtle (instance, action, identity, governance, lifecycle, economic, topology)
 
 ### v3.5.11 -- CK.Consensus Kernel <Badge type="tip" text="DEPLOYED" />
diff --git a/docs/v3.7/compliance.md b/docs/v3.7/compliance.md
@@ -122,7 +122,7 @@ The output shows `{passing_kernels}/{total_kernels}` for each check type. A flee
 
 | Category | Check Types | What It Covers |
 |----------|-------------|----------------|
-| **Identity** | 1, 2, 4, 11 | apiVersion, awakening files, type/governance, version/serving |
+| **Identity** | 1, 2, 4, 11 | apiVersion, awakening files, type/governance, version pinned in `.ckproject` |
 | **Structure** | 3, 6, 7, 9 | Directory layout, processor, web, file integrity |
 | **Edges & NATS** | 5, 12, 17 | Edge validity, NATS topics, edge materialisation |
 | **Ontology** | 14, 15, 18 | Ontology types, instance typing, SHACL validity |
diff --git a/docs/v3.7/conformance.md b/docs/v3.7/conformance.md
@@ -35,6 +35,10 @@ A conformant CKP implementation:
 | 12 | Support all five edge predicates | MUST |
 | 13 | Implement the star topology activation model | MAY |
 
+::: tip CRDs
+The two custom resources published by v3.7 are the **ConceptKernel CRD** (`conceptkernel.org/v1`, shortname `ck`) for per-kernel identity and proof status, and the **CKProject CRD** (`ck.tech.games/v1`, shortname `ckp`) for project-level orchestration. Both schemas are in [Custom Resource Definitions](./crd).
+:::
+
 ## Conformance Levels
 
 CKP defines two conformance levels. Implementations MUST declare which level they target. Partial conformance (meeting some but not all Core requirements) is **non-conformant**.
diff --git a/docs/v3.7/crd.md b/docs/v3.7/crd.md
@@ -47,7 +47,7 @@ spec:
                 type:
                   type: string
                   enum: ["node:hot", "node:cold", "inline", "static", "agent"]
-                  description: "Kernel deployment type per CKP type registry"
+                  description: "Kernel deployment type per CKP type registry. `agent` kernels support long-running conversational sessions with LLM inference, streaming via stream.{kernel}, and persona templates from data/personas/ (see extends.md and streaming.md)."
                 governance:
                   type: string
                   enum: ["STRICT", "RELAXED", "AUTONOMOUS"]
diff --git a/docs/v3.7/evolution.md b/docs/v3.7/evolution.md
@@ -177,5 +177,5 @@ Persona templates are stored in the target kernel's DATA loop (writable), allowi
 | Memory updates (DATA loop) MAY be written directly by agents | PERMITTED |
 | Model selection MUST follow the three-level precedence chain | REQUIRED |
 | Edge-level constraints MUST override persona-level settings | REQUIRED |
-| All LLM calls MUST go through Claude Code CLI, not direct API | REQUIRED |
+| All LLM calls MUST go through Claude Code CLI (`claude -p`) or the Claude Code SDK (`claude_agent_sdk`); direct API calls with self-managed API keys are PROHIBITED | REQUIRED |
 | Structured output SHOULD use `--json-schema` for validation | RECOMMENDED |
diff --git a/docs/v3.7/graph.md b/docs/v3.7/graph.md
@@ -55,7 +55,7 @@ Seven modules declared in the spec are not yet published as Turtle:
 | `topology.ttl` | Fleet topology, namespace mapping, volume layout | Docs stub only |
 
 ::: info Template Exclusion
-`kernel-entity-template.ttl.template` is intentionally excluded from the Turtle publication set. It is a scaffolding template that contains placeholder tokens (`{KERNEL_NAME}`, `{ROLES}`, etc.) and is therefore not valid Turtle. The `.ttl.template` extension signals to Jena Fuseki and other RDF loaders to skip it; per-kernel entity triples are produced at kernel creation time and published per-kernel rather than consumed from this template.
+`kernel-entity-template.ttl.template` is intentionally excluded from the Turtle publication set. It is a scaffolding template that contains placeholder tokens (`{KERNEL_NAME}`, `{ROLES}`, etc.) and is therefore not valid Turtle. The `.ttl.template` suffix keeps it out of the `*.ttl` glob used by the materialisation loader (RDF loaders like Jena Fuseki match by glob, not by extension semantics — the rename ensures the file simply is not fed to the parser). Per-kernel entity triples are produced at kernel creation time and published per-kernel rather than consumed from this template.
 :::
 
 ## Published Triples
diff --git a/docs/v3.7/ontology-model.md b/docs/v3.7/ontology-model.md
@@ -230,9 +230,8 @@ bfo:Entity
 |   |   |   |   +-- ckp:ColdKernel                             [core.ttl]
 |   |   |   |   +-- ckp:InlineKernel                           [core.ttl]
 |   |   |   |   +-- ckp:StaticKernel                           [core.ttl]
-|   |   |   |   +-- ckp:EdgeKernel                             [core.ttl]
+|   |   |   |   +-- ckp:AgentKernel                            [core.ttl]
 |   |   |   |   +-- ckp:ConsensusKernel                        [core.ttl]
-|   |   |   |   +-- ckp:WssHubKernel                           [core.ttl]
 |   |   |   |   +-- ckp:SystemKernel                           [kernel-metadata.ttl]
 |   |   |   |   +-- ckp:ApplicationKernel                      [kernel-metadata.ttl]
 |   |   |   |   +-- ckp:UIKernel                               [kernel-metadata.ttl]
diff --git a/docs/v3.7/project.md b/docs/v3.7/project.md
@@ -24,7 +24,7 @@ CK.Project is a `static` kernel because it holds only declarations; it has no pr
 
 CK.Project's DATA organ holds one **`.ckproject` manifest** per tracked project, keyed by the project's hostname. The hostname is the project's identity -- it determines DNS routing, namespace naming, and filer path prefixes.
 
-The `.ckproject` manifest is the authoritative record of the project's frozen deployment. [CK.Operator](./operator) reads it to materialize kernels at their pinned versions.
+The `.ckproject` manifest is the authoritative record of the project's frozen deployment *intent* -- which kernels, which versions, which commits. [CK.Operator](./operator) reads it to materialize kernels at their pinned versions. Note that "frozen" applies to the CK and TOOL organs (ReadOnlyMany at runtime); the DATA organ still drifts at runtime by design -- see [Pin Semantics](#pin-semantics-pins-ck-pins-tool-pins-data) below for the asymmetry.
 
 **Canonical path** (inside CK.Project's DATA organ on the SeaweedFS filer):
 
