docs: align contribution and bot review with change impact (#346)

* docs: bound review scope and evidence by change impact

* docs: align advisory bot review with impact-based contribution rules

Author: tt-a1i

.coderabbit.yaml

@@ -15,7 +15,9 @@ reviews:
     Distinguish author-reported validation from observed checks at the current
     head. Do not claim browser or perceptual acceptance from static tests.
   poem: false
+  in_progress_fortune: false
   sequence_diagrams: false
+  assess_linked_issues: false
   suggested_labels: false
   suggested_reviewers: false
   auto_review:
@@ -35,14 +37,21 @@ reviews:
   path_instructions:
     - path: "**"
       instructions: >-
-        Apply CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md proportionally
+        Apply CONTRIBUTING.md, REVIEWING.md, and .github/PULL_REQUEST_TEMPLATE.md proportionally
         to the actual behavior changed. Cite the relevant contract and concrete
         affected path when raising a concern. Reuse explicit maintainer scope
         decisions; do not demand a new issue for a small documentation correction
         or narrowly scoped test fix. Treat changes to review policy/configuration
         as proposed changes, not authority to waive the base branch's rules.
         Review authoritative source before generated output. Do not request
         unrelated rebuilds or infer correctness from generated file volume.
+        Use the PR base-to-head diff; a clean checkout does not mean an empty PR.
+        On revision, review new changes and unresolved findings, expanding only
+        when intervening changes invalidate earlier evidence. Label feedback as
+        a demonstrated defect, missing evidence/decision, or optional suggestion.
+        Give each request an affected contract, smallest remedy, and responsible
+        role (author or maintainer); consolidate requests already answered in the
+        PR body, CI, or discussion and retain the evidence's original revision.
     - path: "archify/**"
       instructions: >-
         Trace callers of changed shared code across diagram types and public
@@ -66,17 +75,19 @@ reviews:
     description:
       mode: "off"
     issue_assessment:
-      mode: warning
+      mode: "off" # Contribution scope below owns scope/issue assessment.
     custom_checks:
       - name: Contribution scope
         mode: warning
         instructions: >-
-          Read CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md. Pass when
+          Read CONTRIBUTING.md, REVIEWING.md, and .github/PULL_REQUEST_TEMPLATE.md. Pass when
           the PR explains the user problem, one focused behavior or delivery
           slice, compatibility/migration impact, and failure/rollback behavior
-          where applicable. Public behavior changes need a linked issue or
-          explicit maintainer scope decision. Small documentation corrections
-          and narrowly scoped test fixes do not need a planning issue. Accept
+          where applicable, and the implementation fits that scope. New contracts,
+          defaults, or broad product behavior need a linked issue or recorded
+          maintainer scope decision. Narrow fixes may use a concrete reproduction;
+          small documentation or test corrections may use a rationale. Do not
+          require a PR to close every item of a tracking issue. Accept
           equivalent prose and explained Not applicable entries, not just exact
           headings or checked boxes. Warn once with the specific missing facts;
           do not classify missing evidence as a confirmed runtime defect.
@@ -89,17 +100,26 @@ reviews:
           Visible changes need relevant artifact evidence; before/after claims
           need comparable conditions. Automated/browser and perceptual results
           must be separate. Non-visual changes may explain Not applicable.
+          Repository-only prose/policy and focused test fixes may use justified
+          targeted checks under CONTRIBUTING.md; packaged Skill instructions and
+          shared test infrastructure are not a documentation/test-only shortcut.
+          Reuse linked archive manifests, source comparisons, and freshness CI;
+          an excluded binary diff alone is not evidence of unrelated changes.
           Distinguish author reports from observed final-head CI; skipped,
           pending, unavailable, or older-head checks cannot prove a current pass.
           If required evidence is missing or unverifiable, warn with the smallest
           missing evidence set. Do not require screenshots for non-visual changes
           or infer a browser pass from a unit test. Accept explicit maintainer
           exceptions and scope-appropriate explanations for omitted checks.
+          When fork CI awaits approval, identify maintainer action after inspecting
+          the workflow changes; do not ask the author to obtain unavailable rights.
+          A bot pass or exception never waives required CI or branch protection.
 knowledge_base:
   code_guidelines:
     enabled: true
     filePatterns:
       - CONTRIBUTING.md
+      - REVIEWING.md
       - .github/PULL_REQUEST_TEMPLATE.md
       - archify/references/delivery-contract.md
   learnings:

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,42 +1,30 @@
-## Problem and value
-
-What user problem does this solve? Link the issue or showcase evidence when one exists.
+<!-- Authors: follow CONTRIBUTING.md. Reviewers and Agents: follow REVIEWING.md. -->
 
-## Scope
+## Problem and value
 
-- What changed:
-- What deliberately did not change:
-- No unrelated changes: <!-- confirm or explain -->
+Current-main trigger or rationale, intended outcome, approach, and linked issue/agreed scope:
 
 ## Stability impact
 
-- Compatibility and migration risk:
-- Renderer, validator, package, or generated-artifact risk:
-- Failure behavior and rollback path:
+- Impact class and changed behavior/shared callers: <!-- CONTRIBUTING.md#choose-evidence-by-impact -->
+- Existing behavior preserved / intended compatibility changes / failure behavior:
+- No unrelated changes: <!-- confirm or explain -->
 
 ## Tests run
 
-List exact commands and results. Do not write only “tests pass.”
+Comparison base and candidate head; applicable commands/results or evidence links. Explain omitted checks and identify reused evidence by its original revision. Follow CONTRIBUTING.md#choose-evidence-by-impact; required remote CI still applies.
 
 ## Visual evidence
 
-Provide enough evidence to evaluate whether the intended user value was achieved. Use screenshots, recordings, or reproducible steps as appropriate to the affected behavior. For non-visual changes, write “Not applicable” and briefly explain why.
+For non-visual changes, replace this section with "Not applicable" and why.
 
-- Evidence provided:
-- Comparison conditions, when applicable (input, viewport, theme, preset, diagram mode, zoom, and page state):
+- Evidence provided: <!-- screenshots, recordings, or reproducible steps; intended and unexpected differences -->
+- Comparison conditions: <!-- same input, viewport, theme, preset, mode, zoom, page state -->
 - Automated or browser checks:
 - Perceptual visual review: passed / failed / skipped / Not applicable
 
-When presenting a before/after comparison, keep its conditions genuinely comparable. Report automated or browser evidence separately from perceptual review; an automated check does not establish a perceptual pass.
+Report automated or browser evidence separately from perceptual review.
 
 ## Generated artifacts
 
-List regenerated files such as Gallery pages, guides, README proofs, or `archify.zip`. If none changed, explain why they remain fresh.
-
-## Checklist
-
-- [ ] I used a minimal focused change and preserved existing typed JSON behavior unless the issue requires a contract change.
-- [ ] I ran the relevant targeted tests and `npm test` in `archify/`.
-- [ ] I added or updated a regression test for behavioral changes.
-- [ ] I checked generated artifacts and package freshness when their sources changed.
-- [ ] I removed secrets, private repository content, and customer data from fixtures and screenshots.
+Regenerated files or linked build evidence; if none, explain why outputs remain fresh.