CLI Organizational Subsystem Architectural Guide

Overview

The ZQK Organizational Subsystem (cmd/zqk/organizational) provides first-class, graph-native structural modeling, change recording, impact analysis, and cascade propagation across the Zen Quantum Kernel (ZQK).

In traditional enterprise software and project management tools, organizational structure lives in an external Human Resources Information System (HRIS) or siloed identity directory (such as LDAP or Okta). As a result, technical program management objectsβ€”such as goals, milestones, workstreams, requirements, and backlog itemsβ€”are frequently orphaned or misassigned when teams reorganize, split, or merge.

ZQK treats organizational topology and organizational changes as versioned, deterministic objects within the persistent Knowledge Kernel. The organizational subsystem bridges human team topology with autonomous execution swarms through four core operational capabilities:

  1. Deterministic Change Recording (record-change): Captures structural mutations (restructures, team reassignments, division splits) as immutable kernel change events.
  2. Graph-Native Impact Analysis (analyze-impact): Traverses ontological relationships across workstreams, milestones, goals, and backlog items to compute exact affected blast radiuses.
  3. Guarded Change Propagation (propagate): Applies controlled updates across downstream kernel objects with two-phase verification, dry-run safety, and cryptographic provenance.
  4. Declarative Structure Sync (sync): Ingests bulk enterprise structure representations via YAML or JSON with schema validation gates, allowed-kinds filtering, and idempotent upsert semantics.

Subsystem Architecture & Design Principles

Architectural Topology

flowchart TD
    subgraph EnterpriseInputs ["Enterprise Structure & Change Inputs"]
        OrgYAML["Organizational Schema (YAML/JSON)"]
        ChangeEvents["Organizational Change Briefs"]
    end

    subgraph OrgSubsystem ["cmd/zqk/organizational Subsystem"]
        SyncCmd["zqk organizational sync"]
        RecordCmd["zqk organizational record-change"]
        AnalyzeCmd["zqk organizational analyze-impact"]
        PropagateCmd["zqk organizational propagate"]

        SyncEngine["Bulk Sync & Validation Engine"]
        ImpactEngine["Impact Analysis Traversal Engine"]
        PropEngine["Propagation & Tagging Engine"]
    end

    subgraph DomainModel ["Organizational Domain Plane"]
        Org["organization (ORG-*)"]
        Div["division (DIV-*)"]
        Dept["department (DEP-*)"]
        Team["team (TEAM-*)"]
        Partner["partnership (PAR-*)"]
        Change["organizational_change (OCH-*)"]
        Impact["impact_analysis (IMP-*)"]
    end

    subgraph ExecutionPlane ["Kernel Execution Graph"]
        Workstreams["workstream (WKS-*)"]
        Goals["goal (GOAL-*)"]
        Milestones["milestone (MLS-*)"]
        BLIs["backlog_item (BLI-*)"]
    end

    OrgYAML -->|Ingest & Validate| SyncCmd
    SyncCmd --> SyncEngine
    SyncEngine --> Org & Div & Dept & Team & Partner

    ChangeEvents -->|Record| RecordCmd
    RecordCmd --> Change

    Change -->|Analyze Blast Radius| AnalyzeCmd
    AnalyzeCmd --> ImpactEngine
    ImpactEngine --> Impact

    Impact -->|Preview / Apply| PropagateCmd
    PropagateCmd --> PropEngine
    PropEngine -->|Tag last_propagated_change_ref| Workstreams & Goals & Milestones & BLIs

Key Design Principles

  1. Graph-Native Domain Modeling: Organizations, divisions, departments, teams, and partnerships are fully registered ontological kinds governed by specs in .zqk/process/_internal/specs/ and validated by Content-Addressed Storage (CAS) schemas.

  2. Two-Phase Impact & Propagation Separation: Structural mutations never mutate downstream technical work implicitly. Changes must first produce a verifiable impact_analysis artifact. Propagation requires deliberate human or automated confirmation (--confirm), preventing unintended graph corruption.

  3. Declarative Synchronization with Schema Check-Valves: Enterprise synchronizations enforce strict schema validation, rejecting unallowed object kinds and guaranteeing atomic or fault-tolerant ingestion via configurable error recovery modes.

  4. Auditability & Cryptographic Provenance: All state updates record last_propagated_change_ref attributes, allowing continuous traceability back to the root organizational_change record that initiated the transition.


