chore(memory): BDR-152 + BDR-153 + LRN-305 — ship-feature modern-web-guidance · TODO +1 / -0

This commit is contained in:
bchanot committed 2026-11-22 17:05:26 +01:00
1 parent 2fd155ab90
commit 5651cc09f7
5 files changed
+86

No files matched your search

+12
View File
@@ -1621,3 +1621,15 @@ Supersedes [[BDR-030]].
- **Why**: session c9afbcbf open TODO 44→50 while closing items; MINOR→backlog was habit, no rule; challenge on placement runs found no MAJOR; verifier ECARTS were own contract bookkeeping. - **Why**: session c9afbcbf open TODO 44→50 while closing items; MINOR→backlog was habit, no rule; challenge on placement runs found no MAJOR; verifier ECARTS were own contract bookkeeping.
- **Alternatives rejected**: TODO cap/expiry (cap 10 starts violated); "fix if under five minutes" post-gate exit; base from merge-base (overcounts multi-run branch) or pending diff only (misses earlier commits); verifier exempting whole `.claude/tasks/plans/` (142 durable plans, BDR-065 amendment). - **Alternatives rejected**: TODO cap/expiry (cap 10 starts violated); "fix if under five minutes" post-gate exit; base from merge-base (overcounts multi-run branch) or pending diff only (misses earlier commits); verifier exempting whole `.claude/tasks/plans/` (142 durable plans, BDR-065 amendment).
- **Reference**: 19dfe7e, 39cf9dd, docs e8c061e; handoff plan .claude/tasks/plans/2026-11-20-done-and-triage-levers.md; contract .claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md. Follow-up /feat (contract-interview, ship-feature STEP 6, init-project STEP 10, run_base `--end-of-options`, [gated] only untracked) open in TODO. - **Reference**: 19dfe7e, 39cf9dd, docs e8c061e; handoff plan .claude/tasks/plans/2026-11-20-done-and-triage-levers.md; contract .claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md. Follow-up /feat (contract-interview, ship-feature STEP 6, init-project STEP 10, run_base `--end-of-options`, [gated] only untracked) open in TODO.
## BDR-152 — Modern Web Guidance vendored as git-tree pin v1.0.1 with own Read-only skill, fixed pin is a BDR-056 exception [accepted] (2026-11-22)
- **Decision**: Google Modern Web Guidance (GoogleChrome/modern-web-guidance tag v1.0.1, `64a6d70`) vendored as `managed_by: git-tree` lock entry. `vendor_pinned_tree` (lib/vendor-skills.sh): one shallow fetch at pin, HEAD == pin else refuse, allowlist copy per dest, generated INDEX.md + NOTICE.md, marker-owned swap into skills-external/{mwg,chrome-extensions}. Own thin skill `modern-web-guidance`: allowed-tools Read, no effort, no routing row (NO_ROW_SKILLS), tracked `mwg` link; reads INDEX then guides by local path, never npx or network; disclosure line `Modern Web Guidance: <id>, <id>`. Wiring: rules/web-building.md `## Modern Web Guidance first` (guide wins on platform usage, sub-agent without Skill tool Reads SKILL.md, executor reports plan/guide conflict as open choice) + § Design work + site-motion. Audit skills, agents, CLAUDE.global.md untouched. chrome-extensions always on in EXTERNAL_SKILLS, as is. Doctor `check_vendored_trees` warn only. Fixed pin = assumed exception to BDR-056: pin moves only by editing lock; every bump reviews upstream diff for instruction-like text (guides enter context and outrank local web rules = injection surface bounded by pin).
- **Why**: upstream SKILL.md runs `npx -y modern-web-guidance@latest` each call = remote code + network at use time. User wants current platform practice applied systematically on all front-end work.
- **Alternatives rejected**: link upstream skill (npx latest); per-file curl via `vendor_pinned_skills` (210 guides, no prune on bump); routing row (rowed skill reroutes main loop on load, pulls design off `reflect`); .js/.ts glob on path rule (user: globs unchanged); wiring in audit skills or agents (user).
- **Reference**: 1213af8 04b2d6a 8a8d77f 9bdd07d f91da50 ec2a7b4 2fd155a; spec docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md; contract .claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md. Known limits: ~39 KB INDEX read per front-end task; Write of new file loads no path rule (LRN-238); missing chrome-extensions copy = check_vendored_skills FAIL, doctor exit 1 until `make plugin`.
## BDR-153 — model-router: reference skills never open the main-loop write guard [accepted] (2026-11-22)
- **Decision**: `REFERENCE_SKILLS` (`modern-web-guidance`, `find-docs`) in mods/model-router/hooks/register.ts. Both `st.skillRun = true` sites (typed path armTypedSkill, Skill-tool path registerSkills) skip them. Any other skill still opens guard. Exemption never clears an open run. 4 GUARD tests in register.test.ts.
- **Why**: web rule makes main loop call `modern-web-guidance` before front-end code. Any main-loop Skill call latched `skillRun` → guard open for session → main loop could write front code outside /feat or /hotfix (find-docs already did). Reopened [deferred] confirmation MAJOR, user 2026-11-22 "Rouvrir : exemption".
- **Alternatives rejected**: keep latch (doctrine "no code outside a skill run" defeated by a reference read); clear `skillRun` after reference skill (could close a real run).
- **Reference**: 49d8811; contract .claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md criterion 11. Known gap: future routing row for a reference skill reopens guard via typed route. GUARD_REASON text "re-enter the skill you were running" may point at a reference skill (review Minor, dropped).
+3
View File
@@ -800,3 +800,6 @@ rules:
- /hotfix deferred-stop: [deferred] point stops run once at end of challenge step (keep/cut/reopen, answers bind via contract [gated] + later CONSTRAINTS, /hotfix asks itself, no re-challenge after cut/reopen unless asked). r2 confirmation 5 MAJORs deferred → user answered batch (rule dogfooded). TODO decision closed. - /hotfix deferred-stop: [deferred] point stops run once at end of challenge step (keep/cut/reopen, answers bind via contract [gated] + later CONSTRAINTS, /hotfix asks itself, no re-challenge after cut/reopen unless asked). r2 confirmation 5 MAJORs deferred → user answered batch (rule dogfooded). TODO decision closed.
- /feat deferred-citers (first placed-decision challenge skip): feat/bugfix/hotfix point at challenge-plan § OUTPUT deferred stop. Gates first pass (MET, CONFORME, PASS). Docs a732c6c (README/USAGE/CHANGELOG). - /feat deferred-citers (first placed-decision challenge skip): feat/bugfix/hotfix point at challenge-plan § OUTPUT deferred stop. Gates first pass (MET, CONFORME, PASS). Docs a732c6c (README/USAGE/CHANGELOG).
- User 2026-11-21: [gated] on tracked contract → keep current behaviour, limit recorded in TODO; release deferred (testing phase). - User 2026-11-21: [gated] on tracked contract → keep current behaviour, limit recorded in TODO; release deferred (testing phase).
## 2026-11-22
- ship-feature modern-web-guidance: MWG v1.0.1 git-tree pin + own Read-only skill + web-building wiring + router reference-skill exemption. Gates CONFORME/PASS, review Yes, docs synced. BDR-152, BDR-153, LRN-305. Finish awaits user go.
+6
View File
@@ -2186,3 +2186,9 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s
- **Context**: 2026-11-20 /feat done-triage-levers, lever 6 `TODO +n / -m`. r1 put count in DO step 3 ("taken before step 2" in prose, but placed after). Contract CHECK ran on uncommitted fixture → green. r2 confirmation challenger traced step order → MAJOR. Fix: count in DO step 1, run-base SHA from contract, root pathspec `:/` (subdir cwd = silent 0 too), `--no-color --no-ext-diff`. - **Context**: 2026-11-20 /feat done-triage-levers, lever 6 `TODO +n / -m`. r1 put count in DO step 3 ("taken before step 2" in prose, but placed after). Contract CHECK ran on uncommitted fixture → green. r2 confirmation challenger traced step order → MAJOR. Fix: count in DO step 1, run-base SHA from contract, root pathspec `:/` (subdir cwd = silent 0 too), `--no-color --no-ext-diff`.
- **Apply**: any "report what the run changed" counter: place it before the commit step in the doc's own numbering; base = SHA recorded at run start, never a branch name; fixture rows: uncommitted, committed, subdir cwd, bad SHA → n/a. - **Apply**: any "report what the run changed" counter: place it before the commit step in the doc's own numbering; base = SHA recorded at run start, never a branch name; fixture rows: uncommitted, committed, subdir cwd, bad SHA → n/a.
- **Reference**: lib/capitalize-commit.md DO step 1, lib/memory-commit.sh MC_PATHS, LRN-298 (placement semantics), LRN-193 - **Reference**: lib/capitalize-commit.md DO step 1, lib/memory-commit.sh MC_PATHS, LRN-298 (placement semantics), LRN-193
## LRN-305 — Contract dry run while an executor edits the tree gives false reds (2026-11-22)
- **Pattern**: contract dry run (`gates.sh run` on mktemp copy of working tree) taken while a dispatched executor still edits → copy holds half-applied state → oracle rows red that turn green once executor reports.
- **Context**: 2026-11-21/22 ship-feature modern-web-guidance. Dry run overlapped running executor → false reds; re-run after report = MET. Separate real red same run: row 10 `FAIL bun not on PATH` (see learnings line ~2009, fixed by `PATH="$HOME/.bun/bin:$PATH"` in oracle).
- **Apply**: dry run only with no live executor (before first dispatch, or after its report). Red dry run during a dispatch → re-run after report before acting on it.
- **Reference**: lib/verify-secure-loop.md § BEFORE THE FIRST DISPATCH; BDR-151 lever 4 (contract dry run).
+1
View File
@@ -101,6 +101,7 @@ Open children of the shipped phases (History 2026-11-12), text verbatim.
- [x] DONE c25a7ea (user 2026-11-17: default 600 s, env override kept) gates.sh default `GATES_TIMEOUT=120` < full `make test` (~135 s on 2026-11-16): a "Full make test green" criterion goes NOT-MET on timeout alone (A6 run, re-run with GATES_TIMEOUT=400). Raise the default or have contract-interview write the timeout for full-suite criteria. - [x] DONE c25a7ea (user 2026-11-17: default 600 s, env override kept) gates.sh default `GATES_TIMEOUT=120` < full `make test` (~135 s on 2026-11-16): a "Full make test green" criterion goes NOT-MET on timeout alone (A6 run, re-run with GATES_TIMEOUT=400). Raise the default or have contract-interview write the timeout for full-suite criteria.
- [x] DONE 5bba6ce, merged 30f9825, /hotfix 2026-11-20: numeric id required, indented ABANDON counts (game ledger 2026-09-30-verify-qual-deparse MET → ABANDONED(1)), malformed → ERROR, 5 tests. Was: gates.sh:93 ABANDON regex `([0-9]+)?` reads `ABANDON: 1b …` / `1.1` as id 1: after a renumber (LRN-284) criterion 1 is masked ABANDONED (rc 3) instead of "unknown criterion" ERROR. Anchor the id `([0-9]+)([[:space:]]|$)` + test (robustness challenger, gates hotfix 2026-11-17) - [x] DONE 5bba6ce, merged 30f9825, /hotfix 2026-11-20: numeric id required, indented ABANDON counts (game ledger 2026-09-30-verify-qual-deparse MET → ABANDONED(1)), malformed → ERROR, 5 tests. Was: gates.sh:93 ABANDON regex `([0-9]+)?` reads `ABANDON: 1b …` / `1.1` as id 1: after a renumber (LRN-284) criterion 1 is masked ABANDONED (rc 3) instead of "unknown criterion" ERROR. Anchor the id `([0-9]+)([[:space:]]|$)` + test (robustness challenger, gates hotfix 2026-11-17)
- [ ] parked (GATE 2 LOW, 5a98c2c): probe table names not checked with `IDENT.fullmatch` per table (a `/` walks a path on the approved Supabase host); `printable` lets Unicode bidi/format controls (U+202E, U+2066…) through to the tty - [ ] parked (GATE 2 LOW, 5a98c2c): probe table names not checked with `IDENT.fullmatch` per table (a `/` walks a path on the approved Supabase host); `printable` lets Unicode bidi/format controls (U+202E, U+2066…) through to the tty
- [ ] parked (GATE 2 LOW, feature/modern-web-guidance): lib/vendor-skills.sh `vendor_pinned_tree` symlink check runs after the `cp -R` (overlapping lock targets could write through an upstream symlink; check each listed path before copy or reject overlaps); `_vendor_tree_swap` restore-mv failure → stage cleanup deletes the parked old copy (keep stage, name its path); `python3 -` without `-I` in vendor-skills.sh:271, doctor-vendored.sh:239
- [x] profile name charset check (done by phase 5: `NAME_RE='^[a-z0-9][a-z0-9-]*$'` lib/profile.sh:63 on every profile and session name; the old `read_profile()` is gone) - [x] profile name charset check (done by phase 5: `NAME_RE='^[a-z0-9][a-z0-9-]*$'` lib/profile.sh:63 on every profile and session name; the old `read_profile()` is gone)
- [ ] P22 `make new-skill` scaffold: agent stub lacks `effort:` pin, skill stub lacks entry level, body loads `.claude/agents/$(name).md` instead of `$HOME/.claude/agents/<name>.md` → /hotfix; also: no routing.json row reminder - [ ] P22 `make new-skill` scaffold: agent stub lacks `effort:` pin, skill stub lacks entry level, body loads `.claude/agents/$(name).md` instead of `$HOME/.claude/agents/<name>.md` → /hotfix; also: no routing.json row reminder
- [x] `lib/tests/design-tool-gate.test.sh` hermetic CLI_ABSENT case (done by the phase 5 rewrite: suite green 2026-11-02 with `~/.local/bin/21st` installed, `make test` all suites green on this machine) - [x] `lib/tests/design-tool-gate.test.sh` hermetic CLI_ABSENT case (done by the phase 5 rewrite: suite green 2026-11-02 with `~/.local/bin/21st` installed, `make test` all suites green on this machine)
@@ -0,0 +1,64 @@
# CONTRACT — modern-web-guidance
- date: 2026-11-21 | flow: ship-feature | branch: feature/modern-web-guidance
- status: active
- run-base: d74dd2c8fadad2cba5de5118593aa9837b3efb5c
## REQUEST (verbatim — IMMUTABLE)
j'aimerias qu'on rajoute un skill ou une guidance pour tout ce qui est front, web ou non, tout ce qui s'applique, utiliser le modern web guidance de google https://developer.chrome.com/docs/modern-web-guidance?hl=fr pour tout ce qui est ajour sur les facon de faire et qu'il soit utiliser systematiquement sur les front donc avec les autre skill et agents de front
## CLARIFICATIONS
Q: delivery of the upstream package (its skill runs `npx -y modern-web-guidance@latest` on every call) / A: pinned vendor copy at v1.0.1, our own thin skill reads the local guides, no npx, no network, no remote code; upstream SKILL.md not linked [gated 2026-11-21]
Q: where it is wired / A: path rule rules/web-building.md + design skills (not audit skills, not agents) [gated 2026-11-21]
Q: disclosure / A: short, one line at the end of a front-end answer naming the guide ids consulted, no quotes [gated 2026-11-21]
Q: chrome-extensions skill of the same package / A: installed too, vendored and pinned [gated 2026-11-21]
Q: name and placement of our skill / A: `modern-web-guidance`, flat in skills/, always on in every profile; the vendored dir carries another name [gated 2026-11-21]
Q: guide vs our web rules when they disagree / A: the guide wins on how to use the platform; our rule is adjusted (e.g. motion line) [gated 2026-11-21]
Q: path rule globs / A: unchanged (no .js/.mjs/.ts); plain client JS relies on the skill description [gated 2026-11-21]
Q: chrome-extensions placement / A: always on, as is (its CHROMEWEBSTORE.md behaviour accepted, it only triggers on extension work) [gated 2026-11-21]
Q: plugin gate, switch this repo to the dev profile / A: no, keep full [gated 2026-11-21]
Q: challenge deferred point (confirmation MAJOR): any main-loop Skill call sets model-router `st.skillRun` (register.ts:4634) and opens the write guard for the session, so the rule's skill call would let the main loop write front code outside a code skill (find-docs already does) / A: reopen — model-router gets a reference-skill list (`modern-web-guidance`, `find-docs`) that never opens the guard, with tests; FILE SCOPE gains mods/model-router/hooks/register.ts and register.test.ts [gated 2026-11-22]
## ACCEPTANCE CRITERIA
1. The Modern Web Guidance guides of tag v1.0.1 (commit 64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65) and the chrome-extensions skill are vendored, pinned by that commit in plugins.lock.json, installed by `make plugin` and refreshed at the pin by `make update`; no install or use path runs `npx modern-web-guidance` or reaches the network at use time.
2. Our own skill exposes the local guides (search and read by id) with no npx and no network, and states the short disclosure line.
3. rules/web-building.md tells any front-end work to consult the guidance before writing code, and § Design work makes every design-stack step consult it.
4. The upstream modern-web-guidance SKILL.md is not linked into ~/.claude.
5. `make test` stays green (bun on PATH) and `make doctor` reports no new error.
6. [gated 2026-11-22] Pin, install wiring and the live copy: plugins.lock.json key `modern-web-guidance` holds tag v1.0.1 and commit 64a6d708…; both install-plugins.sh and update-all.sh call `vendor_pinned_tree modern-web-guidance` inside `if !` (a fetch failure warns, never aborts); skills-external/mwg is at the pin, INDEX.md has one line per guide, no upstream SKILL.md; the vendor-tree suite is 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 "$(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
EVIDENCE: MET exit=0 marker-found :: all suites green
7. [gated 2026-11-22] Our skill skills/modern-web-guidance: allowed-tools Read only, no effort, no routing row (NO_ROW_SKILLS), description within 400 characters, reads mwg/INDEX.md then guides by local path, never runs npx or a network command, one tracked `mwg` symlink, the disclosure line scoped to answers that deliver a front-end change.
CHECK: make test suite=lib/tests/mwg-skill.test.sh 2>&1 | tail -1
EXPECT: all suites green
EVIDENCE: MET exit=0 marker-found :: all suites green
8. [gated 2026-11-22] Rule wiring: rules/web-building.md has the section `## Modern Web Guidance first` (sub-agent path without the Skill tool, guide wins on platform usage, an executor reports a plan/guide conflict as an open choice) and § Design work makes every Build, polish, motion and scroll step consult it; the Design work heading and the locked `reflect` line stay byte-identical; site-motion carries the same line.
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
EVIDENCE: MET exit=0 marker-found :: WIRED
9. [gated 2026-11-22] The upstream modern-web-guidance SKILL.md (npx search/retrieve) is linked nowhere under ~/.claude/skills; chrome-extensions is linked as an always-on flat skill.
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
EVIDENCE: MET exit=0 marker-found :: NOT_LINKED
10. [gated 2026-11-22] Full suite green and doctor reports no error (baseline 2026-11-22: "No errors, 2 warning(s)").
CHECK: PATH="$HOME/.bun/bin:$PATH" 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
EVIDENCE: MET exit=0 marker-found :: SUITE_DOCTOR_OK
11. [gated 2026-11-22] model-router: a main-loop Skill call to a reference skill (`modern-web-guidance`, `find-docs`) never sets `st.skillRun`, typed or by name; any other skill still opens the write guard; covered by register.test.ts.
CHECK: grep -q "'modern-web-guidance', 'find-docs'," mods/model-router/hooks/register.ts && PATH="$HOME/.bun/bin:$PATH" make test suite=lib/tests/mods.test.sh 2>&1 | tail -1
EXPECT: all suites green
EVIDENCE: MET exit=0 marker-found :: all suites green
12. [gated 2026-11-22] Doctor: check_vendored_trees warns (never errors) on a missing or stale vendored tree with the remedy `make plugin`, and a missing vendored copy no longer stops doctor under `set -euo pipefail`.
13. [gated 2026-11-22] vendor_pinned_tree refuses before writing anything: a commit not upstream, unsafe lock paths, a dest it did not create (no marker), a symlink in the fetched content or a listed path leaving the checkout; a failed swap restores the previous copy.
## FILE SCOPE
[gated 2026-11-22, STEP 3 approved plan docs/superpowers/plans/2026-11-21-modern-web-guidance.md]
- lib/vendor-skills.sh, lib/tests/vendor-tree.test.sh
- plugins.lock.json, install-plugins.sh, update-all.sh, link.sh, .gitignore
- lib/doctor-vendored.sh, doctor.sh, lib/tests/doctor-vendored.test.sh
- skills/modern-web-guidance/ (SKILL.md, test-prompts.json, `mwg` symlink), lib/tests/mwg-skill.test.sh, lib/tests/effort-routing.test.sh
- rules/web-building.md, skills/pack-design/skills/site-motion/SKILL.md
- mods/model-router/hooks/register.ts, mods/model-router/hooks/register.test.ts
- docs (STEP 8): README.md, USAGE.md, CHANGELOG.md, docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md, docs/superpowers/plans/2026-11-21-modern-web-guidance.md
- generated, gitignored (Task 6): skills-external/mwg/, skills-external/chrome-extensions/, skills/chrome-extensions link