feat(vocab): governed draft->approved glossary promotion — the 3-method alignment pass (task #13)

CHANGELOG.md

@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Glossary promotion v0.1 — the governed draft→approved alignment pass (task #13, closes the vocabulary lifecycle): `tools/promote_glossary_term.py` promotes a `draft` GlossaryTerm to `approved` ONLY when the 3-method alignment holds as a fail-closed MEET — capture (`ontologyClassRef`) ∧ vector-align (`vectorLink`, pinned to the sovereign nomic/768 space AND reciprocated by the named peer) ∧ implement (`estateBinding` entity/service/action). It recomputes the meet (never trusts a flag), refuses on any missing/non-reciprocal/off-space method (term stays draft, no governance hole), and its approved output PASSES the #250 alignment drift-guard by construction. `validate-glossary-promotion` teeth: promotes on full alignment; refuses missing-implement / non-reciprocal / off-space; promoted output passes the #250 guard.
 - Vocab-currency loop — LIVE dogfood on the estate's own vocab (`make vocab-currency-dogfood`): `tools/dogfood_vocab_currency.py` runs the governed loop over this repo's approved `GlossaryTerm`s (fixed/LSA) vs `specs/*.md` (open/LDA). Today only a handful of terms are approved against the full spec corpus, so the governed loop escalates-human (can't reach currency in its bound), writing real draft `GlossaryTerm` proposals to `build/vocab-currency-proposals/` — the artifacts ontogenesis ingests. Reports the outcome (does not gate on it, exit 0); Markdown-cleaned + generic-word stoplisted so domain terms surface. Enforcement stays on fixtures in `validate-vocab-currency-loop`.
 - Vocab-currency loop — draft-term emission (closes the currency→proposal lifecycle): each remediation step now emits a conformant status:**draft** `GlossaryTerm` artifact (`result.proposedTerms`) for the token it connects — the loop PROPOSES drafts for ontogenesis's 3-method alignment pass and never self-approves (`partOfSpeech`/`alignment` are left for downstream; status stays `draft`). The CI harness now REFUSES any proposed term that doesn't conform to `GlossaryTerm.json` or that isn't status:draft, so the loop can't push malformed or self-approved vocab into the glossary. 6 teeth total.
 - Vocab-currency loop v0.1 — the vocabulary-currency GovernedLoop made LIVE (task #13): `tools/vocab_currency_loop.py` instantiates the merged `GovernedLoop` contract and is governed BY it (reads bound + tolerance + `onNonConvergence` + admission from the document). The approved glossary is the FIXED set (LSA), the corpus token distribution is the OPEN set (LDA), and uncovered probability mass is the currency signal (the LSI drive: new fields that became vocab but aren't connected). Remediation connects the highest-mass uncovered term (a proposed `GlossaryTerm`), strictly decreasing divergence. Fail-closed: runs at most `maxIterations` (never spins); escalates-human (non-zero exit) if it can't reach tolerance within the bound rather than declaring currency; refuses to run unadmitted (no `superconsciousRef`). `validate-vocab-currency-loop` asserts all three teeth (converges / escalates / refuses). Emits `candidateNewVocab` for routing into ontogenesis/prophet-ontology. Dependency-free.

Makefile

@@ -1,6 +1,6 @@
-.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-ingestion-pipeline-examples validate-data-acquisition-examples validate-glossary-alignment-examples validate-data-class-examples validate-table-keys validate-dag-loop validate-vocab-currency-loop vocab-currency-dogfood
+.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-ingestion-pipeline-examples validate-data-acquisition-examples validate-glossary-alignment-examples validate-data-class-examples validate-table-keys validate-dag-loop validate-vocab-currency-loop vocab-currency-dogfood validate-glossary-promotion
 
-validate: validate-data-class-examples validate-glossary-alignment-examples validate-data-acquisition-examples validate-ingestion-pipeline-examples validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-resource-contract validate-table-keys validate-dag-loop validate-vocab-currency-loop
+validate: validate-data-class-examples validate-glossary-alignment-examples validate-data-acquisition-examples validate-ingestion-pipeline-examples validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-resource-contract validate-table-keys validate-dag-loop validate-vocab-currency-loop validate-glossary-promotion
 	@echo "OK: validate"
 
 validate-ingestion-pipeline-examples:
@@ -15,6 +15,10 @@ validate-glossary-alignment-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_glossary_alignment_examples.py
 
+validate-glossary-promotion:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_glossary_promotion.py
+
 validate-table-keys:
 	python3 -m pip install --user jsonschema referencing >/dev/null
 	python3 tools/validate_key_bipartite.py

examples/glossary_promotion.governed_loop.json

@@ -0,0 +1,46 @@
+{
+  "draftTerm": {
+    "id": "urn:srcos:glossary:governed-loop",
+    "type": "GlossaryTerm",
+    "specVersion": "2.0.0",
+    "name": "governed loop",
+    "partOfSpeech": "noun-phrase",
+    "status": "draft",
+    "definition": "A correction loop admissible only when bounded, convergent, fail-closed, and admitted by the superconscious."
+  },
+  "alignment": {
+    "ontologyClassRef": "urn:srcos:ontology-class:governance.GovernedLoop",
+    "vectorLink": {
+      "peerRef": "urn:srcos:glossary:operational-dag",
+      "model": "nomic-ai/nomic-embed-text-v1.5",
+      "dimension": 768,
+      "cosine": 0.69
+    },
+    "estateBinding": {
+      "kind": "entity",
+      "ref": "urn:srcos:schema:GovernedLoop"
+    }
+  },
+  "peer": {
+    "id": "urn:srcos:glossary:operational-dag",
+    "type": "GlossaryTerm",
+    "specVersion": "2.0.0",
+    "name": "operational DAG",
+    "partOfSpeech": "noun-phrase",
+    "status": "approved",
+    "definition": "The operational task graph carrying identity and dependency; it must be acyclic.",
+    "alignment": {
+      "ontologyClassRef": "urn:srcos:ontology-class:governance.OperationalDag",
+      "vectorLink": {
+        "peerRef": "urn:srcos:glossary:governed-loop",
+        "model": "nomic-ai/nomic-embed-text-v1.5",
+        "dimension": 768,
+        "cosine": 0.69
+      },
+      "estateBinding": {
+        "kind": "entity",
+        "ref": "urn:srcos:schema:OperationalDAG"
+      }
+    }
+  }
+}

specs/glossary-promotion.md

@@ -0,0 +1,23 @@
+# Glossary term promotion (v0.1) — the governed draft→approved alignment pass
+
+The vocab-currency loop ingests terms as `draft`; a draft term names something but does not yet
+regulate state. It becomes `approved` — able to regulate governance — only through the 3-method
+alignment from the GlossaryTerm contract, and only if all three hold as a **fail-closed meet**
+(the same shape as DAR promotion = governance ∧ IP/legal):
+
+1. **capture** — `alignment.ontologyClassRef` (bound to a formal ontology class)
+2. **vector-align** — `alignment.vectorLink` (an NP↔VP link in the sovereign 768 space, pinned to
+   `nomic-ai/nomic-embed-text-v1.5` / dim 768, and **reciprocated** by the named peer — a one-way
+   link is not an alignment)
+3. **implement** — `alignment.estateBinding` (bound to a real estate entity / service / action)
+
+`tools/promote_glossary_term.py` recomputes the meet (never trusts a declared flag) and promotes
+ONLY if all three hold; otherwise it **refuses** and names the unaligned method(s), leaving the
+term `draft`. It never approves on a partial alignment — an approved-but-unaligned term is a
+governance hole, exactly what the #250 drift-guard rejects. `validate-glossary-promotion`
+(in `make validate`) proves the loop closes: the promoted output PASSES that same #250 guard, so
+promotion is consistent-by-construction with the alignment contract; and missing / non-reciprocal /
+off-space alignments are each refused.
+
+This closes the vocabulary lifecycle: currency-detect → propose draft → ontogenesis-ingest →
+**governed alignment promotion → approved** (regulates state).

tools/promote_glossary_term.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Governed draft->approved promotion of a GlossaryTerm via the 3-method alignment (task #13).
+
+The vocab-currency loop ingests terms as `draft`; a draft term names something but does not yet
+regulate state. It becomes `approved` — able to regulate — only through the 3-method alignment
+from the GlossaryTerm contract (#250), and only if all three hold as a FAIL-CLOSED MEET (the same
+shape as DAR promotion = governance ∧ IP/legal):
+
+    capture      — alignment.ontologyClassRef  (bound to a formal ontology class)
+    vector-align — alignment.vectorLink         (an NP↔VP link in the sovereign 768 space,
+                   RECIPROCATED by the named peer — a one-way link is not an alignment)
+    implement    — alignment.estateBinding      (bound to a real estate entity/service/action)
+
+promote() returns the approved term ONLY if the meet holds; otherwise it REFUSES and names the
+unaligned method(s), leaving the term draft. It never approves on a partial alignment — an approved
+term that isn't captured+aligned+implemented is a governance hole (exactly what #250's drift-guard
+rejects; this is the active promotion whose output that guard then accepts).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import jsonschema
+
+ROOT = Path(__file__).resolve().parents[1]
+GLOSSARY_SCHEMA = ROOT / "schemas" / "GlossaryTerm.json"
+EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
+EMBED_DIM = 768
+ESTATE_KINDS = {"entity", "service", "action"}
+
+
+def load(p: Path) -> dict:
+    return json.loads(Path(p).read_text(encoding="utf-8"))
+
+
+def _method_failures(term: dict, alignment: dict, peer: dict | None) -> list[str]:
+    """Recompute the meet — never trust a declared 'aligned' flag. Returns the missing methods."""
+    fails = []
+    # 1. capture
+    if not str(alignment.get("ontologyClassRef") or "").strip():
+        fails.append("capture (alignment.ontologyClassRef missing)")
+    # 2. vector-align — present, const-pinned to the sovereign space, and RECIPROCATED by the peer
+    vl = alignment.get("vectorLink") or {}
+    cos = vl.get("cosine")
+    if not vl.get("peerRef"):
+        fails.append("vector-align (alignment.vectorLink missing)")
+    elif vl.get("model") != EMBED_MODEL or vl.get("dimension") != EMBED_DIM:
+        fails.append(f"vector-align (vectorLink must pin {EMBED_MODEL} / dim {EMBED_DIM})")
+    elif not isinstance(cos, (int, float)) or isinstance(cos, bool) or not (-1 <= cos <= 1):
+        fails.append("vector-align (vectorLink.cosine must be a number in [-1, 1] — schema-required)")
+    else:
+        back = ((peer or {}).get("alignment") or {}).get("vectorLink") or {}
+        if not peer or peer.get("id") != vl["peerRef"]:
+            fails.append(f"vector-align (peer {vl['peerRef']} not supplied for reciprocity check)")
+        elif back.get("peerRef") != term.get("id"):
+            fails.append(f"vector-align (peer {vl['peerRef']} does not link back — one-way link is not an alignment)")
+    # 3. implement
+    eb = alignment.get("estateBinding") or {}
+    if eb.get("kind") not in ESTATE_KINDS or not str(eb.get("ref") or "").strip():
+        fails.append("implement (alignment.estateBinding missing a valid kind+ref)")
+    return fails
+
+
+def promote(term: dict, alignment: dict, peer: dict | None = None) -> dict:
+    # Input guard — only promote an actual draft GlossaryTerm; a non-term or an already-approved
+    # term is not a valid promotion target (don't silently mutate it).
+    if term.get("type") != "GlossaryTerm" or not str(term.get("id") or "").strip():
+        return {"promoted": False, "term": term.get("id"), "status": term.get("status"),
+                "refused": "not-a-draft-glossary-term",
+                "detail": "promotion input must be a GlossaryTerm with an id"}
+    if term.get("status") == "approved":
+        return {"promoted": False, "term": term["id"], "status": "approved",
+                "refused": "already-approved", "detail": "term is already approved — nothing to promote"}
+
+    fails = _method_failures(term, alignment, peer)
+    if fails:
+        return {"promoted": False, "term": term["id"], "status": "draft",
+                "refused": "incomplete-alignment", "unaligned": fails,
+                "detail": "draft->approved refused: an approved term must be captured + vector-aligned "
+                          "+ implemented (fail-closed meet); it stays draft"}
+    approved = {**term, "status": "approved", "alignment": alignment}
+    # Fail-closed on the output: never MINT a schema-invalid approved term. The method meet checks
+    # the alignment's governance content; this backstops every remaining GlossaryTerm.json constraint.
+    schema_errs = sorted(jsonschema.Draft202012Validator(load(GLOSSARY_SCHEMA)).iter_errors(approved), key=str)
+    if schema_errs:
+        return {"promoted": False, "term": term["id"], "status": "draft",
+                "refused": "schema-invalid-output", "unaligned": [e.message for e in schema_errs],
+                "detail": "promotion would produce a GlossaryTerm that fails GlossaryTerm.json; refusing"}
+    return {"promoted": True, "term": term["id"], "status": "approved", "approvedTerm": approved}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--term", required=True, help="draft GlossaryTerm JSON")
+    ap.add_argument("--alignment", required=True, help="proposed alignment JSON")
+    ap.add_argument("--peer", help="the vectorLink peer term JSON (for reciprocity)")
+    args = ap.parse_args()
+    result = promote(load(Path(args.term)), load(Path(args.alignment)),
+                     load(Path(args.peer)) if args.peer else None)
+    print(json.dumps(result, indent=2))
+    return 0 if result.get("promoted") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())