Organizational Domain Model

The subsystem manages seven primary ontological kinds within the domain:organizational namespace:

Kind Prefix Description Key Relationships
organization ORG-* The root enterprise or sovereign company envelope. Contains division_refs.
division DIV-* High-level organizational unit (e.g., Engineering, Product, Design). Linked to parent division or organization; contains team_refs.
department DEP-* Sub-division functional grouping. Belongs to a division; groups functional teams.
team TEAM-* Atomic execution team composed of humans and autonomous agents. Owns workstreams, backlog items, and seats.
partnership PAR-* Formal collaboration between internal teams or external vendors. Connects multiple team_refs or external partner IDs.
organizational_change OCH-* Immutable audit record capturing a structural transition event. Holds affected_objects and impact_analysis_refs.
impact_analysis IMP-* Calculated dependency graph report detailing affected kernel objects. Links 1:1 via change_ref to its originating organizational_change.

Illustrative Object Identifiers

All organizational objects strictly adhere to canonical prefix patterns (^[A-Z]+-\d{3,}$):

  • Organizations: ORG-DEMO-001, ORG-CORE-001
  • Divisions: DIV-ENG-001, DIV-PROD-001
  • Departments: DEP-PLATFORM-001, DEP-AI-001
  • Teams: TEAM-KERNEL-001, TEAM-FOUNDATION-001
  • Partnerships: PAR-ALLIANCE-001
  • Organizational Changes: OCH-001, OCH-002
  • Impact Analyses: IMP-001, IMP-002

Command Taxonomy & CLI Invocations

The command group is registered under zqk organizational:

zqk organizational [subcommand] [flags]

Available Subcommands

  analyze-impact   Analyze impact of organizational changes on kernel objects
  propagate        Propagate organizational changes to affected objects
  record-change    Record an organizational change in the knowledge kernel
  sync             Sync organizational structure from YAML or JSON files

1. zqk organizational record-change

Records a structural change event in the Knowledge Kernel.

Flags

  • --id (required): Unique identifier for the organizational change (e.g., OCH-001).
  • --change-type (required): Semantic type of change (division_restructure, team_reassignment, split, merge, lead_transition).
  • --title: Brief human-readable title. Defaults to --change-type.
  • --description: Detailed architectural justification. Defaults to --title.
  • --affected-objects: Path to a YAML or JSON file explicitly detailing affected entities.
  • --change-date: RFC3339 timestamp of the change. Defaults to current UTC time.
  • --dry-run: Validates input and logs simulated creation without persisting to storage.

Example Invocations

# Record an engineering restructure with dry-run verification
zqk organizational record-change \
  --id OCH-001 \
  --change-type division_restructure \
  --title "Engineering Platform Realignment" \
  --dry-run

# Record a team reassignment referencing an affected objects payload
zqk organizational record-change \
  --id OCH-002 \
  --change-type team_reassignment \
  --title "Reassign Core Team to Platform Division" \
  --description "Migrating Core Infrastructure team to Division Platform" \
  --affected-objects /tmp/affected_teams.json

2. zqk organizational analyze-impact

Executes graph traversal across the Knowledge Kernel to compute the full blast radius of an organizational change.

Traversal & Cascade Engine

When analyze-impact runs, the analyzer inspects the target organizational_change:

  1. Extracts change_type and explicitly defined affected_objects.
  2. Inspects team and division memberships for downstream dependencies.
  3. Traverses active technical program management entities linked to those units: - Workstreams (workstream): Active streams aligned with the affected team or division. - Goals (goal): High-level strategic objectives owned by affected units. - Milestones (milestone): Time-bounded deliverables scheduled under affected workstreams. - Backlog Items (backlog_item): In-flight or unassigned backlog units mapped to affected teams.
  4. Generates an impact_analysis object (IMP-*) storing the computed mappings in affected_objects.
  5. Links the resulting impact report back to the organizational_change record via impact_analysis_refs.

Flags

  • --change (required): ID of the organizational_change to analyze (e.g., OCH-001).

Example Output

$ zqk organizational analyze-impact --change OCH-001
Impact analysis created: IMP-001
Change: OCH-001 (division_restructure)
Affected object types: 4
  - workstreams: 2 objects
  - goals: 3 objects
  - milestones: 4 objects
  - backlog_items: 12 objects

