docs(shield): add LLD template sample for Bytebite user signup#43
Open
ashwinimanoj wants to merge 1 commit into
Open
docs(shield): add LLD template sample for Bytebite user signup#43ashwinimanoj wants to merge 1 commit into
ashwinimanoj wants to merge 1 commit into
Conversation
Adds a fully-fleshed sample LLD as a reference for a future Shield LLD-template feature. Uses a fictional food-delivery user-signup feature (Postgres + Redis) so all 14 sections have realistic content. Shape: - 12 always-on sections (Overview, Scope, Module layout, Data model, API contracts, Sequence flows, Error handling, Concurrency, Observability, Performance & scaling, Open questions, Changelog) - 2 promote-on-demand sections (Configuration, Security & privacy) - Stable kebab-case anchors per section + sub-section so plan.json stories can reference them via lld_refs - Mermaid sequence diagrams (light theme via CDN) - Performance & scaling is structured into 8 forced-concrete subsections to prevent vague-prose drift - Changelog ties each LLD edit back to a story ID Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ashwinimanoj
added a commit
that referenced
this pull request
May 29, 2026
Two-pathway design: human-invoked /lld <component> writes docs/lld/<component>.md; TRD-driven /plan drafts to docs/shield/<feature>/lld-<component>.md and /implement promotes at milestone close. Two templates (backend pinned to PR #43, infra adapted to declarative IaC). Schema 1.4 -> 1.5 with lld_components[] registry, milestones[].touches_lld[] rollup, and required design_refs[].component when doc==lld. Liberal error handling with auto-heal + audit trails. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ashwinimanoj
added a commit
that referenced
this pull request
May 29, 2026
M1 scope: Path A working end-to-end. 15 tasks across schema bump (1.4 -> 1.5), slug allow-lists (backend + infra), templates (PR-#43-pinned backend; 14-section infra), lld-docs skill, /lld command, and positive eval coverage. M2 (TRD-driven authoring at /plan + promotion at /implement) and M3 (review wiring + version bump + CHANGELOG) ship as separate plans. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ashwinimanoj
added a commit
that referenced
this pull request
May 29, 2026
…lug allow-lists - Backend: 14 sections, 2 promote-on-demand (§9 Configuration, §11 Security & privacy), 8 forced subsections under §12 Performance & scaling. Pinned to PR #43 Bytebite sample. - Infra: 14 sections, 2 promote-on-demand (§7 Security posture, §11 Migration & cutover), 6 forced subsections under §12 Validation. Adapted to declarative IaC. - Source of truth for the /lld emitter (lld-docs SKILL.md) and the lld-docs eval. - Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m1-foundation.md (Phase 2) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ashwinimanoj
added a commit
that referenced
this pull request
May 29, 2026
* feat(shield/plan): TRD §10 single-source-of-truth from plan.json milestones[]
§10 Milestones body is now RENDERED from plan.json milestones[] rather than
hand-generated alongside the sidecar. The two stores that used to co-exist
without a validator binding them are now upstream (plan.json) and downstream
(trd.md §10 between BEGIN/END markers).
Components
----------
- shield/scripts/render_trd_section.py — deterministic renderer (id-sort,
dep-string, idempotency, empty-milestones opt-out marker). Seam for
§5/§7/§11 fan-out in future work.
- shield/scripts/validate_trd.py — new checks: milestone_drift (Critical),
unbounded_markers:milestones, missing_sidecar. Sibling plan.json
auto-default; --sidecar override. Back-compat preserved: TRDs without
BEGIN markers skip the new check.
- shield/skills/general/plan-docs/SKILL.md step 6 — instructs /plan to
inject the rendered §10 marker-wrapped output verbatim.
- shield/skills/general/plan-docs/trd-template.md §10 — prose template
replaced with a render directive (do not hand-edit; edit plan.json + rerun).
Eval coverage (CLAUDE.md mandate)
---------------------------------
- 10 unit tests for the renderer (test_render_trd_section.py)
- 5 unit tests for the validator's drift surface (test_validate_trd_drift.py)
- 3 new shield/evals/plan-trd.yaml cases + fixtures:
milestone-rendered-pass (positive)
milestone-drift (negative -> milestone_drift)
milestone-unbounded-markers (negative -> unbounded_markers:milestones)
- Full eval suite: 22/22 pass (19 existing + 3 new — back-compat preserved).
Drive-by fixes
--------------
- shield/scripts/validate_trd.py + render_trd_section.py marked +x in the
index so the check-shebang-scripts-are-executable hook stops warning.
- .pre-commit-config.yaml eval-format exclude extended with
'[^/]+/fixtures/' so any per-suite fixtures/ dir is recognised as test
data, not an LLM-eval doc.
RED→GREEN paper trail
---------------------
- test_render_trd_section.py started RED (ModuleNotFoundError) ->
10/10 GREEN after render_trd_section.py landed.
- test_validate_trd_drift.py started 3-RED (drift / unbounded /
missing-sidecar undetected) -> 5/5 GREEN after validator extension.
Smoke test
----------
Rendered the real 3-milestone backlog plan.json (from feat/shield-backlog),
confirmed byte-identical second render (idempotency), stitched into a
positive-backend TRD shell -> validate_trd.py exit 0.
First of the planned TRD<->sidecar drift fixes. §5 (functional reqs),
§7 (high-level design components), and §11 (APIs) can fan out from the
same render_trd_section.py seam.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(devx): doc-drift Stop hook + artifacts.md updates
Project-internal Stop hook that prints a soft reminder when a plugin
asset moves without its documentation. Declarative source→docs rules
in .claude/hooks/doc-drift-map.yaml; advisory only — exit 0 always,
never blocks Claude or git commit.
Components
----------
- .claude/hooks/doc-drift-map.yaml — rules: skills/SKILL.md, commands,
agents, scripts → shield/docs/artifacts.md + shield/README.md.
- .claude/hooks/check-doc-drift.py — reads the map, walks
`git diff --name-only HEAD` plus untracked files, emits one stderr
block per drifted rule. Custom git-glob matcher (`*` is segment-only,
`**` is cross-directory; `fnmatch` and `PurePath.match` are both
insufficient on their own). Test files (test_*.py, *_test.py),
*.lock, *.tmp, __init__.py filtered as noise.
- .claude/hooks/test_check_doc_drift.py — 10 tests covering the matcher,
noise filter, co-modification clearing the hint, and one end-to-end
integration test against a tempdir git repo. All green.
- .claude/settings.json — Stop hook registered under hooks.Stop[]
(preserves the existing enabledPlugins entry).
- shield/docs/artifacts.md — TRD §10 SSoT note under `trd.md`
(renderer + validator from c410447) plus new "Project-internal QA"
section documenting the hook.
Design rationale
----------------
Prose docs (artifacts.md, README) cannot be safely auto-edited by a
hook — the edit logic ends up either brittle templating or recursive
LLM editing that damages hand-curated content. The reliable pattern is:
deterministic renderer + drift validator for *programmatic* content
(c410447 did this for TRD §10), and a reminder hook for *prose*. This
commit ships the latter.
Scope is wide on first install (every plugin-asset glob → primary
catalog docs). Narrow it later if noise outweighs value.
Smoke verified in-session: new `shield/skills/.../SKILL.md` without
README co-modification → hint fires; co-modify the doc → hint silent;
new test_*.py → silent (noise filter); new file matching no rule →
silent. The harness watcher should pick the new hooks key up since
.claude/settings.json was already present at session start; if not,
opening /hooks once force-reloads the config.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(superpowers/specs): /lld command design spec
Two-pathway design: human-invoked /lld <component> writes docs/lld/<component>.md;
TRD-driven /plan drafts to docs/shield/<feature>/lld-<component>.md and /implement
promotes at milestone close. Two templates (backend pinned to PR #43, infra
adapted to declarative IaC). Schema 1.4 -> 1.5 with lld_components[] registry,
milestones[].touches_lld[] rollup, and required design_refs[].component when
doc==lld. Liberal error handling with auto-heal + audit trails.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(superpowers/plans): /lld M1 foundation implementation plan
M1 scope: Path A working end-to-end. 15 tasks across schema bump (1.4 -> 1.5),
slug allow-lists (backend + infra), templates (PR-#43-pinned backend; 14-section
infra), lld-docs skill, /lld command, and positive eval coverage. M2 (TRD-driven
authoring at /plan + promotion at /implement) and M3 (review wiring + version
bump + CHANGELOG) ship as separate plans.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(superpowers/plans): /lld M2 TRD-driven authoring + promotion plan
M2 scope: /plan emits feature-folder LLD drafts at planning time (Path B)
via the M1 lld-docs skill; /implement gains step 5h to promote drafts to
canonical at milestone close — with fork-drift concurrency check (auto-heal
re-merge), §14 Changelog append, atomic rename, and design_refs[] anchor
back-fill via token-overlap heuristic. 17 tasks across 6 phases. Depends
on M1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(superpowers/plans): /lld M3 review wiring + negative coverage + cutover plan
M3 scope: four new /plan-review rules (touches_lld_drift,
lld_components_integrity, undocumented_lld, lld_draft_review); 19 negative
eval fixtures (8 missing-always-on + 4 missing-forced-subsection + vague-TBD
+ PoD-lifted-vague + component-not-in-registry + touches_lld-drift +
invalid-type + undocumented-LLD + fork-drift-uncaught); CI workflow
(.github/workflows/eval-lld.yml); plugin version bump 2.20.0 -> 2.21.0
plus CHANGELOG covering the full M1+M2+M3 cutover surface. 17 tasks
across 7 phases. Depends on M1 + M2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/schema): bump plan-sidecar to 1.5 — lld_components[] + touches_lld[] + required-component-when-doc==lld
- Schema 1.5 adds `lld_components[]` at root and `milestones[].touches_lld[]`;
tightens `design_refs[].component` to required when `doc=="lld"`.
- validate_plan.py gains two structural checks: `touches_lld_drift` (persisted
vs rollup) and `lld_component_missing` (design_refs component not in registry).
- 1.4 sidecars without the new arrays validate as 1.5 (back-compat).
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m1-foundation.md (Phase 1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/schema): lld-sections-{backend,infra}.yaml — 14-section slug allow-lists
- Backend: 14 sections, 2 promote-on-demand (§9 Configuration, §11 Security & privacy),
8 forced subsections under §12 Performance & scaling. Pinned to PR #43 Bytebite sample.
- Infra: 14 sections, 2 promote-on-demand (§7 Security posture, §11 Migration & cutover),
6 forced subsections under §12 Validation. Adapted to declarative IaC.
- Source of truth for the /lld emitter (lld-docs SKILL.md) and the lld-docs eval.
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m1-foundation.md (Phase 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/lld-docs): lld-docs SKILL.md + backend + infra templates + /lld command
- SKILL.md owns draft + merge modes, atomic write contract, provenance stamp,
header metadata, §14 Changelog convention, n/a — <reason> escape, PoD sections.
- Backend + infra templates document the 14-section shape with explicit
{#kebab-case} anchors and forced §12 subsections.
- /lld command is Path A entry (canonical write, type detection from repo
markers, active-feature-folder overlap warning, re-run = edit-in-place).
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m1-foundation.md (Phases 3–5)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/scripts): lld_blob_sha + lld_anchor_heuristic helpers
- lld_blob_sha: thin wrapper over `git hash-object`; /plan captures at draft
time, /implement re-computes at milestone close to detect fork drift.
- lld_anchor_heuristic: Jaccard token-overlap anchor selection for
/implement's design_refs[].anchor_url back-fill. Three match types:
exact-match (Jaccard=1.0), heuristic (>0), fallback (=0 → #overview).
- Tie-break by slug allow-list order.
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m2-trd-driven.md (Phase 1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/plan-docs): /plan Path B — derive lld_components + touches_lld rollup + emit feature-folder LLD drafts
- plan-docs SKILL.md gains two new steps: (1) derive lld_components[]
registry from stories' design_refs[] with inferred type per repo markers;
compute milestones[].touches_lld[] rollup. (2) Invoke lld-docs skill per
registry entry in draft or merge mode; capture fork_blob_sha for
enhancement components.
- /plan command behavior gains steps 12 (derive) and 13 (emit drafts).
- output-paths.yaml registers lld_draft_md (per-feature draft) and
lld_canonical_md (project-level docs/lld/<component>.md).
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m2-trd-driven.md (Phase 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/implement-feature): step 5h — promote feature-folder LLD drafts to canonical at milestone close
- Six sub-steps per component: lookup registry → locate draft (JIT
auto-heal if missing) → fork-drift concurrency check (auto-heal remerge
on drift; abort on conflict) → §14 Changelog row append → atomic promote
draft → docs/lld/<name>.md → back-fill design_refs[] anchor_url via the
lld_anchor_heuristic.
- Milestone-close detection: triggered only on the story-close that takes
every story in the milestone to status==done.
- Just-in-time auto-heal prints a loud audit-trail warning when /plan
didn't produce a draft.
- /implement command behavior gains the new milestone-close step.
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m2-trd-driven.md (Phase 3)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/scripts): run_lld_docs + run_step_5h CLI wrappers
- run_lld_docs.py implements the lld-docs SKILL.md contract: draft (build
skeleton from slug allow-list), merge (no-op — caller pre-copies),
remerge (diff3 three-way merge with conflict-section detection).
- run_step_5h.py implements /implement's step 5h: walk touches_lld,
detect drift via blob_sha, auto-heal remerge or abort with named
conflict sections, append §14 Changelog, atomic promote, back-fill
design_refs anchor_url with match-type counts.
- Both accept --canonical-dir override for isolated eval runs.
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m2-trd-driven.md (Phase 5)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(shield/plan-review): four new LLD rules (0f–0i) + lld_fork_drift_uncaught sub-check
- 0f touches_lld_drift (High): persisted milestones[i].touches_lld[] ≠
rollup of design_refs[].component per milestone.
- 0g lld_components_integrity (High; Medium for fork-drift):
missing-registry-entry, type-enum, duplicate-name, plus
lld_fork_drift_uncaught for fork_blob_sha vs live canonical blob.
- 0h undocumented_lld (Medium): canonical exists but design_refs[].anchor_url
is null — suggested back-fill via lld_anchor_heuristic.
- 0i lld_draft_review (High/Medium/Review): structural rubric on feature-folder
drafts — missing always-on, missing forced subsection, vague TBDs in
always-on, PoD lifted-but-vague.
- Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m3-review-and-cutover.md (Phase 1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(shield/lld-docs): eval suite — 3 positives + 6 Path B + 19 negatives + runner + paper trail
Positives (M1):
- backend-user-service, infra-vpc-module (structurally complete LLDs).
- plan-1.5-with-lld-components (validates via validate_plan.py).
Path B (M2):
- pathB-happy: end-to-end /plan → drafts → /implement → promotion + anchor backfill.
- pathB-fork-drift-clean: drift in §13 (non-overlapping); auto-heal succeeds.
- pathB-fork-drift-conflict: drift in §5 (overlapping); abort with named sections.
- pathB-backfill-{exact,fallback}: 'Data model' → data-model (Jaccard 1.0);
'xyzzy plugh quux' → overview (zero overlap).
- pathB-just-in-time: missing draft → JIT auto-heal + loud audit warning.
Negatives (M3, 19 fixtures):
- 8 missing-always-on (4 backend + 4 infra).
- 4 missing-forced-subsection (2 backend + 2 infra).
- neg-vague-tbd, neg-pod-lifted-vague (structural rubric).
- neg-component-not-in-registry, neg-touches-lld-drift, neg-invalid-type
(plan-validation via validate_plan.py named errors).
- neg-undocumented-lld, neg-fork-drift-uncaught (plan-review-finding rules).
Runner mechanically verifies every fixture in shield/evals/run-lld-docs.py.
RED→GREEN paper trail for M1 + M2 included.
Plan ref: docs/superpowers/plans/2026-05-28-lld-command-m{1,2,3}-*.md (eval coverage)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(shield/lld-docs): gitignore eval pathB-*/out runtime artifacts
The out/ directories under each Path B fixture are regenerated by every
shield/evals/run-lld-docs.py invocation (post-run plan.json + promoted
canonical, for failure-mode inspection). They shouldn't be tracked.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* release(shield 2.21.0): /lld + Path B + step 5h + plan-review LLD rules + eval CI
- .github/workflows/eval-lld.yml runs the lld-docs eval (3 positives + 6
Path B + 19 negatives) and unit tests (validate_plan 1.5, blob_sha,
anchor heuristic) on every PR touching the LLD surface.
- marketplace.json: shield 2.20.0 → 2.21.0 (minor bump — new commands +
new user-visible schema field, no API breakage).
- CHANGELOG entry documents the full M1 + M2 + M3 surface for users.
Plan refs:
docs/superpowers/plans/2026-05-28-lld-command-m1-foundation.md
docs/superpowers/plans/2026-05-28-lld-command-m2-trd-driven.md
docs/superpowers/plans/2026-05-28-lld-command-m3-review-and-cutover.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(shield): complete M2 output-path wiring for LLD registry entries
The M2 cutover (842cade) added lld_draft_md + lld_canonical_md to the
output-paths registry but left three loose ends that the shield-suite +
pre-commit lints caught:
1. shield/commands/lld.md was missing the required YAML frontmatter
(name + description). Caught by CI's shield-suite test 'command
frontmatter valid' — the single failing test on PR #56.
2. registry paths lld_draft_md + lld_canonical_md reference {component}
but the variables: block in shield/schema/output-paths.yaml didn't
declare it. Caught by 'shield output-path lint'.
3. lld_draft_md was declared in the registry but no asset claimed it in
its outputs: block. /plan is the documented emitter (per the registry
comment), so add it to /plan's outputs.
All three are causally the same omission — M2 registered the new paths
but didn't fully wire them into the surrounding lint / frontmatter
contract. This commit finishes the wiring.
Verification:
- bash shield/tests/run-all.sh -> 30/30 passed (was 29/30)
- pre-commit run --files <the three files> -> all hooks pass
(shield output-path lint + shield path-resolver pytest both now Pass)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (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.
Summary
docs/superpowers/specs/2026-05-18-lld-sample.html) as a reference for a future Shield LLD-template feature.plan.jsonstories can reference them vialld_refs.What this is not
docs/superpowers/specs/as a design reference.Test plan
#perf-load,#perf-latency, etc.).🤖 Generated with Claude Code