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/hneemann/Digital 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 — Slowing — last commit 9mo ago

• Last commit 9mo ago
• 8 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 9mo ago
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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 hneemann/Digital repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hneemann/Digital.

What it runs against: a local clone of hneemann/Digital — 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 hneemann/Digital | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 297 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hneemann/Digital. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hneemann/Digital.git
#   cd Digital
#
# 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 hneemann/Digital and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "src/main/dig/74xx/CrazySmallCPU.dig" \\
  && ok "src/main/dig/74xx/CrazySmallCPU.dig" \\
  || miss "missing critical file: src/main/dig/74xx/CrazySmallCPU.dig"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "distribution/Digital.exe" \\
  && ok "distribution/Digital.exe" \\
  || miss "missing critical file: distribution/Digital.exe"
test -f ".travis.yml" \\
  && ok ".travis.yml" \\
  || miss "missing critical file: .travis.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 297 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~267d)"
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/hneemann/Digital"
  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).

Digital is a Java-based digital logic designer and circuit simulator for educational purposes, allowing users to visually design, simulate, and analyze combinatorial and sequential logic circuits. It supports schematic drawing, gate-level simulation at 120 kHz clock speeds, VHDL/Verilog component integration via ghdl and Icarus Verilog, and exports designs to hardware description languages. Core capability: teach and verify digital logic from simple gates to complex processors (example: a MIPS-like single-cycle CPU) with timing analysis and test case validation. Monolithic Maven JAR project: src/main/java contains core simulator engine, src/main/dig/ houses pre-built circuit examples (74xx TTL gates, CMOS components, FSM demos), src/main/asm/ contains assembly examples and hex ROM files. Distribution folder bundles executables and Windows/Linux installers. Verilog/Assembly support integrated via external tool subprocess calls (ghdl, Icarus).

Computer engineering and computer science educators and students learning digital logic design, microprocessor architecture, and hardware description languages. Also used by hobbyists building custom components in Java and integrating external CAD workflows via the TCP remote interface.

Actively maintained, evidence-based: pom.xml version 1.0-SNAPSHOT, includes CI/CD via Travis CI (.travis.yml) and Bitbucket Pipelines, has cross-platform installers (Windows .exe, Linux .sh), and documented multi-release history in distribution/ReleaseNotes.txt. Production-ready for educational use; no major breaking-change flags visible, though snapshot version suggests ongoing development.

Single-maintainer project (hneemann GitHub handle visible throughout), limited dependency surface visible in pom.xml (mainly SLF4J for logging, no massive transitive tree implied). Risk: external tool dependencies on ghdl and Icarus Verilog for VHDL/Verilog simulation; Java 8+ runtime required; no package.json or gradle.build alternative implies Maven-only build lock-in. Last commit activity not visible from snapshot data, so assess via GitHub recency check.

No explicit PR or issue data provided; however, file structure suggests active example library expansion (multiple 74xx and CMOS circuit files, VGA and processor variants). Distribution versioning (Version.txt, ReleaseNotes.txt) indicates ongoing release cadence. Exact current work requires GitHub repo inspection.

Check README for instructions.

Daily commands:

mvn clean package
java -jar target/digital-1.0-SNAPSHOT.jar

Or after release build, double-click Digital.jar on Windows/macOS, or run ./Digital.sh on Linux (distribution/linux/Digital.sh).

• pom.xml — Maven build configuration defining all project dependencies, plugins, and build lifecycle; essential for understanding the project structure and build process.
• src/main/dig/74xx/CrazySmallCPU.dig — Example digital circuit design file demonstrating the core .dig format that the simulator parses and executes; critical for understanding the circuit DSL.
• README.md — Project overview, feature list, and installation instructions; essential context for why the codebase exists and its intended users.
• distribution/Digital.exe — Primary Windows distribution artifact; indicates the application entry point and packaging strategy for the simulator.
• .travis.yml — CI/CD pipeline configuration; shows how the project is tested and built across platforms automatically.
• CONTRIBUTING.md — Guidelines for contributors; mandatory reference for understanding code standards and contribution workflow.
• LICENSE — Software license definition; critical for understanding usage rights and obligations.

• Circuit Parser (.dig XML handler) (XML parsing, Java reflection (for custom component loading)) — Deserializes .dig XML circuit files into component graph; validates connections and pin compatibility; instantiates simulator model.
  • Failure mode: Malformed .dig file or undefined component causes parse error; user sees exception; simulation does not start.
