docs(solutions): capture ReDoS learning from plugin trust-boundary inversion

[marcusrbrown]

Why

PR #352 inverted Systematic's plugin registration model from a per-process singleton to per-load registration. The bootstrap marker regex in src/index.ts was unchanged from prior versions, but CodeQL flagged it as polynomial-time ReDoS-vulnerable on the new branch. The regex hadn't moved; the trust boundary around it had — under the singleton it only saw plugin-authored content, but under per-load registration every plugin source can contribute fragments to output.system before the marker matcher runs.

The lesson generalizes beyond this specific fix and is worth compounding: architectural changes that broaden the set of input authors can reclassify a previously safe regex as unsafe, even when the pattern itself is untouched. Worth a learning doc so the next inversion gets caught at design time, not at CodeQL time.

What

New compound doc at docs/solutions/security-issues/redos-after-plugin-trust-boundary-inversion-2026-05-11.md capturing:

• Problem & symptoms — CodeQL alerts feat(commands): add agent routing and model override support #42 + feat: add Claude Code field compatibility to skills system #43 on the marker regex; the specific input shape (repeated opening markers, no closing tag) that triggers backtracking; the architectural commit that exposed it
• What didn't work — bounded-length regex (arbitrary cap, doesn't fix the class), atomic groups (not in JavaScript), CodeQL inline suppression (papers over a real boundary change)
• Solution — the findBootstrapMarkerBlock indexOf/slice helper with before/after code
• Why it works — linear O(n+m) substring search vs O(n²) regex backtracking on adversarial inputs; secondary benefits (no $&/$1 interpolation hazard, more legible semantics)
• Prevention — four concrete rules, the headline being "when you invert or expand a plugin's trust boundary, re-audit every regex even if it was CodeQL-clean before"
• Cross-references — PR fix(plugin): deduplicate factory registration across opencode.json sources #335 origin doc (the singleton that PR refactor(plugin): independent per-load registration with marker-based bootstrap idempotency #352 reverted), the layered-trust-boundaries config overlay doc, and the agent-color schema regression

Discoverability

AGENTS.md line 55 already describes docs/solutions/ accurately. No instruction-file edit needed — the knowledge store surfaces to fresh agents.

Validation

• YAML frontmatter validates against the compound schema: problem_type: security_issue → bug track → category: security-issues/, all enum fields (component, severity, root_cause, resolution_type) match canonical values
• Content-integrity gate clean (the doc lives in docs/solutions/ which is gate-excluded by design, but the gate ran anyway and stayed clean)
• docs/solutions/ is not part of the Starlight content collection — no MDX parse risk from the <SYSTEMATIC_WORKFLOWS> literals in code examples

Creates a new docs/solutions/security-issues/ directory; no other category change.

[fro-bot]

Verdict: PASS

Clean, well-structured compound doc that accurately captures a security learning. Frontmatter is valid, cross-references resolve, and the technical explanation is correct.

Blocking issues

None

Non-blocking concerns

None

Missing tests

None — this is a documentation-only PR. The regression test it references already exists in (lines 579–597) and was validated in this review.

Risk assessment (LOW) + rationale

This change adds a single markdown file under , a directory already excluded from the content-integrity gate by design. No code paths are modified. No plugin API surfaces are touched. The only risk is stale documentation, but the After code snippets match at HEAD exactly and the referenced regression test exists and passes. Blast radius is zero.

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	25658621158
Cache	hit
Session	ses_1e9e17368ffe8ExsUlvqo0Z8zo

[fro-bot]

Verdict: PASS

Clean, well-structured compound doc that accurately captures a security learning. Frontmatter is valid, cross-references resolve, and the technical explanation is correct.

Blocking issues

None

Non-blocking concerns

None

Missing tests

None — this is a documentation-only PR. The regression test it references already exists in tests/unit/plugin.test.ts (lines 579–597) and was validated in this review.

Risk assessment (LOW) + rationale

This change adds a single markdown file under docs/solutions/security-issues/, a directory already excluded from the content-integrity gate by design. No code paths are modified. No plugin API surfaces are touched. The only risk is stale documentation, but the "After" code snippets match src/index.ts at HEAD exactly and the referenced regression test exists and passes. Blast radius is zero.

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	25658621158
Cache	hit
Session	ses_1e9e17368ffe8ExsUlvqo0Z8zo