From 28460c81692fc5a23764a523ec60769cd3d632cc Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 22 Nov 2026 04:07:48 +0100 Subject: [PATCH] docs(spec): modern web guidance, align with the approved plan (one fetch mode, one mwg link, index summaries) --- .../2026-11-21-modern-web-guidance-design.md | 82 +++++++++++-------- 1 file changed, 46 insertions(+), 36 deletions(-) diff --git a/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md b/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md index 8fde2d7..9e8fa01 100644 --- a/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md +++ b/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md @@ -27,18 +27,20 @@ Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0. ### 1. Pinned fetch (`lib/vendor-skills.sh`, new function) -`vendor_pinned_tree [refresh]` reads a new `plugins.lock.json` entry: +`vendor_pinned_tree ` reads a new `plugins.lock.json` entry: ```json "modern-web-guidance": { "source": "https://github.com/GoogleChrome/modern-web-guidance", - "tag": "v1.0.1", "commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65", + "tag": "v1.0.1", + "license": "Apache-2.0 (code), CC-BY 4.0 (guides)", + "managed_by": "git-tree", + "always_on": true, "trees": { - "mwg": ["skills/modern-web-guidance/guides", "LICENSE"], - "chrome-extensions": ["skills/chrome-extensions"] - }, - "always_on": true + "mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE", "README.md": "README.md"}, + "chrome-extensions": {".": "skills/chrome-extensions"} + } } ``` @@ -46,13 +48,16 @@ Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0. `FETCH_HEAD`, then `git rev-parse HEAD` must equal `commit` (else refuse, nothing written). - Copies only the listed repo paths into a staging dir per destination; the upstream `skills/modern-web-guidance/SKILL.md` is never copied. -- For `mwg`: generates `INDEX.md` (one line per guide: `id | category | H1 title`) and an - attribution `NOTICE.md` (source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code). +- For `mwg`: generates `INDEX.md` (one line per guide: `- id | category | summary`, the + summary from the upstream README description, else the guide's H1) and an attribution + `NOTICE.md` (source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code). - Swaps each staging dir into `skills-external/` (old dir removed after the new one is - complete), so guides dropped upstream disappear on a pin bump. -- Install mode skips a complete existing copy at the same commit (marker file - `.vendored-commit`); refresh re-fetches; both install a missing copy (fixes the - "refresh skips absent dirs" gap for this entry). + complete, restored if the swap fails), so guides dropped upstream disappear on a pin bump. +- One mode: a dest whose `.vendored-commit` equals the pin and whose `.vendored-spec` + equals its allowlist is skipped; anything else (absent copy, older pin, edited + allowlist) is fetched. A dest that exists without `.vendored-commit` is never replaced. + A symlink in the fetched content, or a listed path resolving outside the checkout, is + refused with nothing swapped. - Same validation as `vendor_pinned_skills`: `commit` 40 lowercase hex, `source` `https://github.com//`, paths `[A-Za-z0-9._/-]`, no `..`, no leading `/`. A `VENDOR_BASE_URL=file://…` override serves the hermetic suite (same rule as the @@ -60,8 +65,9 @@ Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0. - Both `skills-external/mwg/` and `skills-external/chrome-extensions/` are gitignored (machine-owned, regenerated by the install step, LRN-086). -Callers: `install-plugins.sh` Step 8e (`vendor_pinned_tree modern-web-guidance`) and -`update-all.sh` 7.3 (`… refresh`). The pin moves only by editing the lock entry. +Callers: `install-plugins.sh` Step 8e and `update-all.sh` 7.3, both +`if ! vendor_pinned_tree modern-web-guidance; then warn …; fi` (a fetch failure keeps +the previous copy and the script goes on). The pin moves only by editing the lock entry. ### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on) @@ -72,23 +78,25 @@ Callers: `install-plugins.sh` Step 8e (`vendor_pinned_tree modern-web-guidance`) `find-docs`. `allowed-tools` only pre-approves Read for the invoking turn, it restricts nothing (Claude Code skills docs); the no-npx guarantee rests on the skill's text and the settings soft-deny on undeclared `npx `. -- Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`, - `INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`. +- One tracked relative symlink: `mwg -> ../../skills-external/mwg` (INDEX.md, NOTICE.md, + guides/ behind it). - Workflow in the body: - 1. Read `INDEX.md` whole (210 lines, ~14 KB) and pick the guides by title (Grep and - Glob are absent in some sessions, Read always exists); a body search only when a - text-search tool is at hand. - 2. Read the matching guide(s) and the discipline guide of each category touched (id = - category: html, css, js, forms, accessibility, performance, security, privacy). - 3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line - `npx … retrieve ""` means: find `` in `INDEX.md`, Read - `guides//.md`. Never run npx or any network command for this skill. - 4. Where a guide and a rule of `rules/web-building.md` disagree on how to use the - platform, the guide wins. - 5. End the answer that delivers the front-end change with one line: - `Modern Web Guidance: , ` (or `Modern Web Guidance: checked , none - applied`). No quotes. -- Guides missing (dangling links): say so, remedy `make update`; continue without them. + 1. Read `mwg/INDEX.md` whole (~210 lines, ~39 KB with descriptions) and pick the guides + by summary (Grep and Glob are absent in some sessions, Read always exists); a body + search under `~/.claude/skills/modern-web-guidance/mwg/guides/` only when no summary + fits and a text-search tool is at hand. + 2. Read the matching guide(s). A discipline guide (id = category: html, css, js, forms, + accessibility, performance, security, privacy) only for a new component or page, or + when no specific guide matched: they are long. + 3. A guide line `npx … retrieve ""` means: find `` in `mwg/INDEX.md`, Read + `mwg/guides//.md`. Never run npx or any network command for this skill. + 4. Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule + of `rules/web-building.md` disagree on how to use the platform, the guide wins. An + executor whose closed plan contradicts a guide reports it as an open choice. + 5. The answer that delivers the front-end change (a sub-agent: its report) ends with one + line: `Modern Web Guidance: , ` (or `Modern Web Guidance: checked , + none applied`). No quotes. +- Copy missing (dangling link): say so, remedy `make update`; continue without it. - `test-prompts.json` (darwin convention). ### 3. chrome-extensions (vendored, always on, as is) @@ -121,13 +129,15 @@ No routing row (untracked linked external; a row would reroute the main loop on ### 5. Checks and docs -- `lib/doctor-vendored.sh` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and - its `.vendored-commit` equals the lock commit; `chrome-extensions` link present. +- `lib/doctor-vendored.sh` `check_vendored_trees`: each git-tree dest's `.vendored-commit` + equals the lock commit, else a warning naming `make plugin`; never an error, and doctor + survives `set -euo pipefail` when a vendored copy is missing. - `lib/tests/vendor-tree.test.sh` on a local git fixture: fetch at the pinned commit, - refuse a mismatching commit, whitelist only (no upstream SKILL.md), INDEX generation, - prune of a dropped guide on refresh, install of an absent copy in refresh mode, path - validation. `lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to - run, Read only, no row, links, disclosure, and the rule wiring. + refuse a commit not upstream, allowlist only (no upstream SKILL.md), INDEX generation, + prune of a dropped guide on a pin bump, install of an absent copy, path validation, + allowlist edit re-fetched, foreign dest kept, symlinks refused. + `lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to run, Read + only, no row, the `mwg` link, disclosure, and the rule wiring. - README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an assumed exception to BDR-056.