From 80353fe52847768e2d071b0b84acad6318826f08 Mon Sep 17 00:00:00 2001 From: fredericrous Date: Tue, 27 Oct 2026 18:42:17 +0100 Subject: [PATCH 1/2] docs(skills): aval answers at in_scopes The interface skills, worktree-task 2b and interface-review say that aval resolve answers at the repository's declared in_scopes (decisions ADR-0046), not at a scope the reader must pick. Co-Authored-By: Claude Opus 5.5 --- .../2026-10-27-repo-declares-its-scopes.md | 25 +++++++++++++++++++ dot_claude/agents/interface-review.md | 2 +- dot_claude/skills/accessibility/SKILL.md | 2 +- dot_claude/skills/interface-review/SKILL.md | 2 +- dot_claude/skills/interface/SKILL.md | 2 +- dot_claude/skills/layout/SKILL.md | 2 +- dot_claude/skills/worktree-task/SKILL.md | 2 +- dot_claude/skills/writing/SKILL.md | 2 +- 8 files changed, 32 insertions(+), 7 deletions(-) create mode 100644 docs/plans/2026-10-27-repo-declares-its-scopes.md diff --git a/docs/plans/2026-10-27-repo-declares-its-scopes.md b/docs/plans/2026-10-27-repo-declares-its-scopes.md new file mode 100644 index 0000000..3d9a0cc --- /dev/null +++ b/docs/plans/2026-10-27-repo-declares-its-scopes.md @@ -0,0 +1,25 @@ +--- +canonical: github:fredericrous/aval/docs/plans/2026-10-27-repo-declares-its-scopes.md +phases: [4] +status: done +branch: docs/scope-membership +--- +# A repository declares the scopes it is in + +Pointer. The plan lives in aval (aval#46, 1.11.0); the ADR is decisions +ADR-0046 (decisions#102). This repository carries the dotfiles part of +Phase 4: the interface, layout, writing, accessibility and interface-review +skills, worktree-task step 2b and the interface-review agent now say that +`aval resolve ` answers at the repository's declared `in_scopes`, with no +hand-typed `--scope`. + +## Verification record + +- The two phrasings ("resolved at its applicable scope", "at the diff's + scope") → replaced in all 7 files → 7 replacements in the source, 7 in the + live `~/.claude` copies; each source file is byte-identical to its live copy + (the laptop is the source). +- The behaviour the text now names → a scratch UI change in customer-vision + (declared `[effect-stack, duro-stack]`) → `amont-agent review-brief` carried + `ui.design-system` (ADR-0006 at duro-stack), `ui.measures`, + `stack.web-framework`. diff --git a/dot_claude/agents/interface-review.md b/dot_claude/agents/interface-review.md index b2cf98f..5881d5c 100644 --- a/dot_claude/agents/interface-review.md +++ b/dot_claude/agents/interface-review.md @@ -12,7 +12,7 @@ anything, and never approve on the author's behalf. Your prompt carries the brief the session built: the base sha, the scope block, the `aval traits` output, the `aval resolve` output for the ui and -design-system keys at the diff's scope (with the exemption list of +design-system keys, which `aval resolve ` answers at the repository's declared `in_scopes` (decisions ADR-0046) (with the exemption list of `design-system.every-measure-is-a-token`), the full diff and the removed lines of `git diff -U0`. Read `~/.claude/skills/interface-review/SKILL.md` and follow it on that diff, loading the domain skills it names from diff --git a/dot_claude/skills/accessibility/SKILL.md b/dot_claude/skills/accessibility/SKILL.md index 17b93b4..719e34e 100644 --- a/dot_claude/skills/accessibility/SKILL.md +++ b/dot_claude/skills/accessibility/SKILL.md @@ -11,7 +11,7 @@ Reviewing means two walks. Keyboard-only, where every flow completes without a m Contrast measurement and color fixes belong to `colors`; where `colors` is absent, compute the declared pair's ratio against the table below and mark pairs over a rendered background `Not verified`. Text sizing, iOS input zoom and language metadata belong to `typography`. Spacing between targets and spatial RTL belong to `layout`. Label, error and alt-text wording belong to `writing`. Animation recipes, hover styling and scroll containment belong to `ui`. -A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. +A decision of this repository (resolved with `aval resolve `, which answers at the repository's declared `in_scopes`, decisions ADR-0046; no hand-typed `--scope`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. ## Criteria, not conventions diff --git a/dot_claude/skills/interface-review/SKILL.md b/dot_claude/skills/interface-review/SKILL.md index cdefe07..06c95da 100644 --- a/dot_claude/skills/interface-review/SKILL.md +++ b/dot_claude/skills/interface-review/SKILL.md @@ -12,7 +12,7 @@ It owns the scope, the classification and the change-scoped report. Domain rules Correctness, tests, security and performance belong to the project's general code review. Name such a concern once, point at that review and drop it. -A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. +A decision of this repository (resolved with `aval resolve `, which answers at the repository's declared `in_scopes`, decisions ADR-0046; no hand-typed `--scope`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. ## The change, not the codebase diff --git a/dot_claude/skills/interface/SKILL.md b/dot_claude/skills/interface/SKILL.md index 009685d..314d3b3 100644 --- a/dot_claude/skills/interface/SKILL.md +++ b/dot_claude/skills/interface/SKILL.md @@ -11,7 +11,7 @@ Orchestration is all it owns. Accessibility rules belong to `accessibility`, str Change-scoped review of uncommitted work, branches and pull requests belongs to `interface-review`. -A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. +A decision of this repository (resolved with `aval resolve `, which answers at the repository's declared `in_scopes`, decisions ADR-0046; no hand-typed `--scope`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. ## Evidence, not taste diff --git a/dot_claude/skills/layout/SKILL.md b/dot_claude/skills/layout/SKILL.md index 1648286..0ba9d30 100644 --- a/dot_claude/skills/layout/SKILL.md +++ b/dot_claude/skills/layout/SKILL.md @@ -11,7 +11,7 @@ Write every fix in the project's styling system. The numbers below apply only wh Hit areas and focus behavior belong to `accessibility`. Radius, shadows and animation belong to `ui`. Line length, text spacing and truncation mechanics belong to `typography`. The words themselves belong to `writing`. -A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. +A decision of this repository (resolved with `aval resolve `, which answers at the repository's declared `in_scopes`, decisions ADR-0046; no hand-typed `--scope`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. ## Group with space, not lines diff --git a/dot_claude/skills/worktree-task/SKILL.md b/dot_claude/skills/worktree-task/SKILL.md index 22a6f13..92e2100 100644 --- a/dot_claude/skills/worktree-task/SKILL.md +++ b/dot_claude/skills/worktree-task/SKILL.md @@ -206,7 +206,7 @@ below names one of them. against `git diff --name-only ..HEAD`; no match, no step. Build one brief for the `interface-review` agent: the base sha, the scope block, the `aval traits` output, the `aval resolve` output for the ui - and design-system keys at the diff's scope (with the exemption list of + and design-system keys, which `aval resolve ` answers at the repository's declared `in_scopes` (decisions ADR-0046) (with the exemption list of `design-system.every-measure-is-a-token`), the full diff (no 60 KB cut) and the removed lines of `git diff -U0 ..HEAD`. Launch it in the same message as step 3's `implementation-review` launch, so the diff --git a/dot_claude/skills/writing/SKILL.md b/dot_claude/skills/writing/SKILL.md index e800973..d66960b 100644 --- a/dot_claude/skills/writing/SKILL.md +++ b/dot_claude/skills/writing/SKILL.md @@ -11,7 +11,7 @@ A deliberate brand voice is not a defect. Raise a departure from plain language How copy renders, including `text-transform`, truncation and smart punctuation, belongs to `typography`. Error markup, announcements and the attributes that carry accessible names belong to `accessibility`. Room for translated strings belongs to `layout`. -A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. +A decision of this repository (resolved with `aval resolve `, which answers at the repository's declared `in_scopes`, decisions ADR-0046; no hand-typed `--scope`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal. ## Inventory the existing strings first From 806f98096f148466d8599302fed4e7827712fd0a Mon Sep 17 00:00:00 2001 From: fredericrous Date: Tue, 27 Oct 2026 18:44:29 +0100 Subject: [PATCH 2/2] docs(skills): rewrap the in_scopes sentence Co-Authored-By: Claude Opus 5.5 --- dot_claude/agents/interface-review.md | 5 +++-- dot_claude/skills/worktree-task/SKILL.md | 6 ++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/dot_claude/agents/interface-review.md b/dot_claude/agents/interface-review.md index 5881d5c..28454c5 100644 --- a/dot_claude/agents/interface-review.md +++ b/dot_claude/agents/interface-review.md @@ -12,8 +12,9 @@ anything, and never approve on the author's behalf. Your prompt carries the brief the session built: the base sha, the scope block, the `aval traits` output, the `aval resolve` output for the ui and -design-system keys, which `aval resolve ` answers at the repository's declared `in_scopes` (decisions ADR-0046) (with the exemption list of -`design-system.every-measure-is-a-token`), the full diff and the removed +design-system keys (it answers at the repository's declared `in_scopes`, +decisions ADR-0046; no hand-typed `--scope`), with the exemption list of +`design-system.every-measure-is-a-token`, the full diff and the removed lines of `git diff -U0`. Read `~/.claude/skills/interface-review/SKILL.md` and follow it on that diff, loading the domain skills it names from `~/.claude/skills//`, the repository's `.claude/skills//` or diff --git a/dot_claude/skills/worktree-task/SKILL.md b/dot_claude/skills/worktree-task/SKILL.md index 92e2100..08ef8bd 100644 --- a/dot_claude/skills/worktree-task/SKILL.md +++ b/dot_claude/skills/worktree-task/SKILL.md @@ -206,8 +206,10 @@ below names one of them. against `git diff --name-only ..HEAD`; no match, no step. Build one brief for the `interface-review` agent: the base sha, the scope block, the `aval traits` output, the `aval resolve` output for the ui - and design-system keys, which `aval resolve ` answers at the repository's declared `in_scopes` (decisions ADR-0046) (with the exemption list of - `design-system.every-measure-is-a-token`), the full diff (no 60 KB cut) + and design-system keys (it answers at the repository's declared + `in_scopes`, decisions ADR-0046; no hand-typed `--scope`), with the + exemption list of `design-system.every-measure-is-a-token`, the full + diff (no 60 KB cut) and the removed lines of `git diff -U0 ..HEAD`. Launch it in the same message as step 3's `implementation-review` launch, so the two run in parallel. Findings are advisory: