downstream knowledge workspace and VRBoK Effect Synchronization¶

02.030.130.040 v20260803.001

Change Log

This document governs the relationship between:

the repository-governed canonical Effect registry and definitions in the VRBoK;
Alescent-applied Effect references in the ABoK;
the downstream knowledge workspace Effect object type used for discovery, working notes, relationships, and browsing.

The objective is controlled synchronization rather than unrestricted bidirectional editing.

Authority Model¶

GitHub Repository¶

GitHub is the source of truth for:

canonical Effect ID and name;
canonical definition and Optimized Condition;
Effect lifecycle and authority status;
aliases and prohibited variants;
semantic boundaries;
evidence and valuation doctrine;
ABoK Reference Tier and classification doctrine;
governed Reference Effort Sets;
versioning and change history;
public documentation and generated machine context.

downstream knowledge workspace¶

downstream knowledge workspace is the governed working mirror and discovery environment for:

searchable Effect objects;
candidate Effect capture;
working notes and source material;
Related Concepts;
linked Efforts;
exploratory Tier and Class assignments;
collaboration and knowledge navigation;
links to governed GitHub sources;
applied context that has not yet been promoted into the repository.

A downstream knowledge workspace object is not canonical merely because it exists, has a title ending in Optimization, or contains Tier, Class, or narrative content.

Synchronization Direction¶

downstream knowledge workspace candidate or proposed change
            ↓
  search, qualification, and CRB/issue
            ↓
          GitHub PR
            ↓
       merged VRBoK/ABoK
            ↓
 taxonomy, documentation, and context generation
            ↓
  synchronized downstream knowledge workspace canonical fields

Canonical fields flow from GitHub to downstream knowledge workspace after governance.

Proposed changes flow from downstream knowledge workspace into a CRB, issue, or pull request. They do not silently overwrite governed repository content.

Current downstream knowledge workspace Effect Schema¶

The current writable properties are:

downstream knowledge workspace property	Current interpretation	Governed treatment
title	Effect name	Mirror the canonical name for governed Effects. Candidate names should follow the `[Outcome concept] Optimization` convention.
Tier	Existing tier tag	Interpret as Alescent Reference Tier for governed mirror objects. Do not use it as a contextual Applied Tier.
Class	Flat multi-valued class tags	Mirror Primary and Secondary Alescent Effect Classes until separate properties exist. The Primary Class should be listed first where ordering is preserved.
Value Realization	Narrative synopsis	Use as a concise mirror summary, not as the sole canonical definition or complete doctrine.
Effort Sets	Links to `Effort` objects	Interpret as Illustrative Efforts until downstream knowledge workspace supports a dedicated Reference Effort Set object or relationship.
Related Concepts	Links to Concepts	Retain for navigation and source relationships. Do not treat a Related Concept as an Effect, alias, or evidence without qualification.
Aliases	Alternative names	Mirror governed aliases and preserve useful historical search terms.
Body	Working notes and links	May contain the governed summary, links, source notes, candidate analysis, and applied context.

Target downstream knowledge workspace Schema¶

Where downstream knowledge workspace object-type management permits, the Effect type should add:

Effect ID;
Canonical Status;
Canonical Definition;
Optimized Condition;
Primary Effect Class;
Secondary Effect Classes;
Alescent Reference Tier;
VRBoK URL;
ABoK Reference URL;
Canonical Version;
Last Synchronized;
Synchronization Hash;
Related Effects;
Reference Effort Sets;
Typical Domains;
Evidence Summary;
Valuation Summary;
Superseded By;
Candidate Disposition.

Until those properties are available, the existing schema and standardized body sections should carry the equivalent information.

Standard downstream knowledge workspace Body Structure¶

A governed mirror object should use the following body structure where practical:

## Canonical Reference

- Effect ID:
- VRBoK source:
- ABoK applied reference:
- Canonical version:
- Last synchronized:

## Canonical Definition

...

## Optimized Condition

...

## Alescent Applied Reference

- Reference Tier:
- Primary Class:
- Secondary Classes:

## Illustrative Efforts and Effort Sets

...

## Related Effects and Concepts

...

## Working Notes and Candidate Enhancements

...

The body may contain richer working material, but canonical and proposed content must be distinguishable.

Naming Normalization¶

Every downstream knowledge workspace object of type Effect should normally use the form:

[Outcome concept] Optimization

Where Optimization was omitted in error:

append the suffix to the existing title;
preserve the object ID;
preserve properties, body content, backlinks, and relationships;
retain the unsuffixed term as an alias where it has material search or historical value;
do not infer canonical status from the corrected title.

Title normalization is a naming correction, not canonical adoption.

Candidate Treatment¶

A downstream knowledge workspace Effect object not present in the governed VRBoK registry should be treated as:

Exploratory; or
Candidate;

until the Effect Registry and Lifecycle process qualifies or disposes it.

Candidate objects may retain working Tier, Class, Effort, and Related Concept relationships. Those values are hypotheses and should not be synchronized into canonical fields until adopted.

Duplicate Treatment¶

Where downstream knowledge workspace contains duplicate Effect objects:

preserve all object IDs initially;
inspect backlinks, properties, body content, and relationships;
identify the intended canonical mirror object;
merge or preserve unique information;
mark the redundant object as superseded or merged where possible;
do not delete until dependent references are understood;
record the reconciliation in the repository or synchronization log.

Duplicate titles must not create duplicate canonical Effect IDs.

Conflict Resolution¶

Where repository and downstream knowledge workspace values differ:

Field type	Controlling source
Canonical Effect identity and definition	VRBoK repository
Alescent Reference Tier, Classes, and governed Effort Sets	ABoK repository
Customer-specific Applied Tier and Effect Designation	Governing customer or Engagement record
Working notes and candidate ideas	downstream knowledge workspace, subject to promotion governance
Generated documentation and agent context	Repository generation routines

Do not overwrite working notes merely because canonical fields are synchronized. Keep governed and exploratory content distinguishable.

Synchronization Record¶

effect_sync_record:
  effect_id: ""
  canonical_name: ""
  lifecycle_status: ""

  github:
    vrbok_path: ""
    abok_path: ""
    version: ""
    commit_sha: ""
    content_hash: ""

  downstream knowledge workspace:
    object_id: ""
    object_url: ""
    last_updated: ""
    sync_hash: ""

  synchronization:
    direction: "github_to_downstream knowledge workspace"
    last_synchronized: ""
    synchronized_by: ""
    fields_synchronized: []
    fields_preserved_as_working_content: []
    conflicts: []
    limitations: []

Recommended Automation¶

The preferred implementation is repository-first automation that:

reads the canonical Effect registry and individual Effect definitions;
reads ABoK applied reference records;
matches downstream knowledge workspace objects by persistent object ID before title;
compares version and synchronization hash;
updates only governed mirror fields;
preserves working notes and non-governed relationships;
writes a synchronization report;
flags candidates, duplicates, missing objects, and conflicts;
never creates or deletes canonical Effects automatically;
requires explicit governance for semantic changes.

Cost Optimization Mapping¶

cost_optimization_sync:
  effect_id: "effect.cost-optimization"
  downstream knowledge workspace_object_id: "controlled-source-id"
  vrbok_doc_id: "01.020.010.020.100"
  abok_doc_id: "02.030.130.100"
  canonical_name: "Cost Optimization"
  alescent_reference_tier: "Tier 1"
  primary_class: "Economic"
  secondary_classes:
    - "Operational"

Governance¶

Synchronization routines must be reviewable, versioned, reversible, and limited to declared governed fields.

A synchronization failure or conflict must not cause data loss, silent title replacement, duplicate object creation, or canonical drift.

Material synchronization model changes require ABoK governance and review of any affected VRBoK canonical-source relationships.