From 05446b2e79c5d2c5ff0109ab760b83efb705d4c6 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 22 Nov 2026 01:22:37 +0100 Subject: [PATCH] docs(plan): modern web guidance, challenge fixes (errexit, fetch failure, ownership, index descriptions) --- .../plans/2026-11-21-modern-web-guidance.md | 445 +++++++++++------- 1 file changed, 277 insertions(+), 168 deletions(-) diff --git a/docs/superpowers/plans/2026-11-21-modern-web-guidance.md b/docs/superpowers/plans/2026-11-21-modern-web-guidance.md index 795e539..25dcc43 100644 --- a/docs/superpowers/plans/2026-11-21-modern-web-guidance.md +++ b/docs/superpowers/plans/2026-11-21-modern-web-guidance.md @@ -4,7 +4,7 @@ **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` / `NOTICE.md` / `.vendored-commit`, and swaps the result in. Our tracked skill `skills/modern-web-guidance/` reaches the guides through relative symlinks 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. +**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. **Tech Stack:** bash, python3 (lock parsing, argv only), git, markdown. @@ -13,6 +13,12 @@ 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`. @@ -20,28 +26,29 @@ Out of this plan, done by `/ship-feature` itself: README / USAGE / CHANGELOG (ST - 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. - 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). +- 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). -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). -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` and follow it; the relative links resolve through the `~/.claude/skills` link (checked on a fixture: kernel resolves `../..` from the link's real directory). +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. ## 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 '^vendor_pinned_tree modern-web-guidance$' install-plugins.sh && grep -q '^vendor_pinned_tree modern-web-guidance refresh$' update-all.sh && [ "$(cat skills-external/mwg/.vendored-commit)" = 64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65 ] && [ "$(grep -c '^- ' skills-external/mwg/INDEX.md)" -eq 210 ] && [ -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` + 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 210 ] && [ -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 '~/.claude/skills/modern-web-guidance/SKILL.md' rules/web-building.md && grep -q 'consult `modern-web-guidance` first' rules/web-building.md && echo WIRED` → EXPECT `WIRED` -4. Upstream SKILL.md not 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` +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: CHECK `make test 2>&1 | tail -1` → EXPECT `all suites green`; CHECK `bash doctor.sh 2>&1 | grep -q 'No errors' && echo DOCTOR_OK` → EXPECT `DOCTOR_OK` (baseline 2026-11-22: "No errors, 2 warning(s)"). Oracles 1, 4 and 5 need the live copy: Task 5 runs after Task 4 and before the STEP 5 gates. @@ -55,20 +62,22 @@ Oracles 1, 4 and 5 need the live copy: Task 5 runs after Task 4 and before the S - Create: `lib/tests/vendor-tree.test.sh` **Interfaces:** -- Produces: `vendor_pinned_tree [refresh]` (rc 0 ok/already at pin, rc 1 any failure, nothing changed); `_vendor_read_tree_lock ` (stdout lines: source, commit, tag, license, then `\t\t`); lock entry shape: +- 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), `NOTICE.md`, and `INDEX.md` when the dest holds `guides/`. +- Writes per dest: `skills-external//.vendored-commit` (the commit), `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 / -# 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. +# 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, a dest owned by someone else never replaced, a +# symlink in the fetched content refused. set -u ROOT="$(cd "$(dirname "$0")/../.." && pwd)" LIB="$ROOT/lib/vendor-skills.sh" @@ -82,8 +91,9 @@ 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. +# 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" @@ -93,6 +103,8 @@ 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" @@ -110,7 +122,7 @@ write_lock() { # write_lock [extra-tree-json] "license": "Apache-2.0 (code), CC-BY 4.0 (guides)", "managed_by": "git-tree", "trees": { - "mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"}, + "mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE", "README.md": "README.md"}, "chrome-extensions": {".": "skills/chrome-extensions"}${2:-} } } @@ -123,41 +135,42 @@ export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$UP" # shellcheck source=../vendor-skills.sh disable=SC1091 source "$LIB" run() { vendor_pinned_tree "$@" >"$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=$? -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-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 install mode at the pin: skip, no fetch (source made unreachable). +# 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 refresh after an upstream drop: old-guide disappears locally. +# 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 refresh; rc=$? +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 refresh installs an absent copy (never-installed machine). +# T4 an absent copy is installed (never-installed machine). rm -rf "$REPO/skills-external/chrome-extensions" -run mwg-key refresh; rc=$? +run mwg-key; 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=$? +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)" @@ -170,7 +183,7 @@ 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=$? +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. @@ -178,12 +191,22 @@ 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)" + 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` @@ -206,17 +229,21 @@ Expected: FAIL lines (`vendor_pinned_tree: command not found` in `$WORK/out`), l # 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 -# skills-external/.vendor-stage./, then swapped in whole, so a file +# 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, 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. +# One mode: skip when every dest is at the pin, else fetch (a pin bump, +# a missing or partial copy). A dest that exists without .vendored-commit +# belongs to someone else and is never replaced; a symlink in the fetched +# 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 @@ -226,13 +253,16 @@ 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 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) @@ -250,10 +280,10 @@ 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}") +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: @@ -284,43 +314,77 @@ _vendor_tree_current() { done <<<"$3" } +# _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" 2>/dev/null || return 1 - GIT_TERMINAL_PROMPT=0 git -C "$dir" fetch -q --depth 1 -- "$url" "$sha" \ - 2>/dev/null || return 1 + 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 \ - 2>/dev/null || return 1 + >/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. +# "- | | " 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 title + local dir="$1" f id category summary [ -d "$dir/guides" ] || return 0 { cat <<'EOF' # Guide index -One line per guide: `id | category | title`. Read `guides//.md`. +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")")" - title="$(grep -m1 '^# ' "$f" | sed 's/^# //')" - printf -- '- %s | %s | %s\n' "$id" "$category" "${title:-$id}" + 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 -# //; rc 1 (err names the path) when a path is missing. +# //; rc 1 (err names the path) when a path is missing 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 @@ -336,6 +400,10 @@ _vendor_tree_stage() { 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 } # _vendor_tree_finish — @@ -355,7 +423,8 @@ _vendor_tree_finish() { } # _vendor_tree_swap — moves each staged dest into -# /, the previous copy parked under /.old-. +# /, 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 @@ -363,13 +432,17 @@ _vendor_tree_swap() { if [ -e "$root/$dest" ]; then mv "$root/$dest" "$stage/.old-$dest" || return 1 fi - mv "$stage/$dest" "$root/$dest" || return 1 + 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 [refresh] — see the block comment above. +# vendor_pinned_tree — see the block comment above. rc 0 when +# every dest is at the pin (already or after the fetch), rc 1 otherwise. vendor_pinned_tree() { - local key="$1" refresh="${2:-}" out root="$VENDOR_REPO/skills-external" + 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" @@ -383,33 +456,36 @@ vendor_pinned_tree() { { 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 + if _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; } + _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" + 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" + 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; 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. +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: 21 pass, 0 fail`, `all suites green` (simulated on a scratch clone 2026-11-22: 21/21). +Expected: every line `PASS …`, `vendor-tree: 24 pass, 0 fail`, `all suites green` (simulated on a scratch clone 2026-11-22: 24/24). 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`. @@ -426,53 +502,58 @@ git commit -m "feat(vendor): vendor_pinned_tree fetches whole upstream trees at **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: `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) -- Modify: `lib/doctor-vendored.sh` (new `check_vendored_trees`), `doctor.sh:133` +- 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 [refresh]` (Task 1). -- Produces: `check_vendored_trees ` (doctor: pass/warn lines, never fail); lock key `modern-web-guidance`; dests `skills-external/mwg/`, `skills-external/chrome-extensions/`. +- 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** — 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): +- [ ] **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 ── -TR="$(mktemp -d)" +# ── 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" +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 +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 +printf '%s\n' "$out_t" | grep -q '✗' && R4=0 || R4=1 +# 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" ``` -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`). +Expected: the five new checks FAIL (`check_vendored_trees: command not found`; TREES_ERREXIT_SURVIVES also fails on the current `_dv_check_name` call). - [ ] **Step 3: Implement** @@ -503,17 +584,20 @@ PY } # check_vendored_trees — 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`. +# 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)" + got="$(cat "$repo/skills-external/$dest/.vendored-commit" \ + 2>/dev/null || true)" if [ -z "$got" ]; then - warn "$key: skills-external/$dest missing — run: make update" + 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 update" + 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 @@ -521,13 +605,22 @@ check_vendored_trees() { } ``` +`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 (keep the file's existing key order; place it after `superpowers`): +`plugins.lock.json`, new key right after the `superpowers` entry (keep the file's existing order and formatting): ```json "modern-web-guidance": { @@ -538,32 +631,34 @@ check_vendored_trees "$REPO" "managed_by": "git-tree", "always_on": true, "trees": { - "mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"}, + "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. chrome-extensions linked as is by link.sh. Bump commit + tag deliberately." + "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: after `vendor_pinned_skills superpowers` add +`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 -vendor_pinned_tree modern-web-guidance +if ! vendor_pinned_tree modern-web-guidance; then + warn "Modern Web Guidance not vendored (previous copy kept, if any) — rerun: make plugin" +fi ``` -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 +`update-all.sh` 7.3: after `vendor_pinned_skills superpowers refresh` (:383) add: ```bash echo "" echo "── Updating Modern Web Guidance (GoogleChrome/modern-web-guidance)..." -vendor_pinned_tree modern-web-guidance refresh +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 add +`.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', @@ -578,7 +673,7 @@ 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. +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** @@ -593,7 +688,7 @@ git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extension **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` +- 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` @@ -608,8 +703,8 @@ git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extension # 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 three relative links into skills-external/mwg, the -# disclosure format, a description within the listing budget. +# 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" @@ -624,14 +719,12 @@ check desc-budget "$([ "$desc_len" -gt 100 ] && [ "$desc_len" -le 400 ] && echo 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 `INDEX.md` whole' "$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)" -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)" +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 no-row-listed "$(grep -q '^NO_ROW_SKILLS=".* modern-web-guidance ' "$ROOT/lib/tests/effort-routing.test.sh" && 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 ] @@ -659,58 +752,60 @@ allowed-tools: Read # Modern Web Guidance (local, pinned) -This folder (`~/.claude/skills/modern-web-guidance/`) holds `INDEX.md`, one -line per guide (`- | | `), and the guides at -`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. Read is the only tool needed, nothing -here touches the network. +This folder is `~/.claude/skills/modern-web-guidance/`. Its `mwg/` holds +`INDEX.md`, one line per guide (`- <id> | <category> | <summary>`), and the +guides at `mwg/guides/<category>/<id>.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 `INDEX.md` whole (about 210 short lines) and choose the - guides whose title matches a platform feature or UI pattern the task - uses (a modal is `dialog`, a tooltip a popover, a slow first paint - LCP). No title fits a feature: search the guide bodies under `guides/` - once with the text-search tool at hand, else go on without a guide. -2. Read each chosen guide, plus the discipline guide of each category - touched: the guide whose id equals its category (`html`, `css`, `js`, - `forms`, `accessibility`, `performance`, `security`, `privacy`). +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 "<id>"` names another guide. Find `<id>` in `INDEX.md` for its - category and Read `guides/<category>/<id>.md`. Never run npx, the - guidance CLI or any network command for this skill. + retrieve "<id>"` names another guide. Find `<id>` in `mwg/INDEX.md` + for its category and Read `mwg/guides/<category>/<id>.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. -5. Disclose: end the answer that delivers the front-end change (a - sub-agent: its report) with one line, `Modern Web Guidance: <id>, <id>`. + 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: <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. +`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. ```` -Symlinks (from the repo root): +Symlink (from the repo root), then stage the skill so the `tracked-link` check can see it: ```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 +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 INDEX.md, pick 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": 1, "prompt": "Add a confirmation modal before deleting an item", "expected": "Read mwg/INDEX.md, pick dialog, Read the dialog guide, build on <dialog> per the guide, end with `Modern Web Guidance: <ids>`"}, + {"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"} ] ``` @@ -725,8 +820,8 @@ No `routing.json` edit: neither `modern-web-guidance` nor `chrome-extensions` ge - [ ] **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 list of front-end areas (keep the first sentence, stay within 400 characters) and re-run; a WARN (≥ 0.50) is acceptable and is reported. +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 runs on the live catalog, which holds neither skill before Task 5: its check moves to Task 5.) - [ ] **Step 5: Commit** @@ -740,43 +835,50 @@ 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) +- 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 of `lib/tests/mwg-skill.test.sh`: +- [ ] **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-guide-wins "$(grep -q 'platform, the guide wins' "$W" && echo 1)" -check rule-subagent-path "$(grep -q 'Read `~/.claude/skills/modern-web-guidance/SKILL.md`' "$W" && 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} /^## /&&!/Design work/{p=0} p' "$W" | grep -q 'consult `modern-web-guidance` first' && 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 -qx '- The vendored stack members route to `reflect` (high) through their' "$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. +- [ ] **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: +`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. Without the Skill tool (a sub-agent), Read -`~/.claude/skills/modern-web-guidance/SKILL.md` and follow it. 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. +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. ``` @@ -801,12 +903,11 @@ with 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. +- 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`: append to the intro paragraph ending `top of it.` a new paragraph: +`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 @@ -828,12 +929,20 @@ git commit -m "feat(rules): front-end work consults modern-web-guidance first" --- -### Task 5 (main loop, after Task 4, before the STEP 5 gates): live install and doctor +### Task 5 (main loop, after Task 4, 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: -- `source lib/vendor-skills.sh && vendor_pinned_tree modern-web-guidance` → `modern-web-guidance vendored (pinned @ 64a6d70): chrome-extensions mwg`. +- `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/INDEX.md` resolves; `grep -c '^- ' skills-external/mwg/INDEX.md` → 210. +- `ls skills/modern-web-guidance/mwg/INDEX.md` resolves; `grep -c '^- ' skills-external/mwg/INDEX.md` → 210; 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).