TASKS-CRITICAL closeout: C1, C2, C3 — relationship kind, template kind, template scoping

ARCHITECTURE.md

@@ -64,7 +64,7 @@ prevents transactional updates spanning both endpoints.
 ```erlang
 -record(node, {
   nref,                   %% integer() — primary key
-  kind,                   %% category | attribute | class | instance
+  kind,                   %% category | attribute | class | instance | template
   parent,                 %% integer() | undefined  (undefined = root only)
   attribute_value_pairs   %% [#{attribute => Nref, value => term()}]
 }).
@@ -97,7 +97,7 @@ Five top-level categories are pre-assigned at bootstrap:
 5  └── Projects    (organisational anchor for project databases — see §6)
 ```
 
-The full 30-node BFS scaffold (nrefs 1–30) is documented in
+The full 31-node BFS scaffold (nrefs 1–31) is documented in
 `apps/graphdb/priv/bootstrap.terms`. Code that needs specific nrefs uses
 the constants defined as macros in the worker that owns them
 (`graphdb_attr`, `graphdb_class`, `graphdb_instance`).
@@ -109,6 +109,7 @@ the constants defined as macros in the worker that owns them
 ```erlang
 -record(relationship, {
   id,               %% integer() — primary key
+  kind,             %% taxonomy | composition | connection | instantiation
   source_nref,      %% integer() — arc origin
   characterization, %% integer() — arc label (an attribute nref)
   target_nref,      %% integer() — arc target
@@ -132,17 +133,13 @@ provenance, confidence, weights, validity time frames, flags. Per
 is part of the connection's identity for ASSOCIATE-type arcs, but does
 not participate in graph traversal by default.
 
-### Pending schema additions
+### Connection arcs and the `Template` AVP
 
-One field and one AVP convention are required by the spec but not yet
-on the record. See §10 and `TASKS-CRITICAL.md`:
-
-- `kind` — explicit relationship type (`taxonomy | composition |
-  connection | instantiation`).
-- `Template` AVP — required on `kind = connection` arcs, forbidden
-  elsewhere; the AVP attribute itself is bootstrap-seeded as nref 31.
-
-Both must land before the database holds live data.
+Every `kind = connection` arc carries a `Template` AVP — `#{attribute
+=> 31, value => TemplateNref}` — that scopes the connection's
+semantic context. The AVP attribute is bootstrap-seeded at nref 31;
+it is forbidden on relationships of any other kind. See §7 and
+`graphdb_instance:add_relationship/4,5`.
 
 ---
 
@@ -318,19 +315,8 @@ multi-class membership is silently disambiguated by Mnesia ordering
 
 ## 10. Open Architectural Questions
 
-Pending architectural decisions and required additions. Each item has a
-detailed task in the severity-grouped task files.
-
-### Pending schema additions
-
-| Schema element              | Purpose                                                                                                                                                    | Spec reference                  |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `relationship.kind`         | Explicit type: `taxonomy \| composition \| connection \| instantiation`                                                                                    | §5 — `TASKS-CRITICAL.md` C1     |
-| `node.kind` adds `template` | Fifth peer to category/attribute/class/instance; templates are nodes whose compositional parent is a class                                                 | §3, §7 — `TASKS-CRITICAL.md` C2 |
-| `Template` relationship AVP | Bootstrap-seeded attribute (nref 31); required on `kind = connection` arcs, forbidden elsewhere; per-class default template auto-created at class creation | §5, §7 — `TASKS-CRITICAL.md` C3 |
-
-All three must land before any database ships with live data — schema
-migration on populated Mnesia tables is otherwise required.
+Pending architectural decisions. Each item has a detailed task in the
+severity-grouped task files.
 
 ### Multi-inheritance representation
 
@@ -341,14 +327,6 @@ relationships table only. The `graphdb_class` ancestor walk and
 `graphdb_instance.resolve_from_class` need to traverse via arcs rather
 than the single parent field. See `TASKS-HIGH.md` H3, H4, H5.
 
-### Templates
-
-Templates (spec §7) are active concept nodes that scope connections.
-Representation choice is open — 5th node `kind = template`, or
-`kind = class` with `is_template = true` AVP. Required for §13 query
-filtering and §11 connection-pattern learning. See `TASKS-MEDIUM.md`
-M7.
-
 ### Multilingual storage
 
 Names are currently raw Erlang strings on every node. Spec §15 requires

CLAUDE.md

@@ -120,7 +120,7 @@ This database is an implementation of the knowledge graph model described in
 
 | Concept                     | Erlang mapping                                                                                                                                               |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Node / Concept**          | A record identified by an Nref (positive integer); `kind` is one of `category \| attribute \| class \| instance`                                             |
+| **Node / Concept**          | A record identified by an Nref (positive integer); `kind` is one of `category \| attribute \| class \| instance \| template`                                 |
 | **Category Node**           | Permanent top-level organisational scaffold; forms the skeleton of the entire graph; **bootstrap-only** — cannot be created, modified, or deleted at runtime |
 | **Instance Node**           | Concrete entity: has a name attribute, class membership, compositional parent, and relationships                                                             |
 | **Class Node**              | Type/schema: has a class name attribute, instance name attribute, and qualifying characteristics                                                             |
@@ -137,15 +137,15 @@ Two database roles:
 | **Ontology**                 | All category, attribute, class, and language nodes; bootstrap scaffold; arc label definitions | Category nodes: immutable (bootstrap-only). All other nodes grow freely at runtime. |
 | **Project (instance space)** | Instance nodes and their relationships; one database per project                              | Fully mutable at runtime                                                            |
 
-The environment is shared across all projects. Only bootstrap nrefs (1–30) and a small number of explicitly seeded runtime nrefs (e.g., `target_kind`) are referenced by nref constant in code — all other runtime-added nodes are treated generically.
+The environment is shared across all projects. Only bootstrap nrefs (1–31) and a small number of explicitly seeded runtime nrefs (e.g., `target_kind`) are referenced by nref constant in code — all other runtime-added nodes are treated generically.
 
 nref spaces:
 - **Environment**: bootstrap nrefs 1–30; runtime nrefs 10000+ (protected by `{nref_start, 10000}` in `bootstrap.terms`)
 - **Project**: allocator starts at **1** — no pre-assigned nrefs, no bootstrap file, no floor needed
 
 Cross-database nref resolution: `characterization` and `reciprocal` fields always reference environment nrefs; `target_nref` is routed to environment or project based on the arc label's `target_kind` AVP stored in the environment attribute library.
 
-### Bootstrap Nref Quick-Reference (BFS, nrefs 1–30)
+### Bootstrap Nref Quick-Reference (BFS, nrefs 1–31)
 
 ```
  1  Root (category)