• Simulator Engine (logic evaluator) — Executes digital logic simulation step-by-step; evaluates combinatorial logic, manages flip-flop state, detects signal convergence

Add a new digital logic component example

1. Create a new .dig file in the appropriate category directory under src/main/dig/ (e.g., cmos/, combinatorial/, 74xx/) (src/main/dig/cmos/newComponent.dig)
2. Define the circuit using the Digital .dig XML-based format with input/output pins and internal wiring (src/main/dig/cmos/newComponent.dig)
3. Add corresponding .svg diagram if providing visual documentation (src/main/dig/cmos/newComponent.svg)
4. Test by loading the circuit in Digital simulator to verify correct behavior (distribution/Digital.exe (or Digital.jar on Linux/Mac))

Add a new processor assembly example

1. Create new .asm file in src/main/asm/ with processor instruction sequences (src/main/asm/NewProcessor.asm)
2. Assemble the code using the project's assembler to generate corresponding .hex firmware file (src/main/asm/NewProcessor.hex)
3. Create or reference a processor circuit design in src/main/dig/ that loads this hex file as ROM/EPROM (src/main/dig/cmos/eprom.dig)
4. Verify processor execution in the simulator with test inputs and expected outputs (distribution/Digital.exe (or Digital.jar on Linux/Mac))

Add support for a new platform or release distribution

1. Update version number in distribution/Version.txt (distribution/Version.txt)
2. Add release notes and build configuration for the new platform (distribution/ReleaseNotes.txt)
3. Update pom.xml with platform-specific build profiles or Maven plugins if needed (pom.xml)
4. Create platform-specific launch scripts or wrapper configurations (e.g., new shell script for distribution/linux/) (distribution/linux/Digital.sh)
5. Update CI/CD pipeline (.travis.yml or bitbucket-pipelines.yml) to build and test on new platform (.travis.yml)

• Java (JRE 8+) — Cross-platform runtime enabling single codebase deployment on Windows, Linux, macOS without recompilation; suits educational context requiring accessibility.
• Maven (pom.xml) — Standard Java build system enabling reproducible builds, dependency management, and CI/CD integration across platforms.
• .dig XML-based circuit format — Human-readable, version-controllable circuit description language; enables custom component definitions and easy integration into simulator.
• Launch4j (l4jconfig.xml) — Wraps JAR into native Windows .exe without requiring end-users to invoke Java from command line; improves user experience on Windows.

• Educational focus over industrial simulation accuracy

  • Why: Lowers barrier to entry for students; focuses on ease-of-use and visual understanding rather than SPICE-level precision.
  • Consequence: Not suitable for professional circuit design workflows; may lack analog simulation, detailed timing analysis, or heat dissipation modeling.

• Single-pass interpreter simulation model

  • Why: Simplifies implementation and keeps simulation responsive for interactive learning; avoids complex constraint-solver overhead.
  • Consequence: May struggle with large combinatorial feedback loops or extremely fine-grained timing; convergence detection must be managed carefully.

• JAR distribution requiring pre-installed JRE

  • Why: Reduces distribution size and maintenance burden; leverages existing Eclipse Temurin ecosystem.
  • Consequence: Users must separately install Java or follow setup instructions; higher friction than native standalone executables.

• Integrated GUI simulator rather than CLI-only tool

  • Why: Matches educational use case; immediate visual feedback enhances learning and engagement.
  • Consequence: Larger codebase; not suitable for headless/server deployments or batch circuit analysis.

• Does not provide SPICE-level analog circuit simulation or continuous-time waveform analysis.
• Not intended for professional PCB design or manufacturing workflows.
• Does not support real hardware compilation or synthesis to FPGA/ASIC (digital simulator only).
• Not a collaborative/cloud-based platform; single-user desktop application.
• Does not include comprehensive formal verification or theorem-proving for circuit correctness.

External tool dependency: VHDL and Verilog simulation require ghdl and Icarus Verilog installed separately on the system PATH—no bundled vendoring. JAR-to-EXE conversion: Windows distribution uses Launch4j (l4jconfig.xml); modifying this requires rebuild via l4j Maven plugin. Java 8+ mandate: no newer Java language features possible without updating all target platforms. Snapshot versioning: Maven pom.xml locked to 1.0-SNAPSHOT, which may break CI/CD if release process not automated. No test source visible: src/test/ directory not listed; test coverage unclear—verify by cloning. Assembly/Verilog integration: likely subprocess-based; blocking calls possible; performance under heavy HDL simulation untested.

