docs(spec): modern web guidance, align with the approved plan (one fetch mode, one mwg link, index summaries)

This commit is contained in:
bchanot committed 2026-11-22 04:07:48 +01:00
1 parent d74dd2c8fa
commit 28460c8169
1 file changed
+46 -36
@@ -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) ### 1. Pinned fetch (`lib/vendor-skills.sh`, new function)
`vendor_pinned_tree <lock-key> [refresh]` reads a new `plugins.lock.json` entry: `vendor_pinned_tree <lock-key>` reads a new `plugins.lock.json` entry:
```json ```json
"modern-web-guidance": { "modern-web-guidance": {
"source": "https://github.com/GoogleChrome/modern-web-guidance", "source": "https://github.com/GoogleChrome/modern-web-guidance",
"tag": "v1.0.1",
"commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65", "commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65",
"tag": "v1.0.1",
"license": "Apache-2.0 (code), CC-BY 4.0 (guides)",
"managed_by": "git-tree",
"always_on": true,
"trees": { "trees": {
"mwg": ["skills/modern-web-guidance/guides", "LICENSE"], "mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE", "README.md": "README.md"},
"chrome-extensions": ["skills/chrome-extensions"] "chrome-extensions": {".": "skills/chrome-extensions"}
}, }
"always_on": true
} }
``` ```
@@ -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). `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 - Copies only the listed repo paths into a staging dir per destination; the upstream
`skills/modern-web-guidance/SKILL.md` is never copied. `skills/modern-web-guidance/SKILL.md` is never copied.
- For `mwg`: generates `INDEX.md` (one line per guide: `id | category | H1 title`) and an - For `mwg`: generates `INDEX.md` (one line per guide: `- id | category | summary`, the
attribution `NOTICE.md` (source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code). 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/<dest>` (old dir removed after the new one is - Swaps each staging dir into `skills-external/<dest>` (old dir removed after the new one is
complete), so guides dropped upstream disappear on a pin bump. complete, restored if the swap fails), so guides dropped upstream disappear on a pin bump.
- Install mode skips a complete existing copy at the same commit (marker file - One mode: a dest whose `.vendored-commit` equals the pin and whose `.vendored-spec`
`.vendored-commit`); refresh re-fetches; both install a missing copy (fixes the equals its allowlist is skipped; anything else (absent copy, older pin, edited
"refresh skips absent dirs" gap for this entry). 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` - Same validation as `vendor_pinned_skills`: `commit` 40 lowercase hex, `source`
`https://github.com/<o>/<r>`, paths `[A-Za-z0-9._/-]`, no `..`, no leading `/`. A `https://github.com/<o>/<r>`, paths `[A-Za-z0-9._/-]`, no `..`, no leading `/`. A
`VENDOR_BASE_URL=file://…` override serves the hermetic suite (same rule as the `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 - Both `skills-external/mwg/` and `skills-external/chrome-extensions/` are gitignored
(machine-owned, regenerated by the install step, LRN-086). (machine-owned, regenerated by the install step, LRN-086).
Callers: `install-plugins.sh` Step 8e (`vendor_pinned_tree modern-web-guidance`) and Callers: `install-plugins.sh` Step 8e and `update-all.sh` 7.3, both
`update-all.sh` 7.3 (`… refresh`). The pin moves only by editing the lock entry. `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) ### 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 `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 nothing (Claude Code skills docs); the no-npx guarantee rests on the skill's text and
the settings soft-deny on undeclared `npx <pkg>`. the settings soft-deny on undeclared `npx <pkg>`.
- Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`, - One tracked relative symlink: `mwg -> ../../skills-external/mwg` (INDEX.md, NOTICE.md,
`INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`. guides/ behind it).
- Workflow in the body: - Workflow in the body:
1. Read `INDEX.md` whole (210 lines, ~14 KB) and pick the guides by title (Grep and 1. Read `mwg/INDEX.md` whole (~210 lines, ~39 KB with descriptions) and pick the guides
Glob are absent in some sessions, Read always exists); a body search only when a by summary (Grep and Glob are absent in some sessions, Read always exists); a body
text-search tool is at hand. search under `~/.claude/skills/modern-web-guidance/mwg/guides/` only when no summary
2. Read the matching guide(s) and the discipline guide of each category touched (id = fits and a text-search tool is at hand.
category: html, css, js, forms, accessibility, performance, security, privacy). 2. Read the matching guide(s). A discipline guide (id = category: html, css, js, forms,
3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line accessibility, performance, security, privacy) only for a new component or page, or
`npx … retrieve "<id>"` means: find `<id>` in `INDEX.md`, Read when no specific guide matched: they are long.
`guides/<category>/<id>.md`. Never run npx or any network command for this skill. 3. A guide line `npx … retrieve "<id>"` means: find `<id>` in `mwg/INDEX.md`, Read
4. Where a guide and a rule of `rules/web-building.md` disagree on how to use the `mwg/guides/<category>/<id>.md`. Never run npx or any network command for this skill.
platform, the guide wins. 4. Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule
5. End the answer that delivers the front-end change with one line: of `rules/web-building.md` disagree on how to use the platform, the guide wins. An
`Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>, none executor whose closed plan contradicts a guide reports it as an open choice.
applied`). No quotes. 5. The answer that delivers the front-end change (a sub-agent: its report) ends with one
- Guides missing (dangling links): say so, remedy `make update`; continue without them. line: `Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>,
none applied`). No quotes.
- Copy missing (dangling link): say so, remedy `make update`; continue without it.
- `test-prompts.json` (darwin convention). - `test-prompts.json` (darwin convention).
### 3. chrome-extensions (vendored, always on, as is) ### 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 ### 5. Checks and docs
- `lib/doctor-vendored.sh` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and - `lib/doctor-vendored.sh` `check_vendored_trees`: each git-tree dest's `.vendored-commit`
its `.vendored-commit` equals the lock commit; `chrome-extensions` link present. 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, - `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, refuse a commit not upstream, allowlist only (no upstream SKILL.md), INDEX generation,
prune of a dropped guide on refresh, install of an absent copy in refresh mode, path prune of a dropped guide on a pin bump, install of an absent copy, path validation,
validation. `lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to allowlist edit re-fetched, foreign dest kept, symlinks refused.
run, Read only, no row, links, disclosure, and the rule wiring. `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 - README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an
assumed exception to BDR-056. assumed exception to BDR-056.