contributing.md

Contributing to Glyphic Language

Thank you for your interest in contributing to Glyphic Language — a symbolic protocol, semantic substrate, and training pipeline for drift‑resistant agent cognition.

Glyphic is designed to be extensible, collaborative, and community‑driven.
This document explains how to contribute new glyphs, dictionary entries, syntax rules, CTX fields, templates, and training data.
Guiding Principles

Glyphic is built on four core principles:
1. Determinism

Meaning must be encoded in a structured, predictable, machine‑verifiable way.
2. Extensibility

The language must grow over time through community proposals.
3. Stability

Changes must not break existing models, datasets, or CTX envelopes.
4. Transparency

All changes must be documented, reviewed, and versioned.
Ways to Contribute

You can contribute in several areas:

    New dictionary entries  
    (concepts, actors, emotions, objects, modifiers, places, contexts)

    New glyphs or symbolic structures

    Syntax or grammar improvements  
    (BNF rules, ordering rules, structural constraints)

    CTX protocol extensions  
    (identity, intent, memory, behavior, safety, state, thought)

    Dataset templates  
    (new training patterns for generator)

    Interpreter improvements  
    (encoder, decoder, validator)

    Documentation  
    (guides, examples, diagrams)

    Bug fixes and code improvements

Contribution Workflow
1. Fork the repository
Code

https://github.com/GlyphicMind-Solutions/Glyphic-Language

2. Create a feature branch
Code

git checkout -b feature/my-contribution

3. Make your changes

Follow the guidelines below for dictionary, syntax, CTX, or code changes.
4. Run validation

Before submitting a PR, run:
bash

python -m generator.debug_json
python -m interpreter.interpreter

These ensure:

    dictionary schema is valid

    syntax rules are consistent

    glyphs encode/decode correctly

    CTX envelopes pass validation

5. Submit a Pull Request

Include:

    a clear description of your change

    examples

    justification

    any new templates or tests

Dictionary Contributions

Dictionary files live in:
Code

dictionary/

Each entry must follow the schema:
json

{
  "id": "unique_identifier",
  "name": "Human-readable name",
  "description": "Clear definition of the concept",
  "category": "concept | actor | emotion | object | modifier | place | context",
  "relations": {
    "synonyms": [],
    "antonyms": [],
    "parents": [],
    "children": []
  }
}

Rules

    IDs must be unique.

    Definitions must be neutral, precise, and structural.

    Avoid cultural, political, or subjective framing.

    All entries must pass validation.

Syntax & Grammar Contributions

Syntax files live in:
Code

syntax/
data/ctx_protocol.bnf

Rules

    Syntax must remain deterministic.

    No ambiguous productions.

    No overlapping grammar paths.

    All changes must include examples in syntax/grammar_examples.md.

    All changes must be validated using the interpreter.

CTX Protocol Contributions

CTX files live in:
Code

data/CTX.*.json

These define:

    identity

    intent

    memory

    behavior

    safety

    state

    thought

    response

Rules

    New fields must be justified with a clear use case.

    Fields must be machine‑interpretable.

    No free‑form prose fields.

    All CTX changes must include examples in docs/GLYPHIC_PROTOCOL.md.

Template Contributions

Templates live in:
Code

generator/templates_*.py

Rules

    Templates must produce valid structured meaning.

    Templates must not introduce drift or ambiguity.

    All templates must be tested by generating a small dataset.

Interpreter Contributions

Interpreter files live in:
Code

interpreter/

Rules

    Encoder and decoder must remain reversible.

    Validator must reject invalid glyphs.

    No breaking changes to existing glyph syntax.

    All changes must include tests.

Testing Your Contribution

Before submitting a PR, run:
bash

python -m generator.run_generator --test
python -m interpreter.interpreter --validate

This ensures:

    dictionary integrity

    syntax correctness

    glyph reversibility

    CTX envelope validity

    dataset generation stability

Glyphic Enhancement Proposals (GEPs)

Major changes require a GEP.

Create a file:
Code

GEPs/GEP-XXXX.md

Include:

    Summary

    Motivation

    Specification

    Examples

    Backwards compatibility

    Implementation plan

GEPs are reviewed by maintainers and the community.
Code Style

    Use Python 3.12+

    Follow PEP8

    Keep functions small and modular

    Add docstrings

    Add comments for complex logic

    Avoid unnecessary dependencies

Community Standards

Glyphic is a technical project focused on:

    symbolic structure

    semantic clarity

    deterministic protocols

    agent cognition

Contributions must remain:

    neutral

    technical

    non‑political

    non‑ideological

    grounded in structure, not metaphor

License

By contributing, you agree that your contributions will be licensed under:

Creative Commons Attribution 4.0 International (CC‑BY 4.0)
Thank You

Your contributions help Glyphic evolve into a robust, extensible, civilization‑scale semantic language.