minutework 0.1.52 → 0.1.53

package/assets/claude-local/skills/ontology-authoring/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ontology-authoring
+description: "Promoting a local fact to shared, URN-anchored truth: declaring ontology mappings, URN anchors, and promotion rules, then staging reviewable promotion candidates."
+---
+
+# Ontology Authoring
+
+Use this skill when a local app object should become — or resolve to — a
+**shared, Core-owned, URN-anchored** entity that other tenants' runtimes can
+recognize. This is the authoring half of the promotion loop; the
+principles-only companion is `ontology-mapping/SKILL.md`.
+
+The review law is the point of this lane:
+**Core is the sole `urn:mw:<kind>:<uuid>` minter; a runtime never mints, and
+every promotion is reviewable.** You stage a candidate locally and the
+bridge-owned sweep submits it; an operator (or the conservative auto-accept)
+decides. Nothing you author activates a shared URN by itself.
+
+## 1. Classify: shared WHO/WHERE/WHAT vs tenant-local
+
+Decide, per object, whether it is genuinely shared identity or just tenant
+data:
+
+- `entity` — a shared **WHAT/WHO-org** (a company, vendor, carrier, account).
+- `person` — a shared **WHO** (PII-bearing; always operator-reviewed).
+- `location` — a shared **WHERE** (always operator-reviewed).
+- Everything high-variance or tenant-specific stays **runtime-local** — do not
+  promote it. Overlay it instead (step 2).
+
+Map the object's stable identifiers to namespaced identifier types
+(`EntityIdentifier.id_type` for entities, `PersonIdentifier.id_type` for
+persons). A good shared identifier is namespaced and externally meaningful
+(e.g. a government registry number). FleetRun is illustrative only: a carrier's
+DOT number is an `entity` identifier; the carrier's internal nickname is not.
+
+## 2. Declare mappings, anchors, and overlays (schema DSL)
+
+In `schemas/schema.ts` (or `schema.mw`), declare `ontologyMappings`:
+
+```ts
+ontologyMapping("vendor", "entity", {
+  anchors: [anchor("entity_ref", "entity")],
+  promotionRules: [
+    promotionRule("entity_ref", "entity", {
+      mode: "candidate_match",
+      idType: "registry_id",
+      minConfidence: 0.95,
+    }),
+  ],
+  overlays: [overlay("entity_ref", "vendor_terms", ["payment_terms", "rep"])],
+})
+```
+
+- `anchor(field, target_kind)` — the local field that carries the shared URN
+  once resolved. Compiles into a `URNAnchor` target.
+- `overlay(target_urn_field, overlay_kind, payload_fields)` — hang
+  tenant-specific fields off a shared entity **without** mutating the shared
+  baseline. Keep high-variance fields here, not in the shared object.
+- These compile to `ontologyMappingManifests`, which the runtime materializes
+  as `LocalOntologyMapping` rows on install — that is what makes this runtime's
+  objects of the kind promotion-eligible and what `ontology.resolve_local`
+  falls back to.
+
+## 3. Declare promotion rules (`prom_v1`)
+
+For a promotable fact, declare a `promotionRule` with:
+
+- `mode`: `candidate_match` (resolve to an existing shared entity) or
+  `candidate_create` (propose a new one).
+- `id_type`: the namespaced identifier the match keys on.
+- `min_confidence` (optional): the floor for the conservative entity
+  auto-accept. **Auto-accept fires only for `entity`, only on an exactly-one
+  unique-identifier match at confidence ≥ threshold, and only as an echo of the
+  existing URN — no mint, no create, no merge.** Person, location, zero/multi
+  matches, and any create/merge always go to operator review.
+
+## 4. Stage a candidate at runtime (staging only)
+
+Staging is a runtime act, separate from submission. Cite the exact tools (both
+are outside the default read ring — grant per agent via `enable_agent_tools`):
+
+- `ontology.resolve_local` — read, live. Returns the `URNAnchor` for a local
+  object (the shared `core_urn`) or the active mapping candidates as fallback.
+- `ontology.propose_candidate` — effectful, **staging only**. Records a PENDING
+  `PromotionCandidate`; it does **not** push to Core. The bridge-owned sweep
+  (`MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED`) submits, and Core decides.
+
+Provenance is mandatory and you never supply a URN:
+
+- Put namespaced identifiers in `evidence.identifiers`
+  (`[{ id_type, value }]`), the local anchor target in `evidence.anchor`
+  (`{ local_object_kind, local_object_id, field_name }`), and the supporting
+  signal as plain `evidence` keys.
+- Pass a calibrated `confidence` and an opaque `source_ref` (a
+  `runtime:<id>:<kind>:<id>` reference) — never a `urn:mw:` value, and never a
+  `core_urn`. Only Core mints URNs.
+
+## Cross-runtime anchoring
+
+A runtime learns a shared `core_urn` **only for facts it itself staged**. There
+is no open "does identifier X exist in Core" lookup. When a second runtime has
+the same mapping installed and stages its own candidate for the same fact, the
+sweep re-POSTs it, Core's `(origin_runtime, origin_ref, candidate_kind)` unique
+constraint dedupes against the already-decided request and returns the **same**
+`core_urn`, and that runtime writes its own `URNAnchor`. Same shared truth, no
+new trust surface.
+
+## Cross-references
+
+- `runtime_ontology_contract.md` — runtime-local anchors, mappings, candidates.
+- `core_ontology_and_runtime_overlays.md` — Core ownership and overlays.
+- `schema-engine/SKILL.md` — declaring the schema the mappings hang off.
+- `app-pack-authoring/SKILL.md` — packaging the mappings into an installable app.
+- `ontology-mapping/SKILL.md` — the principles companion.

