From 07205a712c1981bc2c10221b04b6e44c5fd48b25 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 22:39:37 +0200 Subject: [PATCH 1/6] docs(framework): add dominance checks to review and rules Dominance issues were easy for agents to miss when a weaker rule, criterion, or documentation statement was already covered, overridden, or invalidated by a stronger element. This adds the check at the global context, rule-generation, reviewer, and review-template levels. --- CLAUDE.md | 2 ++ .../skills/02-project-memory/assets/AGENTS.md | 2 ++ .../skills/05-rule-generate/actions/02-write-rule.md | 10 ++++++---- .../skills/05-rule-generate/actions/03-validate.md | 2 ++ .../skills/05-rule-generate/assets/rule-template.md | 2 +- .../05-rule-generate/references/rule-authoring.md | 11 +++++++++++ plugins/aidd-dev/agents/reviewer.md | 8 ++++++++ .../skills/05-review/actions/01-review-code.md | 11 ++++++----- .../skills/05-review/actions/02-review-functional.md | 8 +++++--- .../skills/05-review/assets/review-code-template.md | 2 +- .../05-review/assets/review-functional-template.md | 6 ++++++ 11 files changed, 50 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bf7514c5..5e7272e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,6 +18,8 @@ All instructions and information above are willing to be up to date, but always - Do not commit or push yourself unless I ask you to. - For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. - Never duplicate across docs - link to the canonical home. +- Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. +- Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. ### Answering Guidelines diff --git a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md index da9aad46..4ff61e14 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md @@ -21,6 +21,8 @@ - Do not commit or push unless the user asks. - Do not assume your knowledge is current. Be sure of an answer before giving it. +- Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. +- Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. ## Memory Management diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md index 59e78f43..689f3b5c 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md @@ -13,14 +13,16 @@ One rule file per supported confirmed tool, the list of files written, and any s ## Process 1. **Build.** Copy `@../assets/rule-template.md` into one canonical rule, concise. Strip the scaffold (comments + `<...>`). -2. **Frontmatter.** Set the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field a tool does not support. -3. **Render.** Per the write mode (`@../references/tool-paths.md`): +2. **Dominance.** Compare each normative bullet against existing rules, docs, criteria, and context. Delete, merge, or scope bullets already covered, overridden, contradicted, or invalidated by another element. Keep repetition only when clearly marked as an example, migration note, or historical context. +3. **Frontmatter.** Set the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field a tool does not support. +4. **Render.** Per the write mode (`@../references/tool-paths.md`): - **Host**: for each supported confirmed tool, write to its path and extension. Skip an unsupported tool, carrying its reason forward. - **Plugin source**: write one canonical `.md` rule. No per-tool fan-out. -4. **Split.** When examples warrant it, write several rule files rather than one crowded one. -5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +5. **Split.** When examples warrant it, write several rule files rather than one crowded one. +6. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). ## Test - Each rule file exists at its tool's rules path under the chosen scope. - The scope frontmatter matches the rule's reach, per `@../references/tool-paths.md`. +- No normative bullet is already covered, overridden, contradicted, or invalidated by another active element. diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index 26427308..e3e9d93f 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -15,7 +15,9 @@ A short pass or fail line per rule file. 1. **Exists.** Confirm each file is on disk at its expected path. 2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. 3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. +4. **Dominance.** Confirm every normative bullet changes the compliance boundary. If deleting a bullet would not make any previously forbidden behavior allowed, flag it as subsumed. If a bullet overrides or invalidates another element, require explicit scope, priority, exception, or historical status. ## Test - Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. +- No normative bullet is merely implied by, overridden by, or invalidated by another active element. diff --git a/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md b/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md index 3a565469..86a9163a 100644 --- a/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md +++ b/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md @@ -9,4 +9,4 @@ - - - + diff --git a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md index 9867cadf..0d112f47 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md @@ -8,6 +8,17 @@ The contract every generated rule must satisfy. A rule governs editor and agent - **R2.** Bullets only, no prose. One ultra-short rule per bullet (3-7 words). Less is more. - **R3.** Scope every rule to the files it applies to, or mark it as applying to all. - **R4.** English only, regardless of conversation language. +- **R5.** Every normative bullet must change the compliance boundary. Delete, merge, or scope bullets already covered, overridden, contradicted, or invalidated by another element. + +## Dominance check + +Run this check before keeping a rule bullet. + +| Case | What to detect | Action | +| --- | --- | --- | +| Subsumption | A stronger rule already implies a weaker one. | Delete the weaker rule, or convert it into an example under the stronger one. | +| Override | A specific rule changes a general one. | Rewrite with explicit scope, priority, and exception. | +| Invalidation | One rule makes another obsolete, impossible, or false. | Remove the invalid rule, or mark it historical with a current replacement. | ## File naming diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 6724f012..2a13aa89 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -59,6 +59,14 @@ Your output is complete when: - Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. - For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. - Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). +- Run a dominance check on instructions, criteria, findings, documentation statements, and code rules. If one element covers, overrides, contradicts, or makes another impossible, report a finding unless the weaker element is clearly marked as an example, migration note, or historical context. + +| Case | What to detect | Example | Action | +| --- | --- | --- | --- | +| Subsumption | A stronger element already implies a weaker one. | "All fixtures must be TypeScript" plus "Do not add legacy fixture formats." | Delete the weaker element, or convert it into an example under the stronger one. | +| Override | A specific element changes a general one. | "All docs are English" plus "Onboarding examples may stay French." | Rewrite with explicit scope, priority, and exception. | +| Invalidation | One element makes another obsolete, impossible, or false. | A doc explains an active command that another doc says was removed. | Remove the invalid element, or mark it historical with a current replacement. | + - For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. - For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. - Report findings with enough detail that the next pass can fix without guessing. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 63978f69..c1811895 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -24,11 +24,12 @@ severity_breakdown: 1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. 2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. -3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -6. **Write to disk** at `aidd_docs/tasks//-.review.md`. Create the month directory when missing. +3. **Dominance.** For changed instructions, criteria, findings, docs, and code rules, flag elements that are subsumed, overridden without scope, or invalidated by another active element. Use category `dominance`. +4. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). +5. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. +6. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. +7. **Write to disk** at `aidd_docs/tasks//-.review.md`. Create the month directory when missing. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; dominance issues use category `dominance`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 8e3c9b9d..8aca5d84 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -26,6 +26,7 @@ Check against: - Inconsistencies - Duplications +- Dominance issues (subsumption, override, invalidation) - Non logical Flows or Steps @@ -37,9 +38,10 @@ Check against: 4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. 5. **List missing behaviors** (criteria with no trace in the diff). 6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List flow and edge-case gaps** surfaced by walking through each criterion. -8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//-.review_functional.md`. Create the month directory when missing. +7. **List dominance issues** where a criterion, behavior, or doc statement is subsumed, overridden without scope, or invalidated by another active element. +8. **List flow and edge-case gaps** surfaced by walking through each criterion. +9. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//-.review_functional.md`. Create the month directory when missing. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, `Dominance issues`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md index 2fbff291..b91e2767 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md @@ -27,7 +27,7 @@ What the diff was meant to deliver (from the ticket or plan). Tick what the diff One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. +Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`, `dominance`. | Sev | Category | Location | Issue | Suggested fix | | --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md index 9de9d828..af00c38c 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md @@ -39,6 +39,12 @@ Changes present in the diff but traced to no acceptance criterion. - [ ] {{unplanned change - confirm scope with author}} +## Dominance issues + +Criteria, behaviors, or doc statements subsumed, overridden without scope, or invalidated by another active element. + +- [ ] {{dominance issue - merge, delete, or scope explicitly}} + ## Flow / edge-case gaps Gaps surfaced while walking each criterion against the diff. From 93c71ddc1a7bfdd2b30282cd07a9d47d88708dcd Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 22:54:54 +0200 Subject: [PATCH 2/6] docs(framework): reduce dominance check duplication Keep the concise dominance rule in global and rule-authoring surfaces while leaving the detailed case breakdown to the reviewer. Validation now states the shared check without reimplementing reviewer classification. --- .../05-rule-generate/actions/02-write-rule.md | 10 ++++------ .../skills/05-rule-generate/actions/03-validate.md | 4 ++-- .../skills/05-rule-generate/assets/rule-template.md | 2 +- .../05-rule-generate/references/rule-authoring.md | 13 ++----------- .../skills/05-review/actions/01-review-code.md | 11 +++++------ .../05-review/actions/02-review-functional.md | 8 +++----- .../skills/05-review/assets/review-code-template.md | 2 +- .../05-review/assets/review-functional-template.md | 6 ------ 8 files changed, 18 insertions(+), 38 deletions(-) diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md index 689f3b5c..59e78f43 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md @@ -13,16 +13,14 @@ One rule file per supported confirmed tool, the list of files written, and any s ## Process 1. **Build.** Copy `@../assets/rule-template.md` into one canonical rule, concise. Strip the scaffold (comments + `<...>`). -2. **Dominance.** Compare each normative bullet against existing rules, docs, criteria, and context. Delete, merge, or scope bullets already covered, overridden, contradicted, or invalidated by another element. Keep repetition only when clearly marked as an example, migration note, or historical context. -3. **Frontmatter.** Set the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field a tool does not support. -4. **Render.** Per the write mode (`@../references/tool-paths.md`): +2. **Frontmatter.** Set the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field a tool does not support. +3. **Render.** Per the write mode (`@../references/tool-paths.md`): - **Host**: for each supported confirmed tool, write to its path and extension. Skip an unsupported tool, carrying its reason forward. - **Plugin source**: write one canonical `.md` rule. No per-tool fan-out. -5. **Split.** When examples warrant it, write several rule files rather than one crowded one. -6. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +4. **Split.** When examples warrant it, write several rule files rather than one crowded one. +5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). ## Test - Each rule file exists at its tool's rules path under the chosen scope. - The scope frontmatter matches the rule's reach, per `@../references/tool-paths.md`. -- No normative bullet is already covered, overridden, contradicted, or invalidated by another active element. diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index e3e9d93f..48c5da14 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -15,9 +15,9 @@ A short pass or fail line per rule file. 1. **Exists.** Confirm each file is on disk at its expected path. 2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. 3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. -4. **Dominance.** Confirm every normative bullet changes the compliance boundary. If deleting a bullet would not make any previously forbidden behavior allowed, flag it as subsumed. If a bullet overrides or invalidates another element, require explicit scope, priority, exception, or historical status. +4. **Dominance.** Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. ## Test - Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. -- No normative bullet is merely implied by, overridden by, or invalidated by another active element. +- The dominance check is stated. diff --git a/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md b/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md index 86a9163a..3a565469 100644 --- a/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md +++ b/plugins/aidd-context/skills/05-rule-generate/assets/rule-template.md @@ -9,4 +9,4 @@ - - - + diff --git a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md index 0d112f47..c5a478fd 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md @@ -8,17 +8,8 @@ The contract every generated rule must satisfy. A rule governs editor and agent - **R2.** Bullets only, no prose. One ultra-short rule per bullet (3-7 words). Less is more. - **R3.** Scope every rule to the files it applies to, or mark it as applying to all. - **R4.** English only, regardless of conversation language. -- **R5.** Every normative bullet must change the compliance boundary. Delete, merge, or scope bullets already covered, overridden, contradicted, or invalidated by another element. - -## Dominance check - -Run this check before keeping a rule bullet. - -| Case | What to detect | Action | -| --- | --- | --- | -| Subsumption | A stronger rule already implies a weaker one. | Delete the weaker rule, or convert it into an example under the stronger one. | -| Override | A specific rule changes a general one. | Rewrite with explicit scope, priority, and exception. | -| Invalidation | One rule makes another obsolete, impossible, or false. | Remove the invalid rule, or mark it historical with a current replacement. | +- **R5.** Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. +- **R6.** Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. ## File naming diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index c1811895..63978f69 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -24,12 +24,11 @@ severity_breakdown: 1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. 2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. -3. **Dominance.** For changed instructions, criteria, findings, docs, and code rules, flag elements that are subsumed, overridden without scope, or invalidated by another active element. Use category `dominance`. -4. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -5. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -6. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -7. **Write to disk** at `aidd_docs/tasks//-.review.md`. Create the month directory when missing. +3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). +4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. +5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. +6. **Write to disk** at `aidd_docs/tasks//-.review.md`. Create the month directory when missing. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; dominance issues use category `dominance`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 8aca5d84..8e3c9b9d 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -26,7 +26,6 @@ Check against: - Inconsistencies - Duplications -- Dominance issues (subsumption, override, invalidation) - Non logical Flows or Steps @@ -38,10 +37,9 @@ Check against: 4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. 5. **List missing behaviors** (criteria with no trace in the diff). 6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List dominance issues** where a criterion, behavior, or doc statement is subsumed, overridden without scope, or invalidated by another active element. -8. **List flow and edge-case gaps** surfaced by walking through each criterion. -9. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//-.review_functional.md`. Create the month directory when missing. +7. **List flow and edge-case gaps** surfaced by walking through each criterion. +8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//-.review_functional.md`. Create the month directory when missing. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, `Dominance issues`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md index b91e2767..2fbff291 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md @@ -27,7 +27,7 @@ What the diff was meant to deliver (from the ticket or plan). Tick what the diff One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`, `dominance`. +Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. | Sev | Category | Location | Issue | Suggested fix | | --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md index af00c38c..9de9d828 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md @@ -39,12 +39,6 @@ Changes present in the diff but traced to no acceptance criterion. - [ ] {{unplanned change - confirm scope with author}} -## Dominance issues - -Criteria, behaviors, or doc statements subsumed, overridden without scope, or invalidated by another active element. - -- [ ] {{dominance issue - merge, delete, or scope explicitly}} - ## Flow / edge-case gaps Gaps surfaced while walking each criterion against the diff. From 11229fe161ccbd59ef2ccf606b19ff05ba3a6e4f Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 09:53:03 +0200 Subject: [PATCH 3/6] docs(framework): separate global and rule dominance checks Keep the general dominance reminder and reviewer taxonomy separate from rule-generation specifics. Rule authoring and validation now only check for duplicate, weaker, or contradictory rule bullets. --- CLAUDE.md | 3 +-- .../aidd-context/skills/02-project-memory/assets/AGENTS.md | 3 +-- .../skills/05-rule-generate/actions/03-validate.md | 4 ++-- .../skills/05-rule-generate/references/rule-authoring.md | 3 +-- plugins/aidd-dev/agents/reviewer.md | 2 +- 5 files changed, 6 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5e7272e1..56d0445a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,8 +18,7 @@ All instructions and information above are willing to be up to date, but always - Do not commit or push yourself unless I ask you to. - For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. - Never duplicate across docs - link to the canonical home. -- Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. -- Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. +- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. ### Answering Guidelines diff --git a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md index 4ff61e14..26d92ea1 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md @@ -21,8 +21,7 @@ - Do not commit or push unless the user asks. - Do not assume your knowledge is current. Be sure of an answer before giving it. -- Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. -- Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. +- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. ## Memory Management diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index 48c5da14..d81c38c0 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -15,9 +15,9 @@ A short pass or fail line per rule file. 1. **Exists.** Confirm each file is on disk at its expected path. 2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. 3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. -4. **Dominance.** Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. +4. **Rule bullets.** Confirm no bullet repeats, weakens, or contradicts another active bullet in the same rule. ## Test - Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. -- The dominance check is stated. +- No generated rule contains duplicate, weaker, or contradictory bullets. diff --git a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md index c5a478fd..5d40573b 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md @@ -8,8 +8,7 @@ The contract every generated rule must satisfy. A rule governs editor and agent - **R2.** Bullets only, no prose. One ultra-short rule per bullet (3-7 words). Less is more. - **R3.** Scope every rule to the files it applies to, or mark it as applying to all. - **R4.** English only, regardless of conversation language. -- **R5.** Run a dominance check before adding instructions, criteria, findings, docs, or code rules: if one element covers, overrides, contradicts, or invalidates another, delete, merge, or rewrite with explicit scope, priority, and exceptions. -- **R6.** Keep weaker repetition only when it is clearly marked as an example, migration note, or historical context. +- **R5.** Do not add a rule bullet that repeats, weakens, or contradicts another active bullet in the same rule. ## File naming diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 2a13aa89..e32b0daf 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -59,7 +59,7 @@ Your output is complete when: - Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. - For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. - Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- Run a dominance check on instructions, criteria, findings, documentation statements, and code rules. If one element covers, overrides, contradicts, or makes another impossible, report a finding unless the weaker element is clearly marked as an example, migration note, or historical context. +- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. | Case | What to detect | Example | Action | | --- | --- | --- | --- | From 4a73fd2fac37f25998333239e10b7141b8473819 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 09:59:53 +0200 Subject: [PATCH 4/6] docs(framework): prefer intention-revealing names Naming guidance belongs in the global project context because it applies across artifacts. This keeps the rule concise and avoids duplicating it in domain-specific rule generation flows. --- CLAUDE.md | 1 + plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md | 1 + 2 files changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 56d0445a..386af27b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,7 @@ All instructions and information above are willing to be up to date, but always - For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. - Never duplicate across docs - link to the canonical home. - Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. +- When naming anything, prefer intention-revealing names over technical ones: describe the goal or responsibility, not the mechanism, tool, or file format. ### Answering Guidelines diff --git a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md index 26d92ea1..20b5e034 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md @@ -22,6 +22,7 @@ - Do not commit or push unless the user asks. - Do not assume your knowledge is current. Be sure of an answer before giving it. - Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. +- When naming anything, prefer intention-revealing names over technical ones: describe the goal or responsibility, not the mechanism, tool, or file format. ## Memory Management From 4b2727fbfb862e5958447e61535fb8d42a51745e Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 10:27:51 +0200 Subject: [PATCH 5/6] docs(aidd-context): validate rules against shared contracts Rule validation should apply the rule-authoring and tool-path contracts instead of restating individual rule checks. The test now has a single outcome sentence rather than multiple bullet assertions. --- .../skills/05-rule-generate/actions/03-validate.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index d81c38c0..7e4f3495 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -13,11 +13,10 @@ A short pass or fail line per rule file. ## Process 1. **Exists.** Confirm each file is on disk at its expected path. -2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. -3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. -4. **Rule bullets.** Confirm no bullet repeats, weakens, or contradicts another active bullet in the same rule. +2. **Contract.** Validate the file against `@../references/rule-authoring.md`. +3. **Target.** Validate target path and frontmatter against `@../references/tool-paths.md`. +4. **Report.** Emit one pass/fail line per file. ## Test -- Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. -- No generated rule contains duplicate, weaker, or contradictory bullets. +Every written rule file has one pass/fail result against both referenced contracts. From 639fdd50941a9131ed20fb85016057d5e75f90e9 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 10:48:39 +0200 Subject: [PATCH 6/6] docs(aidd-dev): align dominance wording with review role The reviewer should report parallel elements rather than describe adding behavior. This keeps the dominance check phrased for read-only review while preserving the same taxonomy. --- plugins/aidd-dev/agents/reviewer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index e32b0daf..6abcc8ea 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -59,7 +59,7 @@ Your output is complete when: - Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. - For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. - Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. +- When reviewing any added instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, report the parallel element and suggest deleting it, merging it into the stronger element, or rewriting the set with explicit scope, priority, and exception. | Case | What to detect | Example | Action | | --- | --- | --- | --- |