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)
`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
"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/<dest>` (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/<o>/<r>`, 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 <pkg>`.
- 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 "<id>"` means: find `<id>` in `INDEX.md`, Read
`guides/<category>/<id>.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: <id>, <id>` (or `Modern Web Guidance: checked <topics>, 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 "<id>"` means: find `<id>` in `mwg/INDEX.md`, Read
`mwg/guides/<category>/<id>.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: <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).
### 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.