docs(spec): modern web guidance, align with the approved plan (one fetch mode, one mwg link, index summaries)
This commit is contained in:
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.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user