If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mxgmn/MarkovJunior shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 7w ago
• 5 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mxgmn/MarkovJunior repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mxgmn/MarkovJunior.

What it runs against: a local clone of mxgmn/MarkovJunior — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mxgmn/MarkovJunior | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 81 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mxgmn/MarkovJunior. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mxgmn/MarkovJunior.git
#   cd MarkovJunior
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mxgmn/MarkovJunior and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mxgmn/MarkovJunior(\\.git)?\\b" \\
  && ok "origin remote is mxgmn/MarkovJunior" \\
  || miss "origin remote is not mxgmn/MarkovJunior (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "MarkovJunior.csproj" \\
  && ok "MarkovJunior.csproj" \\
  || miss "missing critical file: MarkovJunior.csproj"
test -f "models.xml" \\
  && ok "models.xml" \\
  || miss "missing critical file: models.xml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "LICENSE" \\
  && ok "LICENSE" \\
  || miss "missing critical file: LICENSE"
test -f "CITATION.cff" \\
  && ok "CITATION.cff" \\
  || miss "missing critical file: CITATION.cff"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 81 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~51d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mxgmn/MarkovJunior"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MarkovJunior is a probabilistic programming language for constraint-based procedural generation that uses pattern matching and rewrite rules on grid cells. Programs are XML-defined sequences of rewrite rules (e.g., RBB=GGR) that the interpreter applies via constraint propagation to generate dungeons, mazes, architecture, and puzzles. The core innovation is probabilistic inference that can impose constraints on future states and backtrack through rule applications to satisfy them. Monolithic C# application: MarkovJunior.csproj is the core project. Runtime interpreter logic lives in the root source (likely *.cs files not enumerated), and 150+ runnable example models are stored declaratively in models/ as *.xml files (e.g., models/MazeBacktracker.xml, models/Apartemazements.xml). The images/ folder contains animated GIFs demonstrating each model's output.

Game developers and procedural generation researchers building dungeon generators, level designers, and architectural layout systems; artists and tool creators who want declarative, seed-based world generation without writing simulation code; researchers studying Markov algorithms and constraint satisfaction in generation.

Actively developed, mature for research/hobby use. Single-author repo (mxgmn) with 153 working examples in models/, comprehensive XML syntax docs, and clean C# codebase (161K lines). No CI/CD pipeline visible in provided files, no unit tests mentioned, and commit recency unknown from provided data—appears well-maintained but not at enterprise production maturity.

Single-maintainer project with no visible CI/CD or test suite raises reliability risk. No dependency list visible but C# .NET Framework dependency is implicit. Lack of issue/PR data makes backlog status unclear. The XML model format is custom and tightly coupled to the interpreter, so breaking changes to the language could invalidate existing models/*.xml files without forward compatibility layers.

Unknown from provided data—no recent commits, open PRs, or CI logs are visible. The presence of 153 example models and polished GIFs suggests the core language is feature-complete. Likely focus is on community use and incremental model additions rather than language design changes.

Clone and build with .NET: git clone https://github.com/mxgmn/MarkovJunior.git && cd MarkovJunior && dotnet build MarkovJunior.csproj (assumes .NET SDK is installed). Then run the interpreter on an example model—exact invocation depends on the built binary, likely ./bin/Release/MarkovJunior models/Basic.xml or similar GUI/CLI entry point.

Daily commands: Unknown exact invocation from provided data. Likely: dotnet run --project MarkovJunior.csproj models/Basic.xml or a compiled binary with a model path argument. Check root *.cs entry point and/or README.md for Main() signature and CLI usage.

• MarkovJunior.csproj — C# project configuration defining build targets, dependencies, and compilation settings for the entire codebase.
• models.xml — Master index of all 153 example models that demonstrates the language's capabilities and serves as reference documentation.
• README.md — Primary entry point explaining the probabilistic language foundation, Markov algorithms, rewrite rules, and constraint propagation semantics.
• LICENSE — Legal terms governing usage, modification, and distribution of the MarkovJunior implementation.
• CITATION.cff — Metadata for academic citation enabling proper attribution when referencing this research project.