3. zqk organizational propagate

Propagates the findings of an impact analysis across downstream kernel entities.

Propagation Lifecycle

Propagation follows a strict three-state safety model:

  1. Default Preview Mode: Running zqk organizational propagate --change OCH-001 resolves the active impact analysis and outputs a summary of affected entities, prompting the operator for confirmation.

  2. Explicit Dry-Run Mode: Running zqk organizational propagate --change OCH-001 --dry-run performs a full simulated execution without updating objects in CAS storage.

  3. Confirmed Execution: Running zqk organizational propagate --change OCH-001 --confirm updates each affected object in storage, writing the last_propagated_change_ref attribute.

Flags

  • --change (required): Organizational change object ID (OCH-*).
  • --impact-analysis: Specific impact analysis object ID (IMP-*). If omitted, automatically resolves the latest analysis from references, storage, or draft plane.
  • --dry-run: Preview propagation without modifying objects in storage.
  • --confirm: Confirms and applies propagation updates.

Example Invocations

# 1. Preview affected entities
zqk organizational propagate --change OCH-001

# 2. Preview dry-run
zqk organizational propagate --change OCH-001 --dry-run

# 3. Confirm and apply propagation updates
zqk organizational propagate --change OCH-001 --confirm

4. zqk organizational sync

Performs high-throughput, declarative ingestion of complete organizational structures from external files.

Allowed Kinds Whitelist

For security and domain boundary enforcement, zqk organizational sync enforces a strict whitelist of permitted object kinds:

  • organization
  • division
  • department
  • team
  • partnership
  • organizational_change

Any object kind outside this whitelist (e.g., attempting to sync backlog_item or policy through the organizational sync command) is intercepted and rejected by validation check-valves.

Flags

  • --file (required): Path to YAML or JSON file containing organizational definitions.
  • --input-format: Format of input data (yaml or json). Defaults to yaml.
  • --mode: Ingestion mode:
  • upsert (default): Creates non-existent objects and updates existing objects.
  • create_only: Fails if any object already exists in storage.
  • --dry-run: Validates file schema and integrity without writing to storage.
  • --continue-on-error: Continues processing subsequent records when individual object errors occur.

Example Invocations

# Dry-run validation of corporate org structure
zqk organizational sync --file org_structure.yaml --dry-run

# Bulk upsert with error resilience
zqk organizational sync --file org_structure.yaml --mode upsert --continue-on-error

# Ingestion from JSON manifest
zqk organizational sync --file org_structure.json --input-format json --mode create_only

Security Model, Audit Trails & CAS Boundaries

Security Context & Permissions

All CLI commands in the organizational subsystem operate within the ZQK SecurityContext pipeline:

  • System Authority: Administrative bulk sync operations require SystemSecurityContext or equivalent administrative capabilities.
  • Access Control: Objects conform to public or confidential access profiles defined in their respective YAML schema specifications.
  • Actor Attribution: When changes and propagations are applied, CAS metadata captures the executing agent or operator ID in created_by and updated_by.

CAS Storage Membrane & Draft Plane

  1. Draft Plane Preliminary Isolation: When organizational changes and impact analyses are initially staged, preliminary drafts can reside on the mutable draft plane (.zqk/object_drafts/).

  2. CAS Immutability & Content Addressing: Once validated and promoted, objects are immutably persisted in CAS storage (.zqk/process/). Subsequent changes require new versioned transactions.

  3. Reference Validation Check-Valves: References such as division_refs, team_refs, and change_ref are validated against the live CAS index to guarantee relational integrity across the graph.


Best Practices & Operational Runbook

Slicing & Evolution Guidelines

  • Shift-Left Organization Modeling: Keep team and division topologies up-to-date in source control before launching major technical initiatives. This ensures workstream and backlog assignment automations target accurate teams.

  • Never Skip Impact Analysis: Always execute analyze-impact and review the generated impact_analysis summary before executing propagate --confirm.

  • Atomic Sync Files: When syncing corporate hierarchies, structure files from root to leaves (organization βž” division βž” department βž” team) to allow foreign key references to resolve cleanly during single-pass imports.

  • Idempotent Automation: Integrate zqk organizational sync --dry-run into CI/CD pipelines to validate HRIS export schemas before staging into production kernels.