Covenant Patterns

Covenant Patterns

Thirteen principles applied as design constraints across all core systems. Every yama guards against a presumption.

Overview

Covenant Patterns operationalizes the Pragma Covenant as enforceable design constraints. Unlike generic "best practices," these principles emerged from specific failures—each yama guards against a presumption that caused real damage.

This skill maps covenant principles to practical implementation across:

• Agents — Steering, specs, context assembly
• Prompts — Epistemic rendering, cognitive lenses
• Artifacts — Canvas workflows, semantic JSON
• Workshop — Recipe assembly, slice architecture
• Exocortex — Multi-agent coordination, graph substrate
• Skills — Technical capability documentation

The Thirteen Principles

👁️ Dotfile Visibility

Yama: No bare ls when orienting to directories.

Niyama: Use ls -a or ls -A. Include .* patterns in glob searches. Treat dotfolders as first-class citizens.

✨ Bespokedness

Yama: No enterprise theater. No building for imaginary scale, future users, or "best practices."

Niyama: Personal system optimized for operator workflow/aesthetics/experimentation. Disposable software demands the bespoke. Prefer solutions simple enough to fork without excavation.

⚡ Fast-Fail Enforcement

Yama: No robustness theater. Unenforced invariants do not exist. Never create/delete data as smoke test.

Niyama: Gate on capabilities (missing tool = immediate failure). Enforce invariants at storage boundary. Use read-only startup health checks.

Context Engineering Application:

# BAD: Robustness theater
try:
    result = tool.invoke(params)
except ToolNotFound:
    result = fallback_implementation()  # Hidden failure path

# GOOD: Fast-fail
if not tool.registered():
    raise CapabilityGateFailure(f"Required tool '{tool.name}' not available")
result = tool.invoke(params)

🧷 Decision Integrity

Yama: No fracturing single decisions into sub-decision trees. No reopening locked decisions via adjacent "requirements."

Niyama: Missing + required = choose minimal reversible default, label it, proceed. Missing + not required = proceed silently.

Context Engineering Application:

# BAD: Decision fracturing
def configure_agent(agent):
    model = ask_user("Which model?")  # Decision 1
    if model == "opus":
        variant = ask_user("Which Opus variant?")  # Sub-decision
        if variant == "opus-4":
            reasoning = ask_user("With extended thinking?")  # Sub-sub-decision
    # ... endless tree

# GOOD: Decision integrity
def configure_agent(agent):
    model = ask_user("Which model?") or "sonnet"  # Minimal default
    agent.model = model  # Proceed

🚮 Final-State Surgery

Yama: No compatibility shims, dual-path loaders, legacy fallbacks, zombie stubs, shadow copies, carcinogenic artifacts, or deprecated references.

Niyama: Operator instruction = final-state surgery. Remove prior arrangement entirely. Update all references so old world is unreachable.

Context Engineering Application:

# BAD: Legacy preservation
def migrate_config():
    new_config = load_new_format()
    old_config = load_legacy_format()  # "Just in case"
    if new_config.version < 2:
        return merge(old_config, new_config)  # Compatibility shim
    return new_config

# GOOD: Final-state surgery
def migrate_config():
    config = load_config()
    if config.version < CURRENT_VERSION:
        config = transform_to_current(config)
        save_config(config)  # Overwrite, no backup
        delete_legacy_files()  # Remove old world
    return config

⛔ Work Preservation

Yama: Never discard work unless explicitly asked. Never "clean up" changes or undo "unrelated diffs" without instruction. "Out of scope" = ask, not revert.

Niyama: —

🗡️ Git Semantics

Yama: No amending, reordering, or curating staged contents unless explicitly asked.

Niyama: "Commit" = git add -A then git commit as instructed. Nothing more.

🧊 Protected Paths

Yama: No edits unless operator explicitly requests. Content may drift or be incomplete; do not "fix" or normalize.

