Author SHA1 Message Date
bchanot ea1d5ab400 docs(plan): modern web guidance implementation plan 2026-11-21 23:29:31 +01:00
bchanot 7cc1e6c42d docs(spec): modern web guidance design 2026-11-21 23:18:50 +01:00
2 changed files with 935 additions and 0 deletions

No files matched your search

@@ -0,0 +1,812 @@
# Modern Web Guidance Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Vendor Google's Modern Web Guidance (guides + chrome-extensions) at a pinned commit and make every front-end task consult it through our own local, network-free skill.
**Architecture:** A new `vendor_pinned_tree` helper in `lib/vendor-skills.sh` fetches one pinned commit with git, copies an allowlist of upstream paths into `skills-external/<dest>/`, generates `INDEX.md` / `NOTICE.md` / `.vendored-commit`, and swaps the result in. Our tracked skill `skills/modern-web-guidance/` reaches the guides through relative symlinks and only uses Read/Grep/Glob. `rules/web-building.md` and `site-motion` send front-end work to the skill.
**Tech Stack:** bash, python3 (lock parsing, argv only), git, markdown.
**Spec:** `docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md`
**Contract:** `.claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md`
Out of this plan, done by `/ship-feature` itself: README / USAGE / CHANGELOG (STEP 8 doc sync) and the BDR recording the decisions, including the fixed pin as an exception to BDR-056 (STEP 7).
## Global Constraints
- Pin: tag `v1.0.1`, commit `64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65`, source `https://github.com/GoogleChrome/modern-web-guidance`.
- No path of this feature runs `npx`, `pnpx` or the `modern-web-guidance` CLI; the skill's `allowed-tools` is `Read, Grep, Glob` only.
- The upstream `skills/modern-web-guidance/SKILL.md` is never copied into `skills-external/`.
- Vendored text is never edited (BDR-104/106).
- `CLAUDE.global.md`, `settings.json`, `CLAUDE.md` are not modified (BDR-028, 320-line budget).
- `rules/web-building.md`: the heading line `## Design work — full toolchain (tiered by scope)` and the line `- The vendored stack members route to \`reflect\` (high) through their` stay byte-identical (doctrine-citers and effort-routing locks, LRN-166).
- Tests run only through `make test suite=<file>` (hermetic git config).
- `VENDOR_BASE_URL` override is honored only when it starts with `file://` (same rule as `vendor_pinned_skills`).
## Review Focus
1. Fetch failure or a commit that is not the pin → rc 1, `skills-external/` unchanged (no half-swapped dest).
2. A pin bump that drops a guide upstream → the guide disappears locally after refresh (whole-dir swap, not file overwrite).
3. A machine that never ran `make plugin` → `make update` (refresh mode) installs the copy instead of skipping it.
4. A lock entry with `..`, an absolute path or a bad dest name → rejected before any fetch.
5. Fresh clone before install → our skill's symlinks dangle; the skill says "run `make update`" and doctor warns (no error).
---
### Task 1: `vendor_pinned_tree` fetcher + hermetic suite
**Files:**
- Modify: `lib/vendor-skills.sh` (append after `vendor_pinned_skills`)
- Create: `lib/tests/vendor-tree.test.sh`
**Interfaces:**
- Produces: `vendor_pinned_tree <lock-key> [refresh]` (rc 0 ok/already at pin, rc 1 any failure, nothing changed); `_vendor_read_tree_lock <lockfile> <key>` (stdout lines: source, commit, tag, license, then `<dest>\t<target>\t<repo-path>`); lock entry shape:
`{"source","commit","tag","license","trees":{"<dest>":{"<target>|.":"<repo-path>"}},"managed_by":"git-tree","always_on":true}`.
- Writes per dest: `skills-external/<dest>/.vendored-commit` (the commit), `NOTICE.md`, and `INDEX.md` when the dest holds `guides/`.
- [ ] **Step 1: Write the failing test** — create `lib/tests/vendor-tree.test.sh`:
```bash
#!/usr/bin/env bash
# lib/tests/vendor-tree.test.sh — lib/vendor-skills.sh vendor_pinned_tree():
# pinned git fetch from a file:// fixture repo, allowlisted copy, INDEX /
# NOTICE / .vendored-commit generation, upstream SKILL.md never copied,
# commit mismatch refused with nothing written, refresh prunes a guide
# dropped upstream, refresh installs an absent copy, install mode skips a
# copy already at the pin, unsafe lock paths rejected before any fetch.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
LIB="$ROOT/lib/vendor-skills.sh"
pass=0; fail=0
check_bool() {
if [ "$2" = 1 ]; then pass=$((pass+1)); echo "PASS $1"
else fail=$((fail+1)); echo "FAIL $1"; fi
}
WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
UP="$WORK/upstream"; REPO="$WORK/repo"
mkdir -p "$REPO/skills-external"
g() { git -C "$UP" -c user.email=t@t -c user.name=t "$@"; }
# Fixture upstream: modern-web-guidance layout (SKILL.md + guides/) and a
# chrome-extensions skill with a references/ file.
mkdir -p "$UP/skills/modern-web-guidance/guides/css" \
"$UP/skills/modern-web-guidance/guides/html" \
"$UP/skills/chrome-extensions/references/extensions"
printf 'npx -y modern-web-guidance@latest search\n' \
> "$UP/skills/modern-web-guidance/SKILL.md"
printf '# Animate to intrinsic sizes\nbody\n' \
> "$UP/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md"
printf '# Dialog\nbody\n' > "$UP/skills/modern-web-guidance/guides/html/dialog.md"
printf '# Old guide\nbody\n' > "$UP/skills/modern-web-guidance/guides/html/old-guide.md"
printf -- '---\nname: chrome-extensions\n---\nbody\n' \
> "$UP/skills/chrome-extensions/SKILL.md"
printf 'ref\n' > "$UP/skills/chrome-extensions/references/extensions/api.md"
printf 'Apache License\n' > "$UP/LICENSE"
git init -q "$UP"; g add -A; g commit -qm one
SHA1="$(git -C "$UP" rev-parse HEAD)"
write_lock() { # write_lock <commit> [extra-tree-json]
cat > "$REPO/plugins.lock.json" <<JSON
{
"mwg-key": {
"source": "https://github.com/acme/mwg",
"commit": "$1",
"tag": "v1.0.1",
"license": "Apache-2.0 (code), CC-BY 4.0 (guides)",
"managed_by": "git-tree",
"trees": {
"mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"},
"chrome-extensions": {".": "skills/chrome-extensions"}${2:-}
}
}
}
JSON
}
run() { # run <args…> — sources the lib in a subshell against the fixture
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$UP"
# shellcheck disable=SC1090
source "$LIB"; vendor_pinned_tree "$@" ) >"$WORK/out" 2>&1
}
# T1 install: allowlisted copy, generated files, no upstream SKILL.md.
write_lock "$SHA1"; run mwg-key; rc=$?
M="$REPO/skills-external/mwg"; C="$REPO/skills-external/chrome-extensions"
check_bool T1-rc "$([ $rc -eq 0 ] && echo 1)"
check_bool T1-guide "$([ -f "$M/guides/html/dialog.md" ] && echo 1)"
check_bool T1-license "$([ -f "$M/LICENSE" ] && echo 1)"
check_bool T1-no-upstream-skill "$([ ! -e "$M/SKILL.md" ] && echo 1)"
check_bool T1-index-line "$(grep -qx -- '- dialog | html | Dialog' "$M/INDEX.md" && echo 1)"
check_bool T1-index-count "$([ "$(grep -c '^- ' "$M/INDEX.md")" -eq 3 ] && echo 1)"
check_bool T1-notice "$(grep -q "$SHA1" "$M/NOTICE.md" && grep -q 'CC-BY 4.0' "$M/NOTICE.md" && echo 1)"
check_bool T1-marker "$([ "$(cat "$M/.vendored-commit")" = "$SHA1" ] && echo 1)"
check_bool T1-ce-contents "$([ -f "$C/SKILL.md" ] && [ -f "$C/references/extensions/api.md" ] && echo 1)"
check_bool T1-no-stage-left "$([ -z "$(ls -A "$REPO/skills-external" | grep '^\.vendor-stage')" ] && echo 1)"
# T2 install mode at the pin: skip, no fetch (source made unreachable).
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$WORK/nowhere"
source "$LIB"; vendor_pinned_tree mwg-key ) >"$WORK/out" 2>&1; rc=$?
check_bool T2-skip-rc "$([ $rc -eq 0 ] && grep -q 'already at pin' "$WORK/out" && echo 1)"
# T3 refresh after an upstream drop: old-guide disappears locally.
g rm -q skills/modern-web-guidance/guides/html/old-guide.md; g commit -qm two
SHA2="$(git -C "$UP" rev-parse HEAD)"
write_lock "$SHA2"; run mwg-key refresh; rc=$?
check_bool T3-rc "$([ $rc -eq 0 ] && echo 1)"
check_bool T3-pruned "$([ ! -e "$M/guides/html/old-guide.md" ] && echo 1)"
check_bool T3-marker "$([ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T4 refresh installs an absent copy (never-installed machine).
rm -rf "$REPO/skills-external/chrome-extensions"
run mwg-key refresh; rc=$?
check_bool T4-installs-absent "$([ $rc -eq 0 ] && [ -f "$C/SKILL.md" ] && echo 1)"
# T5 commit not in upstream: rc 1, existing copy untouched.
BAD="0123456789abcdef0123456789abcdef01234567"
write_lock "$BAD"; run mwg-key refresh; rc=$?
check_bool T5-rc "$([ $rc -eq 1 ] && echo 1)"
check_bool T5-untouched "$([ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T6 unsafe repo path rejected before any fetch.
write_lock "$SHA2" ', "evil": {"x": "../etc"}'; run mwg-key; rc=$?
check_bool T6-traversal "$([ $rc -eq 1 ] && grep -q "rejected" "$WORK/out" && [ ! -e "$REPO/skills-external/evil" ] && echo 1)"
# T7 bad dest name rejected.
write_lock "$SHA2" ', "a/b": {"x": "LICENSE"}'; run mwg-key; rc=$?
check_bool T7-dest "$([ $rc -eq 1 ] && grep -q "rejected" "$WORK/out" && echo 1)"
# T8 a missing upstream path aborts with nothing swapped.
write_lock "$SHA2" ', "ghost": {"x": "no/such/path"}'; run mwg-key refresh; rc=$?
check_bool T8-missing-path "$([ $rc -eq 1 ] && [ ! -e "$REPO/skills-external/ghost" ] && [ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T9 a non-file:// VENDOR_BASE_URL is ignored with a warn.
write_lock "$SHA2"
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="https://evil.example"
source "$LIB"; vendor_pinned_tree mwg-key ) >"$WORK/out" 2>&1
check_bool T9-override-ignored "$(grep -q 'VENDOR_BASE_URL ignored' "$WORK/out" && echo 1)"
echo "vendor-tree: $pass pass, $fail fail"
[ "$fail" -eq 0 ]
```
T9 note: with the override ignored the source becomes the real `https://github.com/acme/mwg` URL; the copy is already at the pin, so install mode returns "already at pin" before any fetch. The warn is printed first only if the override check runs before the at-pin skip — the implementation below runs the override check first, on purpose.
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/vendor-tree.test.sh`
Expected: FAIL lines (`vendor_pinned_tree: command not found` in `$WORK/out`), last line `1 suite(s) red: lib/tests/vendor-tree.test.sh`.
- [ ] **Step 3: Implement** — append to `lib/vendor-skills.sh`:
```bash
# ============================================================
# vendor_pinned_tree — whole upstream trees at one pinned commit, by git
# ============================================================
# Lock entry shape (plugins.lock.json, "managed_by": "git-tree"):
# "<key>": {
# "source": "https://github.com/<owner>/<repo>",
# "commit": "<40-hex sha>", "tag": "<tag name, informational>",
# "license": "<one-line license note>",
# "trees": { "<dest>": { "<target>" | ".": "<repo path>", ... }, ... }
# }
# Each <dest> becomes skills-external/<dest>/. "<target>": "<path>" copies
# the repo path as <dest>/<target>; ".": "<path>" copies the path's
# contents into <dest>/. Only listed paths are copied (allowlist). The
# fetch is one `git fetch --depth 1 <source> <commit>`; HEAD must equal
# the pin or nothing is written. Every dest is staged complete under
# skills-external/.vendor-stage.<pid>/, then swapped in whole, so a file
# dropped upstream disappears on a pin bump. Per dest it writes
# .vendored-commit, NOTICE.md, and INDEX.md when the dest holds guides/.
# Install mode skips when every dest is already at the pin; refresh
# re-fetches; both install a missing copy.
# _vendor_read_tree_lock <lockfile> <key> — prints source, commit, tag,
# license, then one "<dest>\t<target>\t<path>" line per item (sorted).
# rc 1 silent when the entry is absent or incomplete; rc 1 with one
# "INVALID\t<field>=<value>" or "INVALID\t<value>" line on a bad field.
_vendor_read_tree_lock() {
python3 - "$1" "$2" <<'PY'
import json, re, sys
SAFE = re.compile(r'^[A-Za-z0-9._/-]+$')
NAME = re.compile(r'^[A-Za-z0-9_-][A-Za-z0-9._-]*$')
COMMIT_RE = re.compile(r'^[0-9a-f]{40}$')
SOURCE_RE = re.compile(
r'^https://github\.com/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/?$')
NOTE_RE = re.compile(r'^[A-Za-z0-9 .,()/+-]*$')
def unsafe(value):
return ".." in value or value.startswith("/") or not SAFE.fullmatch(value)
def bad(text):
print(f"INVALID\t{text}")
sys.exit(1)
lockfile, key = sys.argv[1], sys.argv[2]
with open(lockfile) as f:
entry = json.load(f).get(key, {})
source, sha = entry.get("source", ""), entry.get("commit", "")
tag, note = entry.get("tag", ""), entry.get("license", "")
trees = entry.get("trees", {})
if not source or not sha or not isinstance(trees, dict) or not trees:
sys.exit(1)
if not COMMIT_RE.fullmatch(sha):
bad(f"commit={sha}")
if not SOURCE_RE.fullmatch(source):
bad(f"source={source}")
if tag and unsafe(tag):
bad(f"tag={tag}")
if not isinstance(note, str) or not NOTE_RE.fullmatch(note):
bad(f"license={note}")
rows = []
for dest, items in trees.items():
if not NAME.fullmatch(dest) or not isinstance(items, dict) or not items:
bad(f"dest={dest}")
for target, path in items.items():
if target != "." and not NAME.fullmatch(target):
bad(target)
if not isinstance(path, str) or unsafe(path):
bad(str(path))
rows.append((dest, target, path))
print(source)
print(sha)
print(tag)
print(note)
for dest, target, path in sorted(rows):
print(f"{dest}\t{target}\t{path}")
PY
}
# _vendor_tree_current <root> <sha> <dests> — rc 0 when every dest
# (newline-separated) holds a .vendored-commit equal to <sha>.
_vendor_tree_current() {
local root="$1" sha="$2" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
[ "$(cat "$root/$dest/.vendored-commit" 2>/dev/null)" = "$sha" ] \
|| return 1
done <<<"$3"
}
# _vendor_tree_checkout <dir> <url> <sha> — shallow fetch of <sha> into a
# fresh repo at <dir>; rc 0 only when the checked-out HEAD is <sha>.
_vendor_tree_checkout() {
local dir="$1" url="$2" sha="$3"
git init -q "$dir" 2>/dev/null || return 1
GIT_TERMINAL_PROMPT=0 git -C "$dir" fetch -q --depth 1 -- "$url" "$sha" \
2>/dev/null || return 1
git -C "$dir" -c advice.detachedHead=false checkout -q FETCH_HEAD \
2>/dev/null || return 1
[ "$(git -C "$dir" rev-parse HEAD 2>/dev/null)" = "$sha" ]
}
# _vendor_tree_index <dest_dir> — writes <dest_dir>/INDEX.md, one
# "- <id> | <category> | <H1 title>" line per guides/<category>/<id>.md.
_vendor_tree_index() {
local dir="$1" f id category title
[ -d "$dir/guides" ] || return 0
{
printf '# Guide index\n\nOne line per guide: `id | category | title`.'
printf ' Read `guides/<category>/<id>.md`.\n\n'
find "$dir/guides" -type f -name '*.md' | LC_ALL=C sort \
| while IFS= read -r f; do
id="$(basename "$f" .md)"
category="$(basename "$(dirname "$f")")"
title="$(grep -m1 '^# ' "$f" | sed 's/^# //')"
printf -- '- %s | %s | %s\n' "$id" "$category" "${title:-$id}"
done
} > "$dir/INDEX.md"
}
# _vendor_tree_stage <src> <stage> <items> — copies every
# "<dest>\t<target>\t<path>" item from the checkout <src> into
# <stage>/<dest>/; rc 1 (err names the path) when a path is missing.
_vendor_tree_stage() {
local src="$1" stage="$2" dest target path
while IFS=$'\t' read -r dest target path; do
[ -n "$dest" ] || continue
mkdir -p "$stage/$dest"
if [ ! -e "$src/$path" ]; then
err "upstream path missing at the pin: $path"
return 1
fi
if [ "$target" = "." ]; then
cp -R "$src/$path/." "$stage/$dest/" || return 1
else
cp -R "$src/$path" "$stage/$dest/$target" || return 1
fi
done <<<"$3"
}
# _vendor_tree_finish <stage> <dests> <source> <sha> <tag> <note> —
# writes INDEX.md, NOTICE.md and .vendored-commit into each staged dest.
_vendor_tree_finish() {
local stage="$1" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
_vendor_tree_index "$stage/$dest"
printf '# Vendored content\n\nSource: %s (tag %s, commit %s).\n' \
"$3" "${5:-none}" "$4" > "$stage/$dest/NOTICE.md"
printf 'Fetched by lib/vendor-skills.sh vendor_pinned_tree;' \
>> "$stage/$dest/NOTICE.md"
printf ' never edited here. License: %s.\n' "$6" >> "$stage/$dest/NOTICE.md"
printf '%s\n' "$4" > "$stage/$dest/.vendored-commit"
done <<<"$2"
}
# _vendor_tree_swap <root> <stage> <dests> — moves each staged dest into
# <root>/<dest>, the previous copy parked under <stage>/.old-<dest>.
_vendor_tree_swap() {
local root="$1" stage="$2" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
if [ -e "$root/$dest" ]; then
mv "$root/$dest" "$stage/.old-$dest" || return 1
fi
mv "$stage/$dest" "$root/$dest" || return 1
done <<<"$3"
}
# vendor_pinned_tree <lock-key> [refresh] — see the block comment above.
vendor_pinned_tree() {
local key="$1" refresh="${2:-}" out root="$VENDOR_REPO/skills-external"
local base="${VENDOR_BASE_URL:-}"
if [ -n "$base" ] && [[ "$base" != file://* ]]; then
warn "VENDOR_BASE_URL ignored (must start with file://): $base"
base=""
fi
if ! out="$(_vendor_read_tree_lock "$VENDOR_REPO/plugins.lock.json" "$key")"; then
_vendor_report_lock_error "$key" "$out"
return 1
fi
local source sha tag note items dests
{ read -r source; read -r sha; read -r tag; read -r note; } <<<"$out"
items="$(tail -n +5 <<<"$out")"
dests="$(cut -f1 <<<"$items" | sort -u)"
if [ "$refresh" != "refresh" ] && _vendor_tree_current "$root" "$sha" "$dests"; then
ok "$key already at pin ${sha:0:7}"
return 0
fi
local tmp stage="$root/.vendor-stage.$$"
tmp="$(mktemp -d)" || return 1
mkdir -p "$stage" || { rm -rf "$tmp"; return 1; }
if _vendor_tree_checkout "$tmp/src" "${base:-$source}" "$sha" \
&& _vendor_tree_stage "$tmp/src" "$stage" "$items" \
&& _vendor_tree_finish "$stage" "$dests" "$source" "$sha" "$tag" "$note" \
&& _vendor_tree_swap "$root" "$stage" "$dests"; then
ok "$key vendored (pinned @ ${sha:0:7}): $(tr '\n' ' ' <<<"$dests")"
rm -rf "$tmp" "$stage"
return 0
fi
err "$key: fetch, stage or swap failed at ${sha:0:7} — see above; copies at the previous pin kept"
rm -rf "$tmp" "$stage"
return 1
}
```
Swap failure note: `_vendor_tree_swap` moves dests one by one; a failure after the first move leaves that dest updated and the others at the old pin (each dest self-consistent, `.vendored-commit` tells which). The error line says so; doctor reports the mismatch.
- [ ] **Step 4: Run the suite**
Run: `make test suite=lib/tests/vendor-tree.test.sh`
Expected: every line `PASS …`, `vendor-tree: 21 pass, 0 fail`, `all suites green`.
Then: `shellcheck lib/vendor-skills.sh lib/tests/vendor-tree.test.sh` → no output.
Then the old suite still green: `make test suite=lib/tests/vendor-skills.test.sh` → `all suites green`.
- [ ] **Step 5: Commit**
```bash
git add lib/vendor-skills.sh lib/tests/vendor-tree.test.sh
git commit -m "feat(vendor): vendor_pinned_tree fetches whole upstream trees at a pinned commit"
```
---
### Task 2: Lock entry, install/update/link wiring, gitignore, doctor check
**Files:**
- Modify: `plugins.lock.json` (new key `modern-web-guidance`)
- Modify: `install-plugins.sh` Step 8e (≈ lines 913-940)
- Modify: `update-all.sh` 7.3 (≈ lines 369-383)
- Modify: `link.sh:78-81` (`EXTERNAL_SKILLS`)
- Modify: `.gitignore` (top flat-link block + a new vendored block)
- Modify: `lib/doctor-vendored.sh` (new `check_vendored_trees`), `doctor.sh:133`
- Test: `lib/tests/doctor-vendored.test.sh` (new cases)
**Interfaces:**
- Consumes: `vendor_pinned_tree <key> [refresh]` (Task 1).
- Produces: `check_vendored_trees <repo>` (doctor: pass/warn lines, never fail); lock key `modern-web-guidance`; dests `skills-external/mwg/`, `skills-external/chrome-extensions/`.
- [ ] **Step 1: Write the failing test** — append before the final summary of `lib/tests/doctor-vendored.test.sh` (reuse its `check`/`pass`/`fail` helpers; read the file first and follow its helper names exactly):
```bash
# ── check_vendored_trees: git-tree lock entries ──
TR="$(mktemp -d)"
mkdir -p "$TR/skills-external/at-pin" "$TR/skills-external/stale"
printf '%s\n' 1111111111111111111111111111111111111111 > "$TR/skills-external/at-pin/.vendored-commit"
printf '%s\n' 2222222222222222222222222222222222222222 > "$TR/skills-external/stale/.vendored-commit"
cat > "$TR/plugins.lock.json" <<'JSON'
{"t": {"managed_by": "git-tree", "commit": "1111111111111111111111111111111111111111",
"trees": {"at-pin": {"x": "a"}, "stale": {"x": "a"}, "absent": {"x": "a"}}},
"c": {"managed_by": "curl", "commit": "1111111111111111111111111111111111111111", "skills": ["s"]}}
JSON
out="$(source "$ROOT/lib/doctor-vendored.sh"; check_vendored_trees "$TR" 2>&1)"
printf '%s\n' "$out" | grep -q 't: at-pin at pin 1111111' && R1=1 || R1=0
printf '%s\n' "$out" | grep -q 't: skills-external/stale at 2222222, pin 1111111' && R2=1 || R2=0
printf '%s\n' "$out" | grep -q 't: skills-external/absent missing' && R3=1 || R3=0
printf '%s\n' "$out" | grep -q '✗' && R4=0 || R4=1
rm -rf "$TR"
```
Then, with the suite's own helper (`check_bool NAME 0|1`, lib/tests/doctor-vendored.test.sh:25):
```bash
check_bool TREES_AT_PIN "$R1"
check_bool TREES_STALE_WARN "$R2"
check_bool TREES_MISSING_WARN "$R3"
check_bool TREES_NEVER_FAIL "$R4"
```
The file ends with `echo "PASS=$pass FAIL=$fail"`; insert the block above that line.
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/doctor-vendored.test.sh`
Expected: the four new checks FAIL (`check_vendored_trees: command not found`).
- [ ] **Step 3: Implement**
`lib/doctor-vendored.sh`, append:
```bash
# _dv_tree_expectations <lockfile> — prints "<key>\t<dest>\t<commit>" for
# every "managed_by": "git-tree" entry; dest and commit format-checked,
# an invalid one skipped. Lockfile via argv, stderr discarded.
_dv_tree_expectations() {
python3 - "$1" 2>/dev/null <<'PY'
import json, re, sys
NAME = re.compile(r'^[A-Za-z0-9_-][A-Za-z0-9._-]*$')
COMMIT = re.compile(r'^[0-9a-f]{40}$')
with open(sys.argv[1]) as f:
data = json.load(f)
for key, entry in sorted(data.items()):
if not isinstance(entry, dict) or entry.get("managed_by") != "git-tree":
continue
sha = entry.get("commit", "")
trees = entry.get("trees", {})
if not COMMIT.fullmatch(sha) or not isinstance(trees, dict):
continue
for dest in sorted(trees):
if NAME.fullmatch(dest):
print(f"{key}\t{dest}\t{sha}")
PY
}
# check_vendored_trees <repo> — every git-tree dest exists under
# skills-external/ with a .vendored-commit equal to its pin. Never fails:
# a missing or stale copy is a warn naming `make update`.
check_vendored_trees() {
local repo="$1" key dest sha got
while IFS=$'\t' read -r key dest sha; do
[ -n "$key" ] || continue
got="$(cat "$repo/skills-external/$dest/.vendored-commit" 2>/dev/null)"
if [ -z "$got" ]; then
warn "$key: skills-external/$dest missing — run: make update"
elif [ "$got" != "$sha" ]; then
warn "$key: skills-external/$dest at ${got:0:7}, pin ${sha:0:7} — run: make update"
else
pass "$key: $dest at pin ${sha:0:7}"
fi
done < <(_dv_tree_expectations "$repo/plugins.lock.json")
}
```
`doctor.sh` line 133, after `check_vendored_skills "$REPO" "$HOME/.claude"`:
```bash
check_vendored_trees "$REPO"
```
`plugins.lock.json`, new key (keep the file's existing key order; place it after `superpowers`):
```json
"modern-web-guidance": {
"source": "https://github.com/GoogleChrome/modern-web-guidance",
"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": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"},
"chrome-extensions": {".": "skills/chrome-extensions"}
},
"note": "Google Modern Web Guidance (Chrome, Edge, Firefox, MDN). Guides read locally by skills/modern-web-guidance; the upstream SKILL.md (npx @latest) is never copied. chrome-extensions linked as is by link.sh. Bump commit + tag deliberately."
}
```
`install-plugins.sh` Step 8e: after `vendor_pinned_skills superpowers` add
```bash
vendor_pinned_tree modern-web-guidance
```
and add `chrome-extensions` at the end of the `EXT_SKILL_NAMES=(…)` array.
`update-all.sh` 7.3: after `vendor_pinned_skills superpowers refresh` add
```bash
echo ""
echo "── Updating Modern Web Guidance (GoogleChrome/modern-web-guidance)..."
vendor_pinned_tree modern-web-guidance refresh
```
`link.sh:81`: append `chrome-extensions` inside `EXTERNAL_SKILLS=(…)` (last element, before `)`).
`.gitignore`: in the top flat-link block add `skills/chrome-extensions`; after the superpowers block add
```gitignore
# Modern Web Guidance, vendored (plugins.lock.json 'modern-web-guidance',
# managed_by git-tree) — machine-owned, fetched at the pinned commit by
# install-plugins.sh Step 8e and update-all.sh 7.3 through
# lib/vendor-skills.sh vendor_pinned_tree. Bump the commit deliberately.
skills-external/mwg/
skills-external/chrome-extensions/
skills-external/.vendor-stage.*/
```
- [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/doctor-vendored.test.sh lib/tests/vendor-skills.test.sh lib/tests/vendor-tree.test.sh lib/tests/curated-config-guard.test.sh"`
Expected: `all suites green`. Then `shellcheck lib/doctor-vendored.sh doctor.sh install-plugins.sh update-all.sh link.sh` → no new warning; `python3 -c "import json;json.load(open('plugins.lock.json'))"` → no output.
- [ ] **Step 5: Commit**
```bash
git add plugins.lock.json install-plugins.sh update-all.sh link.sh .gitignore lib/doctor-vendored.sh doctor.sh lib/tests/doctor-vendored.test.sh
git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extensions, doctor checks the pin"
```
---
### Task 3: Our `modern-web-guidance` skill + routing rows
**Files:**
- Create: `skills/modern-web-guidance/SKILL.md`, `skills/modern-web-guidance/test-prompts.json`
- Create (tracked symlinks): `skills/modern-web-guidance/guides`, `skills/modern-web-guidance/INDEX.md`, `skills/modern-web-guidance/NOTICE.md`
- Modify: `mods/model-router/routing.json` (`skills` object)
- Test: `lib/tests/mwg-skill.test.sh`
**Interfaces:**
- Consumes: `skills-external/mwg/{guides,INDEX.md,NOTICE.md}` (Task 1/2 layout).
- Produces: skill name `modern-web-guidance`; disclosure line format `Modern Web Guidance: <id>, <id>` / `Modern Web Guidance: checked <topics>, none applied`.
- [ ] **Step 1: Write the failing test** — `lib/tests/mwg-skill.test.sh`:
```bash
#!/usr/bin/env bash
# lib/tests/mwg-skill.test.sh — skills/modern-web-guidance: read-only
# tools, no npx or network command anywhere in a fenced block, the three
# relative links into skills-external/mwg, the disclosure format, and a
# routing.json row.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
S="$ROOT/skills/modern-web-guidance"
pass=0; fail=0
check() { if [ "$2" = 1 ]; then pass=$((pass+1)); echo "PASS $1"; else fail=$((fail+1)); echo "FAIL $1"; fi; }
check exists "$([ -f "$S/SKILL.md" ] && echo 1)"
check tools "$(grep -qx 'allowed-tools: Read, Grep, Glob' "$S/SKILL.md" && echo 1)"
check no-bash "$(grep -q '^allowed-tools:.*Bash' "$S/SKILL.md" || echo 1)"
fenced_npx="$(awk '/^```/{f=!f; next} f' "$S/SKILL.md" | grep -c 'npx\|pnpx\|curl\|wget')"
check no-fenced-network "$([ "$fenced_npx" -eq 0 ] && echo 1)"
check never-run "$(grep -q 'Never run npx' "$S/SKILL.md" && echo 1)"
check disclosure "$(grep -q '`Modern Web Guidance: <id>, <id>`' "$S/SKILL.md" && echo 1)"
for l in guides:../../skills-external/mwg/guides INDEX.md:../../skills-external/mwg/INDEX.md NOTICE.md:../../skills-external/mwg/NOTICE.md; do
check "link-${l%%:*}" "$([ -L "$S/${l%%:*}" ] && [ "$(readlink "$S/${l%%:*}")" = "${l#*:}" ] && echo 1)"
done
check tracked-links "$([ "$(cd "$ROOT" && git ls-files skills/modern-web-guidance | grep -c 'guides$\|INDEX.md$\|NOTICE.md$')" -eq 3 ] && echo 1)"
row="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['skills'].get('modern-web-guidance',''))" "$ROOT/mods/model-router/routing.json")"
check routing-row "$([ "$row" = explore ] && echo 1)"
check prompts "$(python3 -c "import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if len(d)>=3 else 1)" "$S/test-prompts.json" && echo 1)"
echo "mwg-skill: $pass pass, $fail fail"
[ "$fail" -eq 0 ]
```
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/mwg-skill.test.sh` → `FAIL exists` etc.
- [ ] **Step 3: Implement**
`skills/modern-web-guidance/SKILL.md`:
````markdown
---
name: modern-web-guidance
effort: medium
description: |
Current web-platform practice from Google's Modern Web Guidance (Chrome,
Edge, Firefox and MDN teams), read from a pinned local copy. Run it FIRST,
before writing or changing front-end code: HTML, CSS, client-side JS, UI
components in any framework. Covers dialogs, popovers, forms and
validation, tables, dark mode, container queries, anchor positioning, view
transitions, scroll-driven animation, Core Web Vitals (LCP, INP, CLS),
images, passkeys, sanitization, web components, dates and time zones,
built-in AI. Not for backend, infra, build tooling or tests.
allowed-tools: Read, Grep, Glob
---
# Modern Web Guidance (local, pinned)
The guides sit in this skill's folder: `INDEX.md` (one line per guide,
`id | category | title`) and `guides/<category>/<id>.md`. They are a copy
of GoogleChrome/modern-web-guidance pinned in `plugins.lock.json`
(`NOTICE.md` names the commit and the licenses). Nothing here touches the
network.
## Steps
1. Search: Grep `INDEX.md`, case-insensitive, for one capability at a
time, in 1-3 words naming the UI pattern or platform feature
(`dialog`, `popover`, `table`, `validation`, `view transition`, `LCP`).
No hit: rephrase once with a synonym, then Grep the bodies under
`guides/`. Nothing relevant: go on without a guide.
2. Read: open each matching guide, plus the discipline guide of the task
when one exists (`html`, `css`, `forms`, `accessibility`, `performance`,
`security`).
3. Cross-references: a guide line `npx -y modern-web-guidance@latest
retrieve "<id>"` points at another guide. Glob `guides/*/<id>.md` and
Read it instead. Never run npx, the guidance CLI or any network command
for this skill.
4. Apply: follow the guide, its fallbacks and its Baseline notes, without
adding features the task did not ask for. Where a guide and a rule of
`rules/web-building.md` disagree on how to use the platform, the guide
wins.
5. Disclose: end the answer that delivers the front-end change with one
line, `Modern Web Guidance: <id>, <id>`. Guides checked and none
applied: `Modern Web Guidance: checked <topics>, none applied`. No
quotes.
## Missing copy
`INDEX.md` unreadable (the link dangles on a machine that never ran the
install): say once "Modern Web Guidance not installed, run `make update`"
and continue without it.
````
Symlinks (from the repo root):
```bash
ln -s ../../skills-external/mwg/guides skills/modern-web-guidance/guides
ln -s ../../skills-external/mwg/INDEX.md skills/modern-web-guidance/INDEX.md
ln -s ../../skills-external/mwg/NOTICE.md skills/modern-web-guidance/NOTICE.md
```
`skills/modern-web-guidance/test-prompts.json`:
```json
[
{"id": 1, "prompt": "Add a confirmation modal before deleting an item", "expected": "Grep INDEX.md for dialog, Read the dialog guide (+ html/accessibility), build on <dialog> per the guide, end with `Modern Web Guidance: <ids>`"},
{"id": 2, "prompt": "Make this table usable on mobile", "expected": "Search table/responsive, Read the matching guide, apply its pattern and fallback, disclosure line"},
{"id": 3, "prompt": "Améliore le LCP de la page d'accueil", "expected": "FR trigger: search LCP, Read the performance guides, apply fetchpriority/image guidance, disclosure line"},
{"id": 4, "prompt": "Write a SQL migration for the orders table", "expected": "Does not trigger: backend task"}
]
```
`mods/model-router/routing.json`, inside `"skills"`: add `"modern-web-guidance": "explore"` and `"chrome-extensions": "implement"` (keep the object's existing formatting; place them alphabetically if the object is sorted, else at the end).
- [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/mwg-skill.test.sh lib/tests/effort-routing.test.sh lib/tests/model-routing.test.sh lib/tests/pack-census.test.sh lib/tests/skill-routing-census.test.sh"`
Expected: `all suites green`. If `skill-routing-census` reports a pair ≥ 0.75 involving `modern-web-guidance`, reword the description's trigger list (keep the first sentence) and re-run; a WARN (≥ 0.50) is acceptable and is reported.
- [ ] **Step 5: Commit**
```bash
git add skills/modern-web-guidance mods/model-router/routing.json lib/tests/mwg-skill.test.sh
git commit -m "feat(skills): modern-web-guidance reads the pinned guides locally"
```
---
### Task 4: Wiring in `rules/web-building.md` and `site-motion`
**Files:**
- Modify: `rules/web-building.md` (after line 5 title; lines 27-29 motion; § Design work Build bullet ≈ line 52-57)
- Modify: `skills/pack-design/skills/site-motion/SKILL.md` (intro paragraph ≈ line 24-27)
- Test: `lib/tests/mwg-skill.test.sh` (append wiring checks)
**Interfaces:**
- Consumes: skill name `modern-web-guidance` (Task 3).
- [ ] **Step 1: Write the failing test** — append before the summary line of `lib/tests/mwg-skill.test.sh`:
```bash
W="$ROOT/rules/web-building.md"
check rule-section "$(grep -qx '## Modern Web Guidance first' "$W" && echo 1)"
check rule-before-design "$([ "$(grep -n '^## Modern Web Guidance first' "$W" | cut -d: -f1)" -lt "$(grep -n '^## Design work' "$W" | cut -d: -f1)" ] && echo 1)"
check rule-guide-wins "$(grep -q 'platform, the guide wins' "$W" && echo 1)"
check motion-line "$(grep -q '^- Motion: transform and opacity for continuous or scroll-linked motion,$' "$W" && echo 1)"
check motion-old-gone "$(grep -q 'transform and opacity only' "$W" || echo 1)"
check design-build "$(awk '/^## Design work/{p=1} /^## /&&!/Design work/{p=0} p' "$W" | grep -q 'consult `modern-web-guidance` first' && echo 1)"
check design-heading "$(grep -qx '## Design work — full toolchain (tiered by scope)' "$W" && echo 1)"
check locked-line "$(grep -qx '- The vendored stack members route to `reflect` (high) through their' "$W" && echo 1)"
check site-motion "$(grep -q '`modern-web-guidance`' "$ROOT/skills/pack-design/skills/site-motion/SKILL.md" && echo 1)"
```
- [ ] **Step 2: Run it to verify it fails** — `make test suite=lib/tests/mwg-skill.test.sh` → the new checks FAIL.
- [ ] **Step 3: Implement**
`rules/web-building.md`, insert after the line `# Web building — no default reflexes + done checklist` and its following blank line:
```markdown
## Modern Web Guidance first
Before writing or changing front-end code (markup, styles, client-side JS,
components), run the `modern-web-guidance` skill: it reads Google's pinned
guides locally. Where a guide and a line below disagree on how to use the
platform, the guide wins. End the answer with the skill's one-line
disclosure.
```
Replace the three lines
```
- Motion: transform and opacity only; feedback under 200 ms, ease-out on
entrances, never from scale(0); `will-change` only during an active
animation; pause loops off-screen; honor `prefers-reduced-motion`.
```
with
```
- Motion: transform and opacity for continuous or scroll-linked motion,
other transitions per the Modern Web Guidance guides; feedback under
200 ms, ease-out on entrances, never from scale(0); `will-change` only
during an active animation; pause loops off-screen; honor
`prefers-reduced-motion`.
```
In § Design work, insert right after the Build bullet (after the line ` only for a one-off visual with no project context, not beside impeccable.`):
```
- Every Build step above (impeccable, ui-ux-pro-max, 21st, emil, motion,
design-html, site-motion) must consult `modern-web-guidance` first for
the platform features it uses.
```
`skills/pack-design/skills/site-motion/SKILL.md`: append to the intro paragraph ending `top of it.` a new paragraph:
```markdown
Platform features (scroll-driven animation, view transitions, animating to
intrinsic sizes, reduced motion) come from the `modern-web-guidance` skill
first: read its guide before choosing a library or a technique.
```
- [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/mwg-skill.test.sh lib/tests/doctrine-citers.test.sh lib/tests/effort-routing.test.sh lib/tests/project-rules.test.sh lib/tests/user-rules.test.sh"`
Expected: `all suites green`.
- [ ] **Step 5: Commit**
```bash
git add rules/web-building.md skills/pack-design/skills/site-motion/SKILL.md lib/tests/mwg-skill.test.sh
git commit -m "feat(rules): front-end work consults modern-web-guidance first"
```
---
### Task 5 (main loop, after the gates): live install and doctor
Not an executor task (network fetch on this machine, link refresh):
- `source lib/vendor-skills.sh && vendor_pinned_tree modern-web-guidance` → `modern-web-guidance vendored (pinned @ 64a6d70): chrome-extensions mwg`.
- `bash link.sh` → `chrome-extensions` linked.
- `ls skills/modern-web-guidance/INDEX.md` resolves; `grep -c '^- ' skills-external/mwg/INDEX.md` → 210.
- `make doctor` → no new error; `check_vendored_trees` passes both dests.
- Full `make test` (bun on PATH) → green.
@@ -0,0 +1,123 @@
# Modern Web Guidance in the kit — design
Date: 2026-11-21. Contract: `.claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md`
(all user decisions are in its CLARIFICATIONS). Branch: `feature/modern-web-guidance`.
## Goal
Every front-end task (HTML, CSS, client-side JS, components, in any flow and any profile)
consults Google's Modern Web Guidance before writing code, so the agent applies current
platform practice instead of patterns from its training data. The guidance is read from a
pinned local copy: no npx, no network and no remote code at use time.
## Upstream
`GoogleChrome/modern-web-guidance`, tag v1.0.1 = commit
`64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65` (2026-11-16). Stewarded by Chrome, Edge,
Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0.
- `skills/modern-web-guidance/`: `SKILL.md` (runs `npx -y modern-web-guidance@latest
search|retrieve`, never used here) and `guides/<17 categories>/<id>.md`, 210 files,
~2 MB, no frontmatter, id = basename (unique). 174 lines in 67 guides cross-reference
other guides as `npx -y modern-web-guidance@latest retrieve "<id>"`.
- `skills/chrome-extensions/`: `SKILL.md` + `references/` (24 files, no npx); it names the
`modern-web-guidance` skill and maintains a `CHROMEWEBSTORE.md` in extension projects.
## Components
### 1. Pinned fetch (`lib/vendor-skills.sh`, new function)
`vendor_pinned_tree <lock-key> [refresh]` 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",
"trees": {
"mwg": ["skills/modern-web-guidance/guides", "LICENSE"],
"chrome-extensions": ["skills/chrome-extensions"]
},
"always_on": true
}
```
- One `git init` + `git fetch --depth 1 <source> <commit>` in a `mktemp -d` path, checkout
`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).
- 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).
- 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
existing helper).
- 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.
### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on)
- `SKILL.md` with `name`, `effort: medium` (the `explore` row floor), `description` (front-end triggers; not backend,
infra, tooling), `allowed-tools: Read, Grep, Glob`.
- Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`,
`INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`.
- Workflow in the body:
1. Grep `INDEX.md` for 1-3 terms of the capability (dialog, popover, table, form
validation, view transition, LCP…); fall back to Grep over `guides/`.
2. Read the matching guide(s) and the discipline guide when one applies (html, css,
forms, accessibility, performance, security).
3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line
`npx … retrieve "<id>"` means: Read `guides/*/<id>.md` locally. 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.
- `test-prompts.json` (darwin convention), a `routing.json` row (`modern-web-guidance`,
phase `explore`).
### 3. chrome-extensions (vendored, always on, as is)
Added to `link.sh` `EXTERNAL_SKILLS` (always-on flat link, the superpowers class;
BDR-093 forbids only default-off packs there). Its `CHROMEWEBSTORE.md` behaviour is kept.
A routing row is added if the effort-routing census requires one for linked externals.
### 4. Wiring
- `rules/web-building.md`, new section right after the title: before writing or changing
front-end code, run the `modern-web-guidance` skill; the guide wins on platform usage;
end with its disclosure line. Motion line becomes: "transform and opacity for continuous
or scroll-linked motion; other transitions per the guides". Globs unchanged.
- `§ Design work` (heading kept byte-identical): one line, every step of the stack
(Build, polish, motion, scroll) consults `modern-web-guidance` for the platform
features it uses. This is the only durable route into the foreign design skills.
- `skills/pack-design/skills/site-motion/SKILL.md` (ours): the same line.
- `CLAUDE.global.md` unchanged (320/320); its design pointer already sends design work to
`web-building.md`.
- Known: the path rule also loads inside sub-agents (LRN-232), so front agents see it too.
### 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/tests/mwg.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,
and our `SKILL.md` contains no `npx` command to run.
- README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an
assumed exception to BDR-056.
## Out of scope
Audit skills (a11y, web-validate, guardrails, seo), agents' own briefs, a `.js/.ts` path
glob, a search CLI or embedding index, `legacy-scan`.