@@ -178,6 +178,7 @@ Cross-database nref resolution: `characterization` and `reciprocal` fields alway
 28      Child  — instance compositional arc label (parent: 16)
 29      Class  — instance→class membership arc (parent: 16)
 30      Instance — class→instances membership arc (parent: 16)
+31      Template — Connection-arc scope AVP marker (parent: 16)
 ```
 
 NameAttrNref quick-reference: category=17, attribute=18, class=19, instance=20
@@ -211,7 +212,7 @@ Every graph node is stored as a Mnesia record:
 ```erlang
 -record(node, {
   nref,                   %% integer() — unique positive integer; primary key
-  kind,                   %% category | attribute | class | instance
+  kind,                   %% category | attribute | class | instance | template
   parent,                 %% integer() | undefined  (undefined = root node only)
   attribute_value_pairs   %% [#{attribute => AttrNref, value => Value}]
 }).

README.md

@@ -16,7 +16,7 @@ underway:
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `nref` subsystem       | Fully implemented (DETS-backed ID allocator with `set_floor/1`)                                                                                    |
 | `dictionary` subsystem | `dictionary_imp` implemented; server stubs not yet wired (Task 7)                                                                                  |
-| `graphdb_bootstrap`    | Fully implemented — Mnesia schema/table creation, bootstrap scaffold loader (30 nodes, 29 relationship pairs)                                      |
+| `graphdb_bootstrap`    | Fully implemented — Mnesia schema/table creation, bootstrap scaffold loader (31 nodes, 30 relationship pairs)                                      |
 | `graphdb_mgr`          | Implemented — bootstrap init, public read API (`get_node`, `get_relationships`), category immutability guard; write operations delegate to workers |
 | `graphdb_attr`         | Fully implemented — attribute library (name, literal, relationship attributes, relationship types)                                                 |
 | `graphdb_class`        | Fully implemented — taxonomic hierarchy, qualifying characteristics, class-level inheritance                                                       |

TASKS-CRITICAL.md

@@ -1,5 +1,17 @@
 # SeerStoneGraphDb — Critical Tasks
 
+**Status: complete.** All three critical tasks have landed on `develop`.
+The next series of work opens with a commit that removes this file and
+cleans up the doc references that pointed at it.
+
+| Task | Status | Landing commit                         |
+| ---- | ------ | -------------------------------------- |
+| C1   | Done   | `6c16e2b` — relationship `kind` field  |
+| C2   | Done   | `9a43187` — node kind atom `template`  |
+| C3   | Done   | (this PR) — Template scoping (a/b/c)   |
+
+---
+
 Schema-level departures from `the-knowledge-network.md`. These change
 the shape of the `relationship` record, the `node` kind atom set, or
 the bootstrap scaffold. Land them before the database has live data —
@@ -18,7 +30,7 @@ adds the template-AVP enforcement rule that depends on both C1 and C2.
 
 ---
 
-## C1. Add `kind` field to the `relationship` record
+## C1. Add `kind` field to the `relationship` record — **DONE** (`6c16e2b`)
 
 **Spec:** §5 — *"Relationships between concept nodes are strictly
 typed. Four types exist: Taxonomy (IS-A), Composition (PART-OF),
@@ -65,7 +77,7 @@ Bootstrap loader assigns `kind` based on the characterization nref
 
 ---
 
-## C2. Add `template` to the node kind atom set
+## C2. Add `template` to the node kind atom set — **DONE** (`9a43187`)
 
 **Spec:** §3 — *"every class, attribute, **rule**, **template**,
 instance, and vocabulary entry is a concept node."* §7 — *"a template
@@ -108,7 +120,7 @@ only makes the kind exist.
 
 ---
 
-## C3. Establish template scoping (AVP + per-class default template)
+## C3. Establish template scoping (AVP + per-class default template) — **DONE** (this PR)
 
 **Spec:** §7 Templates — *"a template is a named semantic context
 defined on a class in the ontology... an active node in the ontology

apps/graphdb/CLAUDE.md

@@ -18,8 +18,8 @@
 | `graphdb_instance.erl`  | Instance/compositional hierarchy gen_server (stub)          |
 | `graphdb_language.erl`  | Query language gen_server (stub)                            |
 
-`apps/graphdb/priv/bootstrap.terms` — Erlang Terms file fully written; contains 30 nodes
-(nrefs 1–30, BFS) and 29 compositional relationship pairs. Loaded at first ontology startup.
+`apps/graphdb/priv/bootstrap.terms` — Erlang Terms file fully written; contains 31 nodes
+(nrefs 1–31, BFS) and 30 compositional relationship pairs. Loaded at first ontology startup.
 
 ## Application Lifecycle
 
@@ -49,7 +49,7 @@ Two database roles operate in parallel:
 The ontology is shared across all projects and is a **living, growing database**: new literal attributes, relationship attributes, and classes are added over time. Only category nodes (nrefs 1–5) are permanently fixed.
 
 nref spaces:
-- **Environment**: bootstrap nrefs 1–30; runtime nrefs 10000+ (floor set by `{nref_start, 10000}` directive in `bootstrap.terms`)
+- **Environment**: bootstrap nrefs 1–31; runtime nrefs 10000+ (floor set by `{nref_start, 10000}` directive in `bootstrap.terms`)
 - **Project**: allocator starts at **1** — no pre-assigned nrefs, no bootstrap file, no floor needed
 
 Cross-database nref resolution: `characterization` and `reciprocal` fields always reference environment nrefs; `target_nref` is routed to environment or project based on the arc label's `target_kind` AVP.
@@ -113,7 +113,7 @@ Every graph node is stored as a Mnesia record:
 ```erlang
 -record(node, {
   nref,                   %% integer() — primary key
-  kind,                   %% category | attribute | class | instance
+  kind,                   %% category | attribute | class | instance | template
   parent,                 %% integer() | undefined  (undefined = root node only)
   attribute_value_pairs   %% [#{attribute => AttrNref, value => term()}]
 }).
@@ -140,7 +140,7 @@ A logical bidirectional edge is two `relationship` rows written atomically (one
 
 ---
 
-## Bootstrap Nref Quick-Reference (BFS, nrefs 1–30)
+## Bootstrap Nref Quick-Reference (BFS, nrefs 1–31)
 
 ```
  1  Root (category)
@@ -173,6 +173,7 @@ A logical bidirectional edge is two `relationship` rows written atomically (one
 28      Child  — instance compositional arc label (parent: 16)
 29      Class  — instance→class membership arc (parent: 16)
 30      Instance — class→instances membership arc (parent: 16)
+31      Template — Connection-arc scope AVP marker (parent: 16)
 ```
 
 NameAttrNref quick-reference: category=17, attribute=18, class=19, instance=20