Technical Design: Context Engineering Structural Guardrails

Technical Design: Context Engineering Structural Guardrails

Metadata

• Feature: context-engineering-guardrails
• Issue: #39
• Status: DRAFT
• Created: 2026-02-01

1. Overview

1.1 Summary

Create automated enforcement of context engineering principles and Task ecosystem integrity rules. A single validation module codifies the 5 drift-detection checks from CLAUDE.md, adds split-pair consistency checks, and auto-splits oversized commands. Integrated into CI and pre-commit.

1.2 Goals

• Automate CLAUDE.md drift detection checklist as runnable validation
• Auto-split command files that exceed 300-line threshold via existing CommandSplitter
• Provide a command template so new commands inherit CE patterns by default
• Fail CI on violations; run in pre-commit for local enforcement

1.3 Non-Goals

• Token budget counting per command (fragile, changes with content)
• New plugin ABCs or validator framework classes
• Bracketed subject prefix format checking (convention, not structural)

2. Architecture

2.1 New Module: zerg/validate_commands.py

Single module, no new classes. Functions return (bool, list[str]) matching validation.py pattern.

5 validation checks:

Plus:

• validate_all(commands_dir, auto_split) — aggregator, runs all 5
• _get_base_command_files(commands_dir) — helper, returns .md files excluding .core.md/.details.md/_template.md
• __main__ block for python -m zerg.validate_commands

Constants:

BACKBONE_COMMANDS = {"worker", "status", "merge", "stop", "retry"}
BACKBONE_MIN_REFS = 3
TASK_MARKERS = {"TaskCreate", "TaskUpdate", "TaskList", "TaskGet"}
STATE_PATTERNS = re.compile(r"state.*json|STATE_FILE|\.zerg/state")
EXCLUDED_PREFIXES = ("_",)  # Skip _template.md

Imports MIN_LINES_TO_SPLIT from command_splitter.py (single source of truth).

2.2 Auto-Split Behavior

validate_split_threshold accepts auto_split: bool = False:

• When False (CI mode): returns error listing oversized files
• When True (pre-commit mode): calls CommandSplitter.split_file() on each oversized file, reports what was split, returns success

CI workflow detects uncommitted changes after validation and fails with message: "Command files were auto-split. Commit the generated files."

2.3 Command Template: zerg/data/commands/_template.md

~45 lines. Scaffold for new commands with:

• # ZERG {CommandName} header placeholder
• Arguments/flags section
• Pre-flight checks section
• Task Tracking boilerplate (pattern from build.md:50-65)
• Execution section placeholder
• Exit Codes section
• Help section

Underscore prefix auto-excludes from validator.

2.4 CI Integration: .github/workflows/command-validation.yml

New workflow (separate from changelog-check.yml):

• Triggers: push to main, PR events
• Steps: checkout, setup-python, pip install -e ., python -m zerg.validate_commands
• Fails build on any violation

2.5 Pre-commit Integration

Append local hook to .pre-commit-config.yaml:

- repo: local
  hooks:
    - id: validate-commands
      name: Validate ZERG command files
      entry: python -m zerg.validate_commands --auto-split
      language: system
      files: 'zerg/data/commands/.*\.md$'
      pass_filenames: false

3. File Manifest

4. Test Strategy

tests/unit/test_validate_commands.py — ~20 tests across 6 classes.

Positive tests (real zerg/data/commands/ directory):

• All commands pass task reference check
• All backbone commands pass depth check
• All split pairs are consistent
• No state-json-without-tasks violations
• validate_all() passes clean on current codebase

Negative tests (tmp_path fixtures):

• Missing task reference flagged
• Shallow backbone file flagged
• Orphaned .core.md flagged
• Orphaned .details.md flagged
• Oversized unsplit file flagged
• State JSON without TaskList flagged
• _template.md excluded from checks
• .core.md/.details.md excluded from base file checks

Auto-split tests:

• Oversized file gets split when auto_split=True
• Split produces .core.md and .details.md
• Validator returns success after auto-split

5. Verification

# Validator passes on current codebase
python -m zerg.validate_commands

# New tests pass
pytest tests/unit/test_validate_commands.py -v

# Full suite regression
pytest tests/ --no-header -q

# Pre-commit hook runs
pre-commit run validate-commands --all-files