• XML Parser (C# XDocument / XPath) — Deserializes rewrite rule definitions and initial grid configuration from model files
  • Failure mode: Malformed XML or invalid rule syntax causes parse error and abort
• Rewrite Engine (C# grid data structure, pattern matching algorithms) — Maintains grid state, finds pattern matches, applies rule substitutions, and orchestrates execution loop
  • Failure mode: No matching rules → termination; invalid rule application → grid corruption
• Constraint Propagator (Constraint satisfaction algorithms, arc consistency) — Validates that pattern matches respect logical constraints and eliminates infeasible states
  • Failure mode: Over-constrained model → unsatisfiable, no valid generation path; under-constrained → poor quality output
• Grid Renderer (C# imaging libraries, palette mapping) — Converts final grid state to image output (PNG) or animated sequence (GIF)
  • Failure mode: Missing or invalid palette → incorrect colors; large grids → memory exhaustion
• Model Library (XML DSL, rewrite rule syntax) — 153 reference XML implementations demonstrating language features and domain applications
  • Failure mode: Incorrect rule semantics → wrong output; inefficient rules → slow generation

• User → CLI — Invokes MarkovJunior with model file path and output parameters
• CLI → XML Parser — Reads model XML file and passes raw content for deserialization
• XML Parser → Rewrite Engine — Supplies parsed rewrite rules, initial grid state, and configuration
• Rewrite Engine → Grid State — Reads current grid, scans for matches, writes transformed grid after rule application
• Rewrite Engine → Constraint Propagator — Submits pattern matches for feasibility validation before rule commitment
• Constraint Propagator → Rewrite Engine — Returns pass/fail verdict on match feasibility; prunes invalid matches
• Grid State → Grid Renderer — Final grid transferred to rendering pipeline for PNG/GIF output
• Grid Renderer → User — Saves generated image file to disk; user views output

Add a new procedural generation model

1. Create a new XML file in the models/ directory following the rewrite rule syntax (models/YourNewModel.xml)
2. Define rewrite rules using pattern matching syntax (e.g., ABC=DEF for replace A-B-C with D-E-F) (models/YourNewModel.xml)
3. Register the new model in the master index to expose it to the interpreter (models.xml)
4. Execute and test via the MarkovJunior interpreter CLI/GUI (MarkovJunior.csproj)

Implement a new constraint propagation rule

1. Define the pattern matching logic for detecting rule applicability on the grid (MarkovJunior.csproj)
2. Implement the constraint propagation algorithm that eliminates invalid states (MarkovJunior.csproj)
3. Add test models to models/ that exercise the new constraint type (models/BasicConstraint.xml)

Extend example library for domain-specific generation

1. Study existing domain models (e.g., mazes, dungeons, cellular automata) in models/ (models/MazeBacktracker.xml)
2. Create adapted XML model with domain-specific rewrite rules and constraints (models/DomainSpecificModel.xml)
3. Generate visualization GIF output and add to images/ directory (images/DomainSpecificModel.gif)
4. Update models.xml index to include new example in appropriate category (models.xml)

• C# / .NET — Provides high-performance runtime for constraint propagation over large grid states; cross-platform via Mono/CoreCLR
• XML-based Domain-Specific Language — Human-readable declarative syntax for rewrite rules enables non-programmers to express generative algorithms; easy to version and compare models
• Rewrite systems + Constraint propagation — Combines Markov algorithm foundations with logical inference to solve procedural generation as a constraint satisfaction problem

• Interpreted XML rules vs. compiled bytecode

  • Why: DSL enables rapid experimentation and cross-platform portability without compilation
  • Consequence: Runtime overhead on each step; slower than native machine code but sufficient for interactive generation speeds

• Ordered rule list with first-match semantics

  • Why: Simple, deterministic execution model matches Markov algorithm semantics; predictable behavior for users
  • Consequence: Rule ordering is critical; no implicit rule combination or parallel matching; requires careful model design

• Random match selection vs. exhaustive enumeration

  • Why: Enables stochastic variety in output; avoids bias toward early grid positions
  • Consequence: Non-deterministic results complicate debugging; requires seeding for reproducibility

• Real-time interactive editing with live preview (models are static XML files)
• Networked collaborative model development (single-user file-based workflows)
• GPU acceleration or distributed constraint solving (CPU-based single-threaded engine)
• Built-in GUI editor (command-line or external tool integration assumed)
• Three-dimensional grid generation (2D primary, limited 3D examples)
• Machine learning or learned constraint synthesis (hand-authored rules only)

• XML-only model expression (Medium) — models/*.xml: Models cannot express conditional logic, loops, or meta-rules; complex generation requires flattened rule enumeration leading to verbose, hard-to-maintain XML
• Greedy first-match rule selection (Medium) — Rewrite Engine core loop: No backtracking or rule prioritization beyond list order; once first matching rule fires, other applicable rules ignored in that step. Can cause generation to reach dead-ends
• Grid memory unbounded — Grid State management: No explicit bounds checking

.NET Framework / SDK version constraint unknown—the .csproj may target a specific .NET version (Framework 4.x, Core 3.x, or .NET 6+) that must be installed for dotnet build to succeed. No environment variable or config file mentioned in provided data. The custom XML model format has no schema validation visible, so typos in model definitions may fail silently or at runtime. The constraint propagation inference may have exponential backtracking cost for certain rule sets and grid sizes; no visible heuristics or pruning strategies mentioned.

• Markov algorithm — MarkovJunior is literally named after and implements Markov algorithms; understanding the ordered rule application model (first-match, random-selection, termination on no matches) is the conceptual foundation of the entire language.
• Constraint propagation — Probabilistic inference in MarkovJunior uses constraint propagation to backtrack and reject rule application sequences that violate future constraints; this is the mechanism enabling Sokoban solvers and other goal-directed generation.
• Rewrite rule / Term rewriting — The core execution model is pattern matching and rewriting on grid cells (e.g., RBB=GGR); understanding how the interpreter matches and substitutes patterns is essential to writing models.
• Self-avoiding walk — The MazeBacktracker example uses a self-avoiding random walk, a classic stochastic process; understanding why the first rule RBB=GGR naturally enforces self-avoidance is key to intuiting how MarkovJunior generates coherent structures.
• Backtracking search — Probabilistic inference with constraints requires the interpreter to explore and backtrack through rule application sequences; backtracking search is the algorithmic core of avoiding invalid end states.
• Procedural content generation (PCG) — MarkovJunior is a domain-specific language for PCG; understanding the design space (rule-based vs. sampling vs. learning) and applications (dungeons, architecture, puzzles) contextualizes why this tool exists.

• nothings/stb — Single-header C libraries for procedural generation and image processing; similar philosophy of minimal dependencies and procedural content focus, though different language and scope.
• munificent/crafting-interpreters — Educational interpreter and language design repository; shares the design pattern of a custom DSL with pattern matching and execution semantics, useful for understanding MarkovJunior's rule evaluation architecture.
• jblow/jai — General-purpose language with first-class pattern matching and metaprogramming; related in spirit of declarative rule-based computation, though Jai targets systems programming rather than generation.
• OndrejMarsalek/GrowthGrammarGeneration — Alternative L-system and grammar-based procedural generation framework; solves similar problem (declarative procedural content) with different formal model (context-free grammars vs. Markov rewriting).
• mxgmn/WaveFunctionCollapse — Same author's earlier constraint-based procedural generation tool using tile superposition; foundational work that influenced MarkovJunior's constraint propagation philosophy.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add XML schema validation and documentation for models/*.xml files

The repo contains 150+ example XML model files (models/Apartemazements.xml, models/MazeBacktracker.xml, etc.) but there's no XSD schema or formal documentation of the XML structure. This creates a barrier for contributors wanting to create new models. Documenting the schema would enable IDE autocomplete, validation, and reduce errors when authoring new procedural generation rules.

• [ ] Create models/schema.xsd defining the grammar for rewrite rules, constraints, and grid parameters
• [ ] Add XML namespace declarations to existing model files to reference the schema
• [ ] Document in README.md the structure of a valid model file with examples (rule syntax, convolution patterns, constraint propagation nodes)
• [ ] Add a schema validation test/script that validates all 150+ XML files against the schema

Add GitHub Actions CI workflow to validate all example models execute without errors

With 150+ example XML models in models/ directory, there's no automated way to detect if a code change breaks existing models. A CI pipeline would run each model for N iterations and fail fast if any model throws an exception or produces invalid output, preventing regressions.

• [ ] Create .github/workflows/validate-models.yml that runs on PR/push events
• [ ] Add a C# test harness (e.g., Tests/ModelValidationTests.cs) that dynamically iterates over all *.xml files in models/ directory
• [ ] Execute each model 5-10 times with different random seeds and verify grid output is valid
• [ ] Report results with per-model execution times to catch performance regressions

Create interactive model showcase with built-in parameter UI generator from XML metadata

The models.xml file references all examples but there's no automated way to discover tunable parameters (grid size, iterations, probability weights) or adjust them without editing XML. Extracting parameter metadata from each model's XML and generating a simple UI would make the project more accessible to non-programmers exploring procedural generation.

• [ ] Extend model XML schema (from PR #1) to include optional <parameter> elements with name, type, min, max, default attributes
• [ ] Update 10-15 key models (MazeBacktracker.xml, Basic.xml, etc.) to annotate their tunable numeric/boolean parameters
• [ ] Build a simple WinForms/WPF parameter panel that reflects over XML metadata and binds UI controls to model parameters
• [ ] Document the parameter metadata convention in README.md with examples

• Add unit tests for rule parsing: create a test/ directory with xUnit tests for the XML parser (likely in a RuleParser.cs or ModelLoader.cs class) to validate that models/Basic.xml and other examples parse and execute deterministically with fixed seeds.
• Document the rewrite rule alphabet: the README and syntax.md show examples like RBB=GGR but don't formally define the valid cell colors/symbols or their semantic meaning. Extract a color legend and add it to syntax.md with cross-references to example models.
• Create a 'hello world' model: write a minimal models/HelloWorld.xml tutorial model that generates a simple 5×5 checkerboard pattern with 1 rule, add it to the models.xml index, and document it in syntax.md as the fastest onboarding example for new users.

MarkovJunior is a domain-specific probabilistic programming language with a relatively low attack surface. The codebase appears to be focused on procedural generation rather than web/network services, which reduces certain vulnerability classes (SQLi, XSS not applicable). However, critical gaps exist: (1) No dependency vulnerability data was available for analysis - the .csproj file must be reviewed to ensure all NuGet packages are current and patched; (2) XML parsing is central to the system (models/*.xml files) - ensure proper XML parser configuration to prevent XXE attacks; (3) No security policy documentation. Primary risks involve malicious XML input and outdated dependencies. The project's academic/generative nature suggests lower exploitation likelihood compared to web applications, but input validation and dependency management must be verified.

• Medium · Missing Dependency Manifest — MarkovJunior.csproj / dependency management. No package dependency file (package.json, packages.config, .csproj dependencies section visible, etc.) was provided for analysis. This prevents verification of known vulnerabilities in third-party dependencies. The project uses C# (.csproj file present) but dependency versions cannot be verified. Fix: Provide complete dependency manifest. Run 'dotnet list package --vulnerable' to identify known CVEs. Consider using tools like OWASP Dependency-Check or Snyk for automated vulnerability scanning.
• Low · No SECURITY.md Policy — Repository root. Repository lacks a SECURITY.md file documenting security policy and responsible disclosure process. This may hinder security researchers from reporting vulnerabilities responsibly. Fix: Create a SECURITY.md file following GitHub's security advisory template, outlining how to report vulnerabilities privately.
• Low · Minimal Security Documentation — README.md. README contains no security warnings, guidelines for secure usage, or information about input validation. For a language that processes XML models and generates outputs, security guidance is important. Fix: Add security section to README documenting: input validation practices, safe usage of XML parsing, constraints on model complexity, and any known limitations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.