feat(shield): single canonical output — Markdown source, HTML as a build artifact#65
Merged
Conversation
… build artifact Design spec: Markdown is the one committed/authored output; HTML + site assets become local, gitignored build artifacts regenerated on demand by a render-output.sh build script, triggered by a thin /shield render command. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Six tasks: complete rerender_all coverage (enhanced-*/detailed/*), add render-output.sh build script, /shield render command, gitignore+untrack HTML, prose updates, version bump. Each task is TDD with an executable eval. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ender Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Parentheses in a sequenceDiagram participant alias ("caller (/backlog add
or skill)") break Mermaid's parser ("Syntax error in text"). Rephrase the
alias without parens. Fixed in both the canonical docs/lld/ copy and the
docs/shield/ draft.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
GitHub's parser pinned the error to diagram line 10: the ';' in "append entry (...); validate in-memory doc" is treated as a statement separator, so Mermaid tries to parse "validate in-memory doc" as a new statement and fails expecting an arrow. Replace ';' with 'then'. (The earlier alias-parens change was not the cause.) 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.
What & why
Shield wrote every artifact twice and committed both: the authored
.mdand an HTML mirror underoutputs/(plus the root dashboard assets). 41 HTML files were tracked in git alongside their Markdown — confusing, doubled diffs, and a standing drift risk, since HTML carries zero unique information (it's rendered purely from Markdown).This makes Markdown the single canonical, committed output. HTML + site assets become local build artifacts — gitignored and regenerated on demand. The browsable dashboard (the real consumer — people open it locally) is preserved; it's just built, not committed.
Design + plan:
docs/superpowers/specs/2026-06-08-shield-single-canonical-output-design.md,docs/superpowers/plans/2026-06-08-shield-single-canonical-output.md.Changes
rerender_all.pynow renders the complete HTML set — includingenhanced-*.mdanddetailed/*.mdreviewer docs it previously skipped (so nothing is lost when HTML stops being committed).render-output.sh— one build script: renders all pages (rerender_all.py) then writes the dashboard + shared assets (write_shield_assets.py). Idempotent./shield render— thin command that triggers the build script..gitignore— demotesoutputs/trees + rootindex.html/manifest.js/css/js to build artifacts; the 41 tracked HTML files + root assets aregit rm --cached(kept on disk).output-paths.yaml, session-start hook,artifacts.md,manifest-schema.mdnow describe HTML as a gitignored build artifact pointing at/shield render.2.28.0inmarketplace.json(no rootpyproject.toml).Eval coverage (per CLAUDE.md — required for plugin asset changes)
Three executable evals, all passing (
5 passed):test_rerender_all.py— regression: enhanced-* / detailed/* now render.test_render_output.py— end-to-end build produces pages and dashboard assets; errors on a bad dir.test_gitignore_html_artifacts.py—.gitignorecovers the artifacts and no Shield HTML is tracked.The
/shield rendercommand is a thin trigger fully exercised bytest_render_output.py.Verification
pytest test_rerender_all.py test_render_output.py test_gitignore_html_artifacts.py→ 5 passedgit ls-files 'docs/shield/**/*.html'→ 0🤖 Generated with Claude Code