package/assets/claude-local/skills/ontology-mapping/SKILL.md

@@ -8,6 +8,10 @@ description: "Local app data needs shared identifiers, shared meaning, or mappin
 Use ontology mappings when local app data needs shared identifiers or shared
 meaning.
 
+For the concrete authoring procedure (declaring mappings, URN anchors, and
+promotion rules, then staging reviewable promotion candidates), see the sibling
+`ontology-authoring/SKILL.md`.
+
 - Prefer stable shared references and URNs over duplicating shared entities.
 - Runtime should remain ontology-aware, not ontology-authoritative.
 - Keep local app schema ownership clear even when mapping into shared ontology

package/assets/claude-local/skills/runtime-capability-inventory/SKILL.md

@@ -142,6 +142,12 @@ generated Builder workspace.
   - `ontology.resolve_local` -- Read-only native tool over
     URNAnchor/LocalOntologyMapping; not in the default READ_RING, granted per agent via
     enable_agent_tools.
+  - `ontology.propose_candidate` -- Stages a PENDING PromotionCandidate locally
+    (idempotent on origin_ref+candidate_kind). The bridge-owned submission sweep then
+    carries it cross-plane (PENDING -> SUBMITTED -> resolved with a Core-minted
+    core_urn) under MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED; Core stays the sole URN
+    minter and its ingress fails closed independently. Effectful; outside the default
+    READ_RING, granted per agent via enable_agent_tools.
   - `command_exec.run_template` -- Operator/platform-dispatch surface; not an
     agent-callable tool.
   - `voice.hangup_call` -- VoiceSession finalization is live; the provider-side hangup
@@ -152,12 +158,6 @@ generated Builder workspace.
   leg as unavailable):
   - `scheduling.book_appointment` -- Capability is registered but the direct booking
     executor is MVP-deferred; preflight truthfully reports provider_unavailable.
-  - `ontology.propose_candidate` -- Staging leg only: records a PENDING
-    PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The
-    cross-plane submission to Core (PENDING -> SUBMITTED -> resolved with a minted
-    core_urn) is a deferred, bridge-owned leg; the promotion service stays
-    platform-owned. Effectful; outside the default READ_RING, granted per agent via
-    enable_agent_tools.
   - `voice.initiate_call` -- Pre-dial stack is live (consent + TCPA preflight, approval
     parking, VoiceSession lifecycle); the Twilio dial + realtime media worker are
     platform-owned Phase 4.

package/assets/claude-local/skills/runtime-capability-inventory/primitive-catalog.json

@@ -304,9 +304,9 @@
       "requires_integration": false,
       "requires_secret": false,
       "metered": false,
-      "executor_ready": "partial",
+      "executor_ready": "live",
       "executor_ref": "tool:ontology.propose_candidate",
-      "executor_notes": "Staging leg only: records a PENDING PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The cross-plane submission to Core (PENDING -> SUBMITTED -> resolved with a minted core_urn) is a deferred, bridge-owned leg; the promotion service stays platform-owned. Effectful; outside the default READ_RING, granted per agent via enable_agent_tools.",
+      "executor_notes": "Stages a PENDING PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The bridge-owned submission sweep then carries it cross-plane (PENDING -> SUBMITTED -> resolved with a Core-minted core_urn) under MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED; Core stays the sole URN minter and its ingress fails closed independently. Effectful; outside the default READ_RING, granted per agent via enable_agent_tools.",
       "agent_exposable": true,
       "agent_exposure_path": "native_tool",
       "approval_required": false,

package/assets/claude-local/skills/schema-engine/SKILL.md

@@ -9,6 +9,9 @@ Use this skill when the request needs tenant-defined data structures.
 
 - Define tenant data in `schemas/schema.ts` or `schema.mw`, not ad hoc Django tables.
 - Prefer declarative schema changes before adding custom code surfaces.
+- To map local objects onto shared, URN-anchored ontology entities, declare
+  `ontologyMappings` (with `anchor`, `promotionRule`, and `overlay` helpers) in
+  the same schema source; the procedure is in `ontology-authoring/SKILL.md`.
 - Index only the fields that need query/filter behavior.
 - Treat runtime-backed content as the authoring source; publish safe snapshots for anonymous public delivery.
 - Treat `mw.core.site` as already present in the runtime baseline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutework",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "MinuteWork CLI for workspace scaffolding, local preview workflows, and hosted preview deploys.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "jiti": "^2.6.1",
     "zod": "^4.3.6",
     "@minutework/platform-config": "0.1.3",
-    "@minutework/schema-compiler": "0.1.12"
+    "@minutework/schema-compiler": "0.1.13"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",