• Logic gate simulation and event-driven propagation — Core of Digital: understanding how gate state changes are computed and propagated through the circuit graph enables optimization and debugging of timing issues in complex designs
• Finite State Machines (FSM) and state transition tables — Digital includes a built-in FSM editor that converts visual state diagrams to sequential logic circuits; essential for designing controllers and understanding synchronous sequential design
• Hardware Description Languages (HDL) — VHDL and Verilog — Digital integrates external VHDL (ghdl) and Verilog (Icarus) simulators, allowing schematic and textual HDL to coexist; users must understand both paradigms for mixed-design workflows
• Combinatorial vs. sequential logic synthesis — Digital advertises analysis and synthesis of both; understanding the difference (memory-free vs. state-dependent) is critical for using test cases and export features correctly
• Flip-flops and memory elements (D-FF, SR, JK latches) — Examples in src/main/dig/cmos/ (d-tg-ff.dig, d-tg-ff2.dig) use transmission-gate based flip-flops; understanding transistor-level memory is core to low-level design
• CPU microarchitecture and instruction set design — The CrazySmallCPU.dig and Processor examples demonstrate single-cycle CPU design; users learn register files, ALUs, control paths, and memory interfaces at schematic level
• Test case and circuit verification — Digital allows creating test vectors and assertions; understanding how to write and execute tests ensures correctness before HDL synthesis or physical implementation

• logisim-evolution/logisim-evolution — Direct competitor: Java-based digital logic simulator with similar gate library and circuit export; easier alternative if Logisim's visual editor preferred over Digital's custom UI
• hneemann/Assembler — Companion repo by same author; integrates with Digital via TCP remote interface to allow assembly code editing and live simulation linking
• hneemann/digitalCustomComponents — Official template/example for extending Digital with custom Java components; shows how to package and integrate external logic into the simulator
• verilator/verilator — Industry-standard Verilog simulator and synthesis tool; Digital's Icarus Verilog integration can be extended to Verilator for higher fidelity HDL verification
• ghdl/ghdl — Open-source VHDL simulator that Digital depends on for VHDL component simulation; understanding ghdl source aids debugging HDL integration issues

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 GitHub Actions workflow to replace .travis.yml and bitbucket-pipelines.yml

The repo has outdated CI configuration files (.travis.yml and bitbucket-pipelines.yml) but no GitHub Actions workflow. Since the primary repo is on GitHub, a modern .github/workflows/build.yml would enable automated Maven builds, testing, and release artifact generation. This would streamline the release process currently managed via distribution/checklist.txt and ensure consistency across platforms (Windows executables, Linux shell scripts).

• [ ] Create .github/workflows/build.yml to run 'mvn clean package' on push and PRs
• [ ] Configure workflow to build for multiple platforms (Windows .exe via l4jconfig.xml, Linux .sh script)
• [ ] Add step to run unit tests (currently missing test directory in src/)
• [ ] Configure artifact upload for Digital.zip matching distribution/ structure
• [ ] Document new workflow in CONTRIBUTING.md

Create src/test/java test suite for core circuit simulation logic

The repo has no visible test directory (src/test/) despite being a simulator with complex digital logic. Given the presence of multiple .dig circuit files and assembly examples (src/main/asm/), adding unit tests for the simulation engine would catch regressions. This is critical for educational software where correctness is paramount. Tests should cover basic gates, combinatorial logic (src/main/dig/combinatorial/), and sequential circuits.

• [ ] Create src/test/java directory structure matching src/main/java packages
• [ ] Add unit tests for fundamental gate logic (AND, OR, XOR, NAND from src/main/dig/cmos/)
• [ ] Add integration tests loading and simulating .dig files from src/main/dig/combinatorial/ (Adder8bit.dig, Comp*.dig)
• [ ] Add tests for circuit state propagation and clock simulation
• [ ] Configure pom.xml with maven-surefire-plugin (version 2.22.0+) for JUnit execution

Create missing documentation for .dig circuit file format and extension API