Niyama: Edit-on-request: docs/**

🗣️ Data Fidelity

Yama: No invented model fields, classifications, traits, IDs, DB contents, tool results, or "expected" outputs.

Niyama: UNKNOWN > INVENTED. Missing info = ask or query. Unexecuted/failed tool = treat results as unknown.

Context Engineering Application:

# BAD: Mock data
def get_user_preference(key):
    result = db.query(key)
    if result is None:
        return "default_value"  # Invented!

# GOOD: Data fidelity
def get_user_preference(key):
    result = db.query(key)
    if result is None:
        return Unknown(reason=f"No preference found for '{key}'")
    return result

🔤 Literal Exactness

Yama: No paraphrasing or stylizing literals at interfaces (commands, paths, IDs, tool names, schema names).

Niyama: Exactness required = copy verbatim or fail loudly.

🔒 Threshold-Gated Action

Yama: No crossing commitment thresholds without explicit operator authorization. High-stakes actions require clear gate.

Niyama: —

🔁 Determinism

Yama: No time-based logic in core operations.

Niyama: Prefer deterministic behavior: stable ordering, explicit IDs. Keep execution paths replayable.

Context Engineering Application:

# BAD: Non-deterministic
def generate_id():
    return str(uuid4())  # Random each time

# GOOD: Deterministic
def generate_id(content, namespace):
    return str(uuid5(namespace, content))  # Same input = same ID

🧬 Context Hygiene

Yama: No transmitting context wholesale. No context-stuffing. No councils/event-buses/pipeline frameworks unless requested. No "central context dictator" orchestrators.

Niyama: Compile context per-recipient and per-turn. Prefer gradients over binaries. Prefer tiered context: persistent substrate → compiled working context → retrieval-based long memory.

Context Engineering Application:

# BAD: Context stuffing
def prepare_context(agent, task):
    return {
        "full_history": conversation.all_messages(),
        "all_files": workspace.read_all(),
        "complete_config": config.everything()
    }

# GOOD: Context hygiene
def prepare_context(agent, task):
    return compile_context(
        recipient=agent.role,
        concentration=agent.context_level,
        turn=task,
        tiers=[
            substrate.persistent,
            compiled.for_task(task),
            retrieved.relevant_to(task.query)
        ]
    )

Cross-System Integration

Principle Inheritance

All core systems inherit covenant principles:

Principles (source of truth)
    ↓
├── Agents (steering inherits covenant)
├── Prompts (lenses respect data fidelity)
├── Artifacts (canvas workflows are deterministic)
├── Workshop (recipes apply final-state surgery)
├── Exocortex (daemons enforce context hygiene)
└── Skills (documentation embodies bespokedness)

Validation Pattern

Each system can validate against covenant:

def validate_covenant_compliance(operation, system):
    """Validate operation against covenant principles."""

    violations = []

    # Check each applicable principle
    if operation.creates_legacy_artifacts():
        violations.append("🚮 Final-State Surgery: Legacy artifact detected")

    if operation.invents_data():
        violations.append("🗣️ Data Fidelity: Invented data detected")

    if operation.uses_non_deterministic_ids():
        violations.append("🔁 Determinism: Non-deterministic ID detected")

    if operation.stuffs_context():
        violations.append("🧬 Context Hygiene: Context stuffing detected")

    if violations:
        raise CovenantViolation(violations)

    return True

Quality Gates

Pre-Implementation

• Which covenant principles apply to this work?
• Are there potential violation patterns to avoid?
• Is context being compiled per-recipient, not stuffed?
• Are IDs deterministic, not random?
• Will this create legacy artifacts?

Post-Implementation

• All applicable principles satisfied
• No invented data (UNKNOWN > INVENTED)
• No legacy preservation (final-state surgery)
• Deterministic and replayable
• Context hygiene maintained

Related Skills

• agent-steering — Universal agent configuration with covenant enforcement
• epistemic-rendering — Cognitive lenses that respect data fidelity
• recipe-assembly — Workshop patterns with final-state surgery
• multi-agent-coordination — Pentadyadic patterns with context hygiene

"Every yama guards against a presumption that caused real damage. This doctrine is not theory; it is a scar." 🜍