diff --git a/docs/superpowers/plans/2026-11-21-modern-web-guidance.md b/docs/superpowers/plans/2026-11-21-modern-web-guidance.md deleted file mode 100644 index bc33007..0000000 --- a/docs/superpowers/plans/2026-11-21-modern-web-guidance.md +++ /dev/null @@ -1,1071 +0,0 @@ -# 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//`, generates `INDEX.md` (one line per guide, the upstream README's one-sentence description) / `NOTICE.md` / `.vendored-commit`, and swaps the result in. Our tracked skill `skills/modern-web-guidance/` reaches the copy through one relative symlink `mwg` and needs only Read (Grep and Glob are absent in some sessions). `rules/web-building.md` and `site-motion` send front-end work to the skill; a sub-agent without the Skill tool Reads its `SKILL.md` by path. model-router learns a short list of reference skills (`modern-web-guidance`, `find-docs`) whose loading never opens its main-loop write guard. - -**Tech Stack:** bash, python3 (lock parsing, argv only), git, markdown, TypeScript (model-router mod, `claude plugin test`). - -**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). - -## Alternatives weighed for the fetcher - -- A pinned git submodule (the gstack precedent) gets pin checks, pruning and an atomic checkout from git, but it puts the whole upstream repo on disk (the npx `SKILL.md`, the CLI, policies), against the allowlist rule for fetchers (LRN-109, LRN-184). Its pin would live in the gitlink, while acceptance criterion 1 (user-gated) puts it in `plugins.lock.json`. It cannot hold the generated `INDEX.md` without a dirty submodule, and install-plugins.sh only inits submodules when gstack is absent. Rejected. -- `vendor_pinned_skills` (curl per listed file) for chrome-extensions: 24 files to list by hand and to keep in sync on every pin bump, and a second fetch path at the same commit. Rejected; one git fetch serves both dests. -- A pinned variant of `higgsfield_sync_skills`: same clone-stage-adopt shape, but no lock, no pin check, no prune. `vendor_pinned_tree` reuses its no-prompt git flags and its mktemp stage. - -## 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`: it only pre-approves Read for the invoking turn, it does not restrict tools (Claude Code skills docs). The no-npx guarantee rests on the skill's "Never run npx" sentence, the absence of any command in it, and the settings soft-deny on undeclared `npx `. -- No `routing.json` row and no `effort:` frontmatter for `modern-web-guidance` or `chrome-extensions`: a rowed skill reroutes the main loop on load ("last rowed skill wins", `mods/model-router/hooks/register.ts` onSkillLoad), which would pull design work off `reflect`. `modern-web-guidance` joins `NO_ROW_SKILLS` in `lib/tests/effort-routing.test.sh` (precedent: `find-docs`); `chrome-extensions` is an untracked linked external, the census does not ask for a row. No row is not no side effect: any main-loop Skill call sets `st.skillRun` (register.ts:4634), which opens the write guard for the session; Task 5 exempts reference skills (user decision 2026-11-22, contract CLARIFICATIONS). -- Skill description at most 400 characters (listing budget `SLASH_COMMAND_TOOL_CHAR_BUDGET=50000`, ~34.5k already used by flat + pack descriptions). -- The upstream `skills/modern-web-guidance/SKILL.md` is never copied into `skills-external/`. -- Vendored text is never edited (BDR-104/106); `INDEX.md` and `NOTICE.md` are generated beside it. -- `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). -- install-plugins.sh and update-all.sh run under `set -euo pipefail`: the new fetch is called inside `if !`, a failure warns and the script goes on (the `vendor_pinned_skills` and higgsfield convention). doctor.sh runs under the same options: no new check may trip errexit. -- Tests run only through `make test suite=` (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), and `make plugin` / `make update` warn and continue. -2. A pin bump that drops a guide upstream → the guide disappears locally (whole-dir swap, not file overwrite). -3. A machine that never ran `make plugin` → `make update` installs the copy (one mode: anything not at the pin is fetched). -4. A lock entry with `..`, an absolute path or a bad dest name, a dest dir owned by someone else, or a symlink in the fetched content → rejected, nothing replaced. -5. Fresh clone before install → the skill's `mwg` link dangles; the skill says "run `make update`". Doctor warns for `mwg`; a missing `chrome-extensions` copy is the existing `check_vendored_skills` error, like every other external; doctor reaches its summary either way. -6. A sub-agent executor (feater, bugfixer, hotfixer: no Skill tool in their `tools:`) Reads a front file → the path rule tells it to Read `~/.claude/skills/modern-web-guidance/SKILL.md`; the relative link resolves through the `~/.claude/skills` link (checked on a fixture: the kernel resolves `../..` from the link's real directory). A closed plan that contradicts a guide is reported as an open choice, never overridden silently. -7. A direct front-end request with no code skill running ("change the button color in Header.tsx") → the main loop runs `modern-web-guidance`, then its code write is still redirected to /hotfix or /feat (the reference skill does not open the guard); inside a /feat run the guard stays open. - -## Contract oracles (draft, written into the contract at STEP 3 with `- run-base:`) - -1. Pin + install wiring + local copy at the pin, 210 guides, no upstream SKILL.md: - CHECK: `python3 -c "import json;e=json.load(open('plugins.lock.json'))['modern-web-guidance'];assert e['commit']=='64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65' and e['tag']=='v1.0.1'" && grep -q 'if ! vendor_pinned_tree modern-web-guidance; then' install-plugins.sh && grep -q 'if ! vendor_pinned_tree modern-web-guidance; then' update-all.sh && [ "$(cat skills-external/mwg/.vendored-commit)" = 64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65 ] && [ "$(grep -c '^- ' skills-external/mwg/INDEX.md)" -eq "$(find skills-external/mwg/guides -name '*.md' | wc -l)" ] && [ -f skills-external/chrome-extensions/SKILL.md ] && [ ! -e skills-external/mwg/SKILL.md ] && make test suite=lib/tests/vendor-tree.test.sh 2>&1 | tail -1` → EXPECT `all suites green` -2. Our skill, local read only, disclosure: CHECK `make test suite=lib/tests/mwg-skill.test.sh 2>&1 | tail -1` → EXPECT `all suites green` -3. Rule wiring: CHECK `grep -qx '## Modern Web Guidance first' rules/web-building.md && grep -q 'Read `~/.claude/skills/modern-web-guidance/SKILL.md` and follow it.' rules/web-building.md && grep -q '`modern-web-guidance` first for the platform features it uses.' rules/web-building.md && echo WIRED` → EXPECT `WIRED` -4. Upstream SKILL.md not linked, chrome-extensions linked: CHECK `! grep -l 'modern-web-guidance@latest search' ~/.claude/skills/*/SKILL.md 2>/dev/null | grep -q . && [ -L ~/.claude/skills/chrome-extensions ] && echo NOT_LINKED` → EXPECT `NOT_LINKED` -5. Suite and doctor (one CHECK): `make test 2>&1 | tail -1 | grep -qx 'all suites green' && bash doctor.sh 2>&1 | grep -q 'No errors' && echo SUITE_DOCTOR_OK` → EXPECT `SUITE_DOCTOR_OK` (doctor baseline 2026-11-22: "No errors, 2 warning(s)"). -6. Reference skills keep the write guard: CHECK `grep -q "'modern-web-guidance', 'find-docs'," mods/model-router/hooks/register.ts && make test suite=lib/tests/mods.test.sh 2>&1 | tail -1` → EXPECT `all suites green` - -Oracles 1, 4 and 5 need the live copy: Task 6 runs after Task 5 and before the STEP 5 gates. - ---- - -### 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 ` (rc 0 when every dest is at the pin, already or after the fetch; rc 1 on any failure, no dest half-replaced); `_vendor_read_tree_lock ` (stdout lines: source, commit, tag, license, then `\t\t`); lock entry shape: - `{"source","commit","tag","license","trees":{"":{"|.":""}},"managed_by":"git-tree","always_on":true}`. -- Writes per dest: `skills-external//.vendored-commit` (the commit), `.vendored-spec` (the dest's allowlist lines, so an allowlist edit at the same commit re-fetches), `NOTICE.md`, and `INDEX.md` when the dest holds `guides/` (summary from the dest's `README.md` when present, else the guide's H1). - -- [ ] **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 -# (README description, else H1) / NOTICE / .vendored-commit generation, -# upstream SKILL.md never copied, skip at the pin, a pin bump prunes a -# guide dropped upstream, an absent copy is installed, a commit not -# upstream is refused with nothing written, unsafe lock paths rejected -# before any fetch, an allowlist edit at the same commit re-fetched, a -# dest owned by someone else never replaced, a symlink in the fetched -# content or a listed path leaving the checkout refused. -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/), a -# README listing one guide, 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 -- '- **[dialog](https://x/guides/html/dialog.md)**: Native modal dialog.\n' \ - > "$UP/README.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 [extra-tree-json] - cat > "$REPO/plugins.lock.json" <"$WORK/out" 2>&1; } -M="$REPO/skills-external/mwg"; C="$REPO/skills-external/chrome-extensions" - -# T1 install: allowlisted copy, generated files, no upstream SKILL.md. -write_lock "$SHA1"; run mwg-key; rc=$? -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-desc "$(grep -qx -- '- dialog | html | Native modal dialog.' "$M/INDEX.md" && echo 1)" -check_bool T1-index-h1 "$(grep -qx -- '- animate-to-intrinsic-sizes | css | Animate to intrinsic sizes' "$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 "$(compgen -G "$REPO/skills-external/.vendor-stage.*" >/dev/null || echo 1)" - -# T2 at the pin: skip, no fetch (source made unreachable). -VENDOR_BASE_URL="file://$WORK/nowhere" 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 pin bump 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; 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 an absent copy is installed (never-installed machine). -rm -rf "$REPO/skills-external/chrome-extensions" -run mwg-key; rc=$? -check_bool T4-installs-absent "$([ $rc -eq 0 ] && [ -f "$C/SKILL.md" ] && echo 1)" - -# T12 an allowlist edit at the same commit is applied (README dropped: -# the dialog line falls back to its H1), then restored. -sed 's/, "README.md": "README.md"//' "$REPO/plugins.lock.json" > "$WORK/lock" -cp "$WORK/lock" "$REPO/plugins.lock.json"; run mwg-key; rc=$? -check_bool T12-spec-refetch "$([ $rc -eq 0 ] && [ ! -e "$M/README.md" ] && grep -qx -- '- dialog | html | Dialog' "$M/INDEX.md" && echo 1)" -write_lock "$SHA2"; run mwg-key; rc=$? -check_bool T12-spec-restored "$([ $rc -eq 0 ] && [ -f "$M/README.md" ] && grep -q 'README.md' "$M/.vendored-spec" && echo 1)" - -# T5 commit not in upstream: rc 1, existing copy untouched. -BAD="0123456789abcdef0123456789abcdef01234567" -write_lock "$BAD"; run mwg-key; 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; 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" -VENDOR_BASE_URL="https://evil.example" vendor_pinned_tree mwg-key >"$WORK/out" 2>&1 -check_bool T9-override-ignored "$(grep -q 'VENDOR_BASE_URL ignored' "$WORK/out" && echo 1)" - -# T10 a dest that exists without .vendored-commit is never replaced. -mkdir -p "$REPO/skills-external/owned"; printf 'x\n' > "$REPO/skills-external/owned/keep" -write_lock "$SHA2" ', "owned": {"x": "LICENSE"}'; run mwg-key; rc=$? -check_bool T10-owned "$([ $rc -eq 1 ] && grep -q 'refusing to replace' "$WORK/out" && [ -f "$REPO/skills-external/owned/keep" ] && [ ! -e "$REPO/skills-external/owned/x" ] && echo 1)" - -# T11 a symlink in the fetched content aborts with nothing swapped. -ln -s ../../SKILL.md "$UP/skills/chrome-extensions/references/link.md" -g add -A; g commit -qm three -SHA3="$(git -C "$UP" rev-parse HEAD)" -write_lock "$SHA3"; run mwg-key; rc=$? -check_bool T11-symlink "$([ $rc -eq 1 ] && [ ! -L "$C/references/link.md" ] && [ "$(cat "$C/.vendored-commit")" = "$SHA2" ] && echo 1)" - -# T13 a listed path that resolves outside the checkout is refused. -g rm -q skills/chrome-extensions/references/link.md -mkdir -p "$WORK/outside"; printf 'x\n' > "$WORK/outside/f" -ln -s "$WORK/outside" "$UP/skills/escape"; g add -A; g commit -qm four -SHA4="$(git -C "$UP" rev-parse HEAD)" -write_lock "$SHA4" ', "esc": {".": "skills/escape"}'; run mwg-key; rc=$? -check_bool T13-escape "$([ $rc -eq 1 ] && grep -q 'leaves the checkout' "$WORK/out" && [ ! -e "$REPO/skills-external/esc" ] && echo 1)" - -echo "vendor-tree: $pass pass, $fail fail" -[ "$fail" -eq 0 ] -``` - -- [ ] **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"): -# "": { -# "source": "https://github.com//", -# "commit": "<40-hex sha>", "tag": "", -# "license": "", -# "trees": { "": { "" | ".": "", ... }, ... } -# } -# Each becomes skills-external//. "": "" copies -# the repo path as /; ".": "" copies the path's -# contents into /. Only listed paths are copied (allowlist). The -# fetch is one `git fetch --depth 1 `; HEAD must equal -# the pin or nothing is written. Every dest is staged complete under a -# mktemp dir in skills-external/, then swapped in whole, so a file -# dropped upstream disappears on a pin bump. Per dest it writes -# .vendored-commit, .vendored-spec (its lines of the trees allowlist), -# NOTICE.md, and INDEX.md when the dest holds guides/. One mode: skip when -# every dest holds the pinned commit and the current allowlist, else fetch -# (a pin bump, an allowlist edit, a missing copy). A hand-damaged copy -# with intact markers is not detected: delete the dest and rerun. A dest -# that exists without .vendored-commit belongs to someone else and is -# never replaced; a listed path that resolves outside the checkout, or a -# symlink in the copied content, aborts the run. - -# _vendor_read_tree_lock — prints source, commit, tag, -# license, then one "\t\t" line per item (sorted). -# rc 1 silent when the entry is absent or incomplete; rc 1 with one -# "INVALID\t=" or "INVALID\t" line on a bad field. -# Only values that reach a path or a URL are allowlisted; tag and license -# are free text without control characters. -_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._-]+/?$') - - -def unsafe(value): - return ".." in value or value.startswith("/") or not SAFE.fullmatch(value) - - -def free_text_bad(value): - return not isinstance(value, str) or any(ord(c) < 32 for c in 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 free_text_bad(tag): - bad("tag") -if free_text_bad(note): - bad("license") -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 — rc 0 when every dest of -# holds a .vendored-commit equal to and a .vendored-spec -# equal to its own "\t\t" lines. -_vendor_tree_current() { - local root="$1" sha="$2" items="$3" dest - while IFS= read -r dest; do - [ -n "$dest" ] || continue - [ "$(cat "$root/$dest/.vendored-commit" 2>/dev/null)" = "$sha" ] \ - || return 1 - [ "$(cat "$root/$dest/.vendored-spec" 2>/dev/null)" \ - = "$(awk -F'\t' -v d="$dest" '$1 == d' <<<"$items")" ] || return 1 - done < <(cut -f1 <<<"$items" | sort -u) -} - -# _vendor_tree_owned — rc 1 (err names it) when a dest -# exists without .vendored-commit: a directory another installer or the -# repo owns is never replaced. -_vendor_tree_owned() { - local root="$1" dest - while IFS= read -r dest; do - [ -n "$dest" ] || continue - if [ -e "$root/$dest" ] && [ ! -f "$root/$dest/.vendored-commit" ]; then - err "skills-external/$dest exists without .vendored-commit — \ -not vendored here, refusing to replace it" - return 1 - fi - done <<<"$2" -} - -# _vendor_tree_checkout — shallow fetch of into a -# fresh repo at ; rc 0 only when the checked-out HEAD is . -_vendor_tree_checkout() { - local dir="$1" url="$2" sha="$3" - git init -q "$dir" >/dev/null 2>&1 || return 1 - # No credential prompt of any kind (same flags as - # lib/higgsfield-skills.sh): a private or deleted upstream fails at - # once, not on a terminal, an askpass program or a credential helper. - GIT_TERMINAL_PROMPT=0 GIT_ASKPASS='' SSH_ASKPASS='' \ - git -C "$dir" -c credential.helper= -c core.askPass= \ - fetch -q --depth 1 -- "$url" "$sha" /dev/null 2>&1 \ - || return 1 - git -C "$dir" -c advice.detachedHead=false checkout -q FETCH_HEAD \ - >/dev/null 2>&1 || return 1 - [ "$(git -C "$dir" rev-parse HEAD 2>/dev/null)" = "$sha" ] -} - -# _vendor_tree_summary — the upstream README's one-line -# description of guide (`- **[](…)**: `), empty when the -# README or the line is absent. -_vendor_tree_summary() { - [ -f "$1" ] || return 0 - grep -m1 -F -- "- **[$2](" "$1" \ - | sed -n 's/^- \*\*\[[^]]*\]([^)]*)\*\*: //p' || true -} - -# _vendor_tree_index — writes /INDEX.md, one -# "- | | " line per guides//.md; -# the summary is the README description, else the guide's H1 title. -_vendor_tree_index() { - local dir="$1" f id category summary - [ -d "$dir/guides" ] || return 0 - { - cat <<'EOF' -# Guide index - -One line per guide: `id | category | summary` (the upstream README's -description, else the guide's title). Read `guides//.md`. - -EOF - 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")")" - summary="$(_vendor_tree_summary "$dir/README.md" "$id")" - [ -n "$summary" ] \ - || summary="$(grep -m1 '^# ' "$f" | sed 's/^# //')" - printf -- '- %s | %s | %s\n' "$id" "$category" "${summary:-$id}" - done - } > "$dir/INDEX.md" -} - -# _vendor_tree_stage — copies every -# "\t\t" item from the checkout into -# // and records each dest's lines in .vendored-spec; rc 1 -# (err names the path) when a path is missing, resolves outside the -# checkout, or the copied content holds a symlink. -_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 - case "$(realpath -e -- "$src/$path")" in - "$(realpath -e -- "$src")"/*) ;; - *) err "upstream path leaves the checkout through a symlink: $path" - return 1 ;; - esac - if [ "$target" = "." ]; then - cp -R "$src/$path/." "$stage/$dest/" || return 1 - else - cp -R "$src/$path" "$stage/$dest/$target" || return 1 - fi - done <<<"$3" - if [ -n "$(find "$stage" -type l -print -quit)" ]; then - err "upstream content holds a symlink at the pin — refusing" - return 1 - fi - awk -F'\t' -v s="$stage" 'NF { print > (s "/" $1 "/.vendored-spec") }' \ - <<<"$3" -} - -# _vendor_tree_finish — -# 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 — moves each staged dest into -# /, the previous copy parked under /.old- and -# moved back when the new one cannot be put in place. -_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 - if ! mv "$stage/$dest" "$root/$dest"; then - [ ! -e "$stage/.old-$dest" ] || mv "$stage/.old-$dest" "$root/$dest" - return 1 - fi - done <<<"$3" -} - -# vendor_pinned_tree — see the block comment above. rc 0 when -# every dest is at the pin and allowlist (already or after the fetch), -# rc 1 otherwise. -vendor_pinned_tree() { - local key="$1" 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 _vendor_tree_current "$root" "$sha" "$items"; then - ok "$key already at pin ${sha:0:7}" - return 0 - fi - _vendor_tree_owned "$root" "$dests" || return 1 - local tmp stage - mkdir -p "$root" && tmp="$(mktemp -d)" || return 1 - stage="$(mktemp -d "$root/.vendor-stage.XXXXXX")" \ - || { 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}; a dest not \ -swapped keeps its previous copy (doctor names any not at the pin)" - rm -rf "${tmp:?}" "${stage:?}" - return 1 -} -``` - -Swap failure note: `_vendor_tree_swap` moves dests one by one. When putting a dest in place fails, its previous copy is moved back; a dest swapped before that stays at the new pin (each dest self-consistent, `.vendored-commit` tells which, doctor names it). No INT/TERM trap: a sourced function would override its caller's traps; a Ctrl-C between the two moves leaves the old copy under the stage dir and the next run re-fetches. - -- [ ] **Step 4: Run the suite** - -Run: `make test suite=lib/tests/vendor-tree.test.sh` -Expected: every line `PASS …`, `vendor-tree: 27 pass, 0 fail`, `all suites green` (simulated on a scratch clone 2026-11-22: 27/27). -Then: `shellcheck lib/vendor-skills.sh lib/tests/vendor-tree.test.sh` → no output (simulated: clean). -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 (`EXT_SKILL_NAMES` at :924, call after :932) -- Modify: `update-all.sh` 7.3 (call after :383) -- Modify: `link.sh:78-81` (`EXTERNAL_SKILLS`) -- Modify: `.gitignore` (top flat-link block + a new vendored block after the superpowers block at :139) -- Modify: `lib/doctor-vendored.sh` (new `check_vendored_trees`; `|| true` on the per-name call at :230), `doctor.sh:133` -- Test: `lib/tests/doctor-vendored.test.sh` (new cases) - -**Interfaces:** -- Consumes: `vendor_pinned_tree ` (Task 1). -- Produces: `check_vendored_trees ` (doctor: pass/warn lines, never fail, never trips errexit); lock key `modern-web-guidance`; dests `skills-external/mwg/`, `skills-external/chrome-extensions/`. - -- [ ] **Step 1: Write the failing test** — in `lib/tests/doctor-vendored.test.sh`, insert this block right above the last-but-one line `echo "PASS=$pass FAIL=$fail"` (it uses the suite's `WORK`, `LIB` and `check_bool`): - -```bash -# ── check_vendored_trees: git-tree lock entries; doctor survives errexit ── -TR="$WORK/trees" -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 -printf 'EXTERNAL_SKILLS=(\n ghost-ext\n)\n' > "$TR/link.sh" -out_t="$(check_vendored_trees "$TR" 2>&1)" -printf '%s\n' "$out_t" | grep -q 't: at-pin at pin 1111111' && R1=1 || R1=0 -printf '%s\n' "$out_t" | grep -q 't: skills-external/stale at 2222222, pin 1111111' && R2=1 || R2=0 -printf '%s\n' "$out_t" | grep -q 't: skills-external/absent missing' && R3=1 || R3=0 -# Positive control first: the three lines above must exist. -[ "$R1$R2$R3" = 111 ] && ! printf '%s\n' "$out_t" | grep -q '✗' \ - && R4=1 || R4=0 -# doctor.sh runs under `set -euo pipefail`: a missing tree dest and a -# missing external copy are reported and doctor goes on to its summary. -# shellcheck disable=SC2016 -out_e="$(bash -c 'set -euo pipefail; source "$1" - check_vendored_trees "$2"; check_vendored_skills "$2" "$2/home" - echo DOCTOR_GOES_ON' _ "$LIB" "$TR" 2>&1)" -printf '%s\n' "$out_e" | grep -qx 'DOCTOR_GOES_ON' \ - && printf '%s\n' "$out_e" | grep -q 'ghost-ext: skills-external/ghost-ext/SKILL.md missing' \ - && R5=1 || R5=0 -check_bool TREES_AT_PIN "$R1" -check_bool TREES_STALE_WARN "$R2" -check_bool TREES_MISSING_WARN "$R3" -check_bool TREES_NEVER_FAIL "$R4" -check_bool TREES_ERREXIT_SURVIVES "$R5" -``` - -- [ ] **Step 2: Run it to verify it fails** - -Run: `make test suite=lib/tests/doctor-vendored.test.sh` -Expected: the five new checks FAIL (`check_vendored_trees: command not found`; TREES_NEVER_FAIL needs the three lines above it; TREES_ERREXIT_SURVIVES also fails on the current `_dv_check_name` call). - -- [ ] **Step 3: Implement** - -`lib/doctor-vendored.sh`, append: - -```bash -# _dv_tree_expectations — prints "\t\t" 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 — every git-tree dest exists under -# skills-external/ with a .vendored-commit equal to its pin. Never fails -# and never trips doctor.sh's errexit: a missing or stale copy is a warn -# naming `make plugin`. -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 || true)" - if [ -z "$got" ]; then - warn "$key: skills-external/$dest missing — run: make plugin" - elif [ "$got" != "$sha" ]; then - warn "$key: skills-external/$dest at ${got:0:7}, pin ${sha:0:7} \ -— run: make plugin" - else - pass "$key: $dest at pin ${sha:0:7}" - fi - done < <(_dv_tree_expectations "$repo/plugins.lock.json") -} -``` - -`lib/doctor-vendored.sh:230`, inside `check_vendored_skills`, the line ` _dv_check_name "$repo" "$claude_home" "$name" "$lock_out"` becomes: - -```bash - # fail() reports a miss; doctor.sh (set -e) still reaches its summary. - _dv_check_name "$repo" "$claude_home" "$name" "$lock_out" || true -``` - -(Pre-existing: a missing external copy killed doctor after its first `fail` line; adding `chrome-extensions` to `EXTERNAL_SKILLS` would add one more way to hit it. Simulated: TREES_ERREXIT_SURVIVES fails without either `|| true`, passes with both.) - -`doctor.sh` line 133, after `check_vendored_skills "$REPO" "$HOME/.claude"`: - -```bash -check_vendored_trees "$REPO" -``` - -`plugins.lock.json`, new key right after the `superpowers` entry (keep the file's existing order and formatting): - -```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", "README.md": "README.md"}, - "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. README.md feeds INDEX.md descriptions. chrome-extensions linked as is by link.sh. Bump commit + tag deliberately." -} -``` - -`install-plugins.sh` Step 8e: add `chrome-extensions` at the end of the `EXT_SKILL_NAMES=(…)` array (:924), and after `vendor_pinned_skills superpowers` (:932) add: - -```bash -if ! vendor_pinned_tree modern-web-guidance; then - warn "Modern Web Guidance not vendored (previous copy kept, if any) — rerun: make plugin" -fi -``` - -`update-all.sh` 7.3: after `vendor_pinned_skills superpowers refresh` (:383) add: - -```bash -echo "" -echo "── Updating Modern Web Guidance (GoogleChrome/modern-web-guidance)..." -if ! vendor_pinned_tree modern-web-guidance; then - warn "Modern Web Guidance not vendored (previous copy kept, if any) — rerun: make update" -fi -``` - -`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 (:139) 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 lib/tests/doctor-vendored.test.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 (no routing row) - -**Files:** -- Create: `skills/modern-web-guidance/SKILL.md`, `skills/modern-web-guidance/test-prompts.json` -- Create (tracked symlink): `skills/modern-web-guidance/mwg -> ../../skills-external/mwg` -- Modify: `lib/tests/effort-routing.test.sh:141` (`NO_ROW_SKILLS` gains `modern-web-guidance`) -- 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: , ` / `Modern Web Guidance: checked , 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 is the -# only pre-approved tool, no effort pin and no routing.json row (a row -# reroutes the main loop on load), no npx or network command in a fenced -# block, the relative link into skills-external/mwg, the disclosure -# format, a description within the listing budget. -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; } -fm() { awk '/^---$/{n++; next} n==1' "$S/SKILL.md"; } -check exists "$([ -f "$S/SKILL.md" ] && echo 1)" -check tools "$(fm | grep -qx 'allowed-tools: Read' && echo 1)" -check no-effort "$(fm | grep -q '^effort:' || echo 1)" -desc_len="$(fm | awk '/^description:/{f=1; next} /^[a-z-]+:/{f=0} f' | tr -s ' \n' ' ' | wc -c)" -check desc-budget "$([ "$desc_len" -gt 100 ] && [ "$desc_len" -le 400 ] && echo 1)" -fenced="$(awk '/^```/{f=!f; next} f' "$S/SKILL.md" | grep -c 'npx\|pnpx\|curl\|wget')" -check no-fenced-network "$([ "$fenced" -eq 0 ] && echo 1)" -check never-run "$(grep -q 'Never run npx' "$S/SKILL.md" && echo 1)" -check read-index "$(grep -q 'Read `mwg/INDEX.md` whole' "$S/SKILL.md" && echo 1)" -check search-root "$(grep -q '~/.claude/skills/modern-web-guidance/mwg/guides/' "$S/SKILL.md" && echo 1)" -check disclosure "$(grep -q '`Modern Web Guidance: , `' "$S/SKILL.md" && echo 1)" -check link-mwg "$([ -L "$S/mwg" ] && [ "$(readlink "$S/mwg")" = ../../skills-external/mwg ] && echo 1)" -check tracked-link "$([ "$(cd "$ROOT" && git ls-files skills/modern-web-guidance/mwg | wc -l)" -eq 1 ] && echo 1)" -check no-routing-row "$(grep -q '"modern-web-guidance"\|"chrome-extensions"' "$ROOT/mods/model-router/routing.json" || 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 -description: >- - Current web-platform practice from Google's Modern Web Guidance, read - from a pinned local copy. Use FIRST, before writing or changing - front-end code: HTML, CSS, client-side JS, UI components, forms, - dialogs, layout, motion, Core Web Vitals, images, accessibility. Not - for backend, infra, build tooling or tests. -allowed-tools: Read ---- - -# Modern Web Guidance (local, pinned) - -This folder is `~/.claude/skills/modern-web-guidance/`. Its `mwg/` holds -`INDEX.md`, one line per guide (`- | | `), and the -guides at `mwg/guides//.md`. They are a copy of -GoogleChrome/modern-web-guidance pinned in `plugins.lock.json`; -`mwg/NOTICE.md` names the commit and the licenses. Read is the only tool -needed, nothing here touches the network. - -## Steps - -1. Pick: Read `mwg/INDEX.md` whole (about 210 lines) and choose the - guides whose summary matches a platform feature or UI pattern the - task uses (a modal is `dialog`, an accordion animates to intrinsic - sizes, a slow first paint is LCP). No summary fits a feature: search - `~/.claude/skills/modern-web-guidance/mwg/guides/` once with the - text-search tool at hand, else go on without a guide. -2. Read each chosen guide. Read a discipline guide (the one whose id - equals its category: `html`, `css`, `js`, `forms`, `accessibility`, - `performance`, `security`, `privacy`) only when building a new - component or page, or when no specific guide matched; they are long. -3. Cross-references: a guide line `npx -y modern-web-guidance@latest - retrieve ""` names another guide. Find `` in `mwg/INDEX.md` - for its category and Read `mwg/guides//.md`. - 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. An executor whose closed plan contradicts a guide reports it as - an open choice, never overrides the plan silently. -5. Disclose: the answer that delivers the front-end change (a sub-agent: - its report) ends with one line, `Modern Web Guidance: , `. - Guides checked and none applied: `Modern Web Guidance: checked , - none applied`. No quotes. - -## Missing copy - -`mwg/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. -```` - -Symlink (from the repo root), then stage the skill so the `tracked-link` check can see it: - -```bash -ln -s ../../skills-external/mwg skills/modern-web-guidance/mwg -git add skills/modern-web-guidance -``` - -`skills/modern-web-guidance/test-prompts.json`: - -```json -[ - {"id": 1, "prompt": "Add a confirmation modal before deleting an item", "expected": "Read mwg/INDEX.md, pick dialog, Read the dialog guide, build on per the guide, end with `Modern Web Guidance: `"}, - {"id": 2, "prompt": "Make this accordion open smoothly", "expected": "Pick animate-to-intrinsic-sizes from its summary, Read it, apply its technique and fallback, disclosure line"}, - {"id": 3, "prompt": "Améliore le LCP de la page d'accueil", "expected": "FR trigger: pick the LCP guides, Read them, apply fetchpriority/image guidance, disclosure line"}, - {"id": 4, "prompt": "Write a SQL migration for the orders table", "expected": "Does not trigger: backend task"} -] -``` - -`lib/tests/effort-routing.test.sh:141`: the line becomes - -```bash -NO_ROW_SKILLS=" find-docs graphify impeccable model-router modern-web-guidance " -``` - -No `routing.json` edit: neither `modern-web-guidance` nor `chrome-extensions` gets a row (Global Constraints). - -- [ ] **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"` -Expected: `all suites green`. (The description-collision census reads the live catalog, `~/.claude/skills` → this checkout's `skills/`: it holds our skill as soon as Task 3 lands here, `chrome-extensions` only after Task 6's link.sh. The census runs in Task 6, with both present.) - -- [ ] **Step 5: Commit** - -```bash -git add skills/modern-web-guidance lib/tests/effort-routing.test.sh 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 after the Build bullet ≈ line 57) -- Modify: `skills/pack-design/skills/site-motion/SKILL.md` (after the intro paragraph ending `top of it.`) -- 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 `echo "mwg-skill: …"` of `lib/tests/mwg-skill.test.sh`. Every grepped phrase sits on one line of the text below (checked against it): - -```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-subagent-path "$(grep -qF 'Read `~/.claude/skills/modern-web-guidance/SKILL.md` and follow it.' "$W" && echo 1)" -check rule-plan-time "$(grep -qF 'Planning front-end work runs it before the plan closes.' "$W" && echo 1)" -check rule-guide-wins "$(grep -qF 'the platform, the guide wins.' "$W" && echo 1)" -check rule-no-silent "$(grep -qF 'reports it as an open choice, never overrides it silently.' "$W" && echo 1)" -check rule-disclosure-scope "$(grep -qF 'An answer that delivers a front-end change ends with' "$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; next} /^## /{p=0} p' "$W" | grep -qF '`modern-web-guidance` first for the platform features it uses.' && echo 1)" -check design-heading "$(grep -qx '## Design work — full toolchain (tiered by scope)' "$W" && echo 1)" -check locked-line "$(grep -qxF -- '- 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 except `design-heading` and `locked-line` (already true). - -- [ ] **Step 3: Implement** - -`rules/web-building.md`, insert after the line `# Web building — no default reflexes + done checklist` and its following blank line (keep the line breaks exactly as written): - -```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. No Skill tool (a sub-agent): -Read `~/.claude/skills/modern-web-guidance/SKILL.md` and follow it. -Planning front-end work runs it before the plan closes. -Where a guide and a line below disagree on how to use -the platform, the guide wins. An executor whose closed plan contradicts a guide -reports it as an open choice, never overrides it silently. -An answer that delivers a front-end change ends 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, polish, motion and scroll step above consults - `modern-web-guidance` first for the platform features it uses. -``` - -`skills/pack-design/skills/site-motion/SKILL.md`: after the intro paragraph ending `top of it.`, add a blank line and: - -```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: model-router, reference skills never open the write guard - -User decision 2026-11-22 (contract CLARIFICATIONS): a main-loop call of a reference skill (`modern-web-guidance`, `find-docs`) no longer sets `st.skillRun`, so a direct front-end request still meets the guard's redirect to /hotfix or /feat. Every other skill, rowed or not, keeps opening it. - -**Files:** -- Modify: `mods/model-router/hooks/register.ts` (constant after `INHERITING_AGENTS` ≈ :189; `armTypedSkill` ≈ :3817; `registerSkills` ≈ :4634; the GUARD header comment ≈ :4431) -- Test: `mods/model-router/hooks/register.test.ts` (GUARD block, before `test('GUARD: a Skill call inside a sub-agent does not open it'`) - -- [ ] **Step 1: Write the failing tests** — in `register.test.ts`, insert right before `test('GUARD: a Skill call inside a sub-agent does not open it', async (`: - -```ts -for (const ref of ['modern-web-guidance', 'find-docs']) { - test(`GUARD: the reference skill ${ref} does not open it`, async ( - $, on) => { - await guardRig($, on) - await $.tool.call({ tool: 'Skill', skill: ref } as never) - await endTurn($) - expect(denied(await write($, `${ROOT}/src/a.ts`))).toContain(GUARD) - }) -} - -test('GUARD: a typed reference skill does not open it', async ($, on) => { - await guardRig($, on) - await typed($, '/modern-web-guidance dialog') - await skillPrompt($, 'modern-web-guidance') - await endTurn($) - expect(denied(await write($, `${ROOT}/src/a.ts`))).toContain(GUARD) -}) - -test('GUARD: a reference skill inside a run keeps it open', async ($, on) => { - await guardRig($, on) - await typeFeat($) - await $.tool.call({ tool: 'Skill', skill: 'modern-web-guidance' } as never) - await endTurn($) - expect(denied(await write($, `${ROOT}/src/a.ts`))).toBe('') -}) -``` - -- [ ] **Step 2: Run them to verify they fail** - -Run: `make test suite=lib/tests/mods.test.sh` -Expected: `FAIL model-router: plugin test rc=1: … 3 fail` (simulated 2026-11-22: 663 pass, 3 fail; the "inside a run" test is the positive control and passes either way). - -- [ ] **Step 3: Implement** — in `register.ts`: - -After `const INHERITING_AGENTS: ReadonlySet = new Set(['general-purpose'])` add: - -```ts -// Reference skills read docs (pinned web guides, library docs) and write no -// code: loading one never opens the write guard (user decision 2026-11-22). -const REFERENCE_SKILLS: ReadonlySet = new Set([ - 'modern-web-guidance', 'find-docs', -]) -``` - -In `armTypedSkill`, the line ` if (typed) st.skillRun = true // unrowed too: its body is the user's` becomes: - -```ts - // Unrowed too: its body is the user's. A reference skill writes no code. - if (typed && !REFERENCE_SKILLS.has(skill)) st.skillRun = true -``` - -In `registerSkills`, the line ` if (e.agentId === undefined && !refused) st.skillRun = true` becomes: - -```ts - if (e.agentId === undefined && !refused && - !REFERENCE_SKILLS.has(skill)) st.skillRun = true -``` - -In the GUARD header comment, the line `// latches it anyway.` becomes `// latches it anyway. A reference skill (REFERENCE_SKILLS) never latches.` - -- [ ] **Step 4: Run tests** - -Run: `make test suite="lib/tests/mods.test.sh lib/tests/model-routing.test.sh lib/tests/effort-routing.test.sh"` -Expected: `all suites green` (simulated: `model-router: plugin test passed`, 666 tests). - -- [ ] **Step 5: Commit** - -```bash -git add mods/model-router/hooks/register.ts mods/model-router/hooks/register.test.ts -git commit -m "feat(model-router): reference skills never open the main-loop write guard" -``` - ---- - -### Task 6 (main loop, after Task 5, before the STEP 5 gates): live install, census, doctor - -Not an executor task (network fetch on this machine, link refresh). Contract oracles 1, 4 and 5 read its result, so it runs before GATE 0: - -- `bash -c '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/mwg/INDEX.md` resolves; `grep -c '^- ' skills-external/mwg/INDEX.md` equals the guide count (210 at v1.0.1); 204 lines carry a README description, 6 fall back to the H1. -- `make test suite=lib/tests/skill-routing-census.test.sh`: a pair ≥ 0.75 involving `modern-web-guidance` or `chrome-extensions` → reword our description's list of front-end areas (keep the first sentence, within 400 characters; chrome-extensions is vendored, never reworded) through a fresh executor, re-run. A WARN (≥ 0.50) is reported, not fixed. -- `make doctor` → no new error; `check_vendored_trees` passes both dests. -- Full `make test` (bun on PATH) → green. - -Rollback (if the feature is reverted): `rm ~/.claude/skills/chrome-extensions` (link.sh never unlinks a name dropped from `EXTERNAL_SKILLS`), and delete the gitignored `skills-external/mwg/` and `skills-external/chrome-extensions/` by hand from the repo root. - -## Challenge dispositions (STEP 2b, 2026-11-22) - -- MINOR dropped: shared Python validators across `_vendor_read_tree_lock`, `_vendor_read_lock` and `_dv_tree_expectations` (three heredocs, no shared module; the neighbouring code repeats them too). -- MINOR dropped: INT/TERM trap in `vendor_pinned_tree` (see the swap failure note). -- MINOR dropped: repair of a hand-damaged copy whose markers are intact (delete the dest and rerun; stated in the block comment). -- Confirmation MAJOR (write guard opened by any skill call) → `[deferred 2026-11-22]`, user answer: reopen → Task 5. 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 deleted file mode 100644 index 9e8fa01..0000000 --- a/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md +++ /dev/null @@ -1,147 +0,0 @@ -# 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>/.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 ""`. -- `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 ` reads a new `plugins.lock.json` entry: - -```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", "README.md": "README.md"}, - "chrome-extensions": {".": "skills/chrome-extensions"} - } -} -``` - -- One `git init` + `git fetch --depth 1 ` 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 | 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, 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 - 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 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) - -- `SKILL.md` with `name`, `description` (front-end triggers; not backend, infra, tooling; - at most 400 characters, listing budget), `allowed-tools: Read`. No `effort:` and no - `routing.json` row: a rowed skill reroutes the main loop on load ("last rowed skill - wins"), which would pull design work off `reflect`; listed in `NO_ROW_SKILLS` like - `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 `. -- One tracked relative symlink: `mwg -> ../../skills-external/mwg` (INDEX.md, NOTICE.md, - guides/ behind it). -- Workflow in the body: - 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) - -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. -No routing row (untracked linked external; a row would reroute the main loop on load). - -### 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. - The executors (feater, bugfixer, hotfixer) have no Skill tool in their `tools:`, so the - rule adds: without the Skill tool, Read `~/.claude/skills/modern-web-guidance/SKILL.md` - and follow it. The relative links resolve through the `~/.claude/skills` link (checked - on a fixture). Limit: a Write of a new file loads no path rule (LRN-238). -- model-router: any main-loop Skill call opens the write guard for the session - (`st.skillRun`). A reference-skill list (`modern-web-guidance`, `find-docs`) never - opens it, so a direct front-end request still gets redirected to /hotfix or /feat - (user decision 2026-11-22). - -### 5. Checks and docs - -- `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 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. - -## 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`.