The repo contains many .dig circuit files (src/main/dig/) but no specification document explaining the file format schema. Users and contributors cannot understand how to create custom circuits or extend the simulator. A CIRCUIT_FORMAT.md or docs/file-format.md would lower barriers to contribution and enable community-created circuit libraries.

• [ ] Create docs/circuit-file-format.md documenting .dig XML/JSON schema with examples from src/main/dig/
• [ ] Include component reference (gates, flip-flops, memory elements from cmos/ and 74xx/ directories)
• [ ] Document how to create custom components and reference the extension mechanism in source code
• [ ] Add quick-start example showing how to build an 8-bit adder (reference Adder8bit.dig)
• [ ] Link documentation from README.md and CONTRIBUTING.md

• Add unit tests for core simulation engine (gate propagation, timing, state coherence): create src/test/java/ directory with JUnit tests for AND/OR/XOR gates and D-flip-flop timing verification.
• Document component creation workflow: write a CONTRIBUTING.md tutorial with step-by-step examples of adding a custom 74xx IC (e.g., 74HC138 decoder) to src/main/dig/74xx/ and rebuilding the JAR.
• Expand example library with missing TTL/CMOS gates: identify gaps (e.g., 74HC04 NOT, 74HC08 AND, 74HC32 OR beyond XOR) and create .dig schematics for each, testing against Icarus Verilog equivalents.

The Digital project has moderate security concerns primarily centered on dependency management. The most critical issue is the use of outdated SLF4J 1.7.24 (5+ years old), which should be updated immediately. The project uses snapshot versions for distribution, incomplete plugin configurations, and lacks explicit version pinning for build plugins. The codebase structure shows no obvious injection risks (no SQL queries visible, educational simulator focus), no hardcoded credentials detected, and Docker/infrastructure issues are not apparent. Recommendations focus on modernizing dependencies, using stable release versions, and implementing explicit version management throughout the build configuration.

• High · Outdated SLF4J Dependency — pom.xml - property: version.org.slf4j=1.7.24. The pom.xml specifies SLF4J version 1.7.24 (released in 2017). This version is significantly outdated and may contain known security vulnerabilities. SLF4J 1.7.x has reached end-of-life status. Fix: Update to SLF4J 2.0.x or later (e.g., 2.0.7+). Ensure all dependent logging implementations are also updated to compatible versions.
• Medium · Incomplete Maven Plugin Configuration — pom.xml - maven-project-info-reports-plugin configuration. The pom.xml has a truncated maven-project-info-reports-plugin version declaration (version='3.0' with no patch version). This incomplete configuration could lead to unpredictable plugin behavior or use of an outdated version. Fix: Specify a complete and current version number (e.g., 3.4.1 or later). Review and pin all plugin versions explicitly.
• Medium · Snapshot Version in Production — pom.xml - version: 1.0-SNAPSHOT. The project version is set to '1.0-SNAPSHOT', which indicates unstable development builds. Snapshot versions should not be used for distribution or released artifacts, as they can be overwritten and create supply chain risks. Fix: Use stable release versions (e.g., 1.0.0) for production distributions. Reserve SNAPSHOT versions only for internal development builds.
• Medium · Git Commit ID Plugin Without Version Lock — pom.xml - git-commit-id-plugin. The git-commit-id-plugin is declared in the build configuration without an explicit version number. This allows Maven to use any available version, which could introduce unexpected behavior or security issues. Fix: Add an explicit version attribute (e.g., version='4.9.10' or later) to all plugin declarations.
• Low · Missing Security Headers in Distribution Configuration — distribution/ - exe and shell scripts. The distribution folder contains executable files (Digital.exe, Digital.sh) without visible code signing or integrity verification mechanisms in the build configuration. Fix: Implement code signing for executables, add checksum verification mechanisms, and document the verification process in distribution instructions.
• Low · No Visible Dependency Lock File — pom.xml. The repository does not appear to have a dependency lock file (like pom.lock or maven.lock) to ensure reproducible builds and prevent dependency drift attacks. Fix: Consider using Maven Dependency Plugin or BOM (Bill of Materials) to lock transitive dependency versions. Document the expected dependency tree.
• Low · Empty distributionManagement ID — pom.xml - distributionManagement/site/id. The distributionManagement site configuration has an empty 'id' element, which could cause issues with site deployment and credential management. Fix: Provide a meaningful ID value (e.g., 'project-site') or remove the empty element if not needed.

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.