Known Issues

Active and recently resolved issues for molecule-dev.

Active Issues

(None currently open. This section is updated when issues are filed.)

Recently Resolved

[RESOLVED] plugin.yaml Merge Conflict Residue

Severity: P2 Resolved in: v1.0.0

Symptoms: plugin.yaml contained residual merge conflict markers (<<<<<<<, =======, >>>>>>>) that caused YAML parsing to fail. The runtimes: section listed claude_code, deepagents in the main branch while the working copy attempted to add hermes.

Cause: A git stash operation was used to temporarily discard local changes; on git stash pop, the conflicted state was re-applied and committed without conflict resolution.

Fix: Resolved by overwriting plugin.yaml with clean, conflict-free content. The file now has 3 runtimes declared and the rules: section populated.

Prevention: Never git add a file containing conflict markers. Use git add <file> only after <<<<<<< markers are fully removed, or use git mergetool.

Known Gotchas

These are not bugs but behaviors that may surprise contributors:

`rules/` section missing from plugin.yaml

Symptoms: Adding a new rule file and referencing it in plugin.yaml may silently fail if the rules: key is absent.

Workaround: Verify plugin.yaml contains the top-level rules: key before adding rule references. If absent, add it:

rules:
  - rules/codebase-conventions.md
  - rules/<new-rule>.md

`hermes` runtime requires adapter

Symptoms: Installing the plugin for a hermes workspace runtime works, but at runtime the adapter import may fail if plugins_registry is not installed in the harness environment.

Workaround: This is expected in isolated dev environments. The harness handles adapter resolution at runtime. See runbooks/local-dev-setup.md in the repo for local adapter testing.

No local test runner

Symptoms: npm test / python -m pytest return no results — there are no unit tests in this plugin.

Workaround: This is by design — the plugin is a configuration package. Validation is done by the shared validate-plugin.yml workflow in CI. Run it locally via gh workflow run validate-plugin.yml --ref main.

How to Update This File

When a new issue is discovered:

Add it under Active Issues using the template below.
Include: symptom, cause (if known), workaround, and fix (if resolved).
When fixed, move it to Recently Resolved and note the fix version.

Issue Template

## [TICKET-NUMBER] <Short Title>

**Severity:** P0 / P1 / P2 / P3
**Status:** Workaround / Fix in progress / Fix available / Resolved in vX.Y.Z

**Symptoms:**
**Cause:**
**Workaround:**
**Fix (if available):**

Severity Definitions

Level	Description
P0	Plugin fails to load entirely; no workaround
P1	Core convention violated; can cause production failures
P2	Non-core issue; minor impact or workaround available
P3	Cosmetic; edge case; informational

Reporting

Use the Molecule-AI/internal issue tracker. Tag issues with plugin-molecule-dev.

3.1 KiB Raw Blame History