chore: purge transient planning artifacts (BDR-065)

This commit is contained in:
bchanot committed 2026-11-22 20:08:13 +01:00
1 parent 7e29279b24
commit 0dc0814d62
2 files changed
-1218

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -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>/<id>.md`, 210 files,
~2 MB, no frontmatter, id = basename (unique). 174 lines in 67 guides cross-reference
other guides as `npx -y modern-web-guidance@latest retrieve "<id>"`.
- `skills/chrome-extensions/`: `SKILL.md` + `references/` (24 files, no npx); it names the
`modern-web-guidance` skill and maintains a `CHROMEWEBSTORE.md` in extension projects.
## Components
### 1. Pinned fetch (`lib/vendor-skills.sh`, new function)
`vendor_pinned_tree <lock-key>` 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 <source> <commit>` in a `mktemp -d` path, checkout
`FETCH_HEAD`, then `git rev-parse HEAD` must equal `commit` (else refuse, nothing written).
- Copies only the listed repo paths into a staging dir per destination; the upstream
`skills/modern-web-guidance/SKILL.md` is never copied.
- For `mwg`: generates `INDEX.md` (one line per guide: `- id | category | summary`, the
summary from the upstream README description, else the guide's H1) and an attribution
`NOTICE.md` (source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code).
- Swaps each staging dir into `skills-external/<dest>` (old dir removed after the new one is
complete, restored if the swap fails), so guides dropped upstream disappear on a pin bump.
- One mode: a dest whose `.vendored-commit` equals the pin and whose `.vendored-spec`
equals its allowlist is skipped; anything else (absent copy, older pin, edited
allowlist) is fetched. A dest that exists without `.vendored-commit` is never replaced.
A symlink in the fetched content, or a listed path resolving outside the checkout, is
refused with nothing swapped.
- Same validation as `vendor_pinned_skills`: `commit` 40 lowercase hex, `source`
`https://github.com/<o>/<r>`, paths `[A-Za-z0-9._/-]`, no `..`, no leading `/`. A
`VENDOR_BASE_URL=file://…` override serves the hermetic suite (same rule as the
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 <pkg>`.
- 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 "<id>"` means: find `<id>` in `mwg/INDEX.md`, Read
`mwg/guides/<category>/<id>.md`. Never run npx or any network command for this skill.
4. Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule
of `rules/web-building.md` disagree on how to use the platform, the guide wins. An
executor whose closed plan contradicts a guide reports it as an open choice.
5. The answer that delivers the front-end change (a sub-agent: its report) ends with one
line: `Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>,
none applied`). No quotes.
- Copy missing (dangling link): say so, remedy `make update`; continue without it.
- `test-prompts.json` (darwin convention).
### 3. chrome-extensions (vendored, always on, as is)
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`.