Simplify module specs, add source links, document agent-built provenance#15
Merged
Conversation
Trims the docs/moonmodules spec pages to complement the source rather than restate it (~3,400 → ~2,000 lines, no information lost), links each spec back to its code, and records in the README + release notes that projectMM is authored entirely by agents.
Docs / CI:
- README + release-notes-v1.0.0: state that all code, installer, MoonDeck, docs, tests, and images are agent-authored — the product owner authors process/architecture/specs and controls every commit, merge, and release; call out unit + scenario tests as a strongpoint.
- docs/moonmodules: removed prose that duplicated the .h (method signatures, control mechanics, validation rules) across all 40 spec pages; kept wire contracts, cross-domain wiring, and prior art per the CLAUDE.md spec-doc rule. Fixed two present-tense violations (BlendMap "what worked/needs improvement", Layouts "what needs improvement") and a stale BlendMap blend-path description.
- docs/moonmodules: added a "## Source" section linking every spec to its .h/.cpp (UI + LightConfig to their multi-file sources); consolidated the REST API into HttpServerModule (ui.md links to it) and removed ui.md's self-recap "Feature summary".
- docs/backlog: moved leddriver-analysis-{top-down,bottom-up}.md out of moonmodules (forward-looking design studies, not module specs); repointed the architecture.md link and the docs' internal relative links.
- check_specs.py: enforce the source-link contract — every spec page must carry a "## Source" section whose relative links resolve, catching renamed-source drift and Source-less new pages at commit gate 1.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 43 minutes and 25 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR consolidates and refactors documentation across 50+ moonmodule specifications by adding "Source" sections linking to implementation headers, streamlining content descriptions, and introducing a validation script. Four new external-project activity digests expand the history folder, while navigation and process docs clarify AI agent authorship and prior-art study practices. ChangesDocumentation Audit and Source Link Integration
🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly Related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/moonmodules/light/effects/NoiseEffect.md`:
- Line 16: In the NoiseEffect documentation paragraph that describes 2D/3D
behavior (the line containing the phrase "z axis"), replace the non-hyphenated
term "z axis" with the hyphenated compound "z-axis" to match the surrounding
technical style; locate the sentence that currently reads "in 3D the z axis
scrolls at 1/5 the x-rate..." and update it to "in 3D the z-axis scrolls at 1/5
the x-rate..." so the compound noun is consistently hyphenated across the
NoiseEffect.md text.
In `@scripts/check/check_specs.py`:
- Around line 84-91: The current regex in check_specs.py (the re.search that
assigns m for '^## Source') captures to EOF so links in later sections can be
mistaken as part of Source; narrow the match to only the Source section by
changing the search to capture up to the next top-level header or end-of-file
(e.g. use a non-greedy dotall with a lookahead like "(?=^##\\s|\\Z)"), then
continue using m.group(1) for re.findall (links/rel_links) and the existing
issues logic so only links inside the actual Source section are checked.
- Around line 96-98: The current link-resolution logic accepts absolute or
out-of-repo paths because it only checks filesystem existence; change it to
reject any href target that is absolute or escapes the repository root: compute
target = href.split("#",1)[0] as before, immediately reject if target
startswith("/") or startswith("..") (or contains ".." path components), then
resolve the candidate = (md.parent / target).resolve() and ensure candidate is
inside the repository root (e.g., compare candidate with repo_root.resolve() via
is_relative_to or by checking candidate.parts startswith repo_root.parts); only
if the candidate exists and is inside the repo should you append the link to
issues as valid—otherwise append the same "source link does not resolve" error.
Ensure you update the logic around the existing target/href/md.parent resolution
and the issues.append call.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8801669e-84ab-44b7-aa08-f19b1d649abe
📒 Files selected for processing (46)
README.mddocs/architecture.mddocs/backlog/leddriver-analysis-bottom-up.mddocs/backlog/leddriver-analysis-top-down.mddocs/history/release-notes-v1.0.0.mddocs/moonmodules/core/BoardModule.mddocs/moonmodules/core/Control.mddocs/moonmodules/core/FilesystemModule.mddocs/moonmodules/core/FirmwareUpdateModule.mddocs/moonmodules/core/HttpServerModule.mddocs/moonmodules/core/ImprovProvisioningModule.mddocs/moonmodules/core/MoonModule.mddocs/moonmodules/core/NetworkModule.mddocs/moonmodules/core/Scheduler.mddocs/moonmodules/core/SystemModule.mddocs/moonmodules/core/ui.mddocs/moonmodules/light/BlendMap.mddocs/moonmodules/light/Buffer.mddocs/moonmodules/light/Drivers.mddocs/moonmodules/light/EffectBase.mddocs/moonmodules/light/Layer.mddocs/moonmodules/light/Layers.mddocs/moonmodules/light/Layouts.mddocs/moonmodules/light/LightConfig.mddocs/moonmodules/light/MappingLUT.mddocs/moonmodules/light/drivers/ArtNetSendDriver.mddocs/moonmodules/light/drivers/PreviewDriver.mddocs/moonmodules/light/effects/CheckerboardEffect.mddocs/moonmodules/light/effects/FireEffect.mddocs/moonmodules/light/effects/GameOfLifeEffect.mddocs/moonmodules/light/effects/GlowParticlesEffect.mddocs/moonmodules/light/effects/LavaLampEffect.mddocs/moonmodules/light/effects/LinesEffect.mddocs/moonmodules/light/effects/MetaballsEffect.mddocs/moonmodules/light/effects/NoiseEffect.mddocs/moonmodules/light/effects/ParticlesEffect.mddocs/moonmodules/light/effects/PlasmaEffect.mddocs/moonmodules/light/effects/PlasmaPaletteEffect.mddocs/moonmodules/light/effects/RainbowEffect.mddocs/moonmodules/light/effects/RipplesEffect.mddocs/moonmodules/light/effects/SpiralEffect.mddocs/moonmodules/light/layouts/GridLayout.mddocs/moonmodules/light/layouts/SphereLayout.mddocs/moonmodules/light/modifiers/CheckerboardModifier.mddocs/moonmodules/light/modifiers/MultiplyModifier.mdscripts/check/check_specs.py
Adds four friend-repo activity digests, reframes how the docs describe learning from other projects (study designs, don't copy code; credit by name), and folds in the CodeRabbit review fixes on the spec-source-link checker.
Docs / CI:
- history: added digests for troyhacks/WLED (PixelForge, RMTHI, audio-reactive hardening + a per-month experimental-branches line for the HDMI/ESP32-P4/W5500/voice branches), hpwit/I2SClocklessLedDriver (IDF5.5, RGBCCT, >65K LEDs, arduino-less ESP-IDF — recent work authored mostly by projectMM), hpwit/ESPLiveScript (work lives on version branches, not main), and hpwit/I2SClocklessVirtualLedDriver (dormant since 2024).
- history: renamed the four owner-less digests to owner-repo.md (FastLED-FastLED, wled-WLED, MoonModules-WLED-MM, PlummersSoftwareLLC-NightDriverStrip) for consistency with the new files; fixed the index cross-refs; extended cross-repo trends (parallel DMA output, HDMI/display output, on-device live scripting) and repointed the LED-driver-analysis link to backlog.
- CLAUDE.md + README: reworded the "cherry-pick" language to study-their-designs-don't-copy-their-code; replaced an overstated "ideas aren't copyrightable" claim with a license-respecting, attribution-by-name commitment ("a good idea doesn't care who has it").
- backlog: added docs/backlog/README.md as the folder index (list + draft specs + design studies) and referenced it from the CLAUDE.md doc tree.
- NoiseEffect: hyphenated "z-axis" for consistency with surrounding text.
Reviews:
- 🐇 NoiseEffect "z axis" → "z-axis": fixed.
- 🐇 check_specs.py Source-section regex captured to EOF: fixed — bounded the match to the section with a next-header/EOF lookahead so links in any later section aren't scanned as source links.
- 🐇 check_specs.py accepted absolute/out-of-repo source links: fixed — now rejects absolute paths and any link whose resolved target escapes the repo root.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…unt fix Sharpens architecture.md into an explicit up-front contract (committed-but-unbuilt designs marked 🚧), tightens the core/light-domain boundary in both directions, and corrects the now-stale "three UI files" claim across the docs. Docs / CI: - architecture.md: added a 🚧 legend (designed, not implemented yet, high-prio for release 2) and applied it to the two-core double-buffer handover, multi-device clock sync, light distribution, and multi-layer composition — written in their proper sections rather than a catch-all "undesigned" list. - architecture.md: corrected the "no locks on the hot path" overclaim (single-threaded today; the cross-core hand-off needs an atomic double-buffer swap, scoped lock-free pull to the small-POD-struct case only); first-mention links for MoonModule / Scheduler / controls / UI / ModuleFactory / check_platform_boundary.py; explained "the engine" as the running module tree; clarified markWiredByCode / setLoadAllHook; fixed the Olimex-runs-all-four claim (Gateway runs the two eth variants; S3 firmware is S3-only); "32 channels per light" → runtime uint8_t (1–255), no pre-allocated array. - architecture.md: pulled light-domain specifics out of core sections (brightness/LUT examples) and moved the discovery + clock-sync mechanism into a core § Multi-device runtime, leaving only the light payoff in § Multi-device sync; moved per-module reporting (classSize/dynamicBytes/loopTimeUs) to core as a base-class feature. - "Three hand-maintained UI files" was stale — src/ui embeds five (index.html, app.js, style.css, preview3d.js, install-picker.js). Fixed in architecture.md, ui.md (×3), building.md (ui_embed inputs), performance.md (embedded-assets row). - release-notes-v1.0.0: compressed "Under the hood" (was near-verbatim README) to a summary + link, keeping the release-worthy test-layers and built-by-agents highlights; dropped the stale RMT/SPI mention to match README. - README: "Up to 16,384 LEDs (other devices even more)", Art-Net/DMX wording, "native LED drivers", pipeline "send it to Art-Net, and save it", dropped the 2.0-item aside and the (beta) label. Reviews: - 👤 Product-owner doc review across architecture.md, README, release notes, ui.md — all items processed (linking, boundary, 🚧 marking, stale-claim fixes). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A staged handoff plan for moving the repo from the ewowi personal account to the MoonModules org and cutting the web-installer URLs over to moonmodules.org. Written for a fresh Claude Code session in the post-transfer clone, which won't have the planning context. Docs / CI: - docs/history/repo-transfer.md: new runbook. Two-stage plan (rename repo references first, prove it works via GitHub's 301 redirect, then cut installer URLs to the canonical moonmodules.org as the one CORS-sensitive step), pre-transfer baselines to diff against, exact rewrite scope (~82 occ/28 files for ewowi/projectMM, ~11/9 for ewowi.github.io), the Pages setup (Source=Actions, custom domain blank — and why it differs from MoonLight's branch deploy), the do-not-rewrite exclusions (ewowi/StarLight, projectMM-v1/v2, author names, and this file itself), and the Stage-3 release finish. - docs/history/README.md: index the runbook under a new "Runbooks" heading. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #14 on the same
release-prepbranch. Pure docs + scripts — nosrc/,test/,CMakeLists, orlibrary.jsontouched, so only the spec-check commit gate applies (passing).What landed
Provenance (README + release notes)
Spec simplification (
docs/moonmodules, ~3,400 → ~2,000 lines, no info lost).h(method signatures, control mechanics, validation rules) across all 40 spec pages; kept wire contracts, cross-domain wiring, and prior art per the CLAUDE.md spec-doc rule.leddriver-analysis-{top-down,bottom-up}.mdtodocs/backlog/(forward-looking design studies, not module specs); repointed the architecture.md link and internal relative links.Source links + enforcement
## Sourcesection to every spec page linking back to its.h/.cpp(UI + LightConfig to their multi-file sources).check_specs.pynow enforces the contract: every spec must carry a## Sourcesection whose relative links resolve — catches renamed-source drift and Source-less new pages at commit gate 1.